aiden-runtime 4.8.1 → 4.9.1

package/dist/core/v4/daemon/idempotency/runIdempotencyStore.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/idempotency/runIdempotencyStore.ts — v4.9.0 Slice 5.
+ *
+ * Durable ingress / write-side idempotency. Distinct from the v1
+ * `idempotency_keys` response-replay cache (which stores HTTP response
+ * bodies for exact-byte replay). This store tracks (namespace, key) →
+ * acceptance outcome so a duplicate webhook / email / file / API
+ * request never creates a second `runs` row.
+ *
+ * `acquire()` is the central primitive: atomic insert against the
+ * (namespace, key) PK. Three outcomes:
+ *
+ *   - 'accepted'           — fresh row inserted, caller proceeds with
+ *                            run/trigger creation.
+ *   - 'duplicate'          — row exists with the SAME fingerprint;
+ *                            caller should reuse the linked run/event id.
+ *   - 'rejected_conflict'  — row exists with a DIFFERENT fingerprint;
+ *                            caller is reusing a key for different work
+ *                            and should reject with a loud error.
+ *
+ * Call `link()` after the run/trigger row exists to back-fill the FKs.
+ * `complete()` patches the final result_ref (e.g. span_id of the
+ * outcome). `sweepExpired()` is the GC tick for keys with `expires_at`
+ * in the past.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fingerprintCanonical = fingerprintCanonical;
+exports.acquire = acquire;
+exports.link = link;
+exports.complete = complete;
+exports.sweepExpired = sweepExpired;
+exports.getKey = getKey;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Canonical fingerprint helper — sort keys, stringify, SHA-256 hex.
+ * Drops `undefined` values to keep the hash stable across optional
+ * fields. Use this when the caller doesn't already have a domain-
+ * specific hash (e.g. webhook deliveries already compute one in
+ * `webhookIdempotency.ts`).
+ */
+function fingerprintCanonical(payload) {
+    const canon = canonicalise(payload);
+    return (0, node_crypto_1.createHash)('sha256').update(JSON.stringify(canon)).digest('hex');
+}
+function canonicalise(v) {
+    if (v === null || v === undefined)
+        return null;
+    if (Array.isArray(v))
+        return v.map(canonicalise);
+    if (typeof v === 'object') {
+        const out = {};
+        for (const k of Object.keys(v).sort()) {
+            const val = v[k];
+            if (val !== undefined)
+                out[k] = canonicalise(val);
+        }
+        return out;
+    }
+    return v;
+}
+/**
+ * Attempt to claim (namespace, key) for an incoming request. Atomic
+ * via INSERT OR IGNORE against the (namespace, key) PK + a follow-up
+ * SELECT for the existing row.
+ */
+function acquire(db, opts) {
+    const nowMs = (opts.now ?? Date.now)();
+    const nowIso = new Date(nowMs).toISOString();
+    const expires = opts.ttlMs ? new Date(nowMs + opts.ttlMs).toISOString() : null;
+    const result = db.prepare(`INSERT OR IGNORE INTO run_idempotency_keys
+       (namespace, key, fingerprint, status, created_at, expires_at)
+     VALUES (?, ?, ?, 'accepted', ?, ?)`).run(opts.namespace, opts.key, opts.fingerprint, nowIso, expires);
+    if (result.changes > 0) {
+        const row = readRow(db, opts.namespace, opts.key);
+        return { outcome: 'accepted', row };
+    }
+    // Collision — read existing and compare fingerprint.
+    const existing = readRow(db, opts.namespace, opts.key);
+    if (!existing) {
+        // Defensive: should not happen, the INSERT OR IGNORE only skips
+        // when the PK conflicts.
+        throw new Error('runIdempotencyStore.acquire: INSERT OR IGNORE skipped but no row found');
+    }
+    if (existing.fingerprint === opts.fingerprint) {
+        return { outcome: 'duplicate', existing };
+    }
+    return { outcome: 'rejected_conflict', existing };
+}
+/** Back-fill the run/trigger/span FKs once those rows exist. */
+function link(db, opts) {
+    db.prepare(`UPDATE run_idempotency_keys
+        SET run_id           = COALESCE(?, run_id),
+            trigger_event_id = COALESCE(?, trigger_event_id),
+            span_id          = COALESCE(?, span_id)
+      WHERE namespace = ? AND key = ?`).run(opts.runId ?? null, opts.triggerEventId ?? null, opts.spanId ?? null, opts.namespace, opts.key);
+}
+/**
+ * Patch the terminal status + optional result_ref. Caller picks the
+ * status: `'completed'` for success, `'failed'` for terminal failure.
+ */
+function complete(db, opts) {
+    db.prepare(`UPDATE run_idempotency_keys
+        SET status     = ?,
+            result_ref = COALESCE(?, result_ref)
+      WHERE namespace = ? AND key = ?`).run(opts.status, opts.resultRef ?? null, opts.namespace, opts.key);
+}
+/** Delete keys whose `expires_at` is in the past. Returns the count. */
+function sweepExpired(db, now) {
+    const nowIso = new Date(now ?? Date.now()).toISOString();
+    const r = db.prepare(`DELETE FROM run_idempotency_keys
+       WHERE expires_at IS NOT NULL AND expires_at < ?`).run(nowIso);
+    return { deleted: Number(r.changes ?? 0) };
+}
+/** Diagnostic — single-key lookup. */
+function getKey(db, namespace, key) {
+    return readRow(db, namespace, key);
+}
+function readRow(db, namespace, key) {
+    const r = db.prepare(`SELECT * FROM run_idempotency_keys WHERE namespace = ? AND key = ?`).get(namespace, key);
+    return r ?? null;
+}

package/dist/core/v4/daemon/incarnationStore.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/incarnationStore.ts — v4.9.0 Slice 4.
+ *
+ * Thin DDL wrapper around the `daemon_incarnations` table (schema v8).
+ * Three operations:
+ *
+ *   1. `insertIncarnation()` — boot. Writes one row with `started_at`
+ *      = now ISO. Idempotent on PRIMARY KEY collision (safe re-call).
+ *   2. `markEnded()` — clean shutdown. Patches `ended_at`, `exit_reason`,
+ *      `exit_code` for this incarnation. No-op when the row is missing
+ *      (defensive — e.g. SQLite died before insert).
+ *   3. `lastForDaemon()` — diagnostic. Returns the most recent row for
+ *      a given daemon_id. Used by `aiden doctor`-style surfaces (not
+ *      wired in this slice).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.insertIncarnation = insertIncarnation;
+exports.markEnded = markEnded;
+exports.lastForDaemon = lastForDaemon;
+function insertIncarnation(db, opts) {
+    const started = opts.startedAt ?? new Date().toISOString();
+    db.prepare(`INSERT OR IGNORE INTO daemon_incarnations
+       (incarnation_id, daemon_id, pid, started_at, aiden_version, node_version)
+     VALUES (?, ?, ?, ?, ?, ?)`).run(opts.incarnationId, opts.daemonId, opts.pid, started, opts.aidenVersion, opts.nodeVersion);
+}
+function markEnded(db, opts) {
+    const ended = opts.endedAt ?? new Date().toISOString();
+    db.prepare(`UPDATE daemon_incarnations
+        SET ended_at    = COALESCE(ended_at, ?),
+            exit_reason = COALESCE(exit_reason, ?),
+            exit_code   = COALESCE(exit_code, ?)
+      WHERE incarnation_id = ?`).run(ended, opts.exitReason, opts.exitCode, opts.incarnationId);
+}
+function lastForDaemon(db, daemonId) {
+    const r = db.prepare(`SELECT * FROM daemon_incarnations
+      WHERE daemon_id = ?
+      ORDER BY started_at DESC
+      LIMIT 1`).get(daemonId);
+    return r ?? null;
+}

package/dist/core/v4/daemon/runs/attemptStore.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/runs/attemptStore.ts — v4.9.0 Slice 5.
+ *
+ * One row per execution attempt of a run. `runs.id` (numeric, autoincrement)
+ * stays the canonical run identifier; `run_attempts.attempt_id`
+ * (`att_<uuidv7>`) is the per-try identifier. attempt_number is 1-indexed
+ * and stable per (run_id) — the store computes it via MAX+1 on insert.
+ *
+ * Slice 5 lands schema + writers. Retry-policy logic (which attempts
+ * get retried, with what cooldown) is deferred to Slice 6+.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAttempt = createAttempt;
+exports.completeAttempt = completeAttempt;
+exports.listAttemptsForRun = listAttemptsForRun;
+exports.getAttempt = getAttempt;
+const identity_1 = require("../../identity");
+/**
+ * Create a fresh attempt for the given run. `attempt_number` is derived
+ * by MAX+1 inside a transaction so concurrent creators don't collide.
+ * Returns the new attempt id.
+ */
+function createAttempt(db, opts) {
+    const attemptId = opts.attemptId ?? (0, identity_1.newAttemptId)();
+    const startedAt = opts.startedAt ?? new Date().toISOString();
+    const tx = db.transaction(() => {
+        const row = db.prepare(`SELECT COALESCE(MAX(attempt_number), 0) AS n FROM run_attempts WHERE run_id = ?`).get(opts.runId);
+        const nextNumber = row.n + 1;
+        db.prepare(`INSERT INTO run_attempts
+         (attempt_id, run_id, attempt_number, incarnation_id, started_at, status)
+       VALUES (?, ?, ?, ?, ?, 'running')`).run(attemptId, opts.runId, nextNumber, opts.incarnationId, startedAt);
+    });
+    tx();
+    return attemptId;
+}
+/**
+ * Patch an attempt with a terminal status. COALESCE-protected so the
+ * first-wins semantics match the Slice 4 incarnation pattern: if the
+ * attempt already has an `ended_at`, this call is a no-op for those
+ * fields (status update only applies to the in-flight case).
+ */
+function completeAttempt(db, opts) {
+    const endedAt = opts.endedAt ?? new Date().toISOString();
+    db.prepare(`UPDATE run_attempts
+        SET status        = ?,
+            ended_at      = COALESCE(ended_at, ?),
+            finish_reason = COALESCE(finish_reason, ?),
+            error_class   = COALESCE(error_class, ?),
+            error_message = COALESCE(error_message, ?)
+      WHERE attempt_id = ?`).run(opts.status, endedAt, opts.finishReason ?? null, opts.errorClass ?? null, opts.errorMessage ?? null, opts.attemptId);
+}
+/** List all attempts for a run in attempt-number order. */
+function listAttemptsForRun(db, runId) {
+    return db.prepare(`SELECT * FROM run_attempts WHERE run_id = ? ORDER BY attempt_number ASC`).all(runId);
+}
+/** Diagnostic — single-attempt lookup. */
+function getAttempt(db, attemptId) {
+    const r = db.prepare(`SELECT * FROM run_attempts WHERE attempt_id = ?`).get(attemptId);
+    return r ?? null;
+}

package/dist/core/v4/daemon/runs/reclaim.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/runs/reclaim.ts — v4.9.0 Slice 3.
+ *
+ * Mark runs orphaned by a crashed daemon as `interrupted` so a follow-up
+ * boot (or a human looking at `aiden runs list`) sees an unambiguous
+ * post-mortem instead of an eternally-`running` row.
+ *
+ * Called from two sites:
+ *  1. Process-wide crash handlers (`uncaughtException` /
+ *     `unhandledRejection`) installed in `bootstrap.ts`. Before the
+ *     handler calls `process.exit(1)`, it reclaims this incarnation's
+ *     still-running rows. The DB connection is the same handle the
+ *     dispatcher used; the write is one statement so even a crashed
+ *     process can finish it.
+ *  2. Boot-time, against ANY non-current instance — defence in depth
+ *     for the case where `evaluateBootState` didn't sweep a row (e.g.
+ *     the prior crash happened after BootState ran but before the
+ *     run completed). Idempotent: a no-op when no rows match.
+ *
+ * Uses existing schema columns only — NO new tables, NO new RunStatus
+ * value. Sets `status='interrupted', finish_reason='daemon_crashed',
+ * resume_pending=1, resume_reason='daemon_crashed', completed_at=now`.
+ * Matches the semantics `evaluateBootState` uses for prior-instance
+ * crash recovery, so downstream consumers (`aiden runs list`, restart
+ * resume logic) see one consistent shape.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reclaimStuckRuns = reclaimStuckRuns;
+/**
+ * Reclaim stuck `runs.status='running'` rows. Returns the rows touched
+ * so the caller can emit `run_events` entries (skipped on the crash
+ * path — the inserts could themselves throw, and the UPDATE is the
+ * authoritative outcome).
+ */
+function reclaimStuckRuns(db, opts) {
+    const now = (opts.now ?? Date.now)();
+    // Phase 1 — select the candidate rows. We pull ids first so the
+    // caller can act on them (logging, event emission) without a second
+    // round-trip. Using a single WHERE clause keeps the index hit on
+    // idx_runs_active (`status IN ('queued','running')`).
+    let candidates;
+    if (opts.instanceId !== undefined) {
+        candidates = db.prepare(`SELECT id FROM runs WHERE status = 'running' AND instance_id = ?`).all(opts.instanceId);
+    }
+    else {
+        if (!opts.currentInstanceId) {
+            throw new Error('reclaimStuckRuns: currentInstanceId required when instanceId omitted');
+        }
+        candidates = db.prepare(`SELECT id FROM runs WHERE status = 'running' AND instance_id != ?`).all(opts.currentInstanceId);
+    }
+    if (candidates.length === 0) {
+        return { reclaimed: 0, runIds: [] };
+    }
+    // Phase 2 — single UPDATE for the matching predicate. We re-derive
+    // the WHERE from `opts` rather than passing ids inline (would blow
+    // past SQLite's bound-parameter cap on a pathologically large run
+    // table — unlikely, but cheap to avoid).
+    let updateResult;
+    if (opts.instanceId !== undefined) {
+        updateResult = db.prepare(`UPDATE runs
+          SET status         = 'interrupted',
+              finish_reason  = 'daemon_crashed',
+              completed_at   = ?,
+              resume_pending = 1,
+              resume_reason  = 'daemon_crashed'
+        WHERE status = 'running' AND instance_id = ?`).run(now, opts.instanceId);
+    }
+    else {
+        updateResult = db.prepare(`UPDATE runs
+          SET status         = 'interrupted',
+              finish_reason  = 'daemon_crashed',
+              completed_at   = ?,
+              resume_pending = 1,
+              resume_reason  = 'daemon_crashed'
+        WHERE status = 'running' AND instance_id != ?`).run(now, opts.currentInstanceId);
+    }
+    return {
+        reclaimed: Number(updateResult.changes ?? candidates.length),
+        runIds: candidates.map((c) => c.id),
+    };
+}

package/dist/core/v4/daemon/runs/retryPolicy.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/runs/retryPolicy.ts — v4.9.0 Slice 8.
+ *
+ * Pure policy primitives — `shouldRetry` + `computeBackoffMs`. The
+ * orchestrator (`runWithRetry`) lives next door; this module is
+ * test-friendly with no side effects.
+ *
+ * Defaults chosen to match the implicit policy across the rest of
+ * v4: max 3 attempts, exponential backoff with full jitter capped
+ * at 30s. NetworkError / TimeoutError / ResourceExhausted are
+ * retryable; auth + permission + validation are terminal.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RETRY_POLICY = void 0;
+exports.shouldRetry = shouldRetry;
+exports.computeBackoffMs = computeBackoffMs;
+exports.DEFAULT_RETRY_POLICY = {
+    maxAttempts: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 30000,
+    jitter: 'full',
+    retryableErrorClasses: ['NetworkError', 'TimeoutError', 'ResourceExhausted'],
+    nonRetryableErrorClasses: ['AuthError', 'PermissionDenied', 'ValidationError'],
+};
+/**
+ * Decide whether to retry given the error class + attempt number.
+ *
+ * Precedence:
+ *   1. attemptNumber >= maxAttempts  → false (cap reached)
+ *   2. nonRetryableErrorClasses hit  → false (terminal)
+ *   3. retryableErrorClasses hit     → true
+ *   4. unknown error class           → false (fail closed)
+ *
+ * Treating unknown errors as non-retryable matches Aiden's safety
+ * stance: a retry burst on an unknown failure can multiply damage.
+ */
+function shouldRetry(errorClass, attemptNumber, policy = exports.DEFAULT_RETRY_POLICY) {
+    if (attemptNumber >= policy.maxAttempts)
+        return false;
+    if (policy.nonRetryableErrorClasses.includes(errorClass))
+        return false;
+    if (policy.retryableErrorClasses.includes(errorClass))
+        return true;
+    return false;
+}
+/**
+ * Exponential backoff with optional jitter, capped at `maxDelayMs`.
+ *   attemptNumber=1 → base
+ *   attemptNumber=2 → base*2
+ *   attemptNumber=3 → base*4
+ * Jitter modes:
+ *   'none'  — exact value
+ *   'equal' — value/2 + random(0..value/2)
+ *   'full'  — random(0..value)
+ */
+function computeBackoffMs(attemptNumber, policy = exports.DEFAULT_RETRY_POLICY, rng = Math.random) {
+    if (attemptNumber < 1)
+        return 0;
+    const exp = policy.baseDelayMs * Math.pow(2, attemptNumber - 1);
+    const capped = Math.min(exp, policy.maxDelayMs);
+    switch (policy.jitter) {
+        case 'none': return capped;
+        case 'equal': return Math.floor(capped / 2 + rng() * (capped / 2));
+        case 'full': return Math.floor(rng() * capped);
+    }
+}

package/dist/core/v4/daemon/runs/runWithRetry.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/runs/runWithRetry.ts — v4.9.0 Slice 8.
+ *
+ * Attempt orchestration on top of Slice 5's `run_attempts` table.
+ * Caller supplies an existing run row id + a `RetryPolicy`; this
+ * function creates one `run_attempts` row per attempt, runs `fn`
+ * inside an incrementing-attempt context, and on retryable error
+ * sleeps + tries again. On non-retryable error OR max-attempts cap,
+ * returns `'dead_letter'` so the caller can route to a poison queue.
+ *
+ * The "what's retryable" decision lives in `retryPolicy.ts` so the
+ * orchestrator stays small + testable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWithRetry = runWithRetry;
+const attemptStore_1 = require("./attemptStore");
+const retryPolicy_1 = require("./retryPolicy");
+function defaultSleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/**
+ * Run `fn` with retry policy. Each attempt gets its own `run_attempts`
+ * row + an incremented `ctx.attempt` value visible to the callee.
+ */
+async function runWithRetry(db, ctx, opts, fn) {
+    const sleep = opts.sleep ?? defaultSleep;
+    let lastError = new Error('runWithRetry: no attempts made');
+    let attemptCount = 0;
+    for (let attemptNumber = 1; attemptNumber <= opts.policy.maxAttempts; attemptNumber += 1) {
+        attemptCount = attemptNumber;
+        const attemptId = (0, attemptStore_1.createAttempt)(db, {
+            runId: opts.runId,
+            incarnationId: opts.incarnationId,
+        });
+        const attemptCtx = { ...ctx, attempt: attemptNumber };
+        try {
+            const value = await fn(attemptCtx, attemptNumber);
+            (0, attemptStore_1.completeAttempt)(db, { attemptId, status: 'completed' });
+            return { outcome: 'completed', value, attempts: attemptNumber };
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            lastError = error;
+            const errorClass = error.name || 'Error';
+            const terminalStatus = 'failed';
+            (0, attemptStore_1.completeAttempt)(db, {
+                attemptId,
+                status: terminalStatus,
+                errorClass,
+                errorMessage: error.message,
+            });
+            // Three cases:
+            //   (a) Class is in nonRetryableErrorClasses     → dead_letter (terminal class)
+            //   (b) Class is in retryableErrorClasses        → retry IF cap not reached; else dead_letter (exhausted)
+            //   (c) Class is unknown                         → failed (caller introspects; no auto-retry)
+            const isNonRetryable = opts.policy.nonRetryableErrorClasses.includes(errorClass);
+            const isRetryable = opts.policy.retryableErrorClasses.includes(errorClass);
+            if (isNonRetryable) {
+                return { outcome: 'dead_letter', attempts: attemptNumber, lastError: error };
+            }
+            if (!isRetryable) {
+                return { outcome: 'failed', attempts: attemptNumber, lastError: error };
+            }
+            if (attemptNumber >= opts.policy.maxAttempts) {
+                return { outcome: 'dead_letter', attempts: attemptNumber, lastError: error };
+            }
+            // Retryable + cap not reached: back off and try again.
+            await sleep((0, retryPolicy_1.computeBackoffMs)(attemptNumber, opts.policy));
+        }
+    }
+    // Defensive fallback — loop exited without explicit return.
+    return { outcome: 'dead_letter', attempts: attemptCount, lastError };
+}

package/dist/core/v4/daemon/runs/stuckAttemptWatchdog.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/runs/stuckAttemptWatchdog.ts — v4.9.0 Slice 8.
+ *
+ * Sweeps `run_attempts` (and `spans`) that are stuck `running` from
+ * a previous incarnation past `STUCK_THRESHOLD_MS`. Marks them
+ * `crashed` so post-mortem queries get one consistent shape rather
+ * than mixing "in-flight" with "abandoned".
+ *
+ * Wired as a `setInterval` ticker from bootstrap. Cadence default 5
+ * min, configurable via `AIDEN_STUCK_ATTEMPT_CHECK_MS`. Threshold 30
+ * min default, configurable via `AIDEN_STUCK_ATTEMPT_THRESHOLD_MS`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sweepStuckAttempts = sweepStuckAttempts;
+const DEFAULT_THRESHOLD_MS = 30 * 60 * 1000;
+/**
+ * Run a single sweep pass. Returns the count + ids of rows touched.
+ * Idempotent — calling twice in a row sweeps zero on the second call.
+ */
+function sweepStuckAttempts(db, opts) {
+    const now = (opts.now ?? Date.now)();
+    const thresholdMs = opts.thresholdMs ?? DEFAULT_THRESHOLD_MS;
+    const cutoffIso = new Date(now - thresholdMs).toISOString();
+    const endedAtIso = new Date(now).toISOString();
+    // ── attempts ────────────────────────────────────────────────────────────
+    const attemptRows = db.prepare(`SELECT attempt_id FROM run_attempts
+      WHERE status = 'running'
+        AND incarnation_id != ?
+        AND started_at < ?`).all(opts.currentIncarnationId, cutoffIso);
+    const attemptIds = attemptRows.map((r) => r.attempt_id);
+    if (attemptIds.length > 0) {
+        db.prepare(`UPDATE run_attempts
+          SET status        = 'crashed',
+              ended_at      = COALESCE(ended_at, ?),
+              finish_reason = COALESCE(finish_reason, 'stuck_attempt_swept')
+        WHERE status = 'running'
+          AND incarnation_id != ?
+          AND started_at < ?`).run(endedAtIso, opts.currentIncarnationId, cutoffIso);
+    }
+    // ── spans ──────────────────────────────────────────────────────────────
+    // Open spans (status NULL = in-flight) from a non-current incarnation.
+    // We don't apply the threshold here — any open span owned by a dead
+    // incarnation is by definition stuck; the parent process is gone.
+    const spanRows = db.prepare(`SELECT span_id FROM spans
+      WHERE status IS NULL
+        AND ended_at IS NULL
+        AND incarnation_id != ?`).all(opts.currentIncarnationId);
+    const spanIds = spanRows.map((r) => r.span_id);
+    if (spanIds.length > 0) {
+        db.prepare(`UPDATE spans
+          SET status        = 'cancelled',
+              ended_at      = COALESCE(ended_at, ?),
+              error_class   = COALESCE(error_class, 'OrphanedSpan'),
+              error_message = COALESCE(error_message, 'incarnation died with span open')
+        WHERE status IS NULL
+          AND ended_at IS NULL
+          AND incarnation_id != ?`).run(endedAtIso, opts.currentIncarnationId);
+    }
+    return {
+        reclaimedAttempts: attemptIds.length,
+        reclaimedSpans: spanIds.length,
+        attemptIds,
+        spanIds,
+    };
+}