handmux 0.29.2 → 0.31.0

package/dist/src/cli/agentIntegration.js

@@ -3,8 +3,10 @@ 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 { codebuddyStatePath } from './state.js';
+import { hooksHealthStatus as codebuddyHooksHealthStatus, hooksStatus as codebuddyHooksStatus, installHooks as installCodebuddyHooks, uninstallHooks as uninstallCodebuddyHooks, } from './codebuddyHooks.js';
 import { statusLineStatus, uninstallStatusLine } from './statusLine.js';
-export const AGENT_NAMES = ['codex', 'pi', 'claude'];
+export const AGENT_NAMES = ['codex', 'pi', 'claude', 'codebuddy'];
 const AGENT_NAME_SET = new Set(AGENT_NAMES);
 export function agentName(value) {
     return typeof value === 'string' && AGENT_NAME_SET.has(value) ? value : null;
@@ -37,12 +39,13 @@ export function executableOnPath(command, env = process.env, platform = process.
     }
     return false;
 }
-export function defaultAgentIntegrationContext({ home = homedir(), piEntryFile, hooksSrcDir, claudeStateFile, }) {
+export function defaultAgentIntegrationContext({ home = homedir(), piEntryFile, hooksSrcDir, claudeStateFile, codebuddyStateFile, }) {
     return {
         home,
         piEntryFile,
         hooksSrcDir,
         claudeStateFile,
+        codebuddyStateFile: codebuddyStateFile ?? codebuddyStatePath(home),
         executableAvailable: (command) => executableOnPath(command),
     };
 }
@@ -61,6 +64,16 @@ export function agentIntegrationStatus(name, context) {
             return 'needs-repair';
         return status === 'installed' ? 'ready' : 'not-enabled';
     }
+    if (name === 'codebuddy') {
+        // Same rule as Claude: PATH decides whether CodeBuddy exists, but its first run creates ~/.codebuddy.
+        // Until that directory exists the integration is not enableable, and installHooks must never create it.
+        const status = codebuddyHooksHealthStatus(context.home);
+        if (status === 'no-codebuddy')
+            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 });
@@ -97,6 +110,15 @@ export function enableAgentIntegration(name, context) {
         const status = agentIntegrationStatus(name, context);
         return { name, status, changed: installed.status === 'installed' && before !== 'ready' };
     }
+    if (name === 'codebuddy') {
+        // The same script bundle and the same state-file contract as Claude, deployed into ~/.codebuddy/hooks.
+        const installed = installCodebuddyHooks(context.home, {
+            srcDir: context.hooksSrcDir,
+            stateFile: context.codebuddyStateFile ?? codebuddyStatePath(context.home),
+        });
+        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 };
@@ -118,6 +140,13 @@ export function disableAgentIntegration(name, context) {
         uninstallStatusLine(context.home);
         return { name, status: 'not-enabled', changed };
     }
+    if (name === 'codebuddy') {
+        // CodeBuddy has no statusLine equivalent, so only its own hooks are removed — never another product's
+        // config, and never ~/.codebuddy itself.
+        const changed = codebuddyHooksStatus(context.home) === 'installed';
+        uninstallCodebuddyHooks(context.home);
+        return { name, status: 'not-enabled', changed };
+    }
     try {
         const result = uninstallPiExtension(context.home);
         return { name, status: 'not-enabled', changed: result.changed };

package/dist/src/cli/codebuddyHooks.js

@@ -0,0 +1,286 @@
+// Install/uninstall the CodeBuddy Code lifecycle hooks that feed the handmux inbox. Structurally this is
+// claudeHooks.ts again — CodeBuddy's hooks follow the Claude Code settings schema — but it is a separate
+// module on purpose: it writes another tool's config in another tool's directory, so it owns its own marker,
+// its own settings file and its own script set. One installer must never edit two products' configs.
+//
+// Iron rule: only ever touch ~/.handmux/ and — after explicit opt-in — ~/.codebuddy/. If ~/.codebuddy is
+// absent (no CodeBuddy), skip and report 'no-codebuddy'; never create it.
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { CODEBUDDY_HOOK_SET, deployHookScripts, removeHookScripts, shellWord, writeJsonAtomic, } from './hookScaffold.js';
+const NOTIFY_SCRIPT = CODEBUDDY_HOOK_SET.notify;
+const ENV_FILE = `${NOTIFY_SCRIPT.replace(/\.sh$/, '')}.env`;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const settingsOf = (value) => isRecord(value) ? { ...value } : {};
+const readSettings = (home) => {
+    try {
+        return settingsOf(JSON.parse(fs.readFileSync(settingsPath(home), 'utf8')));
+    }
+    catch {
+        return {};
+    }
+};
+// The five events the inbox reads on CodeBuddy (verified against 2.155.0). src is the argument passed to
+// handmux-codebuddy-notify.sh. No matcher: none of these are tool-scoped, so no per-tool-call hot path is
+// added — the hook only ever fires at a session/turn boundary.
+//   SessionStart binds the pane→session mapping the instant a session begins. It is also the only payload
+//   carrying CodeBuddy's transcript_path, so without it the conversation page has no session to open.
+// Keep this table in sync with ../../hooks/handmux-codebuddy-notify.sh.
+export const HOOK_EVENTS = [
+    { event: 'Stop', src: 'stop' },
+    { event: 'Notification', src: 'notify' },
+    { event: 'UserPromptSubmit', src: 'prompt' },
+    { event: 'SessionStart', src: 'start' },
+    { event: 'SessionEnd', src: 'end' },
+    // The pair that owns "需要你": PermissionRequest lights it the moment the dialog appears, and PostToolUse on
+    // the two interaction tools clears it the moment the user answers — the same events Claude installs. Without
+    // them the state stays lit after the user replies, until the turn happens to end.
+    { event: 'PostToolUse', src: 'resume', matcher: 'AskUserQuestion|ExitPlanMode' },
+    { event: 'PermissionRequest', src: 'permreq' },
+];
+// Version-gated events, mirroring Claude's: written only for a CLI new enough to emit them, pruned otherwise
+// (fail-closed when the version cannot be read). Each closes a state we would otherwise light and never turn
+// off:
+//   PreCompact  → 压缩中 while compaction runs.
+//   PostCompact → clears it the instant compaction finishes.
+//   StopFailure → a turn that died on an API error (rate limit / overload / …) fires NO Stop, so without this
+//                 the pane sticks at 进行中 forever; maps to an 'error' state.
+// `pairWith` welds the invariant "never light a state you cannot turn off": PreCompact installs only together
+// with its clearer PostCompact. minVersion is the version these were verified to exist in (2.155.0); lower it
+// only after test-firing an older build.
+const COMPACT_MIN = '2.155.0';
+export const HOOK_EVENTS_EXT = [
+    { event: 'PostCompact', src: 'compact', minVersion: COMPACT_MIN },
+    { event: 'PreCompact', src: 'compacting', minVersion: COMPACT_MIN, pairWith: 'PostCompact' },
+    { event: 'StopFailure', src: 'stopfail', minVersion: COMPACT_MIN },
+];
+const defaultVersionExec = (command, args, options) => {
+    const r = spawnSync(command, [...args], options);
+    return { status: r.status, stdout: r.stdout };
+};
+// Parse `codebuddy --version` output ("2.155.0") → { major, minor, patch } | null.
+export function parseCodeBuddyVersion(out) {
+    const m = /(\d+)\.(\d+)\.(\d+)/.exec(String(out || ''));
+    return m ? { major: Number(m[1] ?? 0), minor: Number(m[2] ?? 0), patch: Number(m[3] ?? 0) } : null;
+}
+// v >= min ("X.Y.Z"); an unknown version is always below → the gate fails closed.
+export function codeBuddyVersionAtLeast(v, minStr) {
+    if (!v)
+        return false;
+    const [a = 0, b = 0, c = 0] = String(minStr).split('.').map(Number);
+    if (v.major !== a)
+        return v.major > a;
+    if (v.minor !== b)
+        return v.minor > b;
+    return v.patch >= c;
+}
+// Detect the installed CodeBuddy version, or null when it cannot be run/parsed (→ ext events are skipped).
+export function detectCodeBuddyVersion(exec = defaultVersionExec) {
+    try {
+        for (const command of ['codebuddy', 'cbc']) {
+            const r = exec(command, ['--version'], { encoding: 'utf8', timeout: 4000 });
+            if (r && r.status === 0 && r.stdout) {
+                const parsed = parseCodeBuddyVersion(r.stdout);
+                if (parsed)
+                    return parsed;
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// Identifies OUR hooks among the user's own. Distinct from Claude's marker, so neither installer can mistake
+// the other's entries for its own even if a config directory is ever shared.
+const HOOK_MARK = NOTIFY_SCRIPT;
+const isOurHook = (value) => {
+    const hook = isRecord(value) ? value : null;
+    return typeof hook?.command === 'string' && hook.command.includes(HOOK_MARK);
+};
+const cleanGroup = (value) => {
+    if (!isRecord(value) || !Array.isArray(value.hooks))
+        return value;
+    return { ...value, hooks: value.hooks.filter((hook) => !isOurHook(hook)) };
+};
+const nonEmptyGroup = (value) => (!isRecord(value) || !Array.isArray(value.hooks) || value.hooks.length > 0);
+function dropOurHook(hooks, event) {
+    if (!Array.isArray(hooks[event]))
+        return;
+    const kept = hooks[event].map(cleanGroup).filter(nonEmptyGroup);
+    if (kept.length)
+        hooks[event] = kept;
+    else
+        delete hooks[event];
+}
+function alreadyHas(hooks, event) {
+    const groups = hooks[event];
+    return Array.isArray(groups) && groups.some((group) => (isRecord(group) && Array.isArray(group.hooks) && group.hooks.some(isOurHook)));
+}
+function ownedHookCount(hooks, event) {
+    const groups = hooks[event];
+    if (!Array.isArray(groups))
+        return 0;
+    return groups.reduce((count, group) => (count + (isRecord(group) && Array.isArray(group.hooks)
+        ? group.hooks.filter(isOurHook).length : 0)), 0);
+}
+function hasExpectedHook(hooks, event, dest) {
+    const groups = hooks[event.event];
+    const command = `${shellWord(dest)} ${event.src}`;
+    return Array.isArray(groups) && groups.some((group) => (isRecord(group)
+        && group.matcher === (event.matcher ?? '')
+        && Array.isArray(group.hooks)
+        && group.hooks.some((hook) => (isRecord(hook)
+            && hook.type === 'command'
+            && hook.command === command
+            && hook.async === true
+            && hook.timeout === 5))));
+}
+// Merge one event's hook group into `hooks` (mutates), idempotently: first remove Handmux-owned entries for
+// this event, then append the canonical destination. This repairs wrappers left by moved package installs
+// without touching any user/third-party hook that does not carry our marker.
+function addHook(hooks, e, dest) {
+    if (ownedHookCount(hooks, e.event) === 1 && hasExpectedHook(hooks, e, dest))
+        return;
+    dropOurHook(hooks, e.event);
+    const existing = hooks[e.event];
+    const groups = hooks[e.event] = Array.isArray(existing) ? [...existing] : [];
+    groups.push({
+        matcher: e.matcher ?? '',
+        hooks: [{ type: 'command', command: `${shellWord(dest)} ${e.src}`, async: true, timeout: 5 }],
+    });
+}
+// Pure: return a NEW settings object with our hooks merged into settings.hooks, idempotently, leaving
+// the user's own hooks and other keys untouched. `dest` is the absolute path to the copied notify script.
+export function mergeHooks(settings, dest, codebuddyVersion = null) {
+    const s = settingsOf(settings);
+    const hooks = isRecord(s.hooks) ? { ...s.hooks } : {};
+    for (const e of HOOK_EVENTS)
+        addHook(hooks, e, dest);
+    // Extension events: only for a CLI that emits them, and only with their clearer installed too.
+    const enabled = new Set();
+    for (const e of HOOK_EVENTS_EXT) {
+        const ok = !!e.minVersion
+            && codeBuddyVersionAtLeast(codebuddyVersion, e.minVersion)
+            && (!e.pairWith || enabled.has(e.pairWith));
+        if (ok) {
+            enabled.add(e.event);
+            addHook(hooks, e, dest);
+        }
+        else
+            dropOurHook(hooks, e.event);
+    }
+    s.hooks = hooks;
+    return s;
+}
+// Pure: return a NEW settings object with all of OUR hooks removed (uninstall). An event group that ends up
+// empty is dropped; the user's own hooks and other keys are untouched.
+export function stripHooks(settings) {
+    const s = settingsOf(settings);
+    if (!isRecord(s.hooks))
+        return s;
+    const hooks = {};
+    for (const [event, groups] of Object.entries(s.hooks)) {
+        if (!Array.isArray(groups)) {
+            hooks[event] = groups;
+            continue;
+        }
+        const kept = groups.map(cleanGroup).filter(nonEmptyGroup);
+        if (kept.length)
+            hooks[event] = kept;
+    }
+    s.hooks = hooks;
+    return s;
+}
+function codebuddyDir(home = homedir()) { return path.join(home, '.codebuddy'); }
+function settingsPath(home = homedir()) {
+    return path.join(codebuddyDir(home), 'settings.json');
+}
+function notifyDest(home = homedir()) {
+    return path.join(codebuddyDir(home), 'hooks', NOTIFY_SCRIPT);
+}
+// 'no-codebuddy' → ~/.codebuddy absent (don't prompt to enable). 'installed' → our hooks present. 'absent' →
+// CodeBuddy is here but our hooks aren't (offer to enable).
+export function hooksStatus(home = homedir()) {
+    if (!fs.existsSync(codebuddyDir(home)))
+        return 'no-codebuddy';
+    const settings = readSettings(home);
+    const hooks = isRecord(settings.hooks) ? settings.hooks : {};
+    return Object.keys(hooks).some((ev) => alreadyHas(hooks, ev)) ? 'installed' : 'absent';
+}
+function regularFile(file) {
+    try {
+        return fs.statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+// Stronger diagnostic used by `handmux agent`: any partial/old registration is repairable, not ready. Every
+// registered event and every deployed runtime file is required.
+export function hooksHealthStatus(home = homedir()) {
+    const status = hooksStatus(home);
+    if (status !== 'installed')
+        return status;
+    const hooksDir = path.join(codebuddyDir(home), 'hooks');
+    const dest = notifyDest(home);
+    const settings = readSettings(home);
+    const hooks = isRecord(settings.hooks) ? settings.hooks : {};
+    if (!HOOK_EVENTS.every((event) => (ownedHookCount(hooks, event.event) === 1 && hasExpectedHook(hooks, event, dest))))
+        return 'stale';
+    if (![dest, path.join(hooksDir, 'handmux-write.cjs'), path.join(hooksDir, ENV_FILE)].every(regularFile)) {
+        return 'stale';
+    }
+    return 'installed';
+}
+// Install (opt-in): copy the bundled hook scripts to ~/.codebuddy/hooks/, write the env pointing at the state
+// file, and merge our hooks into settings.json. NEVER creates ~/.codebuddy — if it's absent the user
+// doesn't run CodeBuddy, so we report 'no-codebuddy' and do nothing.
+//   srcDir    = the bundled hooks dir (server/hooks)
+//   stateFile = the unified ~/.handmux/codebuddy-state.json path the hook writes and the server reads
+export function installHooks(home = homedir(), { srcDir, stateFile, codebuddyVersion } = {}) {
+    if (!fs.existsSync(codebuddyDir(home)))
+        return { status: 'no-codebuddy' };
+    if (!srcDir || !stateFile)
+        throw new Error('hook srcDir and stateFile are required');
+    deployHookScripts(path.join(codebuddyDir(home), 'hooks'), srcDir, stateFile, CODEBUDDY_HOOK_SET);
+    const settings = readSettings(home);
+    const version = codebuddyVersion !== undefined ? codebuddyVersion : detectCodeBuddyVersion();
+    writeJsonAtomic(settingsPath(home), mergeHooks(settings, notifyDest(home), version));
+    return { status: 'installed' };
+}
+// Keep an ALREADY-installed user's hooks in step with this handmux version on every server start, so a plain
+// `./deploy.sh` (restart) rolls out newly-added lifecycle events and refreshed hook scripts — no phone
+// re-enable needed. Strictly opt-in-preserving: a NO-OP unless our hooks are already present ('installed').
+// It never enables hooks for a user who hasn't opted in ('absent') and never creates ~/.codebuddy
+// ('no-codebuddy'). settings.json is rewritten only when the merge actually changes it, so a steady state
+// writes nothing.
+export function syncHooks(home = homedir(), { srcDir, stateFile } = {}) {
+    const status = hooksStatus(home);
+    if (status !== 'installed')
+        return { status, changed: false };
+    if (!srcDir || !stateFile)
+        throw new Error('hook srcDir and stateFile are required');
+    deployHookScripts(path.join(codebuddyDir(home), 'hooks'), srcDir, stateFile, CODEBUDDY_HOOK_SET);
+    const dest = notifyDest(home);
+    const settings = readSettings(home);
+    const hooks = isRecord(settings.hooks) ? { ...settings.hooks } : {};
+    const before = JSON.stringify(hooks);
+    for (const e of HOOK_EVENTS)
+        addHook(hooks, e, dest); // add only MISSING events
+    const changed = JSON.stringify(hooks) !== before;
+    if (changed)
+        writeJsonAtomic(settingsPath(home), { ...settings, hooks });
+    return { status: 'installed', changed };
+}
+// Uninstall: strip our hooks from settings.json and remove the copied scripts/env. Best-effort on the file
+// deletes (a missing file is fine). Leaves ~/.codebuddy and the user's own hooks intact.
+export function uninstallHooks(home = homedir()) {
+    const settings = readSettings(home);
+    if (fs.existsSync(settingsPath(home)))
+        writeJsonAtomic(settingsPath(home), stripHooks(settings));
+    removeHookScripts(path.join(codebuddyDir(home), 'hooks'), CODEBUDDY_HOOK_SET);
+    return { status: 'absent' };
+}

package/dist/src/cli/hookScaffold.js

@@ -1,8 +1,19 @@
-// Shared IO scaffolding for the Claude Code hook installer and statusLine capturer.
+// Shared IO scaffolding for the Agent hook installers and statusLine capturer.
 import fs from 'node:fs';
 import path from 'node:path';
-export const HOOK_SCRIPTS = ['handmux-notify.sh', 'handmux-write.cjs'];
-const LEGACY_HOOK_SCRIPTS = ['handmux-codex-usage.cjs'];
+// The writer is shared by every Agent: the spool/state protocol is the Agent-independent half.
+const WRITER_SCRIPT = 'handmux-write.cjs';
+export const CLAUDE_HOOK_SET = {
+    notify: 'handmux-notify.sh',
+    eventsVar: 'HANDMUX_CLAUDE_EVENTS',
+    legacy: ['handmux-codex-usage.cjs'],
+};
+export const CODEBUDDY_HOOK_SET = {
+    notify: 'handmux-codebuddy-notify.sh',
+    eventsVar: 'HANDMUX_CODEBUDDY_EVENTS',
+};
+// `handmux-notify.sh` → `handmux-notify.env`, alongside the script so `<dir>/<name>.env` is what sh sources.
+const hookEnvName = (hookSet) => `${hookSet.notify.replace(/\.sh$/, '')}.env`;
 // Env files are sourced by /bin/sh; settings commands use the same shell word syntax.
 export const shellWord = (value) => /^[a-zA-Z0-9_./-]+$/.test(value)
     ? value : `'${value.replace(/'/g, `'"'"'`)}'`;
@@ -14,27 +25,29 @@ export function writeFileAtomic(file, text) {
     fs.renameSync(tmp, file);
 }
 export const writeJsonAtomic = (file, value) => (writeFileAtomic(file, JSON.stringify(value, null, 2)));
-// Deploy the Claude notify/write scripts into `hooksDir` and point their env at the shared state file.
-export function deployHookScripts(hooksDir, srcDir, stateFile) {
+// Deploy an Agent's notify/write scripts into `hooksDir` and point their env at the shared state file.
+export function deployHookScripts(hooksDir, srcDir, stateFile, hookSet = CLAUDE_HOOK_SET) {
     fs.mkdirSync(hooksDir, { recursive: true });
-    for (const f of HOOK_SCRIPTS)
+    for (const f of [hookSet.notify, WRITER_SCRIPT]) {
         fs.copyFileSync(path.join(srcDir, f), path.join(hooksDir, f));
-    for (const f of LEGACY_HOOK_SCRIPTS) {
+    }
+    for (const f of hookSet.legacy ?? []) {
         try {
             fs.unlinkSync(path.join(hooksDir, f));
         }
         catch { /* absent */ }
     }
-    fs.chmodSync(path.join(hooksDir, 'handmux-notify.sh'), 0o755);
-    fs.writeFileSync(path.join(hooksDir, 'handmux-notify.env'), [
+    fs.chmodSync(path.join(hooksDir, hookSet.notify), 0o755);
+    fs.writeFileSync(path.join(hooksDir, hookEnvName(hookSet)), [
         `HANDMUX_STATE=${shellWord(stateFile)}`,
-        `HANDMUX_CLAUDE_EVENTS=${shellWord(`${stateFile}.events`)}`,
+        `${hookSet.eventsVar}=${shellWord(`${stateFile}.events`)}`,
         '',
     ].join('\n'), { mode: 0o600 });
 }
 // Remove the deployed scripts + env (uninstall). Best-effort: a missing file is fine.
-export function removeHookScripts(hooksDir) {
-    for (const f of [...HOOK_SCRIPTS, ...LEGACY_HOOK_SCRIPTS, 'handmux-notify.env']) {
+export function removeHookScripts(hooksDir, hookSet = CLAUDE_HOOK_SET) {
+    const files = [hookSet.notify, WRITER_SCRIPT, hookEnvName(hookSet), ...(hookSet.legacy ?? [])];
+    for (const f of files) {
         try {
             fs.unlinkSync(path.join(hooksDir, f));
         }

package/dist/src/cli/i18n/en.js

@@ -180,7 +180,7 @@ export default {
     'agent.codexBuiltIn': '= Codex integration is built in and already ready.',
     'agent.codexDisable': 'Codex integration is built in and cannot be disabled. Run native `codex` directly to bypass Handmux.',
     'agent.unknown': 'unknown Agent: {name}',
-    'agent.usage': 'usage: handmux agent [list] | handmux agent status|enable|disable <codex|pi|claude>',
+    'agent.usage': 'usage: handmux agent [list] | handmux agent status|enable|disable <codex|pi|claude|codebuddy>',
     // Pi Extension
     'piExtension.confirmEnable': 'Enable the Pi integration with Handmux?',
     'piExtension.installed': '✓ Pi integration enabled.',

package/dist/src/cli/i18n/zh.js

@@ -179,7 +179,7 @@ export default {
     'agent.codexBuiltIn': '= Codex 接入已内置，当前已经 ready。',
     'agent.codexDisable': 'Codex 接入已内置，不能停用。若要绕过 Handmux，请直接运行原生 `codex`。',
     'agent.unknown': '未知 Agent：{name}',
-    'agent.usage': '用法:handmux agent [list] | handmux agent status|enable|disable <codex|pi|claude>',
+    'agent.usage': '用法:handmux agent [list] | handmux agent status|enable|disable <codex|pi|claude|codebuddy>',
     // Pi Extension
     'piExtension.confirmEnable': '启用 Pi 与 Handmux 的接入能力?',
     'piExtension.installed': '✓ 已启用 Pi 接入。',

package/dist/src/cli/state.js

@@ -25,6 +25,10 @@ export function agentRuntimeDirectoryPath(home) {
 // the package-internal server/data default). The CLI sets this as CLAUDE_STATE_FILE for the server child
 // and writes the same path into the hook's env, so both ends read/write one file.
 export function claudeStatePath(home) { return path.join(pocketHome(home), 'claude-state.json'); }
+// The same contract for CodeBuddy, which drives an identical Hook (state file + bounded spool) through the
+// same writer. Its own file, on the same stable per-user path: the CLI sets CODEBUDDY_STATE_FILE for the
+// server child and writes the same path into the CodeBuddy hook env, so both ends agree.
+export function codebuddyStatePath(home) { return path.join(pocketHome(home), 'codebuddy-state.json'); }
 // Push subscriptions and the dynamic-preview registry are mutable runtime data too, so they belong on the
 // same stable per-user path — NOT the package-internal server/data default, which a `npm i -g handmux`
 // reinstall replaces (silently dropping every saved subscription). The CLI injects these as PUSH_STORE /

package/dist/src/cli/supervisor.js

@@ -9,7 +9,7 @@ import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
 import { providerMode, voiceProviderRegistry } from '../asr/providerRegistry.js';
 import { getDriver } from './drivers.js';
-import { writeState, clearState, claudeStatePath, pushStorePath, previewStorePath, notificationsDirPath } from './state.js';
+import { writeState, clearState, claudeStatePath, codebuddyStatePath, pushStorePath, previewStorePath, notificationsDirPath } from './state.js';
 import { initialSupervisorComponentState, reduceSupervisorComponent, } from './supervisorState.js';
 import { probeServerReadiness } from './supervisorHealth.js';
 const here = path.dirname(fileURLToPath(import.meta.url));
@@ -121,6 +121,7 @@ export function supervise(cfg, { home, log = console, spawnChild = defaultSpawnC
             HANDMUX_HOST: cfg.host,
             HANDMUX_TOKEN: cfg.token,
             CLAUDE_STATE_FILE: claudeStatePath(home),
+            CODEBUDDY_STATE_FILE: codebuddyStatePath(home),
             PUSH_STORE: pushStorePath(home),
             PREVIEW_STORE: previewStorePath(home),
             NOTIF_DIR: notificationsDirPath(home),

package/dist/src/codebuddyEvents.js

@@ -0,0 +1,151 @@
+// The CodeBuddy Code hook-event layer: what Handmux knows that is SPECIFIC to CodeBuddy's hook events.
+//
+// CodeBuddy's hook protocol is Claude Code's (same lifecycle event names, same raw payload on stdin, same
+// shared writer + state/spool format), so this file deliberately does NOT re-implement the generic parts:
+//   - the lifecycle vocabulary and the on-disk record format come from agents/hookEvents.ts;
+//   - the state row / spool event reading is shared by the generic Connector (connectors/hookBridge.ts);
+//   - the Inbox operation/snapshot projection is the shared projectHookInbox, parameterized below.
+// What stays here is the mapping from CodeBuddy's `src` names and payload fields to the shared kind
+// language — the one thing no other provider can answer for CodeBuddy.
+//
+// There is also no legacy reader service here (unlike src/claudeEvents.ts): Claude needed one because it
+// predates Inbox Core, and a fresh Agent must NOT create a second state store — the Connector + ordered
+// projector are the only authority for CodeBuddy from day one. A `createCodebuddyEvents` service that
+// serves the conversation lens (pane → session binding, activity) is added by that slice, not this one.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { hookErrorMessage, readHookStateRows } from './agents/hookEvents.js';
+import { CodeBuddyNativeTailReader } from './agents/codebuddyNativeTail.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 same format Claude uses, in CodeBuddy's own file. The hook writes
+// it (the shared handmux-write.cjs); the server only reads it. Default lives under server/data (gitignored
+// runtime data); override with CODEBUDDY_STATE_FILE — the CLI sets that for the server child and writes the
+// same path into the hook's env, exactly like CLAUDE_STATE_FILE.
+export const DEFAULT_STATE_FILE = process.env.CODEBUDDY_STATE_FILE
+    || path.resolve(here, '../data/codebuddy-state.json');
+const record = (value) => (value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : null);
+const text = (value) => typeof value === 'string' ? value : '';
+// Build the 需要你 one-liner from the tool the gate is blocking on. CodeBuddy's PermissionRequest payload is
+// Claude-shaped, but its interactive tool set is NOT verified, so this reads only the generic tool name
+// instead of borrowing Claude's AskUserQuestion/ExitPlanMode wording — a wrong assumption there would put a
+// confident, wrong label in front of the user.
+function permissionMessage(body) {
+    const tool = text(body.tool_name);
+    return tool ? `需要你授权：${tool}` : '需要你';
+}
+// Map a CodeBuddy hook event (src + raw payload) to a notification kind. Pure — no I/O, easy to test.
+//   stop       → done       (Stop: the turn finished; carries the last assistant message)
+//   prompt     → working    (UserPromptSubmit: carries the submitted prompt)
+//   end        → end        (SessionEnd: the pane's CodeBuddy session is over → clear its projection)
+//   start      → null       (SessionStart: neutral by design — it (re)binds pane→session, including the
+//                            NEW transcript_path after /clear. A fresh/just-cleared session reads as
+//                            present, not 进行中, until its first prompt)
+//   permreq    → permission (PermissionRequest: a real gate just appeared, named by its tool)
+//   permdenied → working    (PermissionDenied: the gate is CLOSED. Like Claude's deny→tool_result→resume
+//                            path, the agent continues the turn with the denial; if the turn then ends,
+//                            Stop overrides this with done. Unverified against a live payload — the
+//                            alternative (neutral) would silently drop a running turn's card)
+//   compacting → compacting (PreCompact: a slow operation, shown as 压缩中)
+//   compact    → null       (PostCompact: compaction finished → clear 压缩中. It must not fabricate done;
+//                            Claude's equivalent clears here too, and the next real edge re-states)
+//   stopfail   → error      (StopFailure: the turn ended on an API error, so no Stop fires — this is the
+//                            only signal that closes 进行中 with a failure)
+//   notify     → permission / idle by notification_type; anything else is null (ignored noise:
+//                auth_success, elicitation_*, …) — it must never create or keep an Inbox card
+export function classifyCodeBuddy(src, rawBody = {}) {
+    const body = record(rawBody) || {};
+    if (src === 'stop')
+        return { kind: 'done', msg: text(body.last_assistant_message) };
+    if (src === 'prompt')
+        return { kind: 'working', msg: text(body.prompt) };
+    if (src === 'permreq')
+        return { kind: 'permission', msg: permissionMessage(body) };
+    // Answered or approved: back to working, carrying what the user picked so the card stops asking.
+    if (src === 'resume')
+        return { kind: 'working', msg: text(body.tool_response) };
+    if (src === 'permdenied')
+        return { kind: 'working', msg: '' };
+    if (src === 'compacting')
+        return { kind: 'compacting', msg: '' };
+    if (src === 'compact')
+        return null;
+    if (src === 'stopfail')
+        return { kind: 'error', msg: hookErrorMessage(body) };
+    if (src === 'end')
+        return { kind: 'end' };
+    if (src === 'start')
+        return null;
+    if (src === 'notify') {
+        if (body.notification_type === 'permission_prompt')
+            return { kind: 'permission', msg: text(body.message) };
+        if (body.notification_type === 'idle_prompt')
+            return { kind: 'idle', msg: text(body.message) };
+    }
+    return null;
+}
+// Which record markings are CodeBuddy's self same pipeline may read. The shared writer stamps the Agent's
+// own id on every spool file and state row, so a row carrying another provider's mark must fail closed
+// rather than be projected as CodeBuddy state. Exported here, next to the event vocabulary, because both
+// the Inbox Connector and the conversation lens's pane binding must answer it the same way.
+export function acceptsCodeBuddyAgent(agent) {
+    return agent === 'codebuddy';
+}
+// The conversation lens's pane → session bind. The hook state file records THIS pane's own session id (and
+// its transcript path, when the payload carried one), which is authoritative over any cwd→newest-file
+// guess. Returns null when hooks are off, the pane is not CodeBuddy's, or the row carries no session to
+// bind — so a lens can never open onto a session the pane was not actually running.
+export function createCodebuddyEvents({ stateFile = DEFAULT_STATE_FILE, nativeTail = new CodeBuddyNativeTailReader(), } = {}) {
+    const read = () => readHookStateRows(stateFile, acceptsCodeBuddyAgent);
+    return {
+        paneSession(paneId) {
+            const row = read().get(paneId);
+            const payload = row?.payload;
+            if (!payload)
+                return null;
+            const sessionId = typeof payload.session_id === 'string' ? payload.session_id : null;
+            const transcriptPath = typeof payload.transcript_path === 'string' ? payload.transcript_path : null;
+            if (!sessionId && !transcriptPath)
+                return null;
+            return {
+                sessionId,
+                transcriptPath,
+                cwd: typeof payload.cwd === 'string' ? payload.cwd : null,
+                agent: row?.agent ?? null,
+            };
+        },
+        // The activity the 对话 lens shows while a turn runs: the SAME classification the Inbox projects, so the
+        // typing wave and the roster row can never disagree about what the pane is doing. A caller holding a
+        // process generation gets the row only when it is still that generation's.
+        //
+        // This MUST consult the transcript reconciler, not just the row. CodeBuddy fires no Hook when the user
+        // answers a gate, so a `permreq` row keeps answering 需要你 long after the pane moved on — and the
+        // Interaction adapter's fallback turns that stale answer into a card reading 这个操作需要在终端中完成 on a
+        // pane that is simply working (measured on %5, 2026-09-21: gate answered, Bash results landing at
+        // 00:17:38/42/50/54, a card raised at each of those same seconds with the idle editor as its body).
+        // Claude cannot drift this way because its own paneKind reads the native status first.
+        paneKind(paneId, process) {
+            const row = read().get(paneId);
+            if (!row)
+                return null;
+            if (process && row.process
+                && (process.pid !== row.process.pid || process.startedAt !== row.process.startedAt))
+                return null;
+            if (nativeTail.read(row.payload, row.ts, Date.now(), row.process, row.src).status === 'busy') {
+                return 'working';
+            }
+            return classifyCodeBuddy(row.src, row.payload)?.kind ?? null;
+        },
+        // The prompt this pane last submitted, used only to recognize OUR OWN leftover in the native editor:
+        // the composer may replace that, never a draft a human typed.
+        paneSubmittedPrompt(paneId) {
+            const row = read().get(paneId);
+            if (!row || row.src !== 'prompt')
+                return null;
+            const prompt = row.payload.prompt;
+            return typeof prompt === 'string' && prompt ? prompt : null;
+        },
+    };
+}