handmux 0.5.2 → 0.6.0

package/src/agents/scanUtils.js

@@ -0,0 +1,209 @@
+// Agent-agnostic scan/parse helpers shared by every agent driver and the orphan engine. This is the LEAF
+// layer: it imports nothing from the agent registry, so drivers (claude.js / codex.js) and the engine
+// (orphans.js) can all depend on it without an import cycle.
+//
+// Everything here is about turning `ps`/`tmux`/`lsof` output and session jsonl files into structured data;
+// none of it knows which coding agent it's looking at — the per-agent specifics (which process name, where
+// sessions live, how to resume) live in the driver descriptors that USE these helpers.
+import { execFile } from 'node:child_process';
+import { promises as fsp } from 'node:fs';
+import path from 'node:path';
+
+// Tolerant promisified execFile: resolves '' on any error (no server, missing binary, non-zero exit).
+// Detection is best-effort and must never throw the whole request.
+export function defaultRun(cmd, args) {
+  return new Promise((resolve) => {
+    execFile(cmd, args, { maxBuffer: 8 * 1024 * 1024 }, (err, stdout) => {
+      resolve(err ? '' : String(stdout));
+    });
+  });
+}
+
+// A coding-agent session id is a UUID (Claude's jsonl filename; Codex's rollout-file trailing id). Validate
+// strictly: takeover types `<bin> resume <id>` into a shell via send-keys, so a non-UUID id would be a
+// shell-injection vector.
+export const isSessionUuid = (s) =>
+  typeof s === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(s);
+
+// Strip /dev/ and fold "no controlling terminal" markers (macOS '??', Linux '?') to '' so ps ttys and
+// tmux pane_ttys compare equal: ps 'ttys010' / tmux '/dev/ttys010' → 'ttys010'; ps 'pts/3' / tmux
+// '/dev/pts/3' → 'pts/3'.
+export function normTty(t) {
+  const s = String(t || '').trim();
+  if (!s || s === '??' || s === '?' || s === '-') return '';
+  return s.replace(/^\/dev\//, '');
+}
+
+// ps `etime` (elapsed since start) → milliseconds. Formats (macOS + Linux, no spaces): "MM:SS",
+// "HH:MM:SS", "DD-HH:MM:SS". Used only to derive a startedAt for display/recognition (the "A加成"),
+// NOT for session attribution — a resumed session's process starts long after its jsonl's first event.
+export function etimeToMs(etime) {
+  const s = String(etime).trim();
+  if (!s) return 0;
+  let days = 0;
+  let rest = s;
+  const dash = s.indexOf('-');
+  if (dash >= 0) { days = Number(s.slice(0, dash)) || 0; rest = s.slice(dash + 1); }
+  let sec = 0;
+  for (const p of rest.split(':')) sec = sec * 60 + (Number(p) || 0);
+  return (days * 86400 + sec) * 1000;
+}
+
+// Parse `ps -Ao pid=,ppid=,stat=,etime=,tty=,args=` → LIVE agent processes only, each tagged with the id of
+// the FIRST driver whose `procMatch` regex matches its argv. `agents` is the driver list; a proc matching
+// none is dropped. args (last column) may contain spaces; etime has none. STOPPED (STAT 'T', a Ctrl-Z-
+// suspended job-control stack — verified real: one terminal can hold 8 suspended `claude`s) and ZOMBIE
+// ('Z') processes are dropped: they aren't active sessions to steer, and a suspended original can't write
+// its jsonl so there's nothing to race.
+export function parseAgentProcs(psOut, agents) {
+  const out = [];
+  for (const line of String(psOut).split('\n')) {
+    const m = line.match(/^\s*(\d+)\s+(\d+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(.*)$/);
+    if (!m) continue;
+    const stat = m[3];
+    if (stat[0] === 'T' || stat[0] === 'Z') continue;
+    const args = m[6].trim();
+    const agent = agents.find((a) => a.procMatch.test(args));
+    if (!agent) continue;
+    out.push({ pid: Number(m[1]), ppid: Number(m[2]), etimeMs: etimeToMs(m[4]), tty: normTty(m[5]), args, agent: agent.id });
+  }
+  return out;
+}
+
+// Parse `tmux list-panes -a -F '#{pane_tty}\t#{pane_pid}'` → the set of pane ttys and pane (shell) pids.
+export function parsePaneMembership(tmuxOut) {
+  const ttys = new Set();
+  const pids = new Set();
+  for (const line of String(tmuxOut).split('\n')) {
+    if (!line) continue;
+    const [tty, pid] = line.split('\t');
+    const nt = normTty(tty);
+    if (nt) ttys.add(nt);
+    const n = Number(pid);
+    if (n) pids.add(n);
+  }
+  return { ttys, pids };
+}
+
+// Orphan = an agent proc WITH a real controlling tty that is neither one of tmux's pane ttys nor a child of
+// a pane's shell. The tty requirement drops background/headless runs (SDK/`-p`/`exec` piped, tty '') —
+// those aren't interactive sessions a user would "take over".
+export function findOrphans(procs, membership) {
+  return procs.filter(
+    (p) => p.tty && !membership.ttys.has(p.tty) && !membership.pids.has(p.ppid),
+  );
+}
+
+// A real cwd → its ~/.claude/projects directory name. Claude replaces every non-alphanumeric char with
+// '-' (verified: '/home/user/handmux' → '-home-user-handmux'; both '/'
+// and '_' fold to '-'). The mapping is LOSSY (not reversible), so we only ever encode forward, then
+// confirm each candidate jsonl's recorded `cwd` matches before trusting it.
+export function encodeProjectDir(cwd) {
+  return String(cwd).replace(/[^A-Za-z0-9]/g, '-');
+}
+
+// Read the last `bytes` of a file (for the trailing conversation). The first line of the chunk may be
+// truncated mid-JSON — callers skip lines that don't parse.
+export async function readTail(file, bytes = 65536) {
+  const fh = await fsp.open(file, 'r');
+  try {
+    const { size } = await fh.stat();
+    const start = Math.max(0, size - bytes);
+    const len = size - start;
+    if (len <= 0) return '';
+    const buf = Buffer.alloc(len);
+    await fh.read(buf, 0, len, start);
+    return buf.toString('utf8');
+  } finally {
+    await fh.close();
+  }
+}
+
+// Read the first `bytes` of a file (the session header carries `cwd` early).
+export async function readHead(file, bytes = 65536) {
+  const fh = await fsp.open(file, 'r');
+  try {
+    const buf = Buffer.alloc(bytes);
+    const { bytesRead } = await fh.read(buf, 0, bytes, 0);
+    return buf.slice(0, bytesRead).toString('utf8');
+  } finally {
+    await fh.close();
+  }
+}
+
+// First `"cwd":"..."` anywhere in a chunk (both Claude and Codex record the session cwd early in the file).
+export function firstCwd(headText) {
+  const m = String(headText).match(/"cwd"\s*:\s*"((?:[^"\\]|\\.)*)"/);
+  if (!m) return '';
+  try { return JSON.parse(`"${m[1]}"`); } catch { return m[1]; }
+}
+
+// Pull the last user-typed message text out of a Claude jsonl tail, for a recognizable one-line label.
+// Entries are line-delimited JSON; conversational turns are type 'user' with message.role 'user', whose
+// content is either a string or an array of blocks ({type:'text',text}). Meta rows (last-prompt/ai-title/
+// mode/attachment/summary) are ignored. Scans newest-first.
+export function lastUserSnippet(tailText, max = 80) {
+  const rows = String(tailText).split('\n');
+  for (let i = rows.length - 1; i >= 0; i--) {
+    const line = rows[i].trim();
+    if (!line || line[0] !== '{') continue;
+    let d;
+    try { d = JSON.parse(line); } catch { continue; }
+    if (d.type !== 'user' || !d.message || d.message.role !== 'user') continue;
+    const c = d.message.content;
+    let text = '';
+    if (typeof c === 'string') text = c;
+    else if (Array.isArray(c)) text = c.filter((b) => b && b.type === 'text').map((b) => b.text).join(' ');
+    text = text.replace(/\s+/g, ' ').trim();
+    if (text) return text.length > max ? `${text.slice(0, max)}…` : text;
+  }
+  return '';
+}
+
+// Resolve a cwd to the newest jsonl in its ENCODED project dir whose recorded cwd matches (guards against
+// the lossy encoding colliding two real paths). This is Claude's layout (~/.claude/projects/<enc-cwd>/
+// <uuid>.jsonl); Codex has its own resolver. `snippet` extracts the last user turn (parser injected so
+// each agent's jsonl shape is handled). Returns sessionId, a busy/idle guess (mtime recency), the snippet,
+// and the last-activity timestamp; {} when the dir is absent or nothing matches.
+export async function resolveEncodedDirSession(
+  projectsDir, cwd, { busyMs = 8000, now = Date.now, snippet = lastUserSnippet } = {},
+) {
+  const dir = path.join(projectsDir, encodeProjectDir(cwd));
+  let names;
+  try { names = (await fsp.readdir(dir)).filter((n) => n.endsWith('.jsonl')); } catch { return {}; }
+  const stats = [];
+  for (const n of names) {
+    try { stats.push({ n, mtime: (await fsp.stat(path.join(dir, n))).mtimeMs }); } catch { /* gone */ }
+  }
+  stats.sort((a, b) => b.mtime - a.mtime);
+  for (const { n, mtime } of stats) {
+    const file = path.join(dir, n);
+    let head;
+    try { head = await readHead(file); } catch { continue; }
+    if (firstCwd(head) !== cwd) continue; // different real path collided onto the same dir → skip
+    let snip = '';
+    try { snip = snippet(await readTail(file)); } catch { /* best effort */ }
+    return {
+      sessionId: n.replace(/\.jsonl$/, ''),
+      state: now() - mtime < busyMs ? 'busy' : 'idle',
+      snippet: snip,
+      lastActivity: Math.round(mtime),
+    };
+  }
+  return {};
+}
+
+// A tmux session name derived from a cwd basename, kept within isValidSessionName ([A-Za-z0-9-], ≤16):
+// `<prefix>-<alnum label, ≤8>-<n>`. n disambiguates against existing sessions.
+export function takeoverSessionName(cwdLabel, n, prefix = 'cc') {
+  const base = String(cwdLabel || '').replace(/[^A-Za-z0-9]/g, '').slice(0, 8) || prefix;
+  return `${prefix}-${base}-${n}`.slice(0, 16);
+}
+
+export const isShell = (c) => /^-?(zsh|bash|sh|fish|dash|tcsh|csh|ksh)$/.test(String(c || ''));
+
+export async function lsofCwd(run, pid) {
+  const out = await run('lsof', ['-a', '-p', String(pid), '-d', 'cwd', '-Fn']);
+  for (const line of out.split('\n')) if (line[0] === 'n') return line.slice(1).trim();
+  return '';
+}

package/src/claudeEvents.js

@@ -1,6 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { getAgent } from './agents/index.js';
+import { claude } from './agents/claude.js';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 // The hook-maintained state file: ONE JSON object keyed by tmux pane id, each value the pane's latest
@@ -8,59 +10,10 @@ const here = path.dirname(fileURLToPath(import.meta.url));
 // Default lives under server/data (gitignored runtime data); override with CLAUDE_STATE_FILE.
 export const DEFAULT_STATE_FILE = process.env.CLAUDE_STATE_FILE || path.resolve(here, '../data/claude-state.json');
 
-// Build the 需要你 one-liner for a PermissionRequest, from the tool it's gating on (PermissionRequest
-// carries tool_name + tool_input, unlike the later permission_prompt Notification which only has an
-// English message).
-function permMsg(body) {
-  const t = body.tool_name;
-  if (t === 'AskUserQuestion') {
-    const q = body.tool_input && body.tool_input.questions && body.tool_input.questions[0];
-    const text = (q && (q.question || q.header)) || '';
-    return text ? `需要你回答：${text}` : '需要你回答';
-  }
-  if (t === 'ExitPlanMode') return '需要你批准计划';
-  return t ? `需要你授权：${t}` : '需要你';
-}
-
-// Build the 进行中 one-liner for a resume (PostToolUse after the user answered/approved), surfacing the
-// choice they just made — AskUserQuestion stores it in tool_input.answers, keyed by question.
-function resumeMsg(body) {
-  const a = (body.tool_input && body.tool_input.answers) || (body.tool_response && body.tool_response.answers);
-  if (a && typeof a === 'object') {
-    const picks = Object.values(a).flat().filter(Boolean).join('、');
-    if (picks) return `已答：${picks}`;
-  }
-  if (body.tool_name === 'ExitPlanMode') return '已批准计划';
-  return '';
-}
-
-// Map a hook event (src + raw Claude payload) to a notification "kind". Pure — no I/O, easy to test.
-//   stop                       → done       (turn finished; carries last message)
-//   prompt                     → working    (UserPromptSubmit; carries the prompt)
-//   end                        → end        (SessionEnd; the pane's claude is gone)
-//   notify + idle_prompt       → idle       (waited ~60s; carries the notification message)
-//   notify + permission_prompt → permission (blocked on a permission/选择 gate; carries the message)
-//   resume                     → working    (PostToolUse on AskUserQuestion/ExitPlanMode: the user just
-//                                             answered/approved → Claude is working again; un-sticks the
-//                                             pane from the `permission` state its prompt left behind, and
-//                                             carries the choice the user made, e.g. 已答：Red)
-//   permreq                    → permission (PermissionRequest: a real prompt just appeared — fires ~6s
-//                                             before the permission_prompt Notification and names the tool,
-//                                             so 需要你 shows faster and says what's being asked. Verified
-//                                             NOT to fire for auto-approved tools → no false 需要你 in auto)
-//   anything else              → null       (ignored: auth_success, elicitation_*, etc.)
-export function classifyEvent(src, body = {}) {
-  if (src === 'stop') return { kind: 'done', msg: body.last_assistant_message || '' };
-  if (src === 'prompt') return { kind: 'working', msg: body.prompt || '' };
-  if (src === 'resume') return { kind: 'working', msg: resumeMsg(body) };
-  if (src === 'permreq') return { kind: 'permission', msg: permMsg(body) };
-  if (src === 'end') return { kind: 'end' };
-  if (src === 'notify') {
-    if (body.notification_type === 'idle_prompt') return { kind: 'idle', msg: body.message || '' };
-    if (body.notification_type === 'permission_prompt') return { kind: 'permission', msg: body.message || '' };
-  }
-  return null;
-}
+// Classify a Claude hook event → inbox kind. The logic now lives in the Claude driver (agents/claude.js);
+// re-exported here because tests and callers import it by this path. Per-pane classification in getStates
+// dispatches through getAgent(entry.agent) so Codex (and future agents) classify with their own driver.
+export const classifyEvent = claude.classify;
 
 // Which display VIEW a kind pushes as — and so what the device notification fires for. permission→需要你,
 // done→已完成. 已完成 fires at the COMPLETION MOMENT (done) only. The trailing idle reminder (~60s "still
@@ -70,6 +23,14 @@ export function classifyEvent(src, body = {}) {
 const PUSH_VIEW = { permission: 'needs', done: 'done' };
 const VIEW_LABEL = { needs: '需要你', done: '已完成' };
 
+// The dedup key for a pane's current push view. `needs` is view-only: Claude signals one permission gate via
+// TWO hooks (permreq then permission_prompt) at different ts, and both must collapse to a SINGLE 需要你. But
+// `done` is ts-sensitive: each finished turn is a fresh "已完成 / 该你了". For Claude, two dones are always
+// separated by a 进行中 that re-arms the dedup anyway, so keying done by ts is equivalent; for Codex — whose
+// ONLY event is turn-complete, with no working/prompt event in between — it's what makes turn 2, 3, … push
+// instead of latching on turn 1's done forever.
+function pushKey(view, ts) { return view === 'done' ? `done:${ts}` : view; }
+
 // A 进行中 (working) is a LATCHED state: set by UserPromptSubmit, normally closed by Stop. But an ESC
 // interrupt / walk-away fires NO hook at all (verified across all 26 hook event types), so working never
 // gets closed and the blue dot would stick forever. There's no event signal for the interrupt — so we
@@ -110,9 +71,9 @@ export function createClaudeEvents({ commands, push, file = DEFAULT_STATE_FILE,
   function prime() {
     const recorded = readStateFile(file);
     for (const [pane, r] of Object.entries(recorded)) {
-      const c = r && typeof r.src === 'string' ? classifyEvent(r.src, r.payload || {}) : null;
+      const c = r && typeof r.src === 'string' ? getAgent(r.agent).classify(r.src, r.payload || {}) : null;
       const view = c ? PUSH_VIEW[c.kind] : undefined;
-      if (view) lastPushed[pane] = view; // resting 需要你/已完成 → treat as seen, don't replay
+      if (view) lastPushed[pane] = pushKey(view, r.ts); // resting 需要你/已完成 → treat as seen, don't replay
     }
   }
 
@@ -146,9 +107,12 @@ export function createClaudeEvents({ commands, push, file = DEFAULT_STATE_FILE,
 
     const out = {};
     for (const [pane, rec] of Object.entries(recorded)) {
-      const c = rec && typeof rec.src === 'string' ? classifyEvent(rec.src, rec.payload || {}) : null;
+      const agent = getAgent(rec && rec.agent);
+      const c = rec && typeof rec.src === 'string' ? agent.classify(rec.src, rec.payload || {}) : null;
       const lp = live ? live.get(pane) : null;
-      const gone = live ? (!lp || lp.cmd !== 'claude') : false;
+      // Dropped when tmux says the pane is gone or no longer running THIS agent (hard kill / crash /
+      // Ctrl-C-out with no clean-exit event). A pane keyed by a legacy entry (no agent field) → Claude.
+      const gone = live ? (!lp || !agent.procNames.includes(lp.cmd)) : false;
 
       // (1) push side-effect — runs for every pane regardless of the output filter. Push fires on entry
       // into a 需要你 (permission) / 已完成 (done) view, deduped so a stay-put doesn't re-push. The idle
@@ -158,12 +122,13 @@ export function createClaudeEvents({ commands, push, file = DEFAULT_STATE_FILE,
       if (live) {
         const kind = c ? c.kind : null;
         const view = PUSH_VIEW[kind]; // 'needs' | 'done' | undefined
+        const key = view ? pushKey(view, rec.ts) : undefined;
         if (kind === 'idle') {
           /* trailing idle reminder — no push, keep the dedup as the preceding done left it */
         } else if (gone || !view) {
           lastPushed[pane] = null; // 进行中 / 结束 / gone → re-arm for the next 需要你 / 已完成
-        } else if (lastPushed[pane] !== view && lp.session) {
-          lastPushed[pane] = view;
+        } else if (lastPushed[pane] !== key && lp.session) {
+          lastPushed[pane] = key;
           await sendPush(pane, view, c, lp);
         }
       }
@@ -181,7 +146,7 @@ export function createClaudeEvents({ commands, push, file = DEFAULT_STATE_FILE,
       }
       const loc = lp ? { session: lp.session, window: lp.window, windowName: lp.windowName } : {};
       if (allow && !allow.has(loc.session)) continue;
-      out[pane] = { ...loc, kind: c.kind, msg: c.msg || '', ts: rec.ts || 0 };
+      out[pane] = { ...loc, kind: c.kind, msg: c.msg || '', ts: rec.ts || 0, agent: agent.id };
     }
     return out;
   }

package/src/cli/cloudflared.js

@@ -5,6 +5,52 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { pocketHome } from './state.js';
+import { t } from './i18n/index.js';
+
+const fmtMB = (n) => (n / 1048576).toFixed(1);
+
+// Stream a fetch response into a Buffer, reporting progress per chunk as onProgress(received, total).
+// `total` is the content-length (0 if the server didn't send one). Falls back to arrayBuffer() when the
+// response isn't a readable stream (older/mock fetch), so callers still get the bytes.
+export async function drain(res, onProgress) {
+  const total = Number(res.headers?.get?.('content-length')) || 0;
+  if (!res.body?.getReader) {
+    const b = Buffer.from(await res.arrayBuffer());
+    onProgress?.(b.length, total || b.length);
+    return b;
+  }
+  const reader = res.body.getReader();
+  const chunks = [];
+  let received = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    const c = Buffer.from(value);
+    chunks.push(c);
+    received += c.length;
+    onProgress?.(received, total);
+  }
+  return Buffer.concat(chunks);
+}
+
+// Default progress renderer: a single \r-updated line on a TTY (throttled to ~10/s), e.g.
+// `  cloudflared  45%  (9.2/20.4 MB)`. Non-TTY (piped/logged) gets nothing — the start line already
+// announced the download and a spammy animation would just fill the log with control chars.
+function defaultProgress(out = process.stdout) {
+  if (!out.isTTY) return () => {};
+  let last = 0;
+  return (received, total) => {
+    const done = total && received >= total;
+    const now = Date.now();
+    if (!done && now - last < 100) return;
+    last = now;
+    const body = total
+      ? `${Math.floor((received / total) * 100)}%  (${fmtMB(received)}/${fmtMB(total)} MB)`
+      : `${fmtMB(received)} MB`;
+    out.write(`\r  cloudflared  ${body}   `);
+    if (done) out.write('\n');
+  };
+}
 
 // Map Node's platform/arch to cloudflared's release asset. Linux/Windows ship a bare binary; macOS
 // ships a .tgz that contains a `cloudflared` executable.
@@ -21,7 +67,7 @@ export function onPath(exec = 'cloudflared') {
   return r.status === 0 ? String(r.stdout).trim().split(/\r?\n/)[0] : null;
 }
 
-export async function resolveCloudflared(home, { which = onPath, fetchImpl, log = console } = {}) {
+export async function resolveCloudflared(home, { which = onPath, fetchImpl, log = console, progress } = {}) {
   const found = which('cloudflared');
   if (found) return found;
 
@@ -34,10 +80,10 @@ export async function resolveCloudflared(home, { which = onPath, fetchImpl, log
   if (!doFetch) throw new Error('no fetch available to download cloudflared (Node 18+ required)');
   fs.mkdirSync(dir, { recursive: true });
   const url = `https://github.com/cloudflare/cloudflared/releases/latest/download/${asset.file}`;
-  log.log?.(`  downloading cloudflared (${asset.file}) …`);
+  log.log?.(t('cf.downloading', { file: asset.file }));
   const res = await doFetch(url, { redirect: 'follow' });
   if (!res.ok) throw new Error(`cloudflared download failed: HTTP ${res.status} (${url})`);
-  const buf = Buffer.from(await res.arrayBuffer());
+  const buf = await drain(res, progress || defaultProgress(process.stdout));
 
   if (asset.archive === 'tgz') {
     const tmp = path.join(dir, asset.file);

package/src/cli/codexHooks.js

@@ -0,0 +1,125 @@
+// Install/uninstall the handmux Codex lifecycle hooks — the Codex analogue of claudeHooks.js. Codex 0.142+
+// ships a Claude-parity hook system: the SAME event names, the SAME stdin JSON payload fields (session_id,
+// cwd, hook_event_name, prompt, tool_input, last_assistant_message, stop_hook_active…), and the SAME
+// {matcher, command} registration shape. So Codex reuses handmux's Claude hook scripts verbatim — the only
+// thing that differs is WHERE they're registered (Codex's config.toml) and that we pass agent='codex' so
+// the server tags the state entry (classify + liveness dispatch through the codex driver).
+//
+// Wiring: we append a MARKED region of inline `[[hooks.EVENT]]` tables to ~/.codex/config.toml. That inline
+// form is the mechanism verified to parse (vs. a standalone hooks.json whose auto-discovery is unconfirmed).
+// Multiple `[[hooks.X]]` array-of-tables entries merge, so our blocks coexist with the user's own hooks —
+// no single-slot clobber risk (unlike the old `notify` program), hence no 'conflict' state.
+//
+// Presence is gated on the `codex` BINARY on PATH (see codexOnPath), NOT on ~/.codex existing — that dir
+// name isn't unique to Codex CLI. Because the binary (not the dir) gates us, we MAY create ~/.codex.
+import fs from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+
+// The events we register → the verb passed to handmux-notify.sh (classified by the shared Claude classifier,
+// since Codex's payloads match): UserPromptSubmit→working, Stop→done, PermissionRequest→需要你. PostToolUse
+// fires on every tool call, but its handmux-write.cjs handler for agent=codex is un-stick-ONLY (it flips a
+// pane out of 需要你 back to 进行中 after you approve, and is a no-op otherwise), so it doesn't churn.
+const CODEX_HOOK_EVENTS = [
+  { event: 'UserPromptSubmit', src: 'prompt' },
+  { event: 'Stop', src: 'stop' },
+  { event: 'PermissionRequest', src: 'permreq' },
+  { event: 'PostToolUse', src: 'resume' },
+];
+
+// Shared with Claude — the same scripts drive both (stdin payloads are identical).
+const SCRIPTS = ['handmux-notify.sh', 'handmux-write.cjs'];
+const BEGIN = '# >>> handmux codex-hooks >>>';
+const END = '# <<< handmux codex-hooks <<<';
+
+// True if an executable `codex` is resolvable on PATH. Windows adds the PATHEXT suffixes.
+function codexOnPath(env = process.env) {
+  const exts = process.platform === 'win32' ? (env.PATHEXT || '.EXE;.CMD;.BAT').split(';') : [''];
+  for (const dir of (env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      try { fs.accessSync(path.join(dir, `codex${ext}`), fs.constants.X_OK); return true; } catch { /* keep looking */ }
+    }
+  }
+  return false;
+}
+
+function codexDir(home = homedir()) { return path.join(home, '.codex'); }
+function configPath(home = homedir()) { return path.join(codexDir(home), 'config.toml'); }
+function hooksDir(home = homedir()) { return path.join(codexDir(home), 'hooks'); }
+
+// Build the marked config.toml region: one `[[hooks.EVENT]]` + `[[hooks.EVENT.hooks]]` per event, each
+// running the shared notify script with the event's verb and agent='codex'. The command path is single-
+// quoted inside a TOML basic string (JSON.stringify) so a $HOME with spaces stays safe.
+export function codexHooksBlock(home = homedir()) {
+  const notify = path.join(hooksDir(home), 'handmux-notify.sh');
+  const lines = [BEGIN, '# handmux inbox hooks for Codex — delete this whole region to disable.'];
+  for (const e of CODEX_HOOK_EVENTS) {
+    const cmd = `'${notify}' ${e.src} codex`;
+    lines.push(`[[hooks.${e.event}]]`, `[[hooks.${e.event}.hooks]]`, 'type = "command"', `command = ${JSON.stringify(cmd)}`, '');
+  }
+  lines.push(END, '');
+  return lines.join('\n');
+}
+
+// Pure: splice our marked region into config.toml text — replace an existing region in place (idempotent
+// refresh), else append after the user's content. Returns the new text.
+export function mergeCodexHooks(toml, block) {
+  const text = toml || '';
+  const b = text.indexOf(BEGIN);
+  if (b >= 0) {
+    const e = text.indexOf(END, b);
+    if (e >= 0) return text.slice(0, b) + block.replace(/\n$/, '') + text.slice(e + END.length);
+  }
+  const prefix = text && !text.endsWith('\n') ? text + '\n' : text;
+  return `${prefix}${prefix ? '\n' : ''}${block}`;
+}
+
+// Pure: remove our marked region (leaving the user's own hooks/config untouched).
+export function stripCodexHooks(toml) {
+  const text = toml || '';
+  const b = text.indexOf(BEGIN);
+  if (b < 0) return text;
+  const e = text.indexOf(END, b);
+  if (e < 0) return text;
+  return (text.slice(0, b) + text.slice(e + END.length)).replace(/\n{3,}/g, '\n\n');
+}
+
+function readConf(home) {
+  try { return fs.readFileSync(configPath(home), 'utf8'); } catch { return ''; }
+}
+
+// 'no-codex' → Codex CLI not on PATH (don't prompt). 'installed' → our region present. 'absent' → Codex
+// installed, hooks not wired.
+export function codexHooksStatus(home = homedir()) {
+  if (!codexOnPath()) return 'no-codex';
+  return readConf(home).includes(BEGIN) ? 'installed' : 'absent';
+}
+
+function writeAtomic(file, text) {
+  const tmp = `${file}.tmp`;
+  fs.writeFileSync(tmp, text);
+  fs.renameSync(tmp, file);
+}
+
+// Install (opt-in): copy the shared hook scripts into ~/.codex/hooks/, point their env at the shared state
+// file, and splice our hook region into config.toml (creating ~/.codex if needed — safe, Codex is on PATH).
+// Returns { status }: 'no-codex' (nothing to do) | 'installed'.
+export function installCodexHooks(home = homedir(), { srcDir, stateFile } = {}) {
+  if (!codexOnPath()) return { status: 'no-codex' };
+  fs.mkdirSync(hooksDir(home), { recursive: true });
+  for (const f of SCRIPTS) fs.copyFileSync(path.join(srcDir, f), path.join(hooksDir(home), f));
+  fs.chmodSync(path.join(hooksDir(home), 'handmux-notify.sh'), 0o755);
+  fs.writeFileSync(path.join(hooksDir(home), 'handmux-notify.env'), `HANDMUX_STATE=${stateFile}\n`, { mode: 0o600 });
+  writeAtomic(configPath(home), mergeCodexHooks(readConf(home), codexHooksBlock(home)));
+  return { status: 'installed' };
+}
+
+// Uninstall: strip our config.toml region and remove the copied scripts/env. Best-effort.
+export function uninstallCodexHooks(home = homedir()) {
+  if (fs.existsSync(configPath(home))) writeAtomic(configPath(home), stripCodexHooks(readConf(home)));
+  for (const f of [...SCRIPTS, 'handmux-notify.env']) {
+    try { fs.unlinkSync(path.join(hooksDir(home), f)); } catch { /* already gone */ }
+  }
+  return { status: 'absent' };
+}