handmux 0.29.2 → 0.31.0

package/dist/connectors/claude/index.js

@@ -1,175 +1,23 @@
-import crypto from 'node:crypto';
-import fs from 'node:fs';
-import path from 'node:path';
+// The Claude Code Inbox Connector. All pipeline mechanics live in the generic Hook Bridge Connector
+// (connectors/hookBridge.ts); this module is the Claude PROFILE — the product facts only Claude can answer:
+// which records carry its marking, how a pane proves it is still running Claude, how a `src`+payload maps
+// to an Inbox state, and the out-of-band native Tail reconciliation Claude has and CodeBuddy does not.
 import { classifyClaude } from '../../src/agents/claude.js';
 import { ClaudeNativeTailReader } from '../../src/agents/claudeNativeTail.js';
-import { LocalConnectorBridgeClient } from '../bridgeClient.js';
-const DEFAULT_SPOOL_MAX_FILES = 2_000;
-const DEFAULT_SPOOL_RETENTION_MS = 24 * 60 * 60_000;
-const EVENT_ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,255}$/;
-function isRecord(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-function bounded(value, max) {
-    return typeof value === 'string' && value.length > 0 && value.length <= max;
-}
-function parseProcessFingerprint(value) {
-    if (!isRecord(value) || !Number.isSafeInteger(value.pid) || Number(value.pid) <= 0
-        || typeof value.startedAt !== 'number' || !Number.isFinite(value.startedAt)
-        || value.startedAt < 0 || !bounded(value.tty, 1024))
-        return null;
-    return {
-        pid: Number(value.pid),
-        startedAt: value.startedAt,
-        tty: value.tty,
-    };
-}
-function normalizedTty(value) {
-    if (!value)
-        return undefined;
-    return value.startsWith('/dev/') ? value : `/dev/${value}`;
-}
-function matchesSourceProcess(source, current) {
-    if (!source)
-        return true; // additive field: accept records produced by an older installed Hook
-    return source.pid === current.pid
-        && source.startedAt === current.startedAt
-        && normalizedTty(source.tty) === normalizedTty(current.tty);
-}
-function optionalSession(payload, explicit) {
-    if (bounded(explicit, 1024))
-        return explicit;
-    return bounded(payload.session_id, 1024) ? payload.session_id : undefined;
-}
-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)}…`;
-}
-function canonicalState(kind) {
-    if (kind === 'working' || kind === 'compacting')
-        return 'working';
-    if (kind === 'permission')
-        return 'waiting';
-    if (kind === 'done')
-        return 'done';
-    if (kind === 'error')
-        return 'error';
-    return null;
-}
-export function projectClaudeHookInbox({ eventId, src, sourceOccurredAt, payload, }) {
-    const classified = classifyClaude(src, payload);
-    const state = classified ? canonicalState(classified.kind) : null;
-    const safeEventId = eventId && 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 parseEvent(value) {
-    if (!isRecord(value) || value.version !== 1 || (value.type !== 'event' && value.type !== 'gap')
-        || (value.agent !== undefined && value.agent !== 'claude')
-        || !bounded(value.eventId, 256) || !EVENT_ID_RE.test(value.eventId)
-        || !bounded(value.paneId, 256)
-        || (value.sequence !== undefined && (!Number.isSafeInteger(value.sequence) || Number(value.sequence) <= 0))
-        || (value.src !== undefined && !bounded(value.src, 64))
-        || (value.sessionId !== undefined && !bounded(value.sessionId, 1024))
-        || (value.sourceOccurredAt !== undefined
-            && (typeof value.sourceOccurredAt !== 'number' || !Number.isFinite(value.sourceOccurredAt)))
-        || (value.process !== undefined && parseProcessFingerprint(value.process) === null)
-        || (value.payload !== undefined && !isRecord(value.payload)))
-        return null;
-    return {
-        ...value,
-        ...(value.process === undefined ? {} : { process: parseProcessFingerprint(value.process) }),
-    };
-}
-function readHookState(file) {
-    try {
-        const value = JSON.parse(fs.readFileSync(file, 'utf8'));
-        if (!isRecord(value))
-            return new Map();
-        return new Map(Object.entries(value).flatMap(([paneId, raw]) => {
-            const row = isRecord(raw) ? raw : null;
-            const payload = isRecord(row?.payload) ? row.payload : null;
-            if (!bounded(paneId, 256) || !row || !payload || !bounded(row.src, 64)
-                || (row.agent !== undefined && row.agent !== 'claude'))
-                return [];
-            const ts = typeof row.ts === 'number' && Number.isFinite(row.ts) ? row.ts : 0;
-            const sequence = Number.isSafeInteger(row.sequence) && Number(row.sequence) > 0
-                ? Number(row.sequence) : undefined;
-            const process = row.process === undefined ? undefined : parseProcessFingerprint(row.process);
-            if (process === null)
-                return [];
-            return [[paneId, {
-                        ts,
-                        src: row.src,
-                        ...(row.agent === 'claude' ? { agent: 'claude' } : {}),
-                        payload,
-                        ...(sequence === undefined ? {} : { sequence }),
-                        ...(process === undefined ? {} : { process }),
-                    }]];
-        }));
-    }
-    catch {
-        return new Map();
-    }
-}
-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');
-}
-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(paneId, sessionId, process) {
-    const processRef = {
-        pid: process.pid,
-        ...(process.startedAt === undefined ? {} : { startedAt: process.startedAt }),
-        ...(process.tty === undefined ? {} : { tty: process.tty }),
-    };
-    return {
-        paneId,
-        attachmentId: `claude-hook:${digest(JSON.stringify({ paneId, process: processRef }))}`,
-        ...(sessionId === undefined ? {} : { sessionId }),
-        process: processRef,
-    };
-}
+import { HookBridgeConnector, projectHookInbox } from '../hookBridge.js';
+// Claude's records are explicitly marked `agent: "claude"`; an ABSENT marking is the legacy Claude row from
+// before the multi-Agent format (the reader admits it). Anything else fails closed at the Connector entrance.
+function acceptsClaudeAgent(agent) {
+    return agent === 'claude';
+}
+// Project one Claude Hook edge. Kept as a named export because it is Claude's documented projection and is
+// the only place the Claude classifier meets the shared Inbox operation shape.
+export function projectClaudeHookInbox(input) {
+    return projectHookInbox({ classify: classifyClaude, ...input });
+}
+// tmux reports the native installer's version-named binary (e.g. "2_1_196"), and the value is normalized
+// to 'claude' at ingest by resolveVersionedComms — so an exact single-name match is right here. A
+// version-shaped command is corroborated through the process's REAL executable path.
 function looksLikeClaude(pane, foreground) {
     if (pane.currentCommand === 'claude')
         return true;
@@ -177,397 +25,20 @@ function looksLikeClaude(pane, foreground) {
         return false;
     return typeof foreground.executable === 'string' && /claude/.test(foreground.executable);
 }
-// Bridges the existing async Claude Hooks without ever blocking Claude itself. Hook subprocesses only
-// commit files; this coordinator owns socket lifetime, per-session replacement and durable acknowledgements.
-export class ClaudeHookBridgeConnector {
-    #nativeTail;
-    #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({ nativeTail = new ClaudeNativeTailReader(), 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 (![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('Claude Hook Bridge Connector requires private paths and Runtime identity sources');
-        }
-        this.#socketPath = socketPath;
-        this.#nativeTail = nativeTail;
-        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('Claude 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('Claude Hook Bridge reconciliation failed', error);
-        });
-        return pending;
-    }
-    async close() {
-        if (this.#closed)
-            return;
-        this.#closed = true;
-        this.#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 Claude Hook source files that could not be delivered', {
-            dropped: dropped.size, remaining: events.length - dropped.size,
-        });
-        return files.filter((file) => !dropped.has(file));
-    }
-    async #reconcile() {
-        if (this.#closed)
-            return;
-        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.#process.inspectForeground(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 = parseEvent(JSON.parse(fs.readFileSync(eventFile, 'utf8')));
-            }
-            catch { /* partial/removed file */ }
-            if (event)
-                events.push({ file: eventFile, event });
-        }
-        const state = readHookState(this.#hookStateFile);
-        for (const [paneId, pending] of this.#pendingAcks) {
-            const pane = paneMap.get(paneId);
-            const foreground = pane ? await identity(pane) : null;
-            const latest = state.get(paneId);
-            const latestSession = latest ? optionalSession(latest.payload) : undefined;
-            const replacedSession = foreground && latest?.process && matchesSourceProcess(latest.process, foreground)
-                && latestSession && pending.sessionId && latestSession !== pending.sessionId;
-            if (replacedSession || !pane || (foreground && (foreground.pid !== pending.process.pid
-                || (foreground.startedAt !== undefined && pending.process.startedAt !== undefined
-                    && foreground.startedAt !== pending.process.startedAt)
-                || (foreground.tty !== undefined && pending.process.tty !== undefined
-                    && foreground.tty !== pending.process.tty))))
-                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);
-            const foreground = pane ? await identity(pane) : null;
-            if (!pane || !foreground)
-                continue;
-            if (!event.process && !looksLikeClaude(pane, foreground))
-                continue;
-            if (!matchesSourceProcess(event.process, foreground)) {
-                this.#logger('Discarding stale Claude Hook event after pane process replacement', {
-                    eventId: event.eventId,
-                    paneId: event.paneId,
-                });
-                try {
-                    fs.unlinkSync(eventFile);
-                }
-                catch { /* concurrently removed */ }
-                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);
-            const foreground = pane ? await identity(pane) : null;
-            if (!pane || !foreground)
-                continue;
-            if (!row.process && !looksLikeClaude(pane, foreground))
-                continue;
-            if (!matchesSourceProcess(row.process, 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 : `claude-hook-${row.sequence}`;
-            const projection = projectClaudeHookInbox({
-                ...(eventId === undefined ? {} : { eventId }),
-                src: row.src,
-                sourceOccurredAt: row.ts,
-                payload: row.payload,
-            });
-            if (row.src !== 'end') {
-                const native = this.#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: 'Claude 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 } : {}),
-            }));
-        }
-        this.#nativeTail.retain(currentNativeSessions);
-        const liveClaudePanes = new Set(currentStatePanes);
-        for (const pane of panes) {
-            if (currentStatePanes.has(pane.paneId))
-                continue;
-            const foreground = await identity(pane);
-            if (!foreground || !looksLikeClaude(pane, foreground))
-                continue;
-            liveClaudePanes.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: 'Claude 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);
-            const foreground = pane ? await identity(pane) : null;
-            if (!pane || !foreground)
-                continue;
-            if (!event.process && !looksLikeClaude(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 (!matchesSourceProcess(event.process, foreground)) {
-                this.#logger('Discarding stale Claude 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 && matchesSourceProcess(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 },
-            } : projectClaudeHookInbox({
-                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('Claude 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('Claude 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 (liveClaudePanes.has(paneId))
-                continue;
-            tracked.client.close();
-            this.#clients.delete(paneId);
-        }
-    }
-    #client(paneId, sessionId, foreground) {
-        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: 'claude',
-            snapshotBeforeDurable: true,
-            socketPath: this.#socketPath,
-            credentialFile: this.#credentialFile,
-            stateFile,
-            candidate: candidate(paneId, sessionId, foreground),
-            generation: { id: `claude-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;
+function claudeProfile(nativeTail) {
+    return {
+        agentId: 'claude',
+        label: 'Claude',
+        attachmentPrefix: 'claude-hook',
+        eventPrefix: 'claude-hook',
+        acceptsAgent: acceptsClaudeAgent,
+        matchesAgentPane: looksLikeClaude,
+        project: projectClaudeHookInbox,
+        nativeTail,
+    };
+}
+export class ClaudeHookBridgeConnector extends HookBridgeConnector {
+    constructor({ nativeTail = new ClaudeNativeTailReader(), ...options }) {
+        super({ ...options, profile: claudeProfile(nativeTail) });
     }
 }

package/dist/connectors/codebuddy/index.js

@@ -0,0 +1,49 @@
+// The CodeBuddy Code Inbox Connector. Pipeline mechanics live in the generic Hook Bridge Connector
+// (connectors/hookBridge.ts); this module is the CodeBuddy profile — the product facts only CodeBuddy can
+// answer. It is deliberately thin: CodeBuddy drives the same file Hooks and the same shared writer as
+// Claude, so the only CodeBuddy-specific pieces are the record marking, the pane-process anchor, and the
+// `src`+payload classification (src/codebuddyEvents.ts).
+import { acceptsCodeBuddyAgent, classifyCodeBuddy } from '../../src/codebuddyEvents.js';
+import { isCodeBuddyCommandLine, verifyCodeBuddyProcess } from '../../src/agents/codebuddy.js';
+import { CodeBuddyNativeTailReader } from '../../src/agents/codebuddyNativeTail.js';
+import { HookBridgeConnector, projectHookInbox } from '../hookBridge.js';
+// The marking rule and its reasoning live in src/codebuddyEvents.ts — the conversation lens's pane binding
+// has to answer it identically, so there is exactly one definition rather than two that can drift.
+export { acceptsCodeBuddyAgent };
+export function projectCodeBuddyHookInbox(input) {
+    return projectHookInbox({ classify: classifyCodeBuddy, ...input });
+}
+// CodeBuddy is never the pane's foreground LEAF: it runs inside a Node launcher whose group also carries
+// transient tool children (npm/ruby update checks), and the single-leaf view prefers such a child. The Hook
+// shell records the owning CodeBuddy process, and Runtime anchors the lease on that very row — so the
+// Connector must resolve identity exactly like the adapter verifies it. Comparing the recorded fingerprint
+// (or publishing a candidate) against the leaf instead would never match, and the whole chain would drop
+// every event.
+async function resolveCodeBuddyPaneProcess(pane, context) {
+    const verified = await verifyCodeBuddyProcess(pane, context);
+    return verified && typeof verified === 'object' ? verified : null;
+}
+// Only reached for a record with NO process fingerprint (an older writer). The resolved anchor is already
+// proven CodeBuddy, so this just re-states that in command-line terms.
+function looksLikeCodeBuddy(pane, foreground) {
+    return isCodeBuddyCommandLine(foreground.commandLine ?? '')
+        || isCodeBuddyCommandLine(pane.currentCommand);
+}
+export class CodeBuddyHookBridgeConnector extends HookBridgeConnector {
+    constructor({ nativeTail = new CodeBuddyNativeTailReader(), ...options }) {
+        super({
+            ...options,
+            profile: {
+                agentId: 'codebuddy',
+                label: 'CodeBuddy',
+                attachmentPrefix: 'codebuddy-hook',
+                eventPrefix: 'codebuddy-hook',
+                acceptsAgent: acceptsCodeBuddyAgent,
+                matchesAgentPane: looksLikeCodeBuddy,
+                project: projectCodeBuddyHookInbox,
+                resolvePaneProcess: resolveCodeBuddyPaneProcess,
+                nativeTail,
+            },
+        });
+    }
+}