handmux 0.27.2 → 0.29.1

package/bin/handmux.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 // Stable JavaScript launcher. Keep this file free of product imports until the runtime version is known:
 // Node <22.16 lacks the native sqlite backup API required by the Project Task store, so importing dist first
-// would fail with an opaque module error before HandMux can tell the user what to do.
+// would fail with an opaque module error before handmux can tell the user what to do.
 import { nodeVersionSupport } from './node-version.js';
 
 const support = nodeVersionSupport(process.versions.node);
 if (!support.ok) {
   console.error(
     `[handmux] Node.js ${support.actual} is not supported. `
-    + `Install Node.js ${support.minimum} or newer, then run HandMux again: https://nodejs.org/`,
+    + `Install Node.js ${support.minimum} or newer, then run handmux again: https://nodejs.org/`,
   );
   process.exitCode = 1;
 } else {

package/dist/bin/handmux.js

@@ -2,9 +2,8 @@
 // handmux CLI implementation — compiled before development, tests, packing and publishing.
 //
 // The whole config story is two doors:
-//   handmux start   — just run it. No config needed: defaults to `none` (LAN-only), auto-generates a
-//                     token, prints the (token-free) URL + a QR of it, and the token on its own line. Flags
-//                     let you try variations for one run (e.g. --tunnel cloudflare).
+//   handmux start   — just run it. New users default to `none` (LAN-only) with Token + trusted-device
+//                     authentication. Prints the URL and QR. Flags let you try variations for one run.
 //   handmux setup   — the one place to configure persistently. Interactive; writes ~/.handmux/config.json
 //                     (name, tunnel, push, voice). Re-run it to change anything.
 // `start` reads that file; with no file it uses defaults. Precedence: flag > file > env (HANDMUX_*) >
@@ -15,6 +14,7 @@
 // `cloudflare-named` (stable URL on your own Cloudflare domain) · `ssh` (reverse-forward to your own
 // server via `tunlite run`). `handmux setup` wires any of these up interactively.
 import fs from 'node:fs';
+import { connectAuthControl } from '../src/deviceAuth/control.js';
 import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { createInterface } from 'node:readline';
@@ -22,14 +22,15 @@ import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { createRequire } from 'node:module';
 import { parseArgs, resolveConfig, explainConfig } from '../src/cli/options.js';
+import { installationAuthDefaults, tokenWarning } from '../src/cli/authDefaults.js';
 import { renderCompactQr } from '../src/cli/qr.js';
-import { supervise, bareUrl, publicUrlWithToken } from '../src/cli/supervisor.js';
+import { supervise, bareUrl } from '../src/cli/supervisor.js';
 import { resolveCloudflared } from '../src/cli/cloudflared.js';
 import { resolveTunlite, checkSshAuth } from '../src/cli/tunlite.js';
 import { resolveNatapp, resolveCpolar } from '../src/cli/tunnelClients.js';
 import { installService, uninstallService, isServiceInstalled, stopService } from '../src/cli/service.js';
 import { checkTmux, MIN_TMUX, tmuxInstallHint } from '../src/cli/tmuxVersion.js';
-import { readState, clearState, isAlive, acquireLifecycleLock, logPath, configPath, claudeStatePath, } from '../src/cli/state.js';
+import { readState, clearState, writeSupervisorConfig, isAlive, acquireLifecycleLock, logPath, configPath, claudeStatePath, } from '../src/cli/state.js';
 import { parseSupervisorConfig, readSupervisorLaunchConfig, supervisorLaunchArgs, } from '../src/cli/supervisorLaunch.js';
 import { scanSupervisorPids, terminateSupervisorPids } from '../src/cli/supervisorProcesses.js';
 import { runSetup } from '../src/cli/setupWizard.js';
@@ -42,6 +43,7 @@ import { probe } from '../src/cli/probe.js';
 import { notifyUpdate, runUpdateCheck, isBrewInstall, PKG_NAME } from '../src/cli/updateCheck.js';
 import { t, initLocale } from '../src/cli/i18n/index.js';
 import { runPush } from '../src/cli/pushCmd.js';
+import { runAuthCommand } from '../src/cli/authCmd.js';
 import { runWorkspaceCommand } from '../src/cli/workspaceCmd.js';
 import { runManagedCodexProcess } from '../src/cli/codexManaged.js';
 import { launchErrorCode, launchRawAgent, rawAgentInvocation, } from '../src/cli/agentLauncher.js';
@@ -147,10 +149,7 @@ function resolveFileConfig() {
 function describeConfig(p) {
     return p || t('config.none');
 }
-// Which user-visible settings THIS run would use differ from what's already running (from state.json)?
-// Kept to the two people actually re-run `start` to change — the tunnel and the port; each row is ready to
-// drop straight into the `start.running.changedRow` message ({key, from, to}). Only compares fields the
-// running state actually recorded, so an older state.json can't manufacture phantom diffs.
+// Which user-visible connection settings THIS run would use differ from what's already running (from state.json)?
 function configChanges(cfg, st) {
     const out = [];
     for (const key of ['tunnel', 'port']) {
@@ -205,11 +204,16 @@ async function preflightNgrok(cfg) {
 }
 async function main() {
     switch (command) {
-        case 'start': return withLifecycleLock(start);
+        case 'start': return withLifecycleLock(() => start());
         case 'open': return openCmd();
         case 'stop': return withLifecycleLock(stopAndWait);
-        case 'restart': return withLifecycleLock(async () => { if (!await stopAndWait())
-            return; return start(); });
+        case 'restart': return withLifecycleLock(async () => {
+            const { path: cfgPath } = resolveFileConfig();
+            const authDefaults = installationAuthDefaults(HOME, cfgPath ?? configPath(HOME), flags);
+            if (!await stopAndWait())
+                return;
+            return start(authDefaults);
+        });
         case 'status':
             await status();
             process.exit(process.exitCode || 0);
@@ -217,6 +221,9 @@ async function main() {
         case 'push':
             process.exitCode = await pushCmd();
             return;
+        case 'auth':
+            process.exitCode = await runAuthCommand({ argv: process.argv.slice(3), home: HOME });
+            return;
         case 'restore':
             process.exitCode = await runWorkspaceCommand({ flags, positionals, unknownShortFlags, home: HOME });
             return;
@@ -225,7 +232,9 @@ async function main() {
         case 'shortcuts': return shortcutsCmd();
         case 'hooks': return hooksCmd();
         case 'agent': return agentCmd();
-        case 'service': return withLifecycleLock(serviceCmd);
+        case 'service': return withLifecycleLock(async () => {
+            return serviceCmd();
+        });
         case 'update':
         case 'upgrade': return updateCmd();
         case '__supervise': return runSupervise();
@@ -291,12 +300,12 @@ function updateCmd() {
 function maybeNotifyUpdate() {
     notifyUpdate(HOME, { version: currentVersion(), selfPath: SELF_REAL });
 }
-async function start() {
+async function start(authDefaults) {
     const { path: cfgPath, cfg: fileCfg } = resolveFileConfig();
     console.log(t('config.loaded', { path: describeConfig(cfgPath) }));
     let cfg;
     try {
-        cfg = resolveConfig(flags, fileCfg);
+        cfg = resolveConfig(flags, fileCfg, process.env, undefined, authDefaults ?? installationAuthDefaults(HOME, cfgPath ?? configPath(HOME), flags));
     }
     catch (error) {
         console.error(t('err.generic', { msg: errorMessage(error) }));
@@ -349,7 +358,7 @@ async function start() {
         if (process.stdin.isTTY && await confirm(t('start.running.switchQ'))) {
             if (!await stopAndWait())
                 return;
-            return start();
+            return start({ token: cfg.token });
         }
         console.log(t('start.running.hint'));
         await printAccess(existing);
@@ -403,6 +412,8 @@ async function start() {
         }
     }
     if (cfg.foreground) {
+        // Match background launches: preserve the mode and token even when stop removes state.json.
+        writeSupervisorConfig(cfg, HOME);
         supervise(cfg, { home: HOME });
         console.log(t('start.foreground', { tunnel: cfg.tunnel, port: cfg.port }));
         await waitAndPrint(false);
@@ -568,7 +579,7 @@ async function serviceInstall() {
     console.log(t('config.loaded', { path: describeConfig(cfgPath) }));
     let cfg;
     try {
-        cfg = resolveConfig(flags, fileCfg);
+        cfg = resolveConfig(flags, fileCfg, process.env, undefined, installationAuthDefaults(HOME, cfgPath ?? configPath(HOME), flags));
     }
     catch (error) {
         console.error(t('err.generic', { msg: errorMessage(error) }));
@@ -894,7 +905,7 @@ function configCmd() {
     const { path: cfgPath, cfg: fileCfg } = resolveFileConfig();
     let rows;
     try {
-        rows = explainConfig(flags, fileCfg, cfgPath);
+        rows = explainConfig(flags, fileCfg, cfgPath, process.env, installationAuthDefaults(HOME, cfgPath ?? configPath(HOME), flags));
     }
     catch (error) {
         console.error(t('err.generic', { msg: errorMessage(error) }));
@@ -939,6 +950,20 @@ async function printAccess(st) {
     }
     const publicUrl = st.publicUrl ?? null;
     const localUrl = st.localUrl ?? null;
+    let devices = [];
+    let deviceProtection = null;
+    try {
+        const control = await connectAuthControl(HOME);
+        try {
+            const status = await control.request({ op: 'device-status' });
+            devices = status.devices;
+            deviceProtection = status.enabled === true;
+        }
+        finally {
+            control.close();
+        }
+    }
+    catch { /* The server may still be starting; the token is printed from the resolved state below. */ }
     const token = st.token ?? '';
     const scan = bareUrl(publicUrl);
     console.log('');
@@ -947,10 +972,15 @@ async function printAccess(st) {
     if (st.tunnel === 'none' && st.lanUrl)
         console.log(t('access.lan', { url: bareUrl(st.lanUrl) }));
     console.log(t('access.local', { url: bareUrl(localUrl) }));
+    if (deviceProtection === true) {
+        console.log(t('auth.access'));
+        if (!devices.some(d => d.status === 'active'))
+            console.log(t('auth.noDevices'));
+    }
     console.log(t('access.token', { token }));
-    // The QR carries the token so a phone scan signs in one-tap; the PRINTED links above stay token-free
-    // (safe to screenshot/share — paste the token shown above to sign in there).
-    await maybeQr(publicUrl && token ? publicUrlWithToken(publicUrl, token) : scan, st);
+    if (deviceProtection === false)
+        console.log(tokenWarning(t('auth.warning')));
+    await maybeQr(scan || bareUrl(st.lanUrl ?? localUrl), st);
     if (publicUrl && st.tunnel !== 'none') {
         const ok = await probe(publicUrl);
         if (ok)

package/dist/connectors/bridgeClient.js

@@ -69,9 +69,11 @@ export class LocalConnectorBridgeClient {
     #retryTimer;
     #retryAttempt = 0;
     #flushTail = Promise.resolve();
+    #snapshotBeforeDurable;
     #started = false;
+    #restoredDurable = new Set();
     #closed = false;
-    constructor({ adapterId, socketPath, credentialFile, stateFile, candidate, generation, connect = connectBridgeTransport, retryDelayMs = 250, maxRetryDelayMs = 5_000, maxEphemeralPerChannel = 256, logger = () => { }, }) {
+    constructor({ adapterId, socketPath, credentialFile, stateFile, candidate, generation, connect = connectBridgeTransport, retryDelayMs = 250, maxRetryDelayMs = 5_000, maxEphemeralPerChannel = 256, snapshotBeforeDurable = false, logger = () => { }, }) {
         if (!NAME_RE.test(adapterId) || !path.isAbsolute(socketPath)
             || !path.isAbsolute(credentialFile) || !path.isAbsolute(stateFile)
             || !candidate || !Number.isSafeInteger(retryDelayMs) || retryDelayMs <= 0
@@ -89,8 +91,11 @@ export class LocalConnectorBridgeClient {
         this.#maxRetryDelayMs = maxRetryDelayMs;
         this.#maxEphemeralPerChannel = maxEphemeralPerChannel;
         this.#logger = logger;
+        this.#snapshotBeforeDurable = snapshotBeforeDurable;
         this.#store = new PrivateStateStore(stateFile);
         this.#state = parseState(this.#store.read());
+        for (const item of this.#state.durable)
+            this.#restoredDurable.add(durableKey(item.channel, item.eventId));
         for (const [channel, value] of Object.entries(this.#state.snapshots)) {
             if (!NAME_RE.test(channel))
                 continue;
@@ -170,6 +175,12 @@ export class LocalConnectorBridgeClient {
             waiters.add({ resolve, reject });
         });
     }
+    // Resume the exact payload loaded at startup, including one already ACKed during connection setup.
+    // Source adapters must not reinterpret an old durable ID into different wire bytes on upgrade.
+    resumePersistedDurable(channel, eventId) {
+        return this.#restoredDurable.has(durableKey(channel, eventId))
+            ? this.waitForDurableAck(channel, eventId) : null;
+    }
     waitForDurableDrain() {
         if (this.#closed)
             return Promise.reject(new Error('Connector Bridge client is closed'));
@@ -339,6 +350,8 @@ export class LocalConnectorBridgeClient {
         if (!connection || connection.signal.aborted || this.#closed)
             return;
         while (this.#state.durable.length) {
+            if (this.#snapshotBeforeDurable)
+                await this.#flushSnapshots(connection);
             const item = this.#state.durable[0];
             const receipt = await connection.channel(item.channel).publish({
                 eventId: item.eventId, payload: item.payload,
@@ -353,19 +366,7 @@ export class LocalConnectorBridgeClient {
             }
             this.#resolveDurable(item.channel, item.eventId);
         }
-        for (const channel of [...this.#dirtySnapshots]) {
-            const entry = this.#snapshots.get(channel);
-            if (!entry) {
-                this.#dirtySnapshots.delete(channel);
-                continue;
-            }
-            const revision = entry.revision;
-            const receipt = await connection.channel(channel).setSnapshot(entry.value);
-            if (!receipt.accepted)
-                throw new Error(`Bridge snapshot rejected: ${receipt.reason ?? 'unknown'}`);
-            if (this.#snapshots.get(channel)?.revision === revision)
-                this.#dirtySnapshots.delete(channel);
-        }
+        await this.#flushSnapshots(connection);
         for (const channel of [...this.#dropped]) {
             const receipt = await connection.channel(channel).publish({ payload: { type: 'stream.gap' } });
             if (!receipt.accepted)
@@ -382,4 +383,19 @@ export class LocalConnectorBridgeClient {
             }
         }
     }
+    async #flushSnapshots(connection) {
+        for (const channel of [...this.#dirtySnapshots]) {
+            const entry = this.#snapshots.get(channel);
+            if (!entry) {
+                this.#dirtySnapshots.delete(channel);
+                continue;
+            }
+            const revision = entry.revision;
+            const receipt = await connection.channel(channel).setSnapshot(entry.value);
+            if (!receipt.accepted)
+                throw new Error(`Bridge snapshot rejected: ${receipt.reason ?? 'unknown'}`);
+            if (this.#snapshots.get(channel)?.revision === revision)
+                this.#dirtySnapshots.delete(channel);
+        }
+    }
 }

package/dist/connectors/claude/index.js

@@ -2,7 +2,10 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 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);
@@ -177,6 +180,7 @@ function looksLikeClaude(pane, foreground) {
 // 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;
@@ -185,24 +189,30 @@ export class ClaudeHookBridgeConnector {
     #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({ socketPath, credentialFile, stateDirectory, hookStateFile, eventDirectory, panes, process, pollMs = 250, retryDelayMs = 100, maxRetryDelayMs = 5_000, logger = () => { }, createClient = (options) => new LocalConnectorBridgeClient(options), }) {
+    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(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;
@@ -212,6 +222,8 @@ export class ClaudeHookBridgeConnector {
         this.#pollMs = pollMs;
         this.#retryDelayMs = retryDelayMs;
         this.#maxRetryDelayMs = maxRetryDelayMs;
+        this.#spoolMaxFiles = spoolMaxFiles;
+        this.#spoolRetentionMs = spoolRetentionMs;
         this.#logger = logger;
         this.#createClient = createClient;
     }
@@ -234,6 +246,7 @@ export class ClaudeHookBridgeConnector {
         if (this.#closed)
             return;
         this.#closed = true;
+        this.#nativeTail.clear();
         if (this.#timer)
             clearTimeout(this.#timer);
         this.#timer = undefined;
@@ -241,6 +254,10 @@ export class ClaudeHookBridgeConnector {
             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)
@@ -267,6 +284,40 @@ export class ClaudeHookBridgeConnector {
             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;
@@ -288,7 +339,7 @@ export class ClaudeHookBridgeConnector {
             return pending;
         };
         const events = [];
-        for (const eventFile of this.#eventFiles()) {
+        for (const eventFile of this.#pruneSpool(this.#eventFiles())) {
             let event = null;
             try {
                 const stat = fs.lstatSync(eventFile);
@@ -300,6 +351,20 @@ export class ClaudeHookBridgeConnector {
                 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) {
@@ -313,6 +378,8 @@ export class ClaudeHookBridgeConnector {
             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,
@@ -337,16 +404,25 @@ export class ClaudeHookBridgeConnector {
             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 }),
@@ -354,13 +430,30 @@ export class ClaudeHookBridgeConnector {
                 sourceOccurredAt: row.ts,
                 payload: row.payload,
             });
-            const snapshot = gaps.has(paneId) ? {
+            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));
+            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))
@@ -369,6 +462,8 @@ export class ClaudeHookBridgeConnector {
             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 ? {
@@ -384,6 +479,12 @@ export class ClaudeHookBridgeConnector {
             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,
@@ -397,6 +498,13 @@ export class ClaudeHookBridgeConnector {
             }
             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;
@@ -412,37 +520,25 @@ export class ClaudeHookBridgeConnector {
                 }),
                 payload,
             });
-            let operation = projection.operation;
-            const latest = state.get(event.paneId);
-            const latestSession = latest ? optionalSession(latest.payload) : undefined;
-            if (event.type === 'event' && operation.kind === 'set' && operation.state === 'waiting'
-                && event.sequence !== undefined && latest?.sequence !== undefined
-                && latest.sequence > event.sequence && latestSession === sessionId) {
-                operation = {
-                    kind: 'superseded',
-                    eventId: event.eventId,
-                    ...(event.sourceOccurredAt === undefined ? {} : { sourceOccurredAt: event.sourceOccurredAt }),
-                };
-            }
-            if (!client.publishDurable('inbox', event.eventId, operation)) {
+            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;
             }
-            try {
-                await client.waitForDurableAck('inbox', event.eventId);
+            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) {
+            }).catch((error) => {
                 if (!this.#closed)
-                    throw error;
-                return;
-            }
+                    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))
@@ -460,6 +556,7 @@ export class ClaudeHookBridgeConnector {
         const stateFile = path.join(this.#stateDirectory, `${digest(nextSignature)}.json`);
         const client = this.#createClient({
             adapterId: 'claude',
+            snapshotBeforeDurable: true,
             socketPath: this.#socketPath,
             credentialFile: this.#credentialFile,
             stateFile,

package/dist/hooks/handmux-notify.sh

@@ -53,8 +53,20 @@ if [ -z "$CLAUDE_PID" ]; then
   done
 fi
 if [ -n "$CLAUDE_PID" ]; then
-  # `lstart` follows the process locale on macOS; force C so standalone Node can parse it consistently.
-  CLAUDE_STARTED_AT=$(LC_ALL=C ps -p "$CLAUDE_PID" -o lstart= 2>/dev/null || printf '')
+  # Start time in the same form the server reads (processStartedAt in tmuxRuntime.ts): on Linux the raw
+  # procfs start tick, on macOS the `lstart` string. A wall-clock `lstart` moves whenever the host steps
+  # the guest clock (WSL2), which makes one live process look like several.
+  case "$(uname -s)" in
+    Linux)
+      # comm may contain spaces/parentheses: drop "pid (comm) " first, then starttime is field 20.
+      CLAUDE_STARTED_AT=$(sed 's/.*) //' "/proc/$CLAUDE_PID/stat" 2>/dev/null \
+        | awk '{ print $20 }' 2>/dev/null || printf '')
+      ;;
+    *)
+      # `lstart` follows the process locale on macOS; force C so standalone Node can parse it consistently.
+      CLAUDE_STARTED_AT=$(LC_ALL=C ps -p "$CLAUDE_PID" -o lstart= 2>/dev/null || printf '')
+      ;;
+  esac
   CLAUDE_TTY=$(ps -p "$CLAUDE_PID" -o tty= 2>/dev/null || printf '')
 fi
 # payload 经 stdin 原样流给 node(不在 shell 里转义,避免坏数据);pane 含 '%' 直接进 JSON 字段,

package/dist/hooks/handmux-write.cjs

@@ -27,7 +27,10 @@ if (!file || !pane || !src) process.exit(0);
 
 function processFingerprint() {
   const pid = Number(String(claudePid).trim());
-  const startedAt = Date.parse(String(claudeStartedAt).trim());
+  // The Hook reports the platform's start value (see handmux-notify.sh): a raw procfs tick on Linux, an
+  // lstart string on macOS. A digit-only value stays numeric — Date.parse would make it NaN.
+  const rawStartedAt = String(claudeStartedAt).trim();
+  const startedAt = /^\d+$/.test(rawStartedAt) ? Number(rawStartedAt) : Date.parse(rawStartedAt);
   const rawTty = String(claudeTty).trim();
   if (!Number.isSafeInteger(pid) || pid <= 0 || !Number.isFinite(startedAt)
     || !rawTty || rawTty === '?' || rawTty === '??') return undefined;
@@ -213,6 +216,17 @@ function update() {
     // stay latched at 进行中 forever; treat it as a soft end and clear the pane.
     if (prevSrc === 'prompt' || prevSrc === 'resume') { delete obj[pane]; }
     else applied = false;                                    // resting → drop without writing
+  } else if (src === 'start' && payload?.source === 'compact' && prevSrc === 'compact'
+    && typeof payload.prompt_id === 'string' && payload.prompt_id.length > 0
+    && payload.prompt_id === previous?.payload?.prompt_id
+    && typeof payload.session_id === 'string' && payload.session_id.length > 0
+    && payload.session_id === previous?.payload?.session_id
+    && sameSourceProcess(previous)
+    && Number(ts) > 0 && Number(ts) <= previous.ts) {
+    // Native Claude invokes SessionStart(compact) before PostCompact, but async Hook processes can
+    // finish out of order. Do not replace the completed state with an earlier-started Hook from that
+    // same prompt. Timestamp + prompt/session scope keeps later independent compactions intact.
+    applied = false;
   } else if (src === 'notify' && payload?.notification_type === 'permission_prompt'
     && prevSrc === 'permreq'
     && sameSourceProcess(previous)