polygram 0.21.0 → 0.23.0

package/lib/db.js

@@ -7,6 +7,16 @@
 const fs = require('fs');
 const path = require('path');
 const Database = require('better-sqlite3');
+const {
+  pruneCodexOperationalData,
+} = require('./db/codex-retention');
+const {
+  codexError,
+  listUnresolvedCodexAttempts,
+  requiredString: requiredCodexString,
+  reconcileCodexAttempt,
+  reconstructCodexRecovery,
+} = require('./db/codex-reconciliation');
 
 // 0.8.0 Phase 1: bumped from 9 → 10. Adds migration
 // 010-tool-use-id.sql (pending_approvals.tool_use_id column for the
@@ -26,7 +36,7 @@ const Database = require('better-sqlite3');
 //
 // 0.15: bumped 13 → 14. Adds migration 014-secret-redactions.sql
 // (secret_redactions audit table + messages.secret_scanned_at).
-const SCHEMA_VERSION = 14;
+const SCHEMA_VERSION = 17;
 
 // Sentinel `error` value for outbound rows whose API call may or may not
 // have reached Telegram. markStalePending writes it; hasOutboundReplyTo
@@ -36,6 +46,78 @@ const SCHEMA_VERSION = 14;
 // reply on boot).
 const CRASHED_MID_SEND = 'crashed-mid-send';
 
+const CLAUDE_INLINE_NAMESPACE = 'claude:inline';
+const CLAUDE_CHANNELS_NAMESPACE = 'claude:channels';
+const CODEX_APP_SERVER_NAMESPACE = 'codex:app-server';
+const PROVIDER_NAMESPACES = new Set([
+  CLAUDE_INLINE_NAMESPACE,
+  CLAUDE_CHANNELS_NAMESPACE,
+  CODEX_APP_SERVER_NAMESPACE,
+]);
+
+function claudeNamespaceForStoredBackend(backend) {
+  return backend === 'cli' || backend === 'channels'
+    ? CLAUDE_CHANNELS_NAMESPACE
+    : CLAUDE_INLINE_NAMESPACE;
+}
+
+function requiredTimestamp(value, label) {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw codexError(
+      `Codex ${label} must be a non-negative safe integer`,
+      'CODEX_PERSISTENCE_INPUT_INVALID',
+    );
+  }
+  return value;
+}
+
+function optionalCodexString(value, label) {
+  if (value == null) return null;
+  return requiredCodexString(String(value), label);
+}
+
+function optionalCodexRequestId(value) {
+  if (value == null) return null;
+  if (typeof value === 'string') {
+    return `string:${requiredCodexString(value, 'request ID')}`;
+  }
+  if (Number.isSafeInteger(value)) {
+    return `number:${value}`;
+  }
+  throw codexError(
+    'Codex request ID must be a bounded string or safe integer',
+    'CODEX_PERSISTENCE_INPUT_INVALID',
+  );
+}
+
+function assertExactKeys(row, allowed, code, label) {
+  for (const key of Object.keys(row ?? {})) {
+    if (!allowed.has(key)) {
+      throw codexError(
+        `Codex ${label} rejected field ${key}`,
+        code,
+      );
+    }
+  }
+}
+
+function configChangeValue(value, { nullable, label }) {
+  if (value == null) {
+    if (nullable) return null;
+    const error = new TypeError(`config change ${label} is required`);
+    error.code = 'CONFIG_CHANGE_VALUE_INVALID';
+    throw error;
+  }
+  if (typeof value === 'string') return value;
+  if (typeof value === 'boolean') return String(value);
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+  const error = new TypeError(
+    `config change ${label} must be a string, boolean, or finite number`,
+  );
+  error.code = 'CONFIG_CHANGE_VALUE_INVALID';
+  throw error;
+}
+
 function open(dbPath) {
   const db = new Database(dbPath);
   db.pragma('journal_mode = WAL');
@@ -147,6 +229,195 @@ function wrap(db) {
   const clearSessionIdStmt = db.prepare(`DELETE FROM sessions WHERE session_key = ?`);
   const setSessionBackendStmt = db.prepare(`UPDATE sessions SET pm_backend = ? WHERE session_key = ?`);
 
+  const upsertProviderSessionStmt = db.prepare(`
+    INSERT INTO agent_runtime_sessions (
+      session_key, namespace, provider, provider_session_id,
+      app_server_session_id, agent, cwd, model, effort, pm_backend,
+      created_ts, last_active_ts
+    ) VALUES (
+      @session_key, @namespace, @provider, @provider_session_id,
+      @app_server_session_id, @agent, @cwd, @model, @effort, @pm_backend,
+      @ts, @ts
+    )
+    ON CONFLICT(session_key, namespace) DO UPDATE SET
+      provider = excluded.provider,
+      provider_session_id = excluded.provider_session_id,
+      app_server_session_id = excluded.app_server_session_id,
+      agent = excluded.agent,
+      cwd = excluded.cwd,
+      model = excluded.model,
+      effort = excluded.effort,
+      pm_backend = excluded.pm_backend,
+      last_active_ts = excluded.last_active_ts
+  `);
+  const getProviderSessionStmt = db.prepare(`
+    SELECT *
+      FROM agent_runtime_sessions
+     WHERE session_key = ? AND namespace = ?
+  `);
+  const clearProviderSessionStmt = db.prepare(`
+    DELETE FROM agent_runtime_sessions
+     WHERE session_key = ? AND namespace = ?
+  `);
+  const touchProviderSessionStmt = db.prepare(`
+    UPDATE agent_runtime_sessions
+       SET last_active_ts = ?
+     WHERE session_key = ? AND namespace = ?
+  `);
+  const setProviderBackendStmt = db.prepare(`
+    UPDATE agent_runtime_sessions
+       SET pm_backend = ?
+     WHERE session_key = ? AND namespace = ?
+  `);
+
+  function providerSessionParams(row) {
+    if (!row || !PROVIDER_NAMESPACES.has(row.namespace)) {
+      throw new TypeError('provider session namespace is invalid');
+    }
+    const provider = row.provider;
+    if (
+      (provider === 'claude' && !row.namespace.startsWith('claude:'))
+      || (provider === 'codex' && row.namespace !== CODEX_APP_SERVER_NAMESPACE)
+      || !['claude', 'codex'].includes(provider)
+    ) {
+      throw new TypeError('provider session namespace/provider mismatch');
+    }
+    if (
+      typeof row.provider_session_id !== 'string'
+      || row.provider_session_id.length === 0
+    ) {
+      throw new TypeError('provider session ID must be a non-empty string');
+    }
+    return {
+      session_key: String(row.session_key),
+      namespace: row.namespace,
+      provider,
+      provider_session_id: row.provider_session_id,
+      app_server_session_id: row.app_server_session_id || null,
+      agent: row.agent || null,
+      cwd: row.cwd || null,
+      model: row.model || null,
+      effort: row.effort || null,
+      pm_backend: row.pm_backend || null,
+      ts: row.ts || Date.now(),
+    };
+  }
+
+  function legacySessionParams(row) {
+    return {
+      session_key: row.session_key,
+      chat_id: String(row.chat_id),
+      thread_id: row.thread_id ? String(row.thread_id) : null,
+      claude_session_id: row.claude_session_id,
+      agent: row.agent || null,
+      cwd: row.cwd || null,
+      model: row.model || null,
+      effort: row.effort || null,
+      pm_backend: row.pm_backend || 'sdk',
+      ts: row.ts || Date.now(),
+    };
+  }
+
+  const upsertLegacyAndProviderSession = db.transaction((row) => {
+    const legacy = legacySessionParams(row);
+    const result = upsertSessionStmt.run(legacy);
+    upsertProviderSessionStmt.run(providerSessionParams({
+      ...row,
+      session_key: legacy.session_key,
+      namespace: claudeNamespaceForStoredBackend(legacy.pm_backend),
+      provider: 'claude',
+      provider_session_id: legacy.claude_session_id,
+      pm_backend: legacy.pm_backend,
+      ts: legacy.ts,
+    }));
+    return result;
+  });
+
+  const upsertProviderAndLegacySession = db.transaction((row) => {
+    const provider = providerSessionParams(row);
+    const result = upsertProviderSessionStmt.run(provider);
+    if (provider.provider === 'claude') {
+      upsertSessionStmt.run(legacySessionParams({
+        ...row,
+        session_key: provider.session_key,
+        chat_id: row.chat_id ?? provider.session_key.split(':')[0],
+        claude_session_id: provider.provider_session_id,
+        pm_backend: provider.pm_backend
+          ?? (
+            provider.namespace === CLAUDE_CHANNELS_NAMESPACE
+              ? 'cli'
+              : 'sdk'
+          ),
+        ts: provider.ts,
+      }));
+    }
+    return result;
+  });
+
+  const clearLegacySession = db.transaction((sessionKey) => {
+    const row = getSessionStmt.get(sessionKey);
+    const result = clearSessionIdStmt.run(sessionKey);
+    if (row) {
+      clearProviderSessionStmt.run(
+        sessionKey,
+        claudeNamespaceForStoredBackend(row.pm_backend),
+      );
+    }
+    return result;
+  });
+
+  const clearOneProviderSession = db.transaction((sessionKey, namespace) => {
+    const row = getProviderSessionStmt.get(sessionKey, namespace);
+    const result = clearProviderSessionStmt.run(sessionKey, namespace);
+    if (row?.provider === 'claude') {
+      const legacy = getSessionStmt.get(sessionKey);
+      if (
+        legacy
+        && claudeNamespaceForStoredBackend(legacy.pm_backend) === namespace
+      ) {
+        clearSessionIdStmt.run(sessionKey);
+      }
+    }
+    return result;
+  });
+
+  const readProviderSession = db.transaction((sessionKey, namespace) => {
+    if (
+      namespace === CLAUDE_INLINE_NAMESPACE
+      || namespace === CLAUDE_CHANNELS_NAMESPACE
+    ) {
+      const legacy = getSessionStmt.get(sessionKey);
+      if (
+        legacy
+        && claudeNamespaceForStoredBackend(legacy.pm_backend) === namespace
+      ) {
+        const namespaced = getProviderSessionStmt.get(sessionKey, namespace);
+        if (
+          !namespaced
+          || legacy.last_active_ts > namespaced.last_active_ts
+          || (
+            legacy.last_active_ts === namespaced.last_active_ts
+            && legacy.claude_session_id !== namespaced.provider_session_id
+          )
+        ) {
+          upsertProviderSessionStmt.run(providerSessionParams({
+            session_key: legacy.session_key,
+            namespace,
+            provider: 'claude',
+            provider_session_id: legacy.claude_session_id,
+            agent: legacy.agent,
+            cwd: legacy.cwd,
+            model: legacy.model,
+            effort: legacy.effort,
+            pm_backend: legacy.pm_backend,
+            ts: legacy.last_active_ts,
+          }));
+        }
+      }
+    }
+    return getProviderSessionStmt.get(sessionKey, namespace);
+  });
+
   const getMessageStmt = db.prepare(`
     SELECT * FROM messages WHERE chat_id = ? AND msg_id = ?
     ORDER BY id DESC LIMIT 1
@@ -272,6 +543,3026 @@ function wrap(db) {
     return { replayMarked: txn() };
   }
 
+  function assertCodexGenerationIdentity(generationId, stableHostId, bootSessionId) {
+    const generation = db.prepare(`
+      SELECT * FROM codex_generations WHERE generation_id = ?
+    `).get(generationId);
+    if (!generation) {
+      throw codexError(
+        'Codex generation does not exist',
+        'CODEX_GENERATION_NOT_FOUND',
+      );
+    }
+    if (
+      generation.stable_host_id !== stableHostId
+      || generation.boot_session_id !== bootSessionId
+    ) {
+      throw codexError(
+        'Codex generation identity does not match the durable owner',
+        'CODEX_GENERATION_IDENTITY_MISMATCH',
+      );
+    }
+    return generation;
+  }
+
+  function createCodexGeneration(input) {
+    const generationId = requiredCodexString(
+      input?.generation_id,
+      'generation ID',
+    );
+    const sessionKey = requiredCodexString(input?.session_key, 'session key');
+    const stableHostId = requiredCodexString(
+      input?.stable_host_id,
+      'stable host identity',
+    );
+    const bootSessionId = requiredCodexString(
+      input?.boot_session_id,
+      'boot-session identity',
+    );
+    const ts = requiredTimestamp(input?.ts ?? Date.now(), 'generation timestamp');
+    const threadId = optionalCodexString(input?.thread_id, 'thread ID');
+    const appServerSessionId = optionalCodexString(
+      input?.app_server_session_id,
+      'app-server session ID',
+    );
+
+    return db.transaction(() => {
+      const identity = db.prepare(`
+        SELECT stable_host_id, last_boot_session_id
+          FROM codex_runtime_identity
+         WHERE singleton = 1
+      `).get();
+      if (!identity) {
+        const hasState = db.prepare(`
+          SELECT (
+            (SELECT COUNT(*) FROM codex_generations)
+            + (SELECT COUNT(*) FROM codex_daemon_lease)
+          ) AS count
+        `).get().count;
+        if (hasState) {
+          throw codexError(
+            'Codex persisted identity is missing',
+            'CODEX_PERSISTED_IDENTITY_MISSING',
+          );
+        }
+        db.prepare(`
+          INSERT INTO codex_runtime_identity (
+            singleton, stable_host_id, last_boot_session_id,
+            established_ts, updated_ts
+          ) VALUES (1, ?, ?, ?, ?)
+        `).run(stableHostId, bootSessionId, ts, ts);
+      } else if (identity.stable_host_id !== stableHostId) {
+        throw codexError(
+          'Codex database belongs to another stable host',
+          'CODEX_STABLE_HOST_MISMATCH',
+        );
+      } else if (identity.last_boot_session_id !== bootSessionId) {
+        throw codexError(
+          'Codex boot identity must be reconstructed before generation creation',
+          'CODEX_BOOT_RECONSTRUCTION_REQUIRED',
+        );
+      }
+      return db.prepare(`
+        INSERT INTO codex_generations (
+          generation_id, session_key, thread_id, app_server_session_id,
+          stable_host_id, boot_session_id, state,
+          created_ts, updated_ts
+        ) VALUES (?, ?, ?, ?, ?, ?, 'created', ?, ?)
+      `).run(
+        generationId,
+        sessionKey,
+        threadId,
+        appServerSessionId,
+        stableHostId,
+        bootSessionId,
+        ts,
+        ts,
+      );
+    })();
+  }
+
+  const checkpointDetailKeys = [
+    'method',
+    'outcome',
+    'reason',
+    'errorCode',
+    'source',
+    'clientUserMessageId',
+    'terminalStatus',
+    'itemType',
+    'deltaBytes',
+    'resumed',
+    'model',
+    'effort',
+    'willRetry',
+    'deliveryState',
+    'cancellationCode',
+    'statusType',
+  ];
+  const codexCheckpointKinds = new Set([
+    'request-prepared',
+    'request-write-attempted',
+    'request-response-observed',
+    'thread-initialized',
+    'thread-status-changed',
+    'turn-accepted',
+    'turn-steer-accepted',
+    'turn-error-observed',
+    'turn-started',
+    'item-delta-observed',
+    'item-started',
+    'item-completed',
+    'turn-terminal',
+    'active-start-cancelled',
+    'queued-send-cancelled',
+    'stop-background-cleanup-reused',
+    'stop-terminal-reconciled',
+    'stop-clean-accepted',
+    'stop-empty-registry-observed',
+    'background-terminal-reconciled',
+    'background-clean-accepted',
+    'background-empty-registry-observed',
+    'failed-ambiguous-entered',
+    'containment-entered',
+    'telegram-delivery-settled',
+    'telegram-delivery-failed',
+  ]);
+
+  function checkpointDetail(input) {
+    const detail = {};
+    for (const key of checkpointDetailKeys) {
+      const value = input[key];
+      if (
+        value == null
+        || typeof value === 'string'
+        || typeof value === 'boolean'
+        || Number.isSafeInteger(value)
+      ) {
+        if (value != null) detail[key] = value;
+      }
+    }
+    return Object.keys(detail).length > 0 ? JSON.stringify(detail) : null;
+  }
+
+  function requireCodexAttempt(attemptId, generationId) {
+    const attempt = db.prepare(`
+      SELECT * FROM codex_turn_attempts WHERE attempt_id = ?
+    `).get(attemptId);
+    if (!attempt || attempt.generation_id !== generationId) {
+      throw codexError(
+        'Codex checkpoint attempt does not belong to the generation',
+        'CODEX_ATTEMPT_NOT_FOUND',
+      );
+    }
+    return attempt;
+  }
+
+  function markGenerationAttemptsAmbiguous(generationId, ts) {
+    const result = db.prepare(`
+      UPDATE codex_turn_attempts
+         SET recovery_state = 'ambiguous',
+             ambiguous_ts = COALESCE(ambiguous_ts, ?),
+             updated_ts = ?
+       WHERE generation_id = ?
+         AND delivery_state != 'prepared'
+         AND recovery_state NOT IN ('settled', 'cancelled')
+    `).run(ts, ts, generationId);
+    db.prepare(`
+      UPDATE codex_linked_inputs
+         SET state = 'ambiguous', settled_ts = ?
+       WHERE generation_id = ?
+         AND state = 'linked'
+    `).run(ts, generationId);
+    db.prepare(`
+      UPDATE codex_dispatch_reservations
+         SET state = 'ambiguous',
+             updated_ts = ?,
+             settled_ts = NULL
+       WHERE generation_id = ?
+         AND state IN ('reserved', 'steer-accepted', 'queue-authorized')
+    `).run(ts, generationId);
+    db.prepare(`
+      UPDATE messages
+         SET handler_status = 'codex-ambiguous'
+       WHERE direction = 'in'
+         AND handler_status IN (
+           'received', 'dispatched', 'processing', 'replay-pending'
+         )
+         AND EXISTS (
+           SELECT 1
+             FROM codex_dispatch_reservations reservation
+            WHERE reservation.generation_id = ?
+              AND reservation.state = 'ambiguous'
+              AND reservation.bot_name = messages.bot_name
+              AND reservation.telegram_chat_id = messages.chat_id
+              AND reservation.telegram_message_id = CAST(messages.msg_id AS TEXT)
+         )
+    `).run(generationId);
+    return result;
+  }
+
+  function assertCodexCheckpointOwner(generation, kind) {
+    if (['request-prepared', 'queued-send-cancelled'].includes(kind)) return;
+    const lease = db.prepare(`
+      SELECT generation_id, stable_host_id, boot_session_id, status
+        FROM codex_daemon_lease
+       WHERE singleton = 1
+    `).get();
+    if (
+      generation.state !== 'active'
+      || lease?.status !== 'active'
+      || lease.generation_id !== generation.generation_id
+      || lease.stable_host_id !== generation.stable_host_id
+      || lease.boot_session_id !== generation.boot_session_id
+    ) {
+      throw codexError(
+        'Codex checkpoint generation does not own the active daemon lease',
+        'CODEX_CHECKPOINT_STALE_GENERATION',
+      );
+    }
+  }
+
+  function assertCodexAttemptIdentity(attempt, fields) {
+    for (const [column, value] of Object.entries(fields)) {
+      if (value != null && attempt[column] != null && attempt[column] !== value) {
+        throw codexError(
+          `Codex attempt ${column} is immutable`,
+          'CODEX_ATTEMPT_IDENTITY_MISMATCH',
+        );
+      }
+    }
+  }
+
+  const idempotentCheckpointKinds = new Set([
+    'request-prepared',
+    'request-write-attempted',
+    'request-response-observed',
+    'thread-initialized',
+    'turn-accepted',
+    'turn-steer-accepted',
+    'turn-started',
+    'item-started',
+    'item-completed',
+    'turn-terminal',
+    'active-start-cancelled',
+    'queued-send-cancelled',
+    'telegram-delivery-settled',
+    'telegram-delivery-failed',
+  ]);
+
+  function hasExactCodexCheckpoint({
+    generationId,
+    attemptId,
+    kind,
+    threadId,
+    turnId,
+    requestId,
+    itemId,
+    detailJson,
+  }) {
+    if (!idempotentCheckpointKinds.has(kind)) return false;
+    return db.prepare(`
+      SELECT 1
+        FROM codex_attempt_checkpoints
+       WHERE generation_id = ?
+         AND attempt_id IS ?
+         AND kind = ?
+         AND thread_id IS ?
+         AND turn_id IS ?
+         AND request_id IS ?
+         AND item_id IS ?
+         AND detail_json IS ?
+       LIMIT 1
+    `).get(
+      generationId,
+      attemptId,
+      kind,
+      threadId,
+      turnId,
+      requestId,
+      itemId,
+      detailJson,
+    ) != null;
+  }
+
+  function settleCodexInboundReservation(reservation, handlerStatus) {
+    const inbound = db.prepare(`
+      SELECT handler_status
+        FROM messages
+       WHERE direction = 'in'
+         AND bot_name = ?
+         AND chat_id = ?
+         AND CAST(msg_id AS TEXT) = ?
+    `).get(
+      reservation.bot_name,
+      reservation.telegram_chat_id,
+      reservation.telegram_message_id,
+    );
+    if (!inbound) {
+      throw codexError(
+        'Codex disposition has no exact inbound message',
+        'CODEX_LINKED_INPUT_MESSAGE_NOT_FOUND',
+      );
+    }
+    if (inbound.handler_status === handlerStatus) return;
+    if (![
+      'received',
+      'dispatched',
+      'processing',
+      'replay-pending',
+    ].includes(inbound.handler_status)) {
+      throw codexError(
+        'Codex disposition conflicts with the inbound message state',
+        'CODEX_LINKED_INPUT_MESSAGE_NOT_FOUND',
+      );
+    }
+    db.prepare(`
+      UPDATE messages
+         SET handler_status = ?
+       WHERE direction = 'in'
+         AND bot_name = ?
+         AND chat_id = ?
+         AND CAST(msg_id AS TEXT) = ?
+    `).run(
+      handlerStatus,
+      reservation.bot_name,
+      reservation.telegram_chat_id,
+      reservation.telegram_message_id,
+    );
+  }
+
+  function settleCodexPrimaryInbound(attempt, handlerStatus) {
+    if (attempt.telegram_source_message_id == null) return;
+    const selections = db.prepare(`
+      SELECT *
+        FROM inbound_runtime_selections
+       WHERE session_key = ?
+         AND telegram_message_id = ?
+         AND provider = 'codex'
+       ORDER BY bot_name, telegram_chat_id
+    `).all(
+      attempt.session_key,
+      attempt.telegram_source_message_id,
+    );
+    if (selections.length > 1) {
+      throw codexError(
+        'Codex attempt matches conflicting inbound runtime selections',
+        'INBOUND_RUNTIME_SELECTION_CONFLICT',
+      );
+    }
+    if (selections.length === 1) {
+      settleCodexInboundReservation(selections[0], handlerStatus);
+    }
+  }
+
+  function settleCodexAttemptConsumerOutcome({
+    attempt,
+    generationId,
+    linkedState,
+    attemptRecoveryState,
+    settleQueuedReservation,
+    ts,
+  }) {
+    db.prepare(`
+      UPDATE codex_turn_attempts
+         SET recovery_state = ?,
+             settled_ts = ?,
+             updated_ts = ?
+       WHERE attempt_id = ?
+    `).run(attemptRecoveryState, ts, ts, attempt.attempt_id);
+
+    const handlerStatus = linkedState === 'settled' ? 'replied' : 'failed';
+    settleCodexPrimaryInbound(attempt, handlerStatus);
+
+    const acceptedSteers = attempt.turn_id == null
+      ? []
+      : db.prepare(`
+        SELECT *
+          FROM codex_turn_attempts
+         WHERE generation_id = ?
+           AND method = 'turn/steer'
+           AND turn_id = ?
+           AND delivery_state = 'response-observed'
+           AND response_outcome = 'result'
+           AND recovery_state = 'active'
+         ORDER BY created_ts, attempt_id
+      `).all(generationId, attempt.turn_id);
+    for (const steer of acceptedSteers) {
+      if (steer.telegram_source_message_id == null) continue;
+      const reservations = db.prepare(`
+        SELECT *
+          FROM codex_dispatch_reservations
+         WHERE generation_id = ?
+           AND session_key = ?
+           AND telegram_message_id = ?
+           AND state = 'reserved'
+         ORDER BY reservation_id
+      `).all(
+        generationId,
+        steer.session_key,
+        steer.telegram_source_message_id,
+      );
+      if (reservations.length > 1) {
+        throw codexError(
+          'Codex accepted steer matches conflicting reservations',
+          'CODEX_DISPATCH_RESERVATION_CONFLICT',
+        );
+      }
+      if (reservations.length === 0) continue;
+      const reservation = reservations[0];
+      settleCodexInboundReservation(reservation, handlerStatus);
+      db.prepare(`
+        INSERT INTO codex_linked_inputs (
+          linked_input_id, generation_id, attempt_id, target_attempt_id,
+          telegram_chat_id, telegram_message_id, state,
+          created_ts, settled_ts
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        reservation.reservation_id,
+        generationId,
+        steer.attempt_id,
+        attempt.attempt_id,
+        reservation.telegram_chat_id,
+        reservation.telegram_message_id,
+        linkedState,
+        reservation.created_ts,
+        ts,
+      );
+      db.prepare(`
+        UPDATE codex_dispatch_reservations
+           SET state = ?,
+               steer_attempt_id = ?,
+               target_attempt_id = ?,
+               updated_ts = ?,
+               settled_ts = ?
+         WHERE reservation_id = ?
+           AND state = 'reserved'
+      `).run(
+        linkedState,
+        steer.attempt_id,
+        attempt.attempt_id,
+        ts,
+        ts,
+        reservation.reservation_id,
+      );
+    }
+
+    const linkedReservations = db.prepare(`
+      SELECT reservation.*
+        FROM codex_dispatch_reservations reservation
+        JOIN codex_linked_inputs linked
+          ON linked.linked_input_id = reservation.reservation_id
+       WHERE linked.target_attempt_id = ?
+         AND reservation.state = 'steer-accepted'
+    `).all(attempt.attempt_id);
+    for (const reservation of linkedReservations) {
+      settleCodexInboundReservation(reservation, handlerStatus);
+    }
+    const linkedAttempts = db.prepare(`
+      SELECT attempt_id
+        FROM codex_linked_inputs
+       WHERE target_attempt_id = ? AND state = 'linked'
+    `).all(attempt.attempt_id);
+    db.prepare(`
+      UPDATE codex_linked_inputs
+         SET state = ?, settled_ts = ?
+       WHERE target_attempt_id = ? AND state = 'linked'
+    `).run(linkedState, ts, attempt.attempt_id);
+    db.prepare(`
+      UPDATE codex_dispatch_reservations
+         SET state = ?, updated_ts = ?, settled_ts = ?
+       WHERE reservation_id IN (
+         SELECT linked_input_id
+           FROM codex_linked_inputs
+          WHERE target_attempt_id = ?
+       )
+         AND state = 'steer-accepted'
+    `).run(linkedState, ts, ts, attempt.attempt_id);
+    for (const linked of linkedAttempts) {
+      db.prepare(`
+        UPDATE codex_turn_attempts
+           SET recovery_state = 'settled',
+               settled_ts = ?,
+               updated_ts = ?
+         WHERE attempt_id = ?
+           AND recovery_state NOT IN ('settled', 'cancelled')
+      `).run(ts, ts, linked.attempt_id);
+    }
+    if (attempt.turn_id != null) {
+      db.prepare(`
+        UPDATE codex_turn_attempts
+           SET recovery_state = 'settled',
+               settled_ts = ?,
+               updated_ts = ?
+         WHERE generation_id = ?
+           AND method = 'turn/steer'
+           AND turn_id = ?
+           AND delivery_state = 'response-observed'
+           AND response_outcome = 'result'
+           AND recovery_state = 'active'
+      `).run(ts, ts, generationId, attempt.turn_id);
+    }
+
+    if (
+      settleQueuedReservation
+      && attempt.telegram_source_message_id != null
+    ) {
+      const queued = db.prepare(`
+        SELECT *
+          FROM codex_dispatch_reservations
+         WHERE generation_id = ?
+           AND session_key = ?
+           AND telegram_message_id = ?
+           AND state = 'queue-authorized'
+         ORDER BY reservation_id
+      `).all(
+        generationId,
+        attempt.session_key,
+        attempt.telegram_source_message_id,
+      );
+      if (queued.length > 1) {
+        throw codexError(
+          'Codex terminal attempt matches conflicting queued reservations',
+          'CODEX_QUEUE_SETTLEMENT_CONFLICT',
+        );
+      }
+      if (queued.length === 1) {
+        settleCodexInboundReservation(queued[0], handlerStatus);
+        db.prepare(`
+          UPDATE codex_dispatch_reservations
+             SET state = ?,
+                 target_attempt_id = ?,
+                 updated_ts = ?,
+                 settled_ts = ?
+           WHERE reservation_id = ?
+             AND state = 'queue-authorized'
+        `).run(
+          linkedState,
+          attempt.attempt_id,
+          ts,
+          ts,
+          queued[0].reservation_id,
+        );
+      }
+    }
+
+    db.prepare(`
+      UPDATE codex_generations
+         SET state = 'healthy-stopped',
+             settled_ts = ?,
+             updated_ts = ?
+       WHERE generation_id = ?
+         AND EXISTS (
+           SELECT 1
+             FROM codex_attempt_checkpoints
+            WHERE generation_id = ?
+              AND kind = 'stop-empty-registry-observed'
+         )
+         AND NOT EXISTS (
+           SELECT 1
+             FROM codex_turn_attempts
+            WHERE generation_id = ?
+              AND recovery_state NOT IN ('settled', 'cancelled')
+         )
+    `).run(ts, ts, generationId, generationId, generationId);
+  }
+
+  function recordCodexCheckpoint(input) {
+    const kind = requiredCodexString(input?.kind, 'checkpoint kind');
+    if (!codexCheckpointKinds.has(kind)) {
+      throw codexError(
+        'Codex checkpoint kind is not allowlisted',
+        'CODEX_CHECKPOINT_KIND_REJECTED',
+      );
+    }
+    const generationId = requiredCodexString(
+      input?.generationId ?? input?.generation_id,
+      'generation ID',
+    );
+    const stableHostId = requiredCodexString(
+      input?.stable_host_id ?? input?.hostIdentity,
+      'stable host identity',
+    );
+    const bootSessionId = requiredCodexString(
+      input?.boot_session_id ?? input?.bootSessionIdentity,
+      'boot-session identity',
+    );
+    const attemptId = optionalCodexString(
+      input?.attemptId ?? input?.attempt_id,
+      'attempt ID',
+    );
+    const threadId = optionalCodexString(
+      input?.threadId ?? input?.thread_id,
+      'thread ID',
+    );
+    const turnId = optionalCodexString(
+      input?.turnId ?? input?.turn_id,
+      'turn ID',
+    );
+    const requestId = optionalCodexRequestId(
+      input?.requestId ?? input?.request_id,
+    );
+    const itemId = optionalCodexString(
+      input?.itemId ?? input?.item_id,
+      'item ID',
+    );
+    const method = optionalCodexString(input?.method, 'request method');
+    const sourceId = optionalCodexString(input?.source, 'source message ID');
+    const clientUserMessageId = optionalCodexString(
+      input?.clientUserMessageId ?? input?.client_user_message_id,
+      'client user message ID',
+    );
+    const ts = requiredTimestamp(input?.ts ?? Date.now(), 'checkpoint timestamp');
+    const detailJson = checkpointDetail(input);
+
+    return db.transaction(() => {
+      const generation = assertCodexGenerationIdentity(
+        generationId,
+        stableHostId,
+        bootSessionId,
+      );
+      let attempt = attemptId
+        ? db.prepare(`
+          SELECT * FROM codex_turn_attempts WHERE attempt_id = ?
+        `).get(attemptId)
+        : null;
+      if (attempt) {
+        assertCodexAttemptIdentity(attempt, {
+          method,
+          thread_id: threadId,
+          turn_id: turnId,
+          request_id: requestId,
+          telegram_source_message_id: sourceId,
+          client_user_message_id: clientUserMessageId,
+        });
+        if (hasExactCodexCheckpoint({
+          generationId,
+          attemptId,
+          kind,
+          threadId,
+          turnId,
+          requestId,
+          itemId,
+          detailJson,
+        })) {
+          return { changes: 0, attemptId, kind };
+        }
+      }
+      assertCodexCheckpointOwner(generation, kind);
+
+      if (kind === 'request-prepared') {
+        requiredCodexString(method, 'request method');
+        if (!attemptId) {
+          throw codexError(
+            'Codex prepared checkpoint requires an attempt ID',
+            'CODEX_CHECKPOINT_INPUT_INVALID',
+          );
+        }
+        if (attempt) {
+          if (
+            attempt.generation_id === generationId
+            && attempt.method === method
+            && attempt.delivery_state === 'prepared'
+          ) {
+            return { changes: 0, attemptId, kind };
+          }
+          throw codexError(
+            'Codex attempt ID was reused with different metadata',
+            'CODEX_ATTEMPT_ID_REUSED',
+          );
+        }
+        db.prepare(`
+          INSERT INTO codex_turn_attempts (
+            attempt_id, generation_id, session_key, method,
+            thread_id, turn_id, telegram_source_message_id,
+            client_user_message_id, delivery_state, recovery_state,
+            created_ts, updated_ts
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'prepared', 'prepared', ?, ?)
+        `).run(
+          attemptId,
+          generationId,
+          generation.session_key,
+          method,
+          threadId,
+          turnId,
+          sourceId,
+          clientUserMessageId,
+          ts,
+          ts,
+        );
+        attempt = requireCodexAttempt(attemptId, generationId);
+      } else if (kind === 'queued-send-cancelled' && attemptId && !attempt) {
+        db.prepare(`
+          INSERT INTO codex_turn_attempts (
+            attempt_id, generation_id, session_key, method,
+            thread_id, turn_id, telegram_source_message_id,
+            client_user_message_id, delivery_state, recovery_state,
+            created_ts, updated_ts, settled_ts
+          ) VALUES (?, ?, ?, 'queued/send', ?, ?, ?, ?,
+                    'prepared', 'cancelled', ?, ?, ?)
+        `).run(
+          attemptId,
+          generationId,
+          generation.session_key,
+          threadId,
+          turnId,
+          sourceId,
+          clientUserMessageId,
+          ts,
+          ts,
+          ts,
+        );
+        attempt = requireCodexAttempt(attemptId, generationId);
+      } else if (attemptId) {
+        attempt = requireCodexAttempt(attemptId, generationId);
+      }
+
+      if (kind === 'request-write-attempted') {
+        if (attempt.delivery_state !== 'prepared') {
+          throw codexError(
+            'Codex write-attempted checkpoint is out of order',
+            'CODEX_CHECKPOINT_SEQUENCE_INVALID',
+          );
+        }
+        db.prepare(`
+          UPDATE codex_turn_attempts
+             SET request_id = ?,
+                 delivery_state = 'write-attempted',
+                 recovery_state = 'ambiguous',
+                 ambiguous_ts = COALESCE(ambiguous_ts, ?),
+                 updated_ts = ?
+           WHERE attempt_id = ?
+        `).run(requestId, ts, ts, attemptId);
+      } else if (kind === 'request-response-observed') {
+        if (attempt.delivery_state !== 'write-attempted') {
+          throw codexError(
+            'Codex response-observed checkpoint is out of order',
+            'CODEX_CHECKPOINT_SEQUENCE_INVALID',
+          );
+        }
+        if (!['result', 'error'].includes(input?.outcome)) {
+          throw codexError(
+            'Codex response checkpoint outcome is invalid',
+            'CODEX_CHECKPOINT_INPUT_INVALID',
+          );
+        }
+        db.prepare(`
+          UPDATE codex_turn_attempts
+             SET request_id = COALESCE(request_id, ?),
+                 delivery_state = 'response-observed',
+                 response_outcome = ?,
+                 updated_ts = ?
+           WHERE attempt_id = ?
+        `).run(requestId, input.outcome, ts, attemptId);
+      } else if (
+        ['turn-accepted', 'turn-steer-accepted'].includes(kind)
+      ) {
+        if (!attempt) {
+          throw codexError(
+            'Codex turn lifecycle checkpoint requires an attempt',
+            'CODEX_CHECKPOINT_INPUT_INVALID',
+          );
+        }
+        if (
+          attempt.delivery_state !== 'response-observed'
+          || attempt.response_outcome !== 'result'
+        ) {
+          throw codexError(
+            'Codex accepted checkpoint has no successful response predecessor',
+            'CODEX_CHECKPOINT_SEQUENCE_INVALID',
+          );
+        }
+        db.prepare(`
+          UPDATE codex_turn_attempts
+             SET turn_id = COALESCE(?, turn_id),
+                 recovery_state = CASE
+                   WHEN terminal_status IS NULL THEN 'active'
+                   ELSE 'terminal-pending'
+                 END,
+                 updated_ts = ?
+           WHERE attempt_id = ?
+        `).run(turnId, ts, attemptId);
+        db.prepare(`
+          UPDATE codex_generations
+             SET thread_id = COALESCE(?, thread_id),
+                 state = 'active',
+                 updated_ts = ?
+           WHERE generation_id = ?
+        `).run(threadId, ts, generationId);
+      } else if (kind === 'turn-started') {
+        if (
+          !attempt
+          || attempt.terminal_status != null
+          || !(
+            attempt.recovery_state === 'active'
+            || (
+              attempt.recovery_state === 'ambiguous'
+              && ['write-attempted', 'response-observed'].includes(
+                attempt.delivery_state,
+              )
+            )
+          )
+        ) {
+          throw codexError(
+            'Codex turn-started checkpoint has no dispatched predecessor',
+            'CODEX_CHECKPOINT_SEQUENCE_INVALID',
+          );
+        }
+        db.prepare(`
+          UPDATE codex_turn_attempts
+             SET turn_id = COALESCE(?, turn_id), updated_ts = ?
+           WHERE attempt_id = ?
+        `).run(turnId, ts, attemptId);
+      } else if (
+        ['item-started', 'item-completed', 'item-delta-observed'].includes(kind)
+      ) {
+        const notificationBeforeResponse = (
+          attempt?.recovery_state === 'ambiguous'
+          && ['write-attempted', 'response-observed'].includes(
+            attempt?.delivery_state,
+          )
+        );
+        if (
+          !attempt
+          || attempt.turn_id == null
+          || attempt.terminal_status != null
+          || !(attempt.recovery_state === 'active' || notificationBeforeResponse)
+        ) {
+          throw codexError(
+            'Codex item checkpoint requires a live dispatched turn',
+            'CODEX_CHECKPOINT_SEQUENCE_INVALID',
+          );
+        }
+        db.prepare(`
+          UPDATE codex_turn_attempts
+             SET updated_ts = ?
+           WHERE attempt_id = ?
+        `).run(ts, attemptId);
+        if (kind !== 'item-delta-observed' && itemId) {
+          recordCodexItemEffect({
+            generation_id: generationId,
+            attempt_id: attemptId,
+            item_id: itemId,
+            item_type: input?.itemType ?? 'unknown',
+            state: kind === 'item-started' ? 'started' : 'completed',
+            ts,
+          });
+        }
+      } else if (kind === 'turn-terminal') {
+        if (
+          !attempt
+          || attempt.turn_id == null
+          || attempt.terminal_status != null
+          || !(
+            attempt.recovery_state === 'active'
+            || (
+              attempt.recovery_state === 'ambiguous'
+              && ['write-attempted', 'response-observed'].includes(
+                attempt.delivery_state,
+              )
+            )
+          )
+          || !['completed', 'interrupted', 'failed'].includes(
+          input?.terminalStatus,
+          )
+        ) {
+          throw codexError(
+            'Codex turn terminal checkpoint is invalid',
+            'CODEX_CHECKPOINT_INPUT_INVALID',
+          );
+        }
+        db.prepare(`
+          UPDATE codex_turn_attempts
+             SET turn_id = COALESCE(?, turn_id),
+                 terminal_status = ?,
+                 recovery_state = CASE
+                   WHEN recovery_state = 'active' THEN 'terminal-pending'
+                   ELSE recovery_state
+                 END,
+                 updated_ts = ?
+           WHERE attempt_id = ?
+        `).run(turnId, input.terminalStatus, ts, attemptId);
+      } else if (
+        ['stop-terminal-reconciled', 'background-terminal-reconciled']
+          .includes(kind)
+      ) {
+        db.prepare(`
+          UPDATE codex_turn_attempts
+             SET recovery_state = 'clean-pending', updated_ts = ?
+           WHERE generation_id = ?
+             AND method IN ('turn/start', 'turn/interrupt')
+             AND recovery_state NOT IN ('settled', 'cancelled')
+             AND (? IS NULL OR turn_id = ?)
+        `).run(ts, generationId, turnId, turnId);
+      } else if (
+        ['stop-clean-accepted', 'background-clean-accepted'].includes(kind)
+      ) {
+        db.prepare(`
+          UPDATE codex_turn_attempts
+             SET recovery_state = 'empty-registry-pending', updated_ts = ?
+           WHERE generation_id = ?
+             AND method = 'thread/backgroundTerminals/clean'
+             AND recovery_state NOT IN ('settled', 'cancelled')
+        `).run(ts, generationId);
+      } else if (
+        ['stop-empty-registry-observed', 'background-empty-registry-observed']
+          .includes(kind)
+      ) {
+        db.prepare(`
+          UPDATE codex_turn_attempts
+             SET recovery_state = 'settled',
+                 settled_ts = ?,
+                 updated_ts = ?
+           WHERE generation_id = ?
+             AND method IN (
+               'turn/interrupt',
+               'thread/backgroundTerminals/clean'
+             )
+             AND recovery_state NOT IN ('settled', 'cancelled')
+        `).run(ts, ts, generationId);
+        if (kind === 'stop-empty-registry-observed') {
+          db.prepare(`
+            UPDATE codex_generations
+               SET state = 'healthy-stopped',
+                   settled_ts = ?,
+                   updated_ts = ?
+             WHERE generation_id = ?
+               AND NOT EXISTS (
+                 SELECT 1
+                   FROM codex_turn_attempts
+                  WHERE generation_id = ?
+                    AND recovery_state NOT IN ('settled', 'cancelled')
+               )
+          `).run(ts, ts, generationId, generationId);
+        }
+      } else if (
+        ['telegram-delivery-settled', 'telegram-delivery-failed']
+          .includes(kind)
+      ) {
+        if (!attempt || ![
+          'terminal-pending',
+          'clean-pending',
+          'empty-registry-pending',
+        ].includes(
+          attempt.recovery_state,
+        )) {
+          throw codexError(
+            'Codex delivery settlement requires a terminal attempt',
+            'CODEX_CHECKPOINT_SEQUENCE_INVALID',
+          );
+        }
+        const deliveryFailed = kind === 'telegram-delivery-failed';
+        const linkedState = deliveryFailed
+          ? 'failed'
+          : attempt.terminal_status === 'interrupted'
+            ? 'interrupted'
+            : attempt.terminal_status === 'failed'
+              ? 'failed'
+              : 'settled';
+        settleCodexAttemptConsumerOutcome({
+          attempt,
+          generationId,
+          linkedState,
+          attemptRecoveryState: 'settled',
+          settleQueuedReservation: true,
+          ts,
+        });
+      } else if (
+        ['active-start-cancelled', 'queued-send-cancelled'].includes(kind)
+      ) {
+        if (attempt) {
+          db.prepare(`
+            UPDATE codex_turn_attempts
+               SET recovery_state = 'cancelled',
+                   settled_ts = ?,
+                   updated_ts = ?
+             WHERE attempt_id = ?
+          `).run(ts, ts, attemptId);
+        }
+      } else if (kind === 'failed-ambiguous-entered') {
+        if (attempt) {
+          db.prepare(`
+            UPDATE codex_turn_attempts
+               SET recovery_state = 'ambiguous',
+                   ambiguous_ts = COALESCE(ambiguous_ts, ?),
+                   updated_ts = ?
+             WHERE attempt_id = ?
+          `).run(ts, ts, attemptId);
+          db.prepare(`
+            UPDATE codex_linked_inputs
+               SET state = 'ambiguous', settled_ts = ?
+             WHERE (
+               attempt_id = ?
+               OR target_attempt_id = ?
+             )
+               AND state = 'linked'
+          `).run(ts, attemptId, attemptId);
+          db.prepare(`
+            UPDATE codex_dispatch_reservations
+               SET state = 'ambiguous',
+                   updated_ts = ?,
+                   settled_ts = NULL
+             WHERE (
+               steer_attempt_id = ?
+               OR target_attempt_id = ?
+             )
+               AND state IN (
+                 'reserved', 'steer-accepted', 'queue-authorized'
+               )
+          `).run(ts, attemptId, attemptId);
+          db.prepare(`
+            UPDATE messages
+               SET handler_status = 'codex-ambiguous'
+             WHERE direction = 'in'
+               AND handler_status IN (
+                 'received', 'dispatched', 'processing', 'replay-pending'
+               )
+               AND EXISTS (
+                 SELECT 1
+                   FROM codex_dispatch_reservations reservation
+                  WHERE (
+                    reservation.steer_attempt_id = ?
+                    OR reservation.target_attempt_id = ?
+                  )
+                    AND reservation.state = 'ambiguous'
+                    AND reservation.bot_name = messages.bot_name
+                    AND reservation.telegram_chat_id = messages.chat_id
+                    AND reservation.telegram_message_id
+                      = CAST(messages.msg_id AS TEXT)
+               )
+          `).run(attemptId, attemptId);
+        } else {
+          markGenerationAttemptsAmbiguous(generationId, ts);
+        }
+      } else if (kind === 'containment-entered') {
+        const reason = optionalCodexString(
+          input?.reason,
+          'containment reason',
+        );
+        db.prepare(`
+          UPDATE codex_generations
+             SET state = 'containment-failed',
+                 containment_reason = ?,
+                 updated_ts = ?
+           WHERE generation_id = ?
+        `).run(reason, ts, generationId);
+        markGenerationAttemptsAmbiguous(generationId, ts);
+        const lease = db.prepare(`
+          SELECT generation_id
+            FROM codex_daemon_lease
+           WHERE singleton = 1
+        `).get();
+        if (!lease || lease.generation_id !== generationId) {
+          throw codexError(
+            'Codex containment checkpoint requires the owned daemon lease',
+            'CODEX_LEASE_MISMATCH',
+          );
+        }
+        db.prepare(`
+          UPDATE codex_daemon_lease
+             SET status = 'quarantined',
+                 quarantine_reason = ?,
+                 updated_ts = ?
+           WHERE singleton = 1
+        `).run(reason, ts);
+      } else if (kind === 'thread-initialized') {
+        const initializing = db.prepare(`
+          SELECT attempt_id, delivery_state, response_outcome
+            FROM codex_turn_attempts
+           WHERE generation_id = ?
+             AND method IN ('thread/start', 'thread/resume')
+             AND recovery_state NOT IN ('settled', 'cancelled')
+           ORDER BY created_ts DESC
+           LIMIT 1
+        `).get(generationId);
+        if (
+          !initializing
+          || initializing.delivery_state !== 'response-observed'
+          || initializing.response_outcome !== 'result'
+        ) {
+          throw codexError(
+            'Codex thread initialization has no successful response predecessor',
+            'CODEX_CHECKPOINT_SEQUENCE_INVALID',
+          );
+        }
+        db.prepare(`
+          UPDATE codex_generations
+             SET thread_id = COALESCE(?, thread_id), updated_ts = ?
+           WHERE generation_id = ?
+        `).run(threadId, ts, generationId);
+        db.prepare(`
+          UPDATE codex_turn_attempts
+             SET thread_id = COALESCE(?, thread_id),
+                 recovery_state = 'settled',
+                 settled_ts = ?,
+                 updated_ts = ?
+           WHERE attempt_id = (
+             SELECT attempt_id
+               FROM codex_turn_attempts
+              WHERE generation_id = ?
+                AND method IN ('thread/start', 'thread/resume')
+                AND recovery_state NOT IN ('settled', 'cancelled')
+              ORDER BY created_ts DESC
+              LIMIT 1
+           )
+        `).run(threadId, ts, ts, generationId);
+      } else if (kind === 'thread-status-changed') {
+        requiredCodexString(input?.statusType, 'thread status type');
+      }
+
+      db.prepare(`
+        INSERT INTO codex_attempt_checkpoints (
+          generation_id, attempt_id, kind, thread_id, turn_id,
+          request_id, item_id, detail_json, ts
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        generationId,
+        attemptId,
+        kind,
+        threadId,
+        turnId,
+        requestId,
+        itemId,
+        detailJson,
+        ts,
+      );
+      return { changes: 1, attemptId, kind };
+    })();
+  }
+
+  function recordCodexDeliveryCheckpoint(input) {
+    const allowed = new Set(['checkpoint', 'retireGeneration']);
+    assertExactKeys(
+      input,
+      allowed,
+      'CODEX_DELIVERY_PAYLOAD_REJECTED',
+      'delivery checkpoint',
+    );
+    const checkpoint = input?.checkpoint;
+    if (
+      !checkpoint
+      || ![
+        'telegram-delivery-settled',
+        'telegram-delivery-failed',
+      ].includes(checkpoint.kind)
+      || typeof input.retireGeneration !== 'boolean'
+    ) {
+      throw codexError(
+        'Codex delivery checkpoint payload is invalid',
+        'CODEX_DELIVERY_PAYLOAD_REJECTED',
+      );
+    }
+    return db.transaction(() => {
+      const result = recordCodexCheckpoint(checkpoint);
+      if (!input.retireGeneration) {
+        return { ...result, retired: false };
+      }
+      const generationId = requiredCodexString(
+        checkpoint.generationId ?? checkpoint.generation_id,
+        'generation ID',
+      );
+      const ts = requiredTimestamp(
+        checkpoint.ts ?? Date.now(),
+        'delivery checkpoint timestamp',
+      );
+      const retirement = retireCodexGeneration(generationId, ts, {
+        onlyIfHealthyStopped: true,
+      });
+      if (!retirement.retired) {
+        throw codexError(
+          'Codex delivery could not prove a healthy stopped generation',
+          'CODEX_RETIREMENT_UNVERIFIED',
+        );
+      }
+      return { ...result, retired: true };
+    })();
+  }
+
+  function readCodexDispatchReservation(reservationId) {
+    return db.prepare(`
+      SELECT *
+        FROM codex_dispatch_reservations
+       WHERE reservation_id = ?
+    `).get(reservationId);
+  }
+
+  function recordInboundRuntimeSelection(input) {
+    const allowed = new Set([
+      'session_key',
+      'bot_name',
+      'telegram_chat_id',
+      'telegram_message_id',
+      'provider',
+      'ts',
+    ]);
+    assertExactKeys(
+      input,
+      allowed,
+      'INBOUND_RUNTIME_SELECTION_PAYLOAD_REJECTED',
+      'inbound runtime selection',
+    );
+    const sessionKey = requiredCodexString(input?.session_key, 'session key');
+    const botName = requiredCodexString(input?.bot_name, 'bot name');
+    const telegramChatId = requiredCodexString(
+      input?.telegram_chat_id,
+      'Telegram chat ID',
+    );
+    const telegramMessageId = requiredCodexString(
+      input?.telegram_message_id,
+      'Telegram message ID',
+    );
+    const provider = input?.provider;
+    if (!['claude', 'codex'].includes(provider)) {
+      throw codexError(
+        'Inbound runtime provider is invalid',
+        'INBOUND_RUNTIME_SELECTION_INVALID',
+      );
+    }
+    const ts = requiredTimestamp(
+      input?.ts ?? Date.now(),
+      'inbound runtime selection timestamp',
+    );
+
+    return db.transaction(() => {
+      const existing = db.prepare(`
+        SELECT *
+          FROM inbound_runtime_selections
+         WHERE bot_name = ?
+           AND telegram_chat_id = ?
+           AND telegram_message_id = ?
+      `).get(botName, telegramChatId, telegramMessageId);
+      if (existing) {
+        if (
+          existing.session_key === sessionKey
+          && existing.provider === provider
+        ) {
+          return { changes: 0, selection: existing };
+        }
+        throw codexError(
+          'Inbound runtime selection conflicts with durable identity',
+          'INBOUND_RUNTIME_SELECTION_CONFLICT',
+        );
+      }
+      const inbound = db.prepare(`
+        SELECT direction, bot_name
+          FROM messages
+         WHERE chat_id = ?
+           AND CAST(msg_id AS TEXT) = ?
+      `).get(telegramChatId, telegramMessageId);
+      if (inbound?.direction !== 'in' || inbound.bot_name !== botName) {
+        throw codexError(
+          'Inbound runtime selection has no exact inbound message',
+          'INBOUND_RUNTIME_SELECTION_INBOUND_MISMATCH',
+        );
+      }
+      db.prepare(`
+        INSERT INTO inbound_runtime_selections (
+          bot_name, telegram_chat_id, telegram_message_id,
+          session_key, provider, selected_ts
+        ) VALUES (?, ?, ?, ?, ?, ?)
+      `).run(
+        botName,
+        telegramChatId,
+        telegramMessageId,
+        sessionKey,
+        provider,
+        ts,
+      );
+      return {
+        changes: 1,
+        selection: db.prepare(`
+          SELECT *
+            FROM inbound_runtime_selections
+           WHERE bot_name = ?
+             AND telegram_chat_id = ?
+             AND telegram_message_id = ?
+        `).get(botName, telegramChatId, telegramMessageId),
+      };
+    })();
+  }
+
+  function publicCodexAttempt(attempt) {
+    if (!attempt) return null;
+    return {
+      attemptId: attempt.attempt_id,
+      generationId: attempt.generation_id,
+      method: attempt.method,
+      deliveryState: attempt.delivery_state,
+      recoveryState: attempt.recovery_state,
+      turnId: attempt.turn_id,
+      terminalStatus: attempt.terminal_status,
+    };
+  }
+
+  function publicRuntimeSelection(selection) {
+    return {
+      provider: selection.provider,
+      sessionKey: selection.session_key,
+      selectedTs: selection.selected_ts,
+    };
+  }
+
+  function getReplayProviderRecovery(input) {
+    const allowed = new Set([
+      'sessionKey',
+      'botName',
+      'telegramChatId',
+      'telegramMessageId',
+    ]);
+    assertExactKeys(
+      input,
+      allowed,
+      'REPLAY_PROVIDER_RECOVERY_PAYLOAD_REJECTED',
+      'replay provider recovery',
+    );
+    const sessionKey = requiredCodexString(input?.sessionKey, 'session key');
+    const botName = requiredCodexString(input?.botName, 'bot name');
+    const telegramChatId = requiredCodexString(
+      input?.telegramChatId,
+      'Telegram chat ID',
+    );
+    const telegramMessageId = requiredCodexString(
+      input?.telegramMessageId,
+      'Telegram message ID',
+    );
+    const unknown = (reason) => ({ provider: 'unknown', reason });
+    const selection = db.prepare(`
+      SELECT *
+        FROM inbound_runtime_selections
+       WHERE bot_name = ?
+         AND telegram_chat_id = ?
+         AND telegram_message_id = ?
+    `).get(botName, telegramChatId, telegramMessageId);
+    if (!selection) return unknown('selection-missing');
+    if (selection.session_key !== sessionKey) {
+      return unknown('selection-conflict');
+    }
+
+    const reservations = db.prepare(`
+      SELECT *
+        FROM codex_dispatch_reservations
+       WHERE bot_name = ?
+         AND telegram_chat_id = ?
+         AND telegram_message_id = ?
+    `).all(botName, telegramChatId, telegramMessageId);
+    const attempts = db.prepare(`
+      SELECT attempt.*
+        FROM codex_turn_attempts attempt
+        JOIN codex_generations generation
+          ON generation.generation_id = attempt.generation_id
+       WHERE generation.session_key = ?
+         AND attempt.telegram_source_message_id = ?
+       ORDER BY attempt.created_ts, attempt.attempt_id
+    `).all(sessionKey, telegramMessageId);
+    const linkedInputs = db.prepare(`
+      SELECT linked.*
+        FROM codex_linked_inputs linked
+        JOIN codex_generations generation
+          ON generation.generation_id = linked.generation_id
+       WHERE generation.session_key = ?
+         AND linked.telegram_chat_id = ?
+         AND linked.telegram_message_id = ?
+       ORDER BY linked.created_ts, linked.linked_input_id
+    `).all(sessionKey, telegramChatId, telegramMessageId);
+    const hasCodexEvidence = (
+      reservations.length > 0
+      || attempts.length > 0
+      || linkedInputs.length > 0
+    );
+    if (selection.provider === 'claude') {
+      return hasCodexEvidence
+        ? unknown('provider-evidence-conflict')
+        : {
+          provider: 'claude',
+          kind: 'selected',
+          selection: publicRuntimeSelection(selection),
+        };
+    }
+    if (
+      reservations.length > 1
+      || attempts.length > 1
+      || linkedInputs.length > 1
+    ) {
+      return unknown('codex-evidence-conflict');
+    }
+
+    const reservation = reservations[0] ?? null;
+    const attempt = attempts[0] ?? null;
+    const linkedInput = linkedInputs[0] ?? null;
+    if (
+      reservation
+      && (
+        reservation.session_key !== sessionKey
+        || (
+          attempt
+          && reservation.generation_id !== attempt.generation_id
+        )
+      )
+    ) {
+      return unknown('codex-evidence-conflict');
+    }
+    if (
+      attempt
+      && !['turn/start', 'turn/steer'].includes(attempt.method)
+    ) {
+      return unknown('codex-evidence-conflict');
+    }
+
+    let kind = 'selection-only';
+    let targetAttempt = null;
+    if (linkedInput) {
+      if (
+        !attempt
+        || linkedInput.attempt_id !== attempt.attempt_id
+        || linkedInput.generation_id !== attempt.generation_id
+        || (
+          reservation
+          && (
+            reservation.reservation_id !== linkedInput.linked_input_id
+            || reservation.steer_attempt_id !== attempt.attempt_id
+            || reservation.target_attempt_id !== linkedInput.target_attempt_id
+          )
+        )
+      ) {
+        return unknown('codex-evidence-conflict');
+      }
+      targetAttempt = db.prepare(`
+        SELECT attempt.*
+          FROM codex_turn_attempts attempt
+          JOIN codex_generations generation
+            ON generation.generation_id = attempt.generation_id
+         WHERE attempt.attempt_id = ?
+           AND attempt.generation_id = ?
+           AND generation.session_key = ?
+      `).get(
+        linkedInput.target_attempt_id,
+        linkedInput.generation_id,
+        sessionKey,
+      );
+      if (
+        !targetAttempt
+        || targetAttempt.method !== 'turn/start'
+        || targetAttempt.turn_id !== attempt.turn_id
+      ) {
+        return unknown('codex-evidence-conflict');
+      }
+      kind = 'linked-input';
+    } else if (reservation) {
+      if (reservation.steer_attempt_id != null) {
+        return unknown('codex-evidence-conflict');
+      }
+      if (
+        reservation.target_attempt_id != null
+        && (
+          !attempt
+          || reservation.target_attempt_id !== attempt.attempt_id
+          || attempt.method !== 'turn/start'
+        )
+      ) {
+        return unknown('codex-evidence-conflict');
+      }
+      if (reservation.target_attempt_id != null) {
+        targetAttempt = attempt;
+      }
+      if (attempt && attempt.method !== 'turn/start') {
+        return unknown('codex-evidence-conflict');
+      }
+      kind = 'dispatch-reservation';
+    } else if (attempt) {
+      if (attempt.method !== 'turn/start') {
+        return unknown('codex-evidence-conflict');
+      }
+      kind = 'primary-turn';
+    }
+
+    return {
+      provider: 'codex',
+      kind,
+      selection: publicRuntimeSelection(selection),
+      reservation: reservation
+        ? {
+          reservationId: reservation.reservation_id,
+          generationId: reservation.generation_id,
+          state: reservation.state,
+          targetAttemptId: reservation.target_attempt_id,
+        }
+        : null,
+      attempt: publicCodexAttempt(attempt),
+      linkedInput: linkedInput
+        ? {
+          linkedInputId: linkedInput.linked_input_id,
+          state: linkedInput.state,
+          attemptId: linkedInput.attempt_id,
+          targetAttemptId: linkedInput.target_attempt_id,
+        }
+        : null,
+      targetAttempt: publicCodexAttempt(targetAttempt),
+    };
+  }
+
+  function assertCodexDispatchReservationIdentity(
+    reservation,
+    generationId,
+  ) {
+    if (!reservation) {
+      throw codexError(
+        'Codex dispatch reservation does not exist',
+        'CODEX_DISPATCH_RESERVATION_NOT_FOUND',
+      );
+    }
+    if (reservation.generation_id !== generationId) {
+      throw codexError(
+        'Codex dispatch reservation belongs to another generation',
+        'CODEX_DISPATCH_RESERVATION_CONFLICT',
+      );
+    }
+    return reservation;
+  }
+
+  function claimCodexDispatchReservation(input) {
+    const allowed = new Set([
+      'reservation_id',
+      'generation_id',
+      'session_key',
+      'bot_name',
+      'telegram_chat_id',
+      'telegram_message_id',
+      'stable_host_id',
+      'boot_session_id',
+      'ts',
+    ]);
+    assertExactKeys(
+      input,
+      allowed,
+      'CODEX_DISPATCH_RESERVATION_PAYLOAD_REJECTED',
+      'dispatch reservation',
+    );
+    const reservationId = requiredCodexString(
+      input?.reservation_id,
+      'dispatch reservation ID',
+    );
+    const generationId = requiredCodexString(
+      input?.generation_id,
+      'generation ID',
+    );
+    const sessionKey = requiredCodexString(
+      input?.session_key,
+      'session key',
+    );
+    const botName = requiredCodexString(input?.bot_name, 'bot name');
+    const telegramChatId = requiredCodexString(
+      input?.telegram_chat_id,
+      'Telegram chat ID',
+    );
+    const telegramMessageId = requiredCodexString(
+      input?.telegram_message_id,
+      'Telegram message ID',
+    );
+    const stableHostId = requiredCodexString(
+      input?.stable_host_id,
+      'stable host identity',
+    );
+    const bootSessionId = requiredCodexString(
+      input?.boot_session_id,
+      'boot-session identity',
+    );
+    const ts = requiredTimestamp(
+      input?.ts ?? Date.now(),
+      'dispatch reservation timestamp',
+    );
+
+    return db.transaction(() => {
+      const generation = assertCodexGenerationIdentity(
+        generationId,
+        stableHostId,
+        bootSessionId,
+      );
+      if (generation.session_key !== sessionKey) {
+        throw codexError(
+          'Codex dispatch session does not own the generation',
+          'CODEX_DISPATCH_SESSION_MISMATCH',
+        );
+      }
+      const existingRows = db.prepare(`
+        SELECT *
+          FROM codex_dispatch_reservations
+         WHERE reservation_id = ?
+            OR (
+              bot_name = ?
+              AND
+              telegram_chat_id = ?
+              AND telegram_message_id = ?
+            )
+         ORDER BY reservation_id
+      `).all(reservationId, botName, telegramChatId, telegramMessageId);
+      if (existingRows.length > 0) {
+        const existing = existingRows[0];
+        if (
+          existingRows.length === 1
+          && existing.reservation_id === reservationId
+          && existing.generation_id === generationId
+          && existing.session_key === sessionKey
+          && existing.bot_name === botName
+          && existing.telegram_chat_id === telegramChatId
+          && existing.telegram_message_id === telegramMessageId
+        ) {
+          const handlerStatus = existing.state === 'settled'
+            ? 'replied'
+            : ['failed', 'interrupted', 'cancelled'].includes(existing.state)
+              ? 'failed'
+              : existing.state === 'ambiguous'
+                ? 'codex-ambiguous'
+                : 'dispatched';
+          const inbound = db.prepare(`
+            UPDATE messages
+               SET handler_status = ?
+             WHERE direction = 'in'
+               AND bot_name = ?
+               AND chat_id = ?
+               AND CAST(msg_id AS TEXT) = ?
+          `).run(
+            handlerStatus,
+            existing.bot_name,
+            existing.telegram_chat_id,
+            existing.telegram_message_id,
+          );
+          if (inbound.changes !== 1) {
+            throw codexError(
+              'Codex duplicate reservation has no exact inbound message',
+              'CODEX_DISPATCH_INBOUND_MISMATCH',
+            );
+          }
+          return { claimed: false, reservation: existing };
+        }
+        throw codexError(
+          'Codex dispatch reservation identity was reused',
+          'CODEX_DISPATCH_RESERVATION_CONFLICT',
+        );
+      }
+
+      assertCodexCheckpointOwner(generation, 'request-write-attempted');
+      const inbound = db.prepare(`
+        SELECT direction, bot_name
+          FROM messages
+         WHERE chat_id = ?
+           AND CAST(msg_id AS TEXT) = ?
+      `).get(telegramChatId, telegramMessageId);
+      if (
+        inbound?.direction !== 'in'
+        || inbound.bot_name !== botName
+      ) {
+        throw codexError(
+          'Codex dispatch reservation has no exact inbound message',
+          'CODEX_DISPATCH_INBOUND_MISMATCH',
+        );
+      }
+      db.prepare(`
+        INSERT INTO codex_dispatch_reservations (
+          reservation_id, generation_id, session_key,
+          bot_name, telegram_chat_id, telegram_message_id, state,
+          created_ts, updated_ts
+        ) VALUES (?, ?, ?, ?, ?, ?, 'reserved', ?, ?)
+      `).run(
+        reservationId,
+        generationId,
+        sessionKey,
+        botName,
+        telegramChatId,
+        telegramMessageId,
+        ts,
+        ts,
+      );
+      return {
+        claimed: true,
+        reservation: readCodexDispatchReservation(reservationId),
+      };
+    })();
+  }
+
+  function hasCodexTurnCheckpoint(generationId, attemptId, kind, turnId) {
+    return db.prepare(`
+      SELECT 1
+        FROM codex_attempt_checkpoints
+       WHERE generation_id = ?
+         AND attempt_id = ?
+         AND kind = ?
+         AND turn_id = ?
+       LIMIT 1
+    `).get(generationId, attemptId, kind, turnId) != null;
+  }
+
+  function finalizeCodexAcceptedSteer(input) {
+    const allowed = new Set([
+      'reservation_id',
+      'generation_id',
+      'steer_attempt_id',
+      'target_attempt_id',
+      'stable_host_id',
+      'boot_session_id',
+      'ts',
+    ]);
+    assertExactKeys(
+      input,
+      allowed,
+      'CODEX_DISPATCH_RESERVATION_PAYLOAD_REJECTED',
+      'accepted steer',
+    );
+    const reservationId = requiredCodexString(
+      input?.reservation_id,
+      'dispatch reservation ID',
+    );
+    const generationId = requiredCodexString(
+      input?.generation_id,
+      'generation ID',
+    );
+    const steerAttemptId = requiredCodexString(
+      input?.steer_attempt_id,
+      'steer attempt ID',
+    );
+    const targetAttemptId = requiredCodexString(
+      input?.target_attempt_id,
+      'target attempt ID',
+    );
+    const stableHostId = requiredCodexString(
+      input?.stable_host_id,
+      'stable host identity',
+    );
+    const bootSessionId = requiredCodexString(
+      input?.boot_session_id,
+      'boot-session identity',
+    );
+    const ts = requiredTimestamp(
+      input?.ts ?? Date.now(),
+      'accepted steer timestamp',
+    );
+
+    return db.transaction(() => {
+      const generation = assertCodexGenerationIdentity(
+        generationId,
+        stableHostId,
+        bootSessionId,
+      );
+      let reservation = assertCodexDispatchReservationIdentity(
+        readCodexDispatchReservation(reservationId),
+        generationId,
+      );
+      if ([
+        'steer-accepted',
+        'settled',
+        'failed',
+        'interrupted',
+      ].includes(reservation.state)) {
+        const linked = db.prepare(`
+          SELECT generation_id, attempt_id, target_attempt_id, state,
+                 telegram_chat_id, telegram_message_id
+            FROM codex_linked_inputs
+           WHERE linked_input_id = ?
+        `).get(reservationId);
+        if (
+          reservation.steer_attempt_id === steerAttemptId
+          && reservation.target_attempt_id === targetAttemptId
+          && linked?.generation_id === generationId
+          && linked.attempt_id === steerAttemptId
+          && linked.target_attempt_id === targetAttemptId
+          && reservation.bot_name != null
+          && linked.telegram_chat_id === reservation.telegram_chat_id
+          && linked.telegram_message_id === reservation.telegram_message_id
+          && (
+            (
+              reservation.state === 'steer-accepted'
+              && linked.state === 'linked'
+            )
+            || linked.state === reservation.state
+          )
+        ) {
+          return { changes: 0, reservation };
+        }
+        throw codexError(
+          'Codex accepted steer reservation metadata conflicts',
+          'CODEX_DISPATCH_RESERVATION_CONFLICT',
+        );
+      }
+      if (reservation.state !== 'reserved') {
+        throw codexError(
+          'Codex dispatch reservation cannot accept a steer in this state',
+          'CODEX_DISPATCH_TRANSITION_INVALID',
+        );
+      }
+      assertCodexCheckpointOwner(generation, 'turn-steer-accepted');
+
+      const steer = requireCodexAttempt(steerAttemptId, generationId);
+      const target = requireCodexAttempt(targetAttemptId, generationId);
+      const exactTurn = (
+        steer.turn_id != null
+        && target.turn_id === steer.turn_id
+        && steer.thread_id != null
+        && target.thread_id === steer.thread_id
+      );
+      const steerDurable = (
+        steer.method === 'turn/steer'
+        && steer.delivery_state === 'response-observed'
+        && steer.response_outcome === 'result'
+        && steer.recovery_state === 'active'
+        && hasCodexTurnCheckpoint(
+          generationId,
+          steerAttemptId,
+          'turn-steer-accepted',
+          steer.turn_id,
+        )
+      );
+      const targetDurable = (
+        target.method === 'turn/start'
+        && target.delivery_state === 'response-observed'
+        && target.response_outcome === 'result'
+        && [
+          'active',
+          'terminal-pending',
+          'clean-pending',
+          'empty-registry-pending',
+          'settled',
+        ].includes(target.recovery_state)
+        && hasCodexTurnCheckpoint(
+          generationId,
+          targetAttemptId,
+          'turn-accepted',
+          target.turn_id,
+        )
+      );
+      if (!exactTurn || !steerDurable || !targetDurable) {
+        throw codexError(
+          'Codex accepted steer is not durably bound to its target turn',
+          'CODEX_DISPATCH_STEER_NOT_DURABLE',
+        );
+      }
+
+      const targetAlreadyDelivered = (
+        target.recovery_state === 'settled'
+        && ['completed', 'interrupted', 'failed'].includes(
+          target.terminal_status,
+        )
+        && hasCodexTurnCheckpoint(
+          generationId,
+          targetAttemptId,
+          'telegram-delivery-settled',
+          target.turn_id,
+        )
+      );
+      if (target.recovery_state === 'settled' && !targetAlreadyDelivered) {
+        throw codexError(
+          'Codex settled target lacks exact Telegram delivery proof',
+          'CODEX_DISPATCH_STEER_NOT_DURABLE',
+        );
+      }
+      const linkedState = targetAlreadyDelivered
+        ? target.terminal_status === 'completed'
+          ? 'settled'
+          : target.terminal_status
+        : 'linked';
+      const linkedSettledTs = targetAlreadyDelivered
+        ? target.settled_ts ?? ts
+        : null;
+      db.prepare(`
+        INSERT INTO codex_linked_inputs (
+          linked_input_id, generation_id, attempt_id, target_attempt_id,
+          telegram_chat_id, telegram_message_id, state, created_ts, settled_ts
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        reservationId,
+        generationId,
+        steerAttemptId,
+        targetAttemptId,
+        reservation.telegram_chat_id,
+        reservation.telegram_message_id,
+        linkedState,
+        ts,
+        linkedSettledTs,
+      );
+      if (targetAlreadyDelivered) {
+        const handlerStatus = linkedState === 'settled' ? 'replied' : 'failed';
+        const inbound = db.prepare(`
+          UPDATE messages
+             SET handler_status = ?
+           WHERE direction = 'in'
+             AND bot_name = ?
+             AND chat_id = ?
+             AND CAST(msg_id AS TEXT) = ?
+             AND handler_status IN (
+               'received', 'dispatched', 'processing', 'replay-pending'
+             )
+        `).run(
+          handlerStatus,
+          reservation.bot_name,
+          reservation.telegram_chat_id,
+          reservation.telegram_message_id,
+        );
+        if (inbound.changes !== 1) {
+          throw codexError(
+            'Codex late accepted steer has no live exact inbound message',
+            'CODEX_LINKED_INPUT_MESSAGE_NOT_FOUND',
+          );
+        }
+        db.prepare(`
+          UPDATE codex_turn_attempts
+             SET recovery_state = 'settled',
+                 settled_ts = ?,
+                 updated_ts = ?
+           WHERE attempt_id = ?
+             AND recovery_state = 'active'
+        `).run(linkedSettledTs, ts, steerAttemptId);
+      }
+      db.prepare(`
+        UPDATE codex_dispatch_reservations
+           SET state = ?,
+               steer_attempt_id = ?,
+               target_attempt_id = ?,
+               updated_ts = ?,
+               settled_ts = ?
+         WHERE reservation_id = ?
+           AND state = 'reserved'
+      `).run(
+        targetAlreadyDelivered ? linkedState : 'steer-accepted',
+        steerAttemptId,
+        targetAttemptId,
+        ts,
+        linkedSettledTs,
+        reservationId,
+      );
+      reservation = readCodexDispatchReservation(reservationId);
+      return { changes: 1, reservation };
+    })();
+  }
+
+  function markCodexDispatchDisposition(input) {
+    const allowed = new Set([
+      'reservation_id',
+      'generation_id',
+      'disposition',
+      'stable_host_id',
+      'boot_session_id',
+      'ts',
+    ]);
+    assertExactKeys(
+      input,
+      allowed,
+      'CODEX_DISPATCH_RESERVATION_PAYLOAD_REJECTED',
+      'dispatch disposition',
+    );
+    const reservationId = requiredCodexString(
+      input?.reservation_id,
+      'dispatch reservation ID',
+    );
+    const generationId = requiredCodexString(
+      input?.generation_id,
+      'generation ID',
+    );
+    const disposition = input?.disposition;
+    if (!['queue-authorized', 'ambiguous', 'cancelled'].includes(disposition)) {
+      throw codexError(
+        'Codex dispatch disposition is invalid',
+        'CODEX_DISPATCH_DISPOSITION_INVALID',
+      );
+    }
+    const stableHostId = requiredCodexString(
+      input?.stable_host_id,
+      'stable host identity',
+    );
+    const bootSessionId = requiredCodexString(
+      input?.boot_session_id,
+      'boot-session identity',
+    );
+    const ts = requiredTimestamp(
+      input?.ts ?? Date.now(),
+      'dispatch disposition timestamp',
+    );
+
+    return db.transaction(() => {
+      const generation = assertCodexGenerationIdentity(
+        generationId,
+        stableHostId,
+        bootSessionId,
+      );
+      let reservation = assertCodexDispatchReservationIdentity(
+        readCodexDispatchReservation(reservationId),
+        generationId,
+      );
+      if (reservation.state === disposition) {
+        return { changes: 0, reservation };
+      }
+      const legal = (
+        reservation.state === 'reserved'
+        || (
+          reservation.state === 'queue-authorized'
+          && ['ambiguous', 'cancelled'].includes(disposition)
+        )
+      );
+      if (!legal) {
+        throw codexError(
+          'Codex dispatch disposition transition is invalid',
+          'CODEX_DISPATCH_TRANSITION_INVALID',
+        );
+      }
+      assertCodexCheckpointOwner(generation, 'request-write-attempted');
+      db.prepare(`
+        UPDATE codex_dispatch_reservations
+           SET state = ?,
+               updated_ts = ?,
+               settled_ts = CASE WHEN ? = 'cancelled' THEN ? ELSE NULL END
+         WHERE reservation_id = ?
+      `).run(disposition, ts, disposition, ts, reservationId);
+      reservation = readCodexDispatchReservation(reservationId);
+      if (['ambiguous', 'cancelled'].includes(disposition)) {
+        const handlerStatus = disposition === 'ambiguous'
+          ? 'codex-ambiguous'
+          : 'failed';
+        const inbound = db.prepare(`
+          UPDATE messages
+             SET handler_status = ?
+           WHERE direction = 'in'
+             AND bot_name = ?
+             AND chat_id = ?
+             AND CAST(msg_id AS TEXT) = ?
+             AND handler_status IN (
+               'received', 'dispatched', 'processing', 'replay-pending'
+             )
+        `).run(
+          handlerStatus,
+          reservation.bot_name,
+          reservation.telegram_chat_id,
+          reservation.telegram_message_id,
+        );
+        if (inbound.changes !== 1) {
+          throw codexError(
+            'Codex dispatch disposition has no live exact inbound message',
+            'CODEX_DISPATCH_INBOUND_MISMATCH',
+          );
+        }
+      }
+      return { changes: 1, reservation };
+    })();
+  }
+
+  function settleCodexQueuedDispatch(input) {
+    const allowed = new Set([
+      'attempt_id',
+      'generation_id',
+      'session_key',
+      'bot_name',
+      'telegram_chat_id',
+      'telegram_message_id',
+      'stable_host_id',
+      'boot_session_id',
+      'ts',
+    ]);
+    assertExactKeys(
+      input,
+      allowed,
+      'CODEX_QUEUE_SETTLEMENT_PAYLOAD_REJECTED',
+      'queued dispatch settlement',
+    );
+    const attemptId = requiredCodexString(
+      input?.attempt_id,
+      'queued turn attempt ID',
+    );
+    const generationId = requiredCodexString(
+      input?.generation_id,
+      'generation ID',
+    );
+    const sessionKey = requiredCodexString(input?.session_key, 'session key');
+    const botName = requiredCodexString(input?.bot_name, 'bot name');
+    const telegramChatId = requiredCodexString(
+      input?.telegram_chat_id,
+      'Telegram chat ID',
+    );
+    const telegramMessageId = requiredCodexString(
+      input?.telegram_message_id,
+      'Telegram message ID',
+    );
+    const stableHostId = requiredCodexString(
+      input?.stable_host_id,
+      'stable host identity',
+    );
+    const bootSessionId = requiredCodexString(
+      input?.boot_session_id,
+      'boot-session identity',
+    );
+    const ts = requiredTimestamp(
+      input?.ts ?? Date.now(),
+      'queued dispatch settlement timestamp',
+    );
+
+    return db.transaction(() => {
+      const generation = assertCodexGenerationIdentity(
+        generationId,
+        stableHostId,
+        bootSessionId,
+      );
+      if (generation.session_key !== sessionKey) {
+        throw codexError(
+          'Codex queued turn session does not own its generation',
+          'CODEX_QUEUE_SETTLEMENT_CONFLICT',
+        );
+      }
+      const attempt = requireCodexAttempt(attemptId, generationId);
+      const durableCompleted = (
+        attempt.session_key === sessionKey
+        && attempt.method === 'turn/start'
+        && attempt.telegram_source_message_id === telegramMessageId
+        && attempt.delivery_state === 'response-observed'
+        && attempt.response_outcome === 'result'
+        && attempt.recovery_state === 'settled'
+        && attempt.terminal_status === 'completed'
+        && attempt.turn_id != null
+        && hasCodexTurnCheckpoint(
+          generationId,
+          attemptId,
+          'turn-accepted',
+          attempt.turn_id,
+        )
+        && hasCodexTurnCheckpoint(
+          generationId,
+          attemptId,
+          'turn-terminal',
+          attempt.turn_id,
+        )
+        && hasCodexTurnCheckpoint(
+          generationId,
+          attemptId,
+          'telegram-delivery-settled',
+          attempt.turn_id,
+        )
+      );
+      if (!durableCompleted) {
+        throw codexError(
+          'Codex queued turn lacks exact completed delivery proof',
+          'CODEX_QUEUE_SETTLEMENT_NOT_DURABLE',
+        );
+      }
+
+      const candidates = db.prepare(`
+        SELECT *
+          FROM codex_dispatch_reservations
+         WHERE (
+           bot_name = ?
+           AND telegram_chat_id = ?
+           AND telegram_message_id = ?
+         )
+            OR (
+              generation_id = ?
+              AND session_key = ?
+              AND telegram_message_id = ?
+            )
+         ORDER BY reservation_id
+      `).all(
+        botName,
+        telegramChatId,
+        telegramMessageId,
+        generationId,
+        sessionKey,
+        telegramMessageId,
+      );
+      if (candidates.length === 0) {
+        return {
+          changes: 0,
+          outcome: 'no-reservation',
+          reservation: null,
+        };
+      }
+      if (candidates.length !== 1) {
+        throw codexError(
+          'Codex queued turn matches conflicting dispatch reservations',
+          'CODEX_QUEUE_SETTLEMENT_CONFLICT',
+        );
+      }
+      let reservation = candidates[0];
+      const exactReservation = (
+        reservation.generation_id === generationId
+        && reservation.session_key === sessionKey
+        && reservation.bot_name === botName
+        && reservation.telegram_chat_id === telegramChatId
+        && reservation.telegram_message_id === telegramMessageId
+      );
+      if (!exactReservation) {
+        throw codexError(
+          'Codex queued turn reservation identity conflicts',
+          'CODEX_QUEUE_SETTLEMENT_CONFLICT',
+        );
+      }
+      if (
+        reservation.state === 'settled'
+        && reservation.target_attempt_id === attemptId
+        && reservation.steer_attempt_id == null
+      ) {
+        return { changes: 0, outcome: 'settled', reservation };
+      }
+      if (
+        reservation.state !== 'queue-authorized'
+        || reservation.steer_attempt_id != null
+        || reservation.target_attempt_id != null
+      ) {
+        throw codexError(
+          'Codex dispatch reservation cannot settle this queued turn',
+          'CODEX_QUEUE_SETTLEMENT_CONFLICT',
+        );
+      }
+      db.prepare(`
+        UPDATE codex_dispatch_reservations
+           SET state = 'settled',
+               target_attempt_id = ?,
+               updated_ts = ?,
+               settled_ts = ?
+         WHERE reservation_id = ?
+           AND state = 'queue-authorized'
+      `).run(
+        attemptId,
+        ts,
+        attempt.settled_ts ?? ts,
+        reservation.reservation_id,
+      );
+      reservation = readCodexDispatchReservation(reservation.reservation_id);
+      return { changes: 1, outcome: 'settled', reservation };
+    })();
+  }
+
+  function settleCodexStoppedGeneration(input) {
+    const allowed = new Set([
+      'generation_id',
+      'stable_host_id',
+      'boot_session_id',
+      'ts',
+    ]);
+    assertExactKeys(
+      input,
+      allowed,
+      'CODEX_RETIREMENT_PAYLOAD_REJECTED',
+      'stopped generation settlement',
+    );
+    const generationId = requiredCodexString(
+      input?.generation_id,
+      'generation ID',
+    );
+    const stableHostId = requiredCodexString(
+      input?.stable_host_id,
+      'stable host identity',
+    );
+    const bootSessionId = requiredCodexString(
+      input?.boot_session_id,
+      'boot-session identity',
+    );
+    const ts = requiredTimestamp(
+      input?.ts ?? Date.now(),
+      'stopped generation settlement timestamp',
+    );
+
+    return db.transaction(() => {
+      const generation = assertCodexGenerationIdentity(
+        generationId,
+        stableHostId,
+        bootSessionId,
+      );
+      const lease = db.prepare(`
+        SELECT generation_id, stable_host_id, boot_session_id, status
+          FROM codex_daemon_lease
+         WHERE singleton = 1
+      `).get();
+      if (
+        !['active', 'healthy-stopped'].includes(generation.state)
+        || lease?.status !== 'active'
+        || lease.generation_id !== generationId
+        || lease.stable_host_id !== stableHostId
+        || lease.boot_session_id !== bootSessionId
+      ) {
+        throw codexError(
+          'Codex stopped generation does not own the active daemon lease',
+          'CODEX_CHECKPOINT_STALE_GENERATION',
+        );
+      }
+      const stop = db.prepare(`
+        SELECT turn_id
+          FROM codex_attempt_checkpoints
+         WHERE generation_id = ?
+           AND kind = 'stop-empty-registry-observed'
+         ORDER BY id DESC
+         LIMIT 1
+      `).get(generationId);
+      if (!stop) {
+        throw codexError(
+          'Codex stopped generation lacks exact empty-registry proof',
+          'CODEX_RETIREMENT_UNVERIFIED',
+        );
+      }
+      const unresolved = db.prepare(`
+        SELECT *
+          FROM codex_turn_attempts
+         WHERE generation_id = ?
+           AND delivery_state != 'prepared'
+           AND recovery_state NOT IN ('settled', 'cancelled')
+         ORDER BY created_ts, attempt_id
+      `).all(generationId);
+      if (unresolved.length === 0) {
+        retireCodexGeneration(generationId, ts);
+        return {
+          changes: 0,
+          disposition: 'already-disposed',
+          attemptId: null,
+          retired: true,
+        };
+      }
+      const interrupted = unresolved.filter((attempt) => (
+        attempt.method === 'turn/start'
+        && attempt.turn_id === stop.turn_id
+        && attempt.terminal_status === 'interrupted'
+        && hasCodexTurnCheckpoint(
+          generationId,
+          attempt.attempt_id,
+          'turn-terminal',
+          attempt.turn_id,
+        )
+      ));
+      if (interrupted.length === 0) {
+        return {
+          changes: 0,
+          disposition: 'pending-delivery',
+          attemptId: null,
+        };
+      }
+      if (interrupted.length !== 1) {
+        throw codexError(
+          'Codex stopped generation has conflicting interrupted targets',
+          'CODEX_RETIREMENT_UNVERIFIED',
+        );
+      }
+      const attempt = interrupted[0];
+      settleCodexAttemptConsumerOutcome({
+        attempt,
+        generationId,
+        linkedState: 'interrupted',
+        attemptRecoveryState: 'cancelled',
+        settleQueuedReservation: true,
+        ts,
+      });
+      retireCodexGeneration(generationId, ts);
+      return {
+        changes: 1,
+        disposition: 'stop-cancelled',
+        attemptId: attempt.attempt_id,
+        retired: true,
+      };
+    })();
+  }
+
+  function linkCodexSteeringInput(input) {
+    const allowed = new Set([
+      'linked_input_id',
+      'generation_id',
+      'attempt_id',
+      'target_attempt_id',
+      'telegram_chat_id',
+      'telegram_message_id',
+      'ts',
+    ]);
+    assertExactKeys(
+      input,
+      allowed,
+      'CODEX_LINKED_INPUT_PAYLOAD_REJECTED',
+      'linked input',
+    );
+    const ts = requiredTimestamp(input?.ts ?? Date.now(), 'linked input timestamp');
+    const linkedInputId = requiredCodexString(
+      input?.linked_input_id,
+      'linked input ID',
+    );
+    const generationId = requiredCodexString(
+      input?.generation_id,
+      'generation ID',
+    );
+    const attemptId = requiredCodexString(
+      input?.attempt_id,
+      'steer attempt ID',
+    );
+    const targetAttemptId = requiredCodexString(
+      input?.target_attempt_id,
+      'target attempt ID',
+    );
+    const telegramChatId = requiredCodexString(
+      input?.telegram_chat_id,
+      'Telegram chat ID',
+    );
+    const telegramMessageId = requiredCodexString(
+      input?.telegram_message_id,
+      'Telegram message ID',
+    );
+    return db.transaction(() => {
+      const attempt = requireCodexAttempt(
+        attemptId,
+        generationId,
+      );
+      const target = requireCodexAttempt(
+        targetAttemptId,
+        generationId,
+      );
+      if (attempt.method !== 'turn/steer' || target.method !== 'turn/start') {
+        throw codexError(
+          'Codex linked input must connect steer work to a turn',
+          'CODEX_LINKED_INPUT_INVALID',
+        );
+      }
+      const existing = db.prepare(`
+        SELECT generation_id, attempt_id, target_attempt_id,
+               telegram_chat_id, telegram_message_id
+          FROM codex_linked_inputs
+         WHERE linked_input_id = ?
+      `).get(linkedInputId);
+      if (existing) {
+        if (
+          existing.generation_id === generationId
+          && existing.attempt_id === attemptId
+          && existing.target_attempt_id === targetAttemptId
+          && existing.telegram_chat_id === telegramChatId
+          && existing.telegram_message_id === telegramMessageId
+        ) {
+          return { changes: 0 };
+        }
+        throw codexError(
+          'Codex linked input ID was reused with different metadata',
+          'CODEX_LINKED_INPUT_ID_REUSED',
+        );
+      }
+      return db.prepare(`
+        INSERT INTO codex_linked_inputs (
+          linked_input_id, generation_id, attempt_id, target_attempt_id,
+          telegram_chat_id, telegram_message_id, state, created_ts
+        ) VALUES (?, ?, ?, ?, ?, ?, 'linked', ?)
+      `).run(
+        linkedInputId,
+        generationId,
+        attemptId,
+        targetAttemptId,
+        telegramChatId,
+        telegramMessageId,
+        ts,
+      );
+    })();
+  }
+
+  function claimCodexRetryReservation(input) {
+    const originalAttemptId = requiredCodexString(
+      input?.original_attempt_id,
+      'original attempt ID',
+    );
+    const retryAttemptId = requiredCodexString(
+      input?.retry_attempt_id,
+      'retry attempt ID',
+    );
+    const generationId = requiredCodexString(
+      input?.generation_id,
+      'generation ID',
+    );
+    const stableHostId = requiredCodexString(
+      input?.stable_host_id,
+      'stable host identity',
+    );
+    const bootSessionId = requiredCodexString(
+      input?.boot_session_id,
+      'boot-session identity',
+    );
+    const method = requiredCodexString(input?.method, 'retry method');
+    const threadId = optionalCodexString(input?.thread_id, 'thread ID');
+    const sourceMessageId = optionalCodexString(
+      input?.telegram_source_message_id,
+      'source message ID',
+    );
+    const clientUserMessageId = optionalCodexString(
+      input?.client_user_message_id,
+      'client user message ID',
+    );
+    const ts = requiredTimestamp(input?.ts ?? Date.now(), 'retry claim timestamp');
+    return db.transaction(() => {
+      const generation = assertCodexGenerationIdentity(
+        generationId,
+        stableHostId,
+        bootSessionId,
+      );
+      assertCodexCheckpointOwner(generation, 'request-write-attempted');
+      const reservation = db.prepare(`
+        SELECT reservation.*,
+               original.generation_id AS original_generation_id,
+               original.session_key AS original_session_key,
+               original_generation.stable_host_id AS original_stable_host_id,
+               original_generation.boot_session_id AS original_boot_session_id,
+               original_generation.state AS original_generation_state
+          FROM codex_retry_reservations reservation
+          JOIN codex_turn_attempts original
+            ON original.attempt_id = reservation.original_attempt_id
+          JOIN codex_generations original_generation
+            ON original_generation.generation_id = original.generation_id
+         WHERE reservation.original_attempt_id = ?
+      `).get(originalAttemptId);
+      if (
+        !reservation
+        || reservation.retry_attempt_id !== retryAttemptId
+      ) {
+        throw codexError(
+          'Codex retry reservation does not match the claimed attempt',
+          'CODEX_RETRY_RESERVATION_MISMATCH',
+        );
+      }
+      if (reservation.original_generation_id === generationId) {
+        throw codexError(
+          'Codex retry requires a new generation after reboot release',
+          'CODEX_RETRY_NEW_GENERATION_REQUIRED',
+        );
+      }
+      if (
+        reservation.original_session_key !== generation.session_key
+        || reservation.original_stable_host_id !== generation.stable_host_id
+      ) {
+        throw codexError(
+          'Codex retry generation does not match the original session',
+          'CODEX_RETRY_RESERVATION_MISMATCH',
+        );
+      }
+      const released = db.prepare(`
+        SELECT 1
+          FROM codex_reboot_releases
+         WHERE stable_host_id = ?
+           AND incident_boot_session_id = ?
+           AND released_boot_session_id = ?
+      `).get(
+        reservation.original_stable_host_id,
+        reservation.original_boot_session_id,
+        generation.boot_session_id,
+      );
+      if (!released) {
+        throw codexError(
+          'Codex retry requires a durable reboot release',
+          'CODEX_RETRY_REBOOT_RELEASE_REQUIRED',
+        );
+      }
+      const existing = db.prepare(`
+        SELECT * FROM codex_turn_attempts WHERE attempt_id = ?
+      `).get(retryAttemptId);
+      if (
+        ['claimed', 'dispatched', 'retired'].includes(reservation.state)
+        && existing
+      ) {
+        assertCodexAttemptIdentity(existing, {
+          generation_id: generationId,
+          session_key: generation.session_key,
+          method,
+          thread_id: threadId,
+          telegram_source_message_id: sourceMessageId,
+          client_user_message_id: clientUserMessageId,
+        });
+        return { changes: 0, retryAttemptId };
+      }
+      if (reservation.state !== 'reserved' || existing) {
+        throw codexError(
+          'Codex retry reservation has already been consumed',
+          'CODEX_RETRY_ALREADY_CLAIMED',
+        );
+      }
+      db.prepare(`
+        INSERT INTO codex_turn_attempts (
+          attempt_id, generation_id, session_key, method,
+          thread_id, telegram_source_message_id, client_user_message_id,
+          delivery_state, recovery_state, created_ts, updated_ts
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, 'prepared', 'prepared', ?, ?)
+      `).run(
+        retryAttemptId,
+        generationId,
+        generation.session_key,
+        method,
+        threadId,
+        sourceMessageId,
+        clientUserMessageId,
+        ts,
+        ts,
+      );
+      db.prepare(`
+        INSERT INTO codex_attempt_checkpoints (
+          generation_id, attempt_id, kind, thread_id,
+          detail_json, ts
+        ) VALUES (?, ?, 'request-prepared', ?, ?, ?)
+      `).run(
+        generationId,
+        retryAttemptId,
+        threadId,
+        checkpointDetail({
+          method,
+          source: sourceMessageId,
+          clientUserMessageId,
+        }),
+        ts,
+      );
+      db.prepare(`
+        UPDATE codex_retry_reservations
+           SET state = 'claimed', claimed_ts = ?
+         WHERE original_attempt_id = ?
+      `).run(ts, originalAttemptId);
+      return { changes: 1, retryAttemptId };
+    })();
+  }
+
+  function markCodexRetryDispatched(input) {
+    const originalAttemptId = requiredCodexString(
+      input?.original_attempt_id,
+      'original attempt ID',
+    );
+    const retryAttemptId = requiredCodexString(
+      input?.retry_attempt_id,
+      'retry attempt ID',
+    );
+    const ts = requiredTimestamp(
+      input?.ts ?? Date.now(),
+      'retry dispatch timestamp',
+    );
+    return db.transaction(() => {
+      const reservation = db.prepare(`
+        SELECT * FROM codex_retry_reservations
+         WHERE original_attempt_id = ?
+      `).get(originalAttemptId);
+      const retry = db.prepare(`
+        SELECT * FROM codex_turn_attempts WHERE attempt_id = ?
+      `).get(retryAttemptId);
+      if (
+        !reservation
+        || reservation.retry_attempt_id !== retryAttemptId
+        || !retry
+      ) {
+        throw codexError(
+          'Codex retry dispatch has no materialized reservation',
+          'CODEX_RETRY_RESERVATION_MISMATCH',
+        );
+      }
+      if (reservation.state === 'dispatched') {
+        return { changes: 0, retryAttemptId };
+      }
+      if (
+        reservation.state !== 'claimed'
+        || retry.delivery_state === 'prepared'
+      ) {
+        throw codexError(
+          'Codex retry was not durably write-attempted',
+          'CODEX_RETRY_NOT_WRITE_ATTEMPTED',
+        );
+      }
+      const result = db.prepare(`
+        UPDATE codex_retry_reservations
+           SET state = 'dispatched', dispatched_ts = ?
+         WHERE original_attempt_id = ?
+      `).run(ts, originalAttemptId);
+      return { changes: result.changes, retryAttemptId };
+    })();
+  }
+
+  function retireCodexRetryReservation(input) {
+    const originalAttemptId = requiredCodexString(
+      input?.original_attempt_id,
+      'original attempt ID',
+    );
+    const retryAttemptId = requiredCodexString(
+      input?.retry_attempt_id,
+      'retry attempt ID',
+    );
+    const ts = requiredTimestamp(
+      input?.ts ?? Date.now(),
+      'retry retirement timestamp',
+    );
+    return db.transaction(() => {
+      const reservation = db.prepare(`
+        SELECT * FROM codex_retry_reservations
+         WHERE original_attempt_id = ?
+      `).get(originalAttemptId);
+      const retry = db.prepare(`
+        SELECT recovery_state
+          FROM codex_turn_attempts
+         WHERE attempt_id = ?
+      `).get(retryAttemptId);
+      if (
+        !reservation
+        || reservation.retry_attempt_id !== retryAttemptId
+        || !retry
+      ) {
+        throw codexError(
+          'Codex retry retirement has no materialized reservation',
+          'CODEX_RETRY_RESERVATION_MISMATCH',
+        );
+      }
+      if (reservation.state === 'retired') {
+        return { changes: 0, retryAttemptId };
+      }
+      if (!['settled', 'cancelled'].includes(retry.recovery_state)) {
+        throw codexError(
+          'Codex retry attempt is not durably settled',
+          'CODEX_RETRY_NOT_SETTLED',
+        );
+      }
+      const result = db.prepare(`
+        UPDATE codex_retry_reservations
+           SET state = 'retired', retired_ts = ?
+         WHERE original_attempt_id = ?
+      `).run(ts, originalAttemptId);
+      return { changes: result.changes, retryAttemptId };
+    })();
+  }
+
+  function recordCodexItemEffect(input) {
+    const allowed = new Set([
+      'generation_id',
+      'attempt_id',
+      'item_id',
+      'item_type',
+      'state',
+      'ts',
+    ]);
+    assertExactKeys(
+      input,
+      allowed,
+      'CODEX_EFFECT_PAYLOAD_REJECTED',
+      'item effect',
+    );
+    const generationId = requiredCodexString(
+      input?.generation_id,
+      'generation ID',
+    );
+    const attemptId = requiredCodexString(input?.attempt_id, 'attempt ID');
+    const itemId = requiredCodexString(input?.item_id, 'item ID');
+    const itemType = requiredCodexString(input?.item_type, 'item type');
+    const state = input?.state;
+    if (!['started', 'completed', 'failed'].includes(state)) {
+      throw codexError(
+        'Codex item effect state is invalid',
+        'CODEX_EFFECT_PAYLOAD_REJECTED',
+      );
+    }
+    const ts = requiredTimestamp(input?.ts ?? Date.now(), 'item effect timestamp');
+    return db.transaction(() => {
+      const attempt = requireCodexAttempt(attemptId, generationId);
+      const generation = db.prepare(`
+        SELECT * FROM codex_generations WHERE generation_id = ?
+      `).get(generationId);
+      assertCodexCheckpointOwner(generation, 'item-started');
+      const existing = db.prepare(`
+        SELECT generation_id, item_type, state
+          FROM codex_item_effects
+         WHERE attempt_id = ? AND item_id = ?
+      `).get(attemptId, itemId);
+      if (existing) {
+        if (
+          existing.generation_id !== generationId
+          || existing.item_type !== itemType
+        ) {
+          throw codexError(
+            'Codex item effect identity is immutable',
+            'CODEX_EFFECT_IDENTITY_MISMATCH',
+          );
+        }
+        if (existing.state === state) return { changes: 0 };
+      }
+      const earlyNotification = (
+        attempt.recovery_state === 'ambiguous'
+        && ['write-attempted', 'response-observed'].includes(
+          attempt.delivery_state,
+        )
+      );
+      if (
+        attempt.turn_id == null
+        || attempt.terminal_status != null
+        || !(attempt.recovery_state === 'active' || earlyNotification)
+      ) {
+        throw codexError(
+          'Codex item effect requires a live dispatched turn',
+          'CODEX_EFFECT_SEQUENCE_INVALID',
+        );
+      }
+      if (existing) {
+        if (existing.state !== 'started') {
+          throw codexError(
+            'Codex terminal item effect cannot regress or change',
+            'CODEX_EFFECT_STATE_CONFLICT',
+          );
+        }
+        return db.prepare(`
+          UPDATE codex_item_effects
+             SET state = ?, updated_ts = ?
+           WHERE attempt_id = ? AND item_id = ?
+        `).run(state, ts, attemptId, itemId);
+      }
+      return db.prepare(`
+        INSERT INTO codex_item_effects (
+          generation_id, attempt_id, item_id, item_type,
+          state, created_ts, updated_ts
+        ) VALUES (?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        generationId,
+        attemptId,
+        itemId,
+        itemType,
+        state,
+        ts,
+        ts,
+      );
+    })();
+  }
+
+  function acquireCodexLease(input) {
+    const generationId = requiredCodexString(
+      input?.generation_id,
+      'generation ID',
+    );
+    const stableHostId = requiredCodexString(
+      input?.stable_host_id,
+      'stable host identity',
+    );
+    const bootSessionId = requiredCodexString(
+      input?.boot_session_id,
+      'boot-session identity',
+    );
+    const ts = requiredTimestamp(input?.ts ?? Date.now(), 'lease timestamp');
+    return db.transaction(() => {
+      assertCodexGenerationIdentity(generationId, stableHostId, bootSessionId);
+      const lease = db.prepare(`
+        SELECT * FROM codex_daemon_lease WHERE singleton = 1
+      `).get();
+      if (
+        lease?.status === 'quarantined'
+        || (
+          lease?.status === 'active'
+          && lease.generation_id !== generationId
+        )
+      ) {
+        throw codexError(
+          'Codex daemon generation lease is unavailable',
+          lease.status === 'quarantined'
+            ? 'CODEX_CONTAINMENT_QUARANTINED'
+            : 'CODEX_DAEMON_GENERATION_BUSY',
+        );
+      }
+      db.prepare(`
+        INSERT INTO codex_daemon_lease (
+          singleton, generation_id, stable_host_id, boot_session_id,
+          status, quarantine_reason, acquired_ts, updated_ts, released_ts
+        ) VALUES (1, ?, ?, ?, 'active', NULL, ?, ?, NULL)
+        ON CONFLICT(singleton) DO UPDATE SET
+          generation_id = excluded.generation_id,
+          stable_host_id = excluded.stable_host_id,
+          boot_session_id = excluded.boot_session_id,
+          status = 'active',
+          quarantine_reason = NULL,
+          acquired_ts = excluded.acquired_ts,
+          updated_ts = excluded.updated_ts,
+          released_ts = NULL
+      `).run(generationId, stableHostId, bootSessionId, ts, ts);
+      db.prepare(`
+        UPDATE codex_generations
+           SET state = 'active', updated_ts = ?
+         WHERE generation_id = ?
+      `).run(ts, generationId);
+      return db.prepare(`
+        SELECT * FROM codex_daemon_lease WHERE singleton = 1
+      `).get();
+    })();
+  }
+
+  function markCodexContainment(input) {
+    const generationId = requiredCodexString(
+      input?.generation_id,
+      'generation ID',
+    );
+    const stableHostId = requiredCodexString(
+      input?.stable_host_id,
+      'stable host identity',
+    );
+    const bootSessionId = requiredCodexString(
+      input?.boot_session_id,
+      'boot-session identity',
+    );
+    const reason = requiredCodexString(input?.reason, 'containment reason');
+    const ts = requiredTimestamp(
+      input?.ts ?? Date.now(),
+      'containment timestamp',
+    );
+    return db.transaction(() => {
+      assertCodexGenerationIdentity(generationId, stableHostId, bootSessionId);
+      const lease = db.prepare(`
+        SELECT * FROM codex_daemon_lease WHERE singleton = 1
+      `).get();
+      if (!lease || lease.generation_id !== generationId) {
+        throw codexError(
+          'Codex containment requires the owned daemon lease',
+          'CODEX_LEASE_MISMATCH',
+        );
+      }
+      db.prepare(`
+        UPDATE codex_generations
+           SET state = 'containment-failed',
+               containment_reason = ?,
+               updated_ts = ?
+         WHERE generation_id = ?
+      `).run(reason, ts, generationId);
+      markGenerationAttemptsAmbiguous(generationId, ts);
+      return db.prepare(`
+        UPDATE codex_daemon_lease
+           SET status = 'quarantined',
+               quarantine_reason = ?,
+               updated_ts = ?
+         WHERE singleton = 1
+      `).run(reason, ts);
+    })();
+  }
+
+  function retireCodexGeneration(
+    generationId,
+    ts,
+    { onlyIfHealthyStopped = false } = {},
+  ) {
+    const generation = db.prepare(`
+      SELECT * FROM codex_generations WHERE generation_id = ?
+    `).get(generationId);
+    if (!generation) {
+      throw codexError(
+        'Codex generation does not exist',
+        'CODEX_GENERATION_NOT_FOUND',
+      );
+    }
+    if (generation.state === 'retired') {
+      return { changes: 0, retired: true };
+    }
+    if (onlyIfHealthyStopped && generation.state !== 'healthy-stopped') {
+      return { changes: 0, retired: false };
+    }
+    const unresolved = db.prepare(`
+      SELECT 1
+        FROM codex_turn_attempts
+       WHERE generation_id = ?
+         AND delivery_state != 'prepared'
+         AND recovery_state NOT IN ('settled', 'cancelled')
+       LIMIT 1
+    `).get(generationId);
+    if (unresolved) {
+      throw codexError(
+        'Codex generation still owns unresolved delivery work',
+        'CODEX_RETIREMENT_UNVERIFIED',
+      );
+    }
+    const lease = db.prepare(`
+      SELECT * FROM codex_daemon_lease WHERE singleton = 1
+    `).get();
+    if (
+      lease?.status !== 'active'
+      || lease.generation_id !== generationId
+      || lease.stable_host_id !== generation.stable_host_id
+      || lease.boot_session_id !== generation.boot_session_id
+    ) {
+      throw codexError(
+        'Codex retirement requires the exact active daemon lease',
+        'CODEX_CHECKPOINT_STALE_GENERATION',
+      );
+    }
+    const result = db.prepare(`
+      UPDATE codex_generations
+         SET state = 'retired', settled_ts = ?, updated_ts = ?
+       WHERE generation_id = ?
+         AND state != 'retired'
+    `).run(ts, ts, generationId);
+    const released = db.prepare(`
+      UPDATE codex_daemon_lease
+         SET generation_id = NULL,
+             status = 'clear',
+             quarantine_reason = NULL,
+             updated_ts = ?,
+             released_ts = ?
+       WHERE singleton = 1
+         AND generation_id = ?
+         AND stable_host_id = ?
+         AND boot_session_id = ?
+         AND status = 'active'
+    `).run(
+      ts,
+      ts,
+      generationId,
+      generation.stable_host_id,
+      generation.boot_session_id,
+    );
+    if (result.changes !== 1 || released.changes !== 1) {
+      throw codexError(
+        'Codex retirement lost the exact generation lease',
+        'CODEX_CHECKPOINT_STALE_GENERATION',
+      );
+    }
+    return { changes: 1, retired: true };
+  }
+
+  function markCodexGenerationRetired(input) {
+    const generationId = requiredCodexString(
+      input?.generation_id,
+      'generation ID',
+    );
+    const ts = requiredTimestamp(input?.ts ?? Date.now(), 'retirement timestamp');
+    return db.transaction(() => retireCodexGeneration(generationId, ts))();
+  }
+
   return {
     raw: db,
 
@@ -323,38 +3614,117 @@ function wrap(db) {
     },
 
     upsertSession(row) {
-      return upsertSessionStmt.run({
-        session_key: row.session_key,
-        chat_id: String(row.chat_id),
-        thread_id: row.thread_id ? String(row.thread_id) : null,
-        claude_session_id: row.claude_session_id,
-        agent: row.agent || null,
-        cwd: row.cwd || null,
-        model: row.model || null,
-        effort: row.effort || null,
-        // 0.10.0: pm_backend defaults to 'sdk' if caller doesn't set it.
-        pm_backend: row.pm_backend || 'sdk',
-        ts: row.ts || Date.now(),
-      });
+      return upsertLegacyAndProviderSession(row);
     },
 
     getSession(sessionKey) {
       return getSessionStmt.get(sessionKey);
     },
 
+    upsertProviderSession(row) {
+      return upsertProviderAndLegacySession(row);
+    },
+
+    getProviderSession(sessionKey, namespace) {
+      if (!PROVIDER_NAMESPACES.has(namespace)) {
+        throw new TypeError('provider session namespace is invalid');
+      }
+      return readProviderSession(String(sessionKey), namespace);
+    },
+
+    clearProviderSession(sessionKey, namespace) {
+      if (!PROVIDER_NAMESPACES.has(namespace)) {
+        throw new TypeError('provider session namespace is invalid');
+      }
+      return clearOneProviderSession(String(sessionKey), namespace);
+    },
+
     touchSession(sessionKey, ts = Date.now()) {
-      return touchSessionStmt.run(ts, sessionKey);
+      const row = getSessionStmt.get(sessionKey);
+      const result = touchSessionStmt.run(ts, sessionKey);
+      if (row) {
+        touchProviderSessionStmt.run(
+          ts,
+          sessionKey,
+          claudeNamespaceForStoredBackend(row.pm_backend),
+        );
+      }
+      return result;
     },
 
     clearSessionId(sessionKey) {
-      return clearSessionIdStmt.run(sessionKey);
+      return clearLegacySession(sessionKey);
     },
 
     // 0.10.0: backend reassignment without resetting other session fields.
     // Used when ProcessManager spawns a Process with a different backend
     // than the persisted row says (drift event fires too).
     setSessionBackend(sessionKey, backend) {
-      return setSessionBackendStmt.run(backend, sessionKey);
+      const row = getSessionStmt.get(sessionKey);
+      const result = setSessionBackendStmt.run(backend, sessionKey);
+      if (row) {
+        const beforeNamespace = claudeNamespaceForStoredBackend(row.pm_backend);
+        const afterNamespace = claudeNamespaceForStoredBackend(backend);
+        if (beforeNamespace === afterNamespace) {
+          setProviderBackendStmt.run(backend, sessionKey, beforeNamespace);
+        }
+      }
+      return result;
+    },
+
+    createCodexGeneration,
+    recordCodexCheckpoint,
+    recordCodexDeliveryCheckpoint,
+    getCodexAttempt(attemptId) {
+      return db.prepare(`
+        SELECT * FROM codex_turn_attempts WHERE attempt_id = ?
+      `).get(attemptId);
+    },
+    listCodexAttemptCheckpoints(attemptId) {
+      return db.prepare(`
+        SELECT *
+          FROM codex_attempt_checkpoints
+         WHERE attempt_id = ?
+         ORDER BY id
+      `).all(attemptId);
+    },
+    claimCodexDispatchReservation,
+    recordInboundRuntimeSelection,
+    getReplayProviderRecovery,
+    getCodexDispatchReservation(reservationId) {
+      return readCodexDispatchReservation(requiredCodexString(
+        reservationId,
+        'dispatch reservation ID',
+      ));
+    },
+    finalizeCodexAcceptedSteer,
+    markCodexDispatchDisposition,
+    settleCodexQueuedDispatch,
+    settleCodexStoppedGeneration,
+    linkCodexSteeringInput,
+    claimCodexRetryReservation,
+    markCodexRetryDispatched,
+    retireCodexRetryReservation,
+    recordCodexItemEffect,
+    acquireCodexLease,
+    getCodexLease() {
+      return db.prepare(`
+        SELECT * FROM codex_daemon_lease WHERE singleton = 1
+      `).get();
+    },
+    markCodexContainment,
+    markCodexGenerationRetired,
+    reconstructCodexRecovery(input) {
+      return reconstructCodexRecovery(db, input);
+    },
+    listUnresolvedCodexAttempts(input) {
+      return listUnresolvedCodexAttempts(db, input);
+    },
+    reconcileCodexAttempt(input) {
+      return reconcileCodexAttempt(db, input);
+    },
+    pruneCodexOperationalData(options) {
+      return pruneCodexOperationalData(db, options);
     },
 
     getMessage(chatId, msgId) {
@@ -526,13 +3896,42 @@ function wrap(db) {
       return deleteChatToolDecisionStmt.run(String(bot_name), String(chat_id), id);
     },
 
+    logConfigChanges(rows) {
+      if (!Array.isArray(rows) || rows.length === 0) {
+        throw new TypeError('config change rows are required');
+      }
+      return db.transaction(() => rows.map((row) => logConfigChangeStmt.run({
+        chat_id: String(row.chat_id),
+        thread_id: row.thread_id ? String(row.thread_id) : null,
+        field: row.field,
+        old_value: configChangeValue(row.old_value, {
+          nullable: true,
+          label: 'old_value',
+        }),
+        new_value: configChangeValue(row.new_value, {
+          nullable: false,
+          label: 'new_value',
+        }),
+        user_id: row.user_id || null,
+        user: row.user || null,
+        source: row.source || 'command',
+        ts: row.ts || Date.now(),
+      })))();
+    },
+
     logConfigChange(row) {
       return logConfigChangeStmt.run({
         chat_id: String(row.chat_id),
         thread_id: row.thread_id ? String(row.thread_id) : null,
         field: row.field,
-        old_value: row.old_value ?? null,
-        new_value: row.new_value,
+        old_value: configChangeValue(row.old_value, {
+          nullable: true,
+          label: 'old_value',
+        }),
+        new_value: configChangeValue(row.new_value, {
+          nullable: false,
+          label: 'new_value',
+        }),
         user_id: row.user_id || null,
         user: row.user || null,
         source: row.source || 'command',