tmux-agent 0.1.0

package/tests/unit/codexSend.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it, vi } from "vitest";
+import { codexSendCommand } from "../../src/cli/commands/codex/send";
+import { codexSend } from "../../src/lib/codex/send";
+import { readStdin } from "../../src/lib/io/readStdin";
+import { resolveSessionScope } from "../../src/lib/targeting/scope";
+import { snapshotPanes } from "../../src/lib/tmux/snapshotPanes";
+import { tmuxExec } from "../../src/lib/tmux/exec";
+import { pasteText } from "../../src/lib/tmux/paste";
+import { capturePane } from "../../src/lib/tmux/capturePane";
+
+vi.mock("../../src/lib/io/readStdin", () => ({
+  readStdin: vi.fn()
+}));
+
+vi.mock("../../src/lib/targeting/scope", () => ({
+  resolveSessionScope: vi.fn(),
+  resolveWindowScope: vi.fn()
+}));
+
+vi.mock("../../src/lib/tmux/snapshotPanes", () => ({
+  snapshotPanes: vi.fn()
+}));
+
+vi.mock("../../src/lib/tmux/exec", () => ({
+  tmuxExec: vi.fn()
+}));
+
+vi.mock("../../src/lib/tmux/paste", () => ({
+  pasteText: vi.fn()
+}));
+
+vi.mock("../../src/lib/tmux/capturePane", () => ({
+  capturePane: vi.fn()
+}));
+
+describe("codex send", () => {
+  it("treats key expressions as key mode", async () => {
+    vi.mocked(tmuxExec).mockResolvedValue({ stdout: "", stderr: "", exitCode: 0 });
+    vi.mocked(capturePane).mockResolvedValue("tail");
+
+    const result = await codexSend("%1", "Ctrl+C", { captureTailLines: 5 });
+
+    expect(vi.mocked(pasteText)).not.toHaveBeenCalled();
+    expect(vi.mocked(tmuxExec)).toHaveBeenCalledWith(["send-keys", "-t", "%1", "C-c"]);
+    expect(result.mode).toBe("keys");
+    expect(result.capture_tail).toBe("tail");
+  });
+
+  it("reads stdin when text is '-'", async () => {
+    vi.useFakeTimers();
+    vi.mocked(resolveSessionScope).mockResolvedValue({ session: "s", source: "explicit" });
+    vi.mocked(snapshotPanes).mockResolvedValue([
+      {
+        id: "%1",
+        idx: 0,
+        pid: 123,
+        command: "zsh",
+        title: "codex",
+        status: "active",
+        windowId: "@1"
+      }
+    ]);
+    vi.mocked(readStdin).mockResolvedValue("hello from stdin");
+    vi.mocked(tmuxExec).mockResolvedValue({ stdout: "", stderr: "", exitCode: 0 });
+    vi.mocked(pasteText).mockResolvedValue();
+
+    const promise = codexSendCommand("%1", "-", { json: true });
+    await vi.advanceTimersByTimeAsync(250);
+    const output = await promise;
+    vi.useRealTimers();
+
+    const parsed = JSON.parse(output);
+    expect(parsed.requested).toEqual({ target: "%1", text_source: "stdin" });
+    expect(parsed.resolved.id).toBe("%1");
+    expect(parsed.sent.submit).toBe("Enter");
+    expect(parsed.sent.submit_delay_ms).toBe(250);
+  });
+
+  it("returns captured tail when --capture-tail is set without --json", async () => {
+    vi.useFakeTimers();
+    vi.mocked(resolveSessionScope).mockResolvedValue({ session: "s", source: "explicit" });
+    vi.mocked(snapshotPanes).mockResolvedValue([
+      {
+        id: "%1",
+        idx: 0,
+        pid: 123,
+        command: "zsh",
+        title: "codex",
+        status: "active",
+        windowId: "@1"
+      }
+    ]);
+    vi.mocked(tmuxExec).mockResolvedValue({ stdout: "", stderr: "", exitCode: 0 });
+    vi.mocked(pasteText).mockResolvedValue();
+    vi.mocked(capturePane).mockResolvedValue("tail");
+
+    const promise = codexSendCommand("%1", "继续", { captureTail: 5 });
+    await vi.advanceTimersByTimeAsync(250);
+    const output = await promise;
+    vi.useRealTimers();
+
+    expect(output).toBe("tail");
+    expect(vi.mocked(capturePane)).toHaveBeenCalledWith("%1", 5);
+  });
+});

package/tests/unit/codexSessionInfo.test.ts

@@ -0,0 +1,88 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it, vi } from "vitest";
+import { resolveCodexSessionInfo } from "../../src/lib/codex/sessionInfo";
+import { listProcesses } from "../../src/lib/proc/ps";
+import { listOpenFiles } from "../../src/lib/proc/lsof";
+
+vi.mock("../../src/lib/proc/ps", () => ({
+  listProcesses: vi.fn()
+}));
+
+vi.mock("../../src/lib/proc/lsof", () => ({
+  listOpenFiles: vi.fn()
+}));
+
+describe("codex session-info", () => {
+  it("rejects multiple rollout candidates with diagnostics", async () => {
+    const codexHome = await fs.mkdtemp(path.join(os.tmpdir(), "agent-tmux-codex-"));
+    const sessionsDir = path.join(codexHome, "sessions");
+    await fs.mkdir(sessionsDir, { recursive: true });
+    const rolloutA = path.join(
+      sessionsDir,
+      "rollout-11111111-1111-1111-1111-111111111111.jsonl"
+    );
+    const rolloutB = path.join(
+      sessionsDir,
+      "rollout-22222222-2222-2222-2222-222222222222.jsonl"
+    );
+    await fs.writeFile(rolloutA, "{}", "utf8");
+    await fs.writeFile(rolloutB, "{}", "utf8");
+
+    vi.mocked(listProcesses).mockResolvedValue([
+      { pid: 100, ppid: 1, tty: "ttys001", command: "codex" },
+      { pid: 101, ppid: 1, tty: "ttys002", command: "codex" }
+    ]);
+
+    vi.mocked(listOpenFiles).mockImplementation(async (pid: number) => {
+      if (pid === 100) {
+        return [rolloutA];
+      }
+      if (pid === 101) {
+        return [rolloutB];
+      }
+      return [];
+    });
+
+    try {
+      await resolveCodexSessionInfo({ codexHome });
+      throw new Error("expected resolveCodexSessionInfo to throw");
+    } catch (error: unknown) {
+      expect(error).toBeInstanceOf(Error);
+      const message = (error as Error).message;
+      expect(message).toContain("multiple codex sessions found");
+      expect(message).toContain(`pid=100`);
+      expect(message).toContain(rolloutA);
+      expect(message).toContain(`pid=101`);
+      expect(message).toContain(rolloutB);
+    } finally {
+      await fs.rm(codexHome, { recursive: true, force: true });
+    }
+  });
+
+  it("returns session_id and rollout_path when unique", async () => {
+    const codexHome = await fs.mkdtemp(path.join(os.tmpdir(), "agent-tmux-codex-"));
+    const sessionsDir = path.join(codexHome, "sessions");
+    await fs.mkdir(sessionsDir, { recursive: true });
+    const rollout = path.join(
+      sessionsDir,
+      "rollout-33333333-3333-3333-3333-333333333333.jsonl"
+    );
+    await fs.writeFile(rollout, "{}", "utf8");
+
+    vi.mocked(listProcesses).mockResolvedValue([
+      { pid: 100, ppid: 1, tty: "ttys001", command: "codex" }
+    ]);
+    vi.mocked(listOpenFiles).mockResolvedValue([rollout]);
+
+    try {
+      const info = await resolveCodexSessionInfo({ codexHome });
+      expect(info.sessionId).toBe("33333333-3333-3333-3333-333333333333");
+      expect(info.rolloutPath).toBe(rollout);
+    } finally {
+      await fs.rm(codexHome, { recursive: true, force: true });
+    }
+  });
+});
+

package/tests/unit/codexSpawn.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it, vi } from "vitest";
+import { codexSpawnCommand } from "../../src/cli/commands/codex/spawn";
+import { tmuxExec } from "../../src/lib/tmux/exec";
+
+vi.mock("../../src/lib/tmux/exec", () => ({
+  tmuxExec: vi.fn()
+}));
+
+describe("codex spawn", () => {
+  it("refuses to run without an origin target outside tmux", async () => {
+    const previous = {
+      TMUX: process.env.TMUX,
+      TMUX_PANE: process.env.TMUX_PANE,
+      CODEX_PANE_ID: process.env.CODEX_PANE_ID,
+      ORIGIN_PANE_ID: process.env.ORIGIN_PANE_ID
+    };
+
+    delete process.env.TMUX;
+    delete process.env.TMUX_PANE;
+    delete process.env.CODEX_PANE_ID;
+    delete process.env.ORIGIN_PANE_ID;
+
+    vi.mocked(tmuxExec).mockResolvedValue({ stdout: "", stderr: "", exitCode: 0 });
+
+    try {
+      await expect(codexSpawnCommand({})).rejects.toThrow("requires --origin");
+    } finally {
+      process.env.TMUX = previous.TMUX;
+      process.env.TMUX_PANE = previous.TMUX_PANE;
+      process.env.CODEX_PANE_ID = previous.CODEX_PANE_ID;
+      process.env.ORIGIN_PANE_ID = previous.ORIGIN_PANE_ID;
+    }
+  });
+});

package/tests/unit/keys.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { classifySendInput, parseKeyExpression } from "../../src/lib/tmux/sendKeys";
+
+describe("send keys parsing", () => {
+  it("parses Ctrl+<A-Z>", () => {
+    expect(parseKeyExpression("Ctrl+C")).toBe("C-c");
+    expect(parseKeyExpression("Ctrl+z")).toBe("C-z");
+  });
+
+  it("parses Enter", () => {
+    expect(parseKeyExpression("Enter")).toBe("Enter");
+  });
+
+  it("classifies key mode without enter", () => {
+    const result = classifySendInput("Ctrl+C", false);
+    expect(result.mode).toBe("keys");
+    expect(result.enter).toBe(false);
+  });
+
+  it("classifies text mode with enter default", () => {
+    const result = classifySendInput("echo hi", false);
+    expect(result.mode).toBe("text");
+    expect(result.enter).toBe(true);
+  });
+
+  it("respects no-enter for text", () => {
+    const result = classifySendInput("echo hi", true);
+    expect(result.enter).toBe(false);
+  });
+});

package/tests/unit/outputFormat.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import {
+  formatCommandTitle,
+  formatPaneStatus,
+  formatPaneTable,
+  formatWindowStatus,
+  formatWindowTable
+} from "../../src/lib/output/format";
+import type { PaneInfo, WindowInfo } from "../../src/lib/contracts/types";
+
+describe("output format", () => {
+  it("formats window status", () => {
+    expect(formatWindowStatus("active")).toBe("[Active]");
+    expect(formatWindowStatus("inactive")).toBe("[Idle]");
+  });
+
+  it("formats pane status", () => {
+    expect(formatPaneStatus("active")).toBe("[Active]");
+    expect(formatPaneStatus("idle")).toBe("[Idle]");
+    expect(formatPaneStatus("dead")).toBe("[Dead]");
+  });
+
+  it("formats command/title", () => {
+    expect(formatCommandTitle("vim", "app.py")).toContain("vim");
+    expect(formatCommandTitle("vim", "app.py")).toContain("app.py");
+  });
+
+  it("formats window table", () => {
+    const windows: WindowInfo[] = [
+      { widx: 0, wid: "@0", name: "dev", status: "active" }
+    ];
+    const table = formatWindowTable(windows);
+    expect(table).toContain("WIDX");
+    expect(table).toContain("@0");
+  });
+
+  it("formats pane table", () => {
+    const panes: PaneInfo[] = [
+      {
+        idx: 0,
+        id: "%630",
+        status: "active",
+        command: "vim",
+        title: "app.py",
+        windowId: "@0"
+      }
+    ];
+    const table = formatPaneTable(panes);
+    expect(table).toContain("COMMAND/TITLE");
+    expect(table).toContain("%630");
+  });
+});

package/tests/unit/popupSelect.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("../../src/lib/ui/popupSupport", () => ({
+  checkPopupSupport: vi.fn()
+}));
+
+vi.mock("../../src/lib/tmux/exec", () => ({
+  tmuxExec: vi.fn()
+}));
+
+import { popupSelect, normalizePopupSelectSpec } from "../../src/lib/ui/popupSelect";
+import { checkPopupSupport } from "../../src/lib/ui/popupSupport";
+import { tmuxExec } from "../../src/lib/tmux/exec";
+
+describe("popup select", () => {
+  it("normalizes timeout_ms (default 1h, 0 means no timeout)", () => {
+    const normalizedDefault = normalizePopupSelectSpec({ choices: ["a"] });
+    expect(normalizedDefault.timeoutMs).toBe(3600000);
+    expect(normalizedDefault.waitForFocusTimeoutMs).toBe(3600000);
+    expect(normalizedDefault.waitForResultTimeoutMs).toBe(3600000);
+
+    const normalizedNoTimeout = normalizePopupSelectSpec({ choices: ["a"], timeout_ms: 0 });
+    expect(normalizedNoTimeout.timeoutMs).toBeNull();
+    expect(normalizedNoTimeout.waitForFocusTimeoutMs).toBeNull();
+    expect(normalizedNoTimeout.waitForResultTimeoutMs).toBeNull();
+  });
+
+  it("supports percent sizing for width/height", () => {
+    const normalized = normalizePopupSelectSpec({
+      choices: ["a"],
+      width: "80%",
+      height: "60%"
+    });
+    expect(normalized.width).toBe("80%");
+    expect(normalized.height).toBe("60%");
+  });
+
+  it("times out when popup never returns", async () => {
+    const previousPane = process.env.TMUX_PANE;
+    process.env.TMUX_PANE = "%1";
+
+    vi.mocked(checkPopupSupport).mockResolvedValue({ ok: true });
+    vi.mocked(tmuxExec).mockImplementation((args: string[]) => {
+      if (args[0] === "display-message") {
+        return Promise.resolve({ stdout: "@1\n", stderr: "", exitCode: 0 });
+      }
+      if (args[0] === "list-clients") {
+        return Promise.resolve({
+          stdout: "client1\t/dev/ttys001\tfocused\t$0\tsession\t@1\t%1\n",
+          stderr: "",
+          exitCode: 0
+        });
+      }
+      if (args[0] === "display-popup") {
+        return new Promise(() => undefined);
+      }
+      return Promise.resolve({ stdout: "", stderr: "", exitCode: 0 });
+    });
+
+    try {
+      const promise = popupSelect({
+        mode: "single",
+        defer_if_unfocused: false,
+        defer_until_pane_active: false,
+        timeout_ms: 200,
+        choices: ["a"]
+      });
+      await expect(promise).rejects.toThrow("ui select timed out");
+    } finally {
+      if (previousPane === undefined) {
+        delete process.env.TMUX_PANE;
+      } else {
+        process.env.TMUX_PANE = previousPane;
+      }
+    }
+  });
+});

package/tests/unit/popupSupport.test.ts

@@ -0,0 +1,109 @@
+import { EventEmitter } from "node:events";
+import { PassThrough } from "node:stream";
+import { describe, expect, it, vi } from "vitest";
+
+type SpawnReturn = EventEmitter & { stdout?: PassThrough; stderr?: PassThrough; stdin?: PassThrough };
+
+let spawnImpl: (command: string, args: string[]) => SpawnReturn;
+
+vi.mock("node:child_process", () => ({
+  spawn: (command: string, args: string[]) => spawnImpl(command, args)
+}));
+
+import { checkPopupSupport } from "../../src/lib/ui/popupSupport";
+
+function spawnOk(output: string): SpawnReturn {
+  const child: SpawnReturn = Object.assign(new EventEmitter(), {
+    stdout: new PassThrough(),
+    stderr: new PassThrough()
+  });
+  process.nextTick(() => {
+    child.stdout?.write(output);
+    child.stdout?.end();
+    child.emit("close", 0);
+  });
+  return child;
+}
+
+function spawnFail(stderr: string): SpawnReturn {
+  const child: SpawnReturn = Object.assign(new EventEmitter(), {
+    stdout: new PassThrough(),
+    stderr: new PassThrough()
+  });
+  process.nextTick(() => {
+    child.stderr?.write(stderr);
+    child.stderr?.end();
+    child.emit("close", 1);
+  });
+  return child;
+}
+
+describe("popup support gate", () => {
+  it("rejects when not inside tmux", async () => {
+    const previous = { TMUX: process.env.TMUX, TMUX_PANE: process.env.TMUX_PANE };
+    delete process.env.TMUX;
+    delete process.env.TMUX_PANE;
+
+    spawnImpl = () => spawnOk("");
+
+    try {
+      const support = await checkPopupSupport();
+      expect(support.ok).toBe(false);
+      expect(support.reason).toContain("inside tmux");
+    } finally {
+      process.env.TMUX = previous.TMUX;
+      process.env.TMUX_PANE = previous.TMUX_PANE;
+    }
+  });
+
+  it("rejects when tmux lacks display-popup", async () => {
+    const previous = { TMUX: process.env.TMUX, TMUX_PANE: process.env.TMUX_PANE };
+    process.env.TMUX = "/tmp/tmux,123,0";
+    process.env.TMUX_PANE = "%1";
+
+    spawnImpl = (command, args) => {
+      if (command === "tmux" && args[0] === "list-commands") {
+        return spawnOk("split-window\nlist-panes\n");
+      }
+      if (command === "fzf") {
+        return spawnOk("0.0.0\n");
+      }
+      return spawnFail("unexpected command");
+    };
+
+    try {
+      const support = await checkPopupSupport();
+      expect(support.ok).toBe(false);
+      expect(support.reason).toContain("display-popup");
+    } finally {
+      process.env.TMUX = previous.TMUX;
+      process.env.TMUX_PANE = previous.TMUX_PANE;
+    }
+  });
+
+  it("rejects when fzf is missing", async () => {
+    const previous = { TMUX: process.env.TMUX, TMUX_PANE: process.env.TMUX_PANE };
+    process.env.TMUX = "/tmp/tmux,123,0";
+    process.env.TMUX_PANE = "%1";
+
+    spawnImpl = (command, args) => {
+      if (command === "tmux" && args[0] === "list-commands") {
+        return spawnOk("display-popup\n");
+      }
+      if (command === "fzf") {
+        return spawnFail("not found");
+      }
+      return spawnFail("unexpected command");
+    };
+
+    try {
+      const support = await checkPopupSupport();
+      expect(support.ok).toBe(false);
+      expect(support.reason).toContain("fzf");
+    } finally {
+      process.env.TMUX = previous.TMUX;
+      process.env.TMUX_PANE = previous.TMUX_PANE;
+    }
+  });
+});
+

package/tests/unit/resolvePaneTarget.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { resolvePaneTarget } from "../../src/lib/targeting/resolvePaneTarget";
+import { TargetResolutionError } from "../../src/lib/targeting/errors";
+import type { PaneInfo } from "../../src/lib/contracts/types";
+
+const panes: PaneInfo[] = [
+  { idx: 0, id: "%100", status: "active", command: "vim", title: "app.py", windowId: "@0" },
+  { idx: 1, id: "%101", status: "idle", command: "npm", title: "run dev", windowId: "@0" },
+  { idx: 2, id: "%102", status: "idle", command: "vim", title: "main.ts", windowId: "@0" },
+  { idx: 0, id: "%200", status: "idle", command: "vim", title: "README.md", windowId: "@1" }
+];
+
+describe("resolvePaneTarget", () => {
+  it("resolves by pane id", () => {
+    const resolved = resolvePaneTarget(panes, "%101", { windowId: "@0" });
+    expect(resolved.id).toBe("%101");
+  });
+
+  it("resolves by idx within window", () => {
+    const resolved = resolvePaneTarget(panes, "0", { windowId: "@0" });
+    expect(resolved.id).toBe("%100");
+  });
+
+  it("resolves by keyword", () => {
+    const resolved = resolvePaneTarget(panes, "npm", { windowId: "@0" });
+    expect(resolved.id).toBe("%101");
+  });
+
+  it("throws on ambiguous keyword", () => {
+    expect(() => resolvePaneTarget(panes, "vim", { windowId: "@0" })).toThrow(
+      TargetResolutionError
+    );
+  });
+
+  it("supports composite target", () => {
+    const resolved = resolvePaneTarget(panes, "@0%100");
+    expect(resolved.id).toBe("%100");
+  });
+
+  it("throws on invalid composite target", () => {
+    expect(() => resolvePaneTarget(panes, "@2%100")).toThrow(TargetResolutionError);
+  });
+});

package/tests/unit/resolveWindowTarget.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { resolveWindowTarget } from "../../src/lib/targeting/resolveWindowTarget";
+import { TargetResolutionError } from "../../src/lib/targeting/errors";
+import type { WindowInfo } from "../../src/lib/contracts/types";
+
+const windows: WindowInfo[] = [
+  { widx: 0, wid: "@0", name: "dev", status: "active" },
+  { widx: 1, wid: "@1", name: "logs", status: "inactive" },
+  { widx: 2, wid: "@2", name: "dev-api", status: "inactive" }
+];
+
+describe("resolveWindowTarget", () => {
+  it("resolves by window id", () => {
+    const resolved = resolveWindowTarget(windows, "@1");
+    expect(resolved.wid).toBe("@1");
+    expect(resolved.widx).toBe(1);
+  });
+
+  it("resolves by window index", () => {
+    const resolved = resolveWindowTarget(windows, "2");
+    expect(resolved.wid).toBe("@2");
+  });
+
+  it("resolves by keyword", () => {
+    const resolved = resolveWindowTarget(windows, "logs");
+    expect(resolved.wid).toBe("@1");
+  });
+
+  it("throws on ambiguous keyword", () => {
+    expect(() => resolveWindowTarget(windows, "dev")).toThrow(TargetResolutionError);
+  });
+
+  it("throws on missing target", () => {
+    expect(() => resolveWindowTarget(windows, "missing")).toThrow(TargetResolutionError);
+  });
+});

package/tests/unit/safeRm.test.ts

@@ -0,0 +1,41 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { safeRemove } from "../../src/lib/fs/safeRm";
+
+describe("safeRemove", () => {
+  it("refuses to remove allowed_root itself", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "agent-tmux-safeRm-"));
+    try {
+      await expect(safeRemove(root, root)).rejects.toThrow("refuse to remove allowed root");
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("refuses to remove a path outside allowed_root", async () => {
+    const allowed = await fs.mkdtemp(path.join(os.tmpdir(), "agent-tmux-safeRm-allowed-"));
+    const outside = await fs.mkdtemp(path.join(os.tmpdir(), "agent-tmux-safeRm-outside-"));
+    try {
+      await expect(safeRemove(outside, allowed)).rejects.toThrow("outside allowed_root");
+    } finally {
+      await fs.rm(allowed, { recursive: true, force: true });
+      await fs.rm(outside, { recursive: true, force: true });
+    }
+  });
+
+  it("removes a path under allowed_root", async () => {
+    const allowed = await fs.mkdtemp(path.join(os.tmpdir(), "agent-tmux-safeRm-allowed-"));
+    const target = path.join(allowed, "subdir");
+    await fs.mkdir(target, { recursive: true });
+    await fs.writeFile(path.join(target, "file.txt"), "ok", "utf8");
+
+    const removed = await safeRemove(target, allowed);
+    expect(removed).toBe(true);
+
+    await expect(fs.stat(target)).rejects.toBeTruthy();
+    await fs.rm(allowed, { recursive: true, force: true });
+  });
+});
+

package/tests/unit/scope.test.ts

@@ -0,0 +1,57 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { resolveSessionScope, resolveWindowScope } from "../../src/lib/targeting/scope";
+import { tmuxExec } from "../../src/lib/tmux/exec";
+import { snapshotWindows } from "../../src/lib/tmux/snapshotWindows";
+import type { WindowInfo } from "../../src/lib/contracts/types";
+
+vi.mock("../../src/lib/tmux/exec", () => ({
+  tmuxExec: vi.fn()
+}));
+
+vi.mock("../../src/lib/tmux/snapshotWindows", () => ({
+  snapshotWindows: vi.fn()
+}));
+
+const tmuxExecMock = vi.mocked(tmuxExec);
+const snapshotWindowsMock = vi.mocked(snapshotWindows);
+
+const windows: WindowInfo[] = [
+  { widx: 0, wid: "@0", name: "dev", status: "inactive" },
+  { widx: 1, wid: "@1", name: "logs", status: "active" }
+];
+
+describe("scope", () => {
+  beforeEach(() => {
+    tmuxExecMock.mockReset();
+    snapshotWindowsMock.mockReset();
+  });
+
+  it("resolves explicit session", async () => {
+    const result = await resolveSessionScope("work");
+    expect(result.session).toBe("work");
+  });
+
+  it("resolves session inside tmux", async () => {
+    tmuxExecMock.mockResolvedValue({ stdout: "dev\n", stderr: "", exitCode: 0 });
+    const result = await resolveSessionScope(undefined, { TMUX: "1" });
+    expect(result.session).toBe("dev");
+  });
+
+  it("requires explicit session when ambiguous", async () => {
+    tmuxExecMock.mockResolvedValue({
+      stdout: "a\nb\n",
+      stderr: "",
+      exitCode: 0
+    });
+    await expect(resolveSessionScope(undefined, {})).rejects.toThrow(
+      "default session is ambiguous"
+    );
+  });
+
+  it("chooses active window by default", async () => {
+    snapshotWindowsMock.mockResolvedValue(windows);
+    const result = await resolveWindowScope("dev");
+    expect(result.wid).toBe("@1");
+    expect(result.name).toBe("logs");
+  });
+});