@femtomc/mu-server 26.2.70 → 26.2.71

package/dist/control_plane_run_queue_coordinator.js

@@ -0,0 +1,327 @@
+import { reconcileRunQueue, runSnapshotFromQueueSnapshot, } from "./run_queue.js";
+const DEFAULT_RUN_MAX_STEPS = 20;
+const MAX_RECONCILE_TURNS = 256;
+function toPositiveInt(value, fallback) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return Math.max(1, Math.trunc(value));
+    }
+    if (typeof value === "string" && /^\d+$/.test(value.trim())) {
+        return Math.max(1, Number.parseInt(value, 10));
+    }
+    return Math.max(1, Math.trunc(fallback));
+}
+function normalizeIssueId(value) {
+    if (!value) {
+        return null;
+    }
+    const trimmed = value.trim();
+    if (!/^mu-[a-z0-9][a-z0-9-]*$/i.test(trimmed)) {
+        return null;
+    }
+    return trimmed.toLowerCase();
+}
+function isTerminalQueueState(state) {
+    return state === "done" || state === "failed" || state === "cancelled";
+}
+function isInFlightQueueState(state) {
+    return state === "active" || state === "waiting_review" || state === "refining";
+}
+/**
+ * Queue/reconcile adapter for control-plane run lifecycle operations.
+ *
+ * Keeps inter-root queue execution concerns out of `control_plane.ts` while preserving
+ * queue-first semantics:
+ * - enqueue intents durably
+ * - reconcile/claim/launch deterministically
+ * - mirror runtime events back into durable queue state
+ */
+export class ControlPlaneRunQueueCoordinator {
+    #runQueue;
+    #interRootQueuePolicy;
+    #getRunSupervisor;
+    #defaultRunMaxSteps;
+    #queuedCommandById = new Map();
+    #queueReconcileCounter = 0;
+    #queueReconcileTail = Promise.resolve();
+    constructor(opts) {
+        this.#runQueue = opts.runQueue;
+        this.#interRootQueuePolicy = opts.interRootQueuePolicy;
+        this.#getRunSupervisor = opts.getRunSupervisor;
+        this.#defaultRunMaxSteps = toPositiveInt(opts.defaultRunMaxSteps, DEFAULT_RUN_MAX_STEPS);
+    }
+    runtimeSnapshotsByJobId() {
+        const map = new Map();
+        for (const run of this.#getRunSupervisor()?.list({ limit: 500 }) ?? []) {
+            map.set(run.job_id, run);
+        }
+        return map;
+    }
+    async #launchQueueEntry(row, opPrefix) {
+        const runSupervisor = this.#getRunSupervisor();
+        if (!runSupervisor) {
+            throw new Error("run_supervisor_unavailable");
+        }
+        const command = row.command_id ? (this.#queuedCommandById.get(row.command_id) ?? null) : null;
+        try {
+            const launched = row.mode === "run_start"
+                ? await runSupervisor.launchStart({
+                    prompt: row.prompt ?? "",
+                    maxSteps: row.max_steps,
+                    command,
+                    commandId: row.command_id,
+                    source: row.source,
+                })
+                : await runSupervisor.launchResume({
+                    rootIssueId: row.root_issue_id ?? "",
+                    maxSteps: row.max_steps,
+                    command,
+                    commandId: row.command_id,
+                    source: row.source,
+                });
+            if (command?.command_id) {
+                this.#queuedCommandById.delete(command.command_id);
+            }
+            const latestSnapshot = runSupervisor.get(launched.job_id) ?? launched;
+            await this.#runQueue.bindRunSnapshot({
+                queueId: row.queue_id,
+                run: latestSnapshot,
+                operationId: `${opPrefix}:bind:${row.queue_id}:${launched.job_id}`,
+            });
+        }
+        catch {
+            if (command?.command_id) {
+                this.#queuedCommandById.delete(command.command_id);
+            }
+            await this.#runQueue.transition({
+                queueId: row.queue_id,
+                toState: "failed",
+                operationId: `${opPrefix}:failed:${row.queue_id}`,
+            });
+        }
+    }
+    async #reconcileQueuedRunsNow(reason) {
+        const runSupervisor = this.#getRunSupervisor();
+        if (!runSupervisor) {
+            return;
+        }
+        for (let turn = 0; turn < MAX_RECONCILE_TURNS; turn += 1) {
+            const rows = await this.#runQueue.list({ limit: 500 });
+            const plan = reconcileRunQueue(rows, this.#interRootQueuePolicy);
+            if (plan.activate_queue_ids.length === 0 && plan.launch_queue_ids.length === 0) {
+                return;
+            }
+            if (plan.activate_queue_ids.length > 0) {
+                for (const queueId of plan.activate_queue_ids) {
+                    await this.#runQueue.claim({
+                        queueId,
+                        operationId: `reconcile:${reason}:activate:${queueId}:${turn}`,
+                    });
+                }
+                continue;
+            }
+            for (const queueId of plan.launch_queue_ids) {
+                const row = await this.#runQueue.get(queueId);
+                if (!row || row.state !== "active") {
+                    continue;
+                }
+                if (row.job_id) {
+                    const existing = runSupervisor.get(row.job_id);
+                    if (existing) {
+                        await this.#runQueue.applyRunSnapshot({
+                            queueId: row.queue_id,
+                            run: existing,
+                            operationId: `reconcile:${reason}:existing:${row.queue_id}:${existing.updated_at_ms}`,
+                        });
+                        continue;
+                    }
+                }
+                await this.#launchQueueEntry(row, `reconcile:${reason}:launch:${turn}`);
+            }
+        }
+    }
+    async scheduleReconcile(reason) {
+        const token = `${++this.#queueReconcileCounter}:${reason}`;
+        this.#queueReconcileTail = this.#queueReconcileTail.then(async () => await this.#reconcileQueuedRunsNow(token), async () => await this.#reconcileQueuedRunsNow(token));
+        return await this.#queueReconcileTail;
+    }
+    async launchQueuedRun(launchOpts) {
+        const runSupervisor = this.#getRunSupervisor();
+        if (!runSupervisor) {
+            throw new Error("run_supervisor_unavailable");
+        }
+        const dedupeKey = launchOpts.dedupeKey.trim();
+        if (!dedupeKey) {
+            throw new Error("run_queue_dedupe_key_required");
+        }
+        const maxSteps = toPositiveInt(launchOpts.maxSteps, this.#defaultRunMaxSteps);
+        const queued = await this.#runQueue.enqueue({
+            mode: launchOpts.mode,
+            prompt: launchOpts.mode === "run_start" ? (launchOpts.prompt ?? null) : null,
+            rootIssueId: launchOpts.mode === "run_resume" ? (launchOpts.rootIssueId ?? null) : null,
+            maxSteps,
+            commandId: launchOpts.command?.command_id ?? null,
+            source: launchOpts.source,
+            dedupeKey,
+            operationId: `enqueue:${dedupeKey}`,
+        });
+        if (launchOpts.command?.command_id) {
+            this.#queuedCommandById.set(launchOpts.command.command_id, launchOpts.command);
+        }
+        await this.scheduleReconcile(`enqueue:${queued.queue_id}`);
+        const refreshed = (await this.#runQueue.get(queued.queue_id)) ?? queued;
+        const runtime = refreshed.job_id ? (runSupervisor.get(refreshed.job_id) ?? null) : null;
+        return runSnapshotFromQueueSnapshot(refreshed, runtime);
+    }
+    async launchQueuedRunFromCommand(record) {
+        if (record.target_type === "run start") {
+            const prompt = record.command_args.join(" ").trim();
+            if (!prompt) {
+                throw new Error("run_start_prompt_required");
+            }
+            return await this.launchQueuedRun({
+                mode: "run_start",
+                prompt,
+                source: "command",
+                command: record,
+                dedupeKey: `command:${record.command_id}`,
+            });
+        }
+        if (record.target_type === "run resume") {
+            const fallbackRoot = normalizeIssueId(record.target_id);
+            const explicitRoot = normalizeIssueId(record.command_args[0] ?? "") ?? fallbackRoot;
+            if (!explicitRoot) {
+                throw new Error("run_resume_invalid_root_issue_id");
+            }
+            const maxSteps = toPositiveInt(record.command_args[1], this.#defaultRunMaxSteps);
+            return await this.launchQueuedRun({
+                mode: "run_resume",
+                rootIssueId: explicitRoot,
+                maxSteps,
+                source: "command",
+                command: record,
+                dedupeKey: `command:${record.command_id}`,
+            });
+        }
+        throw new Error("run_queue_invalid_command_target");
+    }
+    async interruptQueuedRun(opts) {
+        const runSupervisor = this.#getRunSupervisor();
+        const result = runSupervisor?.interrupt(opts) ?? { ok: false, reason: "not_found", run: null };
+        if (result.run) {
+            await this.#runQueue
+                .applyRunSnapshot({
+                run: result.run,
+                operationId: `interrupt-sync:${result.run.job_id}:${result.run.updated_at_ms}`,
+                createIfMissing: true,
+            })
+                .catch(() => {
+                // Best effort only.
+            });
+        }
+        if (result.ok) {
+            return result;
+        }
+        const target = opts.jobId?.trim() || opts.rootIssueId?.trim() || "";
+        if (!target) {
+            return result;
+        }
+        const queued = await this.#runQueue.get(target);
+        if (!queued) {
+            return result;
+        }
+        if (queued.state === "queued" ||
+            queued.state === "active" ||
+            queued.state === "waiting_review" ||
+            queued.state === "refining") {
+            const cancelled = await this.#runQueue.transition({
+                queueId: queued.queue_id,
+                toState: "cancelled",
+                operationId: `interrupt-cancel:${target}`,
+            });
+            await this.scheduleReconcile(`interrupt:${queued.queue_id}`);
+            return {
+                ok: true,
+                reason: null,
+                run: runSnapshotFromQueueSnapshot(cancelled),
+            };
+        }
+        return {
+            ok: false,
+            reason: "not_running",
+            run: runSnapshotFromQueueSnapshot(queued),
+        };
+    }
+    async heartbeatQueuedRun(opts) {
+        const runSupervisor = this.#getRunSupervisor();
+        const result = runSupervisor?.heartbeat(opts) ?? { ok: false, reason: "not_found", run: null };
+        let syncedQueue = null;
+        if (result.run) {
+            syncedQueue = await this.#runQueue
+                .applyRunSnapshot({
+                run: result.run,
+                operationId: `heartbeat-sync:${result.run.job_id}:${result.run.updated_at_ms}`,
+                createIfMissing: true,
+            })
+                .catch(() => {
+                // Best effort only.
+                return null;
+            });
+        }
+        if (result.ok || result.reason === "missing_target") {
+            if (syncedQueue && isTerminalQueueState(syncedQueue.state)) {
+                await this.scheduleReconcile(`heartbeat-terminal:${syncedQueue.queue_id}`);
+            }
+            return result;
+        }
+        const target = opts.jobId?.trim() || opts.rootIssueId?.trim() || "";
+        if (!target) {
+            return result;
+        }
+        const queued = await this.#runQueue.get(target);
+        if (!queued) {
+            return result;
+        }
+        if (result.reason === "not_found" && queued.job_id && isInFlightQueueState(queued.state)) {
+            const failed = await this.#runQueue.transition({
+                queueId: queued.queue_id,
+                toState: "failed",
+                operationId: `heartbeat-fallback:not-found:${queued.queue_id}`,
+            });
+            await this.scheduleReconcile(`heartbeat-fallback:not-found:${queued.queue_id}`);
+            return {
+                ok: false,
+                reason: "not_running",
+                run: runSnapshotFromQueueSnapshot(failed),
+            };
+        }
+        if ((syncedQueue && isTerminalQueueState(syncedQueue.state)) || (result.reason === "not_running" && isInFlightQueueState(queued.state))) {
+            await this.scheduleReconcile(`heartbeat-wake:${queued.queue_id}:${result.reason ?? "unknown"}`);
+        }
+        return {
+            ok: false,
+            reason: "not_running",
+            run: runSnapshotFromQueueSnapshot(queued),
+        };
+    }
+    async onRunEvent(event) {
+        const queueEventSnapshot = await this.#runQueue
+            .applyRunSnapshot({
+            run: event.run,
+            operationId: `run-event:${event.seq}:${event.kind}`,
+            createIfMissing: false,
+        })
+            .catch(() => {
+            // Best effort queue reconciliation from runtime events.
+            return null;
+        });
+        if (event.kind === "run_heartbeat" && queueEventSnapshot && isInFlightQueueState(queueEventSnapshot.state)) {
+            await this.scheduleReconcile(`event-wake:run_heartbeat:${queueEventSnapshot.queue_id}:${event.seq}`);
+        }
+        if (event.kind === "run_completed" || event.kind === "run_failed" || event.kind === "run_cancelled") {
+            await this.scheduleReconcile(`terminal:${event.kind}:${event.run.job_id}`);
+        }
+    }
+    stop() {
+        this.#queuedCommandById.clear();
+    }
+}

package/dist/control_plane_telegram_generation.js

@@ -10,7 +10,6 @@ function controlPlaneNonTelegramFingerprint(config) {
         adapters: {
             slack: config.adapters.slack,
             discord: config.adapters.discord,
-            gmail: config.adapters.gmail,
         },
         operator: config.operator,
     });

package/dist/control_plane_wake_delivery.d.ts

@@ -0,0 +1,50 @@
+import type { Channel, IdentityBinding, OutboundEnvelope } from "@femtomc/mu-control-plane";
+export type WakeFanoutSkipReasonCode = "channel_delivery_unsupported" | "telegram_bot_token_missing";
+export type WakeFanoutContext = {
+    wakeId: string;
+    dedupeKey: string;
+    wakeSource: string | null;
+    programId: string | null;
+    sourceTsMs: number | null;
+};
+export type WakeDeliveryMetadata = {
+    wakeId: string;
+    wakeDedupeKey: string;
+    bindingId: string;
+    channel: Channel;
+    outboxId: string;
+    outboxDedupeKey: string;
+};
+export declare function wakeFanoutDedupeKey(opts: {
+    dedupeKey: string;
+    wakeId: string;
+    binding: Pick<IdentityBinding, "channel" | "binding_id">;
+}): string;
+export declare function resolveWakeFanoutCapability(opts: {
+    binding: IdentityBinding;
+    isChannelDeliverySupported: (channel: Channel) => boolean;
+    telegramBotToken: string | null;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    reasonCode: WakeFanoutSkipReasonCode;
+};
+export declare function buildWakeOutboundEnvelope(opts: {
+    repoRoot: string;
+    nowMs: number;
+    message: string;
+    binding: IdentityBinding;
+    context: WakeFanoutContext;
+    metadata?: Record<string, unknown>;
+}): OutboundEnvelope;
+export declare function wakeDeliveryMetadataFromOutboxRecord(record: {
+    outbox_id: string;
+    dedupe_key: string;
+    envelope: Pick<OutboundEnvelope, "channel" | "metadata">;
+}): WakeDeliveryMetadata | null;
+export declare function wakeDispatchReasonCode(opts: {
+    state: "delivered" | "retried" | "dead_letter";
+    lastError: string | null;
+    deadLetterReason: string | null;
+}): string;

package/dist/control_plane_wake_delivery.js

@@ -0,0 +1,123 @@
+function sha256Hex(input) {
+    const hasher = new Bun.CryptoHasher("sha256");
+    hasher.update(input);
+    return hasher.digest("hex");
+}
+function normalizeString(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function normalizeChannel(value) {
+    switch (value) {
+        case "slack":
+        case "discord":
+        case "telegram":
+        case "terminal":
+            return value;
+        default:
+            return null;
+    }
+}
+export function wakeFanoutDedupeKey(opts) {
+    const base = opts.dedupeKey.trim().length > 0 ? opts.dedupeKey.trim() : `wake:${opts.wakeId}`;
+    return `${base}:wake:${opts.wakeId}:${opts.binding.channel}:${opts.binding.binding_id}`;
+}
+export function resolveWakeFanoutCapability(opts) {
+    const { binding } = opts;
+    if (!opts.isChannelDeliverySupported(binding.channel)) {
+        return { ok: false, reasonCode: "channel_delivery_unsupported" };
+    }
+    if (binding.channel === "telegram" && (!opts.telegramBotToken || opts.telegramBotToken.trim().length === 0)) {
+        return { ok: false, reasonCode: "telegram_bot_token_missing" };
+    }
+    return { ok: true };
+}
+export function buildWakeOutboundEnvelope(opts) {
+    const channelConversationId = opts.binding.channel_actor_id;
+    const requestId = `wake-req-${sha256Hex(`${opts.context.wakeId}:${opts.binding.binding_id}`).slice(0, 20)}`;
+    const responseId = `wake-resp-${sha256Hex(`${opts.context.wakeId}:${opts.binding.binding_id}:${opts.nowMs}`).slice(0, 20)}`;
+    return {
+        v: 1,
+        ts_ms: opts.nowMs,
+        channel: opts.binding.channel,
+        channel_tenant_id: opts.binding.channel_tenant_id,
+        channel_conversation_id: channelConversationId,
+        request_id: requestId,
+        response_id: responseId,
+        kind: "lifecycle",
+        body: opts.message,
+        correlation: {
+            command_id: `wake-${opts.context.wakeId}-${opts.binding.binding_id}`,
+            idempotency_key: `wake-idem-${opts.context.wakeId}-${opts.binding.binding_id}`,
+            request_id: requestId,
+            channel: opts.binding.channel,
+            channel_tenant_id: opts.binding.channel_tenant_id,
+            channel_conversation_id: channelConversationId,
+            actor_id: opts.binding.channel_actor_id,
+            actor_binding_id: opts.binding.binding_id,
+            assurance_tier: opts.binding.assurance_tier,
+            repo_root: opts.repoRoot,
+            scope_required: "cp.ops.admin",
+            scope_effective: "cp.ops.admin",
+            target_type: "operator_wake",
+            target_id: opts.context.wakeId,
+            attempt: 1,
+            state: "completed",
+            error_code: null,
+            operator_session_id: null,
+            operator_turn_id: null,
+            cli_invocation_id: null,
+            cli_command_kind: null,
+            run_root_id: null,
+        },
+        metadata: {
+            wake_delivery: true,
+            wake_id: opts.context.wakeId,
+            wake_dedupe_key: opts.context.dedupeKey,
+            wake_binding_id: opts.binding.binding_id,
+            wake_channel: opts.binding.channel,
+            wake_source: opts.context.wakeSource,
+            wake_program_id: opts.context.programId,
+            wake_source_ts_ms: opts.context.sourceTsMs,
+            ...(opts.metadata ?? {}),
+        },
+    };
+}
+export function wakeDeliveryMetadataFromOutboxRecord(record) {
+    const metadata = record.envelope.metadata;
+    if (metadata.wake_delivery !== true) {
+        return null;
+    }
+    const wakeId = normalizeString(metadata.wake_id);
+    const bindingId = normalizeString(metadata.wake_binding_id);
+    const wakeDedupeKey = normalizeString(metadata.wake_dedupe_key) ?? record.dedupe_key;
+    const metadataChannel = normalizeChannel(metadata.wake_channel);
+    const envelopeChannel = normalizeChannel(record.envelope.channel);
+    const channel = metadataChannel ?? envelopeChannel;
+    if (!wakeId || !bindingId || !channel) {
+        return null;
+    }
+    return {
+        wakeId,
+        wakeDedupeKey,
+        bindingId,
+        channel,
+        outboxId: record.outbox_id,
+        outboxDedupeKey: record.dedupe_key,
+    };
+}
+export function wakeDispatchReasonCode(opts) {
+    switch (opts.state) {
+        case "delivered":
+            return "outbox_delivered";
+        case "retried":
+            return opts.lastError && opts.lastError.trim().length > 0 ? opts.lastError : "outbox_retry";
+        case "dead_letter":
+            return opts.deadLetterReason && opts.deadLetterReason.trim().length > 0
+                ? opts.deadLetterReason
+                : "outbox_dead_letter";
+    }
+}

package/dist/index.d.ts

@@ -2,7 +2,10 @@ export type { ControlPlaneActivityEvent, ControlPlaneActivityEventKind, ControlP
 export { ControlPlaneActivitySupervisor } from "./activity_supervisor.js";
 export type { MuConfig, MuConfigPatch, MuConfigPresence } from "./config.js";
 export { applyMuConfigPatch, DEFAULT_MU_CONFIG, getMuConfigPath, muConfigPresence, normalizeMuConfig, readMuConfigFile, redactMuConfigSecrets, writeMuConfigFile, } from "./config.js";
-export type { ActiveAdapter, ControlPlaneConfig, ControlPlaneHandle, ControlPlaneSessionLifecycle, ControlPlaneSessionMutationAction, ControlPlaneSessionMutationResult, } from "./control_plane_contract.js";
+export type { ActiveAdapter, ControlPlaneConfig, ControlPlaneHandle, ControlPlaneSessionLifecycle, ControlPlaneSessionMutationAction, ControlPlaneSessionMutationResult, InterRootQueuePolicy, NotifyOperatorsOpts, NotifyOperatorsResult, OrchestrationQueueState, WakeDeliveryEvent, WakeNotifyContext, WakeNotifyDecision, } from "./control_plane_contract.js";
+export { DEFAULT_INTER_ROOT_QUEUE_POLICY, normalizeInterRootQueuePolicy, ORCHESTRATION_QUEUE_ALLOWED_TRANSITIONS, ORCHESTRATION_QUEUE_INVARIANTS, } from "./control_plane_contract.js";
+export type { DurableRunQueueClaimOpts, DurableRunQueueEnqueueOpts, DurableRunQueueOpts, DurableRunQueueSnapshot, DurableRunQueueState, DurableRunQueueTransitionOpts, RunQueueReconcilePlan, } from "./run_queue.js";
+export { DurableRunQueue, queueStatesForRunStatusFilter, reconcileRunQueue, RUN_QUEUE_RECONCILE_INVARIANTS, runQueuePath, runSnapshotFromQueueSnapshot, runStatusFromQueueState, } from "./run_queue.js";
 export { bootstrapControlPlane, detectAdapters } from "./control_plane.js";
 export type { CronProgramLifecycleAction, CronProgramLifecycleEvent, CronProgramOperationResult, CronProgramRegistryOpts, CronProgramSnapshot, CronProgramStatusSnapshot, CronProgramTarget, CronProgramTickEvent, CronProgramWakeMode, } from "./cron_programs.js";
 export { CronProgramRegistry } from "./cron_programs.js";

package/dist/index.js

@@ -1,5 +1,7 @@
 export { ControlPlaneActivitySupervisor } from "./activity_supervisor.js";
 export { applyMuConfigPatch, DEFAULT_MU_CONFIG, getMuConfigPath, muConfigPresence, normalizeMuConfig, readMuConfigFile, redactMuConfigSecrets, writeMuConfigFile, } from "./config.js";
+export { DEFAULT_INTER_ROOT_QUEUE_POLICY, normalizeInterRootQueuePolicy, ORCHESTRATION_QUEUE_ALLOWED_TRANSITIONS, ORCHESTRATION_QUEUE_INVARIANTS, } from "./control_plane_contract.js";
+export { DurableRunQueue, queueStatesForRunStatusFilter, reconcileRunQueue, RUN_QUEUE_RECONCILE_INVARIANTS, runQueuePath, runSnapshotFromQueueSnapshot, runStatusFromQueueState, } from "./run_queue.js";
 export { bootstrapControlPlane, detectAdapters } from "./control_plane.js";
 export { CronProgramRegistry } from "./cron_programs.js";
 export { computeNextScheduleRunAtMs, normalizeCronSchedule } from "./cron_schedule.js";

package/dist/run_queue.d.ts

@@ -0,0 +1,95 @@
+import type { JsonlStore } from "@femtomc/mu-core";
+import { type InterRootQueuePolicy, type InterRootQueueReconcilePlan, type OrchestrationQueueState } from "@femtomc/mu-orchestrator";
+import type { ControlPlaneRunMode, ControlPlaneRunSnapshot, ControlPlaneRunStatus } from "./run_supervisor.js";
+export type DurableRunQueueState = OrchestrationQueueState;
+export type DurableRunQueueSnapshot = {
+    v: 1;
+    queue_id: string;
+    dedupe_key: string;
+    mode: ControlPlaneRunMode;
+    state: DurableRunQueueState;
+    prompt: string | null;
+    root_issue_id: string | null;
+    max_steps: number;
+    command_id: string | null;
+    source: "command" | "api";
+    job_id: string | null;
+    started_at_ms: number | null;
+    updated_at_ms: number;
+    finished_at_ms: number | null;
+    exit_code: number | null;
+    pid: number | null;
+    last_progress: string | null;
+    created_at_ms: number;
+    revision: number;
+    applied_operation_ids: string[];
+};
+export type DurableRunQueueOpts = {
+    repoRoot: string;
+    nowMs?: () => number;
+    store?: JsonlStore<unknown>;
+    maxOperationIds?: number;
+};
+export type DurableRunQueueEnqueueOpts = {
+    mode: ControlPlaneRunMode;
+    prompt: string | null;
+    rootIssueId: string | null;
+    maxSteps?: number;
+    commandId?: string | null;
+    source: "command" | "api";
+    dedupeKey: string;
+    operationId?: string | null;
+    nowMs?: number;
+};
+export type DurableRunQueueTransitionOpts = {
+    queueId: string;
+    toState: DurableRunQueueState;
+    operationId?: string | null;
+    nowMs?: number;
+};
+export type DurableRunQueueClaimOpts = {
+    queueId?: string | null;
+    operationId?: string | null;
+    nowMs?: number;
+};
+export declare function runStatusFromQueueState(state: DurableRunQueueState): ControlPlaneRunStatus;
+export declare function queueStatesForRunStatusFilter(status: string | null | undefined): DurableRunQueueState[] | null;
+export type RunQueueReconcilePlan = InterRootQueueReconcilePlan;
+export declare const RUN_QUEUE_RECONCILE_INVARIANTS: readonly ["ORCH-INTER-ROOT-RECON-001: one queue snapshot + policy yields one deterministic activation/launch plan.", "ORCH-INTER-ROOT-RECON-002: activation order is FIFO (`created_at_ms`, then `queue_id`) with per-root slot dedupe.", "ORCH-INTER-ROOT-RECON-003: sequential policy admits <=1 occupied root; parallel admits <=max_active_roots roots.", "ORCH-INTER-ROOT-RECON-004: launch candidates are active rows without bound job ids, one launch per root slot."];
+/**
+ * Server adapter wrapper around the orchestrator-owned inter-root planner.
+ */
+export declare function reconcileRunQueue(rows: readonly DurableRunQueueSnapshot[], policy: InterRootQueuePolicy): RunQueueReconcilePlan;
+export declare function runQueuePath(repoRoot: string): string;
+export declare function runSnapshotFromQueueSnapshot(queue: DurableRunQueueSnapshot, runtime?: ControlPlaneRunSnapshot | null): ControlPlaneRunSnapshot;
+export declare class DurableRunQueue {
+    #private;
+    constructor(opts: DurableRunQueueOpts);
+    enqueue(opts: DurableRunQueueEnqueueOpts): Promise<DurableRunQueueSnapshot>;
+    claim(opts?: DurableRunQueueClaimOpts): Promise<DurableRunQueueSnapshot | null>;
+    activate(opts: DurableRunQueueClaimOpts): Promise<DurableRunQueueSnapshot | null>;
+    transition(opts: DurableRunQueueTransitionOpts): Promise<DurableRunQueueSnapshot>;
+    bindRunSnapshot(opts: {
+        queueId: string;
+        run: ControlPlaneRunSnapshot;
+        operationId?: string | null;
+        nowMs?: number;
+    }): Promise<DurableRunQueueSnapshot>;
+    applyRunSnapshot(opts: {
+        run: ControlPlaneRunSnapshot;
+        queueId?: string | null;
+        operationId?: string | null;
+        nowMs?: number;
+        createIfMissing?: boolean;
+    }): Promise<DurableRunQueueSnapshot | null>;
+    get(idOrRoot: string): Promise<DurableRunQueueSnapshot | null>;
+    list(opts?: {
+        states?: readonly DurableRunQueueState[];
+        limit?: number;
+    }): Promise<DurableRunQueueSnapshot[]>;
+    listRunSnapshots(opts?: {
+        status?: string;
+        limit?: number;
+        runtimeByJobId?: Map<string, ControlPlaneRunSnapshot>;
+    }): Promise<ControlPlaneRunSnapshot[]>;
+}