handmux 0.29.2 → 0.31.0

package/dist/connectors/hookBridge.js

@@ -0,0 +1,560 @@
+// The generic Hook → LocalAgentBridge → Inbox Connector. Every Agent whose native lifecycle is delivered
+// as filesystem Hooks (Claude Code, CodeBuddy) drives the same async pipeline, so the pipeline is written
+// ONCE here and the provider supplies only a profile:
+//
+//   - agentId / label / attachmentPrefix       identity of the records this connector publishes
+//   - eventPrefix                              the prefix the shared writer stamps on the spool it reads
+//   - acceptsAgent(agent)                      which provider marking a row or spool event may carry
+//   - resolvePaneProcess(pane, context)        the pane's provider process (the lease anchor)
+//   - matchesAgentPane(pane, foreground)       the legacy-record fallback when no fingerprint was recorded
+//   - project({eventId, src, …})               the provider's src+payload → Inbox projection
+//   - nativeTail                               OPTIONAL out-of-band reconciliation (Claude only today)
+//
+// The Connector never blocks the provider: Hook subprocesses only commit files, while this owns socket
+// lifetime, per-session replacement, and durable acknowledgements.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { LocalConnectorBridgeClient } from './bridgeClient.js';
+import { HOOK_EVENT_ID_RE, canonicalInboxState, matchesHookProcess, normalizedTty, parseHookBridgeEvent, readHookStateRows, } from '../src/agents/hookEvents.js';
+const DEFAULT_SPOOL_MAX_FILES = 2_000;
+const DEFAULT_SPOOL_RETENTION_MS = 24 * 60 * 60_000;
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function message(value, max = 4096) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim();
+    if (!normalized)
+        return undefined;
+    return normalized.length <= max ? normalized : `${normalized.slice(0, max - 1)}…`;
+}
+// The provider-neutral Inbox projection: classify a Hook edge, then emit the one ordered operation plus the
+// recoverable snapshot that describes the same moment. `null` classification clears the run's Inbox item
+// (the pane stays present through process identity); a state with no event ID can never notify.
+export function projectHookInbox({ classify, eventId, src, sourceOccurredAt, payload, }) {
+    const classified = classify(src, payload);
+    const state = classified ? canonicalInboxState(classified.kind) : null;
+    const safeEventId = eventId && HOOK_EVENT_ID_RE.test(eventId) ? eventId : undefined;
+    const occurred = typeof sourceOccurredAt === 'number' && Number.isFinite(sourceOccurredAt)
+        ? sourceOccurredAt : undefined;
+    const base = {
+        ...(safeEventId === undefined ? {} : { eventId: safeEventId }),
+        ...(occurred === undefined ? {} : { sourceOccurredAt: occurred }),
+    };
+    if (!state) {
+        return {
+            operation: { kind: 'clear', ...base },
+            snapshot: { availability: 'ready' },
+        };
+    }
+    const text = message(classified?.msg);
+    const item = {
+        state,
+        ...(text === undefined ? {} : { message: text }),
+        ...((state === 'waiting' || state === 'done' || state === 'error') && safeEventId
+            ? { eventId: safeEventId } : {}),
+        ...(occurred === undefined ? {} : { sourceOccurredAt: occurred }),
+    };
+    return {
+        operation: {
+            kind: 'set',
+            ...item,
+            ...(state === 'working' && safeEventId ? { eventId: safeEventId } : {}),
+        },
+        snapshot: { availability: 'ready', current: item },
+    };
+}
+function optionalSession(payload, explicit) {
+    if (typeof explicit === 'string' && explicit.length > 0 && explicit.length <= 1024)
+        return explicit;
+    const value = payload.session_id;
+    return typeof value === 'string' && value.length > 0 && value.length <= 1024 ? value : undefined;
+}
+// The per-connection identity: a new session, or a new process generation on the same pane, is a different
+// bridge client (and a different local state file). The Agent is deliberately absent — each Connector owns
+// its own state directory, so including it would only rename every existing Claude client's file.
+function signature(paneId, sessionId, process) {
+    return JSON.stringify({
+        paneId, sessionId, pid: process.pid, startedAt: process.startedAt, tty: process.tty,
+    });
+}
+function digest(value) {
+    return crypto.createHash('sha256').update(value).digest('hex');
+}
+// A gap marker is per pane+session+process generation: confirming it must not swallow the next session's
+// gap on the same reused pane.
+function gapKey(file, event) {
+    return JSON.stringify({
+        marker: path.basename(file),
+        paneId: event.paneId,
+        sessionId: event.sessionId ?? null,
+        process: event.process ?? null,
+        eventId: event.eventId,
+    });
+}
+function candidate(profile, paneId, sessionId, process) {
+    const processRef = {
+        pid: process.pid,
+        ...(process.startedAt === undefined ? {} : { startedAt: process.startedAt }),
+        ...(process.tty === undefined ? {} : { tty: process.tty }),
+    };
+    return {
+        paneId,
+        attachmentId: `${profile.attachmentPrefix}:${digest(JSON.stringify({ paneId, process: processRef }))}`,
+        ...(sessionId === undefined ? {} : { sessionId }),
+        process: processRef,
+    };
+}
+// A record's OWN process fingerprint is the only identity a Hook record carries: the notify script read it off
+// the pane's tty when the record was written. Deciding whether the record still belongs to this pane therefore
+// does not start from the pane's foreground GROUP — while the Agent runs a tool, that group's foreground owner
+// IS the tool, so a scan names a different process (or none) from one attempt to the next. The attachment is
+// keyed by the process, so a changing answer mints a new attachment — and so a new run — on every retry, which
+// is what makes an Agent's row blink in and out of the roster, and what discarded events that carried a real
+// state change.
+//
+// The ladder is deliberately conservative: every rung rejects only on positive evidence, and a rung that
+// cannot answer hands the question to the next one.
+//   1. No fingerprint — a record from an older writer. Accept; the legacy pane check owns it.
+//   2. A tty that positively belongs to a different pane — reject. A pane's tty is its stable identity.
+//   3. A liveness probe (every production host supplies one) confirms the record's own pid: alive with the
+//      recorded start time is this generation, and the same pid with a different start time is a recycled pid
+//      — reject. The foreground group is not consulted at all, which is what removes the churn.
+//   4. No probe, or a probe that could not confirm the process (gone, or unreadable — the probe reports both
+//      the same way): compare against the pane's foreground group, exactly as before. This rung has to stay:
+//      without it a record from a dead generation could never retire, and since only one acknowledgement is
+//      ever in flight per pane it would starve that pane's live events forever.
+async function recordStillOwnsPane(fingerprint, pane, inspectProcess, foreground) {
+    if (!fingerprint)
+        return true;
+    if (fingerprint.tty && pane.tty
+        && normalizedTty(fingerprint.tty) !== normalizedTty(pane.tty))
+        return false;
+    if (inspectProcess) {
+        let alive = null;
+        try {
+            alive = await inspectProcess(fingerprint.pid);
+        }
+        catch {
+            alive = null;
+        }
+        if (alive)
+            return alive.startedAt === undefined || alive.startedAt === fingerprint.startedAt;
+    }
+    const current = await foreground();
+    return !current || matchesHookProcess(fingerprint, current);
+}
+export class HookBridgeConnector {
+    #profile;
+    #socketPath;
+    #credentialFile;
+    #stateDirectory;
+    #hookStateFile;
+    #eventDirectory;
+    #panes;
+    #process;
+    #pollMs;
+    #spoolMaxFiles;
+    #spoolRetentionMs;
+    #retryDelayMs;
+    #maxRetryDelayMs;
+    #logger;
+    #createClient;
+    #clients = new Map();
+    #confirmedGaps = new Set();
+    #pendingAcks = new Map();
+    #timer;
+    #tail = Promise.resolve();
+    #started = false;
+    #closed = false;
+    constructor({ profile, socketPath, credentialFile, stateDirectory, hookStateFile, eventDirectory, panes, process, pollMs = 250, retryDelayMs = 100, maxRetryDelayMs = 5_000, logger = () => { }, createClient = (options) => new LocalConnectorBridgeClient(options), spoolMaxFiles = DEFAULT_SPOOL_MAX_FILES, spoolRetentionMs = DEFAULT_SPOOL_RETENTION_MS, }) {
+        if (!profile || !profile.agentId || !profile.attachmentPrefix
+            || ![socketPath, credentialFile, stateDirectory, hookStateFile, eventDirectory].every(path.isAbsolute)
+            || !panes || !process || !Number.isSafeInteger(pollMs) || pollMs < 50
+            || !Number.isSafeInteger(retryDelayMs) || retryDelayMs <= 0
+            || !Number.isSafeInteger(maxRetryDelayMs) || maxRetryDelayMs < retryDelayMs
+            || !Number.isSafeInteger(spoolMaxFiles) || spoolMaxFiles <= 0
+            || !Number.isSafeInteger(spoolRetentionMs) || spoolRetentionMs <= 0) {
+            throw new TypeError(`${profile?.label ?? 'Hook'} Hook Bridge Connector requires private paths and Runtime identity sources`);
+        }
+        this.#profile = profile;
+        this.#socketPath = socketPath;
+        this.#credentialFile = credentialFile;
+        this.#stateDirectory = stateDirectory;
+        this.#hookStateFile = hookStateFile;
+        this.#eventDirectory = eventDirectory;
+        this.#panes = panes;
+        this.#process = process;
+        this.#pollMs = pollMs;
+        this.#retryDelayMs = retryDelayMs;
+        this.#maxRetryDelayMs = maxRetryDelayMs;
+        this.#spoolMaxFiles = spoolMaxFiles;
+        this.#spoolRetentionMs = spoolRetentionMs;
+        this.#logger = logger;
+        this.#createClient = createClient;
+    }
+    start() {
+        if (this.#closed)
+            throw new Error(`${this.#profile.label} Hook Bridge Connector is closed`);
+        if (this.#started)
+            return;
+        this.#started = true;
+        this.#poll();
+    }
+    reconcile() {
+        const pending = this.#tail.then(() => this.#reconcile());
+        this.#tail = pending.catch((error) => {
+            this.#logger(`${this.#profile.label} Hook Bridge reconciliation failed`, error);
+        });
+        return pending;
+    }
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#profile.nativeTail?.clear();
+        if (this.#timer)
+            clearTimeout(this.#timer);
+        this.#timer = undefined;
+        for (const tracked of this.#clients.values())
+            tracked.client.close();
+        this.#clients.clear();
+        await this.#tail.catch(() => { });
+        for (const tracked of this.#clients.values())
+            tracked.client.close();
+        this.#clients.clear();
+        await Promise.allSettled([...this.#pendingAcks.values()].map((pending) => pending.promise));
+    }
+    #poll() {
+        if (this.#closed)
+            return;
+        void this.reconcile().catch(() => { }).finally(() => {
+            if (this.#closed)
+                return;
+            this.#timer = setTimeout(() => this.#poll(), this.#pollMs);
+            this.#timer.unref?.();
+        });
+    }
+    #eventFiles() {
+        try {
+            return fs.readdirSync(this.#eventDirectory)
+                .filter((name) => /^(event-\d+-\d+|gap-[a-f0-9]+)\.json$/.test(name))
+                .sort((first, second) => {
+                const firstGap = first.startsWith('gap-');
+                const secondGap = second.startsWith('gap-');
+                return firstGap === secondGap ? first.localeCompare(second) : firstGap ? -1 : 1;
+            })
+                .map((name) => path.join(this.#eventDirectory, name));
+        }
+        catch {
+            return [];
+        }
+    }
+    // Retention for Hook source files that never reach an acknowledgement: a pane that is gone, a client
+    // that never drains, or a durable publish that keeps failing leaves its file behind, and every poll
+    // re-reads it — an observed 170k files over nine days. Files are listed oldest-first, so a cap drops
+    // the stuck ones and an age window only ever expires files no one is waiting on. `gap-*` markers are
+    // not touched: they are bounded by pane/session and carry a degradation signal until confirmed.
+    #pruneSpool(files) {
+        const events = files.filter((file) => path.basename(file).startsWith('event-'));
+        if (events.length === 0)
+            return files;
+        const now = Date.now();
+        const dropped = new Set();
+        for (const [index, file] of events.entries()) {
+            const beyondCap = this.#spoolMaxFiles > 0 && index < events.length - this.#spoolMaxFiles;
+            let expired = false;
+            try {
+                expired = now - fs.statSync(file).mtimeMs > this.#spoolRetentionMs;
+            }
+            catch { /* removed */ }
+            if (beyondCap || expired)
+                dropped.add(file);
+        }
+        if (dropped.size === 0)
+            return files;
+        for (const file of dropped) {
+            try {
+                fs.unlinkSync(file);
+            }
+            catch { /* concurrently removed */ }
+        }
+        this.#logger?.(`Dropped ${this.#profile.label} Hook source files that could not be delivered`, { dropped: dropped.size, remaining: events.length - dropped.size });
+        return files.filter((file) => !dropped.has(file));
+    }
+    // The pane's provider process — the lease anchor the Connector publishes and the identity every recorded
+    // Hook edge must belong to. Profiles that prove a non-leaf anchor override it; the rest use the leaf.
+    #inspectPane(pane) {
+        return this.#profile.resolvePaneProcess
+            ? this.#profile.resolvePaneProcess(pane, this.#process)
+            : this.#process.inspectForeground(pane);
+    }
+    async #reconcile() {
+        if (this.#closed)
+            return;
+        const profile = this.#profile;
+        let panes;
+        try {
+            panes = await this.#panes.list();
+        }
+        catch {
+            return;
+        }
+        const paneMap = new Map(panes.map((pane) => [pane.paneId, pane]));
+        const identities = new Map();
+        const identity = (pane) => {
+            let pending = identities.get(pane.paneId);
+            if (!pending) {
+                pending = this.#inspectPane(pane);
+                identities.set(pane.paneId, pending);
+            }
+            return pending;
+        };
+        const events = [];
+        for (const eventFile of this.#pruneSpool(this.#eventFiles())) {
+            let event = null;
+            try {
+                const stat = fs.lstatSync(eventFile);
+                if (stat.isFile()) {
+                    event = parseHookBridgeEvent(JSON.parse(fs.readFileSync(eventFile, 'utf8')), (agent) => profile.acceptsAgent(agent));
+                }
+            }
+            catch { /* partial/removed file */ }
+            if (event)
+                events.push({ file: eventFile, event });
+        }
+        const state = readHookStateRows(this.#hookStateFile, (agent) => profile.acceptsAgent(agent));
+        for (const [paneId, pending] of this.#pendingAcks) {
+            const pane = paneMap.get(paneId);
+            const latest = state.get(paneId);
+            const latestSession = latest ? optionalSession(latest.payload) : undefined;
+            const anchor = latest?.process;
+            const replacedSession = anchor && latestSession && pending.sessionId && latestSession !== pending.sessionId;
+            const generationMoved = !!anchor && !matchesHookProcess(anchor, pending.process);
+            if (replacedSession || !pane || generationMoved
+                || !await recordStillOwnsPane(anchor, pane, this.#process.inspectProcess, () => identity(pane))) {
+                pending.client.close();
+            }
+        }
+        const gaps = new Map();
+        const activeGapKeys = new Set(events.flatMap(({ file, event }) => (event.type === 'gap' ? [gapKey(file, event)] : [])));
+        for (const key of this.#confirmedGaps) {
+            if (!activeGapKeys.has(key))
+                this.#confirmedGaps.delete(key);
+        }
+        for (const { file: eventFile, event } of events) {
+            if (event.type !== 'gap')
+                continue;
+            const pane = paneMap.get(event.paneId);
+            if (!pane)
+                continue;
+            if (!await recordStillOwnsPane(event.process, pane, this.#process.inspectProcess, () => identity(pane))) {
+                this.#logger(`Discarding stale ${profile.label} Hook event after pane process replacement`, {
+                    eventId: event.eventId,
+                    paneId: event.paneId,
+                });
+                try {
+                    fs.unlinkSync(eventFile);
+                }
+                catch { /* concurrently removed */ }
+                continue;
+            }
+            const foreground = event.process ?? (await identity(pane));
+            if (!foreground)
+                continue;
+            if (!event.process && !profile.matchesAgentPane(pane, foreground))
+                continue;
+            const latest = state.get(event.paneId);
+            const latestSession = latest ? optionalSession(latest.payload) : undefined;
+            const gapSession = optionalSession(event.payload ?? {}, event.sessionId);
+            if (latestSession && gapSession && latestSession !== gapSession) {
+                try {
+                    fs.unlinkSync(eventFile);
+                }
+                catch { /* replaced session already retired the gap */ }
+                continue;
+            }
+            gaps.set(event.paneId, { event, key: gapKey(eventFile, event) });
+        }
+        const currentStatePanes = new Set();
+        const currentNativeSessions = new Set();
+        const persistedSnapshots = new Map();
+        for (const [paneId, row] of state) {
+            const pane = paneMap.get(paneId);
+            if (!pane)
+                continue;
+            // Same rule as the published events: the row's own fingerprint decides, and a row is only skipped when
+            // that fingerprint is positively a different process generation. Skipping it because a foreground scan
+            // disagreed is what made a live pane's state vanish.
+            if (!await recordStillOwnsPane(row.process, pane, this.#process.inspectProcess, () => identity(pane)))
+                continue;
+            const foreground = row.process ?? (await identity(pane));
+            if (!foreground)
+                continue;
+            if (!row.process && !profile.matchesAgentPane(pane, foreground))
+                continue;
+            currentStatePanes.add(paneId);
+            // A cancelled old-session ACK settles asynchronously; switch clients once it has released the pane.
+            const sessionId = optionalSession(row.payload);
+            if (sessionId && row.src !== 'end')
+                currentNativeSessions.add(sessionId);
+            const pending = this.#pendingAcks.get(paneId);
+            if (pending && pending.sessionId !== sessionId)
+                continue;
+            const eventId = row.sequence === undefined ? undefined : `${profile.eventPrefix}-${row.sequence}`;
+            const projection = profile.project({
+                ...(eventId === undefined ? {} : { eventId }),
+                src: row.src,
+                sourceOccurredAt: row.ts,
+                payload: row.payload,
+            });
+            if (row.src !== 'end') {
+                const native = profile.nativeTail?.read(row.payload, row.ts, Date.now(), row.process, row.src);
+                if (native?.settled)
+                    projection.snapshot = { availability: 'ready' };
+                else if (native?.status === 'busy' || native?.status === 'waiting') {
+                    projection.snapshot = { availability: 'ready', current: {
+                            state: native.status === 'busy' ? 'working' : 'waiting',
+                            eventId: native.statusEventId,
+                        } };
+                }
+                else if (native?.status === 'unknown')
+                    projection.snapshot = { availability: 'unavailable' };
+            }
+            const snapshot = gaps.has(paneId) && projection.snapshot.availability !== 'unavailable' ? {
+                ...projection.snapshot,
+                availability: 'degraded',
+                message: `${profile.label} Hook event history is incomplete`,
+            } : projection.snapshot;
+            persistedSnapshots.set(paneId, this.#client(paneId, sessionId, foreground).setSnapshot('inbox', {
+                ...snapshot,
+                ...(row.process && row.sequence !== undefined ? { sourceSequence: row.sequence } : {}),
+            }));
+        }
+        profile.nativeTail?.retain(currentNativeSessions);
+        const liveAgentPanes = new Set(currentStatePanes);
+        for (const pane of panes) {
+            if (currentStatePanes.has(pane.paneId))
+                continue;
+            const foreground = await identity(pane);
+            if (!foreground || !profile.matchesAgentPane(pane, foreground))
+                continue;
+            liveAgentPanes.add(pane.paneId);
+            if (this.#pendingAcks.has(pane.paneId))
+                continue;
+            const gap = gaps.get(pane.paneId)?.event;
+            const sessionId = gap ? optionalSession(gap.payload ?? {}, gap.sessionId) : undefined;
+            persistedSnapshots.set(pane.paneId, this.#client(pane.paneId, sessionId, foreground).setSnapshot('inbox', gap ? {
+                availability: 'degraded',
+                message: `${profile.label} Hook event history is incomplete`,
+            } : { availability: 'ready' }));
+        }
+        for (const { file: eventFile, event } of events) {
+            const gap = event.type === 'gap' ? gaps.get(event.paneId) : undefined;
+            if (event.type === 'gap' && gap?.event !== event)
+                continue;
+            const pane = paneMap.get(event.paneId);
+            if (!pane)
+                continue;
+            // The event names its own process: the notify script captured it from this pane's tty when the event
+            // fired, and the Runtime verifies that exact generation — alive, same start time, same tty — before it
+            // authorizes a run.
+            const foreground = event.process ?? (await identity(pane));
+            if (!foreground)
+                continue;
+            if (!event.process && !profile.matchesAgentPane(pane, foreground))
+                continue;
+            // A disconnected/rejected pane must not suspend the shared poller or another pane's events.
+            // Keep one acknowledgement in flight per pane to retain its lifecycle ordering.
+            if (this.#pendingAcks.has(event.paneId))
+                continue;
+            if (!await recordStillOwnsPane(event.process, pane, this.#process.inspectProcess, () => identity(pane))) {
+                this.#logger(`Discarding stale ${profile.label} Hook event after pane process replacement`, {
+                    eventId: event.eventId,
+                    paneId: event.paneId,
+                });
+                try {
+                    fs.unlinkSync(eventFile);
+                }
+                catch { /* concurrently removed */ }
+                continue;
+            }
+            const payload = event.payload ?? {};
+            const sessionId = optionalSession(payload, event.sessionId);
+            const latest = state.get(event.paneId);
+            const latestSession = latest ? optionalSession(latest.payload) : undefined;
+            // A current pane session must never be replaced just to replay another session's old queue.
+            // Retain that session's source and original durable payload for a legitimate future resume.
+            if (latest?.process && matchesHookProcess(latest.process, foreground)
+                && latestSession && sessionId && latestSession !== sessionId)
+                continue;
+            const client = this.#client(event.paneId, sessionId, foreground);
+            if (event.type === 'gap' && persistedSnapshots.get(event.paneId) !== true)
+                continue;
+            if (event.type === 'gap' && gap && this.#confirmedGaps.has(gap.key))
+                continue;
+            const projection = event.type === 'gap' ? {
+                operation: { kind: 'gap', eventId: event.eventId },
+            } : profile.project({
+                eventId: event.eventId,
+                src: event.src ?? '',
+                ...(event.sourceOccurredAt === undefined ? {} : {
+                    sourceOccurredAt: event.sourceOccurredAt,
+                }),
+                payload,
+            });
+            const operation = projection.operation;
+            const restoredAck = client.resumePersistedDurable('inbox', event.eventId);
+            if (!restoredAck && !client.publishDurable('inbox', event.eventId, operation)) {
+                this.#logger(`${profile.label} Hook event remains queued because Connector durable state could not be persisted`, {
+                    eventId: event.eventId,
+                    paneId: event.paneId,
+                });
+                continue;
+            }
+            const pending = (restoredAck ?? client.waitForDurableAck('inbox', event.eventId)).then(() => {
+                if (event.type === 'gap' && gap)
+                    this.#confirmedGaps.add(gap.key);
+                else
+                    fs.unlinkSync(eventFile);
+            }).catch((error) => {
+                if (!this.#closed) {
+                    this.#logger(`${profile.label} Hook acknowledgement interrupted; source event remains queued`, error);
+                }
+            }).finally(() => { this.#pendingAcks.delete(event.paneId); });
+            this.#pendingAcks.set(event.paneId, { promise: pending, client, process: foreground, sessionId });
+        }
+        for (const [paneId, tracked] of [...this.#clients]) {
+            if (liveAgentPanes.has(paneId))
+                continue;
+            tracked.client.close();
+            this.#clients.delete(paneId);
+        }
+    }
+    #client(paneId, sessionId, foreground) {
+        const profile = this.#profile;
+        const nextSignature = signature(paneId, sessionId, foreground);
+        const current = this.#clients.get(paneId);
+        if (current?.signature === nextSignature)
+            return current.client;
+        current?.client.close();
+        const stateFile = path.join(this.#stateDirectory, `${digest(nextSignature)}.json`);
+        const client = this.#createClient({
+            adapterId: profile.agentId,
+            snapshotBeforeDurable: true,
+            socketPath: this.#socketPath,
+            credentialFile: this.#credentialFile,
+            stateFile,
+            candidate: candidate(profile, paneId, sessionId, foreground),
+            generation: { id: `${profile.agentId}-session:${digest(sessionId ?? nextSignature)}`, replace: true },
+            retryDelayMs: this.#retryDelayMs,
+            maxRetryDelayMs: this.#maxRetryDelayMs,
+            logger: this.#logger,
+        });
+        this.#clients.set(paneId, { signature: nextSignature, client });
+        client.start();
+        return client;
+    }
+}

package/dist/hooks/handmux-codebuddy-notify.sh

@@ -0,0 +1,116 @@
+#!/bin/sh
+# handmux 上报 hook(CodeBuddy Code). $1 = 事件 src 名:
+#   start(SessionStart) | prompt(UserPromptSubmit) | stop(Stop) | end(SessionEnd) | notify(Notification)
+#   | resume(PostToolUse on the interaction tools) | permreq(PermissionRequest) | permdenied(PermissionDenied) | compacting(PreCompact)
+#   | compact(PostCompact) | stopfail(StopFailure)
+# stdin = CodeBuddy 原始 payload(JSON).
+# 只做本地落盘:更新 JSON latest state,并在启用时追加有界 Bridge event spool。不联网、不依赖服务进程
+# 是否在跑 → 永不阻塞 CodeBuddy(始终 exit 0)。服务端/Connector 稍后消费这些文件。
+# 真正的读-改-写交给同目录的 handmux-write.cjs(node:真 JSON 解析 + 文件锁,多 pane 并发 hook 不丢更新)。
+# 与 Claude 版(handmux-notify.sh)的差别只有三处:配置目录、事件名表、进程身份判定 —— 详见各自注释。
+HANDMUX_AGENT=codebuddy
+export HANDMUX_AGENT
+CFG="$(dirname "$0")/handmux-codebuddy-notify.env"
+[ -f "$CFG" ] && . "$CFG"
+PANE="$TMUX_PANE"
+[ -z "$PANE" ] && exit 0   # 不在 tmux 里(没有 pane 可定位)→ 暂不记录
+# The installer registers the canonical src as the command's argument. Accept the raw hook event name too:
+# a hand-written or project-level settings.json can then point straight at `<script> <EventName>`, and both
+# spellings collapse into the one vocabulary the Connector reads. Anything else is not ours → touch nothing.
+case "$1" in
+  start|prompt|stop|end|notify|resume|permreq|permdenied|compacting|compact|stopfail) SRC="$1" ;;
+  SessionStart) SRC='start' ;;
+  UserPromptSubmit) SRC='prompt' ;;
+  Stop) SRC='stop' ;;
+  SessionEnd) SRC='end' ;;
+  Notification) SRC='notify' ;;
+  # The user answered a question or approved a plan: the wait is over and the turn continues. Registered with
+  # a matcher, so this only ever fires for those two tools.
+  PostToolUse) SRC='resume' ;;
+  PermissionRequest) SRC='permreq' ;;
+  PermissionDenied) SRC='permdenied' ;;
+  PreCompact) SRC='compacting' ;;
+  PostCompact) SRC='compact' ;;
+  StopFailure) SRC='stopfail' ;;
+  *) exit 0 ;;
+esac
+FILE="${HANDMUX_STATE:-$HOME/.codebuddy/handmux-state.json}"
+# 毫秒时间戳:与旧实现的 Date.now() 同单位(客户端已阅水位线兼容)。优先 perl,退化到 秒×1000。
+TS=$(perl -MTime::HiRes -e 'printf "%.0f", Time::HiRes::time()*1000' 2>/dev/null)
+[ -z "$TS" ] && TS=$(( $(date +%s) * 1000 ))
+HOST=$(hostname 2>/dev/null || printf '')
+# Capture the owning CodeBuddy process rather than this short-lived Hook process. The fingerprint lets the
+# Connector reject an offline event after tmux has reused the pane for a different CodeBuddy generation.
+# Missing/incomplete identity is intentionally tolerated for older CodeBuddy/platform variants: the writer
+# then omits the additive field and the legacy latest-state path keeps working.
+CODEBUDDY_PID=''
+CODEBUDDY_STARTED_AT=''
+CODEBUDDY_TTY=''
+# CodeBuddy's process is a Node CLI whose comm is meaningless for identity (`node`, or a version string), so
+# this hook matches the COMMAND LINE instead. A row is CodeBuddy when its PROGRAM token is one of the
+# published launchers (`codebuddy`, `codebuddy-code`, `cbc` — the native build) or when `node` runs a
+# CodeBuddy entry point (the npm layout: `node …/@tencent-ai/codebuddy-code/bin/codebuddy`).
+#   The match is deliberately NOT a substring over the whole line: this hook's own path lives under
+#   ~/.codebuddy/, and CodeBuddy runs configured hooks through a wrapper that names that path — a whole-line
+#   match would crown that short-lived wrapper as the session owner. Only the program/entry tokens are read.
+#   Input rows are `pid command…`; the pid prints only when EXACTLY ONE row matches, so an ambiguous pane
+#   stays unresolved and the writer omits the fingerprint instead of pinning a wrong process generation.
+CODEBUDDY_OWNER_AWK='
+  function base(value) { sub(/.*\//, "", value); return value }
+  function is_codebuddy(   i, program, entry) {
+    program = $2
+    sub(/^-/, "", program)
+    program = base(program)
+    if (program == "codebuddy" || program == "codebuddy-code" || program == "cbc") return 1
+    if (program != "node") return 0
+    for (i = 3; i <= NF; i++) {
+      if ($i ~ /^-/) continue
+      entry = base($i)
+      return (entry == "codebuddy" || entry == "codebuddy-code" || entry == "cbc") ? 1 : 0
+    }
+    return 0
+  }
+  { if (is_codebuddy()) { count += 1; only = $1 } }
+  END { if (count == 1) print only }
+'
+# Walk up from PPID first: it needs no tmux round-trip and, for a synchronous hook, names the Agent exactly.
+# The depth cap keeps a reparented/corrupted chain (PID 1 loops, container init) from spinning forever.
+ANCESTOR_PID=$PPID
+ANCESTOR_DEPTH=0
+while [ -n "$ANCESTOR_PID" ] && [ "$ANCESTOR_PID" -gt 1 ] 2>/dev/null && [ "$ANCESTOR_DEPTH" -lt 32 ]; do
+  ANCESTOR_COMMAND=$(ps -p "$ANCESTOR_PID" -o command= 2>/dev/null || printf '')
+  if [ -n "$ANCESTOR_COMMAND" ]; then
+    CODEBUDDY_PID=$(printf '%s %s\n' "$ANCESTOR_PID" "$ANCESTOR_COMMAND" | awk "$CODEBUDDY_OWNER_AWK")
+  fi
+  [ -n "$CODEBUDDY_PID" ] && break
+  ANCESTOR_PID=$(ps -p "$ANCESTOR_PID" -o ppid= 2>/dev/null | tr -d ' ')
+  ANCESTOR_DEPTH=$((ANCESTOR_DEPTH + 1))
+done
+if [ -z "$CODEBUDDY_PID" ]; then
+  # CodeBuddy runs configured hooks asynchronously, so the short-lived shell may already have been
+  # reparented. The pane's own TTY is still authoritative: scan it and take the single CodeBuddy row.
+  PANE_TTY=$(tmux display-message -p -t "$PANE" '#{pane_tty}' 2>/dev/null || printf '')
+  if [ -n "$PANE_TTY" ]; then
+    CODEBUDDY_PID=$(ps -t "${PANE_TTY#/dev/}" -o pid=,command= 2>/dev/null \
+      | awk "$CODEBUDDY_OWNER_AWK")
+  fi
+fi
+if [ -n "$CODEBUDDY_PID" ]; then
+  # Start time in the same form the server reads (processStartedAt in tmuxRuntime.ts): the raw procfs start
+  # tick where procfs exists, otherwise the `lstart` string. A wall-clock `lstart` moves whenever the host
+  # steps the guest clock (WSL2), which makes one live process look like several. The proc root is
+  # overridable so tests can supply a fixture instead of the host's live process table.
+  PROC_ROOT="${HANDMUX_PROC_ROOT:-/proc}"
+  # comm may contain spaces/parentheses: drop "pid (comm) " first, then starttime is field 20.
+  CODEBUDDY_STARTED_AT=$(sed 's/.*) //' "$PROC_ROOT/$CODEBUDDY_PID/stat" 2>/dev/null \
+    | awk '{ print $20 }' 2>/dev/null || printf '')
+  if [ -z "$CODEBUDDY_STARTED_AT" ]; then
+    # `lstart` follows the process locale on macOS; force C so standalone Node can parse it consistently.
+    CODEBUDDY_STARTED_AT=$(LC_ALL=C ps -p "$CODEBUDDY_PID" -o lstart= 2>/dev/null || printf '')
+  fi
+  CODEBUDDY_TTY=$(ps -p "$CODEBUDDY_PID" -o tty= 2>/dev/null || printf '')
+fi
+# payload 经 stdin 原样流给 node(不在 shell 里转义,避免坏数据);pane 含 '%' 直接进 JSON 字段,不再进 URL。
+node "$(dirname "$0")/handmux-write.cjs" "$FILE" "$PANE" "$SRC" "$TS" "$HOST" \
+  "${HANDMUX_CODEBUDDY_EVENTS:-}" "$CODEBUDDY_PID" "$CODEBUDDY_STARTED_AT" "$CODEBUDDY_TTY" 2>/dev/null || true
+exit 0