handmux 0.23.0 → 0.25.0

package/dist/src/claudeEvents.js

@@ -0,0 +1,525 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getAgent, agentForProc } from './agents/index.js';
+import { resolveVersionedComms } from './agents/claude.js';
+import { resolveCodexComms } from './agents/codex.js';
+import { defaultRun } from './agents/scanUtils.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
+// event { ts, src, host, payload }. The hook writes it (handmux-write.js); the server only reads it.
+// 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');
+// Classify a Claude hook event → inbox kind. Re-exported because tests and callers import this path.
+export const classifyEvent = claude.classify;
+const EVENT_KINDS = new Set([
+    'done', 'working', 'permission', 'compacting', 'error', 'end', 'idle',
+]);
+const VIEW_LABEL = { needs: '需要你', done: '已完成' };
+const recordOf = (value) => value && typeof value === 'object' && !Array.isArray(value)
+    ? value : null;
+const eventKind = (value) => typeof value === 'string' && EVENT_KINDS.has(value)
+    ? value : null;
+const pushView = (kind) => kind === 'permission' ? 'needs' : kind === 'done' ? 'done' : null;
+// 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 normally
+// separated by a 进行中 that re-arms the dedup; the timestamp also protects unusual missing-start sequences.
+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
+// expire working purely by age: latched longer than this with no done/needs ⇒ no-longer-working, drop it.
+// Generous (2h) so a genuinely long-running task keeps its dot for its whole run; a real turn re-lights on
+// its next event, and a new prompt resets the clock.
+const WORKING_TTL_MS = 2 * 60 * 60 * 1000;
+// 压缩中 (compacting) clears three ways: a SUCCESSFUL compaction fires PostCompact (src 'compact' → cleared
+// the instant it finishes); a NO-OP /compact ("Not enough messages to compact") fires no PostCompact but
+// writes its <local-command-stdout> immediately, which the transcript-tail check below catches within a poll;
+// and this TTL is the ultimate backstop for a genuine crash/abort mid-compaction where neither signal comes.
+// It must stay WELL above a real compaction's duration (routinely 1-2min) so it never truncates the animation
+// of a compaction that's actually still running — real ones are cleared by PostCompact, not by this timer.
+const COMPACTING_TTL_MS = 5 * 60 * 1000;
+// A pane latched in `permission` (需要你) has NO hook event to close it when the user resolves the prompt:
+// approving a normal tool (Bash/Edit/…) doesn't hit our PostToolUse matcher (only AskUserQuestion|ExitPlanMode
+// do), and DENYING or ESC-interrupting fires no hook at all (verified across all hook events). So the prompt
+// would read 需要你 until the turn's eventual Stop — or FOREVER after an ESC, which never Stops. Detect the
+// resolution out-of-band: while the prompt is pending Claude is blocked and appends nothing to its session
+// transcript, so the transcript's mtime sits at (or before) the permission event's ts; the instant the user
+// resolves it — approve → tool_result, deny → denial result, ESC → a `[Request interrupted by user]` line —
+// the transcript grows and its mtime jumps past it. mtime beyond the event ts (+ a guard for the near-
+// simultaneous permreq/tool-write case) ⇒ resolved ⇒ drop the stale 需要你 (the pane falls back to neutral
+// process-presence). The guard must clear the gap between the tool_use write and the permreq/notification
+// firing; a real resolution always lands well beyond it (the user takes seconds to answer).
+const PERM_RESOLVED_GUARD_MS = 1500;
+// Read a transcript file's mtime in ms, or null if it's missing/unreadable (→ can't tell, keep 需要你).
+function defaultStatMtime(file) { try {
+    return fs.statSync(file).mtimeMs;
+}
+catch {
+    return null;
+} }
+// Read the LAST complete JSON line of a (possibly multi-MB) transcript, or null if unreadable. Reads only a
+// bounded tail so cost is one small read regardless of transcript size; a last line longer than the window
+// won't parse cleanly, but the only line we care to recognise (the interrupt marker) is tiny.
+function defaultReadTail(file) {
+    try {
+        const fd = fs.openSync(file, 'r');
+        try {
+            const size = fs.fstatSync(fd).size;
+            const len = Math.min(size, 65536);
+            const buf = Buffer.alloc(len);
+            fs.readSync(fd, buf, 0, len, size - len);
+            const lines = buf.toString('utf8').split('\n').filter((line) => line.trim());
+            return lines.at(-1) ?? null;
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        return null;
+    }
+}
+// Pure: has the user resolved the permission prompt recorded by `rec`, judged by its transcript mtime?
+// True only once the transcript has grown past the event ts by more than the guard. Exported for testing.
+export function permissionResolved(rec, mtimeMs, guard = PERM_RESOLVED_GUARD_MS) {
+    const ts = typeof rec.ts === 'number' && Number.isFinite(rec.ts) ? rec.ts : 0;
+    return typeof mtimeMs === 'number' && mtimeMs > ts + guard;
+}
+// Pure: once resolved, the transcript's last line tells a RESUME from an INTERRUPT. Approving (yes) or
+// denying-with-feedback appends a tool_result / Claude's next message → Claude is working again → 进行中.
+// Pressing ESC appends a `[Request interrupted by user…]` marker → the turn ended, back to idle → drop the
+// pane to neutral (null). An unparseable/absent tail is treated as a resume (clears the stale 需要你 and
+// shows active — a truncated huge last line is a big tool_result, never the tiny interrupt marker).
+export function resolvedPermissionKind(lastLine) {
+    if (isInterruptTail(lastLine))
+        return null; // ESC → neutral
+    return { kind: 'working', msg: '' }; // approve / deny → 进行中
+}
+// Pure: does a transcript's last line mark a user ESC-interrupt? Matches both the plain and the
+// "…for tool use" forms. Used to un-stick a 进行中 pane the instant the user aborts a turn.
+export function isInterruptTail(lastLine) {
+    return typeof lastLine === 'string' && /Request interrupted by user/.test(lastLine);
+}
+// Pure: does a transcript's last line mark a /compact having RESOLVED — i.e. Claude wrote the command's
+// <local-command-stdout>? A NO-OP /compact ("Not enough messages to compact") writes it IMMEDIATELY, whereas
+// a real compaction stays silent for its whole (often 1-2min) run and writes it only at the very end — the
+// same moment PostCompact already clears us. So a fresh stdout tail while still 压缩中 ⇒ the compaction is
+// over (nothing to do / done) ⇒ drop the stuck state. Recognised by the system entry's subtype or the tag.
+export function isLocalCommandStdout(lastLine) {
+    if (typeof lastLine !== 'string' || !lastLine)
+        return false;
+    try {
+        const o = recordOf(JSON.parse(lastLine));
+        if (o?.subtype === 'local_command')
+            return true;
+        const c = recordOf(o?.message)?.content;
+        if (typeof c === 'string' && /<local-command-stdout>/.test(c))
+            return true;
+    }
+    catch { /* not JSON → fall through to a raw tag match */ }
+    return /<local-command-stdout>/.test(lastLine);
+}
+// Truncate a Claude message to a notification-friendly one-liner.
+function summarize(msg) {
+    const oneLine = typeof msg === 'string' ? msg.replace(/\s+/g, ' ').trim() : '';
+    return oneLine.length > 120 ? `${oneLine.slice(0, 117)}…` : oneLine;
+}
+// Read the hook's JSON state file. Tolerant of a missing / corrupt / half-written file (returns {}),
+// never throws — the hook replaces it atomically, but a read can still land on a transient state.
+function readStateFile(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        const object = recordOf(parsed);
+        if (!object)
+            return {};
+        return Object.fromEntries(Object.entries(object).flatMap(([pane, value]) => {
+            const row = recordOf(value);
+            if (!row)
+                return [];
+            const payload = recordOf(row.payload) ?? {};
+            const record = {
+                ts: typeof row.ts === 'number' && Number.isFinite(row.ts) ? row.ts : 0,
+                src: typeof row.src === 'string' ? row.src : '',
+                payload,
+            };
+            if (Object.hasOwn(row, 'agent')) {
+                record.agent = typeof row.agent === 'string' && row.agent ? row.agent : null;
+            }
+            return [[pane, record]];
+        }));
+    }
+    catch {
+        return {};
+    }
+}
+function classification(value) {
+    const record = recordOf(value);
+    const kind = eventKind(record?.kind);
+    if (!kind)
+        return null;
+    return { kind, msg: typeof record?.msg === 'string' ? record.msg : '' };
+}
+function classifyRecord(record) {
+    if (!record.src)
+        return null;
+    // Rows predating the multi-Agent format have no `agent` and are known Claude records. An explicit
+    // unknown id is not legacy absence and must fail closed instead of borrowing Claude's classifier.
+    const agent = record.agent === undefined ? getAgent('claude') : getAgent(record.agent);
+    return classification(agent?.classify?.(record.src, record.payload));
+}
+function identifiablePanes(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((candidate) => {
+        const pane = recordOf(candidate);
+        if (!pane || typeof pane.id !== 'string')
+            return [];
+        const cmd = typeof pane.cmd === 'string' ? pane.cmd
+            : typeof pane.command === 'string' ? pane.command : '';
+        return [{
+                ...pane,
+                id: pane.id,
+                cmd,
+                tty: typeof pane.tty === 'string' ? pane.tty : '',
+            }];
+    });
+}
+function livePanes(value) {
+    return identifiablePanes(value).flatMap((pane) => (typeof pane.session === 'string' && typeof pane.window === 'string'
+        && typeof pane.windowName === 'string'
+        ? [pane] : []));
+}
+function managedStates(value) {
+    const object = recordOf(value);
+    if (!object)
+        return {};
+    return Object.fromEntries(Object.entries(object).flatMap(([pane, candidate]) => {
+        const state = recordOf(candidate);
+        if (!state)
+            return [];
+        return [[pane, {
+                    kind: eventKind(state.kind),
+                    msg: typeof state.msg === 'string' ? state.msg : '',
+                    ts: typeof state.ts === 'number' && Number.isFinite(state.ts) ? state.ts : 0,
+                    suppressPush: state.suppressPush === true,
+                }]];
+    }));
+}
+// Per-process event reader. Deps injected for testability:
+//   commands.listLivePanes() → [{ id, cmd, tty, session, window, windowName }]  (one tmux call)
+//   run(cmd, args) → stdout   (used to prove ambiguous version/node commands by real exe; default defaultRun)
+//   push.sendToSession(session, payload, {ttl, urgency, topic})
+//   file: the hook-maintained JSON state file (DEFAULT_STATE_FILE).
+// The hook is the sole writer; the server reads the file fresh on every getStates and on every file
+// change (the watcher, for push). No persisted state of our own — the file IS the persistence.
+export function createClaudeEvents({ commands, push, codexApp = null, file = DEFAULT_STATE_FILE, now = () => Date.now(), statMtime = defaultStatMtime, readTail = defaultReadTail, run = defaultRun, onStateChange = () => { }, watch = fs.watch, mkdir = fs.mkdirSync, setTimer = setTimeout, clearTimer = (handle) => clearTimeout(handle), } = {}) {
+    // Short-lived executable-identity verdicts. Each poll still checks the foreground pid signature; the
+    // cache only avoids repeating lsof while that exact process set is unchanged.
+    const commVerdicts = new Map();
+    const lastPushed = {}; // pane → 'needs' | 'done' | null  (in-process push-transition dedup, by display view)
+    // The dedup above is in-process ONLY: a restart (e.g. ./deploy.sh) wipes it while the hook's state
+    // file on disk keeps every pane's latest 需要你/已完成. Without priming, the first read after boot
+    // would see an empty dedup and re-push every resting pane — a flood of "historical" notifications on
+    // every redeploy. prime() (run from start(), before any request is served) adopts the file's current
+    // resting states as already-notified, so only transitions that happen AFTER boot push.
+    function prime() {
+        const recorded = readStateFile(file);
+        for (const [pane, r] of Object.entries(recorded)) {
+            if (r?.agent === 'codex')
+                continue; // legacy rows are never a Codex state source
+            const c = classifyRecord(r);
+            const view = c ? pushView(c.kind) : null;
+            if (view)
+                lastPushed[pane] = pushKey(view, r.ts); // resting 需要你/已完成 → treat as seen, don't replay
+        }
+    }
+    // Notify the device that a pane entered 需要你 / 已完成. Title carries the state label + session so the
+    // user can tell the two apart at a glance (the inbox shows the same label as a chip); body is the
+    // pane's one-line message, falling back to the bare label. 需要你 is high-urgency (wake the phone).
+    async function sendPush(pane, view, c, lp) {
+        const label = VIEW_LABEL[view];
+        const body = summarize(c.msg) || label;
+        const payload = { title: `${label} · ${lp.session}`, body, tag: `pane-${pane}`, data: { session: lp.session, window: lp.window, pane } };
+        // 可靠优先 TTL: a phone in Doze / briefly offline still gets the LATEST per pane when it wakes (the
+        // pane-topic collapses older ones, so no pileup). 需要你 holds for hours (you're being waited on);
+        // 已完成 ~30min (a stale "done" is less useful). A force-stopped app still can't be reached at all —
+        // that's an OS limit, not a TTL one.
+        const opts = { topic: `pane-${pane}`, ttl: view === 'needs' ? 14400 : 1800, urgency: view === 'needs' ? 'high' : 'normal' };
+        try {
+            await push?.sendToSession(lp.session, payload, opts);
+        }
+        catch { /* best effort */ }
+    }
+    async function updatePush(pane, c, ts, lp, { gone = false, suppressPush = false } = {}) {
+        const kind = c ? c.kind : null;
+        const view = pushView(kind);
+        const key = view ? pushKey(view, ts) : null;
+        if (kind === 'idle')
+            return;
+        if (gone || !view) {
+            lastPushed[pane] = null;
+        }
+        else if (suppressPush) {
+            lastPushed[pane] = key;
+        }
+        else if (lastPushed[pane] !== key && lp?.session && c) {
+            lastPushed[pane] = key;
+            await sendPush(pane, view, c, lp);
+        }
+    }
+    // Agent identity is part of pane navigation, not inbox state. Resolve it from the pane's live foreground
+    // process so the phone can choose terminal/chat during the initial /panes load instead of waiting for the
+    // slower /states reconciliation pass. Work on copies because executable corroboration normalizes `cmd`.
+    async function identifyPaneAgents(panesInput = []) {
+        const panes = identifiablePanes(panesInput);
+        try {
+            await resolveVersionedComms(panes, run, commVerdicts);
+        }
+        catch { /* exact names still work */ }
+        try {
+            await resolveCodexComms(panes, run, commVerdicts);
+        }
+        catch { /* exact names still work */ }
+        return Object.fromEntries(panes.flatMap((pane) => {
+            const agent = agentForProc(pane.cmd);
+            return agent ? [[pane.id, agent.id]] : [];
+        }));
+    }
+    // Read the state file, reconcile every recorded pane against live tmux, and in ONE pass: (1) fire push
+    // for 需要你/已完成 transitions (deduped, global — independent of any caller's session filter), and
+    // (2) build the pane→state roster the inbox shows. A pane is dropped from the roster when its latest
+    // event is `end`/unclassifiable, or when tmux says it's gone or no longer running claude (hard kill /
+    // crash / Ctrl-C-out with no SessionEnd). `allowedSessions` (session NAMES, or null) scopes only the
+    // OUTPUT — push and reconciliation run over every pane. On a tmux failure we degrade: no location, no
+    // reconciliation, no push (we'd have no session name to route to), roster returned best-effort.
+    async function _getStates(allowedSessions = null) {
+        const allow = allowedSessions == null ? null : new Set(allowedSessions);
+        const recorded = readStateFile(file);
+        let live = null;
+        let managedCodex = {};
+        try {
+            if (!commands?.listLivePanes)
+                throw new Error('tmux commands unavailable');
+            const panes = livePanes(await commands.listLivePanes());
+            const agents = await identifyPaneAgents(panes);
+            for (const pane of panes) {
+                const agent = agents[pane.id];
+                if (agent)
+                    pane.cmd = agent;
+            }
+            live = new Map(panes.map((pane) => [pane.id, pane]));
+            managedCodex = codexApp?.inboxStates
+                ? managedStates(await codexApp.inboxStates(panes)) : {};
+        }
+        catch { /* tmux down */ }
+        const out = {};
+        for (const [pane, rec] of Object.entries(recorded)) {
+            // Older Handmux versions wrote Codex events into this Claude Hook state file. Codex is now strictly
+            // App Server-backed, so even an unmanaged pane must ignore those stale rows instead of reviving an
+            // approximate status or notification.
+            if (rec?.agent === 'codex')
+                continue;
+            const agent = rec.agent === undefined ? getAgent('claude') : getAgent(rec.agent);
+            if (!agent)
+                continue;
+            let c = classifyRecord(rec);
+            // A 需要你 the user already resolved leaves no closing hook (see PERM_RESOLVED_GUARD_MS). statMtime
+            // gates the cheap "still pending" path; only once the transcript has grown past the event do we pay the
+            // bounded tail read to tell a RESUME (approve/deny → 进行中) from an INTERRUPT (ESC → neutral present).
+            if (c && c.kind === 'permission') {
+                const tp = typeof rec.payload.transcript_path === 'string' ? rec.payload.transcript_path : null;
+                if (tp && permissionResolved(rec, statMtime(tp)))
+                    c = resolvedPermissionKind(readTail(tp));
+            }
+            else if (c && c.kind === 'working') {
+                // ESC-interrupt during a turn leaves the last hook as the stale 'prompt' (working) — no Stop fires,
+                // so working would otherwise stick until WORKING_TTL_MS (2h), pinning the composer's send→stop toggle.
+                // Once the transcript has grown past the prompt event, a bounded tail read settles it: an interrupt
+                // marker → neutral (un-stick now); any other line → Claude is still producing, stay 进行中. Content is
+                // definitive so no guard window is needed; an unreadable stat/tail can't tell → keep working.
+                const tp = typeof rec.payload.transcript_path === 'string' ? rec.payload.transcript_path : null;
+                const mtime = tp ? statMtime(tp) : null;
+                if (tp && typeof mtime === 'number' && mtime > rec.ts && isInterruptTail(readTail(tp)))
+                    c = null;
+            }
+            else if (c && c.kind === 'compacting') {
+                // A no-op /compact fires no PostCompact; it writes its <local-command-stdout> at once. Once the
+                // transcript has grown past the PreCompact event and its tail is that stdout, the /compact is done
+                // (nothing to compact) → drop 压缩中. A real compaction stays silent until PostCompact, so it keeps
+                // showing for its whole run. Unreadable stat/tail → can't tell → keep 压缩中 (the TTL is the backstop).
+                const tp = typeof rec.payload.transcript_path === 'string' ? rec.payload.transcript_path : null;
+                const mtime = tp ? statMtime(tp) : null;
+                if (tp && typeof mtime === 'number' && mtime > rec.ts && isLocalCommandStdout(readTail(tp)))
+                    c = null;
+            }
+            const lp = live ? live.get(pane) : null;
+            // 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
+            // reminder that trails a done is a NO-OP: 已完成 pings at the completion moment (done) only, so the
+            // 60s "still waiting" idle neither pushes nor disturbs the dedup (the pane is still in the same
+            // resting state). working / end / gone / unclassifiable re-arm the dedup for the next entry.
+            if (live) {
+                await updatePush(pane, c, rec.ts, lp, { gone });
+            }
+            // (2) roster — drop ended / dead / claude-exited panes; resolve location from the live tmux row.
+            if (!c || c.kind === 'end' || gone)
+                continue;
+            // Expire a 进行中 latched past the TTL (an ESC-interrupt / walk-away that never got a Stop): drop it
+            // from the roster so the stuck working pane goes away. See WORKING_TTL_MS.
+            if (c.kind === 'working' && now() - (rec.ts || 0) > WORKING_TTL_MS)
+                continue;
+            if (c.kind === 'compacting' && now() - (rec.ts || 0) > COMPACTING_TTL_MS)
+                continue;
+            const loc = lp ? { session: lp.session, window: lp.window, windowName: lp.windowName } : {};
+            if (allow && (!lp || !allow.has(lp.session)))
+                continue;
+            out[pane] = { ...loc, kind: c.kind, msg: c.msg || '', ts: rec.ts || 0, agent: agent.id };
+        }
+        // App Server is the sole Codex state source. A neutral state still leaves process presence below to
+        // identify the pane as Codex without guessing its activity.
+        if (live) {
+            for (const [pane, state] of Object.entries(managedCodex)) {
+                const lp = live.get(pane);
+                if (!lp)
+                    continue;
+                const c = state.kind
+                    ? { kind: state.kind, msg: state.msg } : null;
+                await updatePush(pane, c, state.ts || 0, lp, { suppressPush: state.suppressPush });
+                if (allow && !allow.has(lp.session))
+                    continue;
+                out[pane] = {
+                    session: lp.session, window: lp.window, windowName: lp.windowName,
+                    kind: c?.kind || null, msg: c?.msg || '', ...(c ? { ts: state.ts || 0 } : {}), agent: 'codex',
+                };
+            }
+        }
+        // (3) process presence — a pane whose FOREGROUND program IS a coding agent reads as "agent here" even
+        // with no active turn on record: a fresh session that hasn't prompted yet, or one right after `/clear`
+        // (whose SessionEnd dropped its roster entry above though the agent is still running). This is what the
+        // phone's per-window agent icon and the dock's default mode key off — process liveness, not the volatile
+        // activity roster. Emitted with kind:null so the inbox (inboxRows keys off VIEW[kind]) skips it and no
+        // push fires, and with NO ts so it stays inert to the done/read high-water marks (maxTs, the seen-mark
+        // effect). An active roster entry from (2) always wins (out[id] set → skip). agentForProc matches the
+        // canonical procName (never the ambiguous 'node'), so a plain node process is not mistaken for an agent.
+        if (live) {
+            for (const lp of live.values()) {
+                if (out[lp.id])
+                    continue;
+                const a = agentForProc(lp.cmd);
+                if (!a)
+                    continue;
+                if (allow && !allow.has(lp.session))
+                    continue;
+                out[lp.id] = { session: lp.session, window: lp.window, windowName: lp.windowName, kind: null, msg: '', agent: a.id };
+            }
+        }
+        return out;
+    }
+    // Run getStates run-to-completion: the /states poll and the file-watcher both call it, and it mutates the
+    // shared `lastPushed` dedup and `await sendPush` mid-loop — overlapping runs could interleave on that state.
+    // Serialize on a tail promise so calls queue instead of racing; each caller still gets its own filtered
+    // roster (allowedSessions differs per call), and the tmux read isn't duplicated concurrently.
+    let tail = Promise.resolve();
+    function getStates(allowedSessions = null) {
+        const current = tail.then(() => _getStates(allowedSessions), () => _getStates(allowedSessions));
+        tail = current.catch(() => { });
+        return current;
+    }
+    // Watch the state file's directory (the hook replaces the file via rename, which changes the inode, so
+    // watching the file itself would go deaf after the first write — watch the dir and filter by name).
+    // On a change, re-run getStates so 需要你/已完成 push fires even when NO client is polling — that's
+    // the whole point of push (notify you while you're away). Debounced so a burst of writes pumps once.
+    let watcher = null;
+    let deb = null;
+    function start() {
+        if (watcher)
+            return;
+        prime(); // boot baseline: don't replay the file's resting 需要你/已完成 as fresh push (see prime())
+        const dir = path.dirname(file);
+        const base = path.basename(file);
+        try {
+            mkdir(dir, { recursive: true });
+        }
+        catch { /* ignore */ }
+        try {
+            watcher = watch(dir, (_evt, fname) => {
+                if (fname && String(fname) !== base)
+                    return;
+                if (deb !== null)
+                    clearTimer(deb);
+                deb = setTimer(() => {
+                    getStates()
+                        .then(() => onStateChange())
+                        .catch(() => { });
+                }, 120);
+            });
+        }
+        catch { /* fs.watch unsupported → push falls back to evaluation on each /states poll */ }
+    }
+    function stop() {
+        if (watcher) {
+            watcher.close();
+            watcher = null;
+        }
+        if (deb !== null)
+            clearTimer(deb);
+        deb = null;
+    }
+    // The chat lens's pane→session bind: the hook state file records THIS pane's exact session (session_id +
+    // transcript_path), authoritative over the terminal-side cwd→newest-jsonl guess (which collapses distinct
+    // sessions that happen to share a cwd — see transcript.js). Returns null when hooks are off / the pane
+    // isn't a Claude pane / the recorded payload carries no session info, so callers can fall back cleanly.
+    function paneSession(pane) {
+        const rec = readStateFile(file)[pane];
+        if (rec?.agent === 'codex')
+            return null;
+        const p = rec?.payload;
+        if (!p)
+            return null;
+        const transcriptPath = typeof p.transcript_path === 'string' ? p.transcript_path : null;
+        const sessionId = typeof p.session_id === 'string' ? p.session_id : null;
+        const cwd = typeof p.cwd === 'string' ? p.cwd : null;
+        if (!transcriptPath && !sessionId)
+            return null;
+        return Object.hasOwn(rec, 'agent')
+            ? { sessionId, transcriptPath, cwd, agent: rec.agent ?? null }
+            : { sessionId, transcriptPath, cwd };
+    }
+    // Agent identity is needed independently of session metadata so the chat lens chooses the matching
+    // backend (Claude transcript or Codex App Server). Untagged legacy hook rows are Claude.
+    function paneAgent(pane) {
+        const rec = readStateFile(file)[pane];
+        if (!rec || typeof rec !== 'object')
+            return null;
+        // Only absence denotes a pre-multi-Agent Claude record. Any explicit unsupported/empty identity must
+        // fail closed at this legacy boundary instead of borrowing Claude's transcript controls.
+        if (rec.agent === undefined)
+            return 'claude';
+        return rec.agent === 'claude' ? 'claude' : null;
+    }
+    function paneKind(pane) {
+        const rec = readStateFile(file)[pane];
+        if (!rec || rec.agent === 'codex')
+            return null;
+        return classifyRecord(rec)?.kind ?? null;
+    }
+    function paneCompletionToken(pane) {
+        const rec = readStateFile(file)[pane];
+        if (!rec || rec.agent === 'codex')
+            return null;
+        const kind = classifyRecord(rec)?.kind ?? null;
+        if (kind !== 'done' && kind !== 'error' && kind !== 'end' && kind !== 'idle')
+            return null;
+        return Number.isFinite(rec.ts) && rec.ts >= 0 ? `claude-completed:${rec.ts}` : null;
+    }
+    return {
+        getStates, identifyPaneAgents, start, stop, paneSession, paneAgent,
+        paneKind, paneCompletionToken,
+    };
+}

package/dist/src/cli/agentIntegration.js

@@ -0,0 +1,131 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { installPiExtension, PiExtensionInstallError, piExtensionStatus, uninstallPiExtension, } from './piExtension.js';
+import { hooksHealthStatus, hooksStatus, installHooks, uninstallHooks } from './claudeHooks.js';
+import { statusLineStatus, uninstallStatusLine } from './statusLine.js';
+export const AGENT_NAMES = ['codex', 'pi', 'claude'];
+const AGENT_NAME_SET = new Set(AGENT_NAMES);
+export function agentName(value) {
+    return typeof value === 'string' && AGENT_NAME_SET.has(value) ? value : null;
+}
+// Resolve from PATH without running the Agent. This keeps `agent status/list` read-only and avoids startup
+// output, prompts, config migrations, or other behavior an upstream CLI may attach to `--version`.
+export function executableOnPath(command, env = process.env, platform = process.platform) {
+    if (!command || command.includes('/') || command.includes('\\'))
+        return false;
+    const pathValue = env.PATH;
+    if (!pathValue)
+        return false;
+    const extensions = platform === 'win32'
+        ? String(env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';').filter(Boolean)
+        : [''];
+    for (const directory of pathValue.split(path.delimiter)) {
+        if (!directory)
+            continue;
+        for (const extension of extensions) {
+            const candidate = path.join(directory, platform === 'win32' ? `${command}${extension}` : command);
+            try {
+                const stat = fs.statSync(candidate);
+                if (stat.isFile()) {
+                    fs.accessSync(candidate, platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK);
+                    return true;
+                }
+            }
+            catch { /* keep searching */ }
+        }
+    }
+    return false;
+}
+export function defaultAgentIntegrationContext({ home = homedir(), piEntryFile, hooksSrcDir, claudeStateFile, }) {
+    return {
+        home,
+        piEntryFile,
+        hooksSrcDir,
+        claudeStateFile,
+        executableAvailable: (command) => executableOnPath(command),
+    };
+}
+export function agentIntegrationStatus(name, context) {
+    if (!context.executableAvailable(name))
+        return 'not-installed';
+    if (name === 'codex')
+        return 'ready';
+    if (name === 'claude') {
+        // PATH determines whether Claude Code itself is installed. Its first run creates ~/.claude; until then
+        // the Agent exists but the integration is not enableable, and installHooks must still never create it.
+        const status = hooksHealthStatus(context.home);
+        if (status === 'no-claude')
+            return 'not-enabled';
+        if (status === 'stale')
+            return 'needs-repair';
+        return status === 'installed' ? 'ready' : 'not-enabled';
+    }
+    let status;
+    try {
+        status = piExtensionStatus(context.home, { entryFile: context.piEntryFile });
+    }
+    catch {
+        return 'needs-repair';
+    }
+    if (status === 'installed')
+        return 'ready';
+    if (status === 'stale')
+        return 'needs-repair';
+    if (status === 'conflict')
+        return 'conflict';
+    return 'not-enabled';
+}
+// Setup may offer Claude integration only after Claude itself has initialized ~/.claude. An executable on
+// PATH without that directory is `not-enabled` for status purposes, but is not yet safely enableable.
+export function shouldOfferClaudeIntegration(context) {
+    return agentIntegrationStatus('claude', context) === 'not-enabled'
+        && hooksStatus(context.home) === 'absent';
+}
+export function enableAgentIntegration(name, context) {
+    const before = agentIntegrationStatus(name, context);
+    if (before === 'not-installed' || before === 'conflict') {
+        return { name, status: before, changed: false };
+    }
+    if (name === 'codex')
+        return { name, status: 'ready', changed: false };
+    if (name === 'claude') {
+        const installed = installHooks(context.home, {
+            srcDir: context.hooksSrcDir,
+            stateFile: context.claudeStateFile,
+        });
+        const status = agentIntegrationStatus(name, context);
+        return { name, status, changed: installed.status === 'installed' && before !== 'ready' };
+    }
+    try {
+        const result = installPiExtension(context.home, { entryFile: context.piEntryFile });
+        return { name, status: 'ready', changed: result.changed };
+    }
+    catch (error) {
+        if (error instanceof PiExtensionInstallError && error.code === 'conflict') {
+            return { name, status: 'conflict', changed: false };
+        }
+        throw error;
+    }
+}
+export function disableAgentIntegration(name, context) {
+    if (name === 'codex')
+        return { name, status: 'ready', changed: false };
+    if (name === 'claude') {
+        const changed = hooksStatus(context.home) === 'installed'
+            || statusLineStatus(context.home) === 'ours';
+        uninstallHooks(context.home);
+        uninstallStatusLine(context.home);
+        return { name, status: 'not-enabled', changed };
+    }
+    try {
+        const result = uninstallPiExtension(context.home);
+        return { name, status: 'not-enabled', changed: result.changed };
+    }
+    catch (error) {
+        if (error instanceof PiExtensionInstallError && error.code === 'conflict') {
+            return { name, status: 'conflict', changed: false };
+        }
+        throw error;
+    }
+}