@hasna/loops 0.4.26 → 0.4.28

package/dist/cli/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.26",
+  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",
@@ -6802,11 +6882,30 @@ function remoteWorktreePrepareLines(worktree) {
     '  git -C "$repo" rev-parse --is-inside-work-tree >/dev/null 2>&1 || { echo "worktree repoRoot is not a git repository: $repo" >&2; return 1; }',
     '  mkdir -p "$(dirname "$path")" || return 1',
     "  # Preparation chatter goes to stderr so run stdout stays the agent's.",
-    '  if git -C "$repo" show-ref --verify --quiet "refs/heads/$branch"; then',
-    '    git -C "$repo" worktree add "$path" "$branch" 1>&2 || return 1',
-    "  else",
-    '    git -C "$repo" worktree add -b "$branch" "$path" HEAD 1>&2 || return 1',
+    "  __openloops_worktree_add() {",
+    '    if git -C "$repo" show-ref --verify --quiet "refs/heads/$branch"; then',
+    '      git -C "$repo" worktree add "$path" "$branch"',
+    "    else",
+    '      git -C "$repo" worktree add -b "$branch" "$path" HEAD',
+    "    fi",
+    "  }",
+    "  local __ol_add_out",
+    '  if __ol_add_out="$(__openloops_worktree_add 2>&1)"; then',
+    '    if [ -n "$__ol_add_out" ]; then printf "%s\\n" "$__ol_add_out" >&2; fi',
+    "    return 0",
     "  fi",
+    '  printf "%s\\n" "$__ol_add_out" >&2',
+    "  # Self-heal git's own remedy for a stale 'missing but already registered",
+    "  # worktree': prune the dead registration (metadata-only; the directory is",
+    "  # already gone) and retry the add exactly once, then fail honestly.",
+    '  case "$__ol_add_out" in',
+    '    *"missing but already registered worktree"*)',
+    '      git -C "$repo" worktree prune 1>&2 || true',
+    "      __openloops_worktree_add 1>&2 || return 1",
+    "      return 0",
+    "      ;;",
+    "  esac",
+    "  return 1",
     "}"
   ];
 }
@@ -6946,6 +7045,9 @@ async function preflightNativeAuthProfile(spec, env) {
 function spawnDetail(result) {
   return (result.stderr || result.stdout || result.error || "").toString().trim();
 }
+function isStaleWorktreeRegistration(detail) {
+  return typeof detail === "string" && /missing but already registered worktree/i.test(detail);
+}
 function resolvedDirEquals(left, right) {
   try {
     return realpathSync(left) === realpathSync(right);
@@ -7047,7 +7149,12 @@ async function ensureLocalWorktree(worktree, env) {
     return { error: `could not create worktree parent directory: ${error instanceof Error ? error.message : String(error)}` };
   }
   const hasBranch = await git(["-C", repoRoot, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`]);
-  const add = hasBranch.status === 0 ? await git(["-C", repoRoot, "worktree", "add", path, branch]) : await git(["-C", repoRoot, "worktree", "add", "-b", branch, path, "HEAD"]);
+  const runAdd = () => hasBranch.status === 0 ? git(["-C", repoRoot, "worktree", "add", path, branch]) : git(["-C", repoRoot, "worktree", "add", "-b", branch, path, "HEAD"]);
+  let add = await runAdd();
+  if ((add.error || (add.status ?? 1) !== 0) && isStaleWorktreeRegistration(spawnDetail(add))) {
+    await git(["-C", repoRoot, "worktree", "prune"]);
+    add = await runAdd();
+  }
   if (add.error || (add.status ?? 1) !== 0) {
     const detail = spawnDetail(add);
     return { error: `git worktree add failed for ${path}${detail ? `: ${detail}` : ""}` };
@@ -10634,6 +10741,7 @@ function timeOnly(value) {
 import { createHash as createHash4 } from "crypto";
 import { hostname as hostname4 } from "os";
 var LOOPS_MIGRATION_SCHEMA = "open-loops.migration/v1";
+var LOOPS_SELF_HOSTED_PUSH_MANIFEST_SCHEMA = "open-loops.self-hosted-push-manifest/v1";
 function canonicalize(value) {
   if (Array.isArray(value))
     return value.map((entry) => canonicalize(entry));
@@ -10794,6 +10902,20 @@ function compareResource(current, incoming, opts) {
     currentHash
   };
 }
+function remoteRepresentationRow(current, incoming, opts) {
+  const incomingHash = migrationHash(incoming);
+  if (!current)
+    return { resource: opts.resource, id: opts.id, name: opts.name, action: "insert", incomingHash };
+  return {
+    resource: opts.resource,
+    id: opts.id,
+    name: opts.name,
+    action: "skip",
+    reason: "remote id is represented; self-hosted list payload is public/redacted, so exact byte comparison is reserved for import apply",
+    incomingHash,
+    currentHash: migrationHash(current)
+  };
+}
 function buildImportMigrationPlan(store, bundle, opts = {}) {
   assertMigrationBundleIntegrity(bundle);
   const includeRuns = opts.includeRuns ?? true;
@@ -10985,39 +11107,184 @@ async function requestJson(fetchImpl, config, path, init = {}) {
     }
   });
   const payload = await response.json().catch(() => ({}));
-  if (!response.ok)
-    throw new Error(typeof payload.error === "string" ? payload.error : `loops-api request failed: ${response.status}`);
+  if (!response.ok) {
+    throw Object.assign(new Error(typeof payload.error === "string" ? payload.error : `loops-api request failed: ${response.status}`), { status: response.status, payload });
+  }
   return payload;
 }
+async function fetchPagedRows(fetchImpl, config, path, key, opts) {
+  const rows = [];
+  const limit = 1000;
+  for (let offset = 0;; offset += limit) {
+    try {
+      const separator = path.includes("?") ? "&" : "?";
+      const payload = await requestJson(fetchImpl, config, `${path}${separator}limit=${limit}&offset=${offset}`);
+      const page = Array.isArray(payload[key]) ? payload[key] : [];
+      rows.push(...page);
+      if (page.length < limit)
+        break;
+    } catch (error) {
+      if (error.status === 404) {
+        opts.unsupported.push(path);
+        opts.warnings.push(`self-hosted control plane does not expose ${path}; exact ${key} comparison is unavailable`);
+        break;
+      }
+      throw error;
+    }
+  }
+  return rows;
+}
+async function fetchOptionalCount(fetchImpl, config, path, opts) {
+  try {
+    const payload = await requestJson(fetchImpl, config, path);
+    return typeof payload.count === "number" ? payload.count : undefined;
+  } catch (error) {
+    if (error.status === 404) {
+      opts.unsupported.push(path);
+      opts.warnings.push(`self-hosted control plane does not expose ${path}; count comparison is unavailable`);
+      return;
+    }
+    throw error;
+  }
+}
 async function fetchRemotePreview(opts) {
   const config = resolveApiConfig(opts);
   const warnings = [];
+  const unsupported = [];
   if (!config.apiUrl) {
     warnings.push("LOOPS_API_URL or HASNA_LOOPS_API_URL is required to inspect a self-hosted control plane");
-    return { loops: [], runs: [], warnings };
+    return { workflows: [], loops: [], runs: [], counts: {}, unsupported, warnings };
   }
   if (!isLocalApiUrl(config.apiUrl) && !config.token) {
     warnings.push("non-local self-hosted APIs require LOOPS_API_TOKEN or HASNA_LOOPS_API_TOKEN");
-    return { loops: [], runs: [], warnings };
+    return { workflows: [], loops: [], runs: [], counts: {}, unsupported, warnings };
   }
   const fetchImpl = opts.fetchImpl ?? fetch;
-  const loopsPayload = await requestJson(fetchImpl, { apiUrl: config.apiUrl, token: config.token }, "/v1/loops?includeArchived=true&limit=1000");
-  const runsPayload = opts.includeRuns === false ? { runs: [] } : await requestJson(fetchImpl, { apiUrl: config.apiUrl, token: config.token }, "/v1/runs?limit=1000");
+  const api = { apiUrl: config.apiUrl, token: config.token };
+  const requestOpts = { unsupported, warnings };
+  const workflows = await fetchPagedRows(fetchImpl, api, "/v1/workflows", "workflows", requestOpts);
+  const loops = await fetchPagedRows(fetchImpl, api, "/v1/loops?includeArchived=true", "loops", requestOpts);
+  const runs = opts.includeRuns === false ? [] : await fetchPagedRows(fetchImpl, api, "/v1/runs?showOutput=true", "runs", requestOpts);
   return {
-    loops: Array.isArray(loopsPayload.loops) ? loopsPayload.loops : [],
-    runs: Array.isArray(runsPayload.runs) ? runsPayload.runs : [],
+    workflows,
+    loops,
+    runs,
+    counts: {
+      workflows: await fetchOptionalCount(fetchImpl, api, "/v1/workflows/count", requestOpts),
+      loops: await fetchOptionalCount(fetchImpl, api, "/v1/loops/count?includeArchived=true", requestOpts),
+      runs: opts.includeRuns === false ? undefined : await fetchOptionalCount(fetchImpl, api, "/v1/runs/count", requestOpts)
+    },
+    unsupported,
     warnings
   };
 }
+function disabledWorkflowForSelfHostedImport(workflow) {
+  return { ...workflow, status: "archived" };
+}
+function pausedLoopForSelfHostedImport(loop) {
+  return {
+    ...loop,
+    status: "paused",
+    nextRunAt: undefined,
+    retryScheduledFor: undefined
+  };
+}
+function selfHostedDefinitionBundle(bundle) {
+  const body = {
+    ...bundle,
+    data: {
+      workflows: bundle.data.workflows.map(disabledWorkflowForSelfHostedImport),
+      loops: bundle.data.loops.map(pausedLoopForSelfHostedImport),
+      runs: bundle.data.runs
+    }
+  };
+  const { hash: _hash, ...hashBody } = body;
+  return { ...body, hash: migrationHash(hashBody) };
+}
+function typedRows(rows) {
+  return rows.filter((row) => Boolean(row && typeof row === "object" && typeof row.id === "string"));
+}
+function rowsById(rows) {
+  return new Map(rows.map((row) => [row.id, row]));
+}
+function rowsByName(rows) {
+  return new Map(rows.filter((row) => typeof row.name === "string").map((row) => [String(row.name), row]));
+}
+function rowIds(rows, resource, action) {
+  return rows.filter((row) => row.resource === resource && row.action === action).map((row) => row.id);
+}
+function existingRowIds(rows, resource) {
+  return rows.filter((row) => row.resource === resource && (row.action === "skip" || row.action === "update")).map((row) => row.id);
+}
+function buildSelfHostedManifest(args) {
+  return {
+    schema: LOOPS_SELF_HOSTED_PUSH_MANIFEST_SCHEMA,
+    generatedAt: new Date().toISOString(),
+    apiUrl: args.apiUrl,
+    dryRun: args.dryRun,
+    replace: args.replace,
+    includeRuns: args.includeRuns,
+    safety: {
+      forcedLoopStatus: "paused",
+      clearedLoopRunPointers: true,
+      forcedWorkflowStatus: "archived",
+      resumesLoops: false
+    },
+    counts: {
+      source: args.bundle.counts,
+      remoteBefore: args.remote.counts,
+      remoteAfter: args.remoteAfter,
+      plan: args.plan.summary,
+      applied: args.applied,
+      skipped: args.skipped,
+      requests: args.requests
+    },
+    missingIds: {
+      workflows: rowIds(args.plan.rows, "workflow", "insert"),
+      loops: rowIds(args.plan.rows, "loop", "insert"),
+      runs: rowIds(args.plan.rows, "run", "insert")
+    },
+    existingIds: {
+      workflows: existingRowIds(args.plan.rows, "workflow"),
+      loops: existingRowIds(args.plan.rows, "loop"),
+      runs: existingRowIds(args.plan.rows, "run")
+    },
+    unsafe: {
+      blocked: args.plan.rows.filter((row) => row.action === "blocked"),
+      conflicts: args.plan.rows.filter((row) => row.action === "conflict"),
+      unsupported: args.remote.unsupported,
+      warnings: args.plan.warnings
+    },
+    rollback: {
+      notes: [
+        "self-hosted push imports through id-preserving upserts; no local loops are resumed or mutated",
+        "imported loops are forced to paused with nextRunAt/retryScheduledFor cleared before upload",
+        "imported workflows are forced to archived before upload",
+        "rollback is manual: archive or delete imported ids from the self-hosted control plane after reviewing this manifest"
+      ],
+      commands: [
+        "loops self-hosted push --dry-run --no-runs --manifest-file <post-rollback-check.json>"
+      ]
+    }
+  };
+}
 async function buildSelfHostedMigrationPlan(store, opts) {
-  const bundle = exportLoopsMigrationBundle(store, { includeRuns: opts.includeRuns ?? true });
+  const bundle = selfHostedDefinitionBundle(exportLoopsMigrationBundle(store, { includeRuns: opts.includeRuns ?? true }));
   const remote = await fetchRemotePreview(opts);
   const rows = [...bundle.blockers.map((row) => ({ ...row, action: "blocked" }))];
   const warnings = [
     ...bundle.warnings,
     ...remote.warnings,
-    "self-hosted remote apply is preview-only until the control plane exposes id-preserving workflow/loop/run import endpoints"
+    "self-hosted push forces imported loops to paused and imported workflows to archived until activation is explicitly approved"
   ];
+  const config = resolveApiConfig(opts);
+  const apiUrl = config.apiUrl;
+  if (!apiUrl) {
+    pushBlocker(rows, "remote", "self-hosted-api-url", "LOOPS_API_URL or HASNA_LOOPS_API_URL is required to compare a self-hosted control plane");
+  } else if (!isLocalApiUrl(apiUrl) && !config.token) {
+    pushBlocker(rows, "remote", "self-hosted-api-token", "non-local self-hosted APIs require LOOPS_API_TOKEN or HASNA_LOOPS_API_TOKEN");
+  }
+  const replace = opts.replace ?? false;
   if (opts.operation === "self-hosted-pull") {
     for (const entry of remote.loops) {
       const value = entry && typeof entry === "object" ? entry : {};
@@ -11047,58 +11314,107 @@ async function buildSelfHostedMigrationPlan(store, opts) {
       schema: LOOPS_MIGRATION_SCHEMA,
       operation: opts.operation,
       dryRun: true,
-      replace: false,
+      replace,
       importable: false,
       rows,
       warnings
     });
-    return { ...plan2, importable: false };
+    return {
+      ...plan2,
+      importable: false,
+      manifest: buildSelfHostedManifest({
+        apiUrl,
+        dryRun: true,
+        replace,
+        includeRuns: opts.includeRuns ?? true,
+        bundle,
+        remote,
+        plan: plan2
+      })
+    };
   }
-  const remoteLoopsByName = new Map(remote.loops.map((entry) => entry && typeof entry === "object" ? entry : undefined).filter((entry) => typeof entry?.name === "string").map((entry) => [String(entry.name), entry]));
+  const remoteWorkflows = typedRows(remote.workflows);
+  const remoteLoops = typedRows(remote.loops);
+  const remoteRuns = typedRows(remote.runs);
+  const remoteWorkflowsById = rowsById(remoteWorkflows);
+  const remoteLoopsById = rowsById(remoteLoops);
+  const remoteRunsById = rowsById(remoteRuns);
+  const remoteLoopsByName = rowsByName(remoteLoops);
   for (const workflow of bundle.data.workflows) {
-    rows.push({
+    if (remote.unsupported.some((entry) => entry.startsWith("/v1/workflows"))) {
+      rows.push({
+        resource: "workflow",
+        id: workflow.id,
+        name: workflow.name,
+        action: "blocked",
+        reason: "self-hosted API does not expose workflow list/count endpoints for safe comparison",
+        incomingHash: migrationHash(workflow)
+      });
+      continue;
+    }
+    rows.push(remoteRepresentationRow(remoteWorkflowsById.get(workflow.id), workflow, {
       resource: "workflow",
       id: workflow.id,
-      name: workflow.name,
-      action: "blocked",
-      reason: "self-hosted API does not expose id-preserving workflow import/list endpoints yet",
-      incomingHash: migrationHash(workflow)
-    });
+      name: workflow.name
+    }));
   }
   for (const loop of bundle.data.loops) {
-    const remoteLoop = remoteLoopsByName.get(loop.name);
-    rows.push({
-      resource: "loop",
-      id: loop.id,
-      name: loop.name,
-      action: "blocked",
-      reason: remoteLoop ? `remote loop name exists (${String(remoteLoop.id ?? "unknown id")}); exact id-preserving comparison is not available` : "normal self-hosted loop create would generate a new id; waiting for id-preserving import endpoint",
-      incomingHash: migrationHash(loop),
-      currentHash: remoteLoop ? migrationHash(remoteLoop) : undefined
-    });
+    const remoteLoop = remoteLoopsById.get(loop.id);
+    if (!remoteLoop) {
+      const nameCollision = remoteLoopsByName.get(loop.name);
+      if (nameCollision && nameCollision.id !== loop.id) {
+        rows.push({
+          resource: "loop",
+          id: loop.id,
+          name: loop.name,
+          action: "insert",
+          reason: `remote loop name exists under different id ${String(nameCollision.id ?? "unknown id")}; id-preserving import will add the missing source id paused`,
+          incomingHash: migrationHash(loop),
+          currentHash: migrationHash(nameCollision)
+        });
+        continue;
+      }
+    }
+    rows.push(remoteRepresentationRow(remoteLoop, loop, { resource: "loop", id: loop.id, name: loop.name }));
   }
   if (opts.includeRuns ?? true) {
     for (const run of bundle.data.runs) {
-      rows.push({
-        resource: "run",
-        id: run.id,
-        name: run.loopName,
-        action: "blocked",
-        reason: "self-hosted API does not expose run-history import endpoints; remote runners should create new run rows",
-        incomingHash: migrationHash(run)
-      });
+      if (run.status === "running") {
+        rows.push({
+          resource: "run",
+          id: run.id,
+          name: run.loopName,
+          action: "blocked",
+          reason: "running rows carry volatile lease/process ownership and are skipped by self-hosted import",
+          incomingHash: migrationHash(run)
+        });
+        continue;
+      }
+      rows.push(remoteRepresentationRow(remoteRunsById.get(run.id), run, { resource: "run", id: run.id, name: run.loopName }));
     }
   }
-  const plan = finalizePlan({
+  let plan = finalizePlan({
     schema: LOOPS_MIGRATION_SCHEMA,
     operation: opts.operation,
     dryRun: true,
-    replace: false,
-    importable: false,
+    replace,
+    importable: bundle.importable && rows.every((row) => row.action !== "blocked" && row.action !== "conflict"),
     rows,
     warnings
   });
-  return { ...plan, importable: false };
+  plan = { ...plan, importable: plan.summary.blocked === 0 && plan.summary.conflict === 0 };
+  return {
+    ...plan,
+    manifest: buildSelfHostedManifest({
+      apiUrl,
+      dryRun: true,
+      replace,
+      includeRuns: opts.includeRuns ?? true,
+      bundle,
+      remote,
+      plan
+    })
+  };
 }
 async function postImportBatch(fetchImpl, config, payload) {
   const body = await requestJson(fetchImpl, config, "/v1/import", { method: "POST", body: JSON.stringify(payload) });
@@ -11119,23 +11435,29 @@ async function applySelfHostedPush(store, opts) {
   const fetchImpl = opts.fetchImpl ?? fetch;
   const includeRuns = opts.includeRuns ?? true;
   const replace = opts.replace ?? false;
+  const plan = await buildSelfHostedMigrationPlan(store, { ...opts, operation: "self-hosted-push", includeRuns, replace });
+  if (plan.summary.blocked > 0 || plan.summary.conflict > 0 || !plan.importable) {
+    throw new ValidationError(`self-hosted push is not safe to apply: blocked=${plan.summary.blocked} conflict=${plan.summary.conflict}`);
+  }
   const batchRows = Math.max(1, opts.batchRows ?? 200);
   const runBatchBytes = Math.max(64 * 1024, opts.runBatchBytes ?? 4 * 1024 * 1024);
   const applied = { workflows: 0, loops: 0, runs: 0 };
   const skipped = { runningRuns: 0, orphanRuns: 0 };
   let requests = 0;
   const base = store.exportMigrationRows({ includeRuns: false });
+  const workflows = base.workflows.map(disabledWorkflowForSelfHostedImport);
+  const loops = base.loops.map(pausedLoopForSelfHostedImport);
   const loopIds = new Set(base.loops.map((loop) => loop.id));
-  for (let i = 0;i < base.workflows.length; i += batchRows) {
-    const batch = base.workflows.slice(i, i + batchRows);
-    const result = await postImportBatch(fetchImpl, config, { workflows: batch, replace });
+  for (let i = 0;i < workflows.length; i += batchRows) {
+    const batch = workflows.slice(i, i + batchRows);
+    const result = await postImportBatch(fetchImpl, config, { workflows: batch, replace, preserveWorkflowActivation: false, preserveLoopScheduling: false });
     applied.workflows += result.imported.workflows;
     requests += 1;
     opts.onProgress?.({ phase: "workflows", sent: applied.workflows, requests });
   }
-  for (let i = 0;i < base.loops.length; i += batchRows) {
-    const batch = base.loops.slice(i, i + batchRows);
-    const result = await postImportBatch(fetchImpl, config, { loops: batch, replace });
+  for (let i = 0;i < loops.length; i += batchRows) {
+    const batch = loops.slice(i, i + batchRows);
+    const result = await postImportBatch(fetchImpl, config, { loops: batch, replace, preserveLoopScheduling: false });
     applied.loops += result.imported.loops;
     requests += 1;
     opts.onProgress?.({ phase: "loops", sent: applied.loops, requests });
@@ -11147,7 +11469,7 @@ async function applySelfHostedPush(store, opts) {
     const flush = async () => {
       if (pending.length === 0)
         return;
-      const result = await postImportBatch(fetchImpl, config, { runs: pending, replace });
+      const result = await postImportBatch(fetchImpl, config, { runs: pending, replace, preserveLoopScheduling: false });
       applied.runs += result.imported.runs;
       skipped.runningRuns += result.skippedRunning;
       requests += 1;
@@ -11177,7 +11499,36 @@ async function applySelfHostedPush(store, opts) {
     }
     await flush();
   }
-  return { ok: true, apiUrl: config.apiUrl, applied, skipped, requests };
+  const remoteAfter = await fetchRemotePreview({ ...opts, operation: "self-hosted-push", includeRuns: false });
+  const bundle = selfHostedDefinitionBundle(exportLoopsMigrationBundle(store, { includeRuns }));
+  const remoteBefore = plan.manifest ? {
+    workflows: [],
+    loops: [],
+    runs: [],
+    counts: plan.manifest.counts.remoteBefore,
+    unsupported: plan.manifest.unsafe.unsupported,
+    warnings: []
+  } : await fetchRemotePreview({ ...opts, operation: "self-hosted-push", includeRuns });
+  return {
+    ok: true,
+    apiUrl: config.apiUrl,
+    applied,
+    skipped,
+    requests,
+    manifest: buildSelfHostedManifest({
+      apiUrl: config.apiUrl,
+      dryRun: false,
+      replace,
+      includeRuns,
+      bundle,
+      remote: remoteBefore,
+      plan,
+      applied,
+      skipped,
+      requests,
+      remoteAfter: remoteAfter.counts
+    })
+  };
 }
 async function registerSelfHostedRunner(opts) {
   const config = resolveApiConfig(opts);
@@ -14124,6 +14475,9 @@ var ROUTE_MANUAL_GATE_FIELDS = [
   "approval_required",
   "approvalRequired"
 ];
+function taskRouteDisallowedTag(tags) {
+  return tags.find((tag) => ROUTE_DISALLOWED_TASK_TAGS.has(tag.toLowerCase()));
+}
 function taskRouteEligibility(data, metadata) {
   const records = taskEventRecords(data, metadata);
   const automation = automationRecords(data, metadata);
@@ -15918,18 +16272,28 @@ function todosTaskRouteRedispatchBackoffMs(attempts) {
 }
 function reactivateStaleTodosTaskWorkItem(store, routeKey, item, now = Date.now()) {
   if (routeKey !== "todos-task")
-    return;
+    return { kind: "dedupe" };
   if (!REACTIVATABLE_TERMINAL_STATUSES.has(item.status))
-    return;
-  if (item.attempts >= MAX_TODOS_TASK_ROUTE_REDISPATCHES)
-    return;
+    return { kind: "dedupe" };
+  if (item.status === "dead_letter" && item.gateDeaths >= GATE_DEATH_CEILING) {
+    return { kind: "dedupe" };
+  }
+  if (item.attempts >= MAX_TODOS_TASK_ROUTE_REDISPATCHES) {
+    if (item.status === "dead_letter")
+      return { kind: "dedupe" };
+    const deadLettered = store.deadLetterWorkflowWorkItem(item.id, {
+      reason: `redispatch cap reached (${item.attempts}/${MAX_TODOS_TASK_ROUTE_REDISPATCHES}): todos task still actionable but ` + `${item.attempts} runs finished without closing it; dead-lettered. Fix the task or 'loops routes requeue' to retry (resets attempts).`
+    });
+    return { kind: "dead-letter", item: deadLettered };
+  }
   const finishedAt = Date.parse(item.updatedAt);
   if (Number.isFinite(finishedAt) && now - finishedAt < todosTaskRouteRedispatchBackoffMs(item.attempts)) {
-    return;
+    return { kind: "dedupe" };
   }
-  return store.requeueWorkflowWorkItem(item.id, {
+  const requeued = store.requeueWorkflowWorkItem(item.id, {
     reason: `re-admitted from ${item.status}: todos task still actionable after prior run (attempt ${item.attempts + 1}/${MAX_TODOS_TASK_ROUTE_REDISPATCHES})`
   });
+  return { kind: "readmit", item: requeued };
 }
 function findRouteWorkItemByKeys(store, routeKey, idempotencyKeys) {
   const [primaryKey, ...aliasKeys] = idempotencyKeys;
@@ -16034,12 +16398,14 @@ function codewithAuthProfilesFromWorkflow(workflow) {
   return profiles.length ? profiles : undefined;
 }
 function dedupedRoutePrint(plan, outcome) {
+  const deadLettered = outcome.existingItem.status === "dead_letter";
   return {
     kind: "deduped",
     value: {
       deduped: true,
       idempotencyKey: plan.idempotencyKey,
       dedupedBy: "work-item",
+      ...deadLettered ? { deadLettered: true, reason: outcome.existingItem.lastReason } : {},
       event: plan.event,
       ...plan.dedupeValueExtras,
       invocation: outcome.invocation ? publicWorkflowInvocation(outcome.invocation) : undefined,
@@ -16047,7 +16413,7 @@ function dedupedRoutePrint(plan, outcome) {
       workflow: outcome.existingWorkflow ? publicWorkflow(outcome.existingWorkflow) : undefined,
       loop: outcome.existingLoop ? publicLoop(outcome.existingLoop) : undefined
     },
-    human: `deduped existing work item ${outcome.existingItem.id} for event=${plan.event.id} idempotency=${plan.idempotencyKey}`
+    human: deadLettered ? `dead-lettered work item ${outcome.existingItem.id} (redispatch cap reached) for event=${plan.event.id} idempotency=${plan.idempotencyKey}` : `deduped existing work item ${outcome.existingItem.id} for event=${plan.event.id} idempotency=${plan.idempotencyKey}`
   };
 }
 function routeEvent(plan) {
@@ -16136,10 +16502,12 @@ function routeEvent(plan) {
       const invocation = store.createWorkflowInvocation(plan.invocationInput);
       const existingItem = findRouteWorkItemByKeys(store, plan.routeKey, dedupeKeys);
       if (existingItem) {
-        if (!reactivateStaleTodosTaskWorkItem(store, plan.routeKey, existingItem)) {
-          const existingLoop = existingItem.loopId ? store.getLoop(existingItem.loopId) : undefined;
-          const existingWorkflow = existingItem.workflowId ? store.getWorkflow(existingItem.workflowId) : undefined;
-          return { kind: "deduped", existingItem, existingLoop, existingWorkflow, invocation };
+        const reactivation = reactivateStaleTodosTaskWorkItem(store, plan.routeKey, existingItem);
+        if (reactivation.kind !== "readmit") {
+          const dedupeItem = reactivation.kind === "dead-letter" ? reactivation.item : existingItem;
+          const existingLoop = dedupeItem.loopId ? store.getLoop(dedupeItem.loopId) : undefined;
+          const existingWorkflow = dedupeItem.workflowId ? store.getWorkflow(dedupeItem.workflowId) : undefined;
+          return { kind: "deduped", existingItem: dedupeItem, existingLoop, existingWorkflow, invocation };
         }
       }
       const throttle = hasThrottleLimits(plan.throttleLimits) ? routeThrottleDecision(store, {
@@ -16305,11 +16673,13 @@ function routeTodosTaskEvent(event, opts) {
     try {
       const existingItem = findRouteWorkItemByKeys(store, "todos-task", [idempotencyKey, ...dedupeAliases]);
       if (existingItem) {
-        if (!reactivateStaleTodosTaskWorkItem(store, "todos-task", existingItem)) {
-          const existingLoop = existingItem.loopId ? store.getLoop(existingItem.loopId) : undefined;
-          const existingWorkflow = existingItem.workflowId ? store.getWorkflow(existingItem.workflowId) : undefined;
-          const existingInvocation = store.getWorkflowInvocation(existingItem.invocationId);
-          return dedupedRoutePrint({ event, idempotencyKey, dedupeValueExtras: {} }, { existingItem, existingLoop, existingWorkflow, invocation: existingInvocation });
+        const reactivation = reactivateStaleTodosTaskWorkItem(store, "todos-task", existingItem);
+        if (reactivation.kind !== "readmit") {
+          const dedupeItem = reactivation.kind === "dead-letter" ? reactivation.item : existingItem;
+          const existingLoop = dedupeItem.loopId ? store.getLoop(dedupeItem.loopId) : undefined;
+          const existingWorkflow = dedupeItem.workflowId ? store.getWorkflow(dedupeItem.workflowId) : undefined;
+          const existingInvocation = store.getWorkflowInvocation(dedupeItem.invocationId);
+          return dedupedRoutePrint({ event, idempotencyKey, dedupeValueExtras: {} }, { existingItem: dedupeItem, existingLoop, existingWorkflow, invocation: existingInvocation });
         }
       }
     } finally {
@@ -16622,6 +16992,33 @@ function taskSourceWorkingDir(task) {
 function canonicalRoutePath(path) {
   return normalizeRoutePath(path) ?? (path?.trim() ? resolve8(path) : undefined);
 }
+function taskUsableRepoProjectPath(task, isRepo) {
+  const metadata = objectField2(task.metadata) ?? {};
+  const candidates = [
+    taskField(task, ["project_path", "projectPath"]),
+    taskEventField(metadata, ["project_path", "projectPath", "project_canonical_path"]),
+    taskDescriptionProjectPath(task),
+    taskField(task, ["working_dir", "workingDir", "cwd"]),
+    taskEventField(metadata, ["working_dir", "workingDir", "cwd"])
+  ];
+  for (const candidate of candidates) {
+    const canonical = canonicalRoutePath(candidate);
+    if (canonical && isRepo(canonical))
+      return canonical;
+  }
+  return;
+}
+function memoizedIsExistingGitProjectPath() {
+  const cache = new Map;
+  return (path) => {
+    const cached = cache.get(path);
+    if (cached !== undefined)
+      return cached;
+    const result = isExistingGitProjectPath(path);
+    cache.set(path, result);
+    return result;
+  };
+}
 function taskListValues(task) {
   const taskList = objectField2(task.task_list);
   return [
@@ -16737,6 +17134,7 @@ function compactDrainResult(result) {
     routeScope: stringField(value.routeScope),
     requeue,
     queuedAtSource: value.queuedAtSource,
+    deadLettered: value.deadLettered === true ? true : undefined,
     fatal: value.fatal === true ? true : undefined
   };
 }
@@ -17015,10 +17413,12 @@ function drainTodosTaskRoutes(opts) {
       scanned: 0,
       candidates: 0,
       filteredCandidates: 0,
+      excludedDisallowedTag: 0,
       scanExhausted: false,
       considered: 0,
       created: 0,
       deduped: 0,
+      deadLettered: 0,
       throttled: 0,
       skipped: 0,
       freshnessClosed: 0,
@@ -17047,10 +17447,12 @@ function drainTodosTaskRoutes(opts) {
       scanned: report2.scanned,
       candidates: report2.candidates,
       filteredCandidates: report2.filteredCandidates,
+      excludedDisallowedTag: report2.excludedDisallowedTag,
       scanExhausted: report2.scanExhausted,
       considered: report2.considered,
       created: report2.created,
       deduped: report2.deduped,
+      deadLettered: report2.deadLettered,
       throttled: report2.throttled,
       skipped: report2.skipped,
       freshnessClosed: report2.freshnessClosed,
@@ -17076,7 +17478,14 @@ function drainTodosTaskRoutes(opts) {
     projectPathPrefix: opts.projectPathPrefix,
     tags: requiredTags
   }));
-  const candidates = filteredCandidates.slice(0, candidateLimit);
+  const requiredTagSet = new Set(requiredTags.map((tag) => tag.toLowerCase()));
+  const windowCandidates = filteredCandidates.filter((task) => {
+    const disallowed = taskRouteDisallowedTag(tagsFromValue2(task.tags));
+    return !disallowed || requiredTagSet.has(disallowed.toLowerCase());
+  });
+  const excludedDisallowedTag = filteredCandidates.length - windowCandidates.length;
+  const candidates = windowCandidates.slice(0, candidateLimit);
+  const isRepo = memoizedIsExistingGitProjectPath();
   const results = [];
   let created = 0;
   for (const task of candidates) {
@@ -17086,7 +17495,7 @@ function drainTodosTaskRoutes(opts) {
     let result;
     try {
       const sourceProject = opts.todosProjectsFromRegistry ? taskField(task, ["source_project_path", "sourceProjectPath"]) : undefined;
-      const explicitRouteProjectPath = sourceProject ? taskRoutePathFromRegistry(sourceProject) : opts.projectPath;
+      const explicitRouteProjectPath = sourceProject ? taskRoutePathFromRegistry(sourceProject) : taskUsableRepoProjectPath(task, isRepo) ?? opts.projectPath;
       event = taskDrainEvent(task, sourceProject, explicitRouteProjectPath);
       result = routeTodosTaskEvent(event, {
         ...opts,
@@ -17129,10 +17538,12 @@ function drainTodosTaskRoutes(opts) {
     scanned: ready.length,
     candidates: candidates.length,
     filteredCandidates: filteredCandidates.length,
-    scanExhausted: ready.length >= scanLimit && filteredCandidates.length < candidateLimit,
+    excludedDisallowedTag,
+    scanExhausted: ready.length >= scanLimit && windowCandidates.length < candidateLimit,
     considered: results.length,
     created: results.filter((result) => result.kind === "created" && !result.value.deduped).length,
     deduped: results.filter((result) => result.kind === "deduped").length,
+    deadLettered: results.filter((result) => result.kind === "deduped" && result.value.deadLettered === true).length,
     throttled: results.filter((result) => result.kind === "throttled").length,
     skipped: results.filter((result) => result.kind === "skipped").length,
     freshnessClosed: results.filter((result) => isFreshnessSkip(result) && result.value.sourceTaskUpdate?.attempted === true).length,
@@ -17161,10 +17572,12 @@ function drainTodosTaskRoutes(opts) {
     scanned: report.scanned,
     candidates: report.candidates,
     filteredCandidates: report.filteredCandidates,
+    excludedDisallowedTag: report.excludedDisallowedTag,
     scanExhausted: report.scanExhausted,
     considered: report.considered,
     created: report.created,
     deduped: report.deduped,
+    deadLettered: report.deadLettered,
     throttled: report.throttled,
     skipped: report.skipped,
     freshnessClosed: report.freshnessClosed,
@@ -17179,7 +17592,7 @@ function drainTodosTaskRoutes(opts) {
   } : { ...report, evidencePath };
   return {
     value,
-    human: `drained todos ready queue: considered=${report.considered} created=${report.created} deduped=${report.deduped} throttled=${report.throttled} skipped=${report.skipped} freshnessClosed=${report.freshnessClosed} fatal=${report.fatal}`
+    human: `drained todos ready queue: considered=${report.considered} created=${report.created} deduped=${report.deduped} deadLettered=${report.deadLettered} throttled=${report.throttled} skipped=${report.skipped} freshnessClosed=${report.freshnessClosed} fatal=${report.fatal} excludedDisallowedTag=${report.excludedDisallowedTag}`
   };
 }
 // src/lib/route/route-tasks.ts
@@ -17846,6 +18259,14 @@ function printMigrationPlan(plan, opts = {}) {
     console.log(`${row.action} ${row.resource}:${row.name ?? row.id} ${row.reason ?? ""}`.trim());
   }
 }
+function writeManifestFile(file, manifest) {
+  if (!file)
+    return;
+  if (manifest === undefined)
+    throw new ValidationError("command did not produce a manifest");
+  writeFileSync7(file, `${JSON.stringify(manifest, null, 2)}
+`, { mode: 384 });
+}
 function backupLoopsDatabase(reason) {
   return backupDatabase({ reason, keep: 3 }).path;
 }
@@ -18003,15 +18424,17 @@ function selfHostedMigrationCommand(operation) {
   });
 }
 selfHosted.command("migrate").description("preview local-to-self-hosted migration actions").option("--api-url <url>", "self-hosted control-plane API URL").option("--dry-run", "preview only; self-hosted migrate does not apply remote changes yet").option("--no-runs", "omit loop run history from the preview").option("--json", "print JSON").action(selfHostedMigrationCommand("self-hosted-migrate"));
-selfHosted.command("push").description("preview (default) or apply an id-preserving local->self-hosted backfill").option("--api-url <url>", "self-hosted control-plane API URL").option("--apply", "apply the backfill via the control-plane /v1/import endpoint (default is preview)").option("--replace", "update existing remote rows whose id matches (default: leave existing rows unchanged)").option("--dry-run", "preview only; equivalent to omitting --apply").option("--no-runs", "omit loop run history").option("--json", "print JSON").action(runAction(async (opts) => {
+selfHosted.command("push").description("preview (default) or apply an id-preserving local->self-hosted backfill").option("--api-url <url>", "self-hosted control-plane API URL").option("--apply", "apply the backfill via the control-plane /v1/import endpoint (default is preview)").option("--replace", "update differing same-id remote rows; safe default may still archive/pause same-id definitions").option("--dry-run", "preview only; equivalent to omitting --apply").option("--no-runs", "omit loop run history").option("--manifest-file <path>", "write a self-hosted comparison/import manifest JSON file").option("--json", "print JSON").action(runAction(async (opts) => {
   if (!opts.apply || opts.dryRun) {
     const store2 = new Store;
     try {
       const plan = await buildSelfHostedMigrationPlan(store2, {
         operation: "self-hosted-push",
         apiUrl: opts.apiUrl,
-        includeRuns: opts.runs
+        includeRuns: opts.runs,
+        replace: opts.replace
       });
+      writeManifestFile(opts.manifestFile, plan.manifest);
       printMigrationPlan(plan, opts);
     } finally {
       store2.close();
@@ -18025,6 +18448,7 @@ selfHosted.command("push").description("preview (default) or apply an id-preserv
       includeRuns: opts.runs,
       replace: opts.replace
     });
+    writeManifestFile(opts.manifestFile, result.manifest);
     if (isJson() || opts.json)
       console.log(JSON.stringify(result, null, 2));
     else {
@@ -18194,12 +18618,12 @@ routes.command("show <id>").description("show one admission work item").action(r
     loop: loop ? publicLoop(loop) : undefined
   }, `${item.id} ${item.status} ${item.routeKey} ${item.subjectRef}`);
 })));
-routes.command("requeue <id>").description("requeue a terminal admission work item for the next task/event delivery").option("--reason <text>", "operator reason recorded on the work item").action(runAction((id, opts) => withStore(async (store) => {
+routes.command("requeue <id>").description("requeue a terminal admission work item for the next task/event delivery (resets the redispatch attempt count so the unwedge is durable; --keep-attempts preserves it)").option("--reason <text>", "operator reason recorded on the work item").option("--keep-attempts", "preserve the redispatch attempt count instead of resetting it (cautious path: the item may re-cap after one more terminal run)").action(runAction((id, opts) => withStore(async (store) => {
   const reason = stringField(opts.reason);
   if (!reason)
     throw new ValidationError("routes requeue requires --reason <text>");
-  const item = await store.requeueWorkflowWorkItem(id, { reason });
-  print(publicWorkflowWorkItem(item), `requeued route work item ${item.id} (${item.routeKey})`);
+  const item = await store.requeueWorkflowWorkItem(id, { reason, resetAttempts: !opts.keepAttempts });
+  print(publicWorkflowWorkItem(item), `requeued route work item ${item.id} (${item.routeKey}) - ${opts.keepAttempts ? "attempts preserved" : "attempts reset"}`);
 })));
 routes.command("invocations").description("list workflow invocations").option("--limit <n>", "maximum rows", "50").action(runAction((opts) => withStore(async (store) => {
   const invocations = await store.listWorkflowInvocations({ limit: positiveInteger(opts.limit, "--limit") ?? 50 });