conductor-remote 1.116.0 → 1.118.0

package/dist-node/src/orchestration/persistence/jobs.js

@@ -0,0 +1,159 @@
+import { randomUUID } from 'node:crypto';
+import { and, asc, eq, notInArray } from 'drizzle-orm';
+import { isTerminalWorkflowJobState, isTerminalWorkflowPhase } from "../workflow/machine.js";
+import { decodeJob } from "./codecs.js";
+import { WorkflowTransitionError } from "./errors.js";
+import { appendEvent, touchRun } from "./events.js";
+import { canonicalRequestJson } from "./idempotency.js";
+import { checkRunGuard, requireJob, requireRun } from "./records.js";
+import { workflowJobs, workflowRuns } from "./schema.js";
+import { asObject, json, optionalJson, ownerAuditKey, probeAlive, RUNNABLE_PHASES, sameOwner, validateRelayIdentity } from "./values.js";
+export function insertJob(context, input) {
+    context.db
+        .prepare(`INSERT INTO workflow_jobs (
+				id, run_id, logical_key, role, cycle, revision, resolved_role_json, prompt, state, cancellation_generation,
+				transcript_cursor_json, created_at, updated_at
+			) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(input.id, input.runId, input.logicalKey, input.role, input.cycle, input.revision, json(input.resolvedRole), input.prompt, input.state, input.cancellationGeneration, optionalJson(input.transcriptCursor), input.at, input.at);
+}
+export function createWorkflowJob(context, input) {
+    return context.immediate(() => {
+        const run = requireRun(context, input.runId);
+        checkRunGuard(run, RUNNABLE_PHASES, input.expectedCancellationGeneration);
+        const existing = context.orm
+            .select()
+            .from(workflowJobs)
+            .where(and(eq(workflowJobs.runId, input.runId), eq(workflowJobs.logicalKey, input.logicalKey)))
+            .get();
+        if (existing) {
+            const decoded = decodeJob(existing);
+            if (decoded.role !== input.role ||
+                decoded.cycle !== (input.cycle ?? run.cycle) ||
+                decoded.revision !== (input.revision ?? run.revision) ||
+                canonicalRequestJson(decoded.resolvedRole) !== canonicalRequestJson(input.resolvedRole) ||
+                decoded.prompt !== input.prompt) {
+                throw new WorkflowTransitionError(`logical job ${input.logicalKey} already has different frozen inputs`);
+            }
+            return { created: false, job: decoded };
+        }
+        const id = input.id ?? randomUUID();
+        const at = context.now();
+        insertJob(context, {
+            ...input,
+            id,
+            cycle: input.cycle ?? run.cycle,
+            revision: input.revision ?? run.revision,
+            state: input.state ?? 'queued',
+            cancellationGeneration: run.cancellationGeneration,
+            at
+        });
+        touchRun(context, input.runId, at);
+        appendEvent(context, input.runId, input.eventKey, 'workflow_job_created', {
+            jobId: id,
+            logicalKey: input.logicalKey,
+            role: input.role,
+            cycle: input.cycle ?? run.cycle,
+            revision: input.revision ?? run.revision,
+            state: input.state ?? 'queued'
+        });
+        return { created: true, job: requireJob(context, id) };
+    });
+}
+export function activateWorkflowJob(context, jobId, expectedCancellationGeneration, eventKey, transcriptCursor) {
+    return updateWorkflowJob(context, {
+        jobId,
+        expectedStates: ['dormant'],
+        expectedCancellationGeneration,
+        state: 'queued',
+        ...(transcriptCursor === undefined ? {} : { transcriptCursor }),
+        eventKey,
+        eventType: 'workflow_job_activated'
+    });
+}
+export function claimNextWorkflowJob(context, owner, runId) {
+    validateRelayIdentity(owner);
+    return context.immediate(() => {
+        const row = context.orm
+            .select({ job: workflowJobs })
+            .from(workflowJobs)
+            .innerJoin(workflowRuns, eq(workflowRuns.id, workflowJobs.runId))
+            .where(and(eq(workflowJobs.state, 'queued'), eq(workflowJobs.cancellationGeneration, workflowRuns.cancellationGeneration), notInArray(workflowRuns.phase, ['blocked', 'completed', 'cancelled']), runId === undefined ? undefined : eq(workflowJobs.runId, runId)))
+            .orderBy(asc(workflowJobs.createdAt), asc(workflowJobs.id))
+            .limit(1)
+            .get()?.job;
+        if (!row)
+            return undefined;
+        const at = context.now();
+        const result = context.db
+            .prepare(`UPDATE workflow_jobs SET state = 'owned', owner_instance_id = ?, owner_pid = ?,
+					owner_process_started_at = ?, owner_protocol_version = ?, updated_at = ?
+				 WHERE id = ? AND state = 'queued'`)
+            .run(owner.instanceId, owner.pid, owner.processStartedAt, owner.protocolVersion, at, row.id);
+        if (Number(result.changes) !== 1)
+            return undefined;
+        touchRun(context, row.runId, at);
+        appendEvent(context, row.runId, `job_claimed:${row.id}:${row.attemptCount + 1}:${ownerAuditKey(owner)}`, 'workflow_job_claimed', {
+            jobId: row.id,
+            ownerInstanceId: owner.instanceId
+        });
+        return requireJob(context, row.id);
+    });
+}
+/** Requeue only the pre-effect `owned` state after exact process death is proven. */
+export function reconcileAbandonedWorkflowJobClaim(context, input) {
+    const observed = requireJob(context, input.jobId);
+    if (!observed.owner || observed.state !== 'owned')
+        return { status: 'unsafe', job: observed };
+    const observedOwner = observed.owner;
+    const probe = input.processProbe ?? context.processProbe;
+    if (probeAlive(observedOwner, probe))
+        return { status: 'owner_alive', job: observed };
+    return context.immediate(() => {
+        const current = requireJob(context, input.jobId);
+        if (current.state !== 'owned' ||
+            !current.owner ||
+            !sameOwner(current.owner, observedOwner) ||
+            current.attemptCount !== observed.attemptCount) {
+            return { status: 'changed', job: current };
+        }
+        const at = context.now();
+        context.db
+            .prepare(`UPDATE workflow_jobs SET state = 'queued', owner_instance_id = NULL, owner_pid = NULL,
+					owner_process_started_at = NULL, owner_protocol_version = NULL, updated_at = ? WHERE id = ?`)
+            .run(at, current.id);
+        touchRun(context, current.runId, at);
+        appendEvent(context, current.runId, `${input.eventKey}:${ownerAuditKey(observedOwner)}`, 'workflow_job_claim_recovered', {
+            jobId: current.id,
+            abandonedInstanceId: observedOwner.instanceId
+        });
+        return { status: 'requeued', job: requireJob(context, current.id) };
+    });
+}
+export function updateWorkflowJob(context, input) {
+    return context.immediate(() => {
+        const job = requireJob(context, input.jobId);
+        const run = requireRun(context, job.runId);
+        if (isTerminalWorkflowPhase(run.phase) || job.state === 'cancelled') {
+            throw new WorkflowTransitionError(`cannot advance terminal job ${job.id}`);
+        }
+        checkRunGuard(run, undefined, input.expectedCancellationGeneration);
+        if (!input.expectedStates.includes(job.state)) {
+            throw new WorkflowTransitionError(`job ${job.id} is ${job.state}, expected ${input.expectedStates.join(' or ')}`);
+        }
+        const at = context.now();
+        const terminalAt = isTerminalWorkflowJobState(input.state) ? (job.terminalAt ?? at) : null;
+        const result = context.db
+            .prepare(`UPDATE workflow_jobs SET state = ?, transcript_cursor_json = ?, child_session_id = ?, outcome_json = ?, task_receipt_json = ?,
+					baton_receipt_json = ?, owner_instance_id = ?, owner_pid = ?, owner_process_started_at = ?,
+					owner_protocol_version = ?, updated_at = ?, terminal_at = ?
+				 WHERE id = ? AND state = ? AND cancellation_generation = ?`)
+            .run(input.state, input.transcriptCursor === undefined
+            ? optionalJson(job.transcriptCursor)
+            : optionalJson(input.transcriptCursor), input.childSessionId === undefined ? (job.childSessionId ?? null) : input.childSessionId, input.outcome === undefined ? optionalJson(job.outcome) : optionalJson(input.outcome), input.taskReceipt === undefined ? optionalJson(job.taskReceipt) : optionalJson(input.taskReceipt), input.batonReceipt === undefined ? optionalJson(job.batonReceipt) : optionalJson(input.batonReceipt), input.clearOwner ? null : (job.owner?.instanceId ?? null), input.clearOwner ? null : (job.owner?.pid ?? null), input.clearOwner ? null : (job.owner?.processStartedAt ?? null), input.clearOwner ? null : (job.owner?.protocolVersion ?? null), at, terminalAt, job.id, job.state, input.expectedCancellationGeneration);
+        if (Number(result.changes) !== 1)
+            throw new WorkflowTransitionError(`job ${job.id} changed concurrently`);
+        touchRun(context, job.runId, at);
+        appendEvent(context, job.runId, input.eventKey, input.eventType, { jobId: job.id, ...asObject(input.eventData) });
+        return requireJob(context, job.id);
+    });
+}

package/dist-node/src/orchestration/persistence/projections.js

@@ -0,0 +1,190 @@
+import { desc, inArray, notInArray } from 'drizzle-orm';
+import { isTerminalWorkflowJobState, isTerminalWorkflowPhase } from "../workflow/machine.js";
+import { decodeRun } from "./codecs.js";
+import { appendEvent } from "./events.js";
+import { getWorkflowEffect, getWorkflowRun, listWorkflowJobs } from "./records.js";
+import { workflowRuns } from "./schema.js";
+import { ALL_JOB_STATES } from "./values.js";
+export function getWorkflowProjection(context, runId) {
+    const run = getWorkflowRun(context, runId);
+    return run ? projectRun(context, run) : undefined;
+}
+export function listWorkflowProjections(context, options = {}) {
+    return context.orm
+        .select()
+        .from(workflowRuns)
+        .where(options.includeTerminal ? undefined : notInArray(workflowRuns.phase, ['completed', 'cancelled']))
+        .orderBy(desc(workflowRuns.updatedAt))
+        .all()
+        .map(row => projectRun(context, decodeRun(row)));
+}
+/**
+ * The sidebar keeps the identity of the newest Workflow that touched each live
+ * workspace after that run reaches a terminal phase. Limit the query to the
+ * workspaces on screen and project only one run per workspace: terminal history
+ * is unbounded, while `/api/state` is polled every few seconds.
+ */
+export function listLatestWorkflowProjectionsForWorkspaces(context, workspaceIds) {
+    const ids = [...new Set(workspaceIds.filter(Boolean))];
+    if (!ids.length)
+        return [];
+    const placeholders = ids.map(() => '?').join(', ');
+    const newest = context.db
+        .prepare(`SELECT id FROM (
+				SELECT id, created_at, updated_at,
+					ROW_NUMBER() OVER (
+						PARTITION BY workspace_id
+						ORDER BY created_at DESC, updated_at DESC, id DESC
+					) AS ordinal
+				FROM workflow_runs
+				WHERE workspace_id IN (${placeholders})
+			) WHERE ordinal = 1
+			ORDER BY created_at DESC, updated_at DESC, id DESC`)
+        .all(...ids);
+    if (!newest.length)
+        return [];
+    const rows = context.orm
+        .select()
+        .from(workflowRuns)
+        .where(inArray(workflowRuns.id, newest.map(row => row.id)))
+        .all();
+    const byId = new Map(rows.map(row => [row.id, row]));
+    return newest.flatMap(({ id }) => {
+        const row = byId.get(id);
+        return row ? [projectRun(context, decodeRun(row))] : [];
+    });
+}
+/**
+ * Active runs always need driving. A cancelled run remains wakeable only while
+ * it has durable evidence that can still settle: an external effect whose
+ * outcome is unknown, an accepted outbox receipt awaiting promotion, or a
+ * delivered child turn whose final outcome has not appeared yet.
+ */
+export function listWorkflowRunIdsNeedingWake(context) {
+    return context.db
+        .prepare(`SELECT r.id FROM workflow_runs r
+				 WHERE r.phase NOT IN ('completed', 'cancelled')
+					OR (
+						r.phase = 'cancelled' AND (
+							EXISTS (
+								SELECT 1 FROM workflow_effects e
+								WHERE e.run_id = r.id AND (
+									e.state IN ('dispatched', 'ambiguous') OR
+									(e.state = 'committed' AND json_extract(e.receipt_json, '$.kind') = 'outbox')
+								)
+							) OR EXISTS (
+								SELECT 1 FROM workflow_jobs j
+								WHERE j.run_id = r.id AND j.state = 'cancelled'
+									AND j.child_session_id IS NOT NULL AND j.outcome_json IS NULL
+									AND (
+										json_extract(j.task_receipt_json, '$.kind') = 'message' OR EXISTS (
+											SELECT 1 FROM workflow_effects task
+											WHERE task.job_id = j.id AND task.kind = 'send_task'
+												AND task.state = 'committed'
+												AND json_extract(task.receipt_json, '$.kind') = 'message'
+										)
+									)
+							)
+						)
+					)
+				 ORDER BY r.updated_at DESC, r.id`)
+        .all().map(row => row.id);
+}
+export function projectRun(context, run) {
+    const jobs = listWorkflowJobs(context, run.id);
+    const summary = (role) => {
+        const selected = jobs.filter(job => job.role === role && job.state !== 'cancelled');
+        return {
+            requested: selected.length,
+            running: selected.filter(job => !isTerminalWorkflowJobState(job.state) && job.state !== 'dormant').length,
+            returned: selected.filter(job => job.state === 'returned').length,
+            failed: selected.filter(job => job.state === 'failed').length
+        };
+    };
+    const publicRole = (role) => ({
+        agentType: role.agentType,
+        model: role.model,
+        ...(role.effort === undefined ? {} : { effort: role.effort }),
+        ...(role.fast === undefined ? {} : { fast: role.fast })
+    });
+    const blocked = run.blocked;
+    const candidates = (blocked?.candidates ?? []).slice(0, 20).map(candidate => ({
+        id: candidate.id,
+        title: context.scrubPublicText(candidate.title).slice(0, 200),
+        repo: context.scrubPublicText(candidate.repo).slice(0, 200),
+        createdAt: candidate.createdAt
+    }));
+    const blockedEffect = blocked ? getWorkflowEffect(context, run.id, blocked.actionId) : undefined;
+    const adoptionKind = blocked?.candidates?.[0]?.kind ?? (blockedEffect?.kind === 'create_workspace' ? 'workspace' : 'session');
+    // Risky replay still needs the stable action id when reconciliation found no
+    // candidate. The fixed wire deliberately has no second public effect-id field,
+    // so retain the recovery envelope with an empty candidates array.
+    const exposeRecoveryAction = !!blocked &&
+        (candidates.length > 0 || blocked.retryClass === 'ambiguous') &&
+        (adoptionKind === 'workspace' || adoptionKind === 'session');
+    const outstanding = jobs.some(job => !isTerminalWorkflowJobState(job.state));
+    const implementationReturned = jobs.some(job => job.role === 'implementation' && job.state === 'returned');
+    return {
+        id: run.id,
+        ...(run.workspaceId ? { workspaceId: run.workspaceId } : {}),
+        ...(run.rootSessionId ? { rootSessionId: run.rootSessionId } : {}),
+        phase: run.phase,
+        objectiveExcerpt: context.scrubPublicText(run.objective).slice(0, 240),
+        roles: {
+            planning: publicRole(run.roles.planning),
+            exploration: publicRole(run.roles.exploration),
+            implementation: publicRole(run.roles.implementation)
+        },
+        jobs: { exploration: summary('exploration'), implementation: summary('implementation') },
+        ...(blocked
+            ? {
+                error: {
+                    code: blocked.errorCode,
+                    message: context.scrubPublicText(blocked.message).slice(0, 500),
+                    retryable: blocked.retryClass === 'deterministic'
+                }
+            }
+            : {}),
+        ...(exposeRecoveryAction ? { adoption: { actionId: blocked.actionId, kind: adoptionKind, candidates } } : {}),
+        actions: {
+            canRetry: run.phase === 'blocked' && run.blocked?.retryClass === 'deterministic',
+            canAdopt: run.phase === 'blocked' && candidates.length > 0,
+            canReplayAmbiguous: run.phase === 'blocked' && run.blocked?.retryClass === 'ambiguous',
+            canCancel: !isTerminalWorkflowPhase(run.phase),
+            canComplete: run.phase === 'reviewing' && implementationReturned && !outstanding
+        },
+        createdAt: run.createdAt,
+        updatedAt: run.updatedAt
+    };
+}
+export function compactTerminalRuns(context, options) {
+    return context.immediate(() => {
+        const rows = context.db
+            .prepare(`SELECT id FROM workflow_runs
+				 WHERE phase IN ('completed', 'cancelled') AND terminal_at IS NOT NULL AND terminal_at < ?
+					AND NOT EXISTS (
+						SELECT 1 FROM workflow_events e
+						WHERE e.run_id = workflow_runs.id AND e.type = 'terminal_compacted'
+					)
+				 ORDER BY terminal_at LIMIT ?`)
+            .all(options.olderThan, Math.max(1, Math.min(options.limit ?? 20, 100)));
+        for (const row of rows) {
+            const jobs = listWorkflowJobs(context, row.id);
+            const effects = context.db
+                .prepare('SELECT state, COUNT(*) count FROM workflow_effects WHERE run_id = ? GROUP BY state')
+                .all(row.id);
+            context.db.prepare('DELETE FROM workflow_capabilities WHERE run_id = ?').run(row.id);
+            context.db.prepare('DELETE FROM workflow_jobs WHERE run_id = ?').run(row.id);
+            context.db.prepare('DELETE FROM workflow_effects WHERE run_id = ?').run(row.id);
+            context.db.prepare('DELETE FROM workflow_events WHERE run_id = ?').run(row.id);
+            appendEvent(context, row.id, 'terminal_compacted', 'terminal_compacted', {
+                jobs: Object.fromEntries(['exploration', 'implementation'].map(role => [
+                    role,
+                    Object.fromEntries(ALL_JOB_STATES.map(state => [state, jobs.filter(job => job.role === role && job.state === state).length]))
+                ])),
+                effects: Object.fromEntries(effects.map(effect => [effect.state, effect.count]))
+            });
+        }
+        return rows.length;
+    });
+}

package/dist-node/src/orchestration/persistence/quarantine.js

@@ -0,0 +1,46 @@
+import { eq } from 'drizzle-orm';
+import { OrchestrationError } from "./errors.js";
+import { uiQuarantine, uiQuarantineSelectSchema } from "./schema.js";
+import { externalFromColumns, nonEmpty, ownerFromColumns } from "./values.js";
+export function activateUiQuarantine(context, input) {
+    return context.immediate(() => {
+        const current = getUiQuarantine(context);
+        if (current.active)
+            return current;
+        const at = context.now();
+        context.db
+            .prepare(`UPDATE ui_quarantine SET active = 1, action_id = ?, effect_id = ?, reason = ?,
+					owner_instance_id = ?, owner_pid = ?, owner_process_started_at = ?, owner_protocol_version = ?,
+					external_pid = ?, external_process_started_at = ?, external_process_group = ?,
+					created_at = ?, cleared_at = NULL, cleared_by = NULL WHERE id = 1`)
+            .run(input.actionId, input.effectId ?? null, nonEmpty(input.reason, 'quarantine reason'), input.owner?.instanceId ?? null, input.owner?.pid ?? null, input.owner?.processStartedAt ?? null, input.owner?.protocolVersion ?? null, input.externalProcess?.pid ?? null, input.externalProcess?.processStartedAt ?? null, input.externalProcess?.processGroup ?? null, at);
+        return getUiQuarantine(context);
+    });
+}
+export function clearUiQuarantine(context, clearedBy) {
+    return context.immediate(() => {
+        const result = context.db
+            .prepare('UPDATE ui_quarantine SET active = 0, cleared_at = ?, cleared_by = ? WHERE id = 1 AND active = 1')
+            .run(context.now(), nonEmpty(clearedBy, 'quarantine clearer'));
+        return Number(result.changes) === 1;
+    });
+}
+export function getUiQuarantine(context) {
+    const candidate = context.orm.select().from(uiQuarantine).where(eq(uiQuarantine.id, 1)).get();
+    if (!candidate)
+        throw new OrchestrationError('orchestration UI quarantine singleton is missing');
+    const row = uiQuarantineSelectSchema.parse(candidate);
+    const owner = ownerFromColumns(row);
+    const externalProcess = externalFromColumns(row);
+    return {
+        active: row.active,
+        ...(row.actionId === null ? {} : { actionId: row.actionId }),
+        ...(row.effectId === null ? {} : { effectId: row.effectId }),
+        ...(row.reason === null ? {} : { reason: row.reason }),
+        ...(owner ? { owner } : {}),
+        ...(externalProcess ? { externalProcess } : {}),
+        ...(row.createdAt === null ? {} : { createdAt: row.createdAt }),
+        ...(row.clearedAt === null ? {} : { clearedAt: row.clearedAt }),
+        ...(row.clearedBy === null ? {} : { clearedBy: row.clearedBy })
+    };
+}

package/dist-node/src/orchestration/persistence/records.js

@@ -0,0 +1,115 @@
+import { and, asc, eq, notInArray } from 'drizzle-orm';
+import { decodeEffect, decodeEffectAttempt, decodeJob, decodeJobAttempt, decodeRun } from "./codecs.js";
+import { WorkflowTransitionError } from "./errors.js";
+import { workflowEffectAttempts, workflowEffects, workflowJobAttempts, workflowJobs, workflowRuns } from "./schema.js";
+import { sameOwner } from "./values.js";
+export function getWorkflowRun(context, id) {
+    const row = context.orm.select().from(workflowRuns).where(eq(workflowRuns.id, id)).get();
+    return row ? decodeRun(row) : undefined;
+}
+export function findActiveWorkflowByRoot(context, rootSessionId) {
+    const row = context.orm
+        .select()
+        .from(workflowRuns)
+        .where(and(eq(workflowRuns.rootSessionId, rootSessionId), notInArray(workflowRuns.phase, ['completed', 'cancelled'])))
+        .get();
+    return row ? decodeRun(row) : undefined;
+}
+export function requireRun(context, id) {
+    const run = getWorkflowRun(context, id);
+    if (!run)
+        throw new WorkflowTransitionError(`Workflow ${id} does not exist`);
+    return run;
+}
+export function checkRunGuard(run, expectedPhase, expectedCancellationGeneration) {
+    const phases = Array.isArray(expectedPhase) ? expectedPhase : expectedPhase ? [expectedPhase] : undefined;
+    if (phases && !phases.includes(run.phase)) {
+        throw new WorkflowTransitionError(`Workflow ${run.id} is ${run.phase}, expected ${phases.join(' or ')}`);
+    }
+    if (run.cancellationGeneration !== expectedCancellationGeneration) {
+        throw new WorkflowTransitionError(`Workflow ${run.id} cancellation generation changed`);
+    }
+}
+export function getWorkflowJob(context, id) {
+    const row = context.orm.select().from(workflowJobs).where(eq(workflowJobs.id, id)).get();
+    return row ? decodeJob(row) : undefined;
+}
+export function listWorkflowJobs(context, runId) {
+    return context.orm
+        .select()
+        .from(workflowJobs)
+        .where(eq(workflowJobs.runId, runId))
+        .orderBy(asc(workflowJobs.createdAt), asc(workflowJobs.id))
+        .all()
+        .map(row => decodeJob(row));
+}
+export function listWorkflowJobAttempts(context, jobId) {
+    return context.orm
+        .select()
+        .from(workflowJobAttempts)
+        .where(eq(workflowJobAttempts.jobId, jobId))
+        .orderBy(asc(workflowJobAttempts.attemptNumber))
+        .all()
+        .map(row => decodeJobAttempt(row));
+}
+export function requireJob(context, id) {
+    const job = getWorkflowJob(context, id);
+    if (!job)
+        throw new WorkflowTransitionError(`Workflow job ${id} does not exist`);
+    return job;
+}
+export function requireJobAttempt(context, id) {
+    const row = context.orm.select().from(workflowJobAttempts).where(eq(workflowJobAttempts.id, id)).get();
+    if (!row)
+        throw new WorkflowTransitionError(`Workflow job attempt ${id} does not exist`);
+    return decodeJobAttempt(row);
+}
+export function getWorkflowEffect(context, runId, actionId) {
+    const row = context.orm
+        .select()
+        .from(workflowEffects)
+        .where(and(eq(workflowEffects.runId, runId), eq(workflowEffects.actionId, actionId)))
+        .get();
+    return row ? decodeEffect(row) : undefined;
+}
+export function listWorkflowEffects(context, runId) {
+    return context.orm
+        .select()
+        .from(workflowEffects)
+        .where(eq(workflowEffects.runId, runId))
+        .orderBy(asc(workflowEffects.createdAt), asc(workflowEffects.id))
+        .all()
+        .map(row => decodeEffect(row));
+}
+export function requireEffectByAction(context, runId, actionId) {
+    const effect = getWorkflowEffect(context, runId, actionId);
+    if (!effect)
+        throw new WorkflowTransitionError(`Workflow effect ${actionId} does not exist`);
+    return effect;
+}
+export function requireEffect(context, id) {
+    const row = context.orm.select().from(workflowEffects).where(eq(workflowEffects.id, id)).get();
+    if (!row)
+        throw new WorkflowTransitionError(`Workflow effect ${id} does not exist`);
+    return decodeEffect(row);
+}
+export function requireEffectAttempt(context, id) {
+    const row = context.orm.select().from(workflowEffectAttempts).where(eq(workflowEffectAttempts.id, id)).get();
+    if (!row)
+        throw new WorkflowTransitionError(`Workflow effect attempt ${id} does not exist`);
+    return decodeEffectAttempt(row);
+}
+export function listWorkflowEffectAttempts(context, effectId) {
+    return context.orm
+        .select()
+        .from(workflowEffectAttempts)
+        .where(eq(workflowEffectAttempts.effectId, effectId))
+        .orderBy(asc(workflowEffectAttempts.attemptNumber))
+        .all()
+        .map(row => decodeEffectAttempt(row));
+}
+export function requireEffectOwner(effect, owner, attemptNumber) {
+    if (!effect.owner || !sameOwner(effect.owner, owner) || effect.attemptCount !== attemptNumber) {
+        throw new WorkflowTransitionError(`effect ${effect.actionId} is not owned by this relay attempt`);
+    }
+}

package/dist-node/src/orchestration/persistence/relays.js

@@ -0,0 +1,78 @@
+import { asc } from 'drizzle-orm';
+import { OrchestrationError } from "./errors.js";
+import { relayInstanceSelectSchema, relayInstances } from "./schema.js";
+import { jsonProperty, optionalJson, probeAlive, sameOwner, validateRelayIdentity } from "./values.js";
+export function registerRelayInstance(context, input) {
+    validateRelayIdentity(input);
+    return context.immediate(() => {
+        const at = context.now();
+        context.db
+            .prepare(`INSERT INTO relay_instances (
+					instance_id, pid, process_started_at, protocol_version, can_drive_ui,
+					heartbeat_at, registered_at, metadata_json
+				) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+				ON CONFLICT(instance_id) DO UPDATE SET
+					pid = excluded.pid,
+					process_started_at = excluded.process_started_at,
+					protocol_version = excluded.protocol_version,
+					can_drive_ui = excluded.can_drive_ui,
+					heartbeat_at = excluded.heartbeat_at,
+					registered_at = CASE
+						WHEN relay_instances.pid = excluded.pid
+						 AND relay_instances.process_started_at = excluded.process_started_at
+						THEN relay_instances.registered_at ELSE excluded.registered_at END,
+					metadata_json = excluded.metadata_json`)
+            .run(input.instanceId, input.pid, input.processStartedAt, input.protocolVersion, input.canDriveUi === false ? 0 : 1, at, at, optionalJson(input.metadata));
+        return requireRelayInstance(context, input.instanceId);
+    });
+}
+export function heartbeatRelayInstance(context, identity) {
+    return context.immediate(() => {
+        const result = context.db
+            .prepare(`UPDATE relay_instances SET heartbeat_at = ?
+				 WHERE instance_id = ? AND pid = ? AND process_started_at = ? AND protocol_version = ?`)
+            .run(context.now(), identity.instanceId, identity.pid, identity.processStartedAt, identity.protocolVersion);
+        return Number(result.changes) === 1;
+    });
+}
+export function listRelayInstances(context) {
+    return context.orm
+        .select()
+        .from(relayInstances)
+        .orderBy(asc(relayInstances.registeredAt), asc(relayInstances.instanceId))
+        .all()
+        .map(candidate => {
+        const row = relayInstanceSelectSchema.parse(candidate);
+        return {
+            instanceId: row.instanceId,
+            pid: row.pid,
+            processStartedAt: row.processStartedAt,
+            protocolVersion: row.protocolVersion,
+            canDriveUi: row.canDriveUi,
+            heartbeatAt: row.heartbeatAt,
+            registeredAt: row.registeredAt,
+            ...jsonProperty('metadata', row.metadata)
+        };
+    });
+}
+export function findIncompatibleRelayInstances(context, current, probe = context.processProbe) {
+    return listRelayInstances(context).filter(instance => {
+        if (!instance.canDriveUi || sameOwner(instance, current) || instance.protocolVersion === current.protocolVersion)
+            return false;
+        return probeAlive(instance, probe);
+    });
+}
+export function requireRelayInstance(context, instanceId) {
+    const instance = listRelayInstances(context).find(entry => entry.instanceId === instanceId);
+    if (!instance)
+        throw new OrchestrationError(`relay instance ${instanceId} does not exist`);
+    return instance;
+}
+export function assertRelayRegistered(context, owner) {
+    const row = context.db
+        .prepare(`SELECT 1 present FROM relay_instances
+			 WHERE instance_id = ? AND pid = ? AND process_started_at = ? AND protocol_version = ? AND can_drive_ui = 1`)
+        .get(owner.instanceId, owner.pid, owner.processStartedAt, owner.protocolVersion);
+    if (!row)
+        throw new OrchestrationError(`relay ${owner.instanceId} is not registered as this live UI-driving process`);
+}