npm - tmuxes - Versions diffs - 0.1.8 → 0.1.9 - Mend

tmuxes 0.1.8 → 0.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (140) hide show

package/.node-version +1 -0
package/.nvmrc +1 -0
package/.tmp-npm-cache/_cacache/content-v2/sha512/43/27/5e000b8b9c56a6ccc66f709485499f4304e2cb1982582ba571321c07b3ef56fcabd2c671898cc8003365a0485b6fd8e73e7b17b073cec0f7d1628c1a99df +0 -0
package/.tmp-npm-cache/_cacache/content-v2/sha512/51/cf/4301295d74559ed494bae160d54d8741077f89faebb311882ac065019246951e7b53f3dcb913793c42b331e14c7070c4810c3cdc27a427d103a7db4614e0 +0 -0
package/.tmp-npm-cache/_cacache/content-v2/sha512/c3/4d/d68a454a916e74c2617f586fbf770981b33811d667c2547eb0e9fc21938f4ee7e98f1ceee4bde8ad8815b5f6efe21b60eee798837d68f51a3340d7e5bb7a +0 -0
package/.tmp-npm-cache/_cacache/content-v2/sha512/fe/40/2abfbefc96299e8bf714aa91d62607190ae299e102cf5933db2e2904640d65d25d67dbbb6fa2ddc92a17f00b9dbfdf2e37487f67d96ec36c64a285b59a7d +0 -0
package/.tmp-npm-cache/_cacache/index-v5/27/fe/81a3de6ce7ae3d1e41a3421de20c5629998c4ee5d0ffe2037630f03b03b2 +4 -0
package/.tmp-npm-cache/_cacache/index-v5/65/22/dd66711f62681fce09aabb2357a2907b4a0c778ac5227c4baf9603fd86e8 +4 -0
package/.tmp-npm-cache/_update-notifier-last-checked +0 -0
package/AGENTS.md +15 -0
package/CLAUDE.md +3 -0
package/LICENSE +21 -21
package/README.en.md +304 -0
package/README.md +299 -295
package/SECURITY.md +31 -0
package/{public → client}/index.html +12 -13
package/client/package.json +29 -0
package/client/src/App.tsx +123 -0
package/client/src/activity.ts +5 -0
package/client/src/api.ts +130 -0
package/client/src/attention.tsx +157 -0
package/client/src/components/FileExplorer.tsx +156 -0
package/client/src/components/FileViewer.tsx +194 -0
package/client/src/components/SessionRow.tsx +108 -0
package/client/src/components/SessionTree.tsx +197 -0
package/client/src/components/SettingsButton.tsx +122 -0
package/client/src/components/Sidebar.tsx +96 -0
package/client/src/components/StatusBanner.tsx +31 -0
package/client/src/components/TargetGroup.tsx +275 -0
package/client/src/components/TerminalPanel.tsx +192 -0
package/client/src/folders.ts +245 -0
package/client/src/hooks/useTerminal.ts +67 -0
package/client/src/hooks/useTmuxSocket.ts +65 -0
package/client/src/i18n.ts +213 -0
package/client/src/main.tsx +17 -0
package/client/src/settings.tsx +87 -0
package/client/src/styles.css +723 -0
package/client/src/types.ts +93 -0
package/client/src/util.ts +65 -0
package/client/tsconfig.json +13 -0
package/client/vite.config.ts +15 -0
package/fig/fig1.png +0 -0
package/package.json +28 -61
package/scripts/prepack.mjs +35 -0
package/{bin → server/bin}/tmuxes.js +36 -36
package/server/package.json +61 -0
package/server/src/agentHooks.ts +120 -0
package/server/src/agentOutput.ts +36 -0
package/server/src/agentState.ts +70 -0
package/server/src/config.ts +31 -0
package/server/src/exe.ts +34 -0
package/server/src/exec.ts +61 -0
package/server/src/files.ts +330 -0
package/server/src/foldersStore.ts +114 -0
package/server/src/index.ts +114 -0
package/server/src/logger.ts +16 -0
package/{dist/monitor.js → server/src/monitor.ts} +10 -9
package/server/src/openBrowser.ts +28 -0
package/{dist/platform.js → server/src/platform.ts} +4 -5
package/server/src/rest/router.ts +290 -0
package/server/src/targetCommand.ts +79 -0
package/server/src/targets.ts +152 -0
package/server/src/tmux/builder.ts +198 -0
package/server/src/tmux/formats.ts +95 -0
package/server/src/tmux/sessions.ts +204 -0
package/server/src/validate.ts +79 -0
package/server/src/windowsSsh.ts +239 -0
package/server/src/winshell/manager.ts +296 -0
package/server/src/ws/protocol.ts +15 -0
package/server/src/ws/sshState.ts +36 -0
package/server/src/ws/terminalSession.ts +207 -0
package/server/src/ws/wsServer.ts +153 -0
package/server/src/wsl.ts +38 -0
package/server/test/agentHooks.test.ts +66 -0
package/server/test/agentOutput.test.ts +26 -0
package/server/test/agentState.test.ts +24 -0
package/server/test/builder.test.ts +162 -0
package/server/test/files.test.ts +81 -0
package/server/test/formats.test.ts +123 -0
package/server/test/monitor.test.ts +25 -0
package/server/test/validate.test.ts +71 -0
package/server/test/wsl.test.ts +18 -0
package/server/tsconfig.json +9 -0
package/server/vitest.config.ts +12 -0
package/start.cmd +30 -0
package/start.command +20 -0
package/start.sh +20 -0
package/tsconfig.base.json +19 -0
package/dist/agentHooks.js +0 -91
package/dist/agentHooks.js.map +0 -1
package/dist/agentOutput.js +0 -30
package/dist/agentOutput.js.map +0 -1
package/dist/agentState.js +0 -45
package/dist/agentState.js.map +0 -1
package/dist/config.js +0 -32
package/dist/config.js.map +0 -1
package/dist/exe.js +0 -37
package/dist/exe.js.map +0 -1
package/dist/exec.js +0 -43
package/dist/exec.js.map +0 -1
package/dist/files.js +0 -243
package/dist/files.js.map +0 -1
package/dist/foldersStore.js +0 -103
package/dist/foldersStore.js.map +0 -1
package/dist/index.js +0 -117
package/dist/index.js.map +0 -1
package/dist/logger.js +0 -16
package/dist/logger.js.map +0 -1
package/dist/monitor.js.map +0 -1
package/dist/openBrowser.js +0 -31
package/dist/openBrowser.js.map +0 -1
package/dist/platform.js.map +0 -1
package/dist/rest/router.js +0 -190
package/dist/rest/router.js.map +0 -1
package/dist/targetCommand.js +0 -41
package/dist/targetCommand.js.map +0 -1
package/dist/targets.js +0 -131
package/dist/targets.js.map +0 -1
package/dist/tmux/builder.js +0 -173
package/dist/tmux/builder.js.map +0 -1
package/dist/tmux/formats.js +0 -61
package/dist/tmux/formats.js.map +0 -1
package/dist/tmux/sessions.js +0 -157
package/dist/tmux/sessions.js.map +0 -1
package/dist/validate.js +0 -65
package/dist/validate.js.map +0 -1
package/dist/winshell/manager.js +0 -267
package/dist/winshell/manager.js.map +0 -1
package/dist/ws/protocol.js +0 -4
package/dist/ws/protocol.js.map +0 -1
package/dist/ws/sshState.js +0 -35
package/dist/ws/sshState.js.map +0 -1
package/dist/ws/terminalSession.js +0 -204
package/dist/ws/terminalSession.js.map +0 -1
package/dist/ws/wsServer.js +0 -151
package/dist/ws/wsServer.js.map +0 -1
package/dist/wsl.js +0 -35
package/dist/wsl.js.map +0 -1
package/public/assets/index-BpVrfoZw.js +0 -44
package/public/assets/index-D_X5SnGx.css +0 -1

package/SECURITY.md ADDED Viewed

@@ -0,0 +1,31 @@
+# Security Policy
+tmuxes is a localhost-only, single-user developer tool.
+It intentionally gives the browser UI access to live tmux sessions, keyboard input, and files inside a selected session's current working directory. Treat anyone who can reach the HTTP server as having shell-level access to the target machine or SSH host.
+## Supported Use
+- Run tmuxes only on a trusted workstation.
+- The server binds to `127.0.0.1` only. Do not reverse-proxy, tunnel, port-forward, or otherwise expose it to a network.
+- tmuxes has no authentication by design.
+- SSH targets use your existing system `ssh` configuration, keys, and agent. tmuxes does not store SSH passwords or private keys.
+- The file browser/editor is scoped to the selected tmux session's current working directory.
+## Unsupported Use
+- Binding to `0.0.0.0` or a LAN/public interface.
+- Running tmuxes as a shared multi-user service.
+- Exposing tmuxes through ngrok, cloudflared, SSH remote forwards, reverse proxies, or container port publishing.
+- Treating tmuxes as a hardened remote administration system.
+## Reporting a Vulnerability
+Please open a private security advisory on GitHub if the repository is hosted there. If advisories are not enabled, contact the maintainer privately before publishing details.
+Useful reports include:
+- Steps to reproduce.
+- Affected platform and Node.js version.
+- Whether the issue affects local, WSL, or SSH targets.
+- The expected security boundary and how it was bypassed.

package/{public → client}/index.html RENAMED Viewed

@@ -1,13 +1,12 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>tmuxes</title>
-    <script type="module" crossorigin src="/assets/index-BpVrfoZw.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-D_X5SnGx.css">
-  </head>
-  <body>
-    <div id="root"></div>
-  </body>
-</html>
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>tmuxes</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/client/package.json ADDED Viewed

@@ -0,0 +1,29 @@
+{
+  "name": "@tmuxes/client",
+  "version": "0.1.0",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0 <23"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-web-links": "^0.12.0",
+    "@xterm/xterm": "^6.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.1",
+    "@types/react-dom": "^19.0.2",
+    "@vitejs/plugin-react": "^5.0.0",
+    "typescript": "^5.7.2",
+    "vite": "^8.0.0"
+  }
+}

package/client/src/App.tsx ADDED Viewed

@@ -0,0 +1,123 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { api, ApiError } from './api';
+import type { OpenFile, Selection, Target } from './types';
+import { useSettings } from './settings';
+import { useAttention } from './attention';
+import { useI18n } from './i18n';
+import { Sidebar } from './components/Sidebar';
+import { TerminalPanel } from './components/TerminalPanel';
+import { FileViewer } from './components/FileViewer';
+export function App() {
+  const { settings } = useSettings();
+  const { t } = useI18n();
+  const attention = useAttention();
+  const [targets, setTargets] = useState<Target[]>([]);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  const [selection, setSelection] = useState<Selection | null>(null);
+  const [openFile, setOpenFile] = useState<OpenFile | null>(null);
+  const [nowMs, setNowMs] = useState(() => Date.now());
+  const [viewerHeight, setViewerHeight] = useState(300);
+  const dragState = useRef<{ startY: number; startH: number } | null>(null);
+  const loadTargets = useCallback(async () => {
+    try {
+      const { targets } = await api.getTargets();
+      setTargets(targets);
+      setLoadError(null);
+    } catch (e) {
+      setLoadError(e instanceof ApiError ? e.message : t.failedLoadTargets);
+    }
+  }, [t.failedLoadTargets]);
+  useEffect(() => {
+    void loadTargets();
+  }, [loadTargets]);
+  // Switching sessions changes the file context — close any open file.
+  useEffect(() => {
+    setOpenFile(null);
+  }, [selection?.targetId, selection?.session]);
+  // Tell the attention tracker which session is in view, so it acknowledges
+  // (clears) that session's badge and won't alert the one you're watching.
+  useEffect(() => {
+    attention.setActive(selection?.targetId ?? null, selection?.session ?? null);
+  }, [attention, selection?.targetId, selection?.session]);
+  // Tick for relative "created" times in the sidebar.
+  useEffect(() => {
+    const id = window.setInterval(() => setNowMs(Date.now()), 30_000);
+    return () => window.clearInterval(id);
+  }, []);
+  const onViewerDividerDown = useCallback(
+    (e: React.MouseEvent) => {
+      e.preventDefault();
+      dragState.current = { startY: e.clientY, startH: viewerHeight };
+      const onMove = (ev: MouseEvent) => {
+        if (!dragState.current) return;
+        const delta = dragState.current.startY - ev.clientY; // drag up → taller viewer
+        const max = window.innerHeight - 160;
+        setViewerHeight(Math.max(100, Math.min(max, dragState.current.startH + delta)));
+      };
+      const onUp = () => {
+        dragState.current = null;
+        window.removeEventListener('mousemove', onMove);
+        window.removeEventListener('mouseup', onUp);
+      };
+      window.addEventListener('mousemove', onMove);
+      window.addEventListener('mouseup', onUp);
+    },
+    [viewerHeight],
+  );
+  const selectedTarget = selection ? targets.find((t) => t.id === selection.targetId) : undefined;
+  return (
+    <div className="app">
+      <Sidebar
+        targets={targets}
+        selection={selection}
+        nowMs={nowMs}
+        loadError={loadError}
+        openFile={openFile}
+        select={setSelection}
+        onRefreshTargets={() => void loadTargets()}
+        onOpenFile={setOpenFile}
+      />
+      <div className="workspace">
+        <div className="term-region">
+          {selection && selectedTarget ? (
+            <TerminalPanel
+              key={`${selection.targetId}/${selection.session}`}
+              targetId={selection.targetId}
+              targetKind={selectedTarget.kind}
+              targetLabel={selectedTarget.label}
+              session={selection.session}
+              fontSize={settings.terminalFontSize}
+            />
+          ) : (
+            <div className="panel">
+              <div className="panel-placeholder">
+                <div style={{ fontSize: 18 }}>{t.selectOrCreateSession}</div>
+                <div>{t.pickSession}</div>
+              </div>
+            </div>
+          )}
+        </div>
+        {openFile && (
+          <>
+            <div className="hdivider" onMouseDown={onViewerDividerDown} title={t.dragResize} />
+            <div className="viewer-region" style={{ height: viewerHeight }}>
+              <FileViewer file={openFile} onClose={() => setOpenFile(null)} />
+            </div>
+          </>
+        )}
+      </div>
+    </div>
+  );
+}

package/client/src/activity.ts ADDED Viewed

@@ -0,0 +1,5 @@
+import type { SessionInfo } from './types';
+export function isSessionActive(session: SessionInfo): boolean {
+  return session.agentState === 'running';
+}

package/client/src/api.ts ADDED Viewed

@@ -0,0 +1,130 @@
+import type {
+  FileEntry,
+  FilePreview,
+  LaunchAgent,
+  SessionDirectory,
+  SessionInfo,
+  Target,
+  WindowInfo,
+} from './types';
+async function request<T>(path: string, init?: RequestInit): Promise<T> {
+  const res = await fetch(path, {
+    headers: { 'Content-Type': 'application/json' },
+    ...init,
+  });
+  if (!res.ok) {
+    let message = `${res.status} ${res.statusText}`;
+    try {
+      const body = (await res.json()) as { error?: string };
+      if (body.error) message = body.error;
+    } catch {
+      /* non-JSON error body */
+    }
+    throw new ApiError(res.status, message);
+  }
+  if (res.status === 204) return undefined as T;
+  return (await res.json()) as T;
+}
+export class ApiError extends Error {
+  constructor(
+    public status: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'ApiError';
+  }
+}
+export const api = {
+  getTargets(): Promise<{ targets: Target[] }> {
+    return request('/api/targets');
+  },
+  getSessions(targetId: string): Promise<{ sessions: SessionInfo[] }> {
+    return request(`/api/targets/${encodeURIComponent(targetId)}/sessions`);
+  },
+  createSession(
+    targetId: string,
+    body: { name?: string; command?: string; shell?: string },
+  ): Promise<{ name: string }> {
+    return request(`/api/targets/${encodeURIComponent(targetId)}/sessions`, {
+      method: 'POST',
+      body: JSON.stringify(body),
+    });
+  },
+  renameSession(targetId: string, name: string, newName: string): Promise<{ name: string }> {
+    return request(
+      `/api/targets/${encodeURIComponent(targetId)}/sessions/${encodeURIComponent(name)}`,
+      { method: 'PATCH', body: JSON.stringify({ newName }) },
+    );
+  },
+  killSession(targetId: string, name: string): Promise<void> {
+    return request(
+      `/api/targets/${encodeURIComponent(targetId)}/sessions/${encodeURIComponent(name)}`,
+      { method: 'DELETE' },
+    );
+  },
+  launchAgent(targetId: string, name: string, agent: LaunchAgent): Promise<{ ok: true }> {
+    return request(
+      `/api/targets/${encodeURIComponent(targetId)}/sessions/${encodeURIComponent(name)}/agent`,
+      { method: 'POST', body: JSON.stringify({ agent }) },
+    );
+  },
+  getWindows(targetId: string, name: string): Promise<{ windows: WindowInfo[] }> {
+    return request(
+      `/api/targets/${encodeURIComponent(targetId)}/sessions/${encodeURIComponent(name)}/windows`,
+    );
+  },
+  getCwd(targetId: string, name: string): Promise<{ cwd: string }> {
+    return request(
+      `/api/targets/${encodeURIComponent(targetId)}/sessions/${encodeURIComponent(name)}/cwd`,
+    );
+  },
+  listFiles(targetId: string, session: string, path: string): Promise<{ path: string; entries: FileEntry[] }> {
+    return request(
+      `/api/targets/${encodeURIComponent(targetId)}/files?session=${encodeURIComponent(session)}&path=${encodeURIComponent(path)}`,
+    );
+  },
+  getSessionFiles(targetId: string, session: string, path?: string): Promise<SessionDirectory> {
+    const qs = path === undefined ? '' : `?path=${encodeURIComponent(path)}`;
+    return request(
+      `/api/targets/${encodeURIComponent(targetId)}/sessions/${encodeURIComponent(session)}/files${qs}`,
+    );
+  },
+  getFile(targetId: string, session: string, path: string): Promise<FilePreview> {
+    return request(
+      `/api/targets/${encodeURIComponent(targetId)}/file?session=${encodeURIComponent(session)}&path=${encodeURIComponent(path)}`,
+    );
+  },
+  saveFile(targetId: string, session: string, path: string, content: string): Promise<{ ok: true }> {
+    return request(`/api/targets/${encodeURIComponent(targetId)}/file`, {
+      method: 'PUT',
+      body: JSON.stringify({ session, path, content }),
+    });
+  },
+  getFolders(targetId: string): Promise<{ folders: unknown[]; assign: Record<string, unknown> }> {
+    return request(`/api/targets/${encodeURIComponent(targetId)}/folders`);
+  },
+  saveFolders(
+    targetId: string,
+    payload: { folders: unknown[]; assign: Record<string, string> },
+  ): Promise<{ ok: true }> {
+    return request(`/api/targets/${encodeURIComponent(targetId)}/folders`, {
+      method: 'PUT',
+      body: JSON.stringify(payload),
+    });
+  },
+};
+/** Build the WebSocket URL for an interactive attach (same-origin). */
+export function terminalSocketUrl(targetId: string, session: string, cols: number, rows: number): string {
+  const proto = location.protocol === 'https:' ? 'wss' : 'ws';
+  const params = new URLSearchParams({
+    target: targetId,
+    session,
+    cols: String(cols),
+    rows: String(rows),
+  });
+  return `${proto}://${location.host}/ws?${params.toString()}`;
+}

package/client/src/attention.tsx ADDED Viewed

@@ -0,0 +1,157 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
+import { useSettings } from './settings';
+import type { AttentionReason } from './types';
+/** Tracks sessions that need attention after an agent hook event and delivers
+ *  the notification: a sidebar highlight, a short sound, and a flashing tab
+ *  title while the tab is in the background. */
+interface AttentionApi {
+  /** Current badge reason for a session, if any. */
+  reasonFor: (targetId: string, session: string) => AttentionReason | undefined;
+  /** Raise attention for a session. */
+  fire: (targetId: string, session: string, reason: AttentionReason) => void;
+  /** A session became active again — drop its badge. */
+  clearAlert: (targetId: string, session: string) => void;
+  /** The user is now looking at this session — acknowledge its alert. */
+  setActive: (targetId: string | null, session: string | null) => void;
+}
+const AttentionContext = createContext<AttentionApi | null>(null);
+const keyOf = (targetId: string, session: string) => `${targetId}\u0000${session}`;
+let audioCtx: AudioContext | null = null;
+function playPing(): void {
+  try {
+    const Ctor = window.AudioContext ?? (window as unknown as { webkitAudioContext?: typeof AudioContext }).webkitAudioContext;
+    if (!Ctor) return;
+    audioCtx ??= new Ctor();
+    const ctx = audioCtx;
+    if (ctx.state === 'suspended') void ctx.resume();
+    const osc = ctx.createOscillator();
+    const gain = ctx.createGain();
+    osc.connect(gain);
+    gain.connect(ctx.destination);
+    osc.type = 'sine';
+    osc.frequency.value = 880;
+    const t = ctx.currentTime;
+    gain.gain.setValueAtTime(0.0001, t);
+    gain.gain.exponentialRampToValueAtTime(0.18, t + 0.01);
+    gain.gain.exponentialRampToValueAtTime(0.0001, t + 0.28);
+    osc.start(t);
+    osc.stop(t + 0.3);
+  } catch {
+    /* audio not available / blocked before a gesture — ignore */
+  }
+}
+export function AttentionProvider({ children }: { children: ReactNode }) {
+  const { settings } = useSettings();
+  const [alerts, setAlerts] = useState<Record<string, AttentionReason>>({});
+  const activeKey = useRef<string | null>(null);
+  // Keep the latest sound preference readable inside async callbacks.
+  const soundOn = useRef(settings.notifySound);
+  soundOn.current = settings.notifySound;
+  const fire = useCallback<AttentionApi['fire']>((targetId, session, reason) => {
+    if (!settings.notifyAttention) return;
+    const key = keyOf(targetId, session);
+    // The user is already watching this session in the foreground — no need.
+    if (key === activeKey.current && !document.hidden) return;
+    setAlerts((prev) => ({ ...prev, [key]: reason }));
+    if (soundOn.current) playPing();
+  }, [settings.notifyAttention]);
+  const clearAlert = useCallback<AttentionApi['clearAlert']>((targetId, session) => {
+    const key = keyOf(targetId, session);
+    setAlerts((prev) => {
+      if (!(key in prev)) return prev;
+      const next = { ...prev };
+      delete next[key];
+      return next;
+    });
+  }, []);
+  const setActive = useCallback<AttentionApi['setActive']>((targetId, session) => {
+    const key = targetId && session ? keyOf(targetId, session) : null;
+    activeKey.current = key;
+    if (!key) return;
+    setAlerts((prev) => {
+      if (!(key in prev)) return prev;
+      const next = { ...prev };
+      delete next[key];
+      return next;
+    });
+  }, []);
+  const reasonFor = useCallback<AttentionApi['reasonFor']>(
+    (targetId, session) => alerts[keyOf(targetId, session)],
+    [alerts],
+  );
+  // Flash the tab title while there are pending alerts and the tab is hidden.
+  useEffect(() => {
+    const count = Object.keys(alerts).length;
+    const base = 'tmuxes';
+    if (count === 0) {
+      document.title = base;
+      return;
+    }
+    let on = false;
+    const render = () => {
+      if (document.hidden) {
+        on = !on;
+        document.title = on ? `🔔 (${count}) ${base}` : base;
+      } else {
+        document.title = base;
+      }
+    };
+    render();
+    const id = window.setInterval(render, 1000);
+    const onVis = () => {
+      if (!document.hidden) {
+        // Foreground again: stop flashing; acknowledge whatever is being viewed.
+        document.title = base;
+        if (activeKey.current) {
+          const key = activeKey.current;
+          setAlerts((prev) => {
+            if (!(key in prev)) return prev;
+            const next = { ...prev };
+            delete next[key];
+            return next;
+          });
+        }
+      } else {
+        render();
+      }
+    };
+    document.addEventListener('visibilitychange', onVis);
+    return () => {
+      window.clearInterval(id);
+      document.removeEventListener('visibilitychange', onVis);
+      document.title = base;
+    };
+  }, [alerts]);
+  const value = useMemo<AttentionApi>(
+    () => ({ reasonFor, fire, clearAlert, setActive }),
+    [reasonFor, fire, clearAlert, setActive],
+  );
+  return <AttentionContext.Provider value={value}>{children}</AttentionContext.Provider>;
+}
+export function useAttention(): AttentionApi {
+  const ctx = useContext(AttentionContext);
+  if (!ctx) throw new Error('useAttention must be used within AttentionProvider');
+  return ctx;
+}

package/client/src/components/FileExplorer.tsx ADDED Viewed

@@ -0,0 +1,156 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { FileEntry, OpenFile, Selection } from '../types';
+import { api, ApiError } from '../api';
+import { basename, isTextFile, joinPath, parentPath } from '../util';
+import { useI18n } from '../i18n';
+interface Props {
+  selection: Selection | null;
+  openFile: OpenFile | null;
+  /** Native shell sessions have no tmux cwd — disables the file browser. */
+  enabled: boolean;
+  /** Pause automatic polling after SSH errors to avoid repeated failed attempts. */
+  pauseOnError: boolean;
+  onOpenFile: (file: OpenFile) => void;
+}
+const POLL_MS = 3000;
+function samePath(a: string | null, b: string | null): boolean {
+  if (!a || !b) return false;
+  const clean = (p: string) => (p === '/' ? p : p.replace(/\/+$/, ''));
+  return clean(a) === clean(b);
+}
+/** Bottom of the sidebar: the files/folders of the selected session's current
+ *  working directory. Follows the session's cwd until you navigate away. */
+export function FileExplorer({ selection, openFile, enabled, pauseOnError, onOpenFile }: Props) {
+  const { t } = useI18n();
+  const [cwd, setCwd] = useState<string | null>(null);
+  const [manualPath, setManualPath] = useState<string | null>(null);
+  const [entries, setEntries] = useState<FileEntry[]>([]);
+  const [error, setError] = useState<string | null>(null);
+  const pollingPaused = useRef(false);
+  const path = manualPath ?? cwd;
+  const following = manualPath === null;
+  const targetId = selection?.targetId;
+  const session = selection?.session;
+  // New selection → re-follow that session's cwd.
+  useEffect(() => {
+    setManualPath(null);
+    setCwd(null);
+    setEntries([]);
+    setError(null);
+    pollingPaused.current = false;
+  }, [targetId, session]);
+  const tick = useCallback(async () => {
+    if (pollingPaused.current) return;
+    if (!targetId || !session) return;
+    try {
+      const { cwd: latest, entries } = await api.getSessionFiles(
+        targetId,
+        session,
+        manualPath ?? undefined,
+      );
+      setCwd(latest);
+      setEntries(entries);
+      setError(null);
+    } catch (e) {
+      setError(e instanceof ApiError ? e.message : t.cannotListDirectory);
+      if (pauseOnError) pollingPaused.current = true;
+    }
+  }, [targetId, session, manualPath, pauseOnError, t.cannotListDirectory]);
+  const manualReconnect = useCallback(() => {
+    pollingPaused.current = false;
+    setError(null);
+    void tick();
+  }, [tick]);
+  useEffect(() => {
+    if (!targetId || !session || !enabled) return;
+    void tick();
+    const id = window.setInterval(() => void tick(), POLL_MS);
+    return () => window.clearInterval(id);
+  }, [targetId, session, enabled, tick]);
+  if (!selection) {
+    return (
+      <div className="explorer">
+        <div className="explorer-empty">{t.selectSessionForFiles}</div>
+      </div>
+    );
+  }
+  if (!enabled) {
+    return (
+      <div className="explorer">
+        <div className="explorer-empty">{t.fileBrowserUnavailable}</div>
+      </div>
+    );
+  }
+  const navigate = (entry: FileEntry) => {
+    if (!path) return;
+    const full = joinPath(path, entry.name);
+    if (entry.type === 'dir') {
+      setManualPath(full);
+    } else if (isTextFile(entry.name)) {
+      onOpenFile({ targetId: selection.targetId, session: selection.session, path: full, name: entry.name });
+    }
+  };
+  const atRoot = samePath(path, cwd);
+  return (
+    <div className="explorer">
+      <div className="explorer-head">
+        <span className="explorer-path" title={path ?? ''}>
+          {path ? basename(path) : '…'}
+        </span>
+        <span className="explorer-actions">
+          {!following && (
+            <button title={t.backToSessionDirectory} onClick={() => setManualPath(null)}>
+              ⌂
+            </button>
+          )}
+          <button title={t.upOneLevel} disabled={!path || path === '/' || atRoot} onClick={() => path && setManualPath(parentPath(path))}>
+            ↑
+          </button>
+        </span>
+      </div>
+      {error && (
+        <div className="error-line">
+          <span>{error}</span>
+          {pauseOnError && (
+            <button onClick={manualReconnect}>
+              {t.reconnect}
+            </button>
+          )}
+        </div>
+      )}
+      <div className="explorer-list">
+        {entries.map((e) => {
+          const openable = e.type === 'dir' || isTextFile(e.name);
+          const isOpen =
+            openFile?.targetId === selection.targetId && path && openFile.path === joinPath(path, e.name);
+          return (
+            <div
+              key={e.name}
+              className={`file-row ${e.type} ${openable ? '' : 'disabled'} ${isOpen ? 'open' : ''}`}
+              onClick={() => openable && navigate(e)}
+              title={e.name}
+            >
+              <span className="file-icon">{e.type === 'dir' ? '📁' : isTextFile(e.name) ? '📄' : '▫'}</span>
+              <span className="file-name">{e.name}</span>
+            </div>
+          );
+        })}
+        {entries.length === 0 && !error && <div className="explorer-empty">{t.emptyDirectory}</div>}
+      </div>
+    </div>
+  );
+}