@fnclaude/cli 1.1.1 → 2.0.0

package/src/help-version.ts

@@ -0,0 +1,151 @@
+/**
+ * --help / --version short-circuits. Pure detection functions plus the
+ * help text and lazy version reader.
+ *
+ * Both detectors scan argv left-to-right and stop at the first literal
+ * `--` — anything after the sentinel is prompt body, not fnclaude flags
+ * (matches Go canonical's wantsHelp/wantsVersion at src/main.go:463-481,
+ * 569-585).
+ *
+ * `-v` is a fnclaude-claimed short flag — the user reaches claude's own
+ * --version via `claude --version` directly. This is the ONLY lowercase
+ * short flag fnclaude reserves; everything else is uppercase-only.
+ */
+
+const SENTINEL = '--';
+
+export function wantsHelp(args: readonly string[]): boolean {
+  for (const tok of args) {
+    if (tok === SENTINEL) return false;
+    if (tok === '-h' || tok === '--help') return true;
+  }
+  return false;
+}
+
+export function wantsVersion(args: readonly string[]): boolean {
+  for (const tok of args) {
+    if (tok === SENTINEL) return false;
+    if (tok === '-v' || tok === '--version') return true;
+  }
+  return false;
+}
+
+export const helpText = `fnclaude — claude CLI launcher with quality-of-life features
+
+Usage:
+  fnc [MODEL] [EFFORT] [SUBCOMMAND] [CWD [WORKTREE]] [FLAGS...] [-- PROMPT]
+
+Magic positional words (order-independent for SUBCOMMAND; MODEL/EFFORT scanned
+left-to-right at the head of argv before any flags):
+  Model alias:   opus | sonnet | haiku                       → --model <alias>
+  Effort level:  low | medium | high | xhigh | max | auto    → --effort <level>
+                  (effort alone at position 1 implies opus)
+  Subcommand:    resume | res                                → --resume
+                 continue | con                              → --continue
+                 fork | fk                                   → --resume --fork-session
+  To use a directory literally named one of these, prefix with ./
+
+Positional paths (max 2 after magic/subcommand tokens):
+  1st remaining → cwd to launch claude in
+                  Accepts: absolute path, ~-prefixed, ./-prefixed, bare repo
+                  name (gh-resolved), name@owner, owner/name, gh:owner/name,
+                  HTTPS URL, SSH URL. Missing repos are cloned per the
+                  cloneTemplate in repoSettings.
+                  (fallback when no path: $XDG_CONFIG_HOME/fnclaude/noop)
+  2nd remaining → worktree name (same semantics as -w <name>)
+  3rd+ remaining → error. Use -A/--also for extra dirs.
+
+Reserved subcommands:
+  mcp [--noop]  — internal MCP server (invoked automatically by claude via
+                  injected --mcp-config; not for direct use)
+  To use a directory literally named mcp, prefix with ./
+
+fnclaude-owned flags (consumed by the launcher, NOT forwarded to claude):
+  -A, --also <dir>      additional extra-dir (repeatable; deferred — see PRD)
+      --no-tmux         suppress auto-tmux injection for this invocation
+  -w, --worktree <name> worktree intercept (matches existing → swap cwd;
+                        no match → forwarded as new-worktree request)
+  -h, --help            show this help and exit
+  -v, --version         print fnclaude's version and exit
+                        (shadows claude's -v; use \`claude --version\` directly)
+
+Capital-letter shortcuts (translate to claude long-form flags):
+  -B → --brief                          -M → --permission-mode <mode>
+  -C → --chrome                         -P → --from-pr [value]
+  -D → --dangerously-skip-permissions   -R → --remote-control [name]
+  -F → --fork-session                   -T → --tmux [classic]
+  -G → --agent <agent>                  -V → --verbose
+  -I → --ide                            -W → --allowedTools <tools>
+
+All other claude flags pass through verbatim — run \`claude --help\` for the
+full reference. POSIX collapsing is supported (-BVC = -B -V -C); only the
+last flag in a collapsed group may take a value. shortRequired flags
+(-G/-M/-W) must be the final character of a cluster, not in the middle.
+
+Cross-cwd resume: when claude shows the resume picker and you select a
+session from a different cwd, fnclaude transparently re-launches in that
+cwd. All flags from the original invocation are preserved.
+
+Worktree intercept: -w <name> (or a 2nd positional) matching an existing
+worktree of the project repo swaps fnclaude's cwd to that worktree.
+Non-matching names pass through as a new-worktree request. --name is
+always set, whether entering or creating.
+
+Auto-name: when --, a prompt, and no --name/-n are all present, fnclaude
+generates a 1-3 word session label via Haiku. With ANTHROPIC_API_KEY set,
+the call goes through the Anthropic SDK directly (fast-path, no claude
+spawn). Without it, fnclaude shells out to \`claude -p\` which uses your
+subscription auth. Falls back silently to a heuristic on failure / timeout.
+
+Auto-tmux: with \`[auto] tmux = "worktree"\` in config, fnclaude injects
+--tmux whenever you create a new worktree (-w <name> with no match).
+Pass --no-tmux to skip this for a single invocation without editing config.
+
+Environment variables (override config; precedence: CLI > env > config):
+  ANTHROPIC_API_KEY     direct-API auth for auto-name (else shells \`claude -p\`)
+  XDG_CONFIG_HOME       config dir base (default: ~/.config)
+  FNC_PROMPTS_DIR       override install-dir prompts location
+                        (default: <exe-dir>/prompts, <exe-dir>/../prompts,
+                         or <exe-dir>/../share/fnclaude/prompts)
+  FNC_NOOP_TEMPLATE_PATH
+                        override handoff.template.md source path used when
+                        seeding the noop fallback directory on first launch
+
+Config file: $XDG_CONFIG_HOME/fnclaude/config.toml
+  [name]      model = "claude-haiku-4-5", timeout = "3s"
+  [auto]      tmux = "never" | "worktree"
+              handoff = "never" | "ask" | <N seconds>
+              spawn_command = "..."   # for opening new terminal windows
+  [exec.env]  NAME = "value"          # injected into every claude child env
+
+Repo settings (~/.claude/settings.json):
+  cloneTemplate / worktreeTemplate / branchTemplate — shared with the
+  claude-code-worktree-paths plugin. Layered with project + local + managed
+  tiers in standard claude-settings precedence.
+
+Examples:
+  fnc                                  # noop session in ~/.config/fnclaude/noop
+  fnc opus max ~/src/proj              # opus + max effort in ~/src/proj
+  fnc ~/src/proj feature               # cwd + worktree name (same as -w feature)
+  fnc sonnet ~/src/proj -- "fix the bug"
+                                       # auto-name from prompt, sonnet model
+  fnc resume ~/src/proj                # session picker for ~/src/proj
+  fnc fnclaude@fnrhombus               # owner-qualified repo ref (auto-cloned)
+  fnc -BVC                             # --brief --verbose --chrome
+
+For more, see https://github.com/fnrhombus/fnclaude
+`;
+
+let cachedVersion: string | null = null;
+
+export async function getVersion(): Promise<string> {
+  if (cachedVersion !== null) return cachedVersion;
+  try {
+    const pkgUrl = new URL('../package.json', import.meta.url);
+    const pkg = (await Bun.file(pkgUrl).json()) as { version?: unknown };
+    cachedVersion = typeof pkg.version === 'string' ? pkg.version : '0.0.0-dev';
+  } catch {
+    cachedVersion = '0.0.0-dev';
+  }
+  return cachedVersion;
+}

package/src/launch/compose-env.ts

@@ -0,0 +1,34 @@
+/**
+ * Build the env passed to claude's child process.
+ *
+ * Order (each step wins over earlier ones):
+ *   1. processEnv — the launcher's inherited env, filtered to defined values.
+ *   2. execEnv    — `[exec.env]` from fnclaude's config.toml.
+ *   3. handoff    — sets FNCLAUDE_HANDOFF if defined; per design.md §5
+ *                   this is the resolved auto.handoff value.
+ *   4. socket     — sets FNC_SOCKET if defined; the AF_UNIX path the
+ *                   MCP subprocess dials for tool calls.
+ *
+ * Per design.md §5: "These are appended AFTER os.Environ() + envFromConfig,
+ * so they win against any same-name entries from user config."
+ */
+
+export interface ComposeEnvArgs {
+  processEnv: Record<string, string | undefined>;
+  execEnv: Record<string, string> | undefined;
+  handoff: string | undefined;
+  socket: string | undefined;
+}
+
+export function composeEnv(args: ComposeEnvArgs): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(args.processEnv)) {
+    if (v !== undefined) out[k] = v;
+  }
+  if (args.execEnv !== undefined) {
+    for (const [k, v] of Object.entries(args.execEnv)) out[k] = v;
+  }
+  if (args.handoff !== undefined) out.FNCLAUDE_HANDOFF = args.handoff;
+  if (args.socket !== undefined) out.FNC_SOCKET = args.socket;
+  return out;
+}

package/src/launch/cross-cwd-parse.ts

@@ -0,0 +1,69 @@
+/**
+ * Parse claude's "To resume, run: cd <dir> && claude --resume <uuid>" hint
+ * out of captured PTY output (typically the tail of fnclaude's 64 KB ring
+ * buffer after claude exits).
+ *
+ * Per design.md §4 (Go canonical src/pty_run.go:17–99):
+ *   - Regex: `/To resume, run:[\s\S]*?cd (\S+) && claude --resume ([0-9a-fA-F-]{36})/g`
+ *   - When multiple matches appear in the tail, LAST match wins. claude's
+ *     own most-recent print is the authoritative hint; earlier matches are
+ *     stale history.
+ *   - Destination cwd must pass `isSafeDest` — absolute path, no shell
+ *     metacharacters, no `..` segment. We reject hostile hints rather than
+ *     silently falling back to an earlier valid one: an attacker who can
+ *     inject bytes into claude's TTY shouldn't get to redirect the relaunch
+ *     just because they followed a benign hint with a hostile one.
+ *   - UUID is defensively re-validated against the canonical 8-4-4-4-12
+ *     shape. The regex character class allows any combination of hex+dash
+ *     in a 36-char run, so e.g. a 36-char hex-only string matches the
+ *     regex but isn't a real UUID — the shape check filters those out.
+ */
+
+export interface CrossCwdHint {
+  cwd: string;
+  uuid: string;
+}
+
+const HINT_RE = /To resume, run:[\s\S]*?cd (\S+) && claude --resume ([0-9a-fA-F-]{36})/g;
+
+const UUID_SHAPE_RE =
+  /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+
+// Shell metacharacters and quote characters that have no business in a
+// path we're about to hand to `cd` (even though we don't actually invoke
+// a shell — defense in depth in case a future call site does).
+const UNSAFE_CHARS = new Set([
+  ';', '|', '&', '$', '`', '<', '>', '(', ')',
+  '{', '}', '[', ']', '#', '!', '\\', "'", '"',
+]);
+
+export function isSafeDest(dest: string): boolean {
+  if (dest === '') return false;
+  // POSIX absolute path. Windows handling is a follow-up.
+  if (!dest.startsWith('/')) return false;
+  for (const ch of dest) {
+    if (UNSAFE_CHARS.has(ch)) return false;
+  }
+  // No `..` path segment.
+  for (const seg of dest.split('/')) {
+    if (seg === '..') return false;
+  }
+  return true;
+}
+
+export function parseCrossCwdHint(text: string): CrossCwdHint | null {
+  // Reset the global regex's lastIndex defensively — matchAll handles this
+  // correctly for us, but we treat HINT_RE as a module-level constant and
+  // never want stateful surprises.
+  let last: { cwd: string; uuid: string } | null = null;
+  for (const m of text.matchAll(HINT_RE)) {
+    const cwd = m[1];
+    const uuid = m[2];
+    if (cwd === undefined || uuid === undefined) continue;
+    last = { cwd, uuid };
+  }
+  if (last === null) return null;
+  if (!isSafeDest(last.cwd)) return null;
+  if (!UUID_SHAPE_RE.test(last.uuid)) return null;
+  return last;
+}

package/src/launch/cross-cwd-relaunch.ts

@@ -0,0 +1,95 @@
+/**
+ * §9.3 — Cross-cwd silent relaunch decision.
+ *
+ * After claude exits the parent fnclaude scans the captured PTY tail
+ * for the "To resume, run: cd <dir> && claude --resume <uuid>" hint
+ * claude prints when the user picks a session from a different
+ * directory via Ctrl-A. When the hint is present (and no other handoff
+ * is already in flight), fnclaude silently re-execs itself with a
+ * reconstructed argv pointing at the new cwd + session uuid.
+ *
+ * This module is the *pure* part of that flow: takes the post-exit
+ * inputs, returns a relaunch decision (yes/no + argv). The side-
+ * effecting re-exec lives in `handoff/awaiter.ts` (shared with §8.5's
+ * MCP handoff path) and the call-site lives in `main.ts`.
+ *
+ * Port of Go canonical `detectCrossCwd` + `reconstructArgv` + the
+ * post-exit check in `main.go::run()`. See Go pty_run.go:84+ and
+ * main.go:1006+.
+ */
+
+import {
+  applyOverrides,
+  preserveArgs,
+  splitLeadingMagic,
+} from '../argv/preserve-args.ts';
+import { parseCrossCwdHint } from './cross-cwd-parse.ts';
+
+export interface CrossCwdRelaunchInput {
+  /** claude's exit code. Non-zero short-circuits — no relaunch. */
+  exitCode: number;
+  /**
+   * Whether the handoff trigger has already accepted a stash. True
+   * means an MCP-handoff is in motion; cross-cwd would race it and we
+   * defer to the handoff path. Mirrors Go canonical's `len(handoffArgv) > 0`
+   * gate in main.go::run().
+   */
+  alreadyStashed: boolean;
+  /**
+   * Tail of PTY output captured during the session (§9.1's ring
+   * buffer). Decoded to text via TextDecoder; the hint matcher tolerates
+   * surrounding ANSI escapes.
+   */
+  ringSnapshot: Uint8Array;
+  /**
+   * `process.argv.slice(2)` from the original fnclaude invocation —
+   * the user-supplied argv before any internal massaging. This is what
+   * survives across the relaunch (modulo positional path → dest swap
+   * + injected `--resume`).
+   */
+  origArgs: readonly string[];
+}
+
+export type CrossCwdRelaunchDecision =
+  | { relaunch: false }
+  | { relaunch: true; argv: string[] };
+
+/**
+ * Decide whether to silently relaunch fnclaude in a different cwd.
+ *
+ * Returns `{relaunch: false}` when any gate fails (non-zero exit,
+ * handoff already stashed, no hint, unsafe hint). Returns
+ * `{relaunch: true, argv}` when all gates pass — argv is the
+ * reconstructed user-side argv ready to feed to the re-exec primitive.
+ *
+ * Reconstruction mirrors Go canonical's `reconstructArgv`:
+ *   1. `preserveArgs(origArgs, {}, {})` — keep magic + flags, drop
+ *      positionals (the dest replaces them).
+ *   2. `applyOverrides(preserved, {})` — no-op since we don't override
+ *      anything cross-cwd; included for parity with the
+ *      transfer/restart shape so future overrides have a place to land.
+ *   3. `splitLeadingMagic` to peel the magic prefix off the front.
+ *   4. `[...magic, dest, '--resume', uuid, ...rest]`.
+ */
+export function decideCrossCwdRelaunch(
+  input: CrossCwdRelaunchInput,
+): CrossCwdRelaunchDecision {
+  if (input.exitCode !== 0) return { relaunch: false };
+  if (input.alreadyStashed) return { relaunch: false };
+  if (input.ringSnapshot.length === 0) return { relaunch: false };
+
+  const text = new TextDecoder().decode(input.ringSnapshot);
+  const hint = parseCrossCwdHint(text);
+  if (hint === null) return { relaunch: false };
+
+  const preserved = preserveArgs(input.origArgs, EMPTY_DENY, EMPTY_BARE_OK);
+  const withOverrides = applyOverrides(preserved, {});
+  const { magic, rest } = splitLeadingMagic(withOverrides);
+
+  const argv: string[] = [...magic, hint.cwd, '--resume', hint.uuid, ...rest];
+  return { relaunch: true, argv };
+}
+
+// Pre-allocated empty sets so we don't allocate per call.
+const EMPTY_DENY: ReadonlySet<string> = new Set();
+const EMPTY_BARE_OK: ReadonlySet<string> = new Set();

package/src/launch/find-claude.ts

@@ -0,0 +1,52 @@
+/**
+ * Locate `claude` on PATH so we can fail fast with a clean error when it
+ * isn't installed — rather than blowing up at Bun.spawn time with a less
+ * helpful ENOENT.
+ *
+ * We walk PATH directly (rather than calling `Bun.which`) so callers can
+ * pass an explicit PATH for testing. This matches the standard PATH
+ * resolution: left-to-right, first executable file with the right name
+ * wins, non-existent directories are skipped silently.
+ *
+ * Windows handling (PATHEXT, .exe etc.) is a follow-up; the rewrite's
+ * primary Unix path lands here first.
+ */
+
+import { accessSync, constants, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface FindClaudeArgs {
+  pathEnv: string;
+}
+
+export type FindClaudeResult =
+  | { ok: true; path: string }
+  | { ok: false; error: string };
+
+export function findClaude(args: FindClaudeArgs): FindClaudeResult {
+  if (args.pathEnv === '') {
+    return errorResult();
+  }
+  const dirs = args.pathEnv.split(':');
+  for (const dir of dirs) {
+    if (dir === '') continue;
+    const candidate = join(dir, 'claude');
+    try {
+      const st = statSync(candidate);
+      if (!st.isFile()) continue;
+      accessSync(candidate, constants.X_OK);
+      return { ok: true, path: candidate };
+    } catch {
+      // Missing, not executable, or unreadable — keep walking.
+    }
+  }
+  return errorResult();
+}
+
+function errorResult(): FindClaudeResult {
+  return {
+    ok: false,
+    error:
+      'fnclaude: `claude` not found on PATH. Install Claude Code (https://docs.claude.com/en/docs/agents/claude-code) and ensure the `claude` binary is on your PATH.',
+  };
+}

package/src/launch/live-permission-reader.ts

@@ -0,0 +1,133 @@
+/**
+ * TS port of Go canonical's `session_state.go` — reads the most recent
+ * permission-mode claude wrote into its per-session JSONL log.
+ *
+ * Claude Code appends records of the form
+ *
+ *   {"type":"permission-mode","permissionMode":"acceptEdits|auto|bypassPermissions|default|dontAsk|plan"}
+ *
+ * to `~/.claude/projects/<encoded-cwd>/<session-id>.jsonl` whenever the
+ * user toggles permission mode in-session. fnclaude reads the latest
+ * value back during §8.1 (restart) and §8.2 (switch) so the relaunched
+ * session inherits whatever the user landed on, not whatever flag the
+ * session was originally launched with.
+ *
+ * Three exports mirror the Go shape:
+ *
+ *   - `encodeCWDForProjects(cwd)` — pure transform: every char NOT in
+ *     `[A-Za-z0-9-]` collapses to `-`. Verified empirically against real
+ *     on-disk session directories (claude replaces `/`, `@`, `+`, `_`,
+ *     `.`, … — the safe rule is the allowlist).
+ *   - `sessionJSONLPath(launchCWD, sessionID)` — joins HOME +
+ *     `.claude/projects` + encoded-cwd + `<sid>.jsonl`.
+ *   - `readLivePermissionMode(launchCWD, sessionID)` — opens, last-wins
+ *     scan, returns `null` on miss/error/unreadable.
+ *
+ * Sync IO via `readFileSync` is fine here: session JSONLs are
+ * bounded-size and the call only fires on MCP-dispatched restart/switch,
+ * never on a hot path. Streaming would add complexity without benefit.
+ *
+ * Only `type === "permission-mode"` records are authoritative — other
+ * record types (user / assistant / system messages) may serialize a
+ * cached `permissionMode` snapshot which is NOT the source of truth per
+ * the Go canonical's comment.
+ */
+
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Encode `cwd` into the directory name claude uses under
+ * `~/.claude/projects/`. The scheme: every character that is NOT in
+ * `[A-Za-z0-9-]` becomes `-`. A canonical absolute path like
+ * `/home/tom/src/fnclaude@fnclaude` encodes to
+ * `-home-tom-src-fnclaude-fnclaude`.
+ */
+export function encodeCWDForProjects(cwd: string): string {
+  let out = '';
+  for (const ch of cwd) {
+    if (
+      (ch >= 'a' && ch <= 'z') ||
+      (ch >= 'A' && ch <= 'Z') ||
+      (ch >= '0' && ch <= '9') ||
+      ch === '-'
+    ) {
+      out += ch;
+    } else {
+      out += '-';
+    }
+  }
+  return out;
+}
+
+/**
+ * Returns the absolute path to claude's per-session JSONL log for
+ * `sessionID` running in `launchCWD`. Caller is responsible for
+ * checking existence — `readLivePermissionMode` handles ENOENT itself.
+ */
+export function sessionJSONLPath(launchCWD: string, sessionID: string): string {
+  return join(resolveHome(), '.claude', 'projects', encodeCWDForProjects(launchCWD), `${sessionID}.jsonl`);
+}
+
+/**
+ * Reads the most recent `permission-mode` value recorded in claude's
+ * session JSONL for `sessionID` under `launchCWD`. Returns `null` if:
+ *
+ *   - the file doesn't exist (ENOENT) or is unreadable,
+ *   - the file exists but contains no `{type:"permission-mode",...}`
+ *     records, or
+ *   - every such record has an empty `permissionMode` field.
+ *
+ * Last-wins semantics: claude's JSONL is append-only, so a forward
+ * linear scan returns the most-recently-written value. Malformed lines
+ * are skipped silently (defensive against partial writes / future
+ * record-shape changes).
+ */
+export function readLivePermissionMode(launchCWD: string, sessionID: string): string | null {
+  const path = sessionJSONLPath(launchCWD, sessionID);
+  let raw: string;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch {
+    // ENOENT / EACCES / EISDIR / anything else → no live override.
+    return null;
+  }
+
+  let latest: string | null = null;
+  for (const line of raw.split('\n')) {
+    if (line === '') continue;
+    let rec: unknown;
+    try {
+      rec = JSON.parse(line);
+    } catch {
+      continue; // malformed line — ignore
+    }
+    if (typeof rec !== 'object' || rec === null) continue;
+    const obj = rec as Record<string, unknown>;
+    if (obj.type !== 'permission-mode') continue;
+    const mode = obj.permissionMode;
+    if (typeof mode !== 'string' || mode === '') continue;
+    latest = mode;
+  }
+  return latest;
+}
+
+/**
+ * HOME resolution. Reads `process.env.HOME` first — it's the canonical
+ * source on POSIX, respects per-test env overrides, and is what `claude`
+ * itself uses to find `~/.claude/`. Falls back to `homedir()` for the
+ * rare case the env var is unset (cron, bare systemd unit), and to `''`
+ * if even that throws (defensive — mirrors Go's `os.UserHomeDir()` →
+ * `os.Getenv("HOME")` fallback chain, just with the order reversed
+ * because `homedir()` caches in Bun and `process.env.HOME` doesn't).
+ */
+function resolveHome(): string {
+  const fromEnv = process.env.HOME;
+  if (fromEnv !== undefined && fromEnv !== '') return fromEnv;
+  try {
+    return homedir();
+  } catch {
+    return '';
+  }
+}

package/src/launch/ring-buffer.ts

@@ -0,0 +1,92 @@
+/**
+ * Fixed-capacity circular byte buffer for capturing the tail of the PTY
+ * output stream. Used by §9.2 to scan claude's last screenful for the
+ * cross-cwd resume hint after exit.
+ *
+ * Default capacity is 64 KB per design.md §4. Earlier Go versions used
+ * 4 KB; the Go source bumped it after claude 2.1.143 emitted more
+ * trailing cleanup and rotated the "To resume, run:" message out of the
+ * 4 KB tail.
+ *
+ * Contract:
+ *   - push(chunk): append bytes; when the buffer is full, wrap and
+ *     overwrite the oldest bytes. A chunk larger than the capacity keeps
+ *     only its trailing `capacity` bytes (the older prefix is dropped).
+ *     Zero-length chunks are no-ops.
+ *   - snapshot(): a fresh Uint8Array containing the current valid bytes
+ *     in chronological order (oldest first). Mutating the snapshot does
+ *     not affect the buffer; subsequent pushes do not mutate prior
+ *     snapshots.
+ *   - size: number of valid bytes currently held, 0 ≤ size ≤ capacity.
+ */
+
+const DEFAULT_CAPACITY = 64 * 1024;
+
+export class RingBuffer {
+  readonly capacity: number;
+  private readonly buf: Uint8Array;
+  /** Index of the oldest valid byte. Only meaningful when full. */
+  private start = 0;
+  /** Number of valid bytes currently held. */
+  private len = 0;
+
+  constructor(capacity: number = DEFAULT_CAPACITY) {
+    this.capacity = capacity;
+    this.buf = new Uint8Array(capacity);
+  }
+
+  get size(): number {
+    return this.len;
+  }
+
+  push(chunk: Uint8Array): void {
+    if (chunk.length === 0 || this.capacity === 0) return;
+
+    // Chunk larger than capacity: drop its prefix, keep only the trailing
+    // `capacity` bytes. Replaces the buffer wholesale — start resets.
+    if (chunk.length >= this.capacity) {
+      this.buf.set(chunk.subarray(chunk.length - this.capacity));
+      this.start = 0;
+      this.len = this.capacity;
+      return;
+    }
+
+    // Compute the write position (one past the last valid byte, modulo
+    // capacity). When the buffer is full, that's the same slot as `start`
+    // — the oldest byte gets overwritten and `start` advances.
+    const writePos = (this.start + this.len) % this.capacity;
+    const tail = this.capacity - writePos;
+    if (chunk.length <= tail) {
+      this.buf.set(chunk, writePos);
+    } else {
+      // Two-segment copy: fill to end of array, then wrap to index 0.
+      this.buf.set(chunk.subarray(0, tail), writePos);
+      this.buf.set(chunk.subarray(tail), 0);
+    }
+
+    if (this.len + chunk.length <= this.capacity) {
+      this.len += chunk.length;
+    } else {
+      // Overflow: bytes past capacity overwrite the oldest bytes; start
+      // advances by the overflow amount.
+      const overflow = this.len + chunk.length - this.capacity;
+      this.start = (this.start + overflow) % this.capacity;
+      this.len = this.capacity;
+    }
+  }
+
+  snapshot(): Uint8Array {
+    if (this.len === 0) return new Uint8Array(0);
+    const out = new Uint8Array(this.len);
+    // Either contiguous (start..start+len fits before capacity) or split
+    // (head wraps past the end of the underlying array).
+    const tail = this.capacity - this.start;
+    if (this.len <= tail) {
+      out.set(this.buf.subarray(this.start, this.start + this.len));
+    } else {
+      out.set(this.buf.subarray(this.start, this.capacity), 0);
+      out.set(this.buf.subarray(0, this.len - tail), tail);
+    }
+    return out;
+  }
+}