@openparachute/agent 0.2.3-rc.2 → 0.2.3-rc.3

package/src/spawn-deps.test.ts

@@ -1,54 +0,0 @@
-/**
- * Tests for `resolveSpawnDeps` (`src/spawn-deps.ts`) — the real-dep resolver
- * shared by the CLI and the web spawn endpoint.
- *
- * The load-bearing regression guard here is the claude config binding: the
- * sandboxed `claude` MUST get `~/.claude.json` bound read-only, or it runs
- * first-run onboarding whose connectivity check is FATAL under the restricted
- * egress proxy and the tmux session dies instantly ("An unknown error occurred").
- * That bug shipped once; this test ensures the binding stays.
- */
-
-import { describe, test, expect, afterEach } from "bun:test";
-import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
-import { tmpdir, homedir } from "node:os";
-import { join, resolve } from "node:path";
-import { resolveSpawnDeps, SpawnDepsError } from "./spawn-deps.ts";
-
-const savedHome = process.env.PARACHUTE_HOME;
-let tmp: string | undefined;
-
-afterEach(() => {
-  if (savedHome === undefined) delete process.env.PARACHUTE_HOME;
-  else process.env.PARACHUTE_HOME = savedHome;
-  if (tmp) {
-    try { rmSync(tmp, { recursive: true, force: true }); } catch {}
-    tmp = undefined;
-  }
-});
-
-describe("resolveSpawnDeps", () => {
-  test("throws SpawnDepsError when there's no operator token", () => {
-    tmp = mkdtempSync(join(tmpdir(), "spawn-deps-empty-"));
-    process.env.PARACHUTE_HOME = tmp; // no operator.token inside
-    expect(() => resolveSpawnDeps()).toThrow(SpawnDepsError);
-  });
-
-  test("binds the claude binary (confined reads) but NOT the operator's ~/.claude", () => {
-    tmp = mkdtempSync(join(tmpdir(), "spawn-deps-"));
-    process.env.PARACHUTE_HOME = tmp;
-    writeFileSync(join(tmp, "operator.token"), "fake-operator-bearer");
-    const deps = resolveSpawnDeps();
-    // The agent's config/onboarding now lives in its own per-session HOME
-    // (seedAgentHome), so we no longer expose the operator's real config.
-    expect(deps.runtimeReadOnly).not.toContain(resolve(homedir(), ".claude.json"));
-    expect(deps.runtimeReadOnly).not.toContain(resolve(homedir(), ".claude"));
-    // The claude BINARY is still bound (needed under confined/scoped reads) when
-    // resolvable on PATH — and claudeBin is set to its absolute path.
-    const bin = Bun.which("claude");
-    if (bin) {
-      expect(deps.claudeBin).toBe(bin);
-      expect(deps.runtimeReadOnly).toContain(bin);
-    }
-  });
-});

package/src/terminal-assets.test.ts

@@ -1,50 +0,0 @@
-/**
- * Tests for same-origin terminal asset serving (`src/terminal-assets.ts`) — the
- * fix for "xterm.js failed to load (CDN blocked?)". Proves the vendored xterm JS +
- * CSS resolve from the installed packages and serve with the right content-type,
- * and that an unknown asset name is a clean miss (the daemon 404s it).
- */
-
-import { describe, test, expect } from "bun:test";
-import { serveTerminalAsset, TERMINAL_ASSET_NAMES } from "./terminal-assets.ts";
-
-describe("serveTerminalAsset", () => {
-  test("serves xterm.js as JavaScript with a real body", async () => {
-    const res = serveTerminalAsset("xterm.js");
-    expect(res).not.toBeNull();
-    expect(res!.status).toBe(200);
-    expect(res!.headers.get("content-type")).toContain("javascript");
-    const body = await res!.text();
-    // The UMD bundle defines the Terminal global — a non-trivial body proves the
-    // file resolved from the package (not an empty/placeholder response).
-    expect(body.length).toBeGreaterThan(1000);
-    expect(body).toContain("Terminal");
-  });
-
-  test("serves xterm.css as CSS", async () => {
-    const res = serveTerminalAsset("xterm.css");
-    expect(res!.status).toBe(200);
-    expect(res!.headers.get("content-type")).toContain("css");
-    expect((await res!.text()).length).toBeGreaterThan(100);
-  });
-
-  test("serves addon-fit.js", async () => {
-    const res = serveTerminalAsset("addon-fit.js");
-    expect(res!.status).toBe(200);
-    expect(res!.headers.get("content-type")).toContain("javascript");
-  });
-
-  test("sets an immutable cache header (version-pinned)", () => {
-    const res = serveTerminalAsset("xterm.js");
-    expect(res!.headers.get("cache-control")).toContain("immutable");
-  });
-
-  test("an unknown asset name → null (caller 404s)", () => {
-    expect(serveTerminalAsset("evil.js")).toBeNull();
-    expect(serveTerminalAsset("../../etc/passwd")).toBeNull();
-  });
-
-  test("the known names are the three xterm assets", () => {
-    expect(TERMINAL_ASSET_NAMES.sort()).toEqual(["addon-fit.js", "xterm.css", "xterm.js"]);
-  });
-});

package/src/terminal.test.ts

@@ -1,530 +0,0 @@
-/**
- * In-page terminal tests — the WS↔pty relay (`createTerminalWsHandlers`,
- * `parseControlFrame`, src/terminal.ts) + the daemon-side terminal upgrade gate
- * (`authorizeTerminalUpgrade`, src/daemon.ts).
- *
- * The relay tests drive the handler set against a FAKE `ServerWebSocket` and the
- * injectable `spawnTerminal` seam — no real tmux, no real pty, no `Bun.serve`.
- * The fake socket exposes a settable `getBufferedAmount()` so we can simulate
- * the hub's send-buffer filling under a flood and assert the flow-control
- * contract (the load-bearing item): a flood PARKS in the daemon-side coalesce
- * queue, the socket is NOT closed, and output resumes (drains) once the client
- * catches up. The hub's blunt 8 MiB cap therefore never has to fire.
- *
- * The auth tests call the pure `authorizeTerminalUpgrade` directly, using the
- * same sentinel-token `mock.module("./hub-jwt.ts")` harness daemon-config-api.
- * test.ts uses — accept paths run without a live hub/JWKS; the no-token reject
- * still hits the real short-circuit.
- */
-import { describe, test, expect, mock } from "bun:test";
-import type { ServerWebSocket } from "bun";
-
-// Sentinel tokens → fixed scope sets. Mirrors daemon-config-api.test.ts so this
-// process-wide mock stays compatible. ADMIN_TOKEN carries agent:admin (==
-// SCOPE_TERMINAL); READ_TOKEN is under-scoped; LEGACY_ADMIN_TOKEN carries the
-// pre-rename channel:admin scope (dual-accept back-compat); anything else throws.
-const ADMIN_TOKEN = "test-admin-token"; // agent:admin (== SCOPE_TERMINAL)
-const READ_TOKEN = "test-read-token"; // agent:read only (insufficient)
-const LEGACY_ADMIN_TOKEN = "test-legacy-admin-token"; // legacy channel:admin (still accepted)
-import { HubJwtError, looksLikeJwt } from "@openparachute/scope-guard";
-mock.module("./hub-jwt.ts", () => ({
-  AGENT_AUDIENCE: "agent",
-  CHANNEL_AUDIENCE: "channel", // deprecated alias kept for back-compat
-  async validateHubJwt(token: string) {
-    // New tokens carry aud:"agent" + agent:* scopes (the daemon mints/validates
-    // agent now). A legacy token carries aud:"channel" + channel:* scopes — the
-    // resource server dual-accepts both during the rename window.
-    const base = { sub: "test", aud: "agent", jti: undefined, clientId: undefined, vaultScope: undefined };
-    if (token === ADMIN_TOKEN) return { ...base, scopes: ["agent:read", "agent:send", "agent:admin"] };
-    if (token === READ_TOKEN) return { ...base, scopes: ["agent:read"] };
-    // Pre-rename token: legacy audience + legacy channel:* scopes. requireScope's
-    // dual-accept (hasScope) must still authorize agent:admin from channel:admin.
-    if (token === LEGACY_ADMIN_TOKEN)
-      return { ...base, aud: "channel", scopes: ["channel:read", "channel:send", "channel:admin"] };
-    throw new HubJwtError("issuer", "invalid token");
-  },
-  HubJwtError,
-  looksLikeJwt,
-  resetJwksCache() {},
-  resetRevocationCache() {},
-}));
-
-import {
-  createTerminalWsHandlers,
-  tmuxAttachEnv,
-  parseControlFrame,
-  HUB_WS_CAP_BYTES,
-  PAUSE_FRAC,
-  RESUME_FRAC,
-  type TerminalWsData,
-  type SpawnTerminalFn,
-  type SpawnedTerminal,
-  type BunTerminal,
-} from "./terminal.ts";
-import { authorizeTerminalUpgrade } from "./daemon.ts";
-import type { Channel } from "./registry.ts";
-
-// ===========================================================================
-// Fakes — a recording pty + a controllable ServerWebSocket.
-// ===========================================================================
-
-/** A fake pty that records writes/resizes and lets the test push pty output. */
-class FakePty implements BunTerminal {
-  writes: Uint8Array[] = [];
-  writeStrings: string[] = [];
-  resizes: Array<{ cols: number; rows: number }> = [];
-  closed = false;
-  /** Captured callbacks from the spawn opts — the test drives pty output via these. */
-  onData!: (bytes: Uint8Array) => void;
-  onExit!: () => void;
-
-  write(data: string | ArrayBufferView | ArrayBufferLike): number {
-    if (typeof data === "string") {
-      this.writeStrings.push(data);
-      return data.length;
-    }
-    const u8 = data instanceof Uint8Array ? data : new Uint8Array(data as ArrayBufferLike);
-    this.writes.push(u8);
-    return u8.byteLength;
-  }
-  resize(cols: number, rows: number): void {
-    this.resizes.push({ cols, rows });
-  }
-  close(): void {
-    this.closed = true;
-  }
-}
-
-interface FakeProc {
-  readonly exited: Promise<number>;
-  killed: boolean;
-  kill(signal?: number | string): void;
-}
-
-/** A fake ServerWebSocket: records sends/close, settable buffered depth. */
-class FakeWs {
-  data: TerminalWsData;
-  sent: Uint8Array[] = [];
-  closeCalls: Array<{ code?: number; reason?: string }> = [];
-  /** Test sets this to simulate the hub send-buffer depth. */
-  buffered = 0;
-
-  constructor(data: TerminalWsData) {
-    this.data = data;
-  }
-  send(bytes: Uint8Array | string): number {
-    if (typeof bytes === "string") {
-      this.sent.push(new TextEncoder().encode(bytes));
-      return bytes.length;
-    }
-    this.sent.push(bytes);
-    return bytes.byteLength;
-  }
-  getBufferedAmount(): number {
-    return this.buffered;
-  }
-  close(code?: number, reason?: string): void {
-    this.closeCalls.push({ code, reason });
-  }
-  get totalSentBytes(): number {
-    return this.sent.reduce((n, b) => n + b.byteLength, 0);
-  }
-}
-
-/** Build a fake-pty spawn seam; returns the seam + a handle on the created pty. */
-function makeSpawn(): { spawn: SpawnTerminalFn; ptyRef: { current?: FakePty }; procRef: { current?: FakeProc } } {
-  const ptyRef: { current?: FakePty } = {};
-  const procRef: { current?: FakeProc } = {};
-  const spawn: SpawnTerminalFn = (_session, opts) => {
-    const pty = new FakePty();
-    pty.onData = opts.onData;
-    pty.onExit = opts.onExit;
-    const proc: FakeProc = { exited: Promise.resolve(0), killed: false, kill() { this.killed = true; } };
-    ptyRef.current = pty;
-    procRef.current = proc;
-    return { terminal: pty, proc } as unknown as SpawnedTerminal;
-  };
-  return { spawn, ptyRef, procRef };
-}
-
-function wsData(over: Partial<TerminalWsData> = {}): TerminalWsData {
-  return { session: "eng-agent", channel: "eng", cols: 80, rows: 24, ...over };
-}
-
-/** Open a handler set + fake ws + fake pty, returning the lot for a test. */
-function setup(opts: { capBytes?: number } = {}) {
-  const { spawn, ptyRef, procRef } = makeSpawn();
-  const warnings: string[] = [];
-  const handlers = createTerminalWsHandlers({
-    spawnTerminal: spawn,
-    capBytes: opts.capBytes,
-    logger: { warn: (...a: unknown[]) => warnings.push(a.map(String).join(" ")) },
-  });
-  const ws = new FakeWs(wsData());
-  handlers.open(ws as unknown as ServerWebSocket<TerminalWsData>);
-  return { handlers, ws, pty: () => ptyRef.current!, proc: () => procRef.current!, warnings };
-}
-
-// Cast helper — drive a handler with the fake ws.
-const asWs = (ws: FakeWs) => ws as unknown as ServerWebSocket<TerminalWsData>;
-
-// ===========================================================================
-// parseControlFrame — unit cases
-// ===========================================================================
-describe("parseControlFrame", () => {
-  test("a valid resize frame parses + clamps", () => {
-    expect(parseControlFrame(JSON.stringify({ type: "resize", cols: 120, rows: 40 }))).toEqual({
-      type: "resize",
-      cols: 120,
-      rows: 40,
-    });
-  });
-
-  test("out-of-range dims clamp to [1, 9999]", () => {
-    expect(parseControlFrame(JSON.stringify({ type: "resize", cols: 0, rows: 999999 }))).toEqual({
-      type: "resize",
-      cols: 1,
-      rows: 9999,
-    });
-  });
-
-  test("malformed JSON → null (forwarded as input by the caller)", () => {
-    expect(parseControlFrame("{not json")).toBeNull();
-  });
-
-  test("a non-resize control type → null", () => {
-    expect(parseControlFrame(JSON.stringify({ type: "evil", cmd: "rm -rf /" }))).toBeNull();
-  });
-
-  test("resize with non-finite dims → null", () => {
-    expect(parseControlFrame(JSON.stringify({ type: "resize", cols: "80", rows: NaN }))).toBeNull();
-    expect(parseControlFrame(JSON.stringify({ type: "resize" }))).toBeNull();
-  });
-
-  test("a bare JSON scalar / array (not an object) → null", () => {
-    expect(parseControlFrame("42")).toBeNull();
-    expect(parseControlFrame("null")).toBeNull();
-    expect(parseControlFrame("[1,2,3]")).toBeNull();
-  });
-});
-
-// ===========================================================================
-// Relay — both directions
-// ===========================================================================
-describe("relay — pty ↔ ws", () => {
-  test("pty output → ws.send (binary), bytes preserved", () => {
-    const { ws, pty } = setup();
-    const chunk = new Uint8Array([0x68, 0x69]); // "hi"
-    pty().onData(chunk);
-    expect(ws.sent).toHaveLength(1);
-    expect(Array.from(ws.sent[0]!)).toEqual([0x68, 0x69]);
-  });
-
-  test("ws binary message → terminal.write (keystrokes to the pty)", () => {
-    const { handlers, ws, pty } = setup();
-    const keys = Buffer.from("ls\n");
-    handlers.message(asWs(ws), keys);
-    expect(pty().writes).toHaveLength(1);
-    expect(Buffer.from(pty().writes[0]!).toString()).toBe("ls\n");
-  });
-
-  test("a text frame that ISN'T a control frame is forwarded to the pty as input (fail-safe)", () => {
-    const { handlers, ws, pty } = setup();
-    handlers.message(asWs(ws), "plain text");
-    expect(pty().writeStrings).toEqual(["plain text"]);
-    expect(pty().resizes).toHaveLength(0);
-  });
-});
-
-// ===========================================================================
-// Control frame — resize
-// ===========================================================================
-describe("control frame — resize", () => {
-  test("a {type:resize} text frame → terminal.resize(cols, rows), NOT written as input", () => {
-    const { handlers, ws, pty } = setup();
-    handlers.message(asWs(ws), JSON.stringify({ type: "resize", cols: 100, rows: 30 }));
-    expect(pty().resizes).toEqual([{ cols: 100, rows: 30 }]);
-    expect(pty().writes).toHaveLength(0);
-    expect(pty().writeStrings).toHaveLength(0);
-  });
-});
-
-// ===========================================================================
-// THE load-bearing test — backpressure flood stays alive
-// ===========================================================================
-describe("backpressure — a flood parks in the queue, never closes the socket", () => {
-  // A tiny cap so the test floods it cheaply. pause @ 50% (500), resume @ 25% (250).
-  const CAP = 1000;
-
-  test("a huge burst while the socket buffer is high → paused + coalesced, socket NOT closed, hub cap never approached", () => {
-    const { ws, pty, proc } = setup({ capBytes: CAP });
-
-    // Simulate the hub's send buffer already full (over the pause mark) and never
-    // draining during the burst — exactly the "a build log floods xterm" case.
-    ws.buffered = CAP; // 1000 ≥ pauseAt(500)
-
-    // First chunk goes out, then the post-send buffered check trips pause.
-    pty().onData(new Uint8Array(64));
-    // Subsequent chunks while paused MUST queue, not send.
-    const FLOOD_CHUNK = new Uint8Array(64 * 1024); // 64 KiB each
-    for (let i = 0; i < 200; i++) pty().onData(FLOOD_CHUNK); // ~12.8 MiB of pty output
-
-    // The socket is ALIVE — no close (no 1011, no 1013), pty alive, proc alive.
-    expect(ws.closeCalls).toHaveLength(0);
-    expect(pty().closed).toBe(false);
-    expect(proc().killed).toBe(false);
-
-    // Our OWN buffered bytes (what the hub sees) never grew past the one chunk we
-    // sent before pausing — the flood parked daemon-side, NOT in the hub buffer.
-    // i.e. we never let the socket approach the 8 MiB hub cap.
-    expect(ws.totalSentBytes).toBeLessThanOrEqual(64);
-    expect(ws.totalSentBytes).toBeLessThan(HUB_WS_CAP_BYTES);
-  });
-
-  test("when the client drains, the queued flood is eventually delivered (resume)", () => {
-    const { handlers, ws, pty } = setup({ capBytes: CAP });
-
-    ws.buffered = CAP; // over pause mark
-    pty().onData(new Uint8Array(64)); // sent → then pause
-    // Queue a bounded flood (well under MAX_QUEUE_BYTES so it parks, not closes).
-    const N = 50;
-    const CHUNK = 64; // bytes
-    for (let i = 0; i < N; i++) pty().onData(new Uint8Array(CHUNK).fill(i));
-    expect(ws.closeCalls).toHaveLength(0);
-    const sentBeforeDrain = ws.sent.length;
-
-    // Client catches up: buffer empties. Bun fires drain repeatedly as it clears;
-    // drain flushes the queue while buffered stays under the pause mark.
-    ws.buffered = 0;
-    // A few drain cycles to flush the whole queue (flushQueue drains until empty
-    // or the pause mark; with buffered=0 it empties in one pass, but loop to be safe).
-    for (let i = 0; i < 5 && ws.sent.length < sentBeforeDrain + N; i++) {
-      handlers.drain(asWs(ws));
-    }
-
-    // Everything queued got delivered — the flood was buffered, not dropped.
-    expect(ws.sent.length).toBe(sentBeforeDrain + N);
-    expect(ws.closeCalls).toHaveLength(0);
-    // And the very last queued chunk arrived intact (content preserved through the queue).
-    const last = ws.sent[ws.sent.length - 1]!;
-    expect(last.byteLength).toBe(CHUNK);
-    expect(last[0]).toBe(N - 1);
-  });
-});
-
-// ===========================================================================
-// Hysteresis — pause @ 50%, resume only under 25%
-// ===========================================================================
-describe("hysteresis — pause @ PAUSE_FRAC, resume only under RESUME_FRAC", () => {
-  const CAP = 1000; // pauseAt = 500, resumeAt = 250
-
-  test("constants are 0.5 / 0.25 (the documented margins)", () => {
-    expect(PAUSE_FRAC).toBe(0.5);
-    expect(RESUME_FRAC).toBe(0.25);
-  });
-
-  test("does NOT pause while buffered stays under the pause mark", () => {
-    const { ws, pty } = setup({ capBytes: CAP });
-    ws.buffered = 400; // < pauseAt(500)
-    pty().onData(new Uint8Array(10));
-    pty().onData(new Uint8Array(10)); // still forwarded, not queued
-    expect(ws.sent).toHaveLength(2);
-    expect(ws.closeCalls).toHaveLength(0);
-  });
-
-  test("pauses at the 50% mark; a drain to BETWEEN resume(25%) and pause(50%) does NOT resume", () => {
-    const { handlers, ws, pty } = setup({ capBytes: CAP });
-    ws.buffered = 500; // == pauseAt → pause after the send
-    pty().onData(new Uint8Array(10));
-    // Now paused: a new pty chunk queues rather than sends.
-    pty().onData(new Uint8Array(10));
-    expect(ws.sent).toHaveLength(1); // only the first went out
-
-    // Drain partway — buffer at 300 (still > resumeAt 250). Queue flushes only if
-    // under the pause mark (300 < 500 so it flushes), but we stay PAUSED for live
-    // forwarding because we're not yet under the resume mark.
-    ws.buffered = 300;
-    handlers.drain(asWs(ws));
-    // A fresh live chunk should STILL queue (paused), proving no premature resume.
-    const sentAfterDrain = ws.sent.length;
-    pty().onData(new Uint8Array(10));
-    expect(ws.sent.length).toBe(sentAfterDrain); // still paused → queued, not sent
-  });
-
-  test("resumes only once buffered falls under the 25% mark (and the queue is empty)", () => {
-    const { handlers, ws, pty } = setup({ capBytes: CAP });
-    ws.buffered = 600; // pause
-    pty().onData(new Uint8Array(10));
-    pty().onData(new Uint8Array(10)); // queued
-
-    // Drain fully under the resume mark → drain flushes the queue + resumes.
-    ws.buffered = 100; // < resumeAt(250)
-    handlers.drain(asWs(ws));
-    // Now resumed: a new live chunk forwards immediately.
-    const before = ws.sent.length;
-    pty().onData(new Uint8Array(10));
-    expect(ws.sent.length).toBe(before + 1);
-  });
-});
-
-// ===========================================================================
-// 1013 — a hopelessly-stuck client is shed
-// ===========================================================================
-describe("stuck client — closed 1013 when the queue blows past MAX_QUEUE_BYTES", () => {
-  // Keep the hub cap tiny so we pause immediately; the queue cap (16 MiB) is the
-  // line under test. Flood past 16 MiB while the socket never drains.
-  const CAP = 1000;
-
-  test(">16 MiB queued while the socket stays full → close(1013), pty + viewer torn down", () => {
-    const { ws, pty, proc, warnings } = setup({ capBytes: CAP });
-    ws.buffered = CAP; // perpetually over the pause mark → everything queues
-    pty().onData(new Uint8Array(64)); // first send trips pause
-
-    // 17 MiB in 1 MiB chunks — crosses the 16 MiB MAX_QUEUE_BYTES line.
-    const MiB = new Uint8Array(1024 * 1024);
-    for (let i = 0; i < 17; i++) pty().onData(MiB);
-
-    const closed1013 = ws.closeCalls.find((c) => c.code === 1013);
-    expect(closed1013).toBeDefined();
-    expect(pty().closed).toBe(true); // pty closed
-    expect(proc().killed).toBe(true); // viewer process killed
-    expect(warnings.some((w) => w.includes("too far behind") || w.includes("too slow"))).toBe(true);
-  });
-});
-
-// ===========================================================================
-// Lifecycle — pty exit + client close tear down the viewer (session lives on)
-// ===========================================================================
-describe("lifecycle — teardown", () => {
-  test("pty exit closes the socket with a clean 1000 (session ended)", () => {
-    const { ws, pty, proc } = setup();
-    pty().onExit();
-    expect(ws.closeCalls.some((c) => c.code === 1000)).toBe(true);
-    expect(pty().closed).toBe(true);
-    expect(proc().killed).toBe(true);
-  });
-
-  test("client close releases the pty + kills the viewer proc (idempotent)", () => {
-    const { handlers, ws, pty, proc } = setup();
-    handlers.close(asWs(ws));
-    expect(pty().closed).toBe(true);
-    expect(proc().killed).toBe(true);
-    // Idempotent — a second close is a no-op (no throw, no double behavior change).
-    expect(() => handlers.close(asWs(ws))).not.toThrow();
-  });
-});
-
-// ===========================================================================
-// tmuxAttachEnv — TERM wiring for the `tmux attach` viewer
-// ===========================================================================
-describe("tmuxAttachEnv — forces a real TERM so `tmux attach` finds terminfo", () => {
-  test("sets TERM=xterm-256color (else tmux aborts 'does not support clear')", () => {
-    expect(tmuxAttachEnv({ PATH: "/usr/bin" }).TERM).toBe("xterm-256color");
-  });
-  test("preserves the inherited env + overrides a stale/empty TERM", () => {
-    const env = tmuxAttachEnv({ PATH: "/usr/bin", HOME: "/home/op", TERM: "" });
-    expect(env.PATH).toBe("/usr/bin");
-    expect(env.HOME).toBe("/home/op");
-    expect(env.TERM).toBe("xterm-256color"); // empty/missing TERM is the daemon's reality
-  });
-});
-
-// ===========================================================================
-// Daemon-side terminal auth — authorizeTerminalUpgrade (pure fn)
-// ===========================================================================
-describe("authorizeTerminalUpgrade — operator-gated agent:admin", () => {
-  function channels(names: string[] = ["eng"]): Map<string, Channel> {
-    const m = new Map<string, Channel>();
-    for (const name of names) {
-      m.set(name, { name, transport: {} as Channel["transport"], entry: { name, transport: "vault" } });
-    }
-    return m;
-  }
-  function req(query = ""): { req: Request; url: URL } {
-    const url = new URL(`http://127.0.0.1/terminal/eng${query}`);
-    return { req: new Request(url, { headers: { upgrade: "websocket" } }), url };
-  }
-
-  test("missing token → reject (401), no session leaked", async () => {
-    const { req: r, url } = req();
-    const d = await authorizeTerminalUpgrade(r, url, channels(), "eng");
-    expect(d.ok).toBe(false);
-    if (!d.ok) expect(d.response.status).toBe(401);
-  });
-
-  test("bad/expired token → reject (401)", async () => {
-    const { req: r, url } = req("?token=garbage-not-a-real-jwt");
-    const d = await authorizeTerminalUpgrade(r, url, channels(), "eng");
-    expect(d.ok).toBe(false);
-    if (!d.ok) expect(d.response.status).toBe(401);
-  });
-
-  test("under-scoped token (agent:read, not agent:admin) → reject (403)", async () => {
-    const { req: r, url } = req(`?token=${READ_TOKEN}`);
-    const d = await authorizeTerminalUpgrade(r, url, channels(), "eng");
-    expect(d.ok).toBe(false);
-    if (!d.ok) expect(d.response.status).toBe(403);
-  });
-
-  test("valid agent:admin token → ok, with the right tmux session + geometry", async () => {
-    const { req: r, url } = req(`?token=${ADMIN_TOKEN}&cols=120&rows=40`);
-    const d = await authorizeTerminalUpgrade(r, url, channels(), "eng");
-    expect(d.ok).toBe(true);
-    if (d.ok) {
-      expect(d.channel).toBe("eng");
-      expect(d.session).toBe("eng-agent"); // <name>-agent (launch-session.sh:38)
-      expect(d.cols).toBe(120);
-      expect(d.rows).toBe(40);
-    }
-  });
-
-  test("legacy channel:admin token still authorizes (dual-accept back-compat)", async () => {
-    // A token minted before the channel→agent rename carries channel:admin (and
-    // aud:"channel"). requireScope's dual-accept (hasScope) must still authorize
-    // the agent:admin-gated terminal until live tokens are re-minted.
-    const { req: r, url } = req(`?token=${LEGACY_ADMIN_TOKEN}&cols=100&rows=30`);
-    const d = await authorizeTerminalUpgrade(r, url, channels(), "eng");
-    expect(d.ok).toBe(true);
-    if (d.ok) {
-      expect(d.session).toBe("eng-agent");
-      expect(d.cols).toBe(100);
-      expect(d.rows).toBe(30);
-    }
-  });
-
-  test("geometry defaults (80×24) when cols/rows absent or out-of-range", async () => {
-    const { req: r, url } = req(`?token=${ADMIN_TOKEN}&cols=0&rows=abc`);
-    const d = await authorizeTerminalUpgrade(r, url, channels(), "eng");
-    expect(d.ok).toBe(true);
-    if (d.ok) {
-      expect(d.cols).toBe(80);
-      expect(d.rows).toBe(24);
-    }
-  });
-
-  test("an agent name that isn't a configured channel is ACCEPTED → its session (agents have own names)", async () => {
-    // The terminal attaches to an AGENT (tmux <name>-agent), not a channel — so a
-    // valid-slug name that isn't in the channel map is accepted (a non-existent
-    // session just fails to attach downstream with a clean 1000, no 404 here).
-    const url = new URL(`http://127.0.0.1/terminal/weaver?token=${ADMIN_TOKEN}`);
-    const r = new Request(url, { headers: { upgrade: "websocket" } });
-    const d = await authorizeTerminalUpgrade(r, url, channels(["eng"]), "weaver");
-    expect(d.ok).toBe(true);
-    if (d.ok) expect(d.session).toBe("weaver-agent");
-  });
-
-  test("a path-traversal-shaped name is rejected by the slug guard → 400 (no escape into tmux -t)", async () => {
-    const weird = "../../etc";
-    const url = new URL(`http://127.0.0.1/terminal/${encodeURIComponent(weird)}?token=${ADMIN_TOKEN}`);
-    const r = new Request(url, { headers: { upgrade: "websocket" } });
-    const d = await authorizeTerminalUpgrade(r, url, channels(["eng"]), weird);
-    expect(d.ok).toBe(false);
-    if (!d.ok) expect(d.response.status).toBe(400);
-  });
-});
-
-// Touch HUB_WS_CAP_BYTES so the import is load-bearing if the relationship to the
-// hub cap ever drifts (the constant mirrors the hub's DEFAULT_MAX_BUFFERED_BYTES).
-test("HUB_WS_CAP_BYTES mirrors the hub's 8 MiB cap", () => {
-  expect(HUB_WS_CAP_BYTES).toBe(8 * 1024 * 1024);
-});