handmux 0.23.0 → 0.25.0

package/dist/src/agent-runtime/interactionLiveHub.js

@@ -0,0 +1,225 @@
+const DEFAULT_MAX_BUFFERED_EVENTS = 256;
+const DEFAULT_IDLE_GRACE_MS = 5_000;
+export class InteractionLiveHubError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'InteractionLiveHubError';
+    }
+}
+class EventQueue {
+    checkpoint;
+    #maxBufferedEvents;
+    #detach;
+    #values = [];
+    #waiting;
+    #closed = false;
+    #detached = false;
+    constructor(checkpoint, maxBufferedEvents, detach) {
+        this.checkpoint = Object.freeze(structuredClone(checkpoint));
+        this.#maxBufferedEvents = maxBufferedEvents;
+        this.#detach = detach;
+    }
+    [Symbol.asyncIterator]() { return this; }
+    next() {
+        const value = this.#values.shift();
+        if (value)
+            return Promise.resolve({ value: structuredClone(value), done: false });
+        if (this.#closed)
+            return Promise.resolve({ value: undefined, done: true });
+        return new Promise((resolve) => { this.#waiting = resolve; });
+    }
+    push(event) {
+        if (this.#closed)
+            return;
+        const cloned = structuredClone(event);
+        if (this.#waiting) {
+            const waiting = this.#waiting;
+            this.#waiting = undefined;
+            waiting({ value: cloned, done: false });
+            return;
+        }
+        if (this.#values.length >= this.#maxBufferedEvents) {
+            this.close();
+            return;
+        }
+        this.#values.push(cloned);
+    }
+    finishAfterDrain() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#detachOnce();
+        if (!this.#values.length && this.#waiting) {
+            const waiting = this.#waiting;
+            this.#waiting = undefined;
+            waiting({ value: undefined, done: true });
+        }
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#values.splice(0);
+        this.#detachOnce();
+        if (this.#waiting) {
+            const waiting = this.#waiting;
+            this.#waiting = undefined;
+            waiting({ value: undefined, done: true });
+        }
+    }
+    #detachOnce() {
+        if (this.#detached)
+            return;
+        this.#detached = true;
+        this.#detach();
+    }
+}
+// App-level fan-out only. InteractionService remains the owner of native observation, persistence,
+// revision ordering, resolution tokens, and first-response-wins semantics.
+export class InteractionLiveHub {
+    #interaction;
+    #maxBufferedEvents;
+    #idleGraceMs;
+    #observations = new Map();
+    #closed = false;
+    constructor({ interaction, maxBufferedEvents = DEFAULT_MAX_BUFFERED_EVENTS, idleGraceMs = DEFAULT_IDLE_GRACE_MS, }) {
+        if (!interaction || typeof interaction.open !== 'function'
+            || !Number.isSafeInteger(maxBufferedEvents) || maxBufferedEvents <= 0
+            || !Number.isSafeInteger(idleGraceMs) || idleGraceMs < 0) {
+            throw new TypeError('Interaction live hub requires a service and bounded queues');
+        }
+        this.#interaction = interaction;
+        this.#maxBufferedEvents = maxBufferedEvents;
+        this.#idleGraceMs = idleGraceMs;
+    }
+    async subscribe(run) {
+        if (this.#closed)
+            throw new InteractionLiveHubError('closed', 'Interaction live hub is closed');
+        let shared = this.#observations.get(run.ref.runId);
+        if (!shared)
+            shared = this.#create(run);
+        if (shared.run !== run || shared.terminated) {
+            throw new InteractionLiveHubError('stale_run', 'Interaction live run is no longer current');
+        }
+        if (shared.idleTimer) {
+            clearTimeout(shared.idleTimer);
+            shared.idleTimer = undefined;
+        }
+        await shared.ready;
+        if (!shared.checkpoint || shared.terminated) {
+            throw new InteractionLiveHubError('unavailable', 'Interaction live observation is unavailable');
+        }
+        let subscription;
+        subscription = new EventQueue(shared.checkpoint, this.#maxBufferedEvents, () => {
+            this.#detach(shared, subscription);
+        });
+        shared.subscribers.add(subscription);
+        return subscription;
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        for (const shared of [...this.#observations.values()])
+            this.#terminate(shared);
+    }
+    #create(run) {
+        const shared = {
+            run,
+            ready: Promise.resolve(),
+            subscribers: new Set(),
+            idleTimer: undefined,
+            terminated: false,
+        };
+        this.#observations.set(run.ref.runId, shared);
+        shared.ready = this.#interaction.open(run, (event) => this.#publish(shared, event)).then((handle) => {
+            if (shared.terminated) {
+                try {
+                    void Promise.resolve(handle.close()).catch(() => { });
+                }
+                catch { /* best effort */ }
+                throw new Error('Interaction live run was revoked during open');
+            }
+            shared.handle = handle;
+            shared.checkpoint = {
+                revision: handle.revision,
+                pending: structuredClone(handle.pending),
+            };
+            void handle.closed.then(() => this.#terminate(shared, true));
+        }).catch((error) => {
+            this.#terminate(shared);
+            throw error;
+        });
+        return shared;
+    }
+    #publish(shared, event) {
+        if (shared.terminated)
+            return;
+        const checkpoint = shared.checkpoint;
+        if (!checkpoint || !Number.isSafeInteger(event.revision)
+            || event.revision !== checkpoint.revision + 1) {
+            this.#terminate(shared);
+            throw new InteractionLiveHubError('unavailable', 'Interaction revision is invalid');
+        }
+        const pending = new Map(checkpoint.pending.map((item) => [item.id, item]));
+        if (event.type === 'opened') {
+            if (event.interaction.runId !== shared.run.ref.runId || pending.has(event.interaction.id)) {
+                this.#terminate(shared);
+                throw new InteractionLiveHubError('unavailable', 'Interaction opened event is invalid');
+            }
+            pending.set(event.interaction.id, structuredClone(event.interaction));
+        }
+        else if (!pending.delete(event.interactionId)) {
+            this.#terminate(shared);
+            throw new InteractionLiveHubError('unavailable', 'Interaction terminal event is invalid');
+        }
+        shared.checkpoint = {
+            revision: event.revision,
+            pending: [...pending.values()],
+        };
+        for (const subscriber of [...shared.subscribers])
+            subscriber.push(event);
+    }
+    #detach(shared, subscription) {
+        shared.subscribers.delete(subscription);
+        this.#idle(shared);
+    }
+    #idle(shared) {
+        if (shared.terminated || shared.subscribers.size || shared.idleTimer)
+            return;
+        if (this.#idleGraceMs === 0) {
+            this.#terminate(shared);
+            return;
+        }
+        shared.idleTimer = setTimeout(() => {
+            shared.idleTimer = undefined;
+            if (!shared.subscribers.size)
+                this.#terminate(shared);
+        }, this.#idleGraceMs);
+        shared.idleTimer.unref?.();
+    }
+    #terminate(shared, drain = false) {
+        if (shared.terminated)
+            return;
+        shared.terminated = true;
+        if (this.#observations.get(shared.run.ref.runId) === shared) {
+            this.#observations.delete(shared.run.ref.runId);
+        }
+        if (shared.idleTimer)
+            clearTimeout(shared.idleTimer);
+        shared.idleTimer = undefined;
+        for (const subscriber of [...shared.subscribers]) {
+            if (drain)
+                subscriber.finishAfterDrain();
+            else
+                subscriber.close();
+        }
+        shared.subscribers.clear();
+        try {
+            void Promise.resolve(shared.handle?.close()).catch(() => { });
+        }
+        catch { /* close is best effort */ }
+    }
+}

package/dist/src/agent-runtime/interactionStore.js

@@ -0,0 +1,18 @@
+import { PrivateStateStore } from '../privateStateStore.js';
+export class MemoryInteractionStateStore {
+    #state = null;
+    load() {
+        return this.#state === null ? null : structuredClone(this.#state);
+    }
+    save(state) {
+        this.#state = structuredClone(state);
+    }
+}
+export class FileInteractionStateStore {
+    #store;
+    constructor(file) {
+        this.#store = new PrivateStateStore(file);
+    }
+    load() { return this.#store.readStrict(); }
+    save(state) { this.#store.write(state); }
+}

package/dist/src/agent-runtime/interactionTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/src/agent-runtime/legacyInboxProjection.js

@@ -0,0 +1,70 @@
+const LEGACY_KIND = {
+    working: 'working',
+    waiting: 'permission',
+    done: 'done',
+    error: 'error',
+};
+const LEGACY_MESSAGE = {
+    working: '进行中',
+    waiting: '需要你',
+    done: '已完成',
+    error: '出错',
+};
+function sameRun(record, run) {
+    return record.run.agentId === run.agentId
+        && record.run.paneId === run.paneId
+        && record.run.runId === run.runId
+        && record.run.sessionId === run.sessionId;
+}
+function sameTerminalEvent(candidate, run, eventId) {
+    if (candidate.agentId !== run.agentId || candidate.eventId !== eventId)
+        return false;
+    if (candidate.sessionId !== undefined && run.sessionId !== undefined) {
+        return candidate.sessionId === run.sessionId;
+    }
+    return candidate.runId === run.runId && candidate.paneId === run.paneId;
+}
+// Temporary compatibility projection for the existing phone roster. Runtime/Inbox remain the only
+// identity and state authorities; tmux contributes presentation location only.
+export function projectLegacyInboxStates({ snapshot, runs, panes, allowedSessions, }) {
+    const allowed = allowedSessions === null ? null : new Set(allowedSessions);
+    const paneById = new Map(panes.map((pane) => [pane.paneId, pane]));
+    const recordByRun = new Map(snapshot.records.map((record) => [record.run.runId, record]));
+    const out = {};
+    for (const run of runs) {
+        const pane = paneById.get(run.paneId);
+        if (allowed && (!pane || !allowed.has(pane.sessionName)))
+            continue;
+        const record = recordByRun.get(run.runId);
+        const current = record && sameRun(record, run) ? record : undefined;
+        const terminal = current && (current.state === 'done' || current.state === 'error');
+        const notifications = terminal && current.eventId
+            ? snapshot.terminalNotifications.filter((candidate) => (sameTerminalEvent(candidate, run, current.eventId))) : [];
+        // One event may have legacy duplicates from Server restarts. Any read copy makes the durable event
+        // read; otherwise keep one canonical notification id so a click marks every duplicate together.
+        const notification = notifications.find((candidate) => candidate.readAt !== undefined)
+            ?? notifications[0];
+        const displayTime = terminal
+            ? current?.sourceOccurredAt ?? current?.acceptedAt
+            : current?.acceptedAt;
+        out[run.paneId] = {
+            ...(pane === undefined ? {} : {
+                session: pane.sessionName,
+                window: pane.windowId,
+                windowName: pane.windowName,
+            }),
+            kind: current ? LEGACY_KIND[current.state] : null,
+            // `reason` is a machine-readable state code. Adapters may use it for recovery/diagnostics,
+            // but the user-facing roster must never render values such as `agent_end_idle` verbatim.
+            msg: current?.message ?? (current ? LEGACY_MESSAGE[current.state] : ''),
+            ...(displayTime === undefined ? {} : { ts: displayTime }),
+            agent: run.agentId,
+            ...(terminal ? {
+                terminalUnread: notifications.length > 0
+                    && notifications.every((candidate) => candidate.readAt === undefined),
+            } : {}),
+            ...(notification === undefined ? {} : { terminalNotificationId: notification.id }),
+        };
+    }
+    return out;
+}

package/dist/src/agent-runtime/migrateLegacyCodexOutbox.js

@@ -0,0 +1,336 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseCodexOutboxSnapshot } from '../codexQueueProtocol.js';
+import { PrivateStateStore } from '../privateStateStore.js';
+import { parseConversationState } from './conversationStore.js';
+const DELIVERY_RECEIPT_TTL_MS = 24 * 60 * 60 * 1_000;
+function payloadHash(text) {
+    return crypto.createHash('sha256').update(text).digest('hex');
+}
+function migrationId(threadId, itemId, text) {
+    return `codex-legacy:${crypto.createHash('sha256').update(`${threadId}\0${itemId}\0${text}`)
+        .digest('hex').slice(0, 40)}`;
+}
+function fsyncDirectory(directory) {
+    let descriptor;
+    try {
+        descriptor = fs.openSync(directory, 'r');
+        fs.fsyncSync(descriptor);
+    }
+    finally {
+        if (descriptor !== undefined)
+            fs.closeSync(descriptor);
+    }
+}
+function verifyBackup(file, fingerprint) {
+    if (!fs.existsSync(file)) {
+        throw new Error('Conversation migration marker exists but the Codex outbox backup is missing');
+    }
+    const actual = crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+    if (actual !== fingerprint) {
+        throw new Error('Codex outbox migration backup does not match its marker');
+    }
+}
+function verifyMarkerSubmissions(state, marker) {
+    if (!marker.submissionKeys) {
+        throw new Error('Conversation migration marker has no scoped submission keys');
+    }
+    for (const key of marker.submissionKeys) {
+        const [agentId, sessionId, clientRequestId] = key.split('\0');
+        if (!agentId || !sessionId || !clientRequestId || !(state.submissions.some((submission) => (submission.agentId === agentId && submission.sessionId === sessionId
+            && submission.clientRequestId === clientRequestId)) || state.deliveryReceipts?.some((receipt) => receipt.agentId === agentId
+            && receipt.sessionId === sessionId && receipt.clientRequestId === clientRequestId))) {
+            throw new Error('Conversation migration marker is missing a referenced delivery');
+        }
+    }
+}
+function requiredKeysFromBackup(file) {
+    if (!fs.existsSync(file))
+        return null;
+    const legacy = parseCodexOutboxSnapshot(JSON.parse(fs.readFileSync(file, 'utf8')));
+    if (!legacy)
+        throw new Error('Legacy Codex outbox backup is corrupt');
+    const keys = legacy.queues.flatMap((queue) => queue.items.map((item) => (`codex\0${queue.threadId}\0${item.requestId ?? migrationId(queue.threadId, item.id, item.text)}`)));
+    for (const receipt of legacy.receipts) {
+        if (receipt.status === 'pending' || receipt.status === 'accepted') {
+            keys.push(`codex\0${receipt.threadId}\0${receipt.requestId}`);
+        }
+    }
+    return [...new Set(keys)];
+}
+function verifyRequiredDeliveries(state, keys) {
+    for (const key of keys) {
+        const [agentId, sessionId, clientRequestId] = key.split('\0');
+        if (!(state.submissions.some((submission) => submission.agentId === agentId
+            && submission.sessionId === sessionId && submission.clientRequestId === clientRequestId)
+            || state.deliveryReceipts?.some((receipt) => receipt.agentId === agentId
+                && receipt.sessionId === sessionId && receipt.clientRequestId === clientRequestId))) {
+            throw new Error('Conversation migration is missing a queued or uncertain delivery');
+        }
+    }
+}
+function finalizeMigration(legacyFile, conversationFile, state, fingerprint) {
+    const marker = state.migrations?.legacyCodexOutboxImported;
+    if (marker)
+        verifyMarkerSubmissions(state, marker);
+    const backup = `${legacyFile}.imported.${fingerprint}.json`;
+    const required = requiredKeysFromBackup(backup);
+    if (required)
+        verifyRequiredDeliveries(state, required);
+    for (const file of [legacyFile, backup]) {
+        try {
+            fs.unlinkSync(file);
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    fsyncDirectory(path.dirname(legacyFile));
+    if (state.migrations?.legacyCodexOutboxImported) {
+        delete state.migrations.legacyCodexOutboxImported;
+        if (Object.keys(state.migrations).length === 0)
+            delete state.migrations;
+        new PrivateStateStore(conversationFile).write(state);
+        fsyncDirectory(path.dirname(conversationFile));
+    }
+}
+function exactMarkerSet(actual, expected) {
+    if (actual.length !== expected.length)
+        return false;
+    const values = new Set(actual);
+    return values.size === actual.length && expected.every((value) => values.has(value));
+}
+function acquireLock(file) {
+    const lock = `${file}.migration.lock`;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const descriptor = fs.openSync(lock, 'wx', 0o600);
+            fs.writeFileSync(descriptor, JSON.stringify({ pid: process.pid, createdAt: Date.now() }));
+            fs.fsyncSync(descriptor);
+            fs.closeSync(descriptor);
+            return () => { try {
+                fs.unlinkSync(lock);
+            }
+            catch { /* already released */ } };
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !('code' in error) || error.code !== 'EEXIST')
+                throw error;
+            let owner = 0;
+            try {
+                owner = Number(JSON.parse(fs.readFileSync(lock, 'utf8')).pid);
+            }
+            catch { /* stale */ }
+            try {
+                if (owner > 0)
+                    process.kill(owner, 0);
+                throw new Error('Codex outbox migration is already running');
+            }
+            catch (probe) {
+                if (probe instanceof Error && !('code' in probe && probe.code === 'ESRCH'))
+                    throw probe;
+                fs.unlinkSync(lock);
+            }
+        }
+    }
+    throw new Error('Could not acquire Codex outbox migration lock');
+}
+export function migrateLegacyCodexOutbox(legacyFile, conversationFile, now = Date.now()) {
+    if (!fs.existsSync(legacyFile)) {
+        if (!fs.existsSync(conversationFile))
+            return { imported: 0 };
+        fsyncDirectory(path.dirname(conversationFile));
+        const stateStore = new PrivateStateStore(conversationFile);
+        const state = parseConversationState(stateStore.readStrict());
+        const marker = state.migrations?.legacyCodexOutboxImported;
+        if (!marker)
+            return { imported: 0 };
+        const backup = `${legacyFile}.imported.${marker.fingerprint}.json`;
+        if (fs.existsSync(backup))
+            verifyBackup(backup, marker.fingerprint);
+        finalizeMigration(legacyFile, conversationFile, state, marker.fingerprint);
+        return { imported: 0, fingerprint: marker.fingerprint };
+    }
+    const release = acquireLock(legacyFile);
+    try {
+        const bytes = fs.readFileSync(legacyFile);
+        const fingerprint = crypto.createHash('sha256').update(bytes).digest('hex');
+        let raw;
+        try {
+            raw = JSON.parse(bytes.toString('utf8'));
+        }
+        catch {
+            throw new Error('Legacy Codex outbox is truncated or invalid JSON');
+        }
+        if (raw && typeof raw === 'object' && !Array.isArray(raw)
+            && raw.migratedToConversationCore === true) {
+            const state = parseConversationState(new PrivateStateStore(conversationFile).readStrict());
+            const marker = state.migrations?.legacyCodexOutboxImported;
+            if (!marker || marker.fingerprint !== raw.fingerprint) {
+                throw new Error('Codex outbox tombstone does not match Conversation migration marker');
+            }
+            const backup = `${legacyFile}.imported.${marker.fingerprint}.json`;
+            if (fs.existsSync(backup))
+                verifyBackup(backup, marker.fingerprint);
+            finalizeMigration(legacyFile, conversationFile, state, marker.fingerprint);
+            return { imported: 0, fingerprint: marker.fingerprint };
+        }
+        const legacy = parseCodexOutboxSnapshot(raw);
+        if (!legacy)
+            throw new Error('Unsupported or corrupt legacy Codex outbox schema');
+        const store = new PrivateStateStore(conversationFile);
+        const state = parseConversationState(store.readStrict());
+        const existingMarker = state.migrations?.legacyCodexOutboxImported;
+        const expectedIds = [];
+        const expectedKeys = [];
+        const byKey = new Map(state.submissions.map((item) => [`${item.agentId}\0${item.sessionId}\0${item.clientRequestId}`, item]));
+        const receiptsByKey = new Map((state.deliveryReceipts ?? []).map((item) => [`${item.agentId}\0${item.sessionId}\0${item.clientRequestId}`, item]));
+        const queuedByNativeId = new Map();
+        let imported = 0;
+        for (const queue of legacy.queues) {
+            for (const item of queue.items) {
+                const id = item.requestId ?? migrationId(queue.threadId, item.id, item.text);
+                const key = `codex\0${queue.threadId}\0${id}`;
+                expectedIds.push(id);
+                expectedKeys.push(key);
+                const existing = byKey.get(key);
+                if (existing) {
+                    if (existing.text !== item.text)
+                        throw new Error('Legacy Codex queue conflicts with Conversation ledger');
+                    queuedByNativeId.set(`${queue.pane}\0${queue.threadId}\0${item.id}`, existing);
+                    continue;
+                }
+                const revision = ++state.ledgerRevision;
+                const submission = {
+                    agentId: 'codex', sessionId: queue.threadId, clientRequestId: id,
+                    text: item.text, payloadHash: payloadHash(item.text), state: 'queued', revision,
+                    queueOrderKey: `${String(Math.floor(item.createdAt)).padStart(16, '0')}:${String(revision).padStart(16, '0')}`,
+                    lastRunId: queue.pane, createdAt: item.createdAt, updatedAt: item.createdAt,
+                };
+                state.submissions.push(submission);
+                byKey.set(key, submission);
+                queuedByNativeId.set(`${queue.pane}\0${queue.threadId}\0${item.id}`, submission);
+                imported += 1;
+            }
+        }
+        for (const receipt of legacy.receipts) {
+            const key = `codex\0${receipt.threadId}\0${receipt.requestId}`;
+            const existing = byKey.get(key);
+            const existingReceipt = receiptsByKey.get(key);
+            if (receipt.status === 'queued') {
+                const queued = queuedByNativeId.get(`${receipt.pane}\0${receipt.threadId}\0${receipt.queueItemId}`);
+                if (!queued || queued.clientRequestId !== receipt.requestId || queued.text !== receipt.text) {
+                    throw new Error('Legacy Codex queued receipt has no matching queue item');
+                }
+                continue;
+            }
+            if (receipt.status === 'pending' || receipt.status === 'accepted') {
+                expectedIds.push(receipt.requestId);
+                expectedKeys.push(key);
+            }
+            if (existingReceipt) {
+                if (existingReceipt.payloadHash !== payloadHash(receipt.text)) {
+                    throw new Error('Legacy Codex receipt conflicts with Conversation delivery receipt');
+                }
+                continue;
+            }
+            if (existing) {
+                if (existing.text !== receipt.text)
+                    throw new Error('Legacy Codex receipt conflicts with Conversation ledger');
+                if (receipt.status !== 'accepted')
+                    continue;
+            }
+            if (receipt.status === 'accepted') {
+                const settled = {
+                    agentId: 'codex', sessionId: receipt.threadId,
+                    clientRequestId: receipt.requestId,
+                    payloadHash: existing?.payloadHash ?? payloadHash(receipt.text),
+                    ...(existing?.baseline === undefined ? {} : { baseline: structuredClone(existing.baseline) }),
+                    ...(receipt.turnId ?? existing?.nativeId
+                        ? { nativeId: (receipt.turnId ?? existing?.nativeId) } : {}),
+                    ...(existing?.steerActionId === undefined ? {} : { steerActionId: existing.steerActionId }),
+                    ...(existing?.steerBaseRevision === undefined
+                        ? {} : { steerBaseRevision: existing.steerBaseRevision }),
+                    ...(existing?.steerAnchor === undefined
+                        ? {} : { steerAnchor: structuredClone(existing.steerAnchor) }),
+                    ...(existing?.steerAttempts === undefined
+                        ? {} : { steerAttempts: structuredClone(existing.steerAttempts) }),
+                    acceptedAt: receipt.updatedAt,
+                    expiresAt: receipt.updatedAt + DELIVERY_RECEIPT_TTL_MS,
+                };
+                if (existing) {
+                    state.submissions = state.submissions.filter((candidate) => candidate !== existing);
+                    byKey.delete(key);
+                }
+                state.deliveryReceipts ??= [];
+                state.deliveryReceipts.push(settled);
+                receiptsByKey.set(key, settled);
+                imported += 1;
+                continue;
+            }
+            const revision = ++state.ledgerRevision;
+            const submission = {
+                agentId: 'codex', sessionId: receipt.threadId, clientRequestId: receipt.requestId,
+                text: receipt.text, payloadHash: payloadHash(receipt.text),
+                state: 'unknown', revision,
+                dispatchOrigin: 'direct',
+                ...(receipt.turnId ? { nativeId: receipt.turnId } : {}),
+                lastRunId: receipt.pane, createdAt: receipt.createdAt, updatedAt: receipt.updatedAt,
+            };
+            state.submissions.push(submission);
+            byKey.set(key, submission);
+            imported += 1;
+        }
+        const uniqueIds = [...new Set(expectedIds)].sort();
+        const uniqueKeys = [...new Set(expectedKeys)].sort();
+        if (existingMarker) {
+            if (existingMarker.fingerprint !== fingerprint
+                || (existingMarker.submissionKeys
+                    ? !exactMarkerSet(existingMarker.submissionKeys, uniqueKeys)
+                    : !exactMarkerSet(existingMarker.submissionIds, uniqueIds))) {
+                throw new Error('Legacy Codex outbox migration marker conflicts with its source');
+            }
+            const needsMarkerUpgrade = !existingMarker.submissionKeys;
+            if (needsMarkerUpgrade)
+                existingMarker.submissionKeys = uniqueKeys;
+            if (imported > 0 || needsMarkerUpgrade)
+                store.write(state);
+        }
+        else {
+            state.migrations ??= {};
+            state.migrations.legacyCodexOutboxImported = {
+                fingerprint, submissionIds: uniqueIds, submissionKeys: uniqueKeys, importedAt: now,
+            };
+            store.write(state);
+        }
+        // PrivateStateStore makes the file contents durable before rename. Persist the directory entry too,
+        // then re-read the committed ledger before the only recoverable legacy source is moved aside.
+        fsyncDirectory(path.dirname(conversationFile));
+        const verified = parseConversationState(store.readStrict());
+        for (const key of uniqueKeys) {
+            const [agentId, sessionId, clientRequestId] = key.split('\0');
+            if (!(verified.submissions.some((submission) => submission.agentId === agentId
+                && submission.sessionId === sessionId && submission.clientRequestId === clientRequestId)
+                || verified.deliveryReceipts?.some((receipt) => receipt.agentId === agentId
+                    && receipt.sessionId === sessionId && receipt.clientRequestId === clientRequestId))) {
+                throw new Error('Conversation migration marker is missing a referenced delivery');
+            }
+        }
+        const backup = `${legacyFile}.imported.${fingerprint}.json`;
+        if (!fs.existsSync(backup))
+            fs.renameSync(legacyFile, backup);
+        else {
+            verifyBackup(backup, fingerprint);
+            if (fs.existsSync(legacyFile))
+                fs.unlinkSync(legacyFile);
+        }
+        fsyncDirectory(path.dirname(legacyFile));
+        finalizeMigration(legacyFile, conversationFile, verified, fingerprint);
+        return { imported, fingerprint };
+    }
+    finally {
+        release();
+    }
+}

package/dist/src/agent-runtime/resourceTypes.js

@@ -0,0 +1 @@
+export {};