@hasna/loops 0.3.56 → 0.3.58

package/dist/sdk/index.js

@@ -459,6 +459,9 @@ function validateTarget(value, label, opts) {
     }
     if (value.model !== undefined)
       assertString(value.model, `${label}.model`);
+    if (value.provider === "opencode" && (typeof value.model !== "string" || value.model.trim() === "")) {
+      throw new Error(`${label}.model is required for provider opencode; pass a provider/model id such as openrouter/google/gemini-2.5-flash`);
+    }
     if (value.variant !== undefined)
       assertString(value.variant, `${label}.variant`);
     if (value.agent !== undefined)
@@ -1255,12 +1258,21 @@ class Store {
     if (!row)
       throw new Error("daemon lease lost");
   }
+  assertNoNestedWorkflowGoal(target, goal) {
+    if (!goal || target.type !== "workflow")
+      return;
+    const workflow = this.getWorkflow(target.workflowId);
+    if (workflow?.goal) {
+      throw new Error(`workflow loop cannot define a loop-level goal when workflow ${workflow.name} already has a top-level goal; remove one goal wrapper`);
+    }
+  }
   createLoop(input, from = new Date) {
     const now = nowIso();
     const target = input.target.type === "workflow" ? input.target : normalizeCreateWorkflowInput({
       name: "loop-target-validation",
       steps: [{ id: "target", target: input.target }]
     }).steps[0].target;
+    this.assertNoNestedWorkflowGoal(target, input.goal);
     const loop = {
       id: genId(),
       name: input.name,
@@ -1432,6 +1444,9 @@ class Store {
       if (this.hasRunningRun(current.id))
         throw new Error(`refusing to retarget running loop: ${current.id}`);
       const workflow = this.requireWorkflow(workflowId);
+      if (current.goal && workflow.goal) {
+        throw new Error(`workflow loop cannot retarget ${current.name} to workflow ${workflow.name} because both define top-level goals`);
+      }
       const target = { ...current.target, workflowId: workflow.id };
       if (opts.workflowTimeoutMs !== undefined)
         target.timeoutMs = opts.workflowTimeoutMs;
@@ -1470,6 +1485,9 @@ class Store {
         throw new Error(`loop is not a workflow loop: ${idOrName}`);
       if (this.hasRunningRun(current.id))
         throw new Error(`refusing to retarget running loop: ${current.id}`);
+      if (current.goal && normalized.goal) {
+        throw new Error(`workflow loop cannot retarget ${current.name} to a workflow that also defines a top-level goal`);
+      }
       const previousWorkflow = this.requireWorkflow(current.target.workflowId);
       const workflow = {
         id: genId(),
@@ -1761,7 +1779,7 @@ class Store {
     if (!sourceDedupeKey)
       throw new Error("cannot refresh workflow invocation without sourceRef.dedupeKey");
     const now = nowIso();
-    const claimableStatuses = ["queued", "deferred", "failed", "dead_letter", "cancelled"];
+    const claimableStatuses = ["queued", "deferred"];
     const statusBindings = Object.fromEntries(claimableStatuses.map((status, index) => [`$status${index}`, status]));
     const placeholders = claimableStatuses.map((_, index) => `$status${index}`).join(",");
     const result = this.db.query(`UPDATE workflow_invocations
@@ -1842,28 +1860,35 @@ class Store {
           project_group=excluded.project_group,
           priority=excluded.priority,
           status=CASE
-            WHEN workflow_work_items.status IN ('succeeded', 'admitted', 'running')
+            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') THEN workflow_work_items.workflow_id
+            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') THEN workflow_work_items.loop_id
+            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') THEN workflow_work_items.workflow_run_id
+            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') THEN workflow_work_items.lease_expires_at
+            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=COALESCE(excluded.last_reason, workflow_work_items.last_reason),
+          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`).run({
       $id: id,
       $routeKey: input.routeKey,
@@ -1916,11 +1941,39 @@ class Store {
     const projectGroup = args.projectGroup ? this.db.query(`SELECT COUNT(*) AS count FROM workflow_work_items WHERE status IN (${placeholders}) AND project_group = ?`).get(...active, args.projectGroup)?.count ?? 0 : undefined;
     return { global, project, ...projectGroup !== undefined ? { projectGroup } : {} };
   }
+  requeueWorkflowWorkItem(id, patch = {}) {
+    const current = this.getWorkflowWorkItem(id);
+    if (!current)
+      throw new Error(`workflow work item not found: ${id}`);
+    const requeueableStatuses = ["succeeded", "failed", "dead_letter", "cancelled"];
+    if (!requeueableStatuses.includes(current.status)) {
+      throw new Error(`workflow work item is not requeueable: ${id} status=${current.status}`);
+    }
+    const now = nowIso();
+    const reason = patch.reason?.trim() || `requeued from ${current.status}`;
+    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,
+          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);
+    if (!item)
+      throw new Error(`workflow work item not found after requeue: ${id}`);
+    if (res.changes !== 1)
+      throw new Error(`workflow work item was not requeued: ${id} status=${item.status}`);
+    return item;
+  }
   admitWorkflowWorkItem(id, patch) {
     const now = nowIso();
     const res = this.db.query(`UPDATE workflow_work_items
          SET status='admitted', attempts=attempts + 1, workflow_id=$workflowId, loop_id=$loopId,
-          next_attempt_at=NULL, lease_expires_at=NULL, last_reason=$reason, updated_at=$updated
+          next_attempt_at=NULL,
+          lease_expires_at=NULL,
+          last_reason=CASE
+            WHEN last_reason IS NOT NULL AND $reason IS NOT NULL THEN last_reason || '; ' || $reason
+            ELSE COALESCE($reason, last_reason)
+          END,
+          updated_at=$updated
          WHERE id=$id AND status IN ('queued', 'deferred')`).run({
       $id: id,
       $workflowId: patch.workflowId,
@@ -3454,6 +3507,9 @@ function assertSupportedAgentOptions(target) {
   assertStringOption(target.agent, `${target.provider}.agent`);
   assertStringOption(target.authProfile, `${target.provider}.authProfile`);
   assertStringOption(target.configIsolation, `${target.provider}.configIsolation`);
+  if (target.provider === "opencode" && (target.model === undefined || target.model.trim() === "")) {
+    throw new Error("opencode.model is required; pass a provider/model id such as openrouter/google/gemini-2.5-flash");
+  }
   if (target.configIsolation !== undefined && target.configIsolation !== "safe" && target.configIsolation !== "none") {
     throw new Error(`${target.provider}.configIsolation must be safe or none`);
   }
@@ -4226,6 +4282,78 @@ function sameBlockerKey(values) {
   return values.map((value) => value.trim()).filter(Boolean).join(`
 `) || "goal completion remains unproven";
 }
+function planStatusForGoal(goal) {
+  if (goal.status === "usageLimited")
+    return "blocked";
+  return goal.status;
+}
+function syncReadyFlags(store, goal, nodes, opts) {
+  const withReady = updateReadyFlags(nodes, planStatusForGoal(goal));
+  for (const node of withReady) {
+    const current = nodes.find((entry) => entry.key === node.key);
+    if (current && current.ready !== node.ready) {
+      store.updateGoalPlanNode(goal.goalId, node.key, { ready: node.ready }, { daemonLeaseId: opts.daemonLeaseId });
+    }
+  }
+  return withReady;
+}
+function summarizeLabels(values, limit = 5) {
+  if (values.length <= limit)
+    return values.join(", ");
+  return `${values.slice(0, limit).join(", ")} and ${values.length - limit} more`;
+}
+function noReadyDiagnostic(goal, nodes) {
+  const planStatus = planStatusForGoal(goal);
+  const byKey = new Map(nodes.map((node) => [node.key, node]));
+  const pendingNodes = nodes.filter((node) => node.status === "pending");
+  const incompleteNodes = nodes.filter((node) => node.status !== "complete");
+  const pendingDetails = pendingNodes.map((node) => ({
+    key: node.key,
+    status: node.status,
+    ready: node.ready,
+    tokenBudget: node.tokenBudget,
+    tokensUsed: node.tokensUsed,
+    budgetExhausted: nodeBudgetExhausted(node),
+    unmetDependencies: node.dependsOn.map((dependency) => ({ key: dependency, status: byKey.get(dependency)?.status ?? "missing" })).filter((dependency) => dependency.status !== "complete")
+  }));
+  const incompleteDetails = incompleteNodes.map((node) => ({
+    key: node.key,
+    status: node.status,
+    ready: node.ready
+  }));
+  let owner = "goal-plan";
+  let cause = "goal plan has no ready nodes";
+  if (planStatus !== "active") {
+    owner = "goal";
+    cause = `goal status is ${goal.status}`;
+  } else if (pendingNodes.length === 0) {
+    owner = "goal-plan";
+    cause = `goal plan has no pending runnable nodes; incomplete nodes: ${summarizeLabels(incompleteDetails.map((node) => `${node.key}:${node.status}`))}`;
+  } else if (pendingDetails.every((node) => node.budgetExhausted)) {
+    owner = "goal-plan-node";
+    cause = `all pending nodes are budget-exhausted: ${summarizeLabels(pendingDetails.map((node) => node.key))}`;
+  } else {
+    const missingDependencies = pendingDetails.flatMap((node) => node.unmetDependencies.filter((dependency) => dependency.status === "missing").map((dependency) => `${node.key}->${dependency.key}`));
+    if (missingDependencies.length > 0) {
+      owner = "goal-plan";
+      cause = `pending nodes reference missing dependencies: ${summarizeLabels(missingDependencies)}`;
+    } else if (pendingDetails.every((node) => node.unmetDependencies.length > 0 || node.budgetExhausted)) {
+      owner = "goal-plan-node";
+      const waiting = pendingDetails.filter((node) => node.unmetDependencies.length > 0).map((node) => `${node.key} waits on ${node.unmetDependencies.map((dependency) => `${dependency.key}:${dependency.status}`).join(",")}`);
+      const exhausted = pendingDetails.filter((node) => node.budgetExhausted).map((node) => `${node.key} budget exhausted`);
+      cause = `pending nodes are blocked by prerequisites: ${summarizeLabels([...waiting, ...exhausted])}`;
+    }
+  }
+  const blocker = `${cause}; owner=${owner}`;
+  return {
+    owner,
+    blocker,
+    planStatus,
+    rollup: rollupSummary(nodes),
+    pendingNodes: pendingDetails,
+    incompleteNodes: incompleteDetails
+  };
+}
 function metadataFor(goal, node, context) {
   return {
     loopId: context?.loopId,
@@ -4286,13 +4414,14 @@ async function planGoal(store, goal, spec, model, opts) {
   }, { daemonLeaseId: opts.daemonLeaseId });
   return store.createGoalPlanNodes(goal.goalId, rawNodes, { daemonLeaseId: opts.daemonLeaseId });
 }
-function stdoutFor(goal, nodes, evidence, validation) {
+function stdoutFor(goal, nodes, evidence, validation, diagnostics) {
   return JSON.stringify({
     goal,
     rollup: rollupSummary(nodes),
     nodes,
     evidence,
-    validation
+    validation,
+    diagnostics
   }, null, 2);
 }
 async function runGoal(store, input, opts = {}) {
@@ -4325,6 +4454,7 @@ async function runGoal(store, input, opts = {}) {
   let validation;
   let lastBlocker = "";
   let repeatedBlockerCount = 0;
+  let lastDiagnostic;
   if (budgetExhausted(goal)) {
     goal = store.updateGoalStatus(goal.goalId, "budgetLimited", { daemonLeaseId: opts.daemonLeaseId });
     return resultFromGoal(goal, "failed", stdoutFor(goal, nodes, evidence), "goal token budget exhausted after planning", startedAt);
@@ -4335,13 +4465,13 @@ async function runGoal(store, input, opts = {}) {
       return resultFromGoal(goal, "failed", stdoutFor(goal, nodes, evidence), "goal cancelled", startedAt);
     }
     goal = store.requireGoal(goal.goalId);
-    nodes = store.listGoalPlanNodes(goal.goalId);
+    nodes = syncReadyFlags(store, goal, store.listGoalPlanNodes(goal.goalId), opts);
     if (budgetExhausted(goal)) {
       goal = store.updateGoalStatus(goal.goalId, "budgetLimited", { daemonLeaseId: opts.daemonLeaseId });
       return resultFromGoal(goal, "failed", stdoutFor(goal, nodes, evidence), "goal token budget exhausted", startedAt);
     }
     const readyKeys = readyNodeKeys({
-      status: goal.status === "active" ? "active" : goal.status === "budgetLimited" ? "budgetLimited" : "blocked",
+      status: planStatusForGoal(goal),
       nodes
     });
     if (readyKeys.length > 0) {
@@ -4440,7 +4570,9 @@ ${result.stderr}`);
       }
       continue;
     }
-    const blocker = "no ready goal nodes and goal plan is incomplete";
+    const diagnostic = noReadyDiagnostic(goal, nodes);
+    lastDiagnostic = diagnostic;
+    const blocker = diagnostic.blocker;
     if (blocker === lastBlocker)
       repeatedBlockerCount += 1;
     else {
@@ -4452,15 +4584,16 @@ ${result.stderr}`);
       turn,
       phase: "status",
       status: repeatedBlockerCount >= 3 ? "blocked" : "active",
-      evidence: { blocker }
+      evidence: diagnostic
     }, { daemonLeaseId: opts.daemonLeaseId });
     if (repeatedBlockerCount >= 3) {
       goal = store.updateGoalStatus(goal.goalId, "blocked", { daemonLeaseId: opts.daemonLeaseId });
-      return resultFromGoal(goal, "failed", stdoutFor(goal, nodes, evidence, validation), blocker, startedAt);
+      return resultFromGoal(goal, "failed", stdoutFor(goal, nodes, evidence, validation, diagnostic), blocker, startedAt);
     }
   }
   goal = store.updateGoalStatus(goal.goalId, "usageLimited", { daemonLeaseId: opts.daemonLeaseId });
-  return resultFromGoal(goal, "failed", stdoutFor(goal, store.listGoalPlanNodes(goal.goalId), evidence, validation), "goal max turns exhausted", startedAt);
+  const exhaustedError = lastDiagnostic?.blocker ?? (lastBlocker ? `${lastBlocker}; max turns exhausted` : "goal max turns exhausted");
+  return resultFromGoal(goal, "failed", stdoutFor(goal, store.listGoalPlanNodes(goal.goalId), evidence, validation, lastDiagnostic), exhaustedError, startedAt);
 }
 
 // src/lib/workflow-runner.ts
@@ -4489,6 +4622,7 @@ async function executeWorkflow(store, workflow, opts = {}) {
     const workflowWithoutGoal = { ...workflow, goal: undefined };
     return runGoal(store, workflow.goal, {
       ...opts,
+      model: opts.goalModel,
       context: {
         loopId: opts.loop?.id,
         loopName: opts.loop?.name,
@@ -4581,6 +4715,7 @@ async function executeWorkflow(store, workflow, opts = {}) {
       if (step.goal) {
         result = await runGoal(store, step.goal, {
           ...opts,
+          model: opts.goalModel,
           target: targetWithStepAccount(step),
           signal: controller.signal,
           context: {
@@ -4722,6 +4857,7 @@ async function executeLoopTarget(store, loop, run, opts = {}) {
     if (loop.goal) {
       return runGoal(store, loop.goal, {
         ...opts,
+        model: opts.goalModel,
         target: loop.target,
         context: {
           loopId: loop.id,
@@ -4743,8 +4879,10 @@ async function executeLoopTarget(store, loop, run, opts = {}) {
     }
   }
   if (loop.goal) {
+    const workflowForLoopGoal = workflow.goal ? { ...workflow, goal: undefined } : workflow;
     return runGoal(store, loop.goal, {
       ...opts,
+      model: opts.goalModel,
       context: {
         loopId: loop.id,
         loopName: loop.name,
@@ -4753,7 +4891,7 @@ async function executeLoopTarget(store, loop, run, opts = {}) {
         workflowId: workflow.id,
         workflowName: workflow.name
       },
-      executeNode: async (node) => executeWorkflow(store, workflow, {
+      executeNode: async (node) => executeWorkflow(store, workflowForLoopGoal, {
         ...opts,
         loop,
         loopRun: run,

package/docs/AUTOMATION_RUNTIME_DESIGN.md

@@ -0,0 +1,228 @@
+# Automation Runtime Design
+
+OpenLoops can execute workflow work that external automation systems have
+already materialized, but it must not become the automation product surface.
+`@hasna/automations` and `@hasna/actions` own automation specs, trigger
+materialization, queue state, approvals, DLQ/replay, idempotency, and audit
+evidence. OpenLoops owns workflow invocation, admission, execution, run
+manifests, and provider routing once work is explicitly handed off.
+
+## Planned Workflow Upsert SDK
+
+External compilers should not write OpenLoops SQLite rows directly. The stable
+contract should be an idempotent CLI/SDK upsert that accepts a fully rendered
+one-shot workflow loop request and returns durable refs.
+
+Proposed SDK shape:
+
+```ts
+type WorkflowUpsertRequest = {
+  idempotencyKey: string;
+  source: { kind: "action" | "automation" | "event"; id: string; dedupeKey?: string };
+  subject: { kind: "repo" | "task" | "pr" | "run"; id?: string; path?: string; url?: string };
+  workflow: { name: string; description?: string; steps: WorkflowStepInput[] };
+  loop: { name: string; schedule: { type: "once"; at: string }; machine?: LoopMachineRef };
+  route?: { projectPath?: string; projectGroup?: string; concurrencyGroup?: string };
+  execution?: AutomationExecutionPolicy;
+  mode?: "dry-run" | "preflight" | "commit";
+  dispatch?: "schedule" | "run-now" | "none";
+};
+
+type AutomationExecutionPolicy = {
+  mode: "standard" | "strict";
+  envAllowlist?: string[];
+  secretRefs?: Array<{ env: string; ref: string; required?: boolean }>;
+  allowTools?: string[];
+  allowCommands?: string[];
+  requireEnforcement?: boolean;
+  redactionProfile?: "default" | "strict";
+};
+
+type WorkflowUpsertResult = {
+  ok: boolean;
+  dryRun: boolean;
+  idempotencyKey: string;
+  specHash: string;
+  refs: {
+    workflowId?: string;
+    loopId?: string;
+    invocationId?: string;
+    workItemId?: string;
+    runId?: string;
+    manifestPath?: string;
+  };
+  action: "created" | "updated" | "reused" | "rejected";
+  preflight?: { ok: boolean; checks: unknown[]; error?: string };
+};
+```
+
+Required semantics:
+
+- `mode="dry-run"` validates, canonicalizes, hashes, and returns the same JSON
+  shape without mutating OpenLoops state.
+- `mode="preflight"` additionally checks provider binaries, machine routing,
+  accounts/auth profiles, prompt files, and workflow target compatibility before
+  commit.
+- `mode="commit"` is idempotent on `idempotencyKey` plus `specHash`: identical
+  requests return existing refs; changed specs create a new workflow version or
+  one-shot loop while preserving previous run history.
+- `dispatch="schedule"` stores a one-shot loop for the daemon; `run-now` claims
+  an immediate manual slot; `none` only materializes refs for another owner to
+  trigger later.
+- All persisted output is redacted before storage, and returned refs are enough
+  for the caller to inspect, cancel, replay, or resolve the run without querying
+  SQLite directly.
+
+## CLI Surface
+
+The planned CLI should mirror the SDK:
+
+```bash
+loops workflows upsert-one-shot ./workflow.json \
+  --idempotency-key actions:<action-id>:<version> \
+  --source-kind action \
+  --source-id <action-id> \
+  --subject-kind repo \
+  --subject-path /path/to/repo \
+  --loop-name action-<action-id> \
+  --at 2026-07-01T12:00:00Z \
+  --mode preflight \
+  --dispatch schedule \
+  --json
+```
+
+`--mode dry-run` must not create a database file in an empty `LOOPS_DATA_DIR`.
+`--mode preflight` must report the exact provider/account/worktree check that
+would fail. `--mode commit` must return the durable refs required for later
+inspection and replay.
+
+## Planned Strict Automation Execution
+
+Automation-generated targets need a stricter execution mode than ordinary local
+agent loops. Strict mode should make execution reproducible, auditable, and
+secret-safe without depending on ambient shell state.
+
+### Policy
+
+`execution.mode="strict"` means:
+
+- Do not inherit full `process.env`. Start from a minimal runtime environment:
+  `PATH`, `HOME`, `TMPDIR`, locale keys, OpenLoops metadata keys, and tool
+  config dirs explicitly produced by account/secret resolution.
+- Pass only named `envAllowlist` values and `secretRefs`; never embed secret
+  values in workflow specs, prompts, metadata, manifests, or task comments.
+- Resolve `secretRefs` at run time through the owning secret/action system and
+  inject them only into the child process that needs them.
+- Default provider posture is safe: `configIsolation="safe"`, no
+  `permissionMode="bypass"`, worktree mode `required` for repo mutation, and
+  provider-native sandboxing where available.
+- Persist stdout, stderr, error, workflow events, and manifests only after
+  redaction. Strict redaction must treat `env`, `secret`, `token`, `key`,
+  `authorization`, `stdout`, `stderr`, `error`, `prompt`, and provider raw
+  response payloads as sensitive by default.
+
+### Allowlist Enforcement
+
+Current `allowlist` metadata is advisory. Strict automation requires real
+enforcement:
+
+- If `requireEnforcement=true`, preflight must reject providers that cannot
+  enforce the requested tool or command allowlist.
+- Codewith/Codex should map allowed tools and commands to provider-native flags
+  or policy files when those surfaces are available.
+- Command targets should run through a small policy wrapper that rejects
+  unlisted executables before `exec`.
+- Providers without enforceable allowlists may still run in `standard` mode,
+  but strict automation should fail before storing or dispatching them.
+
+### CLI Surface
+
+Planned flags:
+
+```bash
+loops workflows upsert-one-shot ./workflow.json \
+  --execution-mode strict \
+  --env-allow PATH,HOME,TMPDIR \
+  --secret-ref OPENROUTER_API_KEY=hasna/openrouter/live/api-key \
+  --allow-command bun,test,git \
+  --allow-tool functions.exec_command \
+  --require-allowlist-enforcement \
+  --redaction-profile strict \
+  --mode preflight \
+  --json
+```
+
+Strict-mode dry runs must show the effective policy and redacted env names, not
+secret values. Strict-mode preflight must fail with a policy classification when
+any required env, secret, account profile, provider sandbox, or allowlist
+enforcement surface is missing.
+
+## Planned DLQ And Replay
+
+OpenLoops already models terminal route work items and has a manual
+`routes requeue` command. The automation runtime contract needs a stricter DLQ
+layer for exhausted side-effecting work, because external action systems need to
+distinguish "failed attempt", "dead until operator action", and "resolved".
+
+### States
+
+Route work items should keep these meanings:
+
+- `failed`: a terminal attempt failed, but policy may still allow an explicit
+  replay after the cause is fixed.
+- `dead_letter`: automatic attempts are exhausted or the failure is classified
+  as unsafe to retry without operator action.
+- `cancelled`: an operator or owner intentionally stopped the work.
+- `succeeded`: the work completed and remains deduped history.
+- `resolved`: planned external DLQ state for `@hasna/actions`; OpenLoops can
+  mirror it as `dead_letter` plus a resolution event until a first-class status
+  is added.
+
+### Commands
+
+Planned command surface:
+
+```bash
+loops dlq list --route-key actions --status dead_letter --json
+loops dlq show <work-item-id> --json
+loops dlq replay <work-item-id> --reason "credential rotated" --idempotency-key <new-key> --json
+loops dlq resolve <work-item-id> --reason "superseded upstream" --resolution superseded --json
+```
+
+`list` and `show` must join the work item, invocation, workflow, loop, latest
+workflow run, step runs, run manifest path, classification, attempt count, and
+last redacted error. `replay` must be idempotent: the same replay request with
+the same new idempotency key returns the same refs; a different key records a
+new replay attempt linked to the original work item. `resolve` must never run
+provider code; it only records why the DLQ entry no longer needs execution.
+
+### Replay Semantics
+
+- Replay requires a human-readable `--reason`; automation callers also pass the
+  original action id and a new replay idempotency key.
+- Replay clears stale loop/workflow/run refs only for terminal work items and
+  never for `queued`, `admitted`, or `running` items.
+- Replay preserves source, subject, manifest, and previous failure history so
+  audits can explain why another attempt exists.
+- Replay of side-effecting work should default to `mode=preflight`; promotion
+  to `mode=commit` is a separate operator/API decision unless the owning
+  `@hasna/actions` policy marks the action safely replayable.
+- If `@hasna/actions` owns the queue, OpenLoops calls the action replay API and
+  stores the returned action/run refs instead of fabricating queue state.
+
+### Dead-Letter Classification
+
+The first implementation should classify terminal failures into:
+
+- `preflight`: missing provider binary, account profile, worktree, prompt file,
+  or machine route.
+- `auth`: invalid credentials or expired provider account.
+- `policy`: manual gate, approval gate, no-auto tag, or strict execution mode
+  denial.
+- `transient`: network, rate limit, provider overload, or lease loss.
+- `bug`: deterministic command/test failure, schema mismatch, or code exception.
+- `unknown`: fallback when no classifier is confident.
+
+Only `transient` and explicitly marked `bug` fixes should be eligible for
+automatic replay policy. `auth`, `policy`, and `preflight` need operator or
+owning-system resolution evidence before replay.