hop2 0.11.12 → 0.11.13

package/hay-web/index.html

@@ -6,7 +6,7 @@
     <!-- Terminal prompt chevron on a dark tile — reads "terminal app" at 16px. -->
     <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='7' fill='%2317181d'/%3E%3Cpath d='M11 9.5 L20.5 16 L11 22.5' fill='none' stroke='%23a78bfa' stroke-width='4' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E" />
     <title>Hay</title>
-    <script type="module" crossorigin src="/assets/index-DzlPn2In.js"></script>
+    <script type="module" crossorigin src="/assets/index-DnSA-VR6.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-DHotLq-D.css">
   </head>
   <body>

package/hop

@@ -2875,6 +2875,10 @@ function unregisterTerminalStream(id, res) {
     streams.delete(res);
     if (streams.size === 0) {
         terminalApiStreams.delete(id);
+        // The idle clock starts when the LAST stream closes — an agent that
+        // held a stream for an hour was active the whole time.
+        const entry = terminalApiSessions.get(id);
+        if (entry) entry.lastTouchedAt = Date.now();
     }
 }
 
@@ -3675,6 +3679,39 @@ function createVirtualClientAdapter(onServerMessage) {
     };
 }
 
+// Fetch a terminal API entry AND stamp it as recently used — every API touch
+// (stream, write, resize, exec, delete) resets the idle clock the reaper
+// below runs on.
+function getTerminalApiEntryTouched(terminalId) {
+    const entry = terminalApiSessions.get(terminalId);
+    if (entry) entry.lastTouchedAt = Date.now();
+    return entry;
+}
+
+// Idle reaper for agent attaches. A virtual client is presence like any
+// other ("agent" in the roster) but has no socket that could die — an agent
+// that crashed or simply never called close would sit in a session's
+// presence forever. Idle = no API touch and no open SSE stream. Reaping is
+// safe for well-behaved agents: the MCP core re-attaches by session name on
+// the next op (recoverTerminalId), so a reaped handle costs one round-trip.
+const TERMINAL_API_IDLE_TTL_MS = Number(process.env.HOP_TERMINAL_API_IDLE_TTL_MS || 15 * 60 * 1000);
+const TERMINAL_API_SWEEP_MS = Number(process.env.HOP_TERMINAL_API_SWEEP_MS || 60 * 1000);
+if (DAEMON_FLAG && TERMINAL_API_IDLE_TTL_MS > 0) {
+    setInterval(() => {
+        const nowMs = Date.now();
+        for (const entry of [...terminalApiSessions.values()]) {
+            if (terminalApiStreams.has(entry.id)) continue; // live stream = in use
+            const idleSince = entry.lastTouchedAt || Date.parse(entry.createdAt) || nowMs;
+            if (nowMs - idleSince <= TERMINAL_API_IDLE_TTL_MS) continue;
+            log(`[terminal-api] detached idle '${entry.actor}' terminal from ${entry.displayName || entry.sessionName} after ${Math.round((nowMs - idleSince) / 60000)}m`, DIM);
+            try { entry.adapter.close(); } catch (e) { /* already closing */ }
+            // adapter.close() detaches the room client and drops the entry;
+            // belt-and-braces in case a close handler threw mid-chain.
+            terminalApiSessions.delete(entry.id);
+        }
+    }, TERMINAL_API_SWEEP_MS).unref();
+}
+
 function closeTerminalApiEntry(terminalId) {
     terminalApiSessions.delete(terminalId);
     const streams = terminalApiStreams.get(terminalId);
@@ -3803,7 +3840,8 @@ async function attachExternalTerminalApiClient(sessionName, displayName, opts =
         actor: opts.actor || 'user',
         clientId,
         adapter: adapterBundle,
-        createdAt: new Date().toISOString()
+        createdAt: new Date().toISOString(),
+        lastTouchedAt: Date.now()
     };
     terminalApiSessions.set(terminalId, sessionEntry);
     return sessionEntry;
@@ -3851,7 +3889,8 @@ async function attachTerminalApiClient(sessionName, displayName, opts = {}) {
         actor: opts.actor || 'user',
         clientId,
         adapter: adapterBundle,
-        createdAt: new Date().toISOString()
+        createdAt: new Date().toISOString(),
+        lastTouchedAt: Date.now()
     };
     terminalApiSessions.set(terminalId, sessionEntry);
     return sessionEntry;
@@ -7415,6 +7454,30 @@ function recordAuth(authEmitter) {
     if (authEmitter) authEmitter.emit('authenticated');
 }
 
+// One MIME map for every static-serving path (hub assets, session assets,
+// Views files) — drifting per-branch copies are how .pdf went missing and a
+// published PDF downloaded as a blob. Includes the `hop view` families
+// (pdf/video/txt) alongside the app bundle's own types.
+const STATIC_CONTENT_TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'application/javascript',
+    '.css': 'text/css',
+    '.json': 'application/json',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+    '.pdf': 'application/pdf',
+    '.mp4': 'video/mp4',
+    '.mov': 'video/quicktime',
+    '.webm': 'video/webm',
+    '.txt': 'text/plain; charset=utf-8',
+    '.md': 'text/plain; charset=utf-8'
+};
+
 function startAuthProxy(authEmitter) {
     log(`[2/4] Starting Session Manager on port ${PROXY_PORT}...`, BOLD);
 
@@ -7424,6 +7487,27 @@ function startAuthProxy(authEmitter) {
         const ip = getClientIp(req);
         const sessionInfo = parseSessionFromRequest(req, parsedUrl);
 
+        // Shared caches must never store what the cookie gate protects.
+        // Cloudflare edge-caches common extensions (.pdf, images, .js) BY
+        // DEFAULT when the origin stays silent, then serves the copy to
+        // whoever asks next — cookie or not. Proven live: a `hop view` PDF
+        // fetched once WITH auth came back cf-cache-status: HIT without it.
+        // Enforced here, at the writeHead choke point, so proxied upstream
+        // headers cannot reopen the hole; a route with a deliberately
+        // different policy sets res.hopCacheControl before responding.
+        const rawWriteHead = res.writeHead.bind(res);
+        res.writeHead = (...args) => {
+            for (const a of args) {
+                if (a && typeof a === 'object' && !Array.isArray(a)) {
+                    for (const k of Object.keys(a)) {
+                        if (String(k).toLowerCase() === 'cache-control') delete a[k];
+                    }
+                }
+            }
+            res.setHeader('Cache-Control', res.hopCacheControl || 'private, no-store');
+            return rawWriteHead(...args);
+        };
+
         // Check auth via cookie OR Authorization header (internal hop-to-hop only)
         // Bearer token is read from state file by other hop processes on same machine
         const authHeader = req.headers.authorization;
@@ -7453,6 +7537,18 @@ function startAuthProxy(authEmitter) {
             return;
         }
 
+        // Apple App Site Association — the trust anchor for NATIVE passkey
+        // sign-in from hop-ios (webcredentials). Apple's CDN fetches this
+        // anonymously over HTTPS, so it must sit in front of the auth gate.
+        // Team + bundle are hop-ios's (project.yml); a WKWebView can never run
+        // WebAuthn, so without this file the phone has no passkey path at all.
+        if (parsedUrl.pathname === '/.well-known/apple-app-site-association' && req.method === 'GET') {
+            res.hopCacheControl = 'public, max-age=300';    // public on purpose — Apple's CDN reads it
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ webcredentials: { apps: ['5AD7QB9795.io.zhoulab.hop.spike'] } }));
+            return;
+        }
+
         // --- PASSKEYS (WebAuthn) ---
         if (parsedUrl.pathname.startsWith('/api/passkeys/') && req.method === 'POST') {
             const respond = (status, payload) => {
@@ -7957,6 +8053,42 @@ function startAuthProxy(authEmitter) {
             return;
         }
 
+        // ---- Views files --------------------------------------------------
+        // Served on an EXTENSIONLESS path on purpose: the edge cache stores
+        // by URL extension and can override origin cache directives, and a
+        // stored copy answers cookie-less clients — observed live with a
+        // `hop view` PDF. The /inline terminal segment keeps the extension
+        // off the end of the path; content-type still comes from the real
+        // file name. The legacy /assets/view/<s>/<f> form redirects here, so
+        // an edge-cached response is at worst a redirect, never the bytes.
+        const viewMatch = req.method === 'GET'
+            && parsedUrl.pathname.match(/^\/view\/([^/]+)\/([^/]+?)(\/inline)?$/);
+        if (viewMatch) {
+            const viewRoot = path.resolve(path.join(HAY_WEB_DIR, 'assets', 'view'));
+            const target = path.resolve(path.join(
+                viewRoot, decodeURIComponent(viewMatch[1]), decodeURIComponent(viewMatch[2])));
+            if (!target.startsWith(viewRoot + path.sep)
+                || !fs.existsSync(target) || !fs.statSync(target).isFile()) {
+                res.writeHead(404, { 'Content-Type': 'text/plain' });
+                res.end('Not found');
+                return;
+            }
+            res.writeHead(200, {
+                'Content-Type': STATIC_CONTENT_TYPES[path.extname(target).toLowerCase()] || 'application/octet-stream'
+            });
+            res.end(fs.readFileSync(target));
+            return;
+        }
+        if (req.method === 'GET' && parsedUrl.pathname.startsWith('/assets/view/')) {
+            const segs = parsedUrl.pathname.slice('/assets/view/'.length).split('/');
+            if (segs.length === 2 && segs[1] && segs[1] !== 'manifest.json') {
+                res.writeHead(302, { Location: `/view/${segs[0]}/${segs[1]}/inline` });
+                res.end();
+                return;
+            }
+            // manifest.json falls through to plain static serving
+        }
+
         if (sessionInfoAuth && sessionInfoAuth.source === 'query' && shouldRedirectToSessionPath(req)) {
             res.writeHead(302, { 'Location': buildSessionPath(displayName) });
             res.end();
@@ -9423,7 +9555,7 @@ function startAuthProxy(authEmitter) {
         const terminalStreamMatch = (parsedUrl.pathname || '').match(/^\/api\/terminals\/([^/]+)\/stream$/);
         if (terminalStreamMatch && req.method === 'GET') {
             const terminalId = terminalStreamMatch[1];
-            const entry = terminalApiSessions.get(terminalId);
+            const entry = getTerminalApiEntryTouched(terminalId);
             if (!entry) {
                 res.writeHead(404, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ error: 'Terminal not found' }));
@@ -9459,7 +9591,7 @@ function startAuthProxy(authEmitter) {
         const terminalWriteMatch = (parsedUrl.pathname || '').match(/^\/api\/terminals\/([^/]+)\/write$/);
         if (terminalWriteMatch && req.method === 'POST') {
             const terminalId = terminalWriteMatch[1];
-            const entry = terminalApiSessions.get(terminalId);
+            const entry = getTerminalApiEntryTouched(terminalId);
             if (!entry) {
                 res.writeHead(404, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ error: 'Terminal not found' }));
@@ -9498,7 +9630,7 @@ function startAuthProxy(authEmitter) {
         const terminalResizeMatch = (parsedUrl.pathname || '').match(/^\/api\/terminals\/([^/]+)\/resize$/);
         if (terminalResizeMatch && req.method === 'POST') {
             const terminalId = terminalResizeMatch[1];
-            const entry = terminalApiSessions.get(terminalId);
+            const entry = getTerminalApiEntryTouched(terminalId);
             if (!entry) {
                 res.writeHead(404, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ error: 'Terminal not found' }));
@@ -9531,7 +9663,7 @@ function startAuthProxy(authEmitter) {
         const terminalExecMatch = (parsedUrl.pathname || '').match(/^\/api\/terminals\/([^/]+)\/exec$/);
         if (terminalExecMatch && req.method === 'POST') {
             const terminalId = terminalExecMatch[1];
-            const entry = terminalApiSessions.get(terminalId);
+            const entry = getTerminalApiEntryTouched(terminalId);
             if (!entry) {
                 res.writeHead(404, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ error: 'Terminal not found' }));
@@ -9571,7 +9703,7 @@ function startAuthProxy(authEmitter) {
         const terminalDeleteMatch = (parsedUrl.pathname || '').match(/^\/api\/terminals\/([^/]+)$/);
         if (terminalDeleteMatch && req.method === 'DELETE') {
             const terminalId = terminalDeleteMatch[1];
-            const entry = terminalApiSessions.get(terminalId);
+            const entry = getTerminalApiEntryTouched(terminalId);
             if (!entry) {
                 res.writeHead(404, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ error: 'Terminal not found' }));
@@ -9795,16 +9927,13 @@ function startAuthProxy(authEmitter) {
                 return;
             }
             const hubExt = path.extname(resolvedHub).toLowerCase();
-            const hubTypes = {
-                '.html': 'text/html; charset=utf-8',
-                '.js': 'application/javascript',
-                '.css': 'text/css',
-                '.json': 'application/json',
-                '.png': 'image/png',
-                '.jpg': 'image/jpeg',
-                '.svg': 'image/svg+xml',
-                '.ico': 'image/x-icon'
-            };
+            const hubTypes = STATIC_CONTENT_TYPES;
+            // Hashed bundle files may live in the BROWSER's cache for a while
+            // ('private' keeps every shared cache out); html and Views files
+            // stay on the no-store default.
+            if (hubExt !== '.html' && !parsedUrl.pathname.startsWith('/assets/view/')) {
+                res.hopCacheControl = 'private, max-age=3600';
+            }
             let hubContent = fs.readFileSync(resolvedHub);
             if (hubExt === '.html') {
                 // Room-less config: marks the page as hop-served (hub mode).
@@ -9952,16 +10081,12 @@ function startAuthProxy(authEmitter) {
 
         // Determine content type
         const ext = path.extname(filePath).toLowerCase();
-        const contentTypes = {
-            '.html': 'text/html; charset=utf-8',
-            '.js': 'application/javascript',
-            '.css': 'text/css',
-            '.json': 'application/json',
-            '.png': 'image/png',
-            '.jpg': 'image/jpeg',
-            '.svg': 'image/svg+xml',
-            '.ico': 'image/x-icon'
-        };
+        // Same split as hub scope: hashed bundles browser-cache privately,
+        // html and Views files keep the no-store default.
+        if (ext !== '.html' && !reqPath.startsWith('/assets/view/')) {
+            res.hopCacheControl = 'private, max-age=3600';
+        }
+        const contentTypes = STATIC_CONTENT_TYPES;
         const contentType = contentTypes[ext] || 'application/octet-stream';
 
         // Read and serve the file
@@ -10154,6 +10279,28 @@ function startAuthProxy(authEmitter) {
             const rows = parseInt(wsUrl.searchParams.get('rows') || '24', 10);
             const source = wsUrl.searchParams.get('source') || '';
             const claimId = wsUrl.searchParams.get('claim') || null;
+            // Client-supplied tab identity; the room evicts a same-key
+            // predecessor on attach (reconnect replaces its own ghost).
+            const deviceKeyRaw = wsUrl.searchParams.get('device') || '';
+            const deviceKey = /^[A-Za-z0-9._-]{1,80}$/.test(deviceKeyRaw) ? deviceKeyRaw : '';
+
+            // Liveness: browsers answer protocol pings in the network stack,
+            // so silence means the peer is gone (locked phone, network hop)
+            // even though no close frame ever arrived. Without this, ghost
+            // clients sat in presence until the tunnel's TCP gave up.
+            let wsAlive = true;
+            ws.on('pong', () => { wsAlive = true; });
+            const wsHeartbeat = setInterval(() => {
+                if (ws.readyState !== WebSocket.OPEN) { clearInterval(wsHeartbeat); return; }
+                if (!wsAlive) {
+                    clearInterval(wsHeartbeat);
+                    try { ws.terminate(); } catch (e) { /* already gone */ }
+                    return;
+                }
+                wsAlive = false;
+                try { ws.ping(); } catch (e) { /* closing */ }
+            }, 30000);
+            ws.on('close', () => clearInterval(wsHeartbeat));
 
             const clientId = hay.generateClientId();
             const colorIndex = Math.floor(Math.random() * 1000);
@@ -10173,7 +10320,7 @@ function startAuthProxy(authEmitter) {
 
             // Attach client to hay room
             session.room.attachClient(
-                { id: clientId, name: clientName, source, colorIndex, cols, rows },
+                { id: clientId, name: clientName, source, deviceKey, colorIndex, cols, rows },
                 hay.createSocketAdapter(ws)
             );
         });
@@ -12785,41 +12932,51 @@ async function main() {
                 process.exit(1);
             }
         }
-        if (local === upstream) {
+        // --restart: cycle onto the CURRENT checkout even when git has
+        // nothing to pull. The running processes can predate the checkout —
+        // commit locally, push, `hop update`, and "Already up to date" used
+        // to leave every process on pre-commit code with no hint.
+        const restartOnly = process.argv.includes('--restart');
+        if (local === upstream && (checkOnly || !restartOnly)) {
             log(`Already up to date (${local.slice(0, 7)}).`, GREEN);
+            if (!checkOnly) log(`Processes were not cycled — if they predate this checkout, ${CYAN}hop update --restart${RESET} restarts them onto it.`, RESET);
             process.exit(0);
         }
-        const behind = runGit(`git rev-list --count HEAD..${upstream}`);
-        const ahead = runGit(`git rev-list --count ${upstream}..HEAD`);
-        log(`Update available: ${behind} new commit(s)${ahead !== '0' ? ` — but local is ${ahead} ahead; resolve manually` : ''}`, YELLOW);
-        try { log(runGit(`git log --oneline --no-decorate HEAD..${upstream} -15`), RESET); } catch (e) { }
-        if (checkOnly) process.exit(0);
-        if (ahead !== '0') process.exit(1);
-        let dirty = '';
-        try { dirty = runGit('git status --porcelain'); } catch (e) { }
-        if (dirty) {
-            log('Working tree has local changes — commit or stash them first.', RED);
-            process.exit(1);
-        }
-        // Dependency fingerprint across the pull: reinstall only when a
-        // lockfile actually changed.
-        const lockRev = (ref, file) => { try { return runGit(`git rev-parse ${ref}:${file}`); } catch (e) { return ''; } };
-        const locks = ['package-lock.json', 'hay/package-lock.json'];
-        const before = locks.map((f) => lockRev('HEAD', f));
-        try { runGit(`git merge --ff-only ${upstream}`); } catch (e) {
-            log(`Fast-forward failed: ${e.message}`, RED);
-            process.exit(1);
-        }
-        const after = locks.map((f) => lockRev('HEAD', f));
-        for (let i = 0; i < locks.length; i++) {
-            if (before[i] !== after[i]) {
-                const dir = locks[i].startsWith('hay/') ? path.join(__dirname, 'hay') : __dirname;
-                log(`Dependencies changed (${locks[i]}) — installing…`, CYAN);
-                try {
-                    execSync('npm install --no-audit --no-fund', { cwd: dir, stdio: 'inherit', timeout: 600000 });
-                } catch (e) {
-                    log(`npm install failed in ${dir}: ${e.message}`, RED);
-                    process.exit(1);
+        if (local === upstream) {
+            log(`Checkout already current (${local.slice(0, 7)}) — restarting processes onto it.`, CYAN);
+        } else {
+            const behind = runGit(`git rev-list --count HEAD..${upstream}`);
+            const ahead = runGit(`git rev-list --count ${upstream}..HEAD`);
+            log(`Update available: ${behind} new commit(s)${ahead !== '0' ? ` — but local is ${ahead} ahead; resolve manually` : ''}`, YELLOW);
+            try { log(runGit(`git log --oneline --no-decorate HEAD..${upstream} -15`), RESET); } catch (e) { }
+            if (checkOnly) process.exit(0);
+            if (ahead !== '0') process.exit(1);
+            let dirty = '';
+            try { dirty = runGit('git status --porcelain'); } catch (e) { }
+            if (dirty) {
+                log('Working tree has local changes — commit or stash them first.', RED);
+                process.exit(1);
+            }
+            // Dependency fingerprint across the pull: reinstall only when a
+            // lockfile actually changed.
+            const lockRev = (ref, file) => { try { return runGit(`git rev-parse ${ref}:${file}`); } catch (e) { return ''; } };
+            const locks = ['package-lock.json', 'hay/package-lock.json'];
+            const before = locks.map((f) => lockRev('HEAD', f));
+            try { runGit(`git merge --ff-only ${upstream}`); } catch (e) {
+                log(`Fast-forward failed: ${e.message}`, RED);
+                process.exit(1);
+            }
+            const after = locks.map((f) => lockRev('HEAD', f));
+            for (let i = 0; i < locks.length; i++) {
+                if (before[i] !== after[i]) {
+                    const dir = locks[i].startsWith('hay/') ? path.join(__dirname, 'hay') : __dirname;
+                    log(`Dependencies changed (${locks[i]}) — installing…`, CYAN);
+                    try {
+                        execSync('npm install --no-audit --no-fund', { cwd: dir, stdio: 'inherit', timeout: 600000 });
+                    } catch (e) {
+                        log(`npm install failed in ${dir}: ${e.message}`, RED);
+                        process.exit(1);
+                    }
                 }
             }
         }
@@ -13162,7 +13319,9 @@ async function main() {
                     entries.push({
                         session: sess,
                         name: f,
-                        path: `/assets/view/${encodeURIComponent(sess)}/${encodeURIComponent(f)}`,
+                        // The extensionless serving path — see the /view route
+                        // for why the extension must stay off the URL's end.
+                        path: `/view/${encodeURIComponent(sess)}/${encodeURIComponent(f)}/inline`,
                         bytes: st.size,
                         mtime: Math.floor(st.mtimeMs / 1000)
                     });
@@ -13204,7 +13363,7 @@ async function main() {
             // session subdir already namespaces collisions between agents.
             const dest = path.join(destDir, path.basename(src));
             fs.copyFileSync(src, dest);
-            console.log(`View: ${state.url}/assets/view/${encodeURIComponent(session)}/${encodeURIComponent(path.basename(src))}`);
+            console.log(`View: ${state.url}/view/${encodeURIComponent(session)}/${encodeURIComponent(path.basename(src))}/inline`);
         }
         if (failed === 0 && files.length > 0) {
             // One bell: the artifact is usually the deliverable the human is
@@ -13274,7 +13433,7 @@ async function main() {
             ].join(''));
             rebuildArtifactManifest();
             console.log(`View: ${proxyUrl}`);
-            console.log(`Attached to ${caller} — also in its artifacts.`);
+            console.log(`Attached to ${caller} — also in its Views.`);
         } else {
             console.log(`View: ${proxyUrl}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hop2",
-  "version": "0.11.12",
+  "version": "0.11.13",
   "description": "🐰 Hop into your terminal from anywhere. Secure remote shell access with 2FA via Cloudflare Tunnel. Next-gen rewrite with native terminal sharing.",
   "main": "hop",
   "bin": {

package/scripts/hay-host.js

@@ -393,11 +393,36 @@ async function main() {
         if (clientBg && typeof room.setClientColors === 'function') {
             room.setClientColors(clientBg, clientFg);
         }
+        // Tab identity forwarded by the daemon: the room evicts a same-key
+        // predecessor on attach, so a phone's reconnect replaces its own
+        // ghost in presence instead of standing next to it.
+        const deviceKeyRaw = wsUrl.searchParams.get('device') || '';
+        const deviceKey = /^[A-Za-z0-9._-]{1,80}$/.test(deviceKeyRaw) ? deviceKeyRaw : '';
+
+        // Liveness: browsers answer protocol pings in the network stack, so
+        // silence means the peer is gone (locked phone, network hop) even
+        // though no close frame ever arrived — through the tunnel that can
+        // outlive the client by hours. Ghosts die within a minute instead.
+        let wsAlive = true;
+        ws.on('pong', () => { wsAlive = true; });
+        const wsHeartbeat = setInterval(() => {
+            if (ws.readyState !== ws.OPEN) { clearInterval(wsHeartbeat); return; }
+            if (!wsAlive) {
+                clearInterval(wsHeartbeat);
+                try { ws.terminate(); } catch (e) { /* already gone */ }
+                return;
+            }
+            wsAlive = false;
+            try { ws.ping(); } catch (e) { /* closing */ }
+        }, 30000);
+        ws.on('close', () => clearInterval(wsHeartbeat));
+
         room.attachClient(
             {
                 id: randomUUID(),
                 name,
                 source,
+                deviceKey,
                 colorIndex: Math.floor(Math.random() * 1000),
                 cols,
                 rows,

package/skills/hop-session/SKILL.md

@@ -37,7 +37,7 @@ hop view report.html analysis.pdf
 `hop view` copies the file behind hop's auth and prints a `View:` URL. The
 human taps it and their browser renders it — on the desktop wall or from the
 phone app, which opens these in-app. It rings the bell once for you, since a
-published artifact is usually the thing the human is waiting on. Re-running
+published file is usually the thing the human is waiting on. Re-running
 it after updating the file re-publishes under the same link.
 
 ## Showing a running web server (dev server, local app)

package/tests/terminal-api.integration.test.cjs

@@ -688,3 +688,49 @@ test('bare token API creations default to agent origin', async () => {
   await requestJson(state.port, state.sessionSecret, 'POST', '/api/sessions/delete', { name: 'BareTokenProbe', internalName: 'BareTokenProbe' });
   await requestJson(state.port, state.sessionSecret, 'POST', '/api/sessions/delete', { name: 'CliUserProbe', internalName: 'CliUserProbe' });
 });
+
+// An agent attach with no API activity and no open stream must expire — a
+// crashed or forgetful agent otherwise parks an "agent" in the session's
+// presence forever. Needs a daemon with a short TTL, so this test relaunches
+// (declaration order puts it last; nothing later depends on daemon state).
+test('an idle agent terminal attach is reaped after the TTL', async () => {
+  const previousState = state;
+  daemonEnv = {
+    ...daemonEnv,
+    HOP_TERMINAL_API_IDLE_TTL_MS: '1500',
+    HOP_TERMINAL_API_SWEEP_MS: '300'
+  };
+  await stopDaemon(true);
+  await launchDaemon(previousState);
+
+  const create = await requestJson(state.port, state.sessionSecret, 'POST', '/api/terminals', {
+    name: 'idle-agent-probe',
+    cwd: tempDir
+  }, agentHeaders);
+  assert.equal(create.status, 200);
+  const terminalId = create.data.id;
+
+  const listed = await requestJson(state.port, state.sessionSecret, 'GET', '/api/terminals', null, agentHeaders);
+  assert.ok(listed.data.terminals.some(t => t.id === terminalId), 'attach visible before the TTL');
+
+  // Touches reset the clock: keep it alive past one full TTL with writes.
+  await delay(1000);
+  await requestJson(state.port, state.sessionSecret, 'POST', `/api/terminals/${terminalId}/write`,
+    { data: ' ' }, agentHeaders);
+  await delay(1000);
+  const alive = await requestJson(state.port, state.sessionSecret, 'GET', '/api/terminals', null, agentHeaders);
+  assert.ok(alive.data.terminals.some(t => t.id === terminalId), 'touched attach survives past a TTL of idle-from-create');
+
+  // Now go silent: the sweep must detach it (session itself stays alive).
+  await delay(2500);
+  const after = await requestJson(state.port, state.sessionSecret, 'GET', '/api/terminals', null, agentHeaders);
+  assert.ok(!after.data.terminals.some(t => t.id === terminalId), 'idle attach reaped');
+  const sessions = await requestJson(state.port, state.sessionSecret, 'GET', '/api/sessions');
+  const s = sessions.data.sessions.find(x => x.displayName === 'idle-agent-probe');
+  assert.ok(s, 'the session itself outlives its reaped attach');
+  const clients = Number(s.clientCount) || 0;
+  assert.equal(clients, 0, `reap must detach the room client, got clientCount=${clients}`);
+
+  await requestJson(state.port, state.sessionSecret, 'POST', '/api/sessions/delete',
+    { name: 'idle-agent-probe', internalName: s.internalName });
+});