handmux 0.29.2 → 0.31.0

package/dist/src/docs.js

@@ -117,12 +117,15 @@ export function createDocs({ home, extraRoots = [], maxDownloadBytes = MAX_TRANS
         if (st.size > MAX_READ_BYTES)
             return { error: 'too large', status: 413 };
         const mtimeMs = st.mtimeMs;
+        // Filesystems without a birth time report 0 (or NaN on some platforms) — the popover shows
+        // 创建时间 only when it is a real value.
+        const birthtimeMs = Number.isFinite(st.birthtimeMs) && st.birthtimeMs > 0 ? st.birthtimeMs : null;
         if (knownMtime != null && mtimeMs === knownMtime)
             return { name: basename(real), type, mtimeMs, notModified: true };
         const content = decodeText(await fs.readFile(real));
         if (content == null)
             return { error: 'not text', status: 415 };
-        return { name: basename(real), type, content, mtimeMs };
+        return { name: basename(real), type, content, mtimeMs, size: st.size, birthtimeMs };
     }
     async function listDir(rawPath) {
         const rh = await realHomeP;
@@ -153,17 +156,28 @@ export function createDocs({ home, extraRoots = [], maxDownloadBytes = MAX_TRANS
                 fileDirents.push(d);
         }
         // stat every file IN PARALLEL — a big dir is thousands of files, and one awaited stat each
-        // (serial) is what made listing hang for seconds. Promise.all lets the OS pipeline them.
+        // (serial) is what made listing hang for seconds. Promise.all lets the OS pipeline them. The same
+        // stat carries the mtime the listing shows, so the timestamp costs no extra syscall. Dirs get one
+        // stat each (there are few) for the same timestamp; a failure just omits the field.
         const fileEntries = await Promise.all(fileDirents.map(async (d) => {
             const type = docTypeFor(d.name) ? 'doc' : imageTypeFor(d.name) ? 'image' : 'file';
-            let size = 0;
             try {
-                size = (await fs.stat(join(real, d.name))).size;
+                const st = await fs.stat(join(real, d.name));
+                return { name: d.name, type, size: st.size, mtimeMs: st.mtimeMs };
+            }
+            catch {
+                return { name: d.name, type, size: 0 }; // gone mid-list → keep the row, no size/time
+            }
+        }));
+        const dirStats = await Promise.all(dirEntries.map(async (entry) => {
+            try {
+                return { ...entry, mtimeMs: (await fs.stat(join(real, entry.name))).mtimeMs };
+            }
+            catch {
+                return entry;
             }
-            catch { /* gone mid-list → size 0 */ }
-            return { name: d.name, type, size };
         }));
-        const entries = [...dirEntries, ...fileEntries];
+        const entries = [...dirStats, ...fileEntries];
         // dirs first; files (doc+file) interleaved alphabetically
         entries.sort((a, b) => (a.type === 'dir' ? 0 : 1) - (b.type === 'dir' ? 0 : 1) || a.name.localeCompare(b.name));
         // "up" stops at whichever allowed root we're in (each root is a ceiling), not only at home.

package/dist/src/logDetail.js

@@ -0,0 +1,27 @@
+// How a log line's optional second value is rendered. It is typed as `error`, but connectors also pass a
+// bag of STRUCTURED DETAILS there ("which event id, which pane"), and rendering those with String() printed
+// `[object Object]` — an operator could not tell which event had been dropped, which is the whole reason the
+// line exists. Reported from the field as exactly that: a wall of
+// `Discarding stale Claude Hook event after pane process replacement: [object Object]`.
+//
+// An Error keeps its message; anything else object-shaped is rendered as bounded JSON so the detail stays
+// readable and a pathological value cannot flood the log. Primitives keep their plain form.
+const MAX_DETAIL = 500;
+export function logDetail(value) {
+    if (value === undefined)
+        return '';
+    if (value instanceof Error)
+        return `: ${value.message}`;
+    if (typeof value === 'object' && value !== null) {
+        try {
+            const json = JSON.stringify(value);
+            if (typeof json !== 'string')
+                return '';
+            return `: ${json.length > MAX_DETAIL ? `${json.slice(0, MAX_DETAIL)}…` : json}`;
+        }
+        catch {
+            return ''; // circular or otherwise unserializable: log the message alone rather than nothing useful
+        }
+    }
+    return `: ${String(value)}`;
+}

package/dist/src/paneInput.js

@@ -1,4 +1,5 @@
 import { assertRequestAuthority } from './requestAuthority.js';
+import { parsePendingPrompt } from './pendingPrompt.js';
 const SUBMIT_GAP_MS = 120;
 const paneInputTails = new Map();
 const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -17,6 +18,78 @@ export async function serializePaneInput(paneId, operation) {
             paneInputTails.delete(paneId);
     }
 }
+// One-line native editor, as every Claude-lineage TUI draws it: `<prompt> value` on the cursor's line with
+// a rule above and below. Wrapped input, attachments, selection menus and unknown layouts fail closed
+// (null) — the caller must never delete content it could not read. Callers send End first: placeholder text
+// is painted after the cursor but is not part of the editor, while real text leaves the cursor at its end.
+// `hint` strips a right-aligned footer the editor paints inside that same line (e.g. CodeBuddy's "↵ send").
+//
+// Trailing blanks are removed before the line is judged, because how the EMPTY editor looks is not stable:
+// Claude writes a non-breaking space after its prompt (which a capture keeps), CodeBuddy a plain one (which
+// a capture trims as a trailing blank), so a genuinely empty editor arrives as the bare prompt. Reading
+// that as unrecognizable — rather than as empty — refused every send to an idle CodeBuddy pane, and even
+// refused the step that verifies our own stale prompt had been cleared, since clearing it produces exactly
+// that line. Nothing is lost by trimming: a line that carries only the prompt cannot be hiding text, and
+// the rules above and below are what prove this line is the editor rather than a prompt character that
+// happens to sit somewhere in the transcript.
+//
+// The rule ABOVE the editor is not always bare either: Claude Code paints the session title inside it
+// (`──── my session title ─`), so a pure run of dashes rejected every send in a titled session — reported
+// from the field with per-pane captures, all of them empty editors waiting for input. It therefore accepts
+// a dash run that opens the line and closes it with the title painted between; the line BELOW stays bare,
+// which is what the same captures show (and what keeps an unrelated decorated line from pairing with the
+// prompt into a false editor box).
+const RULE_RE = /^\u2500{3,}$/;
+const TITLED_RULE_RE = /^\u2500{3,}(?:\s*\S.*\s*\u2500{1,})?$/;
+// Why a send was refused has to be diagnosable from the log alone. The editor is judged by exact geometry,
+// and when a TUI changes its decoration the reader fails closed: the phone tells the user to "handle the
+// draft in the terminal" while they look at an empty composer they cannot do anything about. That happened
+// twice in one day (an empty CodeBuddy editor arriving as the bare prompt, a Claude composer whose top rule
+// carries the session title), and both times the shape had to come from the reporter's own screen capture.
+//
+// So when — and ONLY when — the editor could not be read at all, the rows around the cursor are recorded.
+// A draft we CAN read is somebody's text and is never logged: a readable-but-foreign draft is a normal
+// refusal with a known cause and no diagnostic value.
+const DETAIL_ROWS = 3;
+const DETAIL_ROW_MAX = 120;
+const DETAIL_MAX = 600;
+export function describeEditorArea(screen, cursor, rows = DETAIL_ROWS) {
+    const lines = screen.split('\n');
+    const from = Math.max(0, cursor.cursorY - rows);
+    const to = Math.min(lines.length - 1, cursor.cursorY + rows);
+    const parts = [`cursor=(${cursor.cursorX},${cursor.cursorY})`];
+    for (let i = from; i <= to; i++) {
+        const line = lines[i] ?? '';
+        const clamped = line.length > DETAIL_ROW_MAX ? `${line.slice(0, DETAIL_ROW_MAX)}…` : line;
+        // JSON so escapes of control characters cannot break the surrounding log line.
+        parts.push(`${i}${i === cursor.cursorY ? '*' : ''}=${JSON.stringify(clamped)}`);
+    }
+    const detail = parts.join(' ');
+    return detail.length > DETAIL_MAX ? `${detail.slice(0, DETAIL_MAX)}…` : detail;
+}
+export function singleLineDraft(screen, cursor, prompt = '\u276f', hint) {
+    const lines = screen.split('\n');
+    const line = lines[cursor.cursorY];
+    if (!line || !TITLED_RULE_RE.test(lines[cursor.cursorY - 1]?.trim() ?? '')
+        || !RULE_RE.test(lines[cursor.cursorY + 1]?.trim() ?? ''))
+        return null;
+    const body = line.trimEnd();
+    if (!body.startsWith(prompt))
+        return null;
+    const rest = body.slice(prompt.length);
+    if (!rest)
+        return ''; // The prompt and nothing else: the editor is empty.
+    if (rest[0] !== ' ' && rest[0] !== '\u00a0')
+        return null;
+    const start = prompt.length + 1;
+    let value = hint ? rest.slice(1).replace(hint, '') : rest.slice(1);
+    value = value.trimEnd();
+    if (cursor.cursorX === start)
+        return ''; // Native suggestions are painted here but End does not enter them.
+    if (!value || /[\x00-\x1f\x7f]/.test(value) || cursor.cursorX <= start)
+        return null;
+    return value;
+}
 export function sendPanePrompt(commands, paneId, text, guard) {
     return serializePaneInput(paneId, async () => {
         if (guard && !await guard.validate())
@@ -31,26 +104,50 @@ export function sendPanePrompt(commands, paneId, text, guard) {
         return { nativeMutation: true };
     });
 }
-export function interruptPane(commands, paneId) {
+// Stop the pane's turn. Escape is the key BOTH providers answer to, measured one screen at a time:
+//
+//   Claude                Escape stops the turn (its TUI prints `esc to interrupt` while it is running)
+//   CodeBuddy 2.156.0     Escape stops it — `⎿ Interrupted by user`, and the running `sleep 90` was gone;
+//                         `ctrl+c` did NOT: sent mid-tool, the sleep kept running and the turn kept going.
+//                         Its published keybindings list `ctrl+c → app:interrupt`, which is what this used to
+//                         send; whatever that binding belongs to, it is not the interrupt the pane's own
+//                         footer advertises. One key for both, so there is one place to be wrong.
+export function interruptAgentPane(commands, paneId) {
     return serializePaneInput(paneId, async () => {
         await commands.exitCopyModeIfActive(paneId);
         assertRequestAuthority();
-        await commands.sendKey(paneId, 'C-c');
-    });
-}
-export function interruptClaudePane(commands, paneId) {
-    return serializePaneInput(paneId, async () => {
-        await commands.exitCopyModeIfActive(paneId);
         await commands.sendKey(paneId, 'Escape');
     });
 }
-export function sendPaneChoice(commands, paneId, choice) {
+export function sendPaneMenuChoice(commands, paneId, choice) {
     if (!/^[1-9]$/.test(choice))
         throw new TypeError('Pane choice requires a single option digit');
     return serializePaneInput(paneId, async () => {
         await commands.exitCopyModeIfActive(paneId);
         assertRequestAuthority();
-        // Menu shortcuts are key events; bracketed paste is not handled by Claude's selector.
-        await commands.sendKey(paneId, choice);
+        const target = Number(choice);
+        const readMenu = async () => parsePendingPrompt(await commands.capturePlain(paneId));
+        const menu = await readMenu();
+        if (!menu)
+            throw new Error('No menu is on the pane to answer');
+        if (!menu.options.some((option) => option.n === target)) {
+            throw new Error(`The menu does not offer option ${target}`);
+        }
+        if (menu.kind === 'permission') {
+            await commands.sendKey(paneId, choice);
+            return;
+        }
+        // The cursor is reported as the option NUMBER it sits on and every numbered row is selectable, so the
+        // distance to travel is just the difference.
+        const from = menu.cursor ?? target;
+        if (from !== target) {
+            const key = target > from ? 'Down' : 'Up';
+            for (let step = 0; step < Math.abs(target - from); step++)
+                await commands.sendKey(paneId, key);
+            if ((await readMenu())?.cursor !== target) {
+                throw new Error('The menu did not move to the chosen option');
+            }
+        }
+        await commands.sendKey(paneId, 'Enter');
     });
 }

package/dist/src/pendingPrompt.js

@@ -22,6 +22,11 @@
 // re-polling — each screen (Q1 → Q2 → review) is itself a parseable menu. Escape cancels.
 //
 // The parser ANCHORS on the ❯ cursor line, NOT a footer: the review screen has options but no footer.
+//
+// CodeBuddy's gates parse with this same reader (hookInteraction binds both providers to it). It frames a
+// tool's input in a drawn box — "│ … │" rows closed by a "╰───╯" border — so a captured gate usually has that
+// box directly above the question. The border and the rows are chrome: they are never taken as the question
+// and never scraped as the lead-in prose.
 // Cursor-selected option line: ❯ (or ›»>) then "N.".
 const CURSOR_RE = /^\s*[❯›»>]\s*\d+\.\s/;
 // Any option row: optional cursor, then "N. label".
@@ -43,7 +48,17 @@ const FOOTER_RE = /enter to select|esc to (cancel|reject)/i;
 const ACTIVITY_RE = /^\s*[✻✳✶✽⏺]\s|worked for|cogitated|crafting|cooked for|crunched for|esc to interrupt/i;
 // The input cursor ❯ leading the user's echoed prompt (above the card).
 const PROMPT_ECHO_RE = /^\s*[❯›»>]\s*\D/; // ❯ NOT followed by a digit (that would be an option)
-const isTitleBoundary = (line) => ACTIVITY_RE.test(line) || RULE_RE.test(line) || TAB_BAR_RE.test(line) || FOOTER_RE.test(line) || PROMPT_ECHO_RE.test(line);
+// A drawn box. CodeBuddy frames a tool's input in one (Write/Edit previews, diffs) and draws its own rows as
+// "│ … │", so its border and its interior are chrome rather than text — the lead-in walk used to descend into
+// one and surface an empty row plus the bottom border as the gate's context (measured on pane %5's
+// "Do you want to create ai-news-2026-09.md?" card, 2026-09-22).
+const BOX_CHARS_RE = /[\u2500-\u257F\u2580-\u259F]/;
+const BOX_ONLY_RE = /^[\s\u2500-\u257F\u2580-\u259F]+$/;
+const BOX_EDGE_RE = /^\s*[\u2502\u2503]/; // │ ┃ — the vertical edge of a drawn box
+const isBoxFrame = (line) => BOX_CHARS_RE.test(line) && BOX_ONLY_RE.test(line);
+const isBoxChrome = (line) => isBoxFrame(line) || BOX_EDGE_RE.test(line);
+const isTitleBoundary = (line) => ACTIVITY_RE.test(line) || RULE_RE.test(line) || TAB_BAR_RE.test(line) || FOOTER_RE.test(line)
+    || PROMPT_ECHO_RE.test(line) || isBoxFrame(line);
 const stripRight = (value) => String(value == null ? '' : value).replace(/\s+$/, '');
 // Strip ANSI/OSC escapes so a capture taken WITH `-e` (SGR) still parses — belt-and-suspenders even though
 // the endpoint captures plain.
@@ -61,11 +76,12 @@ function extractLeadIn(lines, fromIdx) {
     const block = [];
     let i = fromIdx;
     // Skip the chrome between the menu and the preceding text (spinner / rules / tab bar / stale footer /
-    // blanks) — but never past a ❯ prompt echo (above it is the PREVIOUS exchange, stale context) nor past a
-    // ⏺ message head (it IS the text's first line — the collect loop includes it).
+    // blanks / a tool preview box) — but never past a ❯ prompt echo (above it is the PREVIOUS exchange, stale
+    // context) nor past a ⏺ message head (it IS the text's first line — the collect loop includes it).
     while (i >= 0) {
         const line = lines[i] ?? '';
-        if (line.trim() && (!isTitleBoundary(line) || PROMPT_ECHO_RE.test(line) || MSG_MARK_RE.test(line)))
+        if (line.trim() && !isBoxChrome(line)
+            && (!isTitleBoundary(line) || PROMPT_ECHO_RE.test(line) || MSG_MARK_RE.test(line)))
             break;
         i--;
     }
@@ -77,7 +93,7 @@ function extractLeadIn(lines, fromIdx) {
             block.unshift(line.trim());
             break;
         } // the ⏺ message head: include & stop
-        if (isTitleBoundary(line))
+        if (isTitleBoundary(line) || isBoxChrome(line))
             break; // hard chrome (incl. ❯ echo): stop
         block.unshift(line.trim());
     }

package/dist/src/routes/files.js

@@ -30,7 +30,10 @@ export function fileRoutes({ docs, uploadExts, maxUploadBytes }) {
                 return res.status(out.status).json({ error: out.error });
             if (out.notModified)
                 return res.json({ name: out.name, type: out.type, mtimeMs: out.mtimeMs, notModified: true });
-            return res.json({ name: out.name, type: out.type, content: out.content, mtimeMs: out.mtimeMs });
+            return res.json({
+                name: out.name, type: out.type, content: out.content, mtimeMs: out.mtimeMs,
+                size: out.size, birthtimeMs: out.birthtimeMs,
+            });
         }
         catch (e) {
             return next(e);

package/dist/src/routes/system.js

@@ -21,7 +21,17 @@ const errorMessage = (error) => error instanceof Error ? error.message : String(
 const here = dirname(fileURLToPath(import.meta.url));
 const HOOKS_SRC = resolvePath(here, '../../hooks'); // server/hooks (bundled scripts)
 const PI_ENTRY = resolvePath(here, '../../connectors/pi/index.js');
-const WEB_AGENT_INTEGRATIONS = ['claude', 'pi'];
+// Every Agent the phone may manage here. The Web client keeps its own mirrored name list
+// (web/src/agentIntegrationApi.ts `NAMES`): adding one here without adding it there is invisible to the
+// user in the best case, and a client that insists on a FIXED set breaks its whole panel in the worst — it
+// must tolerate whatever subset this list reports. Keep the two in step, and keep the client's check
+// "whatever known rows are present", never a count.
+// `codex` is listed to be SHOWN, not managed: it has nothing to install (Handmux drives it through its own
+// App Server), so its row is read-only — 已接入 / 未安装 and no action. It therefore stays out of the
+// enableable set below, and this endpoint never becomes the thing that writes ~/.codex.
+const WEB_AGENT_INTEGRATIONS = ['claude', 'pi', 'codebuddy', 'codex'];
+// Which listed Agents the Web surface may actually install/repair. Codex is absent on purpose.
+const WEB_ENABLEABLE_INTEGRATIONS = ['claude', 'pi', 'codebuddy'];
 const FILLER_FILTER_LEVELS = ['low', 'medium', 'high'];
 const requestFillerFilter = (value) => {
     if (value === undefined)
@@ -135,7 +145,7 @@ export function systemRoutes({ commands, claudeEvents, agentRuntime, asrEnv, sho
         }
     });
     r.post('/agent-integrations/:name/enable', (req, res, next) => {
-        const name = WEB_AGENT_INTEGRATIONS.find((candidate) => candidate === req.params.name);
+        const name = WEB_ENABLEABLE_INTEGRATIONS.find((candidate) => candidate === req.params.name);
         if (!name)
             return res.status(404).json({ error: 'agent integration not found' });
         try {

package/dist/src/server.js

@@ -7,10 +7,13 @@ import { loadToken } from './auth.js';
 import { createApiRouter } from './httpApi.js';
 import { loadUploadExts } from './uploadTypes.js';
 import { createClaudeEvents } from './claudeEvents.js';
+import { createCodebuddyEvents } from './codebuddyEvents.js';
+import { logDetail } from './logDetail.js';
 import { syncHooks } from './cli/claudeHooks.js';
+import { syncHooks as syncCodebuddyHooks } from './cli/codebuddyHooks.js';
 import { syncPiExtension } from './cli/piExtension.js';
 import { removeLegacyCodexHooks } from './cli/legacyCodexHooks.js';
-import { agentRuntimeDirectoryPath, claudeStatePath, codexOutboxPath, } from './cli/state.js';
+import { agentRuntimeDirectoryPath, claudeStatePath, codebuddyStatePath, codexOutboxPath, } from './cli/state.js';
 import * as commands from './tmux/commands.js';
 import * as push from './push.js';
 import * as notifications from './notifications.js';
@@ -41,8 +44,9 @@ import { apiErrorBoundary, apiRequestContext } from './apiErrors.js';
 import { RuntimeHealth } from './healthProtocol.js';
 import { healthRoutes } from './routes/health.js';
 import { createBuiltinAgentRuntime } from './agent-runtime/builtinRuntime.js';
-import { interruptClaudePane, sendPaneChoice } from './paneInput.js';
+import { interruptAgentPane, sendPaneMenuChoice } from './paneInput.js';
 import { sendClaudePanePrompt } from './agents/claudePaneInput.js';
+import { sendCodeBuddyPanePrompt } from './agents/codebuddyPaneInput.js';
 import { createLocalAgentProcessContext, TmuxAgentPaneSource, } from './agent-runtime/tmuxRuntime.js';
 import { InboxPushProjection } from './agent-runtime/inboxPushProjection.js';
 import { defaultGit } from './git.js';
@@ -53,6 +57,7 @@ import { inspectCodexOpenRootSession } from './agents/codexOpenSession.js';
 import { CodexActivationReceiptStore } from './agents/codexActivationReceipt.js';
 import { ApiAccountService, apiAccountsPath } from './apiAccounts.js';
 import { ClaudeHookBridgeConnector } from '../connectors/claude/index.js';
+import { CodeBuddyHookBridgeConnector } from '../connectors/codebuddy/index.js';
 const here = path.dirname(fileURLToPath(import.meta.url));
 // There is ONE config source — ~/.handmux/config.json — and ONE way to run handmux: `handmux start`
 // (the CLI; `node bin/handmux.js start` from a source checkout is the same thing). The CLI resolves
@@ -176,7 +181,26 @@ try {
 catch {
     health.set('codex', 'degraded', 'codex-start-failed');
 }
-const agentPanes = new TmuxAgentPaneSource({ commands });
+// This snapshot drives Runtime reconciliation, and every reconciliation re-probes each pane it tracks: the
+// tmux read is ~13ms, but a `node` pane costs 100ms+ once ps/lsof run, so a 1s cadence burned 1-2.5
+// core-seconds per second on a 35-pane host. Nothing the UI needs comes from that frequency, so the snapshot
+// runs at 3s: an Agent starting or exiting is noticed within that window.
+const agentPanes = new TmuxAgentPaneSource({ commands, pollMs: 3_000 });
+// CodeBuddy's state file is read by the Inbox Connector below AND by the conversation lens's pane → session
+// bind, so it is resolved once here, above both.
+// A refused send is the hardest report to act on: the user sees "终端有未确认的草稿" over an editor they
+// cannot do anything about, and the shape that confused the reader exists only on that pane, in that moment.
+// Record it (bounded, and only when the editor could not be read at all — a draft we CAN read is somebody's
+// text and never reaches the log). Claude's composer carrying its session title in the top rule and an
+// empty CodeBuddy editor arriving as the bare prompt both needed a user's own capture to diagnose.
+// The wording stays factual: a refused send delivers no prompt, but the reader may still have pressed End,
+// and on the path that clears a stale prompt it deliberately sent C-u.
+function reportUnreadableEditor(label, paneId, detail) {
+    console.warn(`[handmux] Cannot read the ${label} composer, so the message was not delivered,`
+        + ` ${paneId}: ${detail}`);
+}
+const codebuddyStateFile = process.env.CODEBUDDY_STATE_FILE || codebuddyStatePath(home);
+const codebuddyEvents = createCodebuddyEvents({ stateFile: codebuddyStateFile });
 const agentProcess = createLocalAgentProcessContext();
 const agentRuntime = createBuiltinAgentRuntime({
     home,
@@ -185,13 +209,25 @@ const agentRuntime = createBuiltinAgentRuntime({
     stateDirectory: agentRuntimeDirectory,
     ...(conversationStartupBlockReason === undefined ? {} : { conversationStartupBlockReason }),
     claudeEvents: events,
+    codebuddyEvents,
+    codebuddyConversationControl: {
+        sendPrompt: (paneId, text, guard) => sendCodeBuddyPanePrompt(commands, paneId, text, () => codebuddyEvents.paneSubmittedPrompt(paneId), guard, (detail) => reportUnreadableEditor('CodeBuddy', paneId, detail)),
+        interrupt: (paneId) => interruptAgentPane(commands, paneId),
+    },
+    codebuddyInteractionControl: {
+        capturePlain: (paneId) => commands.capturePlain(paneId),
+        sendChoice: (paneId, choice) => sendPaneMenuChoice(commands, paneId, choice),
+        // A Hook `permreq` row is what lets a gate whose screen the parser cannot read still surface as a
+        // prompt with a reason instead of silence (same role it plays for Claude).
+        pendingKind: (paneId) => codebuddyEvents.paneKind(paneId) ?? null,
+    },
     claudeConversationControl: {
-        sendPrompt: (paneId, text, guard) => sendClaudePanePrompt(commands, paneId, text, () => events?.paneRestoredPrompt(paneId) ?? null, guard),
-        interrupt: (paneId) => interruptClaudePane(commands, paneId),
+        sendPrompt: (paneId, text, guard) => sendClaudePanePrompt(commands, paneId, text, () => events?.paneRestoredPrompt(paneId) ?? null, guard, (detail) => reportUnreadableEditor('Claude', paneId, detail)),
+        interrupt: (paneId) => interruptAgentPane(commands, paneId),
     },
     claudeInteractionControl: {
         capturePlain: (paneId) => commands.capturePlain(paneId),
-        sendChoice: (paneId, choice) => sendPaneChoice(commands, paneId, choice),
+        sendChoice: (paneId, choice) => sendPaneMenuChoice(commands, paneId, choice),
         pendingKind: (paneId) => events?.paneKind(paneId) ?? null,
     },
     codexApp,
@@ -219,8 +255,23 @@ const claudeInboxBridge = new ClaudeHookBridgeConnector({
     panes: agentPanes,
     process: agentProcess,
     logger: (message, error) => {
-        const detail = error === undefined
-            ? '' : `: ${error instanceof Error ? error.message : String(error)}`;
+        const detail = logDetail(error);
+        console.warn(`[handmux] ${message}${detail}`);
+    },
+});
+// CodeBuddy drives the same Hook pipeline into its own state file. Its out-of-band reconciliation — the
+// transcript read that closes a gate no Hook closes — is CodeBuddy's own (see connectors/codebuddy and
+// agents/codebuddyNativeTail.ts); the connector supplies it, so nothing is configured here.
+const codebuddyInboxBridge = new CodeBuddyHookBridgeConnector({
+    socketPath: agentRuntime.socketPath,
+    credentialFile: path.join(agentRuntimeDirectory, 'bridge-credential.json'),
+    stateDirectory: path.join(agentRuntimeDirectory, 'connectors', 'codebuddy'),
+    hookStateFile: codebuddyStateFile,
+    eventDirectory: `${codebuddyStateFile}.events`,
+    panes: agentPanes,
+    process: agentProcess,
+    logger: (message, error) => {
+        const detail = logDetail(error);
         console.warn(`[handmux] ${message}${detail}`);
     },
 });
@@ -239,6 +290,7 @@ agentRuntime.start().catch((error) => {
     }
 });
 claudeInboxBridge.start();
+codebuddyInboxBridge.start();
 workspace.start().catch(() => { });
 // Keep an already-opted-in user's Claude hooks in step with this handmux version on restart: newly-added
 // lifecycle events (e.g. SessionStart, which rebinds the 对话 lens after /clear) and a refreshed
@@ -251,6 +303,15 @@ try {
     });
 }
 catch { /* best effort — hook sync never fails startup */ }
+// The same roll-forward for an already-opted-in CodeBuddy: newly-added lifecycle events and a refreshed
+// notify script land via a plain restart. A strict no-op unless its hooks are installed.
+try {
+    syncCodebuddyHooks(home, {
+        srcDir: path.resolve(here, '../hooks'),
+        stateFile: codebuddyStateFile,
+    });
+}
+catch { /* best effort — hook sync never fails startup */ }
 // Keep an explicitly installed Pi wrapper pointed at this package version (notably across Homebrew
 // Cellar upgrades). Absent or foreign extensions are untouched; this never opts a user in silently.
 try {

package/dist/src/trimCapture.js

@@ -11,7 +11,7 @@
 // A row counts as blank only if it has no glyph AND no SGR escape. captureBackground normalizes
 // ambiguous blank rows before this step, so genuinely shaded padding carries its explicit SGR while
 // a default-background blank may be trimmed normally.
-export const MAX_TRAILING_BLANK = 3;
+export const MAX_TRAILING_BLANK = 1;
 const isBlank = (row) => row === '' || (/^[ \t]*$/.test(row) && !row.includes('\x1b'));
 export function capTrailingBlankRows(ansi, max = MAX_TRAILING_BLANK) {
     // capture-pane terminates every row with \n (including a trailing one). Peel that off so split

package/dist/src/workspace/checkpointer.js

@@ -1,9 +1,17 @@
 import { captureWorkspace } from './capture.js';
 import { detectEnvironmentChange } from './environment.js';
+import { lockOwnerLabel } from './lock.js';
 import { fingerprintSnapshot } from './schema.js';
 function sameSnapshot(left, right) {
     return fingerprintSnapshot(left) === fingerprintSnapshot(right);
 }
+function formatDuration(ms) {
+    const seconds = Math.max(0, Math.round(ms / 1000));
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.round(seconds / 60);
+    return minutes < 60 ? `${minutes}m` : `${Math.round(minutes / 60)}h`;
+}
 function snapshotEnvironment(observed) {
     return {
         id: observed.id,
@@ -13,8 +21,16 @@ function snapshotEnvironment(observed) {
 }
 async function reconcileOnce(deps, cause) {
     const handle = await deps.lock.tryAcquire({ operationId: `checkpointer:${cause}` });
-    if (!handle)
-        return { status: 'locked' };
+    if (!handle) {
+        // Report who is holding it: "locked" on its own is indistinguishable from a stuck lock, which is
+        // exactly how a blocked checkpointer stayed invisible.
+        let owner = null;
+        try {
+            owner = await deps.lock.readOwner?.() ?? null;
+        }
+        catch { /* the holder may be unreadable */ }
+        return { status: 'locked', owner };
+    }
     try {
         const observed = await deps.observeEnvironment();
         if (!observed || observed.status === 'unknown')
@@ -75,6 +91,19 @@ export function createCheckpointer({ setInterval = globalThis.setInterval, clear
     let stopPromise = null;
     let lastResult = null;
     let lastError = null;
+    let blockedSince = null;
+    let blockedOwner = null;
+    function recordResult(result) {
+        lastResult = result;
+        if (result.status !== 'locked') {
+            blockedSince = null;
+            blockedOwner = null;
+            return;
+        }
+        if (blockedSince === null)
+            blockedSince = now();
+        blockedOwner = lockOwnerLabel(result.owner);
+    }
     function launch(cause) {
         const current = reconcileOnce(deps, cause);
         running = current;
@@ -89,7 +118,7 @@ export function createCheckpointer({ setInterval = globalThis.setInterval, clear
             }
         };
         current.then((result) => {
-            lastResult = result;
+            recordResult(result);
             lastError = null;
             settled();
         }, () => {
@@ -131,6 +160,12 @@ export function createCheckpointer({ setInterval = globalThis.setInterval, clear
     const outstanding = () => (running ?? pendingConfirmation?.promise ?? null);
     return {
         reconcile,
+        // How long the writer lock has been unavailable, with whoever holds it. Null while reconciliation is
+        // free to run. Readiness cannot answer this — a restore holding the lock is legitimately "locked" and
+        // the launcher must still see the server as up — so the protection status consumes this instead.
+        blocked() {
+            return blockedSince === null ? null : { since: blockedSince, owner: blockedOwner };
+        },
         health() {
             if (stopping || stopped)
                 return { status: 'degraded', detail: 'workspace-stopped' };
@@ -142,7 +177,16 @@ export function createCheckpointer({ setInterval = globalThis.setInterval, clear
                 return { status: 'ready', detail: null };
             }
             if (lastResult.status === 'locked') {
-                return { status: 'ready', detail: 'workspace-writer-locked' };
+                // Still "ready": a restore holds this lock on purpose, and the launcher must not read that as the
+                // server being down. The detail carries the holder and the duration so a lock that never clears is
+                // diagnosable from the outside.
+                const held = blockedSince === null ? null : formatDuration(now() - blockedSince);
+                return {
+                    status: 'ready',
+                    detail: 'workspace-writer-locked'
+                        + (blockedOwner ? `: ${blockedOwner}` : '')
+                        + (held ? ` for ${held}` : ''),
+                };
             }
             return { status: 'degraded', detail: `workspace-${lastResult.status || 'unknown'}` };
         },