@hasna/loops 0.4.14 → 0.4.22

package/dist/daemon/index.js

@@ -1204,6 +1204,175 @@ function discardWorkflowRunManifest(staged) {
   } catch {}
 }
 
+// src/lib/run-receipts.ts
+import { createHash as createHash2 } from "crypto";
+import { hostname } from "os";
+
+// src/lib/run-envelope.ts
+var ENVELOPE_EXCERPT_CHARS = 2048;
+var BLOCKED_STEP_ERROR_PREFIX = "blocked:";
+function boundedExcerpt(text, limit = ENVELOPE_EXCERPT_CHARS) {
+  if (!text)
+    return;
+  const scrubbed = scrubSecrets(text);
+  if (scrubbed.length <= limit * 2)
+    return scrubbed;
+  const omitted = scrubbed.length - limit * 2;
+  return `${scrubbed.slice(0, limit)}
+[... ${omitted} chars omitted ...]
+${scrubbed.slice(-limit)}`;
+}
+function summarizeOutput(stdout, stderr) {
+  return {
+    stdoutBytes: stdout ? Buffer.byteLength(stdout, "utf8") : 0,
+    stderrBytes: stderr ? Buffer.byteLength(stderr, "utf8") : 0,
+    stdoutExcerpt: boundedExcerpt(stdout),
+    stderrExcerpt: boundedExcerpt(stderr)
+  };
+}
+function summarizeExecutorResult(result) {
+  return {
+    ...summarizeOutput(result.stdout, result.stderr),
+    status: result.status,
+    exitCode: result.exitCode,
+    durationMs: result.durationMs,
+    error: boundedExcerpt(result.error)
+  };
+}
+function isBlockedStepRun(step) {
+  return step?.status === "skipped" && (step.error?.startsWith(BLOCKED_STEP_ERROR_PREFIX) ?? false);
+}
+function summarizeWorkflowStepRun(step) {
+  return {
+    ...summarizeOutput(step.stdout, step.stderr),
+    stepId: step.stepId,
+    status: step.status,
+    exitCode: step.exitCode,
+    durationMs: step.durationMs,
+    error: boundedExcerpt(step.error),
+    blocked: isBlockedStepRun(step)
+  };
+}
+function workflowRunEnvelope(run, steps) {
+  return JSON.stringify({ workflowRun: run, steps: steps.map(summarizeWorkflowStepRun) }, null, 2);
+}
+
+// src/lib/run-receipts.ts
+var RUN_RECEIPT_SUMMARY_TEXT_CHARS = 4096;
+var RUN_RECEIPT_MAX_IDS = 100;
+var RUN_RECEIPT_MAX_EVIDENCE_PATHS = 100;
+var RUN_RECEIPT_MAX_PATH_CHARS = 1024;
+function canonicalJson(value) {
+  if (Array.isArray(value))
+    return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value).filter(([, entry]) => entry !== undefined).sort(([a], [b]) => a.localeCompare(b)).map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function digestReceipt(receipt) {
+  return `sha256:${createHash2("sha256").update(canonicalJson(receipt)).digest("hex")}`;
+}
+function isoOrNull(value, label) {
+  if (value === undefined || value === null || value === "")
+    return null;
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime()))
+    throw new Error(`${label} must be a valid ISO date/time`);
+  return date.toISOString();
+}
+function nonEmpty(value, label) {
+  const trimmed = value?.trim();
+  if (!trimmed)
+    throw new Error(`${label} must be non-empty`);
+  return trimmed;
+}
+function normalizedStringArray(values, opts) {
+  const out = [];
+  const seen = new Set;
+  for (const raw of values ?? []) {
+    const value = String(raw).trim();
+    if (!value || seen.has(value))
+      continue;
+    seen.add(value);
+    out.push(opts.itemMax ? value.slice(0, opts.itemMax) : value);
+    if (out.length >= opts.max)
+      break;
+  }
+  if ((values?.length ?? 0) > opts.max) {
+    out.push(`[truncated ${values.length - opts.max} ${opts.label}]`);
+  }
+  return out;
+}
+function receiptMachine(input, opts) {
+  if (typeof input.machine === "string")
+    return nonEmpty(input.machine, "machine");
+  if (input.machine && typeof input.machine === "object")
+    return input.machine;
+  if (opts.loop?.machine)
+    return { ...opts.loop.machine };
+  if (typeof opts.defaultMachine === "string")
+    return nonEmpty(opts.defaultMachine, "machine");
+  if (opts.defaultMachine && typeof opts.defaultMachine === "object")
+    return opts.defaultMachine;
+  return hostname();
+}
+function normalizeSummary(input, run) {
+  const stdout = input.stdout ?? run?.stdout;
+  const stderr = input.stderr ?? run?.stderr;
+  const output = summarizeOutput(stdout, stderr);
+  const summaryInput = input.summary;
+  const provided = typeof summaryInput === "object" && summaryInput !== null ? summaryInput : {};
+  const text = typeof summaryInput === "string" ? boundedExcerpt(summaryInput, Math.floor(RUN_RECEIPT_SUMMARY_TEXT_CHARS / 2)) : typeof provided.text === "string" ? boundedExcerpt(provided.text, Math.floor(RUN_RECEIPT_SUMMARY_TEXT_CHARS / 2)) : undefined;
+  return {
+    text,
+    stdout_bytes: Number.isFinite(provided.stdout_bytes) ? Number(provided.stdout_bytes) : output.stdoutBytes,
+    stderr_bytes: Number.isFinite(provided.stderr_bytes) ? Number(provided.stderr_bytes) : output.stderrBytes,
+    stdout_excerpt: typeof provided.stdout_excerpt === "string" ? boundedExcerpt(provided.stdout_excerpt) : output.stdoutExcerpt,
+    stderr_excerpt: typeof provided.stderr_excerpt === "string" ? boundedExcerpt(provided.stderr_excerpt) : output.stderrExcerpt,
+    error: typeof provided.error === "string" ? boundedExcerpt(provided.error) : boundedExcerpt(input.error ?? run?.error),
+    duration_ms: Number.isFinite(provided.duration_ms) ? Number(provided.duration_ms) : input.duration_ms ?? run?.durationMs
+  };
+}
+function normalizeRunReceipt(input, opts = {}) {
+  const now = (opts.now ?? new Date).toISOString();
+  const run = opts.run;
+  const loopId = input.loop_id ?? run?.loopId ?? opts.loop?.id;
+  const normalized = {
+    loop_id: nonEmpty(loopId, "loop_id"),
+    run_id: nonEmpty(input.run_id ?? run?.id, "run_id"),
+    machine: receiptMachine(input, opts),
+    repo: nonEmpty(input.repo ?? opts.defaultRepo ?? targetRepo(opts.loop) ?? process.cwd(), "repo"),
+    task_ids: normalizedStringArray(input.task_ids, { max: RUN_RECEIPT_MAX_IDS, label: "task_ids" }),
+    knowledge_ids: normalizedStringArray(input.knowledge_ids, { max: RUN_RECEIPT_MAX_IDS, label: "knowledge_ids" }),
+    started_at: isoOrNull(input.started_at ?? run?.startedAt, "started_at"),
+    finished_at: isoOrNull(input.finished_at ?? run?.finishedAt, "finished_at"),
+    status: nonEmpty(input.status ?? run?.status, "status"),
+    exit_code: input.exit_code === undefined ? run?.exitCode ?? null : input.exit_code,
+    summary: normalizeSummary(input, run),
+    evidence_paths: normalizedStringArray(input.evidence_paths, {
+      max: RUN_RECEIPT_MAX_EVIDENCE_PATHS,
+      label: "evidence_paths",
+      itemMax: RUN_RECEIPT_MAX_PATH_CHARS
+    })
+  };
+  return {
+    ...normalized,
+    digest_id: input.digest_id?.trim() || digestReceipt(normalized),
+    created_at: opts.existing?.created_at ?? now,
+    updated_at: now
+  };
+}
+function targetRepo(loop) {
+  if (!loop)
+    return;
+  if (loop.target.type === "command")
+    return loop.target.cwd;
+  if (loop.target.type === "agent")
+    return loop.target.cwd;
+  return;
+}
+
 // src/lib/route/todos-cli.ts
 import { closeSync, mkdtempSync, openSync, readFileSync as readFileSync3, rmSync as rmSync2 } from "fs";
 import { spawnSync as spawnSync2 } from "child_process";
@@ -1275,6 +1444,9 @@ function publicRun(run, showOutput = false, opts = {}) {
     error: opts.redactError ? redact(run.error) : run.error
   };
 }
+function publicRunReceipt(receipt) {
+  return { ...receipt };
+}
 function publicExecutorResult(result, showOutput = false) {
   return {
     ...result,
@@ -1398,7 +1570,7 @@ function todosMutationSummary(result) {
 var DEFAULT_RECOVERY_BATCH_LIMIT = 100;
 var DEFAULT_RECOVERY_SCAN_MULTIPLIER = 5;
 var LIVE_EXPIRED_RUN_GRACE_MS = 60000;
-var SCHEMA_USER_VERSION = 7;
+var SCHEMA_USER_VERSION = 8;
 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"]);
@@ -1454,6 +1626,25 @@ function rowToRun(row) {
     updatedAt: row.updated_at
   };
 }
+function rowToRunReceipt(row) {
+  return {
+    loop_id: row.loop_id,
+    run_id: row.run_id,
+    machine: JSON.parse(row.machine_json),
+    repo: row.repo,
+    task_ids: JSON.parse(row.task_ids_json),
+    knowledge_ids: JSON.parse(row.knowledge_ids_json),
+    digest_id: row.digest_id,
+    started_at: row.started_at,
+    finished_at: row.finished_at,
+    status: row.status,
+    exit_code: row.exit_code,
+    summary: JSON.parse(row.summary_json),
+    evidence_paths: JSON.parse(row.evidence_paths_json),
+    created_at: row.created_at,
+    updated_at: row.updated_at
+  };
+}
 function latestRunTime(row) {
   return row.finished_at ?? row.started_at ?? row.created_at;
 }
@@ -1517,6 +1708,7 @@ function rowToWorkflowWorkItem(row) {
     subjectRef: row.subject_ref,
     projectKey: row.project_key ?? undefined,
     projectGroup: row.project_group ?? undefined,
+    machineId: row.machine_id ?? undefined,
     routeScope: row.route_scope ?? undefined,
     priority: row.priority,
     status: row.status,
@@ -1674,6 +1866,7 @@ function scrubbedOrNull(value) {
   return value == null ? null : scrubSecrets(value);
 }
 var MAX_PERSISTED_RUN_OUTPUT_CHARS = 64 * 1024;
+var MAX_PERSISTED_WORKFLOW_EVENT_PAYLOAD_CHARS = 64 * 1024;
 function clampPersistedRunOutput(value) {
   if (value == null || value.length <= MAX_PERSISTED_RUN_OUTPUT_CHARS)
     return value;
@@ -1688,6 +1881,42 @@ ${tail}`;
 function persistedRunOutput(value) {
   return clampPersistedRunOutput(scrubbedOrNull(value));
 }
+function clampTextToChars(value, maxChars, reason) {
+  if (value.length <= maxChars)
+    return value;
+  const marker = `
+...[truncated by ${reason}]...
+`;
+  const budget = Math.max(0, maxChars - marker.length);
+  const headLength = Math.ceil(budget / 2);
+  const tailLength = Math.floor(budget / 2);
+  return `${value.slice(0, headLength)}${marker}${value.slice(value.length - tailLength)}`;
+}
+function boundedWorkflowEventPayloadJson(scrubbedJson) {
+  if (scrubbedJson.length <= MAX_PERSISTED_WORKFLOW_EVENT_PAYLOAD_CHARS)
+    return scrubbedJson;
+  const base = {
+    truncated: true,
+    originalChars: scrubbedJson.length,
+    maxChars: MAX_PERSISTED_WORKFLOW_EVENT_PAYLOAD_CHARS,
+    preview: ""
+  };
+  const baseChars = JSON.stringify(base).length;
+  let previewBudget = Math.max(0, MAX_PERSISTED_WORKFLOW_EVENT_PAYLOAD_CHARS - baseChars - 64);
+  while (true) {
+    const preview = clampTextToChars(scrubbedJson, previewBudget, "loops workflow-event payload retention");
+    const bounded = JSON.stringify({ ...base, preview });
+    if (bounded.length <= MAX_PERSISTED_WORKFLOW_EVENT_PAYLOAD_CHARS || previewBudget === 0)
+      return bounded;
+    previewBudget = Math.max(0, previewBudget - (bounded.length - MAX_PERSISTED_WORKFLOW_EVENT_PAYLOAD_CHARS) - 64);
+  }
+}
+function persistedWorkflowEventPayload(payload) {
+  if (payload == null)
+    return null;
+  const scrubbed = scrubSecretsDeep(payload);
+  return boundedWorkflowEventPayloadJson(scrubSecrets(JSON.stringify(scrubbed)));
+}
 function chmodIfExists(path, mode) {
   try {
     if (existsSync(path))
@@ -1805,6 +2034,17 @@ class Store {
           this.addColumnIfMissing("workflow_work_items", "route_scope", "TEXT");
           this.db.exec("CREATE INDEX IF NOT EXISTS idx_workflow_work_items_scope ON workflow_work_items(route_scope, status)");
         }
+      },
+      {
+        id: "0009_run_receipts",
+        apply: () => this.createRunReceiptsSchema()
+      },
+      {
+        id: "0010_work_item_machine_id",
+        apply: () => {
+          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)");
+        }
       }
     ];
   }
@@ -1866,6 +2106,28 @@ class Store {
       CREATE INDEX IF NOT EXISTS idx_runs_status_lease ON loop_runs(status, lease_expires_at);
       CREATE INDEX IF NOT EXISTS idx_runs_scheduled ON loop_runs(scheduled_for);
 
+      CREATE TABLE IF NOT EXISTS run_receipts (
+        run_id TEXT PRIMARY KEY,
+        loop_id TEXT NOT NULL,
+        machine_json TEXT NOT NULL,
+        repo TEXT NOT NULL,
+        task_ids_json TEXT NOT NULL,
+        knowledge_ids_json TEXT NOT NULL,
+        digest_id TEXT NOT NULL,
+        started_at TEXT,
+        finished_at TEXT,
+        status TEXT NOT NULL,
+        exit_code INTEGER,
+        summary_json TEXT NOT NULL,
+        evidence_paths_json TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_run_receipts_loop ON run_receipts(loop_id, created_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_run_receipts_repo ON run_receipts(repo, created_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_run_receipts_digest ON run_receipts(digest_id);
+      CREATE INDEX IF NOT EXISTS idx_run_receipts_status ON run_receipts(status, created_at DESC);
+
       CREATE TABLE IF NOT EXISTS daemon_lease (
         id TEXT PRIMARY KEY,
         pid INTEGER NOT NULL,
@@ -1952,6 +2214,7 @@ class Store {
         subject_ref TEXT NOT NULL,
         project_key TEXT,
         project_group TEXT,
+        machine_id TEXT,
         route_scope TEXT,
         priority INTEGER NOT NULL,
         status TEXT NOT NULL,
@@ -1970,10 +2233,10 @@ class Store {
       CREATE INDEX IF NOT EXISTS idx_workflow_work_items_project ON workflow_work_items(project_key, status);
       CREATE INDEX IF NOT EXISTS idx_workflow_work_items_group ON workflow_work_items(project_group, status);
       CREATE INDEX IF NOT EXISTS idx_workflow_work_items_invocation ON workflow_work_items(invocation_id);
-      -- idx_workflow_work_items_scope (route_scope, status) is created ONLY by
-      -- migration 0008_work_item_route_scope, never here: this baseline DDL
+      -- New-column indexes (route_scope, machine_id, etc.) are created ONLY by
+      -- their additive migrations, never here: this baseline DDL
       -- re-runs on EVERY open (0001 is not skip-guarded), and on a pre-0008
-      -- database the CREATE TABLE above is a no-op, so an index on route_scope
+      -- database the CREATE TABLE above is a no-op, so an index on a new column
       -- here would execute before the column exists and crash the open
       -- ("no such column: route_scope"). New columns may be folded into the
       -- CREATE TABLE (fresh-db only); their indexes must live in the migration.
@@ -2084,6 +2347,31 @@ class Store {
       CREATE INDEX IF NOT EXISTS idx_goal_runs_workflow_run ON goal_runs(workflow_run_id);
     `);
   }
+  createRunReceiptsSchema() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS run_receipts (
+        run_id TEXT PRIMARY KEY,
+        loop_id TEXT NOT NULL,
+        machine_json TEXT NOT NULL,
+        repo TEXT NOT NULL,
+        task_ids_json TEXT NOT NULL,
+        knowledge_ids_json TEXT NOT NULL,
+        digest_id TEXT NOT NULL,
+        started_at TEXT,
+        finished_at TEXT,
+        status TEXT NOT NULL,
+        exit_code INTEGER,
+        summary_json TEXT NOT NULL,
+        evidence_paths_json TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_run_receipts_loop ON run_receipts(loop_id, created_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_run_receipts_repo ON run_receipts(repo, created_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_run_receipts_digest ON run_receipts(digest_id);
+      CREATE INDEX IF NOT EXISTS idx_run_receipts_status ON run_receipts(status, created_at DESC);
+    `);
+  }
   addColumnIfMissing(table, column, definition) {
     const columns = this.db.query(`PRAGMA table_info(${table})`).all();
     if (columns.some((c) => c.name === column))
@@ -2195,19 +2483,24 @@ class Store {
   }
   listLoops(opts = {}) {
     const limit = opts.limit ?? 200;
+    const offset = Math.max(0, Math.floor(opts.offset ?? 0));
+    if (opts.name != null) {
+      const rows2 = this.db.query("SELECT * FROM loops WHERE name = ? ORDER BY created_at DESC LIMIT ? OFFSET ?").all(opts.name, limit, offset);
+      return this.withLatestRunSummaries(rows2.map(rowToLoop));
+    }
     let rows;
     if (opts.status && opts.archived) {
-      rows = this.db.query("SELECT * FROM loops WHERE status = ? AND archived_at IS NOT NULL ORDER BY next_run_at ASC LIMIT ?").all(opts.status, limit);
+      rows = this.db.query("SELECT * FROM loops WHERE status = ? AND archived_at IS NOT NULL ORDER BY next_run_at ASC LIMIT ? OFFSET ?").all(opts.status, limit, offset);
     } else if (opts.status && opts.includeArchived) {
-      rows = this.db.query("SELECT * FROM loops WHERE status = ? ORDER BY next_run_at ASC LIMIT ?").all(opts.status, limit);
+      rows = this.db.query("SELECT * FROM loops WHERE status = ? ORDER BY next_run_at ASC LIMIT ? OFFSET ?").all(opts.status, limit, offset);
     } else if (opts.status) {
-      rows = this.db.query("SELECT * FROM loops WHERE status = ? AND archived_at IS NULL ORDER BY next_run_at ASC LIMIT ?").all(opts.status, limit);
+      rows = this.db.query("SELECT * FROM loops WHERE status = ? AND archived_at IS NULL ORDER BY next_run_at ASC LIMIT ? OFFSET ?").all(opts.status, limit, offset);
     } else if (opts.archived) {
-      rows = this.db.query("SELECT * FROM loops WHERE archived_at IS NOT NULL ORDER BY archived_at DESC LIMIT ?").all(limit);
+      rows = this.db.query("SELECT * FROM loops WHERE archived_at IS NOT NULL ORDER BY archived_at DESC LIMIT ? OFFSET ?").all(limit, offset);
     } else if (opts.includeArchived) {
-      rows = this.db.query("SELECT * FROM loops ORDER BY status ASC, next_run_at ASC LIMIT ?").all(limit);
+      rows = this.db.query("SELECT * FROM loops ORDER BY status ASC, next_run_at ASC LIMIT ? OFFSET ?").all(limit, offset);
     } else {
-      rows = this.db.query("SELECT * FROM loops WHERE archived_at IS NULL ORDER BY status ASC, next_run_at ASC LIMIT ?").all(limit);
+      rows = this.db.query("SELECT * FROM loops WHERE archived_at IS NULL ORDER BY status ASC, next_run_at ASC LIMIT ? OFFSET ?").all(limit, offset);
     }
     return this.withLatestRunSummaries(rows.map(rowToLoop));
   }
@@ -2885,10 +3178,10 @@ class Store {
     const 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, route_scope, priority, status, attempts, next_attempt_at, lease_expires_at,
+          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 ($id, $routeKey, $idempotencyKey, $invocationId, $sourceType, $sourceRef, $subjectRef,
-          $projectKey, $projectGroup, $routeScope, $priority, $status, 0, $nextAttemptAt, NULL, NULL, NULL, NULL,
+          $projectKey, $projectGroup, $machineId, $routeScope, $priority, $status, 0, $nextAttemptAt, NULL, NULL, NULL, NULL,
           $lastReason, $created, $updated)
          ON CONFLICT(route_key, idempotency_key) DO UPDATE SET
           invocation_id=excluded.invocation_id,
@@ -2897,6 +3190,10 @@ class Store {
           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
@@ -2939,6 +3236,7 @@ class Store {
       $subjectRef: input.subjectRef,
       $projectKey: input.projectKey ?? null,
       $projectGroup: input.projectGroup ?? null,
+      $machineId: input.machineId ?? null,
       $routeScope: input.routeScope ?? null,
       $priority: input.priority ?? 0,
       $status: status,
@@ -3448,7 +3746,7 @@ class Store {
            VALUES ($id, $workflowRunId, 1, 'created', NULL, $payload, $created)`).run({
         $id: genId(),
         $workflowRunId: runId,
-        $payload: JSON.stringify({
+        $payload: persistedWorkflowEventPayload({
           workflowId: input.workflow.id,
           workflowName: input.workflow.name,
           stepCount: input.workflow.steps.length,
@@ -3779,7 +4077,7 @@ class Store {
         $sequence: sequence,
         $eventType: eventType,
         $stepId: stepId ?? null,
-        $payload: payload ? JSON.stringify(payload) : null,
+        $payload: persistedWorkflowEventPayload(payload),
         $created: now
       });
       const event = this.db.query("SELECT * FROM workflow_events WHERE id = ?").get(id);
@@ -4102,18 +4400,93 @@ class Store {
   }
   listRuns(opts = {}) {
     const limit = opts.limit ?? 100;
+    const offset = Math.max(0, Math.floor(opts.offset ?? 0));
     let rows;
     if (opts.loopId && opts.status) {
-      rows = this.db.query("SELECT * FROM loop_runs WHERE loop_id = ? AND status = ? ORDER BY created_at DESC LIMIT ?").all(opts.loopId, opts.status, limit);
+      rows = this.db.query("SELECT * FROM loop_runs WHERE loop_id = ? AND status = ? ORDER BY created_at DESC LIMIT ? OFFSET ?").all(opts.loopId, opts.status, limit, offset);
     } else if (opts.loopId) {
-      rows = this.db.query("SELECT * FROM loop_runs WHERE loop_id = ? ORDER BY created_at DESC LIMIT ?").all(opts.loopId, limit);
+      rows = this.db.query("SELECT * FROM loop_runs WHERE loop_id = ? ORDER BY created_at DESC LIMIT ? OFFSET ?").all(opts.loopId, limit, offset);
     } else if (opts.status) {
-      rows = this.db.query("SELECT * FROM loop_runs WHERE status = ? ORDER BY created_at DESC LIMIT ?").all(opts.status, limit);
+      rows = this.db.query("SELECT * FROM loop_runs WHERE status = ? ORDER BY created_at DESC LIMIT ? OFFSET ?").all(opts.status, limit, offset);
     } else {
-      rows = this.db.query("SELECT * FROM loop_runs ORDER BY created_at DESC LIMIT ?").all(limit);
+      rows = this.db.query("SELECT * FROM loop_runs ORDER BY created_at DESC LIMIT ? OFFSET ?").all(limit, offset);
     }
     return rows.map(rowToRun);
   }
+  writeRunReceipt(input, opts = {}) {
+    const inputRunId = typeof input.run_id === "string" && input.run_id.trim() ? input.run_id : undefined;
+    const existing = inputRunId ? this.getRunReceipt(inputRunId) : undefined;
+    const run = inputRunId ? this.getRun(inputRunId) : undefined;
+    const loop = input.loop_id ? this.getLoop(input.loop_id) : run ? this.getLoop(run.loopId) : undefined;
+    const receipt = normalizeRunReceipt(input, { now: opts.now, run, loop, existing });
+    this.db.query(`INSERT INTO run_receipts (run_id, loop_id, machine_json, repo, task_ids_json, knowledge_ids_json, digest_id,
+          started_at, finished_at, status, exit_code, summary_json, evidence_paths_json, created_at, updated_at)
+         VALUES ($runId, $loopId, $machineJson, $repo, $taskIdsJson, $knowledgeIdsJson, $digestId,
+          $startedAt, $finishedAt, $status, $exitCode, $summaryJson, $evidencePathsJson, $createdAt, $updatedAt)
+         ON CONFLICT(run_id) DO UPDATE SET
+          loop_id=excluded.loop_id,
+          machine_json=excluded.machine_json,
+          repo=excluded.repo,
+          task_ids_json=excluded.task_ids_json,
+          knowledge_ids_json=excluded.knowledge_ids_json,
+          digest_id=excluded.digest_id,
+          started_at=excluded.started_at,
+          finished_at=excluded.finished_at,
+          status=excluded.status,
+          exit_code=excluded.exit_code,
+          summary_json=excluded.summary_json,
+          evidence_paths_json=excluded.evidence_paths_json,
+          updated_at=excluded.updated_at`).run({
+      $runId: receipt.run_id,
+      $loopId: receipt.loop_id,
+      $machineJson: JSON.stringify(receipt.machine),
+      $repo: receipt.repo,
+      $taskIdsJson: JSON.stringify(receipt.task_ids),
+      $knowledgeIdsJson: JSON.stringify(receipt.knowledge_ids),
+      $digestId: receipt.digest_id,
+      $startedAt: receipt.started_at,
+      $finishedAt: receipt.finished_at,
+      $status: receipt.status,
+      $exitCode: receipt.exit_code,
+      $summaryJson: JSON.stringify(receipt.summary),
+      $evidencePathsJson: JSON.stringify(receipt.evidence_paths),
+      $createdAt: receipt.created_at,
+      $updatedAt: receipt.updated_at
+    });
+    return this.getRunReceipt(receipt.run_id) ?? receipt;
+  }
+  getRunReceipt(runId) {
+    const row = this.db.query("SELECT * FROM run_receipts WHERE run_id = ?").get(runId);
+    return row ? rowToRunReceipt(row) : undefined;
+  }
+  listRunReceipts(opts = {}) {
+    const limit = opts.limit ?? 100;
+    const filters = [];
+    const params = [];
+    if (opts.loopId) {
+      filters.push("loop_id = ?");
+      params.push(opts.loopId);
+    }
+    if (opts.repo) {
+      filters.push("repo = ?");
+      params.push(opts.repo);
+    }
+    if (opts.status) {
+      filters.push("status = ?");
+      params.push(opts.status);
+    }
+    if (opts.taskId) {
+      filters.push("EXISTS (SELECT 1 FROM json_each(run_receipts.task_ids_json) WHERE value = ?)");
+      params.push(opts.taskId);
+    }
+    if (opts.knowledgeId) {
+      filters.push("EXISTS (SELECT 1 FROM json_each(run_receipts.knowledge_ids_json) WHERE value = ?)");
+      params.push(opts.knowledgeId);
+    }
+    const where = filters.length ? `WHERE ${filters.join(" AND ")}` : "";
+    const rows = this.db.query(`SELECT * FROM run_receipts ${where} ORDER BY created_at DESC LIMIT ?`).all(...params, limit);
+    return rows.map(rowToRunReceipt);
+  }
   deferLiveExpiredRun(id, now, opts = {}) {
     const updated = now.toISOString();
     const deferredUntil = new Date(now.getTime() + LIVE_EXPIRED_RUN_GRACE_MS).toISOString();
@@ -4272,6 +4645,9 @@ class Store {
     const runs = includeRuns ? this.db.query("SELECT * FROM loop_runs ORDER BY created_at ASC, id ASC").all().map(rowToRun) : [];
     return { schemaVersion: SCHEMA_USER_VERSION, workflows, loops, runs, checks: this.migrationChecks() };
   }
+  exportMigrationRunPage(opts) {
+    return this.db.query("SELECT * FROM loop_runs ORDER BY created_at ASC, id ASC LIMIT ? OFFSET ?").all(opts.limit, opts.offset).map(rowToRun);
+  }
   countTable(table) {
     const row = this.db.query(`SELECT COUNT(*) AS count FROM ${table}`).get();
     return row?.count ?? 0;
@@ -4599,11 +4975,11 @@ import { Command } from "commander";
 
 // src/daemon/daemon.ts
 import { copyFileSync, existsSync as existsSync5, openSync as openSync2, renameSync as renameSync2, rmSync as rmSync5, statSync, truncateSync } from "fs";
-import { hostname as hostname2 } from "os";
+import { hostname as hostname3 } from "os";
 import { spawn as spawn3 } from "child_process";
 
 // src/lib/health.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 import { existsSync as existsSync2, mkdirSync as mkdirSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
 import { join as join5 } from "path";
 var EVIDENCE_CHARS = 2000;
@@ -4665,7 +5041,7 @@ function tagsFromValue(value) {
   return [];
 }
 function stableFingerprint(parts) {
-  return createHash2("sha256").update(parts.join(`
+  return createHash3("sha256").update(parts.join(`
 `)).digest("hex").slice(0, 16);
 }
 function stableScanFingerprint(parts) {
@@ -5728,6 +6104,7 @@ var TRANSPORT_ENV_KEYS = new Set([
   "LOGNAME",
   "PATH",
   "SHELL",
+  "SHLVL",
   "SSH_AGENT_PID",
   "SSH_AUTH_SOCK",
   "TERM",
@@ -5949,6 +6326,7 @@ function composeExecutionEnv(spec, metadata, opts, accountEnv) {
   Object.assign(env, spec.env ?? {});
   Object.assign(env, allowlistEnv(spec.allowlist));
   env.PATH = normalizeExecutionPath(env);
+  env.SHLVL ||= "1";
   Object.assign(env, metadataEnv(metadata));
   return env;
 }
@@ -6020,7 +6398,7 @@ function remoteWorktreePrepareLines(worktree) {
   return [
     "__openloops_prepare_worktree() {",
     `  local repo=${shellQuote(repoRoot)} path=${shellQuote(path)} branch=${shellQuote(branch)}`,
-    "  local top expected_common actual_common current",
+    "  local top expected_common actual_common current status recovered",
     '  if [ -L "$path" ]; then echo "refusing symlinked worktree path $path" >&2; return 1; fi',
     '  if [ -e "$path" ]; then',
     '    top="$(git -C "$path" rev-parse --show-toplevel 2>/dev/null)" || { echo "refusing to reuse non-worktree path: $path" >&2; return 1; }',
@@ -6029,7 +6407,19 @@ function remoteWorktreePrepareLines(worktree) {
     '    actual_common="$(cd "$path" 2>/dev/null && cd "$(git rev-parse --git-common-dir 2>/dev/null)" 2>/dev/null && pwd -P)"',
     '    if [ -z "$expected_common" ] || [ "$expected_common" != "$actual_common" ]; then echo "existing worktree $path belongs to a different git common dir" >&2; return 1; fi',
     '    current="$(git -C "$path" branch --show-current 2>/dev/null)"',
-    '    if [ "$current" != "$branch" ]; then echo "existing worktree $path is on branch ${current:-unknown}, expected $branch" >&2; return 1; fi',
+    '    if [ "$current" != "$branch" ]; then',
+    '      status="$(git -C "$path" status --porcelain=v1 --untracked-files=all 2>/dev/null)" || { echo "existing worktree $path is on branch ${current:-unknown}, expected $branch, and cleanliness could not be checked; inspect or remove the stale worktree" >&2; return 1; }',
+    '      if [ -n "$status" ]; then echo "existing worktree $path is on branch ${current:-unknown}, expected $branch, and has local changes; commit/stash them or remove the stale worktree before retrying" >&2; return 1; fi',
+    '      if git -C "$repo" show-ref --verify --quiet "refs/heads/$branch"; then',
+    '        git -C "$path" checkout "$branch" 1>&2 || { echo "existing worktree $path is clean but could not switch from branch ${current:-unknown} to expected $branch; remove/prune the stale worktree or free the branch before retrying" >&2; return 1; }',
+    '      elif [ -z "$current" ]; then',
+    '        git -C "$path" checkout -b "$branch" 1>&2 || { echo "existing worktree $path is clean but could not recreate expected branch $branch at the current detached HEAD; remove/prune the stale worktree before retrying" >&2; return 1; }',
+    "      else",
+    '        echo "existing worktree $path is on branch $current, expected $branch, but expected branch does not exist; remove/prune the stale worktree or recreate the expected branch before retrying" >&2; return 1',
+    "      fi",
+    '      recovered="$(git -C "$path" branch --show-current 2>/dev/null)"',
+    '      if [ "$recovered" != "$branch" ]; then echo "existing worktree $path branch recovery ended on ${recovered:-unknown}, expected $branch; remove/prune the stale worktree before retrying" >&2; return 1; fi',
+    "    fi",
     "    return 0",
     "  fi",
     '  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; }',
@@ -6110,8 +6500,21 @@ function transportEnv(opts) {
       env[key] = value;
   }
   env.PATH = normalizeExecutionPath(env);
+  env.SHLVL ||= "1";
   return env;
 }
+function remotePreflightFailureMessage(machineId, detail) {
+  const normalized = detail.trim();
+  if (/Host key verification failed|REMOTE HOST IDENTIFICATION HAS CHANGED|Offending .*key in .*known_hosts/i.test(normalized)) {
+    return [
+      `remote preflight failed on ${machineId}: SSH host key verification failed.`,
+      `Verify ${machineId}'s host identity and repair SSH known_hosts/trust material outside OpenLoops;`,
+      "OpenLoops will not disable host-key checking or modify known_hosts automatically.",
+      normalized ? `Transport detail: ${normalized}` : ""
+    ].filter(Boolean).join(" ");
+  }
+  return `remote preflight failed on ${machineId}${normalized ? `: ${normalized}` : ""}`;
+}
 function assertCodewithProfileListed(profile, result) {
   const profiles = codewithProfileSetFromResult(result);
   if (!profiles.has(profile)) {
@@ -6163,6 +6566,9 @@ async function preflightNativeAuthProfile(spec, env) {
   const tableResult = await spawnCapture(spec.command, ["profile", "list"], { env, timeoutMs: 15000 });
   assertCodewithProfileListed(spec.nativeAuthProfile.profile, tableResult);
 }
+function spawnDetail(result) {
+  return (result.stderr || result.stdout || result.error || "").toString().trim();
+}
 function resolvedDirEquals(left, right) {
   try {
     return realpathSync(left) === realpathSync(right);
@@ -6212,8 +6618,45 @@ async function ensureLocalWorktree(worktree, env) {
     }
     const current = await git(["-C", path, "branch", "--show-current"]);
     const actualBranch = current.stdout.trim();
-    if (current.error || (current.status ?? 1) !== 0 || actualBranch !== branch) {
-      return { error: `existing worktree ${path} is on branch ${actualBranch || "unknown"}, expected ${branch}` };
+    if (current.error || (current.status ?? 1) !== 0) {
+      return { error: `existing worktree ${path} branch could not be inspected${spawnDetail(current) ? `: ${spawnDetail(current)}` : ""}` };
+    }
+    if (actualBranch !== branch) {
+      const actualLabel = actualBranch || "unknown";
+      const status = await git(["-C", path, "status", "--porcelain=v1", "--untracked-files=all"]);
+      if (status.error || (status.status ?? 1) !== 0) {
+        const detail = spawnDetail(status);
+        return {
+          error: `existing worktree ${path} is on branch ${actualLabel}, expected ${branch}, and cleanliness could not be checked; inspect or remove the stale worktree${detail ? `: ${detail}` : ""}`
+        };
+      }
+      if (status.stdout.trim()) {
+        return {
+          error: `existing worktree ${path} is on branch ${actualLabel}, expected ${branch}, and has local changes; commit/stash them or remove the stale worktree before retrying`
+        };
+      }
+      const hasBranch2 = await git(["-C", repoRoot, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`]);
+      const checkout = hasBranch2.status === 0 ? await git(["-C", path, "checkout", branch]) : actualBranch ? {
+        status: 1,
+        stdout: "",
+        stderr: `existing worktree ${path} is on branch ${actualLabel}, expected ${branch}, but expected branch does not exist; remove/prune the stale worktree or recreate the expected branch before retrying`,
+        signal: null,
+        timedOut: false
+      } : await git(["-C", path, "checkout", "-b", branch]);
+      if (checkout.error || (checkout.status ?? 1) !== 0) {
+        const detail = spawnDetail(checkout);
+        return {
+          error: `existing worktree ${path} is clean but could not recover branch ${branch} from ${actualLabel}; remove/prune the stale worktree before retrying${detail ? `: ${detail}` : ""}`
+        };
+      }
+      const recovered = await git(["-C", path, "branch", "--show-current"]);
+      if (recovered.error || (recovered.status ?? 1) !== 0 || recovered.stdout.trim() !== branch) {
+        const recoveredBranch = recovered.stdout.trim() || "unknown";
+        const detail = spawnDetail(recovered);
+        return {
+          error: `existing worktree ${path} branch recovery ended on ${recoveredBranch}, expected ${branch}; remove/prune the stale worktree before retrying${detail ? `: ${detail}` : ""}`
+        };
+      }
     }
     return { cwd: worktree.cwd };
   }
@@ -6229,7 +6672,7 @@ async function ensureLocalWorktree(worktree, env) {
   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"]);
   if (add.error || (add.status ?? 1) !== 0) {
-    const detail = (add.stderr || add.stdout || add.error || "").toString().trim();
+    const detail = spawnDetail(add);
     return { error: `git worktree add failed for ${path}${detail ? `: ${detail}` : ""}` };
   }
   return { cwd: worktree.cwd };
@@ -6275,7 +6718,7 @@ function preflightRemoteSpec(spec, machine, metadata, opts) {
     throw new Error(`remote preflight failed on ${machine.id}: ${result.error.message}`);
   if ((result.status ?? 1) !== 0) {
     const detail = (result.stderr || result.stdout || `exit ${result.status ?? "unknown"}`).trim();
-    throw new Error(`remote preflight failed on ${machine.id}${detail ? `: ${detail}` : ""}`);
+    throw new Error(remotePreflightFailureMessage(machine.id, detail));
   }
 }
 async function executeRemoteSpec(spec, machine, metadata, opts, fallbackSpec) {
@@ -6619,55 +7062,6 @@ ${evidence.join(`
 import { generateObject } from "ai";
 import { z } from "zod";
 
-// src/lib/run-envelope.ts
-var ENVELOPE_EXCERPT_CHARS = 2048;
-var BLOCKED_STEP_ERROR_PREFIX = "blocked:";
-function boundedExcerpt(text, limit = ENVELOPE_EXCERPT_CHARS) {
-  if (!text)
-    return;
-  const scrubbed = scrubSecrets(text);
-  if (scrubbed.length <= limit * 2)
-    return scrubbed;
-  const omitted = scrubbed.length - limit * 2;
-  return `${scrubbed.slice(0, limit)}
-[... ${omitted} chars omitted ...]
-${scrubbed.slice(-limit)}`;
-}
-function summarizeOutput(stdout, stderr) {
-  return {
-    stdoutBytes: stdout ? Buffer.byteLength(stdout, "utf8") : 0,
-    stderrBytes: stderr ? Buffer.byteLength(stderr, "utf8") : 0,
-    stdoutExcerpt: boundedExcerpt(stdout),
-    stderrExcerpt: boundedExcerpt(stderr)
-  };
-}
-function summarizeExecutorResult(result) {
-  return {
-    ...summarizeOutput(result.stdout, result.stderr),
-    status: result.status,
-    exitCode: result.exitCode,
-    durationMs: result.durationMs,
-    error: boundedExcerpt(result.error)
-  };
-}
-function isBlockedStepRun(step) {
-  return step?.status === "skipped" && (step.error?.startsWith(BLOCKED_STEP_ERROR_PREFIX) ?? false);
-}
-function summarizeWorkflowStepRun(step) {
-  return {
-    ...summarizeOutput(step.stdout, step.stderr),
-    stepId: step.stepId,
-    status: step.status,
-    exitCode: step.exitCode,
-    durationMs: step.durationMs,
-    error: boundedExcerpt(step.error),
-    blocked: isBlockedStepRun(step)
-  };
-}
-function workflowRunEnvelope(run, steps) {
-  return JSON.stringify({ workflowRun: run, steps: steps.map(summarizeWorkflowStepRun) }, null, 2);
-}
-
 // src/lib/goal/model-factory.ts
 import { createOpenRouter } from "@openrouter/ai-sdk-provider";
 var DEFAULT_GOAL_MODEL = "openai/gpt-4o-mini";
@@ -7910,7 +8304,7 @@ async function tick(deps) {
 // src/daemon/control.ts
 import { existsSync as existsSync4, mkdirSync as mkdirSync6, readFileSync as readFileSync5, rmSync as rmSync4, writeFileSync as writeFileSync3 } from "fs";
 import { spawnSync as spawnSync5 } from "child_process";
-import { hostname } from "os";
+import { hostname as hostname2 } from "os";
 import { dirname as dirname4, join as join7 } from "path";
 
 // src/daemon/loop.ts
@@ -8063,7 +8457,7 @@ function daemonStatus(store, path = pidFilePath()) {
   return {
     ...isDaemonRunning(path),
     lease: store.getDaemonLease(),
-    host: hostname(),
+    host: hostname2(),
     loops: {
       total: store.countLoops(),
       active: store.countLoops("active"),
@@ -8197,7 +8591,7 @@ async function runDaemon(opts = {}) {
   const ownStore = !opts.store;
   const store = opts.store ?? new Store;
   const leaseId = genId();
-  const runnerId = `${hostname2()}:${process.pid}:${leaseId}`;
+  const runnerId = `${hostname3()}:${process.pid}:${leaseId}`;
   const intervalMs = opts.intervalMs ?? intervalFromEnv() ?? 1000;
   const leaseTtlMs = opts.leaseTtlMs ?? Math.max(60000, intervalMs * 10);
   const laneConcurrency = resolveLaneConcurrency(opts);
@@ -8206,7 +8600,7 @@ async function runDaemon(opts = {}) {
   const lease = store.acquireDaemonLease({
     id: leaseId,
     pid: process.pid,
-    hostname: hostname2(),
+    hostname: hostname3(),
     ttlMs: leaseTtlMs
   });
   if (!lease)
@@ -8241,7 +8635,7 @@ async function runDaemon(opts = {}) {
       reacquired = store.acquireDaemonLease({
         id: leaseId,
         pid: process.pid,
-        hostname: hostname2(),
+        hostname: hostname3(),
         ttlMs: leaseTtlMs
       });
     } catch {
@@ -8540,7 +8934,7 @@ function enableStartup(result) {
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.4.14",
+  version: "0.4.22",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",
@@ -8650,7 +9044,6 @@ var package_default = {
     bun: ">=1.0.0"
   },
   dependencies: {
-    "@hasna/contracts": "^0.4.1",
     "@hasna/events": "^0.1.9",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@openrouter/ai-sdk-provider": "2.9.1",
@@ -8660,7 +9053,8 @@ var package_default = {
     zod: "4.4.3"
   },
   optionalDependencies: {
-    "@hasna/machines": "0.0.49"
+    "@hasna/machines": "0.0.49",
+    "@hasna/contracts": "^0.4.2"
   },
   devDependencies: {
     "@types/bun": "latest",