hop2 0.11.2 → 0.11.4

package/hop

@@ -16,6 +16,11 @@ const net = require('net');
 const WebSocket = require('ws');
 const { resolveActorFromHeaders, canActorAccessSession } = require('./lib/terminal-access');
 const { generateSessionName, getThemeChoices, isValidTheme, DEFAULT_THEME } = require('./lib/naming-themes');
+const {
+    createFailureTracker,
+    createSingleFlight,
+    sameHostIncarnation
+} = require('./lib/hay-host-watchdog');
 
 const os = require('os');
 const DAEMON_FLAG = process.argv.includes('--daemon');
@@ -323,6 +328,8 @@ const HAY_HOST_DISCOVERY_CACHE_MS = parsePositiveIntEnv('HOP_HAY_HOST_DISCOVERY_
 const HAY_HOST_HOME_HASH = crypto.createHash('sha256').update(path.resolve(HOME_DIR)).digest('hex').slice(0, 24);
 const HAY_HOST_HOME_FLAG = `--hop-home-hash=${HAY_HOST_HOME_HASH}`;
 let hayHostState = null;
+const hayHostInspectionFlight = createSingleFlight();
+const hayHostEnsureFlight = createSingleFlight();
 // Session content search: per-room ANSI-stripped tail, cached briefly so a
 // typing burst in the switcher re-greps without re-fetching from the host.
 const sessionSearchTextCache = new Map();
@@ -352,7 +359,25 @@ function stripAnsiForSearch(raw) {
 // only after this many consecutive failed probes spanning at least the window.
 const HAY_HOST_UNRESPONSIVE_PROBES = 3;
 const HAY_HOST_UNRESPONSIVE_WINDOW_MS = 60_000;
-let hayHostProbeFailures = { pid: 0, count: 0, firstAt: 0 };
+const hayHostProbeFailures = createFailureTracker({
+    requiredFailures: HAY_HOST_UNRESPONSIVE_PROBES,
+    windowMs: HAY_HOST_UNRESPONSIVE_WINDOW_MS
+});
+const HAY_HOST_DAEMON_STALL_THRESHOLD_MS = 2000;
+const HAY_HOST_DAEMON_STALL_HOLD_MS = HAY_HOST_UNRESPONSIVE_WINDOW_MS;
+let lastDaemonEventLoopStall = { at: 0, driftMs: 0 };
+if (DAEMON_FLAG) {
+    const intervalMs = 1000;
+    let expectedAt = Date.now() + intervalMs;
+    setInterval(() => {
+        const at = Date.now();
+        const driftMs = Math.max(0, at - expectedAt);
+        expectedAt = at + intervalMs;
+        if (driftMs >= HAY_HOST_DAEMON_STALL_THRESHOLD_MS) {
+            lastDaemonEventLoopStall = { at, driftMs };
+        }
+    }, intervalMs).unref();
+}
 // Serialize host spawning across concurrent ensure calls / processes: without
 // this, N racing `hop` invocations that each see "no host" spawn N hosts
 // (observed: four in one second), scattering sessions across orphans.
@@ -366,6 +391,12 @@ function parsePositiveIntEnv(name, fallback) {
     return parsed;
 }
 
+function getRecentDaemonEventLoopStall() {
+    if (!lastDaemonEventLoopStall.at) return null;
+    if (Date.now() - lastDaemonEventLoopStall.at > HAY_HOST_DAEMON_STALL_HOLD_MS) return null;
+    return { ...lastDaemonEventLoopStall };
+}
+
 // Password hashing using scrypt (built-in, no external deps)
 function hashPassword(password) {
     const salt = crypto.randomBytes(16).toString('hex');
@@ -658,13 +689,60 @@ function getRuntimeSessionMetadata(name) {
     return runtimeSessionMetadata.get(name) || null;
 }
 
+// Durable meta is read on every effective-config lookup, so a tiny cache
+// keeps it off the hot path. Invalidated by mtime, so an external write
+// (the hook, another process) is picked up without a restart.
+const durableIdentityCache = new Map();
+function readDurableIdentity(name) {
+    if (!name || !SESSION_NAME_RE.test(name)) return null;
+    let mtimeMs = 0;
+    try {
+        mtimeMs = fs.statSync(path.join(CLAUDE_SESSIONS_DIR, `${name}.meta`)).mtimeMs;
+    } catch (e) {
+        durableIdentityCache.delete(name);
+        return null;
+    }
+    const hit = durableIdentityCache.get(name);
+    if (hit && hit.mtimeMs === mtimeMs) return hit.value;
+    const value = readClaudeSessionMeta(name);
+    durableIdentityCache.set(name, { mtimeMs, value });
+    return value;
+}
+
+// THE identity accessor. Everything that asks "what is this session called,
+// where is it filed, who made it" comes through here.
+//
+// The layers are not peers. saved/runtime configs are CACHES that any code
+// path may recreate with defaults — `hop restore` writes one per session
+// with the INTERNAL name — while durable meta is where a user's own answers
+// are recorded and the only layer that survives the daemon. Merging
+// saved-over-runtime and stopping there meant a crash + restore silently
+// reverted every rename and un-filed every folder, because restore's freshly
+// written cache outranked the file that knew better. Meta wins for the
+// user-authored fields; everything else keeps the old precedence.
 function getEffectiveSessionConfig(name) {
     const saved = getSessionConfig(name);
     const runtime = getRuntimeSessionMetadata(name);
-    if (saved && runtime) {
-        return { ...runtime, ...saved };
+    const base = saved && runtime ? { ...runtime, ...saved } : (saved || runtime || null);
+    const durable = readDurableIdentity(name);
+    if (!durable) return base;
+    if (!base) {
+        return {
+            type: 'terminal',
+            displayName: durable.displayName,
+            folderId: durable.folderId,
+            createdBy: durable.createdBy,
+            cwd: durable.cwd
+        };
     }
-    return saved || runtime || null;
+    const merged = { ...base };
+    if (durable.displayName) merged.displayName = durable.displayName;
+    if (durable.folderId !== undefined) merged.folderId = durable.folderId || null;
+    if (durable.createdBy) merged.createdBy = durable.createdBy;
+    if (durable.tagline) merged.tagline = durable.tagline;
+    if (durable.parked !== undefined) merged.parked = durable.parked;
+    if (durable.archived !== undefined) merged.archived = durable.archived;
+    return merged;
 }
 
 function hasSavedSessionConfig(name) {
@@ -711,16 +789,34 @@ function getSessionDisplayName(name) {
     return toDisplaySessionName(name);
 }
 
+// Name lookups are case-insensitive: an exact-case wearer always wins, and
+// otherwise a UNIQUE case-insensitive wearer resolves. Two sessions whose
+// names differ only by case are ambiguous — that falls back to exact-only
+// rather than guessing which one the caller meant.
+function sameNameFold(a, b) {
+    return typeof a === 'string' && typeof b === 'string' && a.toLowerCase() === b.toLowerCase();
+}
+
 function findInternalSessionName(displayName) {
     if (!displayName) return null;
+    let folded = null;
+    let foldedAmbiguous = false;
+    const noteFolded = (name, current) => {
+        if (!sameNameFold(current, displayName)) return;
+        if (folded && folded !== name) foldedAmbiguous = true;
+        else folded = name;
+    };
     for (const [name, config] of Object.entries(sessionStore.sessions)) {
         const current = config?.displayName || toDisplaySessionName(name);
         if (current === displayName) return name;
+        noteFolded(name, current);
     }
     for (const [name, config] of runtimeSessionMetadata.entries()) {
-        if ((config?.displayName || name) === displayName) return name;
+        const current = config?.displayName || name;
+        if (current === displayName) return name;
+        noteFolded(name, current);
     }
-    return null;
+    return foldedAmbiguous ? null : folded;
 }
 
 // "In use" means a session ACTUALLY WEARS this name right now, or the name is
@@ -1994,6 +2090,9 @@ function saveHopConfig(config) {
 // session should be the session you left, not a summary of it. Set
 // resume_mode to "summary" (cheaper) or "ask" (leave the prompt alone).
 const RESUME_PROMPT_RE = /Resuming the full session|Resume from summary|Resume full session as-is/i;
+// Claude Code's own chrome — proof the app is up even when the room reports
+// the wrapper shell as its foreground process (argv launch).
+const CLAUDE_UI_RE = /bypass permissions on|shift\+tab to cycle|Welcome back|esc to interrupt|\? for shortcuts/i;
 function getResumeMode() {
     const mode = String(getHopConfig().resume_mode || '').toLowerCase();
     return mode === 'summary' || mode === 'ask' ? mode : 'full';
@@ -3023,12 +3122,13 @@ async function listActiveSessionsRuntimeFirst() {
     if (!isExternalTerminalBackend()) {
         return { sessions: listActiveSessions(), runtimeAvailable: true };
     }
+    let reconciled;
     try {
-        await reconcileExternalRuntimeSessions();
+        reconciled = await reconcileExternalRuntimeSessions();
     } catch (e) {
         return { sessions: [], runtimeAvailable: false };
     }
-    const runtimeRooms = await fetchExternalHayRuntimeRooms();
+    const runtimeRooms = reconciled?.rooms;
     if (!Array.isArray(runtimeRooms)) {
         return { sessions: [], runtimeAvailable: false };
     }
@@ -3196,8 +3296,16 @@ function buildSessionEntries(haySessions, opts = {}) {
         if (type !== 'port' && !includeStoredTerminalSessions && !sessionMap.has(name)) {
             continue;
         }
-        const displayName = config?.displayName || toDisplaySessionName(name);
-        const folderId = config?.folderId || null;
+        // Identity fields go through THE accessor, not this raw store entry.
+        // Reading the store directly silently reverted renames and un-filed
+        // folders whenever a recreated cache (e.g. restore's fresh session
+        // definitions) lacked them — the durable meta knew better the whole
+        // time, and the overwrite branch below was clobbering the correct
+        // value the live-rooms loop had already computed.
+        const effective = getEffectiveSessionConfig(name) || config;
+        const displayName = effective?.displayName || toDisplaySessionName(name);
+        const folderId = effective?.folderId || null;
+        const createdBy = effective?.createdBy || 'user';
         const clientSummary = getSessionClientSummary(name);
         if (!sessionMap.has(name)) {
             sessionMap.set(name, {
@@ -3219,7 +3327,7 @@ function buildSessionEntries(haySessions, opts = {}) {
                 startup: config?.startup,
                 autoStart: config?.autoStart,
                 createdAt: config?.createdAt,
-                createdBy: config?.createdBy || 'user',
+                createdBy,
                 agentPermitted: config?.agentPermitted === true,
                 localCliCount: clientSummary.localCliCount,
                 hasLocalCli: clientSummary.hasLocalCli
@@ -3246,7 +3354,7 @@ function buildSessionEntries(haySessions, opts = {}) {
             entry.startup = config?.startup;
             entry.autoStart = config?.autoStart;
             entry.createdAt = config?.createdAt;
-            entry.createdBy = config?.createdBy || 'user';
+            entry.createdBy = createdBy;
             entry.agentPermitted = config?.agentPermitted === true;
             entry.localCliCount = localCliCount;
             entry.hasLocalCli = clientSummary.hasLocalCli || localCliCount > 0 || entry.hasLocalCli === true;
@@ -3257,8 +3365,11 @@ function buildSessionEntries(haySessions, opts = {}) {
         if (!name || sessionMap.has(name)) continue;
         const type = config?.type || 'terminal';
         if (type !== 'port' && !includeStoredTerminalSessions) continue;
-        const displayName = config?.displayName || toDisplaySessionName(name);
-        const folderId = config?.folderId || null;
+        // Same rule as above: identity via THE accessor, mechanics from the
+        // runtime cache.
+        const effective = getEffectiveSessionConfig(name) || config;
+        const displayName = effective?.displayName || toDisplaySessionName(name);
+        const folderId = effective?.folderId || null;
         const clientSummary = getSessionClientSummary(name);
         sessionMap.set(name, {
             name,
@@ -3279,7 +3390,7 @@ function buildSessionEntries(haySessions, opts = {}) {
             startup: config?.startup,
             autoStart: config?.autoStart,
             createdAt: config?.createdAt,
-            createdBy: config?.createdBy || 'user',
+            createdBy: effective?.createdBy || 'user',
             agentPermitted: config?.agentPermitted === true,
             localCliCount: clientSummary.localCliCount,
             hasLocalCli: clientSummary.hasLocalCli
@@ -3839,7 +3950,9 @@ function writeClaudeSessionRecord(internalName, rec) {
     if (!internalName || !SESSION_NAME_RE.test(internalName)) return;
     try { fs.mkdirSync(CLAUDE_SESSIONS_DIR, { recursive: true }); } catch (e) { /* best effort */ }
     try {
-        fs.writeFileSync(path.join(CLAUDE_SESSIONS_DIR, `${internalName}.json`), JSON.stringify(rec), { mode: 0o600 });
+        // Same crash-safety as the metas: records are what lets a claude
+        // conversation resume at all.
+        writePrivateFile(path.join(CLAUDE_SESSIONS_DIR, `${internalName}.json`), JSON.stringify(rec), 0o600);
     } catch (e) { /* best effort */ }
 }
 
@@ -3881,7 +3994,14 @@ function writeClaudeSessionMeta(internalName, meta) {
     if (!internalName || !SESSION_NAME_RE.test(internalName)) return;
     try { fs.mkdirSync(CLAUDE_SESSIONS_DIR, { recursive: true }); } catch (e) { /* best effort */ }
     try {
-        fs.writeFileSync(path.join(CLAUDE_SESSIONS_DIR, `${internalName}.meta`), JSON.stringify(meta), { mode: 0o600 });
+        // ATOMIC + FSYNCED, not writeFileSync. The thermal-sleep crash proved
+        // the difference with a natural experiment: folders.json (written via
+        // writePrivateFile the same night) SURVIVED, while every meta
+        // rewritten in the prior three days — every rename, every folder
+        // filing — vanished with the un-fsynced page cache. These files are
+        // the restore inventory; they are exactly the data that must outlive
+        // a power cut.
+        writePrivateFile(path.join(CLAUDE_SESSIONS_DIR, `${internalName}.meta`), JSON.stringify(meta), 0o600);
     } catch (e) { /* best effort */ }
 }
 
@@ -4276,6 +4396,35 @@ async function restoreSavedSessionsUnlocked({ dryRun = false, includeAgents = fa
                 // a second copy on top of it (that is how command lines piled
                 // up in a shell that was busy booting).
                 if (running) { finish('already-running'); continue; }
+                // Same blindness applies before typing: a session whose
+                // command was launched as argv shows a shell here while
+                // claude runs beneath it. Typing again would land keystrokes
+                // in claude's own prompt. And ABSENCE of claude chrome is not
+                // enough — under a many-session restore storm claude can take
+                // longer than every timeout to paint its first frame, and the
+                // typed "fallback" landed the whole relaunch command in the
+                // composer of the claude that then finished booting. The only
+                // screen that may be typed into is one POSITIVELY showing an
+                // idle shell prompt.
+                let promptVisible = false;
+                try {
+                    const grid = await getRoomGridPreviewShared(job.plan.internalName);
+                    const text = String(grid?.text || '');
+                    if (RESUME_PROMPT_RE.test(text) || CLAUDE_UI_RE.test(text)) {
+                        job.state = 'verify';
+                        job.since = Date.now();
+                        continue;
+                    }
+                    const lines = text.split('\n').map((l) => l.trimEnd()).filter((l) => l.trim() !== '');
+                    const last = lines.length ? lines[lines.length - 1] : '';
+                    promptVisible = /[%$#❯>]\s*$/.test(last);
+                } catch (e) { /* host busy — treat as not visible */ }
+                if (!promptVisible) {
+                    // Nothing to safely type into (blank screen, app booting).
+                    // Keep waiting; the verify deadline bounds the wait.
+                    if (Date.now() - job.since > 30_000) { finish('never-started'); }
+                    continue;
+                }
                 // A fresh shell reports its own name once it has execed; that
                 // is our prompt-ready signal, and it beats guessing with a timer.
                 if (Date.now() - job.since < 400) continue;
@@ -4287,7 +4436,25 @@ async function restoreSavedSessionsUnlocked({ dryRun = false, includeAgents = fa
                 continue;
             }
             if (job.state === 'verify') {
-                if (running) {
+                // "Is it running?" cannot be answered by the foreground
+                // process alone. Argv launch runs `shell -lc "<cmd>; exec
+                // shell -l"`, so the foreground process is the WRAPPER SHELL
+                // for the whole life of the command — the very mechanism that
+                // replaced typing made the process check blind. After the
+                // crash restore, claude was sitting at its own resume prompt
+                // while this loop reported "never-started", retyped the
+                // command into that prompt, and gave up without answering it.
+                // The screen is the honest witness: a resume prompt, or
+                // claude's own chrome, means it is up.
+                let screenSaysRunning = false;
+                if (!running) {
+                    try {
+                        const grid = await getRoomGridPreviewShared(job.plan.internalName);
+                        const text = String(grid?.text || '');
+                        screenSaysRunning = RESUME_PROMPT_RE.test(text) || CLAUDE_UI_RE.test(text);
+                    } catch (e) { /* host busy — try again next tick */ }
+                }
+                if (running || screenSaysRunning) {
                     const key = resumeChoiceKey(getResumeMode());
                     if (!key) { finish('resumed'); continue; }
                     job.state = 'answer-prompt';
@@ -4502,13 +4669,29 @@ function removeClaudeHook() {
 }
 
 // Resolve display name aliases (follows rename chain)
+// Alias keys resolve case-insensitively too (unique match only), so a
+// remembered old name keeps working however the caller cases it.
+function lookupSessionAliasKey(name) {
+    if (sessionAliases[name] !== undefined) return name;
+    let match = null;
+    for (const key of Object.keys(sessionAliases)) {
+        if (sameNameFold(key, name)) {
+            if (match !== null) return null; // ambiguous — exact only
+            match = key;
+        }
+    }
+    return match;
+}
+
 function resolveDisplayNameAlias(name) {
     if (!name || typeof name !== 'string') return name;
     let current = name;
     const seen = new Set();
-    while (sessionAliases[current] && !seen.has(current)) {
+    while (!seen.has(current)) {
+        const key = lookupSessionAliasKey(current);
+        if (key === null || sessionAliases[key] === undefined) break;
         seen.add(current);
-        current = sessionAliases[current];
+        current = sessionAliases[key];
     }
     return current;
 }
@@ -4895,10 +5078,16 @@ function resolveSessionDisplayName(displayName) {
     const fallbackInternalName = toInternalSessionName(resolvedDisplayName);
     const fallbackExists = !!fallbackInternalName
         && (hopSessionExists(fallbackInternalName) || !!getEffectiveSessionConfig(fallbackInternalName));
+    // A case-insensitive hit canonicalizes to the name the session actually
+    // wears, so /s/titan redirects to /s/Titan instead of serving the same
+    // session under a differently-cased twin URL.
+    const canonicalDisplayName = internalFromConfig
+        ? (getSessionDisplayName(internalFromConfig) || resolvedDisplayName)
+        : resolvedDisplayName;
     return {
-        displayName: resolvedDisplayName,
+        displayName: canonicalDisplayName,
         internalName: internalFromConfig || (fallbackExists ? fallbackInternalName : null),
-        aliasRedirect: resolvedDisplayName !== displayName
+        aliasRedirect: canonicalDisplayName !== displayName
     };
 }
 
@@ -4990,6 +5179,14 @@ const resolveVia = (req) => {
 };
 
 function resolveActor(req) {
+    const declared = String(req?.headers?.[ACTOR_HEADER] || '').toLowerCase();
+    if (declared === 'agent' || declared === 'user') return declared;
+    // Undeclared: infer from the auth path. Cookie = a human in the web UI.
+    // Bearer token without the hop CLI's via stamp = automation.
+    if (req?.hopAuthVia === 'token') {
+        const via = String(req?.headers?.[VIA_HEADER] || '').toLowerCase();
+        if (via !== 'cli' && via !== 'web') return 'agent';
+    }
     return resolveActorFromHeaders(req?.headers || {}, ACTOR_HEADER);
 }
 
@@ -5091,7 +5288,8 @@ function writeHayHostStateFile(state) {
     const changed = !hayHostState
         || hayHostState.pid !== state.pid
         || hayHostState.port !== state.port;
-    if (!changed) return;
+    const missingStateFile = !fs.existsSync(HAY_HOST_STATE_FILE);
+    if (!changed && !missingStateFile) return;
     hayHostState = {
         pid: state.pid,
         port: state.port,
@@ -5109,7 +5307,11 @@ function writeHayHostStateFile(state) {
     writePrivateFile(HAY_HOST_STATE_FILE, JSON.stringify(hayHostState));
 }
 
-function clearHayHostStateFile() {
+function clearHayHostStateFile(expectedState = null) {
+    if (expectedState) {
+        const registered = readHayHostStateFile();
+        if (!sameHostIncarnation(registered, expectedState)) return false;
+    }
     hayHostState = null;
     hayHostDiscoveryCache = { expiresAt: 0, hosts: [] };
     try {
@@ -5117,6 +5319,7 @@ function clearHayHostStateFile() {
             fs.unlinkSync(HAY_HOST_STATE_FILE);
         }
     } catch (e) { }
+    return true;
 }
 
 function parseListeningPortForPid(pid) {
@@ -6077,9 +6280,25 @@ function syncSessionMetaFromRooms(rooms) {
     for (const room of rooms) {
         if (!room || typeof room.id !== 'string' || !SESSION_NAME_RE.test(room.id)) continue;
         const cwd = typeof room.cwd === 'string' ? room.cwd : '';
-        if (!cwd) continue;
         const existing = readClaudeSessionMeta(room.id);
-        if (existing && existing.cwd === cwd) continue;
+        // A room with no cwd used to be skipped entirely — so it never got a
+        // durable meta, and a session that only ever lived in the host's
+        // memory was UNRECOVERABLE the moment the host died: `hop restore`
+        // reads this directory, and a session absent from it cannot even be
+        // named, let alone relaunched. That is how a thermal-sleep crash took
+        // ten sessions with no trace. Every live room now leaves a record;
+        // cwd is filled in when it becomes known.
+        if (!existing) {
+            writeClaudeSessionMeta(room.id, {
+                internalName: room.id,
+                ...(cwd ? { cwd } : {}),
+                createdAt: new Date().toISOString(),
+                updatedAt: new Date().toISOString()
+            });
+            continue;
+        }
+        if (!cwd) continue;
+        if (existing.cwd === cwd) continue;
         // Carry an origin we already know; never invent one. This pass exists
         // to backfill cwd, and defaulting createdBy to 'user' here silently
         // stamped "human" onto every agent session whose origin lived only in
@@ -6152,7 +6371,7 @@ function choosePreferredHayHost(inspectedHosts, preferredHost = null) {
     return ranked[0]?.host || null;
 }
 
-async function inspectExternalHayHosts(force = false) {
+async function inspectExternalHayHostsOnce(force = false) {
     if (!isExternalTerminalBackend()) return [];
     const candidates = listDiscoveredHayHostCandidates(force);
     if (candidates.length === 0) return [];
@@ -6160,7 +6379,10 @@ async function inspectExternalHayHosts(force = false) {
         const __h0 = Date.now();
         const healthy = await probeExternalHayHostFromHost(host);
         const __h1 = Date.now();
-        const rooms = await fetchExternalHayRuntimeRoomsFromHost(host);
+        // A failed liveness probe must not enqueue an expensive /rooms walk
+        // behind it. The fallback watchdog probe below decides whether a known
+        // host is merely slow; room enumeration never decides whether to kill.
+        const rooms = healthy ? await fetchExternalHayRuntimeRoomsFromHost(host) : null;
         const __h2 = Date.now();
         if (__h2 - __h0 > 150) log(`[perf] inspect host pid=${host.pid} port=${host.port}: probe=${__h1-__h0}ms rooms=${__h2-__h1}ms`, YELLOW);
         return { host, healthy, rooms };
@@ -6168,6 +6390,11 @@ async function inspectExternalHayHosts(force = false) {
     return inspected.filter((entry) => entry.healthy === true && Array.isArray(entry.rooms));
 }
 
+async function inspectExternalHayHosts(force = false) {
+    if (force) return await inspectExternalHayHostsOnce(true);
+    return await hayHostInspectionFlight.run(() => inspectExternalHayHostsOnce(false));
+}
+
 function hostBelongsToCurrentHome(entry, preferredHost = null) {
     if (!entry || !entry.host) return false;
     if (typeof entry.host.homeHash === 'string') {
@@ -6187,7 +6414,12 @@ function getExternalHayHostStateOrThrow() {
         hayHostState = readHayHostStateFile();
     }
     if (!hayHostState || !isProcessAlive(hayHostState.pid)) {
-        clearHayHostStateFile();
+        const registered = readHayHostStateFile();
+        if (registered && isProcessAlive(registered.pid)) {
+            hayHostState = registered;
+            return registered;
+        }
+        clearHayHostStateFile(registered || null);
         throw new Error('External hay host is not running');
     }
     return hayHostState;
@@ -6219,18 +6451,25 @@ async function stopExternalHayHostProcess(hostState, timeoutMs = 1500) {
     return !isProcessAlive(pid);
 }
 
-async function ensureExternalHayHostReady() {
-    if (!isExternalTerminalBackend()) return null;
+function markExternalHayHostResponsive(host) {
+    const recovered = hayHostProbeFailures.recordSuccess(Number(host?.pid));
+    if (recovered) {
+        log(`[Hay] Host ${host.pid} responsive again after ${recovered.count} failed probe(s).`, DIM);
+    }
+    writeHayHostStateFile(host);
+    return host;
+}
 
+async function ensureExternalHayHostReadyOnce() {
     const existing = hayHostState || readHayHostStateFile();
     const inspectedExisting = await inspectExternalHayHosts();
     const relevantExisting = inspectedExisting.filter((entry) => hostBelongsToCurrentHome(entry, existing));
     const preferredExisting = choosePreferredHayHost(relevantExisting, existing);
     if (preferredExisting) {
-        writeHayHostStateFile(preferredExisting);
-        return preferredExisting;
+        return markExternalHayHostResponsive(preferredExisting);
     }
 
+    let stateCleared = false;
     if (existing && isProcessAlive(existing.pid)) {
         // Generous timeout: a host mid-GC or briefly saturated is SLOW, not
         // dead — and "restarting" it kills every live PTY. Only a host that
@@ -6239,29 +6478,58 @@ async function ensureExternalHayHostReady() {
         // alive beats dead).
         const healthy = await probeExternalHayHostFromHost(existing, 5000);
         if (healthy) {
-            if (hayHostProbeFailures.pid === existing.pid && hayHostProbeFailures.count > 0) {
-                log(`[Hay] Host ${existing.pid} responsive again after ${hayHostProbeFailures.count} failed probe(s).`, DIM);
-            }
-            hayHostProbeFailures = { pid: 0, count: 0, firstAt: 0 };
+            return markExternalHayHostResponsive(existing);
+        }
+        const failure = hayHostProbeFailures.recordFailure(existing.pid);
+        if (!failure.shouldRestart) {
+            log(`[Hay] Host ${existing.pid} (port ${existing.port}) slow: probe timed out (${failure.count}/${HAY_HOST_UNRESPONSIVE_PROBES} over ${Math.round(failure.failingForMs / 1000)}s). Keeping it alive.`, YELLOW);
             writeHayHostStateFile(existing);
             return existing;
         }
-        if (hayHostProbeFailures.pid !== existing.pid) {
-            hayHostProbeFailures = { pid: existing.pid, count: 0, firstAt: Date.now() };
-        }
-        hayHostProbeFailures.count += 1;
-        const failingForMs = Date.now() - hayHostProbeFailures.firstAt;
-        if (hayHostProbeFailures.count < HAY_HOST_UNRESPONSIVE_PROBES || failingForMs < HAY_HOST_UNRESPONSIVE_WINDOW_MS) {
-            log(`[Hay] Host ${existing.pid} (port ${existing.port}) slow: probe timed out (${hayHostProbeFailures.count}/${HAY_HOST_UNRESPONSIVE_PROBES} over ${Math.round(failingForMs / 1000)}s). Keeping it alive.`, YELLOW);
+        const daemonStall = getRecentDaemonEventLoopStall();
+        if (daemonStall) {
+            log(`[Hay] Host ${existing.pid} is slow while the daemon also stalled ~${Math.round(daemonStall.driftMs)}ms. Resetting the watchdog window and keeping the host alive.`, YELLOW);
+            hayHostProbeFailures.reset();
             writeHayHostStateFile(existing);
             return existing;
         }
-        log(`[Hay] Host ${existing.pid} (port ${existing.port}) unresponsive for ${Math.round(failingForMs / 1000)}s (${hayHostProbeFailures.count} failed probes). Restarting it.`, YELLOW);
-        hayHostProbeFailures = { pid: 0, count: 0, firstAt: 0 };
-        await stopExternalHayHostProcess(existing);
+
+        // Every await above gives another process a chance to publish a new host.
+        // Never apply a destructive decision to a state generation we no longer
+        // own, even if the old PID is still around.
+        const registeredBeforeStop = readHayHostStateFile();
+        if (!sameHostIncarnation(registeredBeforeStop, existing)) {
+            hayHostProbeFailures.reset();
+            log(`[Hay] Host state changed while probing ${existing.pid}; aborting the stale restart.`, YELLOW);
+            if (registeredBeforeStop && isProcessAlive(registeredBeforeStop.pid)
+                && await probeExternalHayHostFromHost(registeredBeforeStop, 1500)) {
+                return markExternalHayHostResponsive(registeredBeforeStop);
+            }
+            return existing;
+        }
+
+        log(`[Hay] Host ${existing.pid} (port ${existing.port}) unresponsive for ${Math.round(failure.failingForMs / 1000)}s (${failure.count} failed probes). Restarting it.`, YELLOW);
+        hayHostProbeFailures.reset();
+        const stopped = await stopExternalHayHostProcess(existing);
+        if (!stopped) {
+            throw new Error(`Hay host ${existing.pid} did not stop; refusing to spawn a rival`);
+        }
+        stateCleared = clearHayHostStateFile(existing);
+        if (!stateCleared) {
+            throw new Error('Hay host state changed during restart; refusing to clear or replace it');
+        }
     }
 
-    clearHayHostStateFile();
+    if (!stateCleared) {
+        const registered = readHayHostStateFile();
+        if (registered && (!existing || !sameHostIncarnation(registered, existing))) {
+            if (isProcessAlive(registered.pid) && await probeExternalHayHostFromHost(registered, 1500)) {
+                return markExternalHayHostResponsive(registered);
+            }
+            throw new Error('Hay host state changed during recovery; refusing to clear or replace it');
+        }
+        clearHayHostStateFile(registered || null);
+    }
 
     // Spawn lock: concurrent ensure calls (other hop processes, racing web
     // requests) must not each spawn a host. Loser waits for the winner's
@@ -6286,8 +6554,7 @@ async function ensureExternalHayHostReady() {
                 await new Promise((resolve) => setTimeout(resolve, 200));
                 const spawned = readHayHostStateFile();
                 if (spawned && isProcessAlive(spawned.pid) && await probeExternalHayHostFromHost(spawned, 1500)) {
-                    hayHostState = spawned;
-                    return spawned;
+                    return markExternalHayHostResponsive(spawned);
                 }
             }
             // Winner never delivered — fall through and spawn ourselves.
@@ -6295,9 +6562,37 @@ async function ensureExternalHayHostReady() {
         try {
             spawnLockFd = fs.openSync(HAY_HOST_SPAWN_LOCK, 'wx');
             fs.writeSync(spawnLockFd, String(process.pid));
-        } catch (e2) { spawnLockFd = null; /* proceed unlocked rather than fail */ }
+        } catch (e2) {
+            throw new Error('Another Hop process is still spawning the Hay host; refusing to spawn a rival');
+        }
+    }
+    try {
+
+    const registeredSurvivor = readHayHostStateFile();
+    if (registeredSurvivor && isProcessAlive(registeredSurvivor.pid)
+        && await probeExternalHayHostFromHost(registeredSurvivor, 1500)) {
+        return markExternalHayHostResponsive(registeredSurvivor);
     }
+
+    // Last look before spawning: an already-running, healthy host for THIS hop
+    // home means we must adopt it, not add a rival. Two hosts split the fleet —
+    // the daemon canonicalizes one, so every room on the loser goes invisible
+    // and dies unrecorded when it is reaped — and both thrash the same state
+    // files. The spawn lock above only serializes racing spawners; a host that
+    // survived a crash (or was started by hand) is outside its scope, which is
+    // how two hosts came to exist across the thermal-sleep crash.
     try {
+        const survivors = (await inspectExternalHayHosts(true))
+            .filter((entry) => entry.healthy && hostBelongsToCurrentHome(entry, null));
+        const adoptable = survivors
+            .map((entry) => entry.host)
+            .filter((host) => host && Number.isInteger(host.pid) && isProcessAlive(host.pid))
+            .sort((a, b) => (b.startedAt || 0) - (a.startedAt || 0))[0];
+        if (adoptable) {
+            log(`[host] adopting the running host (pid ${adoptable.pid}, port ${adoptable.port}) instead of spawning a rival`, DIM);
+            return markExternalHayHostResponsive(adoptable);
+        }
+    } catch (e) { /* inspection failed — spawning is still the right move */ }
 
     const hostScript = path.join(__dirname, 'scripts', 'hay-host.js');
     if (!fs.existsSync(hostScript)) {
@@ -6369,6 +6664,11 @@ async function ensureExternalHayHostReady() {
     }
 }
 
+async function ensureExternalHayHostReady() {
+    if (!isExternalTerminalBackend()) return null;
+    return await hayHostEnsureFlight.run(ensureExternalHayHostReadyOnce);
+}
+
 async function callExternalHayHostApi(apiPath, method = 'GET', body = null, timeoutMs = 2000) {
     if (!isExternalTerminalBackend()) return null;
     const state = await ensureExternalHayHostReady();
@@ -6940,6 +7240,14 @@ function startAuthProxy(authEmitter) {
             : null;
         const isAuthenticated = cookies[SESSION_COOKIE_NAME] === SESSION_SECRET
             || tokenFromHeader === SESSION_SECRET;
+        // How this request proved itself decides the DEFAULT actor. Humans
+        // reach the API through the web UI (cookie) or the hop CLI (which
+        // stamps x-hop-via); a raw Bearer-token call with neither is, in
+        // practice, always automation — an agent's script, a probe, a cron.
+        // Those callers rarely remember to declare x-hop-actor, and every
+        // one that forgot used to land its sessions in the USER tab
+        // (SelectProbe et al). Explicit headers still win outright.
+        req.hopAuthVia = cookies[SESSION_COOKIE_NAME] === SESSION_SECRET ? 'cookie' : 'token';
 
         // API: Auth status (used by local CLI to wait for remote login)
         if (parsedUrl.pathname === '/api/auth' && req.method === 'GET') {
@@ -11040,15 +11348,26 @@ async function claimUnnamedLocalCliSession(opts = {}) {
 }
 
 function resolveSessionTargetByDisplay(sessionsRes, displayName) {
-    const sessions = Array.isArray(sessionsRes?.sessions) ? sessionsRes.sessions : [];
-    let target = sessions.find((session) => (
-        session && session.type !== 'port' && session.displayName === displayName
-    ));
-    if (!target && sessionsRes?.aliases && sessionsRes.aliases[displayName]) {
-        const resolvedName = sessionsRes.aliases[displayName];
-        target = sessions.find((session) => (
-            session && session.type !== 'port' && session.displayName === resolvedName
-        ));
+    const sessions = (Array.isArray(sessionsRes?.sessions) ? sessionsRes.sessions : [])
+        .filter((session) => session && session.type !== 'port');
+    // Exact-case match wins; otherwise a UNIQUE case-insensitive wearer
+    // resolves, so `hop attach titan` finds "Titan".
+    const byName = (name) => {
+        const lower = String(name).toLowerCase();
+        let exact = null;
+        const folded = [];
+        for (const session of sessions) {
+            if (session.displayName === name) { exact = session; break; }
+            if (String(session.displayName).toLowerCase() === lower) folded.push(session);
+        }
+        return exact || (folded.length === 1 ? folded[0] : null);
+    };
+    let target = byName(displayName);
+    if (!target && sessionsRes?.aliases) {
+        const aliasKeys = Object.keys(sessionsRes.aliases);
+        const aliasKey = aliasKeys.find((key) => key === displayName)
+            ?? aliasKeys.find((key) => key.toLowerCase() === String(displayName).toLowerCase());
+        if (aliasKey) target = byName(sessionsRes.aliases[aliasKey]);
     }
     return target || null;
 }
@@ -11165,12 +11484,21 @@ function resolveOrCreateLocalTerminalSession(nameArg, opts = {}) {
             };
         }
 
-        const existingByList = existingSessions.find((session) => {
-            if (!session || session.type === 'port') return false;
-            if (session.displayName === requestedDisplay) return true;
-            if (session.internalName === requestedDisplay || session.internalName === requested) return true;
-            return false;
-        });
+        // Case-insensitive so `hop titan` attaches to "Titan" instead of
+        // minting a lowercase twin. Exact matches take priority; a folded
+        // match only counts when it is unambiguous.
+        const matchesName = (candidate, name) => typeof candidate === 'string' && typeof name === 'string'
+            && candidate.toLowerCase() === name.toLowerCase();
+        const eligibleSessions = existingSessions.filter((session) => session && session.type !== 'port');
+        const exactByList = eligibleSessions.find((session) => (
+            session.displayName === requestedDisplay
+            || session.internalName === requestedDisplay || session.internalName === requested
+        ));
+        const foldedByList = exactByList ? [] : eligibleSessions.filter((session) => (
+            matchesName(session.displayName, requestedDisplay)
+            || matchesName(session.internalName, requestedDisplay) || matchesName(session.internalName, requested)
+        ));
+        const existingByList = exactByList || (foldedByList.length === 1 ? foldedByList[0] : null);
         if (existingByList && existingByList.internalName) {
             return {
                 internalName: existingByList.internalName,
@@ -11415,7 +11743,144 @@ function suggestNearestCommand(input) {
     return best;
 }
 
+// One source of truth for CLI usage: the full `hop --help` output and the
+// per-command `hop <cmd> --help` output both render from this table, so a
+// command can never exist without help (a stray `hop restore --help` once
+// fell through and ran a live restore).
+const HELP_SECTIONS = [
+    { title: 'Usage', lines: [
+        `hop                       Launch the daemon+tunnel if needed and open a NEW terminal session`,
+        `hop new                   Same as hop (always opens a new session)`,
+        `hop attach                Reattach to an existing session (picks an unattached one; lists them if none are free)`,
+        `hop attach <name>         Reattach to an existing session by name`,
+        `hop attach all            Reattach to every existing session in turn`,
+        `hop start                 Start the daemon and tunnel only, then print QR codes (no terminal session)`,
+        `hop local [session]       Open a terminal with no daemon or tunnel — local only, not reachable remotely`,
+        `hop stop                  Stop hop daemon (terminal sessions keep running)`,
+        `hop stop --all            Stop daemon, hay-host, and all terminal sessions`,
+        `hop status                Show daemon, tunnel, and session status`,
+        `hop doctor                Run environment/health checks`,
+        `hop logs [-f] [hay-host]  Show daemon logs (-f to follow)`,
+        `hop --help                Show this help message`,
+    ] },
+    { title: 'URL & QR', lines: [
+        `hop url                   Print current tunnel URL`,
+        `hop qr                    Show tunnel URL as QR code`,
+        `hop qr auth               Show authenticator setup QR code`,
+    ] },
+    { title: 'Config', lines: [
+        `hop config                Show hop config`,
+        `hop config theme [name]   Show or set the session naming theme`,
+    ] },
+    { title: 'Custom Domain', lines: [
+        `hop domain                Show current domain config`,
+        `hop domain <hostname>     Setup custom domain (e.g., hop.example.com)`,
+        `hop domain-clear          Remove custom domain, use random URLs`,
+    ] },
+    { title: 'Security', lines: [
+        `hop password              Show password status`,
+        `hop password set          Set or change password`,
+        `hop password clear        Remove password protection`,
+    ] },
+    { title: 'Multi-user (admin)', lines: [
+        `hop user list             List all users`,
+        `hop user add <name>       Add a user (creates tunnel + DNS)`,
+        `hop user remove <name>    Remove a user`,
+        `hop user export <name>    Export credentials for a user`,
+    ] },
+    { title: 'Sessions', lines: [
+        `hop session list [--all|-a]      List live sessions (--all/-a adds workspace defs across all workspaces)`,
+        `hop session add <name> [--cwd P] --workspace W  Save a terminal definition to a workspace`,
+        `hop session add <name> --port N --workspace W   Save a port definition to a workspace`,
+        `hop session rename <old> <new>   Rename a session`,
+        `hop session remove <name>        Remove a session`,
+        `hop session permit <name>        Allow agent access`,
+        `hop session origin <name> <user|agent>  Move a session between user/agent sides (switcher filter + restore policy)`,
+        `hop session block <name>         Block agent access`,
+    ] },
+    { title: 'Workspaces', lines: [
+        `hop workspace list            List workspaces`,
+        `hop workspace create <name>   Create an empty workspace`,
+        `hop workspace show <name>     Show saved definitions in a workspace`,
+        `hop workspace save <name>     Save selected live sessions into a workspace`,
+        `hop workspace load <name>     Start sessions defined in a workspace`,
+        `hop workspace delete <name> [--yes]  Delete a workspace (asks before deleting a non-empty one)`,
+    ] },
+    { title: 'Restore', lines: [
+        `hop restore [--dry-run] [--agents]  Recreate your saved sessions, resuming claude conversations (--agents includes agent-created ones)`,
+        `hop update [--check|--host] Self-update from GitHub (daemon restart; sessions survive; --host cycles the host too)`,
+        `hop claude-hook install   Enable full restore (adds a Claude SessionStart hook)`,
+        `hop claude-hook status|remove   Check or remove the hook`,
+        `hop agent-skill install   Install Hop orchestration instructions for Claude and Codex`,
+        `hop agent-skill status|remove   Check or remove the skills`,
+        `hop claude-skill ...      Backward-compatible Claude-only alias`,
+    ] },
+    { title: 'Client mode (for users)', lines: [
+        `hop client <credentials>  Run tunnel with exported credentials`,
+    ] },
+    { title: 'Math', lines: [
+        `hop math '<latex>'        Render a LaTeX formula (inline image where supported, else Unicode)`,
+    ] },
+    { title: 'Maintenance', lines: [
+        `hop health [--restart]    Check tunnel health (--restart forces a tunnel restart)`,
+        `hop wipe [--all] [--yes]  Remove workspace-defined sessions (--all kills live; --yes skips confirmation)`,
+        `hop wipe --agent          Close all agent-created terminal API sessions`,
+        `hop config resume <mode>  How restores answer claude's resume question (full|summary|ask)`,
+    ] },
+];
+
+function printFullHelp() {
+    log(`\n${BOLD}Hop - Remote Terminal Access${RESET}\n`, CYAN);
+    for (const section of HELP_SECTIONS) {
+        log(`${BOLD}${section.title}:${RESET}`, RESET);
+        for (const line of section.lines) {
+            log(`  ${line}`, RESET);
+        }
+        log('');
+    }
+}
+
+// Print every usage line whose command word matches. Returns false when the
+// table documents nothing for it.
+function printCommandHelp(cmd) {
+    const matched = [];
+    for (const section of HELP_SECTIONS) {
+        for (const line of section.lines) {
+            const word = (line.match(/^hop\s+(\S+)/) || [])[1] || '';
+            if (word === cmd) matched.push(line);
+        }
+    }
+    if (matched.length === 0) return false;
+    log(`\n${BOLD}Usage:${RESET}`, RESET);
+    for (const line of matched) {
+        log(`  ${line}`, RESET);
+    }
+    log('');
+    return true;
+}
+
 async function main() {
+    // Any command followed by --help/-h prints usage instead of running: help
+    // must never execute the real thing. Bare "help" is NOT intercepted here —
+    // positional args (a session name, latex) may legitimately be "help" — and
+    // `hop client` keeps its own richer help text.
+    const argCmd = process.argv[2];
+    if (argCmd && argCmd !== 'client' && !['--help', '-h', 'help'].includes(argCmd)
+        && process.argv.slice(3).some((a) => a === '--help' || a === '-h')) {
+        if (!printCommandHelp(argCmd)) {
+            if (KNOWN_COMMANDS.includes(argCmd)) {
+                printFullHelp();
+            } else {
+                const suggestion = suggestNearestCommand(argCmd);
+                log(`Unknown command: ${argCmd}`, RED);
+                if (suggestion) log(`Did you mean ${CYAN}hop ${suggestion}${RESET}?`, RESET);
+                log(`Run ${CYAN}hop --help${RESET} for the full command list.`, RESET);
+                process.exit(1);
+            }
+        }
+        process.exit(0);
+    }
+
     // Handle `hop client` - run as a user with exported credentials
     if (process.argv[2] === 'client') {
         // Separate flags from positionals so flag order doesn't matter.
@@ -11852,11 +12317,14 @@ async function main() {
 
         const sessionsRes = await fetchSessionList(state);
         const allSessions = (sessionsRes?.sessions || []).filter((s) => s.type !== 'port');
-        let targets = named.length
-            ? allSessions.filter((s) => named.includes(s.displayName) || named.includes(s.internalName))
-            : allSessions;
+        const namedLower = named.map((n) => n.toLowerCase());
+        const wearsAnyName = (s) => namedLower.includes(String(s.displayName || '').toLowerCase())
+            || namedLower.includes(String(s.internalName || '').toLowerCase());
+        let targets = named.length ? allSessions.filter(wearsAnyName) : allSessions;
         if (named.length) {
-            const missing = named.filter((n) => !allSessions.some((s) => s.displayName === n || s.internalName === n));
+            const missing = named.filter((n) => !allSessions.some((s) =>
+                String(s.displayName || '').toLowerCase() === n.toLowerCase()
+                || String(s.internalName || '').toLowerCase() === n.toLowerCase()));
             for (const m of missing) log(`No such session: ${m}`, YELLOW);
         }
         // Freshness: a tagline names the session's DURABLE goal, so it should
@@ -12339,86 +12807,7 @@ async function main() {
     }
 
     if (process.argv[2] === '--help' || process.argv[2] === '-h' || process.argv[2] === 'help') {
-        log(`\n${BOLD}Hop - Remote Terminal Access${RESET}\n`, CYAN);
-        log(`${BOLD}Usage:${RESET}`, RESET);
-        log(`  hop                       Launch the daemon+tunnel if needed and open a NEW terminal session`, RESET);
-        log(`  hop new                   Same as hop (always opens a new session)`, RESET);
-        log(`  hop attach                Reattach to an existing session (picks an unattached one; lists them if none are free)`, RESET);
-        log(`  hop attach <name>         Reattach to an existing session by name`, RESET);
-        log(`  hop attach all            Reattach to every existing session in turn`, RESET);
-        log(`  hop start                 Start the daemon and tunnel only, then print QR codes (no terminal session)`, RESET);
-        log(`  hop local [session]       Open a terminal with no daemon or tunnel — local only, not reachable remotely`, RESET);
-        log(`  hop stop                  Stop hop daemon (terminal sessions keep running)`, RESET);
-        log(`  hop stop --all            Stop daemon, hay-host, and all terminal sessions`, RESET);
-        log(`  hop status                Show daemon, tunnel, and session status`, RESET);
-        log(`  hop doctor                Run environment/health checks`, RESET);
-        log(`  hop logs [-f] [hay-host]  Show daemon logs (-f to follow)`, RESET);
-        log(`  hop --help                Show this help message`, RESET);
-        log('');
-        log(`${BOLD}URL & QR:${RESET}`, RESET);
-        log(`  hop url                   Print current tunnel URL`, RESET);
-        log(`  hop qr                    Show tunnel URL as QR code`, RESET);
-        log(`  hop qr auth               Show authenticator setup QR code`, RESET);
-        log('');
-        log(`${BOLD}Config:${RESET}`, RESET);
-        log(`  hop config                Show hop config`, RESET);
-        log(`  hop config theme [name]   Show or set the session naming theme`, RESET);
-        log('');
-        log(`${BOLD}Custom Domain:${RESET}`, RESET);
-        log(`  hop domain                Show current domain config`, RESET);
-        log(`  hop domain <hostname>     Setup custom domain (e.g., hop.example.com)`, RESET);
-        log(`  hop domain-clear          Remove custom domain, use random URLs`, RESET);
-        log('');
-        log(`${BOLD}Security:${RESET}`, RESET);
-        log(`  hop password              Show password status`, RESET);
-        log(`  hop password set          Set or change password`, RESET);
-        log(`  hop password clear        Remove password protection`, RESET);
-        log('');
-        log(`${BOLD}Multi-user (admin):${RESET}`, RESET);
-        log(`  hop user list             List all users`, RESET);
-        log(`  hop user add <name>       Add a user (creates tunnel + DNS)`, RESET);
-        log(`  hop user remove <name>    Remove a user`, RESET);
-        log(`  hop user export <name>    Export credentials for a user`, RESET);
-        log('');
-        log(`${BOLD}Sessions:${RESET}`, RESET);
-        log(`  hop session list [--all|-a]      List live sessions (--all/-a adds workspace defs across all workspaces)`, RESET);
-        log(`  hop session add <name> [--cwd P] --workspace W  Save a terminal definition to a workspace`, RESET);
-        log(`  hop session add <name> --port N --workspace W   Save a port definition to a workspace`, RESET);
-        log(`  hop session rename <old> <new>   Rename a session`, RESET);
-        log(`  hop session remove <name>        Remove a session`, RESET);
-        log(`  hop session permit <name>        Allow agent access`, RESET);
-        log(`  hop session origin <name> <user|agent>  Move a session between user/agent sides (switcher filter + restore policy)`, RESET);
-        log(`  hop session block <name>         Block agent access`, RESET);
-        log('');
-        log(`${BOLD}Workspaces:${RESET}`, RESET);
-        log(`  hop workspace list            List workspaces`, RESET);
-        log(`  hop workspace create <name>   Create an empty workspace`, RESET);
-        log(`  hop workspace show <name>     Show saved definitions in a workspace`, RESET);
-        log(`  hop workspace save <name>     Save selected live sessions into a workspace`, RESET);
-        log(`  hop workspace load <name>     Start sessions defined in a workspace`, RESET);
-        log(`  hop workspace delete <name> [--yes]  Delete a workspace (asks before deleting a non-empty one)`, RESET);
-        log('');
-        log(`${BOLD}Restore:${RESET}`, RESET);
-        log(`  hop restore [--dry-run]   Recreate your saved sessions, resuming claude conversations`, RESET);
-        log(`  hop update [--check|--host] Self-update from GitHub (daemon restart; sessions survive; --host cycles the host too)`, RESET);
-        log(`  hop claude-hook install   Enable full restore (adds a Claude SessionStart hook)`, RESET);
-        log(`  hop claude-hook status|remove   Check or remove the hook`, RESET);
-        log(`  hop agent-skill install   Install Hop orchestration instructions for Claude and Codex`, RESET);
-        log(`  hop agent-skill status|remove   Check or remove the skills`, RESET);
-        log(`  hop claude-skill ...      Backward-compatible Claude-only alias`, RESET);
-        log('');
-        log(`${BOLD}Client mode (for users):${RESET}`, RESET);
-        log(`  hop client <credentials>  Run tunnel with exported credentials`, RESET);
-        log('');
-        log(`${BOLD}Math:${RESET}`, RESET);
-        log(`  hop math '<latex>'        Render a LaTeX formula (inline image where supported, else Unicode)`, RESET);
-        log('');
-        log(`${BOLD}Maintenance:${RESET}`, RESET);
-        log(`  hop health [--restart]    Check tunnel health (--restart forces a tunnel restart)`, RESET);
-        log(`  hop wipe [--all] [--yes]  Remove workspace-defined sessions (--all kills live; --yes skips confirmation)`, RESET);
-        log(`  hop wipe --agent          Close all agent-created terminal API sessions`, RESET);
-        log(`  hop config resume <mode>  How restores answer claude's resume question (full|summary|ask)`, RESET);
-        log('');
+        printFullHelp();
         process.exit(0);
     }