kitty-hive 0.6.12 → 0.7.2

package/codex-channel.ts

@@ -31,8 +31,10 @@
  *   CODEX_EXTRA_ARGS  extra space-separated args before the prompt
  */
 
-import { spawn } from 'node:child_process';
+import { spawn, type ChildProcess } from 'node:child_process';
 import { execSync } from 'node:child_process';
+import { createServer } from 'node:net';
+import { TurnTracker, type RpcTransport, type TurnOutcome } from './src/codex-channel-runtime.js';
 
 // --- Config (env) ---
 
@@ -44,6 +46,12 @@ const HIVE_AGENT_ROLES = process.env.HIVE_AGENT_ROLES || '';
 const CODEX_CMD = process.env.CODEX_CMD || 'codex';
 const CODEX_PROFILE = process.env.CODEX_PROFILE || '';
 const CODEX_EXTRA_ARGS = (process.env.CODEX_EXTRA_ARGS || '').trim();
+// CODEX_CHANNEL_MODE: 'auto' (default) tries appserver first, falls back to
+// exec if codex < 0.124 or app-server fails to start. 'appserver' forces
+// appserver mode (fails hard if unavailable). 'exec' forces the legacy
+// spawn-per-event mode (works on any codex version, no shared context).
+const CODEX_CHANNEL_MODE = (process.env.CODEX_CHANNEL_MODE || 'auto') as 'auto' | 'appserver' | 'exec';
+const CODEX_APPSERVER_CWD = process.env.CODEX_APPSERVER_CWD || process.cwd();
 
 // Allow CLI flags to override env
 for (let i = 2; i < process.argv.length; i++) {
@@ -207,6 +215,13 @@ interface ParsedEvent {
   raw?: string;
 }
 
+// NO daemon-side retry. Earlier versions retried failed `sendTurn`s up to 3×;
+// that turned out to be the proximate cause of the 2026-05-26 duplicate-turn
+// incident — see codex-channel-runtime.ts header for the post-mortem. The
+// TurnTracker now blocks re-issue of `turn/start` for an already-attempted
+// event_id; loss recovery (hive SSE replay, pending_pushes drain on daemon
+// respawn) lives at a higher layer.
+
 let codexBusy = false;
 const eventQueue: ParsedEvent[] = [];
 
@@ -254,6 +269,329 @@ function buildPrompt(ev: ParsedEvent): string {
   ].join('\n');
 }
 
+// ===== Appserver mode (codex ≥ 0.124) =====
+// Long-lived codex via `codex app-server --listen ws://127.0.0.1:<port>`.
+// One JSON-RPC WebSocket connection, one persistent thread, one turn per
+// hive event injected via turn/start. Thread context survives across events
+// — no codex startup overhead, no fresh-context loss.
+
+let pushMode: 'appserver' | 'exec' | null = null;
+let appserverProc: ChildProcess | null = null;
+let appserverWs: any /* WebSocket */ = null;
+let appserverWsUrl: string | null = null;  // ws://127.0.0.1:<port> — for outside callers via supervisor
+let threadId: string | null = null;
+let appserverDeathHandled = false;  // guard so multiple death signals only exit once
+let turnTracker: TurnTracker | null = null;
+
+/** Called when EITHER codex app-server child process dies post-ready OR the WS
+ *  closes / errors. Both fire together when app-server crashes. Exits the
+ *  daemon with non-zero so the supervisor's child.on('exit') triggers an
+ *  exponential-backoff respawn with a fresh codex app-server. In-flight events
+ *  in the local queue ARE lost — known limitation, documented in v0.7.0 notes.
+ *  Idempotent via the appserverDeathHandled guard. */
+function onAppserverDeath(reason: string): void {
+  if (appserverDeathHandled) return;
+  appserverDeathHandled = true;
+  console.error(`[codex-channel] appserver died: ${reason}`);
+  console.error('[codex-channel] exiting daemon — supervisor will respawn with fresh codex app-server');
+  try { appserverWs?.close(); } catch { /* ignore */ }
+  try { appserverProc?.kill('SIGTERM'); } catch { /* ignore */ }
+  // exit code 2 distinguishes "app-server crash" from "clean shutdown via SIGTERM"
+  process.exit(2);
+}
+let nextRpcId = 100;
+const pendingResponses = new Map<number, { resolve: (r: any) => void; reject: (e: Error) => void }>();
+
+function pickFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = createServer();
+    srv.listen(0, '127.0.0.1', () => {
+      const addr = srv.address();
+      const port = typeof addr === 'object' && addr ? addr.port : 0;
+      srv.close(() => port ? resolve(port) : reject(new Error('failed to pick free port')));
+    });
+    srv.on('error', reject);
+  });
+}
+
+async function setupAppserver(): Promise<void> {
+  if (typeof (globalThis as any).WebSocket !== 'function') {
+    throw new Error('global WebSocket not available (need Node 22+); set CODEX_CHANNEL_MODE=exec');
+  }
+  const port = await pickFreePort();
+  console.error(`[codex-channel] starting appserver: ${CODEX_CMD} app-server --listen ws://127.0.0.1:${port}`);
+
+  // detached: true puts appserverProc in its own process group, so SIGTERM
+  // to -pid kills the entire subtree (npm/npx wrapper + grandchild codex
+  // binary). Without this, killing only the wrapper leaves the actual codex
+  // process orphaned and still LISTENing on the ws port — see Bug 1 follow-up
+  // (2026-05-20): `agent remove` killed the daemon but `lsof -i :<port>` still
+  // showed the vendor codex binary holding the port.
+  appserverProc = spawn(CODEX_CMD, ['app-server', '--listen', `ws://127.0.0.1:${port}`], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    detached: true,
+  });
+
+  // Wait for listen-ready line on stderr, or fail after 10s
+  await new Promise<void>((resolve, reject) => {
+    let ready = false;
+    const timer = setTimeout(() => {
+      if (!ready) { ready = true; reject(new Error('codex app-server did not become ready within 10s')); }
+    }, 10000);
+    appserverProc!.stderr!.on('data', (chunk) => {
+      const s = String(chunk);
+      process.stderr.write(`[codex-app] ${s}`);
+      if (!ready && /Listening|listen|started|ready/i.test(s)) {
+        ready = true; clearTimeout(timer); resolve();
+      }
+    });
+    appserverProc!.stdout!.on('data', (chunk) => process.stderr.write(`[codex-app] ${chunk}`));
+    appserverProc!.on('exit', (code, signal) => {
+      if (!ready) {
+        ready = true; clearTimeout(timer);
+        reject(new Error(`codex app-server exited (code=${code}, signal=${signal}) before becoming ready`));
+        return;
+      }
+      // post-ready exit: codex app-server crashed mid-flight. Daemon's WS will
+      // also close immediately; further turn/start calls would silently fail.
+      // Best recovery is for daemon to die so supervisor respawns it cleanly
+      // with a fresh codex app-server. In-flight events in the local queue
+      // are lost — acceptable for v1 (rare path); pending_pushes in hive
+      // will hold any events that arrived AFTER daemon exit and re-deliver
+      // when supervisor's new daemon binds.
+      onAppserverDeath(`codex app-server exited (code=${code}, signal=${signal})`);
+    });
+    appserverProc!.on('error', (err) => {
+      if (!ready) { ready = true; clearTimeout(timer); reject(err); return; }
+      onAppserverDeath(`codex app-server process error: ${err?.message || err}`);
+    });
+  });
+
+  // Even after the "listening" log line, give the WS endpoint a beat to accept.
+  await new Promise(r => setTimeout(r, 200));
+
+  // Open WS
+  appserverWs = new (globalThis as any).WebSocket(`ws://127.0.0.1:${port}`);
+  await new Promise<void>((resolve, reject) => {
+    const onOpen = () => { cleanup(); resolve(); };
+    const onErr = (e: any) => { cleanup(); reject(new Error(`WS open failed: ${e?.message || e?.type || 'unknown'}`)); };
+    const cleanup = () => {
+      appserverWs.removeEventListener('open', onOpen);
+      appserverWs.removeEventListener('error', onErr);
+    };
+    appserverWs.addEventListener('open', onOpen);
+    appserverWs.addEventListener('error', onErr);
+    setTimeout(() => { if (appserverWs.readyState !== 1) { cleanup(); reject(new Error('WS open timeout')); } }, 5000);
+  });
+
+  appserverWs.addEventListener('message', (ev: any) => {
+    let msg: any;
+    try { msg = JSON.parse(String(ev.data)); } catch (err) {
+      console.error('[codex-channel] WS parse error:', err);
+      return;
+    }
+    // RPC response
+    if (msg.id != null && (msg.result !== undefined || msg.error !== undefined)) {
+      const pending = pendingResponses.get(msg.id);
+      if (pending) {
+        pendingResponses.delete(msg.id);
+        if (msg.error) pending.reject(new Error(`codex rpc error: ${JSON.stringify(msg.error)}`));
+        else pending.resolve(msg.result);
+      }
+      return;
+    }
+    // Notification — let the tracker route turn-related ones by turn id.
+    // Unmatched notifications (item delta, agentMessage stream, etc.) are
+    // ignored at this layer.
+    if (msg.method && turnTracker?.handleNotification(msg.method, msg.params)) {
+      return;
+    }
+  });
+
+  appserverWs.addEventListener('close', () => {
+    onAppserverDeath('appserver WS closed by remote (codex app-server likely exited)');
+  });
+  appserverWs.addEventListener('error', (e: any) => {
+    onAppserverDeath(`appserver WS error: ${e?.message || e?.type || 'unknown'}`);
+  });
+
+  // 1. initialize
+  await rpcCall('initialize', {
+    clientInfo: { name: 'kitty-hive-codex-channel', version: '0.7.0' },
+  });
+  // initialized notification — fire and forget
+  appserverWs.send(JSON.stringify({ jsonrpc: '2.0', method: 'initialized', params: {} }));
+
+  // 2. thread/resume (if we have a persisted thread_id from a prior daemon
+  //    lifetime) or thread/start (first-time spawn). Supervisor injects
+  //    HIVE_AGENT_THREAD_ID after the first ready announcement, persisted in
+  //    agents.thread_id; codex app-server loads the corresponding jsonl from
+  //    ~/.codex/sessions/ so conversation history survives daemon kill /
+  //    serve restart / machine reboot.
+  const persistedThreadId = (process.env.HIVE_AGENT_THREAD_ID || '').trim();
+  let resumed = false;
+  if (persistedThreadId) {
+    try {
+      const resumeResp = await rpcCall('thread/resume', { threadId: persistedThreadId });
+      const resumedId = resumeResp?.thread?.id;
+      if (!resumedId) throw new Error(`thread/resume returned no thread.id: ${JSON.stringify(resumeResp)}`);
+      threadId = resumedId;
+      resumed = true;
+      console.error(`[codex-channel] appserver thread resumed: ${threadId} (${resumeResp?.thread?.turns?.length ?? 0} turns)`);
+    } catch (err) {
+      // Common cause: jsonl missing (stale thread_id from a wiped ~/.codex)
+      // or codex schema upgrade. Fall back to a fresh thread; the new
+      // thread_id will overwrite the stale one in agents.thread_id via
+      // markDaemonReady → setAgentThreadId, so this self-heals.
+      console.error(`[codex-channel] thread/resume failed for ${persistedThreadId}, falling back to thread/start: ${err}`);
+    }
+  }
+  if (!resumed) {
+    const threadResp = await rpcCall('thread/start', { cwd: CODEX_APPSERVER_CWD });
+    threadId = threadResp?.thread?.id;
+    if (!threadId) throw new Error(`thread/start did not return thread.id: ${JSON.stringify(threadResp)}`);
+    console.error(`[codex-channel] appserver thread started: ${threadId}`);
+  }
+  appserverWsUrl = `ws://127.0.0.1:${port}`;
+
+  // Bring up the TurnTracker now that we have a thread. RpcTransport is a
+  // thin adapter over the local rpcCall — the tracker stays decoupled from
+  // our WS plumbing so tests can swap in a stub transport.
+  turnTracker = new TurnTracker(
+    { call: (method, params, timeoutMs) => rpcCall(method, params, timeoutMs) },
+    threadId!,
+  );
+
+  // 2a. Announce ready signal back to hive supervisor so kitty-kitty (or any
+  // other launcher) can query the (ws_url, thread_id) pair via
+  // hive_codex_pane_ws / GET /admin/codex-daemons. Best-effort: failure here
+  // just means the daemon's pane info isn't immediately discoverable; daemon
+  // still processes pushes normally. Also persists thread_id for next spawn.
+  await announceReady().catch(err => {
+    console.error('[codex-channel] failed to announce ready to supervisor:', err);
+  });
+
+  // 3. intro turn. On thread/start (first-time spawn), inject the full agent
+  // brief. On thread/resume, the brief is already in thread history — but the
+  // daemon process is brand new, so its MCP client session lost the
+  // hive_start binding that the thread previously made. Inject a short
+  // re-bind notice so codex calls hive_start again before the next event.
+  if (resumed) {
+    const rebind = [
+      `[kitty-hive] daemon restarted — your MCP session is fresh.`,
+      `Call hive_start({ id: "${agentId}" }) again to re-bind your hive identity`,
+      `before handling the next event. Then wait silently for the next push.`,
+    ].join('\n');
+    const outcome = await sendTurn(rebind, { eventId: `daemon-rebind:${threadId}:${Date.now()}` });
+    if (outcome.kind !== 'completed') {
+      console.error(`[codex-channel] rebind intro turn outcome: ${outcome.kind} — continuing anyway`);
+    }
+  } else {
+    const intro = [
+      `You are kitty-hive agent "${agentName}" (id: ${agentId}).`,
+      ``,
+      `You are running inside a persistent codex thread driven by the kitty-hive`,
+      `codex-channel daemon. The daemon will inject one short message per hive`,
+      `event into this thread; you handle the event and wait for the next.`,
+      ``,
+      `FIRST ACTION: call hive_start({ id: "${agentId}" }) to bind your MCP`,
+      `session to your hive identity. This makes every hive_* tool call run`,
+      `as you (not as a new agent). Do this BEFORE handling the first event.`,
+      `NOTE: if you ever see a "[kitty-hive] daemon restarted" notice, call`,
+      `hive_start again — the daemon process restarted and the MCP binding`,
+      `was lost (but this thread's history was preserved).`,
+      ``,
+      `For each event:`,
+      `- Push notifications are id-only by design — call the fetch tool the`,
+      `  daemon points to (hive_dm_read / hive_check / hive_team_events /`,
+      `  hive_team_info) BEFORE acting on the event content.`,
+      `- Handle per type (DM, task-propose, step-start, awaiting_approval,`,
+      `  team-message, ...) using the matching hive_* tools.`,
+      `- When done, just stop. The next event will arrive as a new turn.`,
+      ``,
+      `Acknowledge readiness briefly, then wait for the first event.`,
+    ].join('\n');
+    const outcome = await sendTurn(intro, { eventId: `daemon-intro:${threadId}:${Date.now()}` });
+    if (outcome.kind !== 'completed') {
+      console.error(`[codex-channel] startup intro turn outcome: ${outcome.kind} — continuing anyway`);
+    }
+  }
+}
+
+/** Tell the hive supervisor (the parent process that spawned us) that we have
+ *  a live ws + thread, so it can answer hive_codex_pane_ws / show in admin
+ *  snapshots. HIVE_URL is the supervisor's MCP base url (set explicitly by
+ *  codex-supervisor when it spawns us); derive admin URL from it. */
+async function announceReady(): Promise<void> {
+  if (!agentId || !appserverWsUrl || !threadId) return;
+  const adminUrl = ENV_URL.replace(/\/mcp\/?$/, '') + '/admin/codex-daemon-ready';
+  const res = await fetch(adminUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      agent_id: agentId,
+      ws_url: appserverWsUrl,
+      thread_id: threadId,
+    }),
+  });
+  if (!res.ok) {
+    throw new Error(`POST ${adminUrl} → ${res.status} ${await res.text().catch(() => '')}`);
+  }
+  console.error(`[codex-channel] announced ready: ws=${appserverWsUrl} thread=${threadId.slice(0, 8)}...`);
+}
+
+async function rpcCall(method: string, params: any, timeoutMs = 30000): Promise<any> {
+  if (!appserverWs || appserverWs.readyState !== 1) throw new Error('appserver WS not open');
+  const id = nextRpcId++;
+  const payload = JSON.stringify({ jsonrpc: '2.0', id, method, params });
+  return new Promise((resolve, reject) => {
+    pendingResponses.set(id, { resolve, reject });
+    appserverWs.send(payload);
+    setTimeout(() => {
+      if (pendingResponses.has(id)) {
+        pendingResponses.delete(id);
+        reject(new Error(`codex appserver rpc '${method}' timed out after ${timeoutMs}ms`));
+      }
+    }, timeoutMs);
+  });
+}
+
+/** Inject one hive event as a turn into the codex thread. Returns the
+ *  terminal outcome — caller branches on `outcome.kind` rather than catching.
+ *  See codex-channel-runtime.ts for the design rationale (2026-05-26 incident
+ *  notes). The eventId is used for cross-attempt idempotency: once an event
+ *  has been handed to the tracker, the tracker refuses to re-issue
+ *  `turn/start` for the same id, no matter what kind of failure intervened.
+ *  This is the core defense against duplicate-turn injection. */
+async function sendTurn(text: string, opts: { eventId?: string } = {}): Promise<TurnOutcome> {
+  if (!turnTracker) throw new Error('turnTracker not initialized — did setupAppserver run?');
+  return turnTracker.sendTurn(text, opts);
+}
+
+/** Short prompt for appserver mode — context is persistent, so each event is
+ *  just "here's what arrived + how to fetch full content". */
+function buildEventTurnText(ev: ParsedEvent): string {
+  const senderLabel = ev.from || ev.from_agent_id || 'unknown';
+  const summary = ev.title || ev.preview || ev.raw || `(no summary)`;
+  let fetchHint: string;
+  if (ev.type === 'message' && ev.message_id != null) {
+    fetchHint = `hive_dm_read({ message_id: ${ev.message_id} })`;
+  } else if (ev.task_id) {
+    fetchHint = `hive_check({ task_id: "${ev.task_id}" })`;
+  } else if (ev.team_id) {
+    fetchHint = ev.type === 'team-rules-update'
+      ? `hive_team_info({ team_id: "${ev.team_id}" })  # rules updated; refresh`
+      : `hive_team_events({ team_id: "${ev.team_id}" })`;
+  } else {
+    fetchHint = `hive_inbox()`;
+  }
+  return [
+    `[hive event] type=${ev.type} from=${senderLabel}`,
+    `summary: ${summary}`,
+    `fetch:   ${fetchHint}`,
+  ].join('\n');
+}
+
 function spawnCodex(prompt: string): Promise<void> {
   return new Promise((resolve) => {
     const args: string[] = ['exec'];
@@ -283,17 +621,80 @@ function spawnCodex(prompt: string): Promise<void> {
   });
 }
 
+/** Build a stable dedup key from a parsed event. Used as TurnTracker's
+ *  eventId so even a retry/replay of the same logical hive event never
+ *  produces a second `turn/start` on codex's side. Falls back to a content
+ *  hash when nothing else is available. */
+function eventDedupKey(ev: ParsedEvent): string {
+  if (ev.event_id) return `evid:${ev.event_id}`;
+  if (ev.message_id != null) return `dm:${ev.message_id}`;
+  if (ev.task_id) return `task:${ev.task_id}:${ev.type || 'unknown'}`;
+  if (ev.team_id) return `team:${ev.team_id}:${ev.type || 'unknown'}`;
+  // Last resort — should be rare; hash content + sender so unrelated events
+  // don't collide.
+  return `raw:${ev.from_agent_id || 'unknown'}:${ev.type || 'unknown'}:${(ev.raw || ev.preview || '').slice(0, 80)}`;
+}
+
 async function processNextEvent() {
   if (codexBusy) return;
   const next = eventQueue.shift();
   if (!next) return;
   codexBusy = true;
   try {
-    await spawnCodex(buildPrompt(next));
+    if (pushMode === 'appserver') {
+      const text = buildEventTurnText(next);
+      const eventId = eventDedupKey(next);
+      console.error(`[codex-channel] inject turn (${text.length} chars) eventId=${eventId} into thread ${threadId?.slice(-8)}`);
+      const outcome = await sendTurn(text, { eventId });
+      // TurnOutcome is a closed union — each kind reflects a known terminal
+      // state observed at codex's side. We DON'T retry locally on any of
+      // these: re-issuing turn/start was the exact cause of the 2026-05-26
+      // duplicate-turn incident. Loss recovery (if any is warranted) lives
+      // a layer up: hive's pending_pushes / SSE replay across daemon
+      // respawn delivers missed events again.
+      switch (outcome.kind) {
+        case 'completed':
+          // Normal path. Nothing more to do.
+          break;
+        case 'failed':
+          console.error(`[codex-channel] turn failed on codex (turnId=${outcome.turnId} willRetry=${outcome.willRetry}): ${JSON.stringify(outcome.error)}`);
+          break;
+        case 'interrupted':
+          console.error(`[codex-channel] turn interrupted on codex (turnId=${outcome.turnId}) — event consumed`);
+          break;
+        case 'timeout':
+          console.error(`[codex-channel] turn did not complete within ${outcome.afterMs}ms (turnId=${outcome.turnId}); leaving turn in-flight on codex, NOT retrying to avoid duplicate inject`);
+          break;
+        case 'rpc_send_error':
+          console.error(`[codex-channel] turn/start RPC error (event eventId=${eventId}): ${outcome.error.message}`);
+          if (!appserverWs || appserverWs.readyState !== 1) {
+            console.error('[codex-channel] appserver WS appears dead; switching subsequent events to exec mode (daemon will exit shortly anyway)');
+            pushMode = 'exec';
+          }
+          break;
+        case 'skipped_duplicate':
+          // Should only fire if the same eventId is enqueued twice in this
+          // daemon lifetime — e.g. SSE drain replay after a brief disconnect.
+          // Expected behavior; log at info to make it visible without alarm.
+          console.error(`[codex-channel] skipped already-injected event (eventId=${outcome.eventId})`);
+          break;
+      }
+    } else {
+      await spawnCodex(buildPrompt(next));
+    }
+  } catch (err) {
+    // Anything that throws now is genuinely unexpected (sendTurn no longer
+    // throws — it returns TurnOutcome). Log loudly and move on; do not
+    // re-queue, to preserve the no-duplicate guarantee.
+    console.error('[codex-channel] unexpected processing error (event dropped to preserve no-duplicate guarantee):', err);
+    console.error(`[codex-channel] dropped event: ${JSON.stringify({
+      type: next.type, event_id: next.event_id, task_id: next.task_id,
+      message_id: next.message_id, from: next.from || next.from_agent_id,
+    })}`);
   } finally {
     codexBusy = false;
   }
-  // Drain any events that piled up while codex was running
+  // Drain any events that piled up while codex was busy
   if (eventQueue.length > 0) setImmediate(processNextEvent);
 }
 
@@ -371,8 +772,63 @@ async function listenSSE() {
 
 // --- Boot ---
 
+async function setupPushMode() {
+  if (CODEX_CHANNEL_MODE === 'exec') {
+    pushMode = 'exec';
+    console.error(`[codex-channel] mode: exec (per-event codex spawn; forced via CODEX_CHANNEL_MODE=exec)`);
+    return;
+  }
+  // 'auto' or 'appserver': try appserver
+  try {
+    await setupAppserver();
+    pushMode = 'appserver';
+    console.error(`[codex-channel] mode: appserver (long-lived codex thread; context persists across events)`);
+  } catch (err) {
+    if (CODEX_CHANNEL_MODE === 'appserver') {
+      console.error(`[codex-channel] appserver mode forced but setup failed: ${err}`);
+      cleanupAppserver();
+      process.exit(1);
+    }
+    console.error(`[codex-channel] appserver setup failed, falling back to exec mode: ${err}`);
+    cleanupAppserver();
+    pushMode = 'exec';
+  }
+}
+
+function cleanupAppserver() {
+  if (appserverWs) {
+    try { appserverWs.close(); } catch { /* ignore */ }
+    appserverWs = null;
+  }
+  if (appserverProc?.pid) {
+    // Kill the WHOLE process group (negative pid). Because we spawned with
+    // `detached: true`, appserverProc.pid is also the group leader id; the
+    // grandchild codex binary the wrapper exec'd is in the same group and
+    // will receive SIGTERM too. Without this, the wrapper dies but the
+    // grandchild codex binary stays alive holding the ws port.
+    try { process.kill(-appserverProc.pid, 'SIGTERM'); } catch { /* ignore */ }
+    // Fallback: also SIGTERM the wrapper itself in case kill -group missed.
+    try { appserverProc.kill('SIGTERM'); } catch { /* ignore */ }
+    appserverProc = null;
+  }
+  threadId = null;
+}
+
+function shutdown(signal: NodeJS.Signals) {
+  // Mark intentional shutdown BEFORE killing children — otherwise
+  // appserverProc.kill() triggers our death handler thinking app-server
+  // crashed, racing process.exit(0) with process.exit(2).
+  appserverDeathHandled = true;
+  console.error(`[codex-channel] received ${signal}, shutting down...`);
+  cleanupAppserver();
+  process.exit(0);
+}
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+
 async function main() {
   preflight();
+  // 1. register on hive
   while (true) {
     try {
       await initHiveSession();
@@ -385,10 +841,14 @@ async function main() {
       await new Promise((r) => setTimeout(r, 3000));
     }
   }
+  // 2. set up codex push mode (appserver preferred, exec fallback)
+  await setupPushMode();
+  // 3. subscribe to hive SSE
   await listenSSE();
 }
 
 main().catch((err) => {
   console.error('[codex-channel] fatal:', err);
+  cleanupAppserver();
   process.exit(1);
 });