tmuxes 0.1.7 → 0.1.9

package/server/src/agentState.ts

@@ -0,0 +1,70 @@
+export type AgentKind = 'claude' | 'codex';
+export type AgentState = 'running' | 'waiting' | 'idle';
+export type AttentionReason = 'decision' | 'done' | 'error';
+
+export interface AgentSnapshot {
+  agentKind: AgentKind;
+  agentState: AgentState;
+  attentionReason?: AttentionReason;
+  agentEvent?: string;
+  agentNonce?: string;
+}
+
+export const AGENT_OPTION = '@tmuxes_agent';
+
+function isAgentKind(v: string): v is AgentKind {
+  return v === 'claude' || v === 'codex';
+}
+
+function isAgentState(v: string): v is AgentState {
+  return v === 'running' || v === 'waiting' || v === 'idle';
+}
+
+function isAttentionReason(v: string): v is AttentionReason {
+  return v === 'decision' || v === 'done' || v === 'error';
+}
+
+function cleanToken(v: string): string {
+  return v.replace(/[^A-Za-z0-9_.-]/g, '_');
+}
+
+export function agentValue(
+  kind: AgentKind,
+  state: AgentState,
+  reason: AttentionReason | '',
+  event: string,
+  nonce: string,
+): string {
+  return [
+    kind,
+    state,
+    reason,
+    cleanToken(event),
+    nonce.replace(/:/g, '_'),
+  ].join(':');
+}
+
+export function agentInitialValue(kind: AgentKind): string {
+  return agentValue(kind, 'idle', '', 'launch', String(Date.now()));
+}
+
+export function agentHookCommand(
+  kind: AgentKind,
+  state: AgentState,
+  reason: AttentionReason | '',
+  event: string,
+): string {
+  return `tmux set-option -q ${AGENT_OPTION} ${agentValue(kind, state, reason, event, '$(date +%s).$$')}`;
+}
+
+export function parseAgentValue(raw: string | undefined): AgentSnapshot | undefined {
+  if (!raw) return undefined;
+  const [kind, state, reason, event, ...nonceParts] = raw.split(':');
+  if (!isAgentKind(kind) || !isAgentState(state)) return undefined;
+  const snap: AgentSnapshot = { agentKind: kind, agentState: state };
+  if (isAttentionReason(reason)) snap.attentionReason = reason;
+  if (event) snap.agentEvent = event;
+  const nonce = nonceParts.join(':');
+  if (nonce) snap.agentNonce = nonce;
+  return snap;
+}

package/server/src/config.ts

@@ -0,0 +1,31 @@
+/** Central configuration. Localhost-only by design — see README/SECURITY. */
+export const config = {
+  /** Bind address. Intentionally not configurable: this is a no-auth local shell UI. */
+  host: '127.0.0.1',
+  port: Number(process.env.TMUXES_PORT ?? 7420),
+
+  /** ssh timeouts (seconds). */
+  ssh: {
+    /** Management calls fail fast so the UI never hangs. */
+    connectTimeoutMgmt: 8,
+    /** Interactive attach is allowed a little longer. */
+    connectTimeoutTty: 10,
+    /** Keep the OpenSSH control master alive for long-lived SSH reuse. */
+    controlPersist: 'yes',
+  },
+
+  /**
+   * Allowed WebSocket Origins. The WS upgrade bypasses Express middleware, so
+   * we enforce this in the upgrade handler to block DNS-rebind / cross-site WS
+   * hijack. Empty/absent Origin (non-browser clients) is allowed.
+   */
+  isAllowedOrigin(origin: string | undefined): boolean {
+    if (!origin) return true;
+    try {
+      const { hostname } = new URL(origin);
+      return hostname === '127.0.0.1' || hostname === 'localhost' || hostname === '[::1]';
+    } catch {
+      return false;
+    }
+  },
+} as const;

package/server/src/exe.ts

@@ -0,0 +1,34 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute, join, delimiter } from 'node:path';
+import { isWindows } from './platform.js';
+
+/**
+ * Resolve a command name to a full path for node-pty on Windows.
+ *
+ * Unlike child_process.spawn, node-pty's ConPTY path does NOT search PATH or
+ * append a PATHEXT extension, so `pty.spawn('ssh', …)` fails with
+ * "File not found". We resolve the executable ourselves (PATH + common system
+ * locations). On POSIX, execvp already searches PATH, so the name is returned
+ * unchanged.
+ */
+export function resolveExecutable(file: string): string {
+  if (!isWindows) return file;
+  if (isAbsolute(file) && existsSync(file)) return file;
+
+  const hasExt = /\.[A-Za-z0-9]+$/.test(file);
+  const exts = hasExt ? [''] : (process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';');
+  const sysRoot = process.env.SystemRoot || process.env.windir || 'C:\\Windows';
+  const dirs = [
+    ...(process.env.PATH || '').split(delimiter),
+    join(sysRoot, 'System32'),
+    join(sysRoot, 'System32', 'OpenSSH'), // ssh.exe ships here, not always on PATH
+  ];
+  for (const dir of dirs) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const candidate = join(dir, file + ext);
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return file; // fall back; node-pty surfaces a clear error if truly missing
+}

package/server/src/exec.ts

@@ -0,0 +1,61 @@
+import { spawn } from 'node:child_process';
+
+export interface CommandResult {
+  code: number | null;
+  signal: NodeJS.Signals | null;
+  stdout: string;
+  stderr: string;
+}
+
+export interface RunOptions {
+  timeoutMs?: number;
+  /** stdout decoding — wsl.exe emits UTF-16LE, everything else is UTF-8. */
+  encoding?: BufferEncoding;
+  /** Written to the child's stdin (then closed) — used to pipe file contents. */
+  input?: string;
+}
+
+/**
+ * Run a command as an argv array with NO shell. Never rejects — a nonzero exit
+ * or spawn error resolves with the captured output so callers can interpret it
+ * (e.g. tmux "no server running" is a normal empty case, not a throw).
+ */
+export function runCommand(file: string, args: string[], opts: RunOptions = {}): Promise<CommandResult> {
+  const encoding = opts.encoding ?? 'utf8';
+  return new Promise((resolve) => {
+    const child = spawn(file, args, { shell: false });
+    const outChunks: Buffer[] = [];
+    const errChunks: Buffer[] = [];
+    let settled = false;
+
+    const timer = opts.timeoutMs
+      ? setTimeout(() => {
+          child.kill('SIGKILL');
+        }, opts.timeoutMs)
+      : null;
+
+    child.stdout.on('data', (d: Buffer) => outChunks.push(d));
+    child.stderr.on('data', (d: Buffer) => errChunks.push(d));
+
+    if (opts.input !== undefined) {
+      child.stdin.on('error', () => {
+        /* ignore EPIPE if the child exits early */
+      });
+      child.stdin.end(opts.input);
+    }
+
+    const done = (code: number | null, signal: NodeJS.Signals | null, extraErr?: string) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      const stderr = Buffer.concat(errChunks).toString(encoding) + (extraErr ?? '');
+      resolve({ code, signal, stdout: Buffer.concat(outChunks).toString(encoding), stderr });
+    };
+
+    child.on('error', (err) => {
+      // e.g. ENOENT when ssh/tmux/wsl.exe is missing — surface as a failed result.
+      done(null, null, err.message);
+    });
+    child.on('close', (code, signal) => done(code, signal));
+  });
+}

package/server/src/files.ts

@@ -0,0 +1,330 @@
+import { promises as fsp } from 'node:fs';
+import { basename as posixBasename, dirname as posixDirname } from 'node:path/posix';
+import { commandArgv } from './tmux/builder.js';
+import { TmuxError } from './tmux/sessions.js';
+import type { Target } from './targets.js';
+import { runTargetCommand } from './targetCommand.js';
+
+const REMOTE_TIMEOUT_MS = 15_000;
+/** Max bytes returned for a file preview. */
+export const FILE_PREVIEW_CAP = 2_000_000;
+/** A NUL anywhere in a preview means the file is binary. */
+const NUL = String.fromCharCode(0);
+
+export interface FileEntry {
+  name: string;
+  type: 'dir' | 'file';
+}
+
+export interface FilePreview {
+  path: string;
+  content: string;
+  truncated: boolean;
+  binary: boolean;
+}
+
+export interface SessionDirectory {
+  cwd: string;
+  path: string;
+  entries: FileEntry[];
+}
+
+const SESSION_DIRECTORY_SCRIPT = [
+  'session=$1',
+  'requested=$2',
+  'cwd=$(tmux display-message -p -t "$session" \'#{pane_current_path}\') || exit $?',
+  'if [ -z "$cwd" ]; then echo "empty session cwd" >&2; exit 70; fi',
+  'root=$(realpath -- "$cwd") || exit $?',
+  'if [ -z "$requested" ]; then requested=$cwd; fi',
+  'case "$requested" in /*) ;; *) echo "path must be absolute" >&2; exit 64;; esac',
+  'candidate=$(realpath -- "$requested") || exit $?',
+  'if [ "$root" = "/" ]; then inside=1; else case "$candidate" in "$root"|"$root"/*) inside=1 ;; *) inside=0 ;; esac; fi',
+  'if [ "$inside" != 1 ]; then echo "path is outside the session working directory" >&2; exit 77; fi',
+  'if [ ! -d "$candidate" ]; then echo "not a directory" >&2; exit 66; fi',
+  'printf "%s\\0%s\\0" "$cwd" "$candidate"',
+  'ls -Ap1 -- "$candidate"',
+].join('\n');
+
+function timeout(t: Target): number | undefined {
+  return t.kind === 'local' ? undefined : REMOTE_TIMEOUT_MS;
+}
+
+function normalizeRoot(path: string): string {
+  if (path === '/') return path;
+  return path.replace(/\/+$/, '');
+}
+
+export function isInsideRoot(root: string, candidate: string): boolean {
+  const normalizedRoot = normalizeRoot(root);
+  return normalizedRoot === '/' || candidate === normalizedRoot || candidate.startsWith(`${normalizedRoot}/`);
+}
+
+async function remoteRealpath(t: Target, path: string): Promise<string> {
+  const r = await run(t, ['realpath', path]);
+  if (r.code !== 0) {
+    if (/No such file|not found/i.test(r.stderr)) throw new TmuxError(404, 'path not found');
+    if (/Permission denied/i.test(r.stderr)) throw new TmuxError(403, 'permission denied');
+    throw new TmuxError(502, r.stderr.trim().split('\n')[0] || 'cannot resolve path');
+  }
+  const resolved = r.stdout.trim().split('\n')[0];
+  if (!resolved) throw new TmuxError(502, 'empty resolved path');
+  return resolved;
+}
+
+async function realpath(t: Target, path: string): Promise<string> {
+  if (t.kind === 'local') {
+    try {
+      return await fsp.realpath(path);
+    } catch (e) {
+      throw fsError(e, path);
+    }
+  }
+  return remoteRealpath(t, path);
+}
+
+async function tryRealpath(t: Target, path: string): Promise<string | null> {
+  try {
+    return await realpath(t, path);
+  } catch (e) {
+    if (e instanceof TmuxError && e.status === 404) return null;
+    throw e;
+  }
+}
+
+/**
+ * Resolve a requested target path and verify it stays inside the session's cwd.
+ * This keeps the file browser/editor scoped to the agent workspace instead of
+ * exposing arbitrary host files through the no-auth local server.
+ */
+export async function resolveScopedPath(
+  t: Target,
+  rootPath: string,
+  requestedPath: string,
+  opts: { forWrite?: boolean } = {},
+): Promise<string> {
+  if (!requestedPath.startsWith('/')) throw new TmuxError(400, 'path must be absolute');
+
+  const root = await realpath(t, rootPath);
+  let candidate: string | null = null;
+
+  if (opts.forWrite) {
+    candidate = await tryRealpath(t, requestedPath);
+    if (!candidate) {
+      const name = posixBasename(requestedPath);
+      if (!name || name === '.' || name === '..') throw new TmuxError(400, 'invalid path');
+      const parent = await realpath(t, posixDirname(requestedPath));
+      candidate = parent === '/' ? `/${name}` : `${parent}/${name}`;
+    }
+  } else {
+    candidate = await realpath(t, requestedPath);
+  }
+
+  if (!isInsideRoot(root, candidate)) {
+    throw new TmuxError(403, 'path is outside the session working directory');
+  }
+  return candidate;
+}
+
+async function run(t: Target, argv: string[]) {
+  return runTargetCommand(t, (opts) => commandArgv(t, argv, opts), { timeoutMs: timeout(t) });
+}
+
+/** The working directory of a session's active pane (tmux #{pane_current_path}). */
+export async function getSessionCwd(t: Target, session: string): Promise<string> {
+  const r = await run(t, ['tmux', 'display-message', '-p', '-t', session, '#{pane_current_path}']);
+  if (r.code !== 0) {
+    if (/can't find|no server running|session not found/i.test(r.stderr)) {
+      throw new TmuxError(404, `session "${session}" not found`);
+    }
+    throw new TmuxError(502, r.stderr.trim().split('\n')[0] || 'cannot read session cwd');
+  }
+  const cwd = r.stdout.trim();
+  if (!cwd) throw new TmuxError(502, 'empty session cwd');
+  return cwd;
+}
+
+function sortEntries(entries: FileEntry[]): FileEntry[] {
+  return entries.sort((a, b) => {
+    if (a.type !== b.type) return a.type === 'dir' ? -1 : 1;
+    return a.name.localeCompare(b.name, undefined, { numeric: true, sensitivity: 'base' });
+  });
+}
+
+function parseRemoteEntries(stdout: string): FileEntry[] {
+  return stdout
+    .split('\n')
+    .filter((l) => l.length > 0)
+    .map((line) => {
+      const isDir = line.endsWith('/');
+      const name = isDir ? line.slice(0, -1) : line;
+      return { name, type: isDir ? ('dir' as const) : ('file' as const) };
+    })
+    .filter((e) => e.name && e.name !== '.' && e.name !== '..');
+}
+
+function sessionDirectoryError(session: string, stderr: string): TmuxError {
+  const first = stderr.trim().split('\n')[0] || 'cannot list directory';
+  if (/can't find|no server running|session not found/i.test(stderr)) {
+    return new TmuxError(404, `session "${session}" not found`);
+  }
+  if (/path must be absolute/i.test(stderr)) return new TmuxError(400, 'path must be absolute');
+  if (/not a directory/i.test(stderr)) return new TmuxError(400, 'not a directory');
+  if (/Permission denied/i.test(stderr)) return new TmuxError(403, 'permission denied');
+  if (/outside the session working directory/i.test(stderr)) {
+    return new TmuxError(403, 'path is outside the session working directory');
+  }
+  if (/No such file|not found|realpath:/i.test(stderr)) return new TmuxError(404, 'path not found');
+  return new TmuxError(502, first);
+}
+
+async function remoteSessionDirectory(
+  t: Target,
+  session: string,
+  requestedPath?: string,
+): Promise<SessionDirectory> {
+  if (requestedPath !== undefined && !requestedPath.startsWith('/')) {
+    throw new TmuxError(400, 'path must be absolute');
+  }
+  const r = await run(t, [
+    'sh',
+    '-c',
+    SESSION_DIRECTORY_SCRIPT,
+    'tmuxes-session-directory',
+    session,
+    requestedPath ?? '',
+  ]);
+  if (r.code !== 0) throw sessionDirectoryError(session, r.stderr);
+
+  const firstSep = r.stdout.indexOf(NUL);
+  const secondSep = firstSep < 0 ? -1 : r.stdout.indexOf(NUL, firstSep + 1);
+  if (firstSep < 0 || secondSep < 0) throw new TmuxError(502, 'cannot parse directory listing');
+
+  const cwd = r.stdout.slice(0, firstSep);
+  const path = r.stdout.slice(firstSep + 1, secondSep);
+  const entries = parseRemoteEntries(r.stdout.slice(secondSep + 1));
+  return { cwd, path, entries: sortEntries(entries) };
+}
+
+export async function listSessionDirectory(
+  t: Target,
+  session: string,
+  requestedPath?: string,
+): Promise<SessionDirectory> {
+  if (t.kind !== 'local') return remoteSessionDirectory(t, session, requestedPath);
+
+  const cwd = await getSessionCwd(t, session);
+  const path = await resolveScopedPath(t, cwd, requestedPath ?? cwd);
+  return { cwd, path, entries: await listDirectory(t, path) };
+}
+
+/** List a directory ON THE TARGET. Local uses fs; wsl/ssh shell out to `ls`. */
+export async function listDirectory(t: Target, path: string): Promise<FileEntry[]> {
+  if (t.kind === 'local') {
+    let dirents;
+    try {
+      dirents = await fsp.readdir(path, { withFileTypes: true });
+    } catch (e) {
+      throw fsError(e, path);
+    }
+    const entries: FileEntry[] = [];
+    for (const d of dirents) {
+      if (d.name.startsWith('.') && (d.name === '.' || d.name === '..')) continue;
+      let isDir = d.isDirectory();
+      if (d.isSymbolicLink()) {
+        // Resolve symlinks so linked dirs are navigable.
+        try {
+          const st = await fsp.stat(path.replace(/\/$/, '') + '/' + d.name);
+          isDir = st.isDirectory();
+        } catch {
+          isDir = false;
+        }
+      }
+      entries.push({ name: d.name, type: isDir ? 'dir' : 'file' });
+    }
+    return sortEntries(entries);
+  }
+
+  // wsl/ssh: `ls -Ap1 -- <path>` → one per line, dirs end with "/".
+  const r = await run(t, ['ls', '-Ap1', '--', path]);
+  if (r.code !== 0) {
+    if (/No such file|not found/i.test(r.stderr)) throw new TmuxError(404, 'directory not found');
+    if (/Permission denied/i.test(r.stderr)) throw new TmuxError(403, 'permission denied');
+    throw new TmuxError(502, r.stderr.trim().split('\n')[0] || 'cannot list directory');
+  }
+  return sortEntries(parseRemoteEntries(r.stdout));
+}
+
+/** Read a (capped) file preview ON THE TARGET. */
+export async function readFilePreview(t: Target, path: string): Promise<FilePreview> {
+  if (t.kind === 'local') {
+    let fh;
+    try {
+      fh = await fsp.open(path, 'r');
+    } catch (e) {
+      throw fsError(e, path);
+    }
+    try {
+      const st = await fh.stat();
+      if (st.isDirectory()) throw new TmuxError(400, 'path is a directory');
+      const cap = FILE_PREVIEW_CAP;
+      const buf = Buffer.alloc(Math.min(cap, Number(st.size)));
+      const { bytesRead } = await fh.read(buf, 0, buf.length, 0);
+      const slice = buf.subarray(0, bytesRead);
+      return {
+        path,
+        content: slice.toString('utf8'),
+        truncated: st.size > cap,
+        binary: slice.includes(0),
+      };
+    } finally {
+      await fh.close();
+    }
+  }
+
+  // wsl/ssh: read up to cap+1 bytes; if we got cap+1 the file is larger.
+  const r = await run(t, ['head', '-c', String(FILE_PREVIEW_CAP + 1), '--', path]);
+  if (r.code !== 0) {
+    if (/No such file|not found/i.test(r.stderr)) throw new TmuxError(404, 'file not found');
+    if (/Is a directory/i.test(r.stderr)) throw new TmuxError(400, 'path is a directory');
+    if (/Permission denied/i.test(r.stderr)) throw new TmuxError(403, 'permission denied');
+    throw new TmuxError(502, r.stderr.trim().split('\n')[0] || 'cannot read file');
+  }
+  const truncated = r.stdout.length > FILE_PREVIEW_CAP;
+  const content = truncated ? r.stdout.slice(0, FILE_PREVIEW_CAP) : r.stdout;
+  return { path, content, truncated, binary: content.includes(NUL) };
+}
+
+/** Overwrite a file ON THE TARGET with `content` (UTF-8). Local uses fs;
+ *  wsl/ssh pipe the bytes into `tee -- <path>` over stdin (tee truncates). */
+export async function writeFile(t: Target, path: string, content: string): Promise<void> {
+  if (t.kind === 'local') {
+    try {
+      await fsp.writeFile(path, content, 'utf8');
+    } catch (e) {
+      throw fsError(e, path);
+    }
+    return;
+  }
+
+  // `tee` opens the file with O_TRUNC|O_CREAT, so shorter content can't leave a
+  // stale tail. Its stdout echo of the content is ignored.
+  const r = await runTargetCommand(t, (opts) => commandArgv(t, ['tee', '--', path], opts), {
+    timeoutMs: REMOTE_TIMEOUT_MS,
+    input: content,
+  });
+  if (r.code !== 0) {
+    if (/No such file|not found/i.test(r.stderr)) throw new TmuxError(404, 'directory not found');
+    if (/Is a directory/i.test(r.stderr)) throw new TmuxError(400, 'path is a directory');
+    if (/Permission denied/i.test(r.stderr)) throw new TmuxError(403, 'permission denied');
+    throw new TmuxError(502, r.stderr.trim().split('\n')[0] || 'cannot write file');
+  }
+}
+
+function fsError(e: unknown, path: string): TmuxError {
+  const code = (e as NodeJS.ErrnoException)?.code;
+  if (code === 'ENOENT') return new TmuxError(404, `not found: ${path}`);
+  if (code === 'EACCES') return new TmuxError(403, `permission denied: ${path}`);
+  if (code === 'ENOTDIR') return new TmuxError(400, `not a directory: ${path}`);
+  if (code === 'EISDIR') return new TmuxError(400, `path is a directory: ${path}`);
+  return new TmuxError(502, e instanceof Error ? e.message : 'filesystem error');
+}

package/server/src/foldersStore.ts

@@ -0,0 +1,114 @@
+import { promises as fsp } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { config } from './config.js';
+import { sshClientArgs, sshQuote } from './tmux/builder.js';
+import type { Target } from './targets.js';
+import { TmuxError } from './tmux/sessions.js';
+import { runTargetCommand } from './targetCommand.js';
+
+/**
+ * Sidebar folder organization, stored ON THE TARGET so it follows the cluster:
+ * every client connecting to the same target reads/writes the same file, so the
+ * folder tree syncs across browsers and machines (like the tmux sessions do).
+ *
+ * Path: $HOME/.config/tmuxes/folders.json on the target.
+ * - local / winlocal → the server's own filesystem (fs).
+ * - ssh             → the remote $HOME (ssh runs commands from $HOME).
+ * - wsl             → the distro's $HOME (`wsl --cd ~`).
+ */
+
+const REL = '.config/tmuxes/folders.json';
+const REMOTE_TIMEOUT_MS = 15_000;
+const MAX_BYTES = 500_000;
+
+export interface FolderPayload {
+  folders: unknown[];
+  assign: Record<string, unknown>;
+}
+
+const EMPTY: FolderPayload = { folders: [], assign: {} };
+
+function localPath(): string {
+  return join(homedir(), '.config', 'tmuxes', 'folders.json');
+}
+
+function remoteArgv(
+  t: Target,
+  script: string,
+  opts: { multiplex?: boolean } = {},
+): { file: string; args: string[] } {
+  if (t.kind === 'wsl') {
+    // --cd ~ → run from the distro home; sh -c handles the redirections.
+    return { file: 'wsl.exe', args: ['-d', t.distro ?? '', '--cd', '~', '--exec', 'sh', '-c', script] };
+  }
+  // ssh: wrap in `sh -c '<script>'` so it works regardless of the remote login
+  // shell, and runs from the default cwd ($HOME).
+  return {
+    file: 'ssh',
+    args: [
+      ...sshClientArgs(t, {
+        batchMode: true,
+        connectTimeout: config.ssh.connectTimeoutMgmt,
+        multiplex: opts.multiplex,
+      }).slice(1),
+      'sh',
+      '-c',
+      sshQuote(script),
+    ],
+  };
+}
+
+function runRemote(t: Target, script: string, input?: string) {
+  return runTargetCommand(t, (opts) => remoteArgv(t, script, opts), {
+    timeoutMs: REMOTE_TIMEOUT_MS,
+    input,
+  });
+}
+
+async function readRaw(t: Target): Promise<string> {
+  if (t.kind === 'local' || t.kind === 'winlocal') {
+    try {
+      return await fsp.readFile(localPath(), 'utf8');
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code === 'ENOENT') return '';
+      throw new TmuxError(502, 'cannot read folders');
+    }
+  }
+  // `2>/dev/null` so a missing file produces empty stdout + no stderr; a real
+  // transport failure (ssh down) prints to stderr → surfaced as 502.
+  const r = await runRemote(t, `cat ${REL} 2>/dev/null`);
+  if (r.code === 0) return r.stdout;
+  if (r.stderr.trim()) throw new TmuxError(502, r.stderr.trim().split('\n')[0]);
+  return ''; // missing file
+}
+
+async function writeRaw(t: Target, raw: string): Promise<void> {
+  if (t.kind === 'local' || t.kind === 'winlocal') {
+    await fsp.mkdir(dirname(localPath()), { recursive: true });
+    await fsp.writeFile(localPath(), raw, 'utf8');
+    return;
+  }
+  const r = await runRemote(t, `mkdir -p .config/tmuxes && cat > ${REL}`, raw);
+  if (r.code !== 0) throw new TmuxError(502, r.stderr.trim().split('\n')[0] || 'cannot write folders');
+}
+
+export async function readFolders(t: Target): Promise<FolderPayload> {
+  const raw = await readRaw(t);
+  if (!raw.trim()) return EMPTY;
+  try {
+    const o = JSON.parse(raw) as Partial<FolderPayload>;
+    if (o && Array.isArray(o.folders) && o.assign && typeof o.assign === 'object') {
+      return { folders: o.folders, assign: o.assign as Record<string, unknown> };
+    }
+  } catch {
+    /* corrupt file → treat as empty */
+  }
+  return EMPTY;
+}
+
+export async function writeFolders(t: Target, payload: FolderPayload): Promise<void> {
+  const raw = JSON.stringify({ folders: payload.folders, assign: payload.assign });
+  if (Buffer.byteLength(raw, 'utf8') > MAX_BYTES) throw new TmuxError(413, 'folders payload too large');
+  await writeRaw(t, raw);
+}