tmux-ide 1.3.1 → 2.1.0

package/src/dispatch.ts

@@ -0,0 +1,102 @@
+import { resolve, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { loadMission, loadGoal, loadTask } from "./lib/task-store.ts";
+import { IdeError } from "./lib/errors.ts";
+
+interface DispatchOptions {
+  taskId: string;
+  json?: boolean;
+}
+
+/**
+ * Print task dispatch context to stdout so agents can read it directly.
+ *
+ * 1. If a dispatch file exists (.tasks/dispatch/{id}.md), print it.
+ * 2. Otherwise, build the context from the task store (mission + goal + task).
+ * 3. In JSON mode, output a structured object.
+ * 4. Always end with the completion command hint.
+ */
+export async function dispatch(
+  targetDir: string | null | undefined,
+  opts: DispatchOptions,
+): Promise<void> {
+  const dir = resolve(targetDir ?? ".");
+  const { taskId, json } = opts;
+
+  if (!taskId) {
+    throw new IdeError("Missing task ID. Usage: tmux-ide dispatch <id>", {
+      code: "USAGE",
+    });
+  }
+
+  // Try dispatch file first
+  const dispatchFile = join(dir, ".tasks", "dispatch", `${taskId}.md`);
+  const hasDispatchFile = existsSync(dispatchFile);
+
+  // Always load the task for structured data
+  const task = loadTask(dir, taskId);
+  if (!task && !hasDispatchFile) {
+    throw new IdeError(`Task "${taskId}" not found and no dispatch file exists`, {
+      code: "TASK_NOT_FOUND",
+    });
+  }
+
+  // Load mission and goal context
+  const mission = loadMission(dir);
+  const goal = task?.goal ? loadGoal(dir, task.goal) : null;
+
+  if (json) {
+    const prompt = hasDispatchFile ? readFileSync(dispatchFile, "utf-8") : buildPrompt(dir, task!);
+    const result: Record<string, unknown> = {
+      task: task ?? null,
+      mission: mission ?? null,
+      goal: goal ?? null,
+      prompt,
+    };
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  // Text mode: print the readable prompt
+  if (hasDispatchFile) {
+    const content = readFileSync(dispatchFile, "utf-8");
+    console.log(content);
+  } else {
+    console.log(buildPrompt(dir, task!));
+  }
+
+  // Always print the completion hint
+  console.log("");
+  console.log(`When done: tmux-ide task done ${taskId} --proof "what you did"`);
+}
+
+/**
+ * Build a human-readable prompt from the task store.
+ * Mirrors the logic of buildTaskPrompt() in orchestrator.ts but without
+ * requiring an orchestrator config.
+ */
+function buildPrompt(dir: string, task: NonNullable<ReturnType<typeof loadTask>>): string {
+  let prompt = "";
+
+  const mission = loadMission(dir);
+  if (mission) {
+    prompt += `Mission: ${mission.title}\n`;
+    if (mission.description) prompt += `${mission.description}\n`;
+    prompt += "\n";
+  }
+
+  if (task.goal) {
+    const goal = loadGoal(dir, task.goal);
+    if (goal) {
+      prompt += `Goal: ${goal.title}\n`;
+      if (goal.acceptance) prompt += `Acceptance: ${goal.acceptance}\n`;
+      prompt += "\n";
+    }
+  }
+
+  prompt += `Your Task: ${task.title}\n`;
+  if (task.description) prompt += `${task.description}\n`;
+  prompt += `\nPriority: P${task.priority}\n`;
+  if (task.tags?.length) prompt += `Tags: ${task.tags.join(", ")}\n`;
+  return prompt.trim();
+}

package/src/doctor.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, beforeEach, afterEach, expect } from "bun:test";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { doctor } from "./doctor.ts";
+
+let tmpDir: string;
+let origCwd: string;
+let origLog: typeof console.log;
+let logged: string[];
+let origExitCode: number | undefined;
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "tmux-ide-doctor-test-"));
+  origCwd = process.cwd();
+  logged = [];
+  origLog = console.log;
+  origExitCode = process.exitCode;
+  console.log = (...a: string[]) => logged.push(a.join(" "));
+});
+
+afterEach(() => {
+  process.chdir(origCwd);
+  console.log = origLog;
+  process.exitCode = origExitCode;
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("doctor", () => {
+  it("reports tmux installed check", async () => {
+    process.chdir(tmpDir);
+    writeFileSync(join(tmpDir, "ide.yml"), "name: test\nrows:\n  - panes:\n      - title: Shell\n");
+    await doctor({ json: true });
+    const output = JSON.parse(logged[0]);
+    const tmuxCheck = output.checks.find((c) => c.label === "tmux installed");
+    expect(tmuxCheck).toBeTruthy();
+    // tmux is installed in this CI/test environment, so it should pass
+    expect(tmuxCheck.pass).toBe(true);
+  });
+
+  it("reports tmux version check", async () => {
+    process.chdir(tmpDir);
+    writeFileSync(join(tmpDir, "ide.yml"), "name: test\nrows:\n  - panes:\n      - title: Shell\n");
+    await doctor({ json: true });
+    const output = JSON.parse(logged[0]);
+    const versionCheck = output.checks.find((c) => c.label.includes("tmux version"));
+    expect(versionCheck).toBeTruthy();
+  });
+
+  it("reports Node.js version check as passing", async () => {
+    process.chdir(tmpDir);
+    writeFileSync(join(tmpDir, "ide.yml"), "name: test\nrows:\n  - panes:\n      - title: Shell\n");
+    await doctor({ json: true });
+    const output = JSON.parse(logged[0]);
+    const nodeCheck = output.checks.find((c) => c.label.includes("Node.js"));
+    expect(nodeCheck).toBeTruthy();
+    expect(nodeCheck.pass).toBe(true);
+  });
+
+  it("reports ide.yml exists check as passing when present", async () => {
+    process.chdir(tmpDir);
+    writeFileSync(join(tmpDir, "ide.yml"), "name: test\nrows:\n  - panes:\n      - title: Shell\n");
+    await doctor({ json: true });
+    const output = JSON.parse(logged[0]);
+    const ideCheck = output.checks.find((c) => c.label.includes("ide.yml"));
+    expect(ideCheck).toBeTruthy();
+    expect(ideCheck.pass).toBe(true);
+  });
+
+  it("reports ide.yml exists check as failing when absent", async () => {
+    process.chdir(tmpDir);
+    // No ide.yml written
+    await doctor({ json: true });
+    const output = JSON.parse(logged[0]);
+    const ideCheck = output.checks.find((c) => c.label.includes("ide.yml"));
+    expect(ideCheck).toBeTruthy();
+    expect(ideCheck.pass).toBe(false);
+  });
+
+  it("marks agent teams check as optional", async () => {
+    process.chdir(tmpDir);
+    writeFileSync(join(tmpDir, "ide.yml"), "name: test\nrows:\n  - panes:\n      - title: Shell\n");
+    await doctor({ json: true });
+    const output = JSON.parse(logged[0]);
+    const teamsCheck = output.checks.find((c) => c.label.includes("agent teams"));
+    expect(teamsCheck).toBeTruthy();
+    expect(teamsCheck.optional).toBe(true);
+  });
+
+  it("optional checks don't fail the overall result", async () => {
+    process.chdir(tmpDir);
+    writeFileSync(join(tmpDir, "ide.yml"), "name: test\nrows:\n  - panes:\n      - title: Shell\n");
+    // Even if agent teams env var is not set, ok should still be true
+    const origEnv = process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
+    delete process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
+    try {
+      await doctor({ json: true });
+      const output = JSON.parse(logged[0]);
+      // ok depends on required checks, not optional ones
+      const requiredFailing = output.checks.filter((c) => !c.pass && !c.optional);
+      if (requiredFailing.length === 0) {
+        expect(output.ok).toBe(true);
+      }
+    } finally {
+      if (origEnv !== undefined) {
+        process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = origEnv;
+      }
+    }
+  });
+
+  it("prints human-readable output without --json", async () => {
+    process.chdir(tmpDir);
+    writeFileSync(join(tmpDir, "ide.yml"), "name: test\nrows:\n  - panes:\n      - title: Shell\n");
+    await doctor();
+    // Should have printed colored output with ✓ or ✗
+    expect(logged.length > 0).toBeTruthy();
+    expect(logged.some((l) => l.includes("tmux installed"))).toBeTruthy();
+  });
+});

package/src/doctor.ts

@@ -0,0 +1,167 @@
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { readConfig } from "./lib/yaml-io.ts";
+import { loadSkills } from "./lib/skill-registry.ts";
+
+interface CheckResult {
+  label: string;
+  pass: boolean;
+  detail: string;
+  optional: boolean;
+}
+
+function check(
+  label: string,
+  fn: () => string,
+  { optional = false }: { optional?: boolean } = {},
+): CheckResult {
+  try {
+    const result = fn();
+    return { label, pass: true, detail: result, optional };
+  } catch (e) {
+    return { label, pass: false, detail: (e as Error).message, optional };
+  }
+}
+
+export async function doctor({ json }: { json?: boolean } = {}): Promise<void> {
+  const checks: CheckResult[] = [];
+
+  checks.push(
+    check("tmux installed", () => {
+      execSync("which tmux", { stdio: "ignore" });
+      return "found";
+    }),
+  );
+
+  checks.push(
+    check("tmux version ≥ 3.0", () => {
+      const version = execSync("tmux -V", { encoding: "utf-8" }).trim();
+      const num = parseFloat(version.replace(/[^0-9.]/g, ""));
+      if (num < 3.0) throw new Error(`${version} (need ≥ 3.0)`);
+      return version;
+    }),
+  );
+
+  checks.push(
+    check("Node.js ≥ 18", () => {
+      const major = parseInt(process.versions.node.split(".")[0]!);
+      if (major < 18) throw new Error(`Node ${process.versions.node} (need ≥ 18)`);
+      return `v${process.versions.node}`;
+    }),
+  );
+
+  checks.push(
+    check(
+      "256-color terminal",
+      () => {
+        const term = process.env.TERM ?? "";
+        if (
+          !term.includes("256color") &&
+          !term.includes("ghostty") &&
+          !term.includes("kitty") &&
+          term !== "tmux-256color"
+        ) {
+          throw new Error(`$TERM is "${term}"`);
+        }
+        return term;
+      },
+      { optional: true },
+    ),
+  );
+
+  checks.push(
+    check("ide.yml exists", () => {
+      const path = resolve(".", "ide.yml");
+      if (!existsSync(path)) throw new Error("not found in current directory");
+      return "found";
+    }),
+  );
+
+  checks.push(
+    check(
+      "Claude Code agent teams",
+      () => {
+        if (process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS !== "1") {
+          throw new Error("not set (enable with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)");
+        }
+        return "enabled";
+      },
+      { optional: true },
+    ),
+  );
+
+  checks.push(
+    check(
+      "pane skill references",
+      () => {
+        const dir = resolve(".");
+        const { config } = readConfig(dir);
+        const skills = loadSkills(dir);
+        const skillNames = new Set(skills.map((s) => s.name));
+        const unresolved: string[] = [];
+        for (const row of config.rows) {
+          for (const pane of row.panes) {
+            if (pane.skill && !skillNames.has(pane.skill)) {
+              unresolved.push(`${pane.title ?? "untitled"} → ${pane.skill}`);
+            }
+          }
+        }
+        if (unresolved.length > 0) {
+          throw new Error(`${unresolved.length} unresolved: ${unresolved.join(", ")}`);
+        }
+        const count = config.rows.flatMap((r) => r.panes).filter((p) => p.skill).length;
+        return count > 0 ? `${count} reference(s), all resolved` : "no skill references";
+      },
+      { optional: true },
+    ),
+  );
+
+  checks.push(
+    check(
+      "tailscale CLI",
+      () => {
+        const version = execSync("tailscale version", { encoding: "utf-8" }).trim().split("\n")[0]!;
+        return version;
+      },
+      { optional: true },
+    ),
+  );
+
+  checks.push(
+    check(
+      "ngrok CLI",
+      () => {
+        const version = execSync("ngrok version", { encoding: "utf-8" }).trim();
+        return version;
+      },
+      { optional: true },
+    ),
+  );
+
+  checks.push(
+    check(
+      "cloudflared CLI",
+      () => {
+        const version = execSync("cloudflared --version", { encoding: "utf-8" }).trim();
+        return version;
+      },
+      { optional: true },
+    ),
+  );
+
+  const allPass = checks.every((c) => c.pass || c.optional);
+
+  if (json) {
+    console.log(JSON.stringify({ ok: allPass, checks }, null, 2));
+    return;
+  }
+
+  for (const c of checks) {
+    const icon = c.pass ? "✓" : c.optional ? "○" : "✗";
+    const color = c.pass ? "\x1b[32m" : c.optional ? "\x1b[33m" : "\x1b[31m";
+    console.log(`${color}${icon}\x1b[0m ${c.label} — ${c.detail}`);
+  }
+
+  if (!allPass) process.exitCode = 1;
+}

package/src/init.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, beforeEach, afterEach, expect } from "bun:test";
+import { mkdtempSync, writeFileSync, readFileSync, existsSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { init } from "./init.ts";
+
+let tmpDir;
+let origCwd;
+let origLog;
+let logged;
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "tmux-ide-init-test-"));
+  origCwd = process.cwd();
+  process.chdir(tmpDir);
+  logged = [];
+  origLog = console.log;
+  console.log = (...a) => logged.push(a.join(" "));
+});
+
+afterEach(() => {
+  process.chdir(origCwd);
+  console.log = origLog;
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("init", () => {
+  it("creates ide.yml from default template when no stack detected", async () => {
+    await init({ json: true });
+    expect(existsSync(join(tmpDir, "ide.yml"))).toBeTruthy();
+    const output = JSON.parse(logged[0]);
+    expect(output.created).toBe(true);
+    expect(output.template).toBe("default");
+  });
+
+  it("creates ide.yml from named template", async () => {
+    await init({ template: "nextjs", json: true });
+    expect(existsSync(join(tmpDir, "ide.yml"))).toBeTruthy();
+    const content = readFileSync(join(tmpDir, "ide.yml"), "utf-8");
+    expect(content.includes("rows")).toBeTruthy();
+    const output = JSON.parse(logged[0]);
+    expect(output.created).toBe(true);
+    expect(output.template).toBe("nextjs");
+  });
+
+  it("creates ide.yml from detected stack", async () => {
+    // Create a package.json with a Next.js dependency to trigger detection
+    writeFileSync(
+      join(tmpDir, "package.json"),
+      JSON.stringify({
+        name: "test-app",
+        dependencies: { next: "14.0.0" },
+        scripts: { dev: "next dev" },
+      }),
+    );
+    await init({ json: true });
+    expect(existsSync(join(tmpDir, "ide.yml"))).toBeTruthy();
+    const output = JSON.parse(logged[0]);
+    expect(output.created).toBe(true);
+    expect(output.detected.length > 0).toBeTruthy();
+  });
+
+  it("rejects when ide.yml already exists", async () => {
+    writeFileSync(join(tmpDir, "ide.yml"), "name: existing\n");
+    await expect(init({ json: true })).rejects.toThrow();
+  });
+
+  it("rejects unknown template name", async () => {
+    await expect(init({ template: "nonexistent-template-xyz", json: true })).rejects.toThrow();
+  });
+
+  it("replaces the name field with the directory basename", async () => {
+    await init({ template: "default", json: true });
+    const content = readFileSync(join(tmpDir, "ide.yml"), "utf-8");
+    const dirName = tmpDir.split("/").pop();
+    expect(content.includes(`name: ${dirName}`)).toBeTruthy();
+  });
+
+  it("prints human-readable output without --json", async () => {
+    await init();
+    expect(logged.some((l) => l.includes("Created ide.yml"))).toBeTruthy();
+  });
+
+  it("scaffolds missions skills, library, and AGENTS.md", async () => {
+    await init({ template: "missions", json: true });
+
+    expect(existsSync(join(tmpDir, ".tmux-ide", "skills", "frontend.md"))).toBeTruthy();
+    expect(existsSync(join(tmpDir, ".tmux-ide", "skills", "backend.md"))).toBeTruthy();
+    expect(existsSync(join(tmpDir, ".tmux-ide", "skills", "reviewer.md"))).toBeTruthy();
+    expect(existsSync(join(tmpDir, ".tmux-ide", "skills", "researcher.md"))).toBeTruthy();
+    expect(existsSync(join(tmpDir, ".tmux-ide", "library"))).toBeTruthy();
+    expect(existsSync(join(tmpDir, "AGENTS.md"))).toBeTruthy();
+    expect(readFileSync(join(tmpDir, "AGENTS.md"), "utf-8")).toContain(
+      `## Project: ${join(tmpDir).split("/").pop()}`,
+    );
+
+    const output = JSON.parse(logged[0]);
+    expect(output.template).toBe("missions");
+    expect(output.paths.some((path: string) => path.endsWith("frontend.md"))).toBeTruthy();
+  });
+});

package/src/init.ts

@@ -0,0 +1,144 @@
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  mkdirSync,
+  readdirSync,
+  copyFileSync,
+} from "node:fs";
+import { resolve, join, basename, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+import { detectStack, suggestConfig } from "./detect.ts";
+import { outputError, printLayout } from "./lib/output.ts";
+import type { IdeConfig } from "./types.ts";
+
+function copyTemplateSkills(targetDir: string): string[] {
+  const created: string[] = [];
+  const templateSkillsDir = resolve(__dirname, "..", "templates", "skills");
+  if (!existsSync(templateSkillsDir)) return created;
+
+  mkdirSync(targetDir, { recursive: true });
+  for (const file of readdirSync(templateSkillsDir)) {
+    if (!file.endsWith(".md")) continue;
+    const destination = join(targetDir, file);
+    copyFileSync(join(templateSkillsDir, file), destination);
+    created.push(destination);
+  }
+  return created;
+}
+
+function scaffoldMissionsWorkspace(dir: string, name: string): string[] {
+  const created: string[] = [];
+  const skillsDir = join(dir, ".tmux-ide", "skills");
+  created.push(...copyTemplateSkills(skillsDir));
+
+  const libraryDir = join(dir, ".tmux-ide", "library");
+  if (!existsSync(libraryDir)) {
+    mkdirSync(libraryDir, { recursive: true });
+    created.push(libraryDir);
+  }
+
+  const agentsTemplatePath = resolve(__dirname, "..", "templates", "AGENTS.md");
+  if (existsSync(agentsTemplatePath)) {
+    const agentsPath = join(dir, "AGENTS.md");
+    const content = readFileSync(agentsTemplatePath, "utf-8").replace(/{{name}}/g, name);
+    writeFileSync(agentsPath, content);
+    created.push(agentsPath);
+  }
+
+  return created;
+}
+
+export async function init({
+  template,
+  json,
+}: { template?: string; json?: boolean } = {}): Promise<void> {
+  const dir = process.cwd();
+  const configPath = resolve(dir, "ide.yml");
+
+  if (existsSync(configPath)) {
+    outputError("ide.yml already exists in this directory", "EXISTS");
+  }
+
+  // If a specific template is requested, use it
+  if (template) {
+    const templatePath = resolve(__dirname, "..", "templates", `${template}.yml`);
+    if (!existsSync(templatePath)) {
+      outputError(`Template "${template}" not found`, "NOT_FOUND");
+    }
+
+    let content = readFileSync(templatePath, "utf-8");
+    const name = basename(dir);
+    content = content.replace(/^name: .+/m, `name: ${name}`);
+    const tmpPath = configPath + ".tmp";
+    writeFileSync(tmpPath, content);
+    renameSync(tmpPath, configPath);
+    const created =
+      template === "missions"
+        ? scaffoldMissionsWorkspace(dir, name)
+        : copyTemplateSkills(join(dir, ".tmux-ide", "skills"));
+
+    if (json) {
+      console.log(JSON.stringify({ created: true, template, name, paths: created }));
+    } else {
+      console.log(`Created ide.yml from "${template}" template for "${name}"`);
+      const yaml = (await import("js-yaml")).default;
+      printLayout(yaml.load(content) as IdeConfig);
+      for (const createdPath of created) {
+        console.log(`Created ${createdPath.replace(dir + "/", "")}`);
+      }
+    }
+    return;
+  }
+
+  // Smart detection
+  const detected = detectStack(dir);
+  const name = basename(dir);
+
+  if (detected.frameworks.length > 0) {
+    // Use detected stack to generate config
+    const config = suggestConfig(dir, detected);
+    const yaml = (await import("js-yaml")).default;
+    const tmpPath2 = configPath + ".tmp";
+    writeFileSync(tmpPath2, yaml.dump(config, { lineWidth: -1, noRefs: true, quotingType: '"' }));
+    renameSync(tmpPath2, configPath);
+
+    const desc = detected.frameworks.join(" + ");
+    if (json) {
+      console.log(JSON.stringify({ created: true, detected: detected.frameworks, name }));
+    } else {
+      console.log(`Detected ${desc}. Created ide.yml for "${name}".`);
+      printLayout(config);
+      console.log("Edit it to customize, then run: tmux-ide");
+    }
+  } else {
+    // Fallback to default template
+    const templatePath = resolve(__dirname, "..", "templates", "default.yml");
+    let content = readFileSync(templatePath, "utf-8");
+    content = content.replace(/^name: .+/m, `name: ${name}`);
+    const tmpPath3 = configPath + ".tmp";
+    writeFileSync(tmpPath3, content);
+    renameSync(tmpPath3, configPath);
+
+    if (json) {
+      console.log(JSON.stringify({ created: true, template: "default", name }));
+    } else {
+      console.log(`Created ide.yml for "${name}"`);
+      const yaml = (await import("js-yaml")).default;
+      printLayout(yaml.load(content) as IdeConfig);
+      console.log("Edit it to configure your workspace, then run: tmux-ide");
+    }
+  }
+
+  // Copy built-in skills if .tmux-ide/skills/ doesn't exist
+  const skillsDir = join(dir, ".tmux-ide", "skills");
+  if (!existsSync(skillsDir)) {
+    const created = copyTemplateSkills(skillsDir);
+    if (created.length > 0 && !json) {
+      console.log("Copied built-in skill templates to .tmux-ide/skills/");
+    }
+  }
+}

package/src/inspect.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from "bun:test";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cli = join(__dirname, "..", "bin", "cli.js");
+
+function makeProject(config = "name: inspect-session\nrows:\n  - panes:\n      - title: Shell\n") {
+  const dir = mkdtempSync(join(tmpdir(), "tmux-ide-inspect-test-"));
+  writeFileSync(join(dir, "ide.yml"), config);
+  return dir;
+}
+
+function runCli(args, cwd) {
+  return spawnSync("node", [cli, ...args], {
+    cwd,
+    encoding: "utf-8",
+  });
+}
+
+describe("inspect command", () => {
+  it("prints resolved config state as json", () => {
+    const dir = makeProject(
+      "name: inspect-session\nrows:\n  - size: 70%\n    panes:\n      - title: Claude\n        command: claude\n        focus: true\n      - title: Shell\n",
+    );
+
+    try {
+      const result = runCli(["inspect", "--json"], dir);
+
+      expect(result.status).toBe(0);
+      const payload = JSON.parse(result.stdout);
+      expect(payload.session).toBe("inspect-session");
+      expect(payload.valid).toBe(true);
+      expect(payload.summary.rows).toBe(1);
+      expect(payload.summary.panes).toBe(2);
+      expect(payload.summary.focus).toBe("rows.0.panes.0");
+      expect(payload.tmux.running).toBe(false);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("reports validation errors for invalid pane arrays instead of crashing", () => {
+    const dir = makeProject("name: inspect-session\nrows:\n  - panes: nope\n");
+
+    try {
+      const result = runCli(["inspect", "--json"], dir);
+
+      expect(result.status).toBe(0);
+      const payload = JSON.parse(result.stdout);
+      expect(payload.valid).toBe(false);
+      expect(JSON.stringify(payload.errors)).toMatch(/rows\[0\]\.panes must be an array/);
+      expect(payload.rows).toEqual([
+        {
+          index: 0,
+          size: null,
+          panes: [],
+        },
+      ]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});