ai-foreman 1.7.6 → 1.7.8

package/dist/workflowDb.js

@@ -3,6 +3,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statS
 import { hostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import Database from "better-sqlite3";
+import { providerSessionKey } from "./sessionIdentity.js";
 export const WORKFLOW_DB_FILE = ".rafi/recovery.sqlite3";
 /** Read the current project lease without creating or migrating recovery state. */
 export function readCurrentWorkflowLease(projectDir) {
@@ -42,6 +43,20 @@ export class WorkflowDb {
         this.importLegacyOnce();
     }
     close() { this.db.close(); }
+    /** Ensure non-workflow build records can use the same durable event store. */
+    ensureRun(runId, kind = "build", now = new Date()) {
+        const existing = this.getRun(runId);
+        if (existing)
+            return existing;
+        const at = now.toISOString();
+        this.db.transaction(() => {
+            const inserted = this.db.prepare(`INSERT OR IGNORE INTO workflow_runs(run_id,kind,status,checkpoint,original_work_json,remaining_work_json,state_json,legacy,created_at,updated_at)
+        VALUES(?,?,'running','durable-baseline','{}','{}','{}',0,?,?)`).run(runId, kind, at, at);
+            if (inserted.changes)
+                this.insertEvent(runId, "durable_baseline", "durable-baseline", { source: "host" }, at);
+        })();
+        return this.getRun(runId);
+    }
     createRun(input, now = new Date()) {
         const at = now.toISOString();
         const run = {
@@ -87,21 +102,187 @@ export class WorkflowDb {
         return rows.map((row) => ({ sequence: row.sequence, type: row.event_type, checkpoint: row.checkpoint, payload: parseJson(row.payload_json), at: row.created_at }));
     }
     recordSettings(runId, role, boundary, settings, now = new Date()) {
+        this.ensureRun(runId, "build", now);
         this.db.transaction(() => {
             this.db.prepare("INSERT OR REPLACE INTO role_settings(run_id,role,boundary,revision,settings_json,created_at) VALUES(?,?,?,?,?,?)")
                 .run(runId, role, boundary, settings.settings_revision, json(settings), now.toISOString());
             this.insertEvent(runId, "settings_boundary", `role:${role}:${boundary}`, { revision: settings.settings_revision }, now.toISOString());
         })();
     }
-    recordProjectSettingsRevision(revision, defaults, now = new Date()) {
-        this.db.prepare("INSERT OR REPLACE INTO project_settings_revisions(revision,defaults_json,created_at) VALUES(?,?,?)").run(revision, json(defaults), now.toISOString());
+    recordProjectSettingsRevision(revision, defaults, targetsOrNow = {}, now = new Date()) {
+        const targets = targetsOrNow instanceof Date ? {} : targetsOrNow;
+        const recordedAt = targetsOrNow instanceof Date ? targetsOrNow : now;
+        this.db.transaction(() => {
+            this.db.prepare(`INSERT INTO project_settings_revisions(revision,defaults_json,created_at) VALUES(?,?,?)
+        ON CONFLICT(revision) DO UPDATE SET defaults_json=excluded.defaults_json,created_at=excluded.created_at`).run(revision, json(defaults), recordedAt.toISOString());
+            const entries = Object.entries(targets);
+            if (entries.length) {
+                this.db.prepare("DELETE FROM project_settings_revision_targets WHERE revision=?").run(revision);
+                const insert = this.db.prepare("INSERT INTO project_settings_revision_targets(revision,role,fields_json) VALUES(?,?,?)");
+                for (const [role, fields] of entries)
+                    insert.run(revision, role, json([...new Set(fields)].sort()));
+            }
+        })();
+    }
+    projectSettingsRevisionTargets(revision) {
+        const rows = this.db.prepare("SELECT role,fields_json FROM project_settings_revision_targets WHERE revision=? ORDER BY role").all(revision);
+        return Object.fromEntries(rows.map((row) => [row.role, parseJson(row.fields_json)]));
     }
     recordTelemetry(runId, snapshot, now = new Date()) {
+        this.ensureRun(runId, "build", now);
         this.db.prepare("INSERT INTO workflow_telemetry(run_id,snapshot_json,created_at) VALUES(?,?,?)").run(runId, json(snapshot), now.toISOString());
     }
-    recordSession(runId, role, stream, sessionId, transition, settings, now = new Date()) {
-        this.db.prepare(`INSERT INTO provider_sessions(run_id,role,stream,provider,model,session_id,transition,settings_revision,created_at)
-      VALUES(?,?,?,?,?,?,?,?,?)`).run(runId, role, stream, settings.make, settings.model, sessionId ?? null, transition, settings.settings_revision, now.toISOString());
+    recordContextSample(sample) {
+        this.ensureRun(sample.runId);
+        const session = sessionParts(sample.sessionRef, sample.providerSessionId, sample.sessionKey);
+        if (session.ref)
+            this.recordProviderSessionBinding(session.ref, new Date(sample.observedAt));
+        const normalized = { ...sample, ...(session.ref ? { sessionRef: session.ref } : {}), ...(session.key ? { sessionKey: session.key } : {}) };
+        this.db.prepare(`INSERT INTO context_samples(run_id,role,provider_session_id,session_key,session_ref_json,sample_json,observed_at)
+      VALUES(?,?,?,?,?,?,?)`).run(sample.runId, sample.role, session.id, session.key, session.refJson, json(normalized), sample.observedAt);
+    }
+    contextSamples(runId, role) {
+        const rows = role
+            ? this.db.prepare("SELECT sample_json FROM context_samples WHERE run_id=? AND role=? ORDER BY sample_id").all(runId, role)
+            : this.db.prepare("SELECT sample_json FROM context_samples WHERE run_id=? ORDER BY sample_id").all(runId);
+        return rows.map((row) => parseJson(row.sample_json));
+    }
+    recordSessionUsage(sample) {
+        this.ensureRun(sample.runId);
+        const session = sessionParts(sample.sessionRef, sample.providerSessionId, sample.sessionKey);
+        if (session.ref)
+            this.recordProviderSessionBinding(session.ref, new Date(sample.observedAt));
+        const normalized = { ...sample, ...(session.ref ? { sessionRef: session.ref } : {}), ...(session.key ? { sessionKey: session.key } : {}) };
+        this.db.prepare(`INSERT INTO session_usage_samples(run_id,role,provider_session_id,session_key,session_ref_json,sample_json,observed_at)
+      VALUES(?,?,?,?,?,?,?)`).run(sample.runId, sample.role, session.id, session.key, session.refJson, json(normalized), sample.observedAt);
+    }
+    sessionUsageSamples(runId, role) {
+        const rows = role
+            ? this.db.prepare("SELECT sample_json FROM session_usage_samples WHERE run_id=? AND role=? ORDER BY sample_id").all(runId, role)
+            : this.db.prepare("SELECT sample_json FROM session_usage_samples WHERE run_id=? ORDER BY sample_id").all(runId);
+        return rows.map((row) => parseJson(row.sample_json));
+    }
+    acknowledgeSettings(ack) {
+        this.ensureRun(ack.runId);
+        const session = sessionParts(ack.sessionRef, ack.providerSessionId, ack.sessionKey);
+        this.db.transaction(() => {
+            this.db.prepare(`INSERT INTO live_settings_acknowledgments(run_id,role,provider_session_id,session_key,session_ref_json,revision,acknowledged_at)
+        VALUES(?,?,?,?,?,?,?) ON CONFLICT(run_id,role,revision) DO UPDATE SET provider_session_id=excluded.provider_session_id,session_key=excluded.session_key,session_ref_json=excluded.session_ref_json,acknowledged_at=excluded.acknowledged_at`)
+                .run(ack.runId, ack.role, session.id, session.key, session.refJson, ack.revision, ack.acknowledgedAt);
+            if (session.key) {
+                this.db.prepare(`INSERT INTO live_settings_session_acknowledgments(run_id,role,provider_session_id,session_key,session_ref_json,revision,acknowledged_at)
+          VALUES(?,?,?,?,?,?,?) ON CONFLICT(run_id,role,session_key,revision) DO UPDATE SET provider_session_id=excluded.provider_session_id,session_ref_json=excluded.session_ref_json,acknowledged_at=excluded.acknowledged_at`)
+                    .run(ack.runId, ack.role, session.id, session.key, session.refJson, ack.revision, ack.acknowledgedAt);
+            }
+            this.insertEvent(ack.runId, "live_settings_acknowledged", `settings:${ack.revision}`, { role: ack.role, providerSessionId: session.id, sessionKey: session.key }, ack.acknowledgedAt);
+        })();
+    }
+    settingsAcknowledgments(revision) {
+        const scoped = this.db.prepare("SELECT * FROM live_settings_session_acknowledgments WHERE revision=? ORDER BY acknowledged_at").all(revision);
+        const covered = new Set(scoped.map((row) => `${row.run_id}:${row.role}`));
+        const legacy = this.db.prepare("SELECT * FROM live_settings_acknowledgments WHERE revision=? ORDER BY acknowledged_at").all(revision)
+            .filter((row) => !covered.has(`${row.run_id}:${row.role}`));
+        return [...scoped, ...legacy]
+            .sort((left, right) => left.acknowledged_at.localeCompare(right.acknowledged_at))
+            .map((row) => ({ runId: row.run_id, role: row.role, ...(row.provider_session_id ? { providerSessionId: row.provider_session_id } : {}), ...(row.session_key ? { sessionKey: row.session_key } : {}), ...(row.session_ref_json ? { sessionRef: parseJson(row.session_ref_json) } : {}), revision: row.revision, acknowledgedAt: row.acknowledged_at }));
+    }
+    appendContinuityEvent(input, now = new Date()) {
+        this.ensureRun(input.runId, "build", now);
+        const at = now.toISOString();
+        const safePayload = sanitizeContinuityValue(input.payload);
+        const session = sessionParts(input.sessionRef, undefined, input.sessionKey);
+        const digest = digestJson({ runId: input.runId, role: input.role, kind: input.kind, payload: safePayload, authoritativeStateRevision: input.authoritativeStateRevision, sessionKey: session.key, at });
+        const result = this.db.prepare(`INSERT INTO continuity_events(run_id,role,kind,payload_json,digest,authoritative_state_revision,session_key,session_ref_json,created_at)
+      VALUES(?,?,?,?,?,?,?,?,?)`).run(input.runId, input.role, input.kind, json(safePayload), digest, input.authoritativeStateRevision, session.key, session.refJson, at);
+        return { sequence: Number(result.lastInsertRowid), runId: input.runId, role: input.role, kind: input.kind, payload: safePayload, digest, authoritativeStateRevision: input.authoritativeStateRevision, createdAt: at, ...(session.key ? { sessionKey: session.key } : {}), ...(session.ref ? { sessionRef: session.ref } : {}) };
+    }
+    continuityEvents(runId, afterSequence = 0) {
+        const rows = this.db.prepare("SELECT * FROM continuity_events WHERE run_id=? AND sequence>? ORDER BY sequence").all(runId, afterSequence);
+        return rows.map(continuityEventFromRow);
+    }
+    publishContinuityCheckpoint(input, now = new Date()) {
+        this.ensureRun(input.runId, "build", now);
+        return this.db.transaction(() => {
+            const at = now.toISOString();
+            const previous = this.continuityHead(input.runId, input.role);
+            const latestEvent = this.db.prepare("SELECT COALESCE(MAX(sequence),0) AS sequence FROM continuity_events WHERE run_id=?").get(input.runId);
+            const safeDelta = sanitizeContinuityValue(input.delta);
+            const session = sessionParts(input.sessionRef, undefined, input.sessionKey);
+            const digest = digestJson({ runId: input.runId, role: input.role, sequence: latestEvent.sequence, predecessorDigest: previous?.digest, delta: safeDelta, authoritativeStateRevision: input.authoritativeStateRevision, sessionKey: session.key });
+            const result = this.db.prepare(`INSERT INTO continuity_checkpoints(run_id,role,event_sequence,state,delta_json,digest,predecessor_digest,authoritative_state_revision,session_key,session_ref_json,created_at)
+        VALUES(?,?,?,?,?,?,?,?,?,?,?)`).run(input.runId, input.role, latestEvent.sequence, input.state ?? "current", json(safeDelta), digest, previous?.digest ?? null, input.authoritativeStateRevision, session.key, session.refJson, at);
+            const checkpoint = {
+                checkpointId: Number(result.lastInsertRowid), runId: input.runId, role: input.role,
+                sequence: latestEvent.sequence, state: input.state ?? "current", delta: safeDelta, digest,
+                ...(previous ? { predecessorDigest: previous.digest } : {}),
+                authoritativeStateRevision: input.authoritativeStateRevision, createdAt: at,
+                ...(session.key ? { sessionKey: session.key } : {}), ...(session.ref ? { sessionRef: session.ref } : {}),
+            };
+            this.upsertContinuityHead({ runId: input.runId, role: input.role, state: checkpoint.state, sequence: checkpoint.sequence, digest, authoritativeStateRevision: input.authoritativeStateRevision, updatedAt: at });
+            this.refreshRunContinuityHead(input.runId, input.authoritativeStateRevision, at);
+            this.insertEvent(input.runId, "continuity_checkpoint", `continuity:${input.role}`, { checkpointId: checkpoint.checkpointId, digest, state: checkpoint.state }, at);
+            return checkpoint;
+        })();
+    }
+    continuityCheckpoints(runId, role) {
+        const rows = role
+            ? this.db.prepare("SELECT * FROM continuity_checkpoints WHERE run_id=? AND role=? ORDER BY checkpoint_id").all(runId, role)
+            : this.db.prepare("SELECT * FROM continuity_checkpoints WHERE run_id=? ORDER BY checkpoint_id").all(runId);
+        return rows.map(continuityCheckpointFromRow);
+    }
+    latestContinuityCheckpoint(runId, role) {
+        const row = this.db.prepare("SELECT * FROM continuity_checkpoints WHERE run_id=? AND role=? ORDER BY checkpoint_id DESC LIMIT 1").get(runId, role);
+        return row ? continuityCheckpointFromRow(row) : undefined;
+    }
+    continuityHead(runId, role) {
+        const row = this.db.prepare("SELECT * FROM continuity_heads WHERE run_id=? AND role=?").get(runId, role);
+        return row ? continuityHeadFromRow(row) : undefined;
+    }
+    setContinuityHeadState(runId, role, state, now = new Date()) {
+        const head = this.continuityHead(runId, role);
+        if (!head)
+            return undefined;
+        const next = { ...head, state, updatedAt: now.toISOString() };
+        this.upsertContinuityHead(next);
+        this.refreshRunContinuityHead(runId, head.authoritativeStateRevision, next.updatedAt);
+        return next;
+    }
+    recordSession(runId, role, stream, session, transition, settings, now = new Date()) {
+        this.ensureRun(runId, "build", now);
+        const scoped = sessionParts(typeof session === "object" ? session : undefined, typeof session === "string" ? session : undefined);
+        if (scoped.ref)
+            this.recordProviderSessionBinding(scoped.ref, now);
+        this.db.prepare(`INSERT INTO provider_sessions(run_id,role,stream,provider,model,session_id,session_key,session_ref_json,transition,settings_revision,created_at)
+      VALUES(?,?,?,?,?,?,?,?,?,?,?)`).run(runId, role, stream, settings.make, settings.model, scoped.id, scoped.key, scoped.refJson, transition, settings.settings_revision, now.toISOString());
+    }
+    providerSessionRefs(runId, role) {
+        const rows = role
+            ? this.db.prepare("SELECT session_ref_json FROM provider_sessions WHERE run_id=? AND role=? AND session_ref_json IS NOT NULL ORDER BY id").all(runId, role)
+            : this.db.prepare("SELECT session_ref_json FROM provider_sessions WHERE run_id=? AND session_ref_json IS NOT NULL ORDER BY id").all(runId);
+        const refs = rows.map((row) => parseJson(row.session_ref_json));
+        return [...new Map(refs.map((ref) => [providerSessionKey(ref), ref])).values()];
+    }
+    /** Project-local lookup used to resolve compatibility raw IDs into scoped references. */
+    recordProviderSessionBinding(ref, now = new Date()) {
+        const key = providerSessionKey(ref);
+        this.db.prepare(`INSERT INTO provider_session_bindings(session_key,provider_session_id,role,session_ref_json,observed_at)
+      VALUES(?,?,?,?,?) ON CONFLICT(session_key) DO UPDATE SET session_ref_json=excluded.session_ref_json,observed_at=excluded.observed_at`)
+            .run(key, ref.sessionId, ref.role, json(ref), now.toISOString());
+    }
+    providerSessionBindings(sessionId, role) {
+        const clauses = [];
+        const values = [];
+        if (sessionId) {
+            clauses.push("provider_session_id=?");
+            values.push(sessionId);
+        }
+        if (role) {
+            clauses.push("role=?");
+            values.push(role);
+        }
+        const where = clauses.length ? ` WHERE ${clauses.join(" AND ")}` : "";
+        const rows = this.db.prepare(`SELECT session_ref_json FROM provider_session_bindings${where} ORDER BY observed_at`).all(...values);
+        return rows.map((row) => parseJson(row.session_ref_json));
     }
     recordIssue(runId, issue) {
         const result = this.db.prepare("INSERT INTO workflow_issues(run_id,code,issue_json,created_at) VALUES(?,?,?,?)").run(runId, issue.code, json(issue), issue.occurred_at);
@@ -118,10 +299,15 @@ export class WorkflowDb {
         return this.operation(input.idempotencyKey);
     }
     updateOperation(idempotencyKey, status, details = {}, now = new Date()) {
-        if (!this.operation(idempotencyKey))
+        const prior = this.operation(idempotencyKey);
+        if (!prior)
             throw new Error(`operation not found: ${idempotencyKey}`);
-        this.db.prepare("UPDATE operation_journal SET status=?,result_json=?,external_id=?,error=?,updated_at=? WHERE idempotency_key=?")
-            .run(status, details.result === undefined ? null : json(details.result), details.externalId ?? null, details.error ?? null, now.toISOString(), idempotencyKey);
+        const at = now.toISOString();
+        this.db.transaction(() => {
+            this.db.prepare("UPDATE operation_journal SET status=?,result_json=?,external_id=?,error=?,updated_at=? WHERE idempotency_key=?")
+                .run(status, details.result === undefined ? null : json(details.result), details.externalId ?? null, details.error ?? null, at, idempotencyKey);
+            this.appendContinuityEvent({ runId: prior.runId, role: "host", kind: "operation_receipt", payload: { idempotencyKey, kind: prior.kind, status, externalId: details.externalId, error: details.error }, authoritativeStateRevision: this.continuityHead(prior.runId, "run")?.authoritativeStateRevision ?? 0 }, now);
+        })();
         return this.operation(idempotencyKey);
     }
     operation(idempotencyKey) {
@@ -141,6 +327,271 @@ export class WorkflowDb {
         const row = this.db.prepare("SELECT content FROM content_refs WHERE digest=?").get(digest);
         return row?.content;
     }
+    stageHandoff(manifest, markdown) {
+        this.ensureRun(manifest.runId);
+        const manifestText = stableJson(sanitizeContinuityValue(manifest));
+        const manifestDigest = this.putEvidence("handoff", manifestText);
+        const markdownDigest = this.putEvidence("handoff", markdown);
+        const lineage = {
+            runId: manifest.runId,
+            generation: manifest.generation,
+            manifestDigest,
+            markdownDigest,
+            ...(manifest.predecessorSessionId ? { predecessorSessionId: manifest.predecessorSessionId } : {}),
+            ...(manifest.predecessorSessionRef ? { predecessorSessionRef: manifest.predecessorSessionRef } : {}),
+            state: "staged",
+            createdAt: manifest.createdAt,
+        };
+        this.db.transaction(() => {
+            const existing = this.db.prepare("SELECT manifest_digest,markdown_digest FROM handoffs WHERE run_id=? AND generation=?").get(manifest.runId, manifest.generation);
+            if (existing && (existing.manifest_digest !== manifestDigest || existing.markdown_digest !== markdownDigest)) {
+                throw new Error(`handoff generation ${manifest.generation} is immutable`);
+            }
+            const predecessor = sessionParts(manifest.predecessorSessionRef, manifest.predecessorSessionId);
+            this.db.prepare(`INSERT OR IGNORE INTO handoffs(run_id,generation,role,manifest_digest,markdown_digest,predecessor_session_id,predecessor_session_key,predecessor_session_ref_json,state,created_at)
+        VALUES(?,?,?,?,?,?,?,?,?,?)`).run(manifest.runId, manifest.generation, manifest.role, manifestDigest, markdownDigest, predecessor.id, predecessor.key, predecessor.refJson, "staged", manifest.createdAt);
+            this.insertEvent(manifest.runId, "handoff_staged", `handoff:${manifest.generation}`, { generation: manifest.generation, manifestDigest, markdownDigest, resources: manifest.resources }, manifest.createdAt);
+        })();
+        return this.handoff(manifest.runId, manifest.generation) ?? lineage;
+    }
+    acceptHandoff(runId, generation, successor, now = new Date()) {
+        const session = sessionParts(typeof successor === "object" ? successor : undefined, typeof successor === "string" ? successor : undefined);
+        if (!session.id?.trim())
+            throw new Error("a validated successor session ID is required before handoff acceptance");
+        if (session.ref)
+            this.recordProviderSessionBinding(session.ref, now);
+        return this.db.transaction(() => {
+            const prior = this.handoff(runId, generation);
+            if (!prior)
+                throw new Error(`handoff generation ${generation} not found for run ${runId}`);
+            if (prior.state === "failed")
+                throw new Error("a failed handoff cannot be accepted");
+            const at = now.toISOString();
+            this.db.prepare(`UPDATE handoffs SET state='accepted',successor_session_id=?,successor_session_key=?,successor_session_ref_json=?,accepted_at=? WHERE run_id=? AND generation=?`)
+                .run(session.id, session.key, session.refJson, at, runId, generation);
+            this.db.prepare(`INSERT INTO role_mutation_leases(run_id,role,generation,provider_session_id,provider_session_key,provider_session_ref_json,moved_at)
+        SELECT run_id,role,generation,?,?,?,? FROM handoffs WHERE run_id=? AND generation=?
+        ON CONFLICT(run_id,role) DO UPDATE SET generation=excluded.generation,provider_session_id=excluded.provider_session_id,provider_session_key=excluded.provider_session_key,provider_session_ref_json=excluded.provider_session_ref_json,moved_at=excluded.moved_at`)
+                .run(session.id, session.key, session.refJson, at, runId, generation);
+            this.insertEvent(runId, "handoff_accepted", `handoff:${generation}`, { generation, successorSessionId: session.id, sessionKey: session.key, leaseMoved: true }, at);
+            return this.handoff(runId, generation);
+        })();
+    }
+    /** Fence the initial role owner without overwriting a lease already moved by a handoff. */
+    claimInitialRoleLease(runId, role, providerSession, now = new Date()) {
+        const session = sessionParts(typeof providerSession === "object" ? providerSession : undefined, typeof providerSession === "string" ? providerSession : undefined);
+        if (!session.id?.trim())
+            throw new Error("a provider session ID is required to claim the role lease");
+        this.ensureRun(runId);
+        this.db.prepare(`INSERT OR IGNORE INTO role_mutation_leases(run_id,role,generation,provider_session_id,provider_session_key,provider_session_ref_json,moved_at) VALUES(?,?,?,?,?,?,?)`)
+            .run(runId, role, 0, session.id, session.key, session.refJson, now.toISOString());
+        return this.roleMutationLease(runId, role);
+    }
+    roleMutationLease(runId, role) {
+        const row = this.db.prepare(`SELECT run_id,role,generation,provider_session_id,provider_session_key,provider_session_ref_json,moved_at FROM role_mutation_leases WHERE run_id=? AND role=?`)
+            .get(runId, role);
+        return row ? { runId: row.run_id, role: row.role, generation: row.generation, providerSessionId: row.provider_session_id, ...(row.provider_session_key ? { sessionKey: row.provider_session_key } : {}), ...(row.provider_session_ref_json ? { sessionRef: parseJson(row.provider_session_ref_json) } : {}), movedAt: row.moved_at } : undefined;
+    }
+    /** Move a dead predecessor's lease only after a fresh recovery produced a schema-valid checkpoint. */
+    moveRoleLeaseAfterValidatedRecovery(runId, role, providerSession, reason, now = new Date()) {
+        const session = sessionParts(typeof providerSession === "object" ? providerSession : undefined, typeof providerSession === "string" ? providerSession : undefined);
+        if (!session.id?.trim())
+            throw new Error("a validated recovery session ID is required to move the role lease");
+        this.ensureRun(runId);
+        const prior = this.roleMutationLease(runId, role);
+        if ((session.key && prior?.sessionKey === session.key) || (!session.key && prior?.providerSessionId === session.id))
+            return prior;
+        const at = now.toISOString();
+        const generation = (prior?.generation ?? -1) + 1;
+        return this.db.transaction(() => {
+            this.db.prepare(`INSERT INTO role_mutation_leases(run_id,role,generation,provider_session_id,provider_session_key,provider_session_ref_json,moved_at) VALUES(?,?,?,?,?,?,?)
+        ON CONFLICT(run_id,role) DO UPDATE SET generation=excluded.generation,provider_session_id=excluded.provider_session_id,provider_session_key=excluded.provider_session_key,provider_session_ref_json=excluded.provider_session_ref_json,moved_at=excluded.moved_at`)
+                .run(runId, role, generation, session.id, session.key, session.refJson, at);
+            this.insertEvent(runId, "validated_recovery_lease_moved", `recovery:${role}:${generation}`, {
+                role, generation, predecessorSessionId: prior?.providerSessionId, successorSessionId: session.id, successorSessionKey: session.key,
+                reason: sanitizeText(reason).slice(0, 500),
+            }, at);
+            return this.roleMutationLease(runId, role);
+        })();
+    }
+    failHandoff(runId, generation, reason, now = new Date()) {
+        const prior = this.handoff(runId, generation);
+        if (!prior)
+            throw new Error(`handoff generation ${generation} not found for run ${runId}`);
+        if (prior.state === "accepted")
+            throw new Error("an accepted handoff cannot be failed");
+        const at = now.toISOString();
+        this.db.prepare("UPDATE handoffs SET state='failed',failure=? WHERE run_id=? AND generation=?").run(sanitizeText(reason).slice(0, 2000), runId, generation);
+        this.insertEvent(runId, "handoff_failed", `handoff:${generation}`, { generation, reason: sanitizeText(reason).slice(0, 500) }, at);
+        return this.handoff(runId, generation);
+    }
+    handoff(runId, generation) {
+        const row = this.db.prepare("SELECT * FROM handoffs WHERE run_id=? AND generation=?").get(runId, generation);
+        return row ? handoffFromRow(row) : undefined;
+    }
+    handoffs(runId) {
+        return this.db.prepare("SELECT * FROM handoffs WHERE run_id=? ORDER BY generation").all(runId).map(handoffFromRow);
+    }
+    handoffContent(runId, generation) {
+        const lineage = this.handoff(runId, generation);
+        if (!lineage)
+            return undefined;
+        const manifest = this.getEvidence(lineage.manifestDigest);
+        const markdown = this.getEvidence(lineage.markdownDigest);
+        if (!manifest || !markdown)
+            throw new Error(`handoff ${runId}/${generation} references missing durable content`);
+        return { lineage, manifest: JSON.parse(manifest.toString("utf8")), markdown: markdown.toString("utf8") };
+    }
+    deleteHandoffHistory(runId) {
+        const run = this.getRun(runId);
+        if (!run)
+            throw new Error(`run not found: ${runId}`);
+        if (!["completed", "cancelled", "superseded"].includes(run.status))
+            throw new Error(`run ${runId} is active or recoverable; durable handoff history cannot be deleted`);
+        const rows = this.db.prepare("SELECT manifest_digest,markdown_digest FROM handoffs WHERE run_id=?").all(runId);
+        this.db.transaction(() => {
+            this.db.prepare("DELETE FROM role_mutation_leases WHERE run_id=?").run(runId);
+            this.db.prepare("DELETE FROM handoffs WHERE run_id=?").run(runId);
+            for (const row of rows) {
+                for (const digest of [row.manifest_digest, row.markdown_digest]) {
+                    const referenced = this.db.prepare("SELECT 1 FROM handoffs WHERE manifest_digest=? OR markdown_digest=? LIMIT 1").get(digest, digest);
+                    if (!referenced)
+                        this.db.prepare("DELETE FROM content_refs WHERE digest=? AND kind='handoff'").run(digest);
+                }
+            }
+        })();
+        return rows.length;
+    }
+    startCompactionAttempt(input, now = new Date()) {
+        this.ensureRun(input.runId);
+        const at = now.toISOString();
+        const session = sessionParts(input.sessionRef, input.providerSessionId, input.sessionKey);
+        this.db.prepare(`INSERT OR IGNORE INTO compaction_attempts(idempotency_key,run_id,role,provider_session_id,session_key,session_ref_json,crossing_key,status,before_sample_json,origin,provider_event_id,threshold_generation_id,created_at,updated_at)
+      VALUES(?,?,?,?,?,?,?,'started',?,?,?,?,?,?)`).run(input.idempotencyKey, input.runId, input.role, session.id, session.key, session.refJson, input.crossingKey, input.beforeSample ? json(input.beforeSample) : null, input.origin ?? "rafi-manual", input.providerEventId ?? null, input.thresholdGenerationId ?? null, at, at);
+        const direct = this.compactionAttempt(input.idempotencyKey);
+        if (direct)
+            return direct;
+        if (session.key && input.providerEventId) {
+            const duplicate = this.db.prepare("SELECT * FROM compaction_attempts WHERE run_id=? AND role=? AND session_key=? AND provider_event_id=?").get(input.runId, input.role, session.key, input.providerEventId);
+            if (duplicate)
+                return compactionAttemptFromRow(duplicate);
+        }
+        throw new Error(`failed to persist compaction attempt ${input.idempotencyKey}`);
+    }
+    finishCompactionAttempt(idempotencyKey, input, now = new Date()) {
+        const prior = this.compactionAttempt(idempotencyKey);
+        if (!prior)
+            throw new Error(`compaction attempt not found: ${idempotencyKey}`);
+        if (prior.status !== "started")
+            return prior;
+        this.db.prepare("UPDATE compaction_attempts SET status=?,after_sample_json=?,error=?,updated_at=? WHERE idempotency_key=?")
+            .run(input.status ?? (input.ok ? "succeeded" : "failed"), input.afterSample ? json(input.afterSample) : null, input.error ? sanitizeText(input.error).slice(0, 2000) : null, now.toISOString(), idempotencyKey);
+        const status = input.status ?? (input.ok ? "succeeded" : "failed");
+        this.insertEvent(prior.runId, `compaction_${status}`, `context:${prior.role}`, { idempotencyKey, providerSessionId: prior.providerSessionId, sessionKey: prior.sessionKey, crossingKey: prior.crossingKey, origin: prior.origin, providerEventId: prior.providerEventId }, now.toISOString());
+        return this.compactionAttempt(idempotencyKey);
+    }
+    compactionAttempt(idempotencyKey) {
+        const row = this.db.prepare("SELECT * FROM compaction_attempts WHERE idempotency_key=?").get(idempotencyKey);
+        return row ? compactionAttemptFromRow(row) : undefined;
+    }
+    linkCompactionProviderEvent(idempotencyKey, providerEventId) {
+        const prior = this.compactionAttempt(idempotencyKey);
+        if (!prior)
+            throw new Error(`compaction attempt not found: ${idempotencyKey}`);
+        if (prior.providerEventId === providerEventId)
+            return prior;
+        this.db.prepare("UPDATE compaction_attempts SET provider_event_id=?,updated_at=? WHERE idempotency_key=?")
+            .run(providerEventId, new Date().toISOString(), idempotencyKey);
+        return this.compactionAttempt(idempotencyKey);
+    }
+    compactionAttempts(runId, role, providerSession) {
+        if (!providerSession)
+            return [];
+        const session = sessionParts(typeof providerSession === "object" ? providerSession : undefined, typeof providerSession === "string" ? providerSession : undefined);
+        const rows = session.key
+            ? this.db.prepare("SELECT * FROM compaction_attempts WHERE run_id=? AND role=? AND session_key=? ORDER BY created_at,idempotency_key").all(runId, role, session.key)
+            : this.db.prepare("SELECT * FROM compaction_attempts WHERE run_id=? AND role=? AND provider_session_id=? AND session_key IS NULL ORDER BY created_at,idempotency_key").all(runId, role, session.id);
+        return rows.map(compactionAttemptFromRow);
+    }
+    successfulCompactionCount(runId, role, providerSession) {
+        if (!providerSession)
+            return 0;
+        const session = sessionParts(typeof providerSession === "object" ? providerSession : undefined, typeof providerSession === "string" ? providerSession : undefined);
+        const row = session.key
+            ? this.db.prepare(`SELECT COUNT(*) AS count FROM compaction_attempts WHERE run_id=? AND role=? AND session_key=? AND status IN ('succeeded','unverified')`).get(runId, role, session.key)
+            : this.db.prepare(`SELECT COUNT(*) AS count FROM compaction_attempts WHERE run_id=? AND role=? AND provider_session_id=? AND session_key IS NULL AND status IN ('succeeded','unverified')`).get(runId, role, session.id);
+        return row.count;
+    }
+    upsertThresholdGeneration(input, now = new Date()) {
+        this.ensureRun(input.runId);
+        const at = now.toISOString();
+        const session = sessionParts(input.sessionRef, input.providerSessionId, input.sessionKey);
+        this.db.prepare(`INSERT INTO threshold_generations(
+      generation_id,run_id,role,provider_session_id,session_key,session_ref_json,generation,state,configured_ceiling_percent,
+      installed_native_token_limit,installed_native_percent,settings_revision,model,latest_sample_json,frozen_action_digest,provider_event_id,created_at,updated_at
+    ) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+    ON CONFLICT(generation_id) DO UPDATE SET
+      provider_session_id=excluded.provider_session_id,session_key=excluded.session_key,session_ref_json=excluded.session_ref_json,
+      state=excluded.state,configured_ceiling_percent=excluded.configured_ceiling_percent,
+      installed_native_token_limit=excluded.installed_native_token_limit,installed_native_percent=excluded.installed_native_percent,
+      settings_revision=excluded.settings_revision,model=excluded.model,latest_sample_json=excluded.latest_sample_json,
+      frozen_action_digest=COALESCE(excluded.frozen_action_digest,threshold_generations.frozen_action_digest),
+      provider_event_id=COALESCE(excluded.provider_event_id,threshold_generations.provider_event_id),updated_at=excluded.updated_at`).run(input.generationId, input.runId, input.role, session.id, session.key, session.refJson, input.generation, input.state, input.configuredCeilingPercent, input.installedNativeTokenLimit ?? null, input.installedNativePercent ?? null, input.settingsRevision, input.model, input.latestSample ? json(input.latestSample) : null, input.frozenActionDigest ?? null, input.providerEventId ?? null, at, at);
+        return this.thresholdGeneration(input.generationId);
+    }
+    thresholdGeneration(generationId) {
+        const row = this.db.prepare("SELECT * FROM threshold_generations WHERE generation_id=?").get(generationId);
+        return row ? thresholdGenerationFromRow(row) : undefined;
+    }
+    thresholdGenerations(runId, role, sessionKey) {
+        const rows = role && sessionKey
+            ? this.db.prepare("SELECT * FROM threshold_generations WHERE run_id=? AND role=? AND session_key=? ORDER BY generation").all(runId, role, sessionKey)
+            : role
+                ? this.db.prepare("SELECT * FROM threshold_generations WHERE run_id=? AND role=? ORDER BY created_at,generation").all(runId, role)
+                : this.db.prepare("SELECT * FROM threshold_generations WHERE run_id=? ORDER BY created_at,generation").all(runId);
+        return rows.map(thresholdGenerationFromRow);
+    }
+    markRoleAdapterActive(input) {
+        this.ensureRun(input.runId);
+        const sessionKey = input.sessionKey ?? `${input.role}:unscoped:${input.providerSessionId ?? "pending"}`;
+        this.db.prepare(`INSERT INTO active_role_adapter_sessions(run_id,role,provider_session_id,session_key,settings_revision,observed_at)
+      VALUES(?,?,?,?,?,?) ON CONFLICT(run_id,role,session_key) DO UPDATE SET provider_session_id=excluded.provider_session_id,settings_revision=excluded.settings_revision,observed_at=excluded.observed_at`)
+            .run(input.runId, input.role, input.providerSessionId ?? null, sessionKey, input.settingsRevision, input.observedAt);
+    }
+    clearRoleAdapterActive(runId, role, sessionKey) {
+        if (sessionKey)
+            this.db.prepare("DELETE FROM active_role_adapter_sessions WHERE run_id=? AND role=? AND session_key=?").run(runId, role, sessionKey);
+        else
+            this.db.prepare("DELETE FROM active_role_adapter_sessions WHERE run_id=? AND role=?").run(runId, role);
+    }
+    activeRoleAdapters(runId, observedAfter) {
+        const clauses = [];
+        const values = [];
+        if (runId) {
+            clauses.push("run_id=?");
+            values.push(runId);
+        }
+        if (observedAfter) {
+            clauses.push("observed_at>=?");
+            values.push(observedAfter);
+        }
+        const where = clauses.length ? ` WHERE ${clauses.join(" AND ")}` : "";
+        const rows = this.db.prepare(`SELECT * FROM active_role_adapter_sessions${where} ORDER BY run_id,role,session_key`).all(...values);
+        return rows.map((row) => ({ runId: row.run_id, role: row.role, ...(row.provider_session_id ? { providerSessionId: row.provider_session_id } : {}), ...(row.session_key ? { sessionKey: row.session_key } : {}), settingsRevision: row.settings_revision, observedAt: row.observed_at }));
+    }
+    recordRecoveryDecision(receipt) {
+        this.ensureRun(receipt.runId);
+        const digest = digestJson(receipt);
+        const session = sessionParts(receipt.predecessorSessionRef, receipt.predecessorSessionId);
+        this.db.transaction(() => {
+            this.db.prepare(`INSERT INTO recovery_decisions(run_id,decided_at,mode,digest,session_key,session_ref_json,receipt_json)
+        VALUES(?,?,?,?,?,?,?)`).run(receipt.runId, receipt.decidedAt, receipt.mode, digest, session.key, session.refJson, json(receipt));
+            this.insertEvent(receipt.runId, "recovery_decision", "recovery", { mode: receipt.mode, digest }, receipt.decidedAt);
+        })();
+    }
+    recoveryDecisions(runId) {
+        return this.db.prepare("SELECT receipt_json FROM recovery_decisions WHERE run_id=? ORDER BY decision_id").all(runId).map((row) => parseJson(row.receipt_json));
+    }
     beginPublication(runId, intent, previousDigests, now = new Date()) {
         const transactionId = randomUUID();
         const at = now.toISOString();
@@ -230,6 +681,22 @@ export class WorkflowDb {
         }
         return count;
     }
+    upsertContinuityHead(head) {
+        this.db.prepare(`INSERT INTO continuity_heads(run_id,role,state,event_sequence,digest,authoritative_state_revision,updated_at)
+      VALUES(?,?,?,?,?,?,?) ON CONFLICT(run_id,role) DO UPDATE SET state=excluded.state,event_sequence=excluded.event_sequence,digest=excluded.digest,authoritative_state_revision=excluded.authoritative_state_revision,updated_at=excluded.updated_at`)
+            .run(head.runId, head.role, head.state, head.sequence, head.digest, head.authoritativeStateRevision, head.updatedAt);
+    }
+    refreshRunContinuityHead(runId, authoritativeStateRevision, at) {
+        const rows = this.db.prepare("SELECT role,state,event_sequence,digest FROM continuity_heads WHERE run_id=? AND role IN ('builder','qa') ORDER BY role").all(runId);
+        if (!rows.length)
+            return;
+        const state = rows.some((row) => row.state === "invalid") ? "invalid"
+            : rows.some((row) => row.state === "degraded") ? "degraded"
+                : rows.some((row) => row.state === "stale") ? "stale" : "current";
+        const sequence = Math.max(...rows.map((row) => row.event_sequence));
+        const digest = digestJson(rows.map((row) => ({ role: row.role, digest: row.digest })));
+        this.upsertContinuityHead({ runId, role: "run", state, sequence, digest, authoritativeStateRevision, updatedAt: at });
+    }
     insertEvent(runId, type, checkpoint, payload, at) {
         this.db.prepare("INSERT INTO workflow_events(run_id,event_type,checkpoint,payload_json,created_at) VALUES(?,?,?,?,?)").run(runId, type, checkpoint, json(payload), at);
     }
@@ -239,24 +706,118 @@ export class WorkflowDb {
       CREATE TABLE IF NOT EXISTS workflow_events(sequence INTEGER PRIMARY KEY AUTOINCREMENT,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),event_type TEXT NOT NULL,checkpoint TEXT NOT NULL,payload_json TEXT NOT NULL,created_at TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS role_settings(run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),role TEXT NOT NULL,boundary INTEGER NOT NULL,revision INTEGER NOT NULL,settings_json TEXT NOT NULL,created_at TEXT NOT NULL,PRIMARY KEY(run_id,role,boundary));
       CREATE TABLE IF NOT EXISTS project_settings_revisions(revision INTEGER PRIMARY KEY,defaults_json TEXT NOT NULL,created_at TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS project_settings_revision_targets(revision INTEGER NOT NULL REFERENCES project_settings_revisions(revision),role TEXT NOT NULL,fields_json TEXT NOT NULL,PRIMARY KEY(revision,role));
       CREATE TABLE IF NOT EXISTS workflow_telemetry(id INTEGER PRIMARY KEY AUTOINCREMENT,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),snapshot_json TEXT NOT NULL,created_at TEXT NOT NULL);
-      CREATE TABLE IF NOT EXISTS provider_sessions(id INTEGER PRIMARY KEY AUTOINCREMENT,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),role TEXT NOT NULL,stream TEXT NOT NULL,provider TEXT NOT NULL,model TEXT NOT NULL,session_id TEXT,transition TEXT NOT NULL,settings_revision INTEGER NOT NULL,created_at TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS provider_sessions(id INTEGER PRIMARY KEY AUTOINCREMENT,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),role TEXT NOT NULL,stream TEXT NOT NULL,provider TEXT NOT NULL,model TEXT NOT NULL,session_id TEXT,session_key TEXT,session_ref_json TEXT,transition TEXT NOT NULL,settings_revision INTEGER NOT NULL,created_at TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS provider_session_bindings(session_key TEXT PRIMARY KEY,provider_session_id TEXT NOT NULL,role TEXT NOT NULL,session_ref_json TEXT NOT NULL,observed_at TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS workflow_issues(issue_id INTEGER PRIMARY KEY AUTOINCREMENT,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),code TEXT NOT NULL,issue_json TEXT NOT NULL,created_at TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS operation_journal(idempotency_key TEXT PRIMARY KEY,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),kind TEXT NOT NULL,status TEXT NOT NULL,intent_json TEXT NOT NULL,result_json TEXT,external_id TEXT,error TEXT,created_at TEXT NOT NULL,updated_at TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS content_refs(digest TEXT PRIMARY KEY,kind TEXT NOT NULL,content BLOB NOT NULL,created_at TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS project_lease(singleton INTEGER PRIMARY KEY CHECK(singleton=1),owner TEXT NOT NULL,generation INTEGER NOT NULL,pid INTEGER NOT NULL,host TEXT NOT NULL,process_start TEXT NOT NULL,heartbeat_at TEXT NOT NULL,run_id TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS legacy_imports(source_path TEXT NOT NULL,digest TEXT NOT NULL,run_id TEXT NOT NULL,imported_at TEXT NOT NULL,PRIMARY KEY(source_path,digest));
       CREATE TABLE IF NOT EXISTS publication_transactions(transaction_id TEXT PRIMARY KEY,run_id TEXT NOT NULL,status TEXT NOT NULL,intent_json TEXT NOT NULL,previous_digests_json TEXT NOT NULL,created_at TEXT NOT NULL,updated_at TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS context_samples(sample_id INTEGER PRIMARY KEY AUTOINCREMENT,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),role TEXT NOT NULL,provider_session_id TEXT,session_key TEXT,session_ref_json TEXT,sample_json TEXT NOT NULL,observed_at TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS session_usage_samples(sample_id INTEGER PRIMARY KEY AUTOINCREMENT,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),role TEXT NOT NULL,provider_session_id TEXT,session_key TEXT,session_ref_json TEXT,sample_json TEXT NOT NULL,observed_at TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS live_settings_acknowledgments(run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),role TEXT NOT NULL,provider_session_id TEXT,session_key TEXT,session_ref_json TEXT,revision INTEGER NOT NULL,acknowledged_at TEXT NOT NULL,PRIMARY KEY(run_id,role,revision));
+      CREATE TABLE IF NOT EXISTS live_settings_session_acknowledgments(run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),role TEXT NOT NULL,provider_session_id TEXT,session_key TEXT NOT NULL,session_ref_json TEXT,revision INTEGER NOT NULL,acknowledged_at TEXT NOT NULL,PRIMARY KEY(run_id,role,session_key,revision));
+      CREATE TABLE IF NOT EXISTS continuity_events(sequence INTEGER PRIMARY KEY AUTOINCREMENT,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),role TEXT NOT NULL,kind TEXT NOT NULL,payload_json TEXT NOT NULL,digest TEXT NOT NULL UNIQUE,authoritative_state_revision INTEGER NOT NULL,session_key TEXT,session_ref_json TEXT,created_at TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS continuity_checkpoints(checkpoint_id INTEGER PRIMARY KEY AUTOINCREMENT,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),role TEXT NOT NULL,event_sequence INTEGER NOT NULL,state TEXT NOT NULL,delta_json TEXT NOT NULL,digest TEXT NOT NULL UNIQUE,predecessor_digest TEXT,authoritative_state_revision INTEGER NOT NULL,session_key TEXT,session_ref_json TEXT,created_at TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS continuity_heads(run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),role TEXT NOT NULL,state TEXT NOT NULL,event_sequence INTEGER NOT NULL,digest TEXT NOT NULL,authoritative_state_revision INTEGER NOT NULL,updated_at TEXT NOT NULL,PRIMARY KEY(run_id,role));
+      CREATE TABLE IF NOT EXISTS handoffs(run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),generation INTEGER NOT NULL,role TEXT NOT NULL,manifest_digest TEXT NOT NULL,markdown_digest TEXT NOT NULL,predecessor_session_id TEXT,predecessor_session_key TEXT,predecessor_session_ref_json TEXT,successor_session_id TEXT,successor_session_key TEXT,successor_session_ref_json TEXT,state TEXT NOT NULL,failure TEXT,created_at TEXT NOT NULL,accepted_at TEXT,PRIMARY KEY(run_id,generation));
+      CREATE TABLE IF NOT EXISTS role_mutation_leases(run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),role TEXT NOT NULL,generation INTEGER NOT NULL,provider_session_id TEXT NOT NULL,provider_session_key TEXT,provider_session_ref_json TEXT,moved_at TEXT NOT NULL,PRIMARY KEY(run_id,role));
+      CREATE TABLE IF NOT EXISTS compaction_attempts(idempotency_key TEXT PRIMARY KEY,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),role TEXT NOT NULL,provider_session_id TEXT,session_key TEXT,session_ref_json TEXT,crossing_key TEXT NOT NULL,status TEXT NOT NULL,before_sample_json TEXT,after_sample_json TEXT,error TEXT,origin TEXT NOT NULL DEFAULT 'rafi-manual',provider_event_id TEXT,threshold_generation_id TEXT,created_at TEXT NOT NULL,updated_at TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS threshold_generations(generation_id TEXT PRIMARY KEY,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),role TEXT NOT NULL,provider_session_id TEXT,session_key TEXT,session_ref_json TEXT,generation INTEGER NOT NULL,state TEXT NOT NULL,configured_ceiling_percent REAL NOT NULL,installed_native_token_limit INTEGER,installed_native_percent REAL,settings_revision INTEGER NOT NULL,model TEXT NOT NULL,latest_sample_json TEXT,frozen_action_digest TEXT,provider_event_id TEXT,created_at TEXT NOT NULL,updated_at TEXT NOT NULL,UNIQUE(run_id,role,session_key,generation));
+      CREATE TABLE IF NOT EXISTS active_role_adapter_sessions(run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),role TEXT NOT NULL,provider_session_id TEXT,session_key TEXT NOT NULL,settings_revision INTEGER NOT NULL,observed_at TEXT NOT NULL,PRIMARY KEY(run_id,role,session_key));
+      CREATE TABLE IF NOT EXISTS recovery_decisions(decision_id INTEGER PRIMARY KEY AUTOINCREMENT,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),decided_at TEXT NOT NULL,mode TEXT NOT NULL,digest TEXT NOT NULL UNIQUE,session_key TEXT,session_ref_json TEXT,receipt_json TEXT NOT NULL);
       CREATE INDEX IF NOT EXISTS workflow_events_run ON workflow_events(run_id,sequence);
       CREATE INDEX IF NOT EXISTS operations_run ON operation_journal(run_id,status);
+      CREATE INDEX IF NOT EXISTS context_samples_run_role ON context_samples(run_id,role,sample_id);
+      CREATE INDEX IF NOT EXISTS continuity_events_run ON continuity_events(run_id,sequence);
+      CREATE INDEX IF NOT EXISTS continuity_checkpoints_run_role ON continuity_checkpoints(run_id,role,checkpoint_id);
+      CREATE INDEX IF NOT EXISTS compaction_session ON compaction_attempts(run_id,role,provider_session_id,status);
     `);
+        for (const [table, columns] of Object.entries({
+            provider_sessions: { session_key: "TEXT", session_ref_json: "TEXT" },
+            context_samples: { session_key: "TEXT", session_ref_json: "TEXT" },
+            session_usage_samples: { session_key: "TEXT", session_ref_json: "TEXT" },
+            live_settings_acknowledgments: { session_key: "TEXT", session_ref_json: "TEXT" },
+            continuity_events: { session_key: "TEXT", session_ref_json: "TEXT" },
+            continuity_checkpoints: { session_key: "TEXT", session_ref_json: "TEXT" },
+            handoffs: { predecessor_session_key: "TEXT", predecessor_session_ref_json: "TEXT", successor_session_key: "TEXT", successor_session_ref_json: "TEXT" },
+            role_mutation_leases: { provider_session_key: "TEXT", provider_session_ref_json: "TEXT" },
+            compaction_attempts: { session_key: "TEXT", session_ref_json: "TEXT", origin: "TEXT NOT NULL DEFAULT 'rafi-manual'", provider_event_id: "TEXT", threshold_generation_id: "TEXT" },
+            recovery_decisions: { session_key: "TEXT", session_ref_json: "TEXT" },
+        })) {
+            for (const [column, definition] of Object.entries(columns))
+                this.ensureColumn(table, column, definition);
+        }
+        this.db.exec(`
+      CREATE INDEX IF NOT EXISTS provider_sessions_scoped ON provider_sessions(run_id,role,session_key,id);
+      CREATE INDEX IF NOT EXISTS provider_session_bindings_id ON provider_session_bindings(provider_session_id,role,observed_at);
+      CREATE INDEX IF NOT EXISTS context_samples_scoped ON context_samples(run_id,role,session_key,sample_id);
+      CREATE INDEX IF NOT EXISTS session_usage_scoped ON session_usage_samples(run_id,role,session_key,sample_id);
+      CREATE INDEX IF NOT EXISTS compaction_session_scoped ON compaction_attempts(run_id,role,session_key,status);
+      CREATE UNIQUE INDEX IF NOT EXISTS compaction_native_event_unique ON compaction_attempts(run_id,role,session_key,provider_event_id) WHERE provider_event_id IS NOT NULL;
+      CREATE INDEX IF NOT EXISTS threshold_generation_scoped ON threshold_generations(run_id,role,session_key,generation);
+      CREATE INDEX IF NOT EXISTS active_role_adapter_session_observed ON active_role_adapter_sessions(observed_at,run_id,role);
+      CREATE INDEX IF NOT EXISTS live_settings_session_revision ON live_settings_session_acknowledgments(revision,run_id,role,session_key);
+    `);
+    }
+    ensureColumn(table, column, definition) {
+        const columns = this.db.prepare(`PRAGMA table_info(${table})`).all();
+        if (!columns.some((entry) => entry.name === column))
+            this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`);
     }
 }
 function rowToRun(row) { return { runId: row.run_id, kind: row.kind, status: row.status, checkpoint: row.checkpoint, originalWork: parseJson(row.original_work_json), remainingWork: parseJson(row.remaining_work_json), state: parseJson(row.state_json), ...(row.lease_generation === null ? {} : { leaseGeneration: row.lease_generation }), legacy: Boolean(row.legacy), createdAt: row.created_at, updatedAt: row.updated_at }; }
 function operationFromRow(row) { return { idempotencyKey: row.idempotency_key, runId: row.run_id, kind: row.kind, status: row.status, intent: parseJson(row.intent_json), ...(row.result_json ? { result: parseJson(row.result_json) } : {}), ...(row.external_id ? { externalId: row.external_id } : {}), ...(row.error ? { error: row.error } : {}), createdAt: row.created_at, updatedAt: row.updated_at }; }
+function continuityEventFromRow(row) { return { sequence: row.sequence, runId: row.run_id, role: row.role, kind: row.kind, payload: parseJson(row.payload_json), digest: row.digest, authoritativeStateRevision: row.authoritative_state_revision, createdAt: row.created_at, ...(row.session_key ? { sessionKey: row.session_key } : {}), ...(row.session_ref_json ? { sessionRef: parseJson(row.session_ref_json) } : {}) }; }
+function continuityCheckpointFromRow(row) { return { checkpointId: row.checkpoint_id, runId: row.run_id, role: row.role, sequence: row.event_sequence, state: row.state, delta: parseJson(row.delta_json), digest: row.digest, ...(row.predecessor_digest ? { predecessorDigest: row.predecessor_digest } : {}), authoritativeStateRevision: row.authoritative_state_revision, createdAt: row.created_at, ...(row.session_key ? { sessionKey: row.session_key } : {}), ...(row.session_ref_json ? { sessionRef: parseJson(row.session_ref_json) } : {}) }; }
+function continuityHeadFromRow(row) { return { runId: row.run_id, role: row.role, state: row.state, sequence: row.event_sequence, digest: row.digest, authoritativeStateRevision: row.authoritative_state_revision, updatedAt: row.updated_at }; }
+function handoffFromRow(row) { return { runId: row.run_id, generation: row.generation, manifestDigest: row.manifest_digest, markdownDigest: row.markdown_digest, ...(row.predecessor_session_id ? { predecessorSessionId: row.predecessor_session_id } : {}), ...(row.predecessor_session_ref_json ? { predecessorSessionRef: parseJson(row.predecessor_session_ref_json) } : {}), ...(row.successor_session_id ? { successorSessionId: row.successor_session_id } : {}), ...(row.successor_session_ref_json ? { successorSessionRef: parseJson(row.successor_session_ref_json) } : {}), state: row.state, createdAt: row.created_at, ...(row.accepted_at ? { acceptedAt: row.accepted_at } : {}) }; }
+function compactionAttemptFromRow(row) { return { idempotencyKey: row.idempotency_key, runId: row.run_id, role: row.role, ...(row.provider_session_id ? { providerSessionId: row.provider_session_id } : {}), ...(row.session_key ? { sessionKey: row.session_key } : {}), ...(row.session_ref_json ? { sessionRef: parseJson(row.session_ref_json) } : {}), crossingKey: row.crossing_key, status: row.status, origin: row.origin ?? "rafi-manual", ...(row.provider_event_id ? { providerEventId: row.provider_event_id } : {}), ...(row.threshold_generation_id ? { thresholdGenerationId: row.threshold_generation_id } : {}), ...(row.before_sample_json ? { beforeSample: parseJson(row.before_sample_json) } : {}), ...(row.after_sample_json ? { afterSample: parseJson(row.after_sample_json) } : {}), ...(row.error ? { error: row.error } : {}), createdAt: row.created_at, updatedAt: row.updated_at }; }
+function thresholdGenerationFromRow(row) {
+    return {
+        generationId: row.generation_id, runId: row.run_id, role: row.role,
+        ...(row.provider_session_id ? { providerSessionId: row.provider_session_id } : {}),
+        ...(row.session_key ? { sessionKey: row.session_key } : {}),
+        ...(row.session_ref_json ? { sessionRef: parseJson(row.session_ref_json) } : {}),
+        generation: row.generation, state: row.state, configuredCeilingPercent: row.configured_ceiling_percent,
+        ...(row.installed_native_token_limit === null ? {} : { installedNativeTokenLimit: row.installed_native_token_limit }),
+        ...(row.installed_native_percent === null ? {} : { installedNativePercent: row.installed_native_percent }),
+        settingsRevision: row.settings_revision, model: row.model,
+        ...(row.latest_sample_json ? { latestSample: parseJson(row.latest_sample_json) } : {}),
+        ...(row.frozen_action_digest ? { frozenActionDigest: row.frozen_action_digest } : {}),
+        ...(row.provider_event_id ? { providerEventId: row.provider_event_id } : {}),
+        createdAt: row.created_at, updatedAt: row.updated_at,
+    };
+}
 function json(value) { return JSON.stringify(value ?? null); }
 function parseJson(value) { return JSON.parse(value); }
+function sessionParts(ref, rawId, suppliedKey) {
+    const key = ref ? providerSessionKey(ref) : suppliedKey;
+    return { id: ref?.sessionId ?? rawId ?? null, key: key ?? null, ...(ref ? { ref } : {}), refJson: ref ? json(ref) : null };
+}
 function sanitizeText(value) { return value.replace(/\b(sk-[A-Za-z0-9_-]{12,}|(?:api[_-]?key|token|password)\s*[:=]\s*\S+)/gi, "[REDACTED]"); }
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    if (value && typeof value === "object")
+        return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`).join(",")}}`;
+    return JSON.stringify(value ?? null);
+}
+function digestJson(value) { return createHash("sha256").update(stableJson(value)).digest("hex"); }
+function sanitizeContinuityValue(value, depth = 0) {
+    if (depth > 12)
+        return "[TRUNCATED]";
+    if (typeof value === "string")
+        return sanitizeText(value).slice(0, 20_000);
+    if (Array.isArray(value))
+        return value.slice(0, 500).map((entry) => sanitizeContinuityValue(entry, depth + 1));
+    if (value && typeof value === "object")
+        return Object.fromEntries(Object.entries(value).filter(([key]) => !/^(credential|secret|hidden_reasoning|raw_transcript|api_key|token|password)$/i.test(key)).slice(0, 500).map(([key, entry]) => [key, sanitizeContinuityValue(entry, depth + 1)]));
+    return value;
+}
 function processStartIdentity(pid = process.pid) { try {
     return readFileSync(`/proc/${pid}/stat`, "utf8").split(" ")[21] ?? "unavailable";
 }
@@ -279,7 +840,7 @@ function leaseVerifiedLive(lease, now, staleMs) {
 function ensureRecoveryGitignore(projectDir) {
     const localExclude = join(projectDir, ".git", "info", "exclude");
     const path = existsSync(localExclude) ? localExclude : join(projectDir, ".gitignore");
-    const entries = [WORKFLOW_DB_FILE, `${WORKFLOW_DB_FILE}-wal`, `${WORKFLOW_DB_FILE}-shm`];
+    const entries = [WORKFLOW_DB_FILE, `${WORKFLOW_DB_FILE}-wal`, `${WORKFLOW_DB_FILE}-shm`, ".rafi/cache/handoffs/"];
     const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
     const missing = entries.filter((entry) => !existing.split(/\r?\n/).includes(entry));
     if (missing.length)