borgmcp 1.1.15 → 2.0.2

package/src/codex-app-wake.ts

@@ -0,0 +1,524 @@
+import {
+  getActiveCube,
+  getCodexWakeTarget,
+  setCodexWakeTarget,
+  type ActiveCube,
+} from './cubes.js';
+import { CodexAppServerClient } from './codex-app-server.js';
+import { checkCodexBridgeHealthy } from './codex-remote.js';
+import { hasPendingWakeActivity } from './remote-client.js';
+import {
+  BORG_CODEX_REMOTE_WAKE_ENV,
+  resolveSessionAgentKind,
+} from './agent-runtime.js';
+import {
+  codexAppServerSocketFromEnv,
+  pickFreshThread,
+  wakeTargetChanged,
+  wakeRetryBackoffMs,
+  wakeRetryExpired,
+  WAKE_RETRY_MAX_ATTEMPTS,
+  shouldFireHeartbeat,
+  type CodexThreadInfo,
+} from './codex-wake-resolve.js';
+
+export const CODEX_WAKE_PROMPT =
+  'New Borg cube-log activity arrived.';
+
+export function formatCodexWakePrompt(inboxLine: string): string {
+  return `New Borg cube-log activity arrived:\n${inboxLine}`;
+}
+
+// gh#708: STATIC catch-up/drain prompt (zero interpolation — no token/secret/PII/
+// cube-content; the entry bodies are fetched by codex itself via the
+// grant/visibility-gated borg_read-log, never injected into the wake). Delivered
+// once after a wake is deferred (mid-turn thread) or retried (transient miss), to
+// fire the already-shipped drain so no entry is skipped. gh#857 WI-2 reuses it as
+// the periodic heartbeat prompt.
+export const CODEX_CATCHUP_PROMPT =
+  'Borg cube activity arrived while you were busy. Wake triage: run `borg_read-log unread_only=true` and DRAIN — repeat until the returned page is under the limit and behind_by is 0 — so no entries are skipped. Then handle actionable entries; if none, resume the prior interrupted work.';
+
+export function isCodexRemoteWakeEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env[BORG_CODEX_REMOTE_WAKE_ENV] === '1';
+}
+
+export { resolveSessionAgentKind } from './agent-runtime.js';
+
+export interface CodexWakeTarget {
+  enabled: boolean;
+}
+
+export function resolveCodexWakeTarget(env: NodeJS.ProcessEnv = process.env): CodexWakeTarget {
+  if (!isCodexRemoteWakeEnabled(env)) {
+    return { enabled: false };
+  }
+  return { enabled: true };
+}
+
+/**
+ * gh#633: resolve a codex drone's transport-agnostic "wake-path-armed" signal
+ * from its OWN runtime wake mechanism — the app-server bridge's process
+ * liveness, the codex analogue of the claude tail-F Monitor health. Fed into
+ * the health beat so the HOP-2 wake-path-deaf classifier reads a
+ * transport-agnostic armed signal instead of the claude-shaped monitor_armed
+ * (which is false-by-design for codex and falsely flagged them, gh#633).
+ *
+ * Tri-state (boolean|null; caller maps null→armed for false-deaf-avoidance):
+ *   - false ONLY on a positively-dead bridge: no wake target registered (the
+ *     bridge cannot deliver wakes), OR the app-server pid is dead.
+ *   - true when the wake target resolves AND the app-server pid is alive.
+ *   - null when the bridge health is indeterminate (target read or pid check
+ *     could not resolve) → armed (don't false-flag on uncertainty).
+ */
+export async function probeCodexBridgeArmed(
+  active: { cubeId: string; droneId: string },
+  deps: {
+    getCodexWakeTarget?: typeof getCodexWakeTarget;
+    checkBridge?: typeof checkCodexBridgeHealthy;
+  } = {}
+): Promise<boolean | null> {
+  try {
+    const resolve = deps.getCodexWakeTarget ?? getCodexWakeTarget;
+    const target = await resolve(active.cubeId, active.droneId);
+    // No registered wake target → the bridge cannot deliver a wake → not armed.
+    if (!target) return false;
+    const check = deps.checkBridge ?? checkCodexBridgeHealthy;
+    return check(target.socketPath);
+  } catch {
+    return null;
+  }
+}
+
+let wakeInFlight = false;
+const pendingWakeRequests: Array<{
+  reason: string;
+  deps: CodexWakeDeps;
+}> = [];
+const deliveredWakeKeys = new Set<string>();
+const deliveredWakeKeyOrder: string[] = [];
+const DELIVERED_WAKE_KEY_CAP = 100;
+
+// gh#708/#857: a single in-flight retry-drain loop coalesces ALL wakes deferred
+// (mid-turn thread) or missed (transient error) into ONE retried-until-delivered
+// drain. The coalesce gate means a burst collapses to one poller, not N.
+let retryDrainInFlight = false;
+
+// gh#857 WI-2: timestamp of the last SUCCESSFUL wake delivery (per-entry OR
+// retry-drain OR heartbeat). The heartbeat reads this (shouldFireHeartbeat) to
+// skip when a delivery already landed inside the cadence window. Module-scoped
+// because the wake path and the heartbeat run in the same MCP-client child.
+let lastDeliveredAt: number | null = null;
+
+/** gh#857 WI-2: last successful wake delivery time (for the heartbeat gate). */
+export function getLastDeliveredAt(): number | null {
+  return lastDeliveredAt;
+}
+
+function markDelivered(deps: CodexWakeDeps): void {
+  lastDeliveredAt = (deps.now ?? Date.now)();
+}
+
+// gh#857 WI-2: a single-in-flight guard for the heartbeat tick (mirrors
+// wakeInFlight + retryDrainInFlight). Without it, a tick that stalls in IO past
+// the next interval could let a second tick read the stale (pre-markDelivered)
+// lastDeliveredAt, pass its gate, and double-inject the drain — the exact
+// double-fire the design forbids.
+let heartbeatInFlight = false;
+
+// gh#861 finding 1: a SINGLE module-scoped mutex serializing the resolve+inject
+// critical section ACROSS all three injecting paths (per-entry wake, retry-drain,
+// heartbeat tick). The per-path flags above (wakeInFlight / retryDrainInFlight /
+// heartbeatInFlight) each serialize their OWN path but NOT across paths — so a
+// per-entry WAKE prompt and a heartbeat/retry DRAIN prompt could land in the same
+// codex thread concurrently (double-inject collision). This lock closes that
+// cross-path race: a path that cannot acquire it backs off via its own retry
+// mechanism (heartbeat: skip tick; retry-drain: continue loop; per-entry: schedule
+// a retry-drain so the entry is not lost).
+let injectInFlight = false;
+
+function tryAcquireInjectLock(): boolean {
+  if (injectInFlight) return false;
+  injectInFlight = true;
+  return true;
+}
+
+function releaseInjectLock(): void {
+  injectInFlight = false;
+}
+
+/**
+ * gh#861 finding 3: a positively-dead codex app-server socket. ENOENT means the
+ * socket file is gone (the app-server never created it / unlinked it on exit) —
+ * the wake path cannot deliver, so the heartbeat timer should be torn down. Kept
+ * narrow (ENOENT only): a transient ECONNREFUSED during a momentary blip must NOT
+ * tear the backstop down.
+ */
+function isAppServerDeadError(err: unknown): boolean {
+  return (err as { code?: string } | null)?.code === 'ENOENT';
+}
+
+function defaultSleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export interface CodexWakeDeps {
+  getActiveCube?: typeof getActiveCube;
+  getCodexWakeTarget?: typeof getCodexWakeTarget;
+  // gh#855: self-heal write of the freshly-resolved target (write-only-on-change).
+  setCodexWakeTarget?: typeof setCodexWakeTarget;
+  createClient?: (
+    socketPath: string
+  ) => Pick<CodexAppServerClient, 'connect' | 'readThread' | 'startTurn' | 'loadedThreadIds' | 'close'>;
+  // gh#855: injectable env (live app-server socket) + cwd (thread disambiguation).
+  env?: NodeJS.ProcessEnv;
+  cwd?: () => string;
+  // gh#708/#857: injectable for the retry-drain loop (real timers in prod; fake in tests).
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+  // gh#857: injectable backoff jitter (default Math.random()*500) so co-located
+  // sibling drones don't retry in lockstep; deterministic (0) in tests.
+  jitter?: () => number;
+  // gh#857: injectable hard iteration ceiling for the retry-drain loop (default
+  // WAKE_RETRY_MAX_ATTEMPTS); small values let tests prove the loop terminates
+  // under a non-advancing clock without running thousands of iterations.
+  maxAttempts?: number;
+  // client#76: token-free, non-mutating preflight for the periodic backstop.
+  // Per-entry and retry-drain paths do not use this: their pending obligation is
+  // already established by a concrete delivered/deferred event.
+  hasPendingWork?: (active: ActiveCube) => Promise<boolean>;
+  // gh#861 finding 2: lease-ownership gate for the heartbeat tick — a lease-LOSING
+  // duplicate child must NOT tick/inject (symmetry with the per-entry path, which
+  // only fires inside an SSE session that holds the stream lease). Heartbeat-only;
+  // when omitted the gate is skipped (direct unit calls / the per-entry + drain
+  // paths are already lease-silenced upstream). Production wiring passes a
+  // predicate reading the stream loop's current lease ownership.
+  isStreamOwner?: () => boolean;
+  // gh#861 finding 3: invoked when the heartbeat tick detects the codex app-server
+  // socket is positively gone (ENOENT) — the wake path is dead, so the production
+  // wiring tears down the heartbeat timer (re-armed when an active cube returns).
+  onAppServerSocketDead?: () => void;
+}
+
+/**
+ * gh#855: FRESH wake-target resolution. Prefer THIS drone's live app-server
+ * socket (pinned into the child's env at spawn) and re-resolve the loaded thread
+ * NOW (loadedThreadIds is re-runnable) — so a missed/stale launch probe or a
+ * thread change can never cause permanent deafness. Self-heals the file cache
+ * (write-only-on-change) so other readers (probeCodexBridgeArmed / health-beat)
+ * stay current. Falls back to the launch-recorded file when the env socket is
+ * absent (un-upgraded launch) — no regression. Returns the resolved target, or
+ * null (caller skips this wake; the next one retries). Does NOT keep a
+ * connection open — the env path opens a short-lived probe client to re-resolve
+ * the thread, then closes it, so the caller can dedup BEFORE opening the wake
+ * connection (no reconnect on an already-delivered wake).
+ */
+function makeCodexClient(
+  sock: string,
+  deps: CodexWakeDeps
+): Pick<CodexAppServerClient, 'connect' | 'readThread' | 'startTurn' | 'loadedThreadIds' | 'close'> {
+  return deps.createClient ? deps.createClient(sock) : new CodexAppServerClient(sock);
+}
+
+async function resolveFreshCodexWakeTarget(
+  active: { cubeId: string; droneId: string },
+  deps: CodexWakeDeps
+): Promise<{ socketPath: string; threadId: string } | null> {
+  const envSocket = codexAppServerSocketFromEnv(deps.env ?? process.env);
+  if (envSocket) {
+    const probe = makeCodexClient(envSocket, deps);
+    await probe.connect();
+    try {
+      const ids = await probe.loadedThreadIds();
+      const summaries: CodexThreadInfo[] = [];
+      for (const id of ids) {
+        const t = await probe.readThread(id);
+        if (t) summaries.push({ id: t.id, cwd: t.cwd, updatedAt: t.updatedAt });
+      }
+      const threadId = pickFreshThread(summaries, { cwd: (deps.cwd ?? (() => process.cwd()))() });
+      if (!threadId) return null; // no loaded thread yet — next wake retries (no permanent fail)
+      await maybePersistWakeTarget(active, { socketPath: envSocket, threadId }, deps);
+      return { socketPath: envSocket, threadId };
+    } finally {
+      probe.close();
+    }
+  }
+
+  // Fallback: the launch-recorded file (un-upgraded launch / env absent) — no
+  // connect needed to resolve, so the caller dedups before opening any socket.
+  const target = await (deps.getCodexWakeTarget ?? getCodexWakeTarget)(active.cubeId, active.droneId);
+  if (!target) return null;
+  return { socketPath: target.socketPath, threadId: target.threadId };
+}
+
+/** Self-healing cache write — only when the resolved target actually changed. */
+async function maybePersistWakeTarget(
+  active: { cubeId: string; droneId: string },
+  fresh: { socketPath: string; threadId: string },
+  deps: CodexWakeDeps
+): Promise<void> {
+  try {
+    const get = deps.getCodexWakeTarget ?? getCodexWakeTarget;
+    const set = deps.setCodexWakeTarget ?? setCodexWakeTarget;
+    const existing = await get(active.cubeId, active.droneId);
+    const prev = existing ? { socketPath: existing.socketPath, threadId: existing.threadId } : null;
+    if (wakeTargetChanged(prev, fresh)) {
+      await set(active.cubeId, active.droneId, fresh);
+    }
+  } catch {
+    // best-effort cache write; never break the wake path
+  }
+}
+
+export function wakeCodexViaAppServer(
+  reason: string = CODEX_WAKE_PROMPT,
+  env: NodeJS.ProcessEnv = process.env,
+  deps: CodexWakeDeps = {}
+): void {
+  const target = resolveCodexWakeTarget(env);
+  if (!target.enabled) return;
+  pendingWakeRequests.push({ reason, deps });
+  if (wakeInFlight) return;
+
+  wakeInFlight = true;
+  void drainCodexWakeQueue().finally(() => {
+    wakeInFlight = false;
+  });
+}
+
+async function drainCodexWakeQueue(): Promise<void> {
+  while (pendingWakeRequests.length > 0) {
+    const request = pendingWakeRequests.shift()!;
+    await wakeCodexTargeted(request.reason, request.deps);
+  }
+}
+
+async function wakeCodexTargeted(reason: string, deps: CodexWakeDeps): Promise<void> {
+  // gh#861 finding 1: another path (heartbeat/retry-drain) is mid-inject into the
+  // same thread — defer to the retry-drain so this entry isn't double-injected nor
+  // lost (the drain re-syncs the whole burst via the server read-cursor).
+  if (!tryAcquireInjectLock()) {
+    scheduleRetryDrain(deps);
+    return;
+  }
+  try {
+    const active = await (deps.getActiveCube ?? getActiveCube)();
+    if (!active) return;
+    // gh#855: resolve FRESH (live env socket + re-resolved thread), falling back
+    // to the launch-recorded file only when the env socket is absent.
+    const resolved = await resolveFreshCodexWakeTarget(active, deps);
+    if (!resolved) return;
+    const { socketPath, threadId } = resolved;
+    const wakeKey = `${threadId}\0${reason}`;
+    if (deliveredWakeKeys.has(wakeKey)) return; // dedup before opening the wake socket
+    const client = makeCodexClient(socketPath, deps);
+    await client.connect();
+    try {
+      const thread = await client.readThread(threadId);
+      if (thread?.status?.type === 'active') {
+        // gh#708/#857: the thread is mid-turn — this per-entry wake can't land
+        // now. Schedule the retry-drain (coalesced, retried-until-delivered) so
+        // the burst's entries are drained once the thread goes idle; codex has no
+        // on-disk tail fallback like Claude's borg-inbox-monitor.
+        scheduleRetryDrain(deps);
+        return;
+      }
+      await client.startTurn(threadId, reason);
+      rememberDeliveredWake(wakeKey);
+      markDelivered(deps);
+    } finally {
+      client.close();
+    }
+  } catch {
+    // gh#857: a transient connect/read/startTurn failure must NOT be silently
+    // swallowed (the old best-effort drop let a single blip lose an entry).
+    // Schedule the retry-drain so the wake is retried-until-delivered; the SSE
+    // stream is never broken (this is fire-and-forget).
+    scheduleRetryDrain(deps);
+  } finally {
+    releaseInjectLock();
+  }
+}
+
+/**
+ * gh#708/#857 WI-1: schedule a single coalesced retry-drain. Multiple wakes
+ * deferred (mid-turn) or missed (transient) collapse into ONE loop
+ * (retryDrainInFlight gate). The loop retries — with exponential backoff
+ * (wakeRetryBackoffMs) — until the thread is reachable+idle and the
+ * CODEX_CATCHUP_PROMPT drain is delivered (server read-cursor then drains ALL
+ * unread, so one drain covers the whole burst). Durable: unlike the old
+ * 15-min-give-up catch-up poller, it retries until a generous age cap
+ * (wakeRetryExpired); the gh#857 WI-2 heartbeat is the backstop beyond that.
+ * Never throws into the SSE path (fire-and-forget).
+ */
+function scheduleRetryDrain(deps: CodexWakeDeps): void {
+  if (retryDrainInFlight) return; // coalesce: one loop covers all deferred/missed wakes
+  retryDrainInFlight = true;
+  void runRetryDrainLoop(deps).finally(() => {
+    retryDrainInFlight = false;
+  });
+}
+
+async function runRetryDrainLoop(deps: CodexWakeDeps): Promise<void> {
+  const sleep = deps.sleep ?? defaultSleep;
+  const now = deps.now ?? Date.now;
+  const jitter = deps.jitter ?? (() => Math.random() * 500);
+  const maxAttempts = deps.maxAttempts ?? WAKE_RETRY_MAX_ATTEMPTS;
+  const startedAt = now();
+  let attempts = 0;
+  // Terminate on the time-based age cap OR a hard iteration ceiling (defensive
+  // belt: a non-advancing clock would make the time-only guard hot-spin).
+  while (!wakeRetryExpired(startedAt, now()) && attempts < maxAttempts) {
+    await sleep(wakeRetryBackoffMs(attempts, jitter()));
+    attempts++;
+    // gh#861 finding 1: another path (heartbeat/per-entry wake) holds the inject
+    // lock — back off and retry rather than double-inject into the same thread.
+    if (!tryAcquireInjectLock()) continue;
+    try {
+      const active = await (deps.getActiveCube ?? getActiveCube)();
+      if (!active) continue; // no active cube yet → keep retrying (until age cap)
+      // gh#855: same FRESH resolution as the per-entry wake, so a stale launch
+      // probe can't defeat the retry-drain either.
+      const resolved = await resolveFreshCodexWakeTarget(active, deps);
+      if (!resolved) continue; // thread not loaded yet → retry (age-capped)
+      const { socketPath, threadId } = resolved;
+      const client = makeCodexClient(socketPath, deps);
+      await client.connect();
+      try {
+        const thread = await client.readThread(threadId);
+        if (thread?.status?.type === 'active') {
+          continue; // re-defer: still mid-turn (backoff before next poll)
+        }
+        await client.startTurn(threadId, CODEX_CATCHUP_PROMPT);
+        markDelivered(deps);
+        return; // drain delivered → server read-cursor drains all unread → done
+      } finally {
+        client.close();
+      }
+    } catch {
+      // transient socket/read error must not abort the loop — keep retrying with
+      // backoff until reachable+idle or the age cap; never throws into SSE.
+    } finally {
+      releaseInjectLock();
+    }
+  }
+  // aged out: the gh#857 WI-2 periodic heartbeat is the ultimate backstop.
+}
+
+/**
+ * gh#857 WI-2: codex /loop-equivalent heartbeat cadence. Codex retains this
+ * independent 20-minute drain because it has no Claude-style per-entry inbox
+ * Monitor. Claude recovery is adaptive: 3h ±30m while the Monitor is healthy
+ * or indeterminate, and 15m ±3m only while it is explicitly broken.
+ */
+export const CODEX_HEARTBEAT_CADENCE_MS = 20 * 60_000;
+
+/**
+ * gh#857/client#76: one tick of the codex catch-up backstop. The cadence only
+ * initiates a token-free unread-state preflight; a DRAIN turn is injected when
+ * that authoritative scan finds real work that a per-entry wake missed. Recent
+ * delivery still suppresses redundant preflights. Unlike the per-entry path it
+ * does not consult deliveredWakeKeys because the unread cursor is authoritative.
+ * Best-effort: a failed preflight, mid-turn thread, transient error, or unresolved
+ * target skips this tick and lets the next cadence retry. Never throws.
+ */
+export async function fireCodexHeartbeatTick(
+  deps: CodexWakeDeps = {},
+  cadenceMs: number = CODEX_HEARTBEAT_CADENCE_MS
+): Promise<void> {
+  if (heartbeatInFlight) return; // a prior tick's IO is still running → no overlap
+  const now = (deps.now ?? Date.now)();
+  if (!shouldFireHeartbeat(lastDeliveredAt, now, cadenceMs)) return; // a wake landed recently
+  // gh#861 finding 2: a lease-LOSING duplicate child must not tick/inject — mirror
+  // the per-entry path, which only fires inside an SSE session holding the stream
+  // lease. When the gate is provided and we don't own the lease, skip this tick.
+  if (deps.isStreamOwner && !deps.isStreamOwner()) return;
+  // gh#861 finding 1: another path is mid-inject into the thread → skip this tick
+  // (next tick retries) rather than collide a DRAIN prompt with an in-flight wake.
+  if (!tryAcquireInjectLock()) return;
+  // Set BEFORE the first await — the check+gate+set above are synchronous, so a
+  // concurrent tick can't interleave before the flag is set (single-threaded).
+  heartbeatInFlight = true;
+  try {
+    const active = await (deps.getActiveCube ?? getActiveCube)();
+    if (!active) return;
+    // Elapsed time alone must never cross the model boundary. Query the
+    // authoritative unread state without advancing its cursor; only then touch
+    // the app-server socket or resolve a thread.
+    const hasPendingWork = deps.hasPendingWork ?? hasPendingWakeActivity;
+    if (!(await hasPendingWork(active))) return;
+    const resolved = await resolveFreshCodexWakeTarget(active, deps);
+    if (!resolved) return; // thread not loaded yet → next tick retries
+    const client = makeCodexClient(resolved.socketPath, deps);
+    await client.connect();
+    try {
+      const thread = await client.readThread(resolved.threadId);
+      if (thread?.status?.type === 'active') return; // mid-turn → skip; next tick retries
+      await client.startTurn(resolved.threadId, CODEX_CATCHUP_PROMPT);
+      // markDelivered updates local heartbeat-gating state only.
+      markDelivered(deps);
+    } finally {
+      client.close();
+    }
+  } catch (err) {
+    // gh#861 finding 3: a positively-dead app-server socket (ENOENT) → the wake
+    // path is gone; signal teardown so the timer stops ticking against a dead
+    // socket (re-armed when an active cube returns). Other (transient) errors are
+    // best-effort skips — never break the SSE stream; next tick retries.
+    if (isAppServerDeadError(err)) deps.onAppServerSocketDead?.();
+  } finally {
+    heartbeatInFlight = false;
+    releaseInjectLock();
+  }
+}
+
+/**
+ * gh#857 WI-2: start the codex /loop-equivalent heartbeat — a setInterval firing
+ * fireCodexHeartbeatTick every cadence. CODEX-ONLY: claude wakes via the tail-F
+ * inbox Monitor + /loop ScheduleWakeup and has NO app-server socket to inject
+ * into, so the heartbeat is intrinsically a codex mechanism. The gate reads
+ * agentKind and remote-wake capability LOCALLY from this child's own env,
+ * never a mutable/server-recorded field, so a mislabel can't silently defeat
+ * the backstop (gh#633 lesson). Agent CLI identity and remote transport are
+ * separate: a Codex CLI without a live remote transport has no app-server
+ * heartbeat to run. The timer is unref'd so it never keeps the process alive.
+ * Returns the timer, or null when this is not a remotely-wakeable Codex
+ * session. Injectable for tests.
+ */
+export function startCodexHeartbeat(
+  opts: {
+    agentKind?: 'claude' | 'codex' | 'opencode';
+    remoteWakeEnabled?: boolean;
+    intervalMs?: number;
+    tick?: () => void;
+  } = {}
+): ReturnType<typeof setInterval> | null {
+  const agentKind = opts.agentKind ?? resolveSessionAgentKind();
+  const remoteWakeEnabled = opts.remoteWakeEnabled ?? isCodexRemoteWakeEnabled();
+  if (agentKind !== 'codex' || !remoteWakeEnabled) return null;
+  const intervalMs = opts.intervalMs ?? CODEX_HEARTBEAT_CADENCE_MS;
+  const tick = opts.tick ?? (() => void fireCodexHeartbeatTick());
+  const timer = setInterval(tick, intervalMs);
+  timer.unref?.();
+  return timer;
+}
+
+export function resetCodexWakeForTests(): void {
+  wakeInFlight = false;
+  pendingWakeRequests.length = 0;
+  deliveredWakeKeys.clear();
+  deliveredWakeKeyOrder.length = 0;
+  retryDrainInFlight = false;
+  lastDeliveredAt = null;
+  heartbeatInFlight = false;
+  injectInFlight = false;
+}
+
+function rememberDeliveredWake(key: string): void {
+  if (deliveredWakeKeys.has(key)) return;
+  deliveredWakeKeys.add(key);
+  deliveredWakeKeyOrder.push(key);
+  while (deliveredWakeKeyOrder.length > DELIVERED_WAKE_KEY_CAP) {
+    const oldKey = deliveredWakeKeyOrder.shift();
+    if (oldKey) deliveredWakeKeys.delete(oldKey);
+  }
+}

package/src/codex-launch.ts

@@ -0,0 +1,140 @@
+import type { BorgCli } from './cubes.js';
+import { wakePathArming, type AgentKind } from './regen-format.js';
+
+/**
+ * The claude kickoff prompt's wake-path section (gh#929) — the SAME shared
+ * `wakePathArming` the SessionStart hook + /clear orientation use (one place,
+ * not three), plus a one-line NEVER-TaskStop safety reminder preserved from
+ * the pre-gh#929 monitorClause. Built by both launch call sites
+ * (claude.ts + assimilate-cmd.ts) and passed to `buildAgentKickoffPrompt` as
+ * `monitorClause`. Codex wakes via the app-server (no tail-Monitor / `/loop`
+ * to arm) → empty; no active cube (no inboxPath) → empty.
+ */
+export function buildKickoffWakePathClause(
+  agentKind: AgentKind,
+  inboxPath: string | null,
+  monitorStateRoot?: string | null
+): string {
+  if (agentKind === 'claude' && inboxPath) {
+    return (
+      wakePathArming('claude', inboxPath, monitorStateRoot) +
+      '\nKeep this Monitor armed for the whole session — NEVER TaskStop it (the generic ' +
+      '/loop "TaskStop any Monitor you armed" step does NOT apply to the cube inbox Monitor; ' +
+      'it targets throwaway loop-scratch watches only). The sole exception is a confirmed ' +
+      'terminal eviction (410 DRONE_EVICTED). '
+    );
+  }
+  return '';
+}
+
+export interface CodexWakeTargetDeps {
+  setCodexWakeTarget: (
+    cubeId: string,
+    droneId: string,
+    target: { threadId: string; socketPath: string }
+  ) => Promise<void>;
+  findLoadedCodexThread: (options: {
+    socketPath: string;
+    cwd: string;
+    previewIncludes: string;
+    updatedAfter: number;
+  }) => Promise<string | null>;
+}
+
+export function buildAgentKickoffPrompt(options: {
+  cli: BorgCli;
+  codexWakeNonce: string | null;
+  monitorClause: string;
+  codexWakePathClause?: string;
+}): string {
+  // gh#929: compacted to the load-bearing launch essentials (lean/explicit/
+  // imperative, #914 treatment). STRIPPED: the read-log-triage paragraph (the
+  // playbook owns it post-#914) + the role-specific anti-passive-Standing
+  // clause (Coordinator/Queen-only; belongs in role-text, not injected for
+  // ALL). KEPT: core call + MCP-disconnect recovery + the wake-path arming
+  // (claude via the shared monitorClause = buildKickoffWakePathClause; codex
+  // via codexWakePathClause) + the claude/codex/opencode cli-branching.
+  const codexNonceClause = options.codexWakeNonce
+    ? `Wake target nonce: ${options.codexWakeNonce}. `
+    : '';
+  const codexWakePathClause =
+    options.codexWakePathClause ??
+    `Codex Borg wakeups use remote-control when available; if no wake arrives, run borg_regen manually when returning to the session.`;
+  const opencodeWakePathClause = `OpenCode wakes: the inbox Monitor is not available yet for OpenCode; check activity by calling borg_read-log periodically.`;
+  const loopOrEmpty = options.cli === 'claude' ? '/loop ' : '';
+  const wakeClause = options.cli === 'claude'
+    ? options.monitorClause
+    : options.cli === 'codex'
+      ? codexWakePathClause
+      : opencodeWakePathClause;
+  return (
+    `${loopOrEmpty}Call borg_regen and follow the playbook in its response. ` +
+    codexNonceClause +
+    `Note: at session start the borg MCP server is still spinning up in ` +
+    `parallel — if a system reminder claims "MCP server disconnected" or ` +
+    `the borg tools are not yet registered, do NOT bail. Recover via ` +
+    `\`ToolSearch({query: "select:mcp__borg__borg_regen,mcp__borg__borg_log,Monitor", max_results: 3})\` ` +
+    `to load the bootstrap tools in one call, then call borg_regen. ` +
+    `The server typically becomes available within a few seconds. ` +
+    wakeClause
+  );
+}
+
+export function socketPathFromRemoteArgs(args: string[]): string | null {
+  const index = args.indexOf('--remote');
+  if (index < 0) return null;
+  const value = args[index + 1];
+  if (!value?.startsWith('unix://')) return null;
+  return value.slice('unix://'.length);
+}
+
+export function threadIdFromPassthroughArgs(args: string[]): string | null {
+  if (args[0] === 'resume' && args[1] && !args[1].startsWith('-')) return args[1];
+  const resumeIndex = args.indexOf('--resume');
+  if (resumeIndex >= 0 && args[resumeIndex + 1]) return args[resumeIndex + 1];
+  return null;
+}
+
+export async function recordCodexWakeTarget(options: {
+  deps: CodexWakeTargetDeps;
+  cubeId: string;
+  droneId: string;
+  socketPath: string;
+  cwd: string;
+  previewNeedle: string;
+  launchedAtSeconds: number;
+  passthroughArgs?: string[];
+}): Promise<void> {
+  try {
+    const explicitThreadId = options.passthroughArgs
+      ? threadIdFromPassthroughArgs(options.passthroughArgs)
+      : null;
+    if (explicitThreadId) {
+      await options.deps.setCodexWakeTarget(options.cubeId, options.droneId, {
+        threadId: explicitThreadId,
+        socketPath: options.socketPath,
+      });
+      return;
+    }
+
+    const deadline = Date.now() + 15_000;
+    while (Date.now() < deadline) {
+      const threadId = await options.deps.findLoadedCodexThread({
+        socketPath: options.socketPath,
+        cwd: options.cwd,
+        previewIncludes: options.previewNeedle,
+        updatedAfter: options.launchedAtSeconds - 5,
+      });
+      if (threadId) {
+        await options.deps.setCodexWakeTarget(options.cubeId, options.droneId, {
+          threadId,
+          socketPath: options.socketPath,
+        });
+        return;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+  } catch {
+    // Best-effort mapping: launch still succeeds and manual regen remains available.
+  }
+}