handmux 0.27.2 → 0.29.0

package/dist/src/claudeEvents.js

@@ -6,6 +6,7 @@ import { resolveVersionedComms } from './agents/claude.js';
 import { resolveCodexComms } from './agents/codex.js';
 import { defaultRun } from './agents/scanUtils.js';
 import { claude } from './agents/claude.js';
+import { ClaudeNativeTailReader } from './agents/claudeNativeTail.js';
 const here = path.dirname(fileURLToPath(import.meta.url));
 // The hook-maintained state file: ONE JSON object keyed by tmux pane id, each value the pane's latest
 // event { ts, src, host, payload }. The hook writes it (handmux-write.js); the server only reads it.
@@ -60,28 +61,6 @@ function defaultStatMtime(file) { try {
 catch {
     return null;
 } }
-// Read the LAST complete JSON line of a (possibly multi-MB) transcript, or null if unreadable. Reads only a
-// bounded tail so cost is one small read regardless of transcript size; a last line longer than the window
-// won't parse cleanly, but the only line we care to recognise (the interrupt marker) is tiny.
-function defaultReadTail(file) {
-    try {
-        const fd = fs.openSync(file, 'r');
-        try {
-            const size = fs.fstatSync(fd).size;
-            const len = Math.min(size, 65536);
-            const buf = Buffer.alloc(len);
-            fs.readSync(fd, buf, 0, len, size - len);
-            const lines = buf.toString('utf8').split('\n').filter((line) => line.trim());
-            return lines.at(-1) ?? null;
-        }
-        finally {
-            fs.closeSync(fd);
-        }
-    }
-    catch {
-        return null;
-    }
-}
 // Pure: has the user resolved the permission prompt recorded by `rec`, judged by its transcript mtime?
 // True only once the transcript has grown past the event ts by more than the guard. Exported for testing.
 export function permissionResolved(rec, mtimeMs, guard = PERM_RESOLVED_GUARD_MS) {
@@ -145,6 +124,14 @@ function readStateFile(file) {
                 src: typeof row.src === 'string' ? row.src : '',
                 payload,
             };
+            if (typeof row.sequence === 'number' && Number.isSafeInteger(row.sequence) && row.sequence > 0) {
+                record.sequence = row.sequence;
+            }
+            const process = recordOf(row.process);
+            if (process && typeof process.pid === 'number' && Number.isSafeInteger(process.pid)
+                && typeof process.startedAt === 'number' && Number.isFinite(process.startedAt)) {
+                record.process = { pid: process.pid, startedAt: process.startedAt };
+            }
             if (Object.hasOwn(row, 'agent')) {
                 record.agent = typeof row.agent === 'string' && row.agent ? row.agent : null;
             }
@@ -215,7 +202,7 @@ function managedStates(value) {
 //   file: the hook-maintained JSON state file (DEFAULT_STATE_FILE).
 // The hook is the sole writer; the server reads the file fresh on every getStates and on every file
 // change (the watcher, for push). No persisted state of our own — the file IS the persistence.
-export function createClaudeEvents({ commands, push, codexApp = null, file = DEFAULT_STATE_FILE, now = () => Date.now(), statMtime = defaultStatMtime, readTail = defaultReadTail, run = defaultRun, onStateChange = () => { }, watch = fs.watch, mkdir = fs.mkdirSync, setTimer = setTimeout, clearTimer = (handle) => clearTimeout(handle), } = {}) {
+export function createClaudeEvents({ nativeTail = new ClaudeNativeTailReader(), commands, push, codexApp = null, file = DEFAULT_STATE_FILE, now = () => Date.now(), statMtime = defaultStatMtime, readTail, run = defaultRun, onStateChange = () => { }, watch = fs.watch, mkdir = fs.mkdirSync, setTimer = setTimeout, clearTimer = (handle) => clearTimeout(handle), } = {}) {
     // Short-lived executable-identity verdicts. Each poll still checks the foreground pid signature; the
     // cache only avoids repeating lsof while that exact process set is unchanged.
     const commVerdicts = new Map();
@@ -326,15 +313,23 @@ export function createClaudeEvents({ commands, push, codexApp = null, file = DEF
             if (!agent)
                 continue;
             let c = classifyRecord(rec);
+            const native = rec.src === 'end' ? null : nativeTail.read(rec.payload, rec.ts, now(), rec.process, rec.src);
+            if (native?.status === 'busy')
+                c = { kind: 'working', msg: '' };
+            else if (native?.status === 'waiting')
+                c = { kind: 'permission', msg: '' };
+            else if (native?.settled)
+                c = null;
             // A 需要你 the user already resolved leaves no closing hook (see PERM_RESOLVED_GUARD_MS). statMtime
             // gates the cheap "still pending" path; only once the transcript has grown past the event do we pay the
             // bounded tail read to tell a RESUME (approve/deny → 进行中) from an INTERRUPT (ESC → neutral present).
-            if (c && c.kind === 'permission') {
+            if (!native?.status && c && c.kind === 'permission') {
                 const tp = typeof rec.payload.transcript_path === 'string' ? rec.payload.transcript_path : null;
-                if (tp && permissionResolved(rec, statMtime(tp)))
-                    c = resolvedPermissionKind(readTail(tp));
+                if (tp && permissionResolved(rec, statMtime(tp))) {
+                    c = readTail ? resolvedPermissionKind(readTail(tp)) : { kind: 'working', msg: '' };
+                }
             }
-            else if (c && c.kind === 'working') {
+            else if (!native?.status && c && c.kind === 'working') {
                 // ESC-interrupt during a turn leaves the last hook as the stale 'prompt' (working) — no Stop fires,
                 // so working would otherwise stick until WORKING_TTL_MS (2h), pinning the composer's send→stop toggle.
                 // Once the transcript has grown past the prompt event, a bounded tail read settles it: an interrupt
@@ -342,18 +337,25 @@ export function createClaudeEvents({ commands, push, codexApp = null, file = DEF
                 // definitive so no guard window is needed; an unreadable stat/tail can't tell → keep working.
                 const tp = typeof rec.payload.transcript_path === 'string' ? rec.payload.transcript_path : null;
                 const mtime = tp ? statMtime(tp) : null;
-                if (tp && typeof mtime === 'number' && mtime > rec.ts && isInterruptTail(readTail(tp)))
+                if (readTail && tp && typeof mtime === 'number' && mtime > rec.ts && isInterruptTail(readTail(tp)))
                     c = null;
             }
-            else if (c && c.kind === 'compacting') {
+            else if (!native?.status && c && c.kind === 'compacting') {
                 // A no-op /compact fires no PostCompact; it writes its <local-command-stdout> at once. Once the
                 // transcript has grown past the PreCompact event and its tail is that stdout, the /compact is done
                 // (nothing to compact) → drop 压缩中. A real compaction stays silent until PostCompact, so it keeps
                 // showing for its whole run. Unreadable stat/tail → can't tell → keep 压缩中 (the TTL is the backstop).
                 const tp = typeof rec.payload.transcript_path === 'string' ? rec.payload.transcript_path : null;
                 const mtime = tp ? statMtime(tp) : null;
-                if (tp && typeof mtime === 'number' && mtime > rec.ts && isLocalCommandStdout(readTail(tp)))
-                    c = null;
+                if (tp && typeof mtime === 'number' && mtime > rec.ts) {
+                    const last = native?.lastRecord;
+                    const content = recordOf(last?.message)?.content;
+                    const stdout = last?.sessionId === rec.payload.session_id && last?.isSidechain !== true
+                        && typeof last?.timestamp === 'string' && Date.parse(last.timestamp) > rec.ts
+                        && typeof content === 'string' && /^\s*<local-command-stdout>[\s\S]*<\/local-command-stdout>\s*$/.test(content);
+                    if (readTail ? isLocalCommandStdout(readTail(tp)) : stdout)
+                        c = null;
+                }
             }
             const lp = live ? live.get(pane) : null;
             // Dropped when tmux says the pane is gone or no longer running THIS agent (hard kill / crash /
@@ -463,6 +465,7 @@ export function createClaudeEvents({ commands, push, codexApp = null, file = DEF
         catch { /* fs.watch unsupported → push falls back to evaluation on each /states poll */ }
     }
     function stop() {
+        nativeTail.clear();
         if (watcher) {
             watcher.close();
             watcher = null;
@@ -503,23 +506,76 @@ export function createClaudeEvents({ commands, push, codexApp = null, file = DEF
             return 'claude';
         return rec.agent === 'claude' ? 'claude' : null;
     }
-    function paneKind(pane) {
+    function paneKind(pane, process) {
         const rec = readStateFile(file)[pane];
-        if (!rec || rec.agent === 'codex')
+        if (!rec || (rec.agent !== undefined && rec.agent !== 'claude'))
+            return null;
+        if (process && rec.process && (process.pid !== rec.process.pid || process.startedAt !== rec.process.startedAt))
             return null;
+        if (rec.src === 'end') {
+            if (typeof rec.payload.session_id === 'string')
+                nativeTail.release(rec.payload.session_id);
+        }
+        else {
+            const native = nativeTail.read(rec.payload, rec.ts, now(), rec.process, rec.src);
+            if (native.status === 'unknown')
+                return null;
+            if (native.status === 'busy')
+                return 'working';
+            if (native.status === 'waiting')
+                return 'permission';
+            if (native.settled)
+                return 'idle';
+        }
+        // Activity is not the Inbox roster: neutral lifecycle edges deliberately create no Inbox card,
+        // but a completed manual /compact must release the conversation queue. Automatic compaction
+        // continues the current turn, so it must not admit another prompt between compaction and generation.
+        if (rec.src === 'compact') {
+            return rec.payload.trigger === 'manual' ? 'idle'
+                : rec.payload.trigger === 'auto' ? 'working' : null;
+        }
+        if (rec.src === 'start') {
+            // Native full/partial/reactive compaction calls SessionStart(compact) before PostCompact.
+            // It identifies neither an idle session nor specifically an automatic compaction.
+            return ['startup', 'clear', 'resume'].includes(String(rec.payload.source)) ? 'idle'
+                : rec.payload.source === 'compact' ? 'compacting' : null;
+        }
         return classifyRecord(rec)?.kind ?? null;
     }
-    function paneCompletionToken(pane) {
+    function paneCompletionToken(pane, process) {
         const rec = readStateFile(file)[pane];
-        if (!rec || rec.agent === 'codex')
+        if (!rec || (rec.agent !== undefined && rec.agent !== 'claude'))
+            return null;
+        if (process && rec.process && (process.pid !== rec.process.pid || process.startedAt !== rec.process.startedAt))
+            return null;
+        const native = rec.src === 'end' ? undefined : nativeTail.read(rec.payload, rec.ts, now(), rec.process, rec.src);
+        if (native?.status && native.status !== 'idle')
             return null;
-        const kind = classifyRecord(rec)?.kind ?? null;
+        if (native?.settled)
+            return native.settled;
+        // An idle startup/resume/clear is the first dispatch baseline. Give it a stable token too:
+        // the queue can then detect a fast completion even when no poll observed its busy phase.
+        const baseline = rec.src === 'start' && ['startup', 'clear', 'resume'].includes(String(rec.payload.source));
+        const kind = (rec.src === 'compact' && rec.payload.trigger === 'manual') || baseline
+            ? 'idle' : classifyRecord(rec)?.kind ?? null;
         if (kind !== 'done' && kind !== 'error' && kind !== 'end' && kind !== 'idle')
             return null;
-        return Number.isFinite(rec.ts) && rec.ts >= 0 ? `claude-completed:${rec.ts}` : null;
+        const nativeCompletion = native?.localCommand;
+        if (nativeCompletion !== undefined)
+            return nativeCompletion;
+        return Number.isFinite(rec.ts) && rec.ts >= 0
+            ? `claude-${baseline ? 'baseline' : 'completed'}:${rec.ts}${rec.sequence === undefined ? '' : `:${rec.sequence}`}`
+            : null;
     }
     return {
         getStates, identifyPaneAgents, start, stop, paneSession, paneAgent,
-        paneKind, paneCompletionToken,
+        paneKind, paneCompletionToken, nativeTail,
+        paneRestoredPrompt(pane) {
+            const rec = readStateFile(file)[pane];
+            if (!rec || rec.src === 'end' || (rec.agent !== undefined && rec.agent !== 'claude'))
+                return null;
+            const native = nativeTail.read(rec.payload, rec.ts, now(), rec.process, rec.src);
+            return native.status === 'idle' ? native.restoredPrompt ?? null : null;
+        },
     };
 }

package/dist/src/cli/authCmd.js

@@ -0,0 +1,202 @@
+import { text, select, confirm, isCancel } from '@clack/prompts';
+import { AuthControlError, connectAuthControl } from '../deviceAuth/control.js';
+import { DeviceAuthError, parseExpire, validateName } from '../deviceAuth/service.js';
+import { tokenWarning } from './authDefaults.js';
+import { t } from './i18n/index.js';
+const usage = (target) => target === 'device'
+    ? 'Usage: handmux auth device status|on|off|add|list|edit|revoke'
+    : target === 'address'
+        ? 'Usage: handmux auth address status|on|off|list|add|remove'
+        : 'Usage: handmux auth device <action> | handmux auth address <action>';
+export function parseAuthArgs(argv, interactive) {
+    const [target, action, ...rest] = argv;
+    if (target !== 'device' && target !== 'address') {
+        throw new Error(usage());
+    }
+    const deviceActions = ['status', 'on', 'off', 'add', 'list', 'edit', 'revoke'];
+    const addressActions = ['status', 'on', 'off', 'list', 'add', 'remove'];
+    const allowed = target === 'device' ? deviceActions : addressActions;
+    if (!action || !allowed.includes(action))
+        throw new Error(usage(target));
+    const result = { target, action: action };
+    if (target === 'address') {
+        if (action === 'add' || action === 'remove') {
+            if (rest.length !== 1 || !rest[0])
+                throw new Error(`Usage: handmux auth address ${action} <origin>`);
+            result.origin = rest[0];
+        }
+        else if (rest.length)
+            throw new Error(`Usage: handmux auth address ${action}`);
+        return result;
+    }
+    if (['status', 'on', 'off', 'list'].includes(action)) {
+        if (rest.length)
+            throw new Error(`Usage: handmux auth device ${action}`);
+        return result;
+    }
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === '--code' || arg === '--name' || arg === '--expire') {
+            const key = arg === '--code' ? 'code' : arg === '--name' ? 'name' : 'expire';
+            const value = rest[++i];
+            if (!value || value.startsWith('--') || result[key] !== undefined)
+                throw new Error(`Provide ${arg} exactly once with a value`);
+            result[key] = value;
+        }
+        else if (arg.startsWith('-') || result.id !== undefined)
+            throw new Error(`Unexpected argument: ${arg}`);
+        else if (action === 'add')
+            throw new Error('Use --code for non-interactive add; interactive add reads the code after handmux auth device add');
+        else
+            result.id = arg;
+    }
+    if (action === 'list' && (result.id || result.code || result.name !== undefined || result.expire !== undefined))
+        throw new Error('Usage: handmux auth device list');
+    if (action !== 'add' && result.code !== undefined)
+        throw new Error('The --code flag is only valid for handmux auth device add');
+    if (action === 'revoke' && (result.name !== undefined || result.expire !== undefined))
+        throw new Error('Usage: handmux auth device revoke <device-id>');
+    if ((action === 'edit' || action === 'revoke') && !result.id)
+        throw new Error('Provide the exact device ID from handmux auth device list');
+    if (action === 'edit' && result.name === undefined && result.expire === undefined)
+        throw new Error('Provide --name or --expire');
+    if (result.name !== undefined)
+        result.name = validateName(result.name);
+    if (result.expire !== undefined)
+        parseExpire(result.expire);
+    if (action === 'add') {
+        if (result.code !== undefined && !/^\d{6}$/.test(result.code))
+            throw new Error('Code must be exactly 6 digits, preserving leading zeros');
+        if (!interactive && (result.code === undefined || result.name === undefined || result.expire === undefined))
+            throw new Error('Non-interactive add requires --code, --name and --expire; no code has been consumed');
+    }
+    return result;
+}
+const safeText = (value) => String(value ?? '').replace(/[\x00-\x1f\x7f-\x9f]/g, '');
+const controlErrorCopy = {
+    AUTH_UNAVAILABLE: 'auth.error.unavailable', INVALID_COMMAND: 'auth.error.invalidCommand',
+    CODE_INVALID: 'auth.error.codeInvalid', CLAIM_RATE_LIMIT: 'auth.error.rateLimit',
+    PAIRING_NOT_FOUND: 'auth.error.pairingGone', PAIRING_INACTIVE: 'auth.error.pairingGone',
+    DEVICE_NOT_FOUND: 'auth.error.deviceNotFound', DEVICE_INACTIVE: 'auth.error.deviceInactive',
+    DEVICE_CONFLICT: 'auth.error.conflict', INVALID_EDIT: 'auth.error.invalidEdit',
+    INVALID_VERSION: 'auth.error.invalidVersion', PAIRING_CAPACITY: 'auth.error.pairingCapacity',
+    TOKEN_REQUIRED: 'auth.error.tokenRequired', DEVICE_REQUIRED: 'auth.error.deviceRequired',
+    DEVICE_EXPIRY_CLI_ONLY: 'auth.error.expiryCliOnly',
+    INVALID_EXPIRE: 'auth.invalidDuration', INVALID_NAME: 'auth.invalidName',
+    INVALID_ORIGIN: 'auth.error.invalidOrigin', ORIGIN_LIMIT: 'auth.error.originLimit',
+    SESSION_INVALID: 'auth.error.sessionInvalid', DEVICE_AUTH_DISABLED: 'auth.error.unavailable',
+};
+const iso = (value) => typeof value === 'number' ? new Date(value).toISOString() : 'never';
+function outputDevice(value) {
+    const d = value;
+    return `${safeText(d.id)}\t${safeText(d.name)}\t${safeText(d.status)}\t${iso(d.expires_at)}\t${iso(d.authorized_at)}\t${iso(d.last_used_at)}\t${safeText(d.browser_summary)}${'previousExpiresAt' in d ? `\tprevious expiry: ${iso(d.previousExpiresAt)}` : ''}`;
+}
+const canceled = Symbol('canceled');
+async function ask(promise) { const result = await promise; if (isCancel(result))
+    throw canceled; return result; }
+export async function runAuthCommand({ argv, home, interactive = !!process.stdin.isTTY, log = console.log, err = console.error, connect = connectAuthControl }) {
+    let client;
+    try {
+        const args = parseAuthArgs(argv, interactive);
+        client = await connect(home);
+        if (args.target === 'address') {
+            if (args.action === 'status' || args.action === 'list') {
+                const result = await client.request({ op: 'address-status' });
+                log(`可信地址保护: ${result.enabled ? '已开启' : '未开启'}`);
+                if (!result.enabled)
+                    log(tokenWarning(t('auth.addressWarning')));
+                result.origins.forEach(origin => log(origin));
+                return 0;
+            }
+            if (args.action === 'on' || args.action === 'off') {
+                if (args.action === 'off' && interactive && !await ask(confirm({ message: t('auth.addressDisableConfirm'), initialValue: false })))
+                    throw canceled;
+                const result = await client.request({ op: 'address-policy', enabled: args.action === 'on' });
+                log(`可信地址保护: ${result.enabled ? '已开启' : '未开启'}`);
+                return 0;
+            }
+            const result = await client.request({ op: args.action === 'add' ? 'address-add' : 'address-remove', origin: args.origin });
+            log(`访问地址: ${args.action === 'add' ? '已添加' : '已删除'}`);
+            result.origins.forEach(origin => log(origin));
+            return 0;
+        }
+        if (args.action === 'status') {
+            const result = await client.request({ op: 'device-status' });
+            log(`可信设备保护: ${result.enabled ? '已开启' : '未开启'}`);
+            if (!result.enabled)
+                log(tokenWarning(t('auth.warning')));
+            log('ID\tNAME\tSTATUS\tEXPIRES\tADDED\tLAST ACCESS\tBROWSER');
+            result.devices.forEach(d => log(outputDevice(d)));
+            return 0;
+        }
+        if (args.action === 'on' || args.action === 'off') {
+            if (args.action === 'off' && interactive && !await ask(confirm({ message: t('auth.deviceDisableConfirm'), initialValue: false })))
+                throw canceled;
+            const result = await client.request({ op: 'device-policy', enabled: args.action === 'on' });
+            log(`可信设备保护: ${result.enabled ? '已开启' : '未开启'}`);
+            return 0;
+        }
+        if (args.action === 'list') {
+            const result = await client.request({ op: 'device-list' });
+            log('ID\tNAME\tSTATUS\tEXPIRES\tADDED\tLAST ACCESS\tBROWSER');
+            result.forEach(d => log(outputDevice(d)));
+            return 0;
+        }
+        if (args.action !== 'add') {
+            const result = await client.request({ op: `device-${args.action}`, id: args.id, name: args.name, expire: args.expire });
+            log('ID\tNAME\tSTATUS\tEXPIRES\tADDED\tLAST ACCESS\tBROWSER');
+            log(outputDevice(result));
+            return 0;
+        }
+        log(t('auth.safety'));
+        if (!args.code)
+            args.code = await ask(text({ message: t('auth.code'), validate: v => /^\d{6}$/.test(v ?? '') ? undefined : t('auth.codeInvalid') }));
+        const claimed = await client.request({ op: 'claim', code: args.code });
+        const needsPrompt = args.name === undefined || args.expire === undefined;
+        log(t('auth.claimed'));
+        log(safeText(claimed.browserSummary));
+        if (claimed.origin)
+            log(`${t('auth.origin')}: ${safeText(claimed.origin)}`);
+        if (args.name === undefined) {
+            const fallback = safeText(claimed.browserSummary).slice(0, 80) || 'Browser';
+            args.name = await ask(text({ message: t('auth.name'), defaultValue: fallback, placeholder: fallback, validate: v => { try {
+                    validateName(v || fallback);
+                }
+                catch (e) {
+                    return e instanceof DeviceAuthError && e.code === 'INVALID_NAME' ? t('auth.invalidName') : e.message;
+                } return undefined; } }));
+            args.name = args.name || fallback;
+        }
+        if (args.expire === undefined) {
+            const expire = await ask(select({ message: t('auth.expire'), initialValue: '30d', options: [
+                    ...['1h', '1d', '7d', '30d'].map(value => ({ value, label: value })),
+                    { value: 'custom', label: t('auth.custom') }, { value: 'never', label: t('auth.never') },
+                ] }));
+            args.expire = expire === 'custom' ? await ask(text({ message: t('auth.duration'), validate: v => { try {
+                    parseExpire(v);
+                }
+                catch (e) {
+                    return e instanceof DeviceAuthError && e.code === 'INVALID_EXPIRE' ? t('auth.invalidDuration') : e.message;
+                } return undefined; } })) : expire;
+        }
+        if (needsPrompt && !await ask(confirm({ message: t('auth.confirm'), initialValue: true })))
+            throw canceled;
+        const result = await client.request({ op: 'authorize', id: claimed.id, name: args.name, expire: args.expire });
+        log('ID\tNAME\tSTATUS\tEXPIRES\tADDED\tLAST ACCESS\tBROWSER');
+        log(outputDevice(result));
+        return 0;
+    }
+    catch (error) {
+        if (error === canceled)
+            err(t('auth.canceled'));
+        else if (error instanceof AuthControlError || error instanceof DeviceAuthError) {
+            err(t(controlErrorCopy[error.code] ?? 'auth.error.controlFailed'));
+        }
+        else
+            err(error instanceof Error ? safeText(error.message) : t('auth.error.controlFailed'));
+        return 1;
+    }
+    finally {
+        client?.close();
+    }
+}

package/dist/src/cli/authDefaults.js

@@ -0,0 +1,18 @@
+import fs from 'node:fs';
+import { configPath, readState, readSupervisorConfig, statePath, supervisorConfigPath } from './state.js';
+// Only the CLI has installation evidence. Pure config mappers must not guess whether {} is a
+// newcomer or an existing setup. Authentication policy itself is persisted by the server database.
+export function installationAuthDefaults(home, target = configPath(home), flags = {}, env = process.env) {
+    const state = readState(home);
+    const supervisor = readSupervisorConfig(home);
+    const hasConfig = fs.existsSync(target) || fs.existsSync(configPath(home));
+    const hasHistory = fs.existsSync(statePath(home)) || fs.existsSync(supervisorConfigPath(home));
+    const explicitToken = flags.token != null || env.HANDMUX_TOKEN != null;
+    const isNew = !hasConfig && !hasHistory && !explicitToken;
+    const token = [state?.token, supervisor?.token].find((value) => typeof value === 'string' && value.length > 0);
+    return { isNew, ...(typeof token === 'string' ? { token } : {}) };
+}
+// Keep this shared by access output: foreground, background, and already-running startup paths.
+export function tokenWarning(message, color = !!process.stdout.isTTY) {
+    return color ? `\u001b[33m${message}\u001b[39m` : message;
+}

package/dist/src/cli/claudeHooks.js

@@ -8,7 +8,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
-import { writeJsonAtomic, deployHookScripts, removeHookScripts } from './hookScaffold.js';
+import { writeJsonAtomic, deployHookScripts, removeHookScripts, shellWord } from './hookScaffold.js';
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 const settingsOf = (value) => isRecord(value) ? { ...value } : {};
 const readSettings = (home) => {
@@ -135,7 +135,7 @@ function addHook(hooks, e, dest) {
     dropOurHook(hooks, e.event);
     const existing = hooks[e.event];
     const groups = hooks[e.event] = Array.isArray(existing) ? [...existing] : [];
-    groups.push({ matcher: e.matcher || '', hooks: [{ type: 'command', command: `${dest} ${e.src}`, async: true, timeout: 5 }] });
+    groups.push({ matcher: e.matcher || '', hooks: [{ type: 'command', command: `${shellWord(dest)} ${e.src}`, async: true, timeout: 5 }] });
 }
 // Pure: return a NEW settings object with our six hooks merged into settings.hooks, idempotently, leaving
 // the user's own hooks and other keys untouched. `dest` is the absolute path to the copied notify script.
@@ -193,7 +193,7 @@ export function hooksStatus(home = homedir()) {
 }
 function hasExpectedHook(hooks, event, dest) {
     const groups = hooks[event.event];
-    const command = `${dest} ${event.src}`;
+    const command = `${shellWord(dest)} ${event.src}`;
     return Array.isArray(groups) && groups.some((group) => (isRecord(group)
         && group.matcher === (event.matcher || '')
         && Array.isArray(group.hooks)

package/dist/src/cli/hookScaffold.js

@@ -3,6 +3,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 export const HOOK_SCRIPTS = ['handmux-notify.sh', 'handmux-write.cjs'];
 const LEGACY_HOOK_SCRIPTS = ['handmux-codex-usage.cjs'];
+// Env files are sourced by /bin/sh; settings commands use the same shell word syntax.
+export const shellWord = (value) => /^[a-zA-Z0-9_./-]+$/.test(value)
+    ? value : `'${value.replace(/'/g, `'"'"'`)}'`;
 // Atomic write (tmp + rename) so a crash can't leave a half-written config file. Text in, text out — callers
 // pass raw TOML for config.toml, or use writeJsonAtomic for pretty-printed settings.json.
 export function writeFileAtomic(file, text) {
@@ -24,7 +27,8 @@ export function deployHookScripts(hooksDir, srcDir, stateFile) {
     }
     fs.chmodSync(path.join(hooksDir, 'handmux-notify.sh'), 0o755);
     fs.writeFileSync(path.join(hooksDir, 'handmux-notify.env'), [
-        `HANDMUX_STATE=${stateFile}`,
+        `HANDMUX_STATE=${shellWord(stateFile)}`,
+        `HANDMUX_CLAUDE_EVENTS=${shellWord(`${stateFile}.events`)}`,
         '',
     ].join('\n'), { mode: 0o600 });
 }

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

@@ -1,6 +1,48 @@
 // English catalog (the fallback locale). Keys are grouped by command/area. `{var}` placeholders are filled
 // by translate(). Keep this in lockstep with zh.js — a missing zh key silently falls back to the line here.
 export default {
+    'auth.section': 'Authentication & security',
+    'auth.trusted': 'Device protection',
+    'auth.token': 'Token login',
+    'auth.manageHint': 'Use the CLI for protection switches; view and manage devices and access addresses in Web settings.',
+    'auth.noDevices': 'No devices are authorized yet. Open Handmux in the target browser, then run handmux auth device add on this computer.',
+    'auth.access': 'Device authorization: open Handmux in the target browser, then run handmux auth device add here and follow the prompts.',
+    'auth.warning': '⚠ Trusted device protection is off: a Token alone is enough to access Handmux. We recommend running handmux auth device on to enable it.',
+    'auth.addressWarning': '⚠ Trusted address protection is off: any address can attempt to connect. We recommend running handmux auth address on to enable it.',
+    'auth.deviceDisableConfirm': '⚠ Turning off trusted device protection increases security risk: a Token alone will grant access. Confirm you want to turn it off?',
+    'auth.addressDisableConfirm': '⚠ Turning off trusted address protection increases security risk: any address can attempt to connect. Confirm you want to turn it off?',
+    'auth.code': 'Enter the 6-digit code shown in the target browser',
+    'auth.codeInvalid': 'Enter exactly 6 digits.',
+    'auth.claimed': 'The authorization request was found. Set a device name and duration within 5 minutes; the browser can sign in after you confirm.',
+    'auth.origin': 'Origin',
+    'auth.name': 'Device name',
+    'auth.expire': 'Authorization duration',
+    'auth.custom': 'Custom',
+    'auth.never': 'No expiry',
+    'auth.duration': 'Enter a duration such as 1h, 7d, 30d, or never',
+    'auth.confirm': 'Authorize this browser?',
+    'auth.canceled': 'This authorization was canceled.',
+    'auth.safety': 'Only confirm the browser you are adding. Never enter a code sent by someone else.',
+    'auth.invalidName': 'The device name must be 1–80 characters and contain no control characters.',
+    'auth.invalidDuration': 'Enter a duration such as 1h, 7d, 30d, or never.',
+    'auth.error.unavailable': 'Cannot reach the Handmux authorization service. Make sure Handmux is running, then try again.',
+    'auth.error.invalidCommand': 'That authorization operation is invalid. Try again.',
+    'auth.error.codeInvalid': 'The code is invalid, expired, or already used. Request a new code in the browser.',
+    'auth.error.rateLimit': 'Too many code attempts. Try again later.',
+    'auth.error.pairingGone': 'This authorization request no longer exists or has expired. Request a new code in the browser.',
+    'auth.error.deviceNotFound': 'Device not found. Run handmux auth device list to check the device ID.',
+    'auth.error.deviceInactive': 'This device has expired or been unbound. Authorize it again.',
+    'auth.error.conflict': 'The device was changed by another operation. List devices again, then retry.',
+    'auth.error.invalidEdit': 'Provide at least --name or --expire.',
+    'auth.error.invalidVersion': 'The device was updated. List devices again, then retry.',
+    'auth.error.pairingCapacity': 'There are too many pending authorization requests. Try again later.',
+    'auth.error.tokenRequired': 'Provide the Token before starting authorization.',
+    'auth.error.deviceRequired': 'Authorize this browser before enabling device protection.',
+    'auth.error.expiryCliOnly': 'Change device expiry with the handmux CLI on the server.',
+    'auth.error.invalidOrigin': 'Invalid access address. Provide a complete http(s) URL.',
+    'auth.error.originLimit': 'The trusted access-address limit has been reached. Remove one before adding another.',
+    'auth.error.sessionInvalid': 'This device authorization is no longer valid. Pair it again.',
+    'auth.error.controlFailed': 'The authorization operation did not complete. Check Handmux status, then try again.',
     // generic
     'err.generic': '✗ {msg}',
     'err.configNotFound': '✗ --config {path}: not found',
@@ -108,7 +150,7 @@ export default {
     'access.pending': '(pending…)',
     'access.lan': '  📶 lan    {url}',
     'access.local': '  💻 local  {url}',
-    'access.token': '  🔑 token  {token}',
+    'access.token': '  🔑 Token login  {token}',
     'access.reachable': '  ✓ reachable',
     'access.unreachable': '  ⚠ tunnel up but {url} did not answer — check the server-side reverse proxy / DNS',
     'access.hint': '  handmux status | stop',
@@ -179,6 +221,7 @@ export default {
     'setup.askSshHost': 'ssh host (user@host[:port])',
     'setup.askRemotePort': 'remote port on the ssh host',
     'setup.askPublicUrl': 'public url — http(s):// as appropriate (blank = http://host:remotePort)',
+    'setup.askDirectPublicUrl': 'custom access URL (your own reverse tunnel or proxy; blank = local/LAN direct only)',
     'setup.natappGuide': 'Where to get the authtoken: register free at https://natapp.cn → create a tunnel → copy its authtoken (the free tier is enough to start).',
     'setup.cpolarGuide': 'Where to get the authtoken: register free at https://cpolar.com → open the dashboard → Verify → copy your authtoken.',
     'setup.askAuthtoken': 'authtoken',
@@ -194,19 +237,19 @@ export default {
     'setup.secConnection': 'Connection',
     'setup.secName': 'Name',
     'setup.secPort': 'Port',
-    'setup.secToken': 'Token',
+    'setup.secToken': 'Token login',
     'setup.secBrowser': 'Web preview',
     'setup.browserOff': 'not configured · Direct mode only',
     'setup.askBrowserDomain': 'Web preview proxy domain (blank = Direct mode only)',
     'setup.browserAbout': 'Enter a proxy domain (for example, preview.example.com) and route its wildcard subdomains to Handmux over HTTPS; leave it blank for Direct mode only.',
-    'setup.tokenAuto': 'auto · new each start',
-    'setup.tokenCustom': 'Set a custom token…',
-    'setup.tokenRandom': 'Generate a random one',
-    'setup.tokenReset': 'Reset to auto (new each start)',
-    'setup.askToken': 'Access token — it appears in the URL you open on the phone',
-    'setup.tokenGenerated': 'New token: {token}',
-    'setup.valToken': 'enter a token',
-    'setup.valTokenSpace': 'no spaces — the token goes in a URL',
+    'setup.tokenAuto': 'saved (the Token does not rotate automatically)',
+    'setup.tokenCustom': 'Change the Token…',
+    'setup.tokenRandom': 'Generate and save a new random Token',
+    'setup.tokenReset': 'The Token does not rotate automatically',
+    'setup.askToken': 'Token — required together with a trusted device',
+    'setup.tokenGenerated': 'New Token: {token}',
+    'setup.valToken': 'enter the Token',
+    'setup.valTokenSpace': 'no spaces — enter the Token separately on the login page',
     'setup.secLanguage': 'CLI language / 命令行语言',
     'setup.secPush': 'Push',
     'setup.secVoice': 'Voice',
@@ -236,6 +279,7 @@ export default {
     'setup.valRequired': '{label} is required',
     'setup.valHost': 'enter a valid domain (e.g. myapp.example.com)',
     'setup.valPreviewDomain': 'enter only a domain, e.g. preview.example.com; do not include http://, https://, a port, or *.',
+    'setup.valPublicUrl': 'enter a complete http(s) origin such as https://handmux.example.com (no path or credentials)',
     'setup.valContact': 'use mailto:you@example.com or https://your.site (a real domain — Apple rejects fake ones)',
     'setup.sumTemp': 'temporary',
     'setup.sumFixed': 'fixed',
@@ -248,6 +292,7 @@ export default {
     'setup.connSshHost': 'SSH host',
     'setup.connRemotePort': 'Remote port',
     'setup.connPublicUrl': 'Public URL',
+    'setup.connDirectAuto': '(blank = local / LAN direct)',
     'setup.connJump': 'Jump host',
     'setup.connDomain': 'Domain',
     'setup.connRegion': 'Region',
@@ -357,6 +402,16 @@ export default {
   handmux stop | restart | status
   handmux logs [--follow] [--lines N]
   handmux push <title> <body>   notify your phone from a script (--session X · --device K · --tag T · --url U)
+  handmux auth device status   show device protection status and devices
+  handmux auth device on|off   turn device protection on or off
+  handmux auth device add      interactively authorize a browser (automation uses --code, --name and --expire)
+  handmux auth device list     list full device IDs, names, expiry and access times
+  handmux auth device edit <id>   update the device name or expiry
+  handmux auth device revoke <id>  revoke a device immediately
+  handmux auth address status  show trusted address protection status and addresses
+  handmux auth address on|off  turn trusted address protection on or off
+  handmux auth address add <origin>     add an access address
+  handmux auth address remove <origin>  remove an access address
   handmux codex [args...]       launch a Codex TUI synchronized with chat view
   handmux pi [args...]          launch Pi with its arguments unchanged
   handmux agent [list]          show supported Agent integrations
@@ -384,7 +439,7 @@ start flags (matching env var in parens):
   --tunnel none|cloudflare|cloudflare-named|ssh|natapp|cpolar   expose method (default: none)
   --port N                      server port (HANDMUX_PORT, default: 19999)
   --host H                      bind host (HANDMUX_HOST, default: 0.0.0.0)
-  --token S                     auth token (HANDMUX_TOKEN, default: generated each start)
+  --token S                     auth token (HANDMUX_TOKEN, default: reuse existing or generate)
   --name "My Box"               app name in the browser tab + home-screen icon (HANDMUX_APP_NAME)
   --public-url URL              public url to advertise (HANDMUX_PUBLIC_URL; any tunnel, incl. none if
                                 you run your own; ssh defaults to http://host:remotePort; for