tmux-ide 2.6.1 → 2.7.0

package/packages/daemon/src/tui/team/sessions.ts

@@ -14,10 +14,11 @@ import { execFileSync } from "node:child_process";
 import {
   classifyInstant,
   parseAuthority,
+  parseAuthorityEpoch,
   type AgentStatus,
   type StatusTracker,
 } from "../detect/classify.ts";
-import type { AgentManifest } from "../detect/manifest.ts";
+import type { AgentManifest, ManifestConfidence } from "../detect/manifest.ts";
 import { readProcessTable, resolveAgentCommand } from "../detect/process-tree.ts";
 import { readPaneSnapshot } from "../detect/snapshot.ts";
 
@@ -33,6 +34,80 @@ export interface TeamSession {
    * this is the richer breakdown the switcher/cockpit navigate.
    */
   windowList: TeamWindow[];
+  /**
+   * Per-pane agent detail — one entry for every pane the two-layer detection
+   * classifies as an agent (a manifest resolved and it isn't the `shell`
+   * catch-all). A FLAT list across the session's windows; each entry carries
+   * its own `windowIndex`, so a consumer that wants a per-window view groups by
+   * it. ADDITIVE: the rollup fields above (`status`, `windowList`, `panes`) are
+   * unchanged — this only SURFACES per-pane truth the rollup already computes.
+   * Optional so pre-existing constructors stay valid; {@link listTeamSessions}
+   * always populates it (possibly empty).
+   */
+  agents?: PaneAgentEntry[];
+}
+
+/**
+ * Per-pane agent detail surfaced alongside a session's rollup. Emitted only for
+ * panes that resolve to a real agent (a manifest, excluding the `shell`
+ * catch-all). Everything here is already computed during the status rollup —
+ * this record just keeps it instead of discarding it.
+ */
+export interface PaneAgentEntry {
+  /** tmux pane id, e.g. `%5`. */
+  paneId: string;
+  /** `window_index` of the window (tab) this pane lives in. */
+  windowIndex: number;
+  /** Owning session name (repeated per entry so a flattened list stays keyed). */
+  session: string;
+  /** The resolved agent kind — the manifest id (`claude`, `codex`, …). */
+  kind: string;
+  /** Final per-pane status (authority when fresh, else scraped/tracked). */
+  state: AgentStatus;
+  /** The manifest's evidence confidence (`conservative` when the manifest omits it). */
+  confidence: ManifestConfidence;
+  /**
+   * The authority state's epoch stamp when the AUTHORITY layer provided the
+   * state (`@agent_state` = `"<state>:<epoch>"`); null for a scraped/tracked
+   * pane, which has no authoritative timestamp.
+   */
+  since: number | null;
+  /** `pane_title`. */
+  title: string;
+  /** `pane_current_command` — the pane's immediate process (often node/bun/sh). */
+  command: string;
+  /** `pane_current_path` — the pane's working directory. */
+  dir: string;
+}
+
+/**
+ * Build a {@link PaneAgentEntry} from a classified pane — PURE. Returns null
+ * for a NON-agent pane (no manifest resolved, or the `shell` catch-all), which
+ * gets no entry. `since` is threaded from the caller (the authority epoch when
+ * the authority layer supplied the state, else null). No tmux/`ps` access —
+ * every input is already resolved by the rollup.
+ */
+export function buildAgentEntry(input: {
+  sessionName: string;
+  pane: Pick<PaneRecord, "id" | "windowIndex" | "title" | "cmd" | "dir">;
+  manifest: AgentManifest | undefined;
+  state: AgentStatus;
+  since: number | null;
+}): PaneAgentEntry | null {
+  const { manifest, pane } = input;
+  if (!manifest || manifest.id === "shell") return null;
+  return {
+    paneId: pane.id,
+    windowIndex: pane.windowIndex,
+    session: input.sessionName,
+    kind: manifest.id,
+    state: input.state,
+    confidence: manifest.confidence ?? "conservative",
+    since: input.since,
+    title: pane.title,
+    command: pane.cmd,
+    dir: pane.dir,
+  };
 }
 
 /**
@@ -74,6 +149,8 @@ interface PaneRecord {
   cmd: string;
   /** `pane_title`. */
   title: string;
+  /** `pane_current_path` — the pane's working directory. */
+  dir: string;
   /** Raw `@agent_state` pane option (authority layer), if set. */
   authority: string;
   /** Raw `@agent_hint` pane option — forces a manifest when set. */
@@ -177,16 +254,21 @@ export function listTeamSessions(
       const seen = opts.viewed === name;
 
       const nowSec = Math.floor(Date.now() / 1000);
-      const wantPane = typeof opts.onPane === "function";
+      const agents: PaneAgentEntry[] = [];
       const statuses = panes.map((pane) => {
         // AUTHORITY first: a fresh hook-reported state outranks scraping.
         const authority = parseAuthority(pane.authority, nowSec);
         let status: AgentStatus;
-        // The manifest is resolved in the fallback anyway; for authority panes
-        // we only resolve it (cheaply — the process table is already loaded, no
-        // capture) when a pane sink wants the agent name for a chip.
+        // The agent kind is needed for BOTH the chip (onPane) and the per-pane
+        // agent entry, so the manifest is resolved for every pane. It's cheap —
+        // the process table is already loaded, and authority panes take NO
+        // capture-pane round-trip.
         let manifest: AgentManifest | undefined;
+        // The authority state's own timestamp (its "since"); only fresh
+        // authority states carry one — scraped panes have no stamp.
+        let since: number | null = null;
         if (authority !== null) {
+          since = parseAuthorityEpoch(pane.authority);
           if (authority === "done" && seen) {
             // Viewing acknowledges a finished agent — persist the ack so the
             // pane doesn't flip back to done on the next tick.
@@ -195,11 +277,9 @@ export function listTeamSessions(
           } else {
             status = authority;
           }
-          if (wantPane) {
-            manifest = resolveAgentCommand(pane.cmd, pane.pid, processTable, {
-              hint: pane.hint,
-            }).manifest;
-          }
+          manifest = resolveAgentCommand(pane.cmd, pane.pid, processTable, {
+            hint: pane.hint,
+          }).manifest;
         } else {
           // FALLBACK: snapshot scraping. Resolve the real agent from the pane's
           // process tree (pane_current_command alone is usually just node/bun/sh).
@@ -221,6 +301,10 @@ export function listTeamSessions(
           agent: manifest && manifest.id !== "shell" ? manifest.id : null,
           status,
         });
+        // Surface per-pane agent detail (same resolved manifest/status — nothing
+        // re-derived). Non-agent panes yield null and are skipped.
+        const entry = buildAgentEntry({ sessionName: name, pane, manifest, state: status, since });
+        if (entry) agents.push(entry);
         return status;
       });
 
@@ -233,6 +317,7 @@ export function listTeamSessions(
         // `panes` and `statuses` are parallel (statuses = panes.map(...)), so
         // the pure rollup can group each pane's window with its resolved status.
         windowList: rollupWindows(panes, statuses),
+        agents,
       };
     });
 }
@@ -243,9 +328,11 @@ function collectPanes(): Map<string, PaneRecord[]> {
     "list-panes",
     "-a",
     "-F",
-    // Window fields sit before pane_title so the (tab-safe) title stays the
-    // trailing catch-all — window names don't contain tabs in practice.
-    `#{session_name}\t#{pane_id}\t#{pane_pid}\t#{pane_current_command}\t#{@agent_state}\t#{@agent_hint}\t#{${SIDEBAR_PANE_OPTION}}\t#{window_index}\t#{window_name}\t#{window_active}\t#{pane_title}`,
+    // Window fields + pane_current_path sit before pane_title so the (tab-safe)
+    // title stays the trailing catch-all — window names/paths don't contain tabs
+    // in practice. pane_current_path rides this SAME list-panes call (no extra
+    // tmux round-trip) so per-pane agent entries can carry a working dir.
+    `#{session_name}\t#{pane_id}\t#{pane_pid}\t#{pane_current_command}\t#{@agent_state}\t#{@agent_hint}\t#{${SIDEBAR_PANE_OPTION}}\t#{window_index}\t#{window_name}\t#{window_active}\t#{pane_current_path}\t#{pane_title}`,
   ]);
   const bySession = new Map<string, PaneRecord[]>();
   for (const line of raw.split("\n").filter(Boolean)) {
@@ -260,6 +347,7 @@ function collectPanes(): Map<string, PaneRecord[]> {
       windowIndex = "0",
       windowName = "",
       windowActive = "0",
+      dir = "",
       ...titleParts
     ] = line.split("\t");
     if (!session) continue;
@@ -274,6 +362,7 @@ function collectPanes(): Map<string, PaneRecord[]> {
       windowIndex: Number(windowIndex) || 0,
       windowName,
       windowActive: windowActive === "1",
+      dir,
       title: titleParts.join("\t"),
     });
     bySession.set(session, list);

package/scripts/build-tui.mjs

@@ -16,7 +16,9 @@
  * node-only for CI) — run `pnpm build:tui` on a machine with bun.
  *
  * Cross-compile: pass `--target bun-<os>-<arch>` (e.g. bun-linux-x64) to build
- * for another platform. Defaults to the host target.
+ * for another platform. Defaults to the host target. Pass `--outfile <path>` to
+ * write somewhere other than the default dist path (the release workflow uses
+ * this to emit per-platform artifacts side by side).
  */
 
 import { createSolidTransformPlugin } from "@opentui/solid/bun-plugin";
@@ -27,8 +29,7 @@ import { fileURLToPath } from "node:url";
 const here = dirname(fileURLToPath(import.meta.url));
 const repoRoot = resolve(here, "..");
 const entry = resolve(repoRoot, "packages/daemon/src/tui/main.ts");
-const outDir = resolve(repoRoot, "packages/daemon/dist/tui");
-const outfile = resolve(outDir, "tmux-ide-tui");
+const defaultOutDir = resolve(repoRoot, "packages/daemon/dist/tui");
 
 if (!existsSync(entry)) {
   throw new Error(`[build-tui] entry not found: ${entry}`);
@@ -38,7 +39,13 @@ const targetArg = process.argv.indexOf("--target");
 const target =
   targetArg !== -1 ? process.argv[targetArg + 1] : `bun-${process.platform}-${process.arch}`;
 
-mkdirSync(outDir, { recursive: true });
+const outfileArg = process.argv.indexOf("--outfile");
+const outfile =
+  outfileArg !== -1
+    ? resolve(process.argv[outfileArg + 1])
+    : resolve(defaultOutDir, "tmux-ide-tui");
+
+mkdirSync(dirname(outfile), { recursive: true });
 
 const start = Date.now();
 const result = await Bun.build({

package/scripts/perf-mirror.mjs

@@ -0,0 +1,313 @@
+#!/usr/bin/env bun
+/**
+ * perf-mirror — the M21 baseline harness.
+ *
+ * Drives the real unified app (`tmux-ide app`) against a scripted tmux session
+ * on the default socket, exercising the three mirror-pipeline taps that gate
+ * behind TMUX_IDE_ZZ_PERF, then prints a p50/p95 table for:
+ *   - feed-parse   ms per stdout chunk   (/tmp/zz-feed.log,  control-client)
+ *   - snapshot     ms per 8ms paint tick (/tmp/zz-perf.log,  app.tsx)
+ *   - input-echo   ms keystroke→echo→paint (/tmp/zz-input.log, perf-tap)
+ * across three scenarios: IDLE, FLOOD (scrolling), ALT (alt-screen redraw).
+ *
+ * Everything it creates is `zz-perf-*` on the default socket and is killed on
+ * exit (success OR failure). It NEVER touches any other session. Run it from
+ * the repo root:  bun scripts/perf-mirror.mjs
+ *
+ * Env knobs (all optional): PERF_FLOOD_MS, PERF_ALT_MS, PERF_IDLE_MS,
+ * PERF_KEYS (input samples), PERF_KEY_GAP_MS, PERF_WARMUP_MS.
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import os from "node:os";
+import { summarize } from "../packages/daemon/src/tui/mirror/perf-tap.ts";
+
+const REPO = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const APP = "packages/daemon/src/tui/mirror/app.tsx";
+const TARGET = "zz-perf-target";
+const HOST = "zz-perf-host";
+const FEED_LOG = "/tmp/zz-feed.log";
+const SNAP_LOG = "/tmp/zz-perf.log";
+const INPUT_LOG = "/tmp/zz-input.log";
+
+const cfg = {
+  floodMs: num(process.env.PERF_FLOOD_MS, 6000),
+  altMs: num(process.env.PERF_ALT_MS, 6000),
+  idleMs: num(process.env.PERF_IDLE_MS, 4000),
+  keys: num(process.env.PERF_KEYS, 50),
+  keyGapMs: num(process.env.PERF_KEY_GAP_MS, 90),
+  warmupMs: num(process.env.PERF_WARMUP_MS, 5000),
+};
+
+function num(v, d) {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : d;
+}
+
+/** tmux on the DEFAULT socket, un-nested (TMUX/TMUX_TMPDIR cleared) — the socket
+ *  the app's control client attaches to and where the user's real sessions live.
+ *  We only ever name zz-perf-* targets. */
+function tmux(args, opts = {}) {
+  return execFileSync("tmux", args, {
+    env: { ...process.env, TMUX: "", TMUX_TMPDIR: "" },
+    encoding: "utf8",
+    stdio: opts.inherit ? "inherit" : ["ignore", "pipe", "pipe"],
+    ...opts,
+  });
+}
+function tmuxQuiet(args) {
+  try {
+    return tmux(args);
+  } catch {
+    return "";
+  }
+}
+function sessionExists(name) {
+  try {
+    tmux(["has-session", "-t", name]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const truncate = (p) => writeFileSync(p, "");
+function readCol(path, col) {
+  if (!existsSync(path)) return [];
+  return readFileSync(path, "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .map((l) => Number(l.trim().split(/\s+/)[col]))
+    .filter((n) => Number.isFinite(n));
+}
+
+// ── keystroke / flood injection ─────────────────────────────────────────────
+
+/** Type into the HOST (the app), which forwards to the focused target pane. */
+const sendHostKey = (key) => tmuxQuiet(["send-keys", "-t", HOST, key]);
+const sendHostChar = (ch) => tmuxQuiet(["send-keys", "-t", HOST, "-l", ch]);
+/** Run a command directly in the TARGET pane (bypasses the app — pure output). */
+function runInTarget(line) {
+  tmuxQuiet(["send-keys", "-t", TARGET, "-l", line]);
+  tmuxQuiet(["send-keys", "-t", TARGET, "Enter"]);
+}
+/** Interrupt whatever the target pane is running, back to a clean prompt. */
+function calmTarget() {
+  tmuxQuiet(["send-keys", "-t", TARGET, "C-c"]);
+  tmuxQuiet(["send-keys", "-t", TARGET, "-l", "printf '\\033[?1049l'"]);
+  tmuxQuiet(["send-keys", "-t", TARGET, "Enter"]);
+  tmuxQuiet(["send-keys", "-t", TARGET, "-l", "clear"]);
+  tmuxQuiet(["send-keys", "-t", TARGET, "Enter"]);
+}
+
+// ── lifecycle ───────────────────────────────────────────────────────────────
+
+function cleanup() {
+  for (const s of [HOST, TARGET]) {
+    if (sessionExists(s)) tmuxQuiet(["kill-session", "-t", s]);
+  }
+}
+
+async function setup() {
+  cleanup(); // clear any leftovers from a crashed prior run
+  truncate(FEED_LOG);
+  truncate(SNAP_LOG);
+  truncate(INPUT_LOG);
+
+  // Target: a plain shell on the default socket. The app mirrors this session;
+  // its control client (`tmux -C attach`, TMUX="") reaches the default socket.
+  tmux(["new-session", "-d", "-s", TARGET, "-x", "200", "-y", "50"]);
+  // A generous host so the app has room and never wraps the flood oddly.
+  tmux([
+    "new-session",
+    "-d",
+    "-s",
+    HOST,
+    "-x",
+    "220",
+    "-y",
+    "60",
+    // Forward TMUX_IDE_FB_PANES verbatim so the default incremental blit path
+    // (M21.4) and the `=0` StyledRun kill switch can be measured on the same
+    // harness/taps. Unset → the app's default (blit).
+    `cd ${REPO} && TMUX_IDE_ZZ_PERF=1 ${process.env.TMUX_IDE_FB_PANES !== undefined ? `TMUX_IDE_FB_PANES=${process.env.TMUX_IDE_FB_PANES} ` : ""}exec bun ${APP} --target=${TARGET}`,
+  ]);
+
+  process.stdout.write(`  warming up (${cfg.warmupMs}ms) — app attaching + seeding…\n`);
+  await sleep(cfg.warmupMs);
+  sendHostKey("F2"); // force the Terminal surface (pane-forward keyboard path)
+  await sleep(400);
+}
+
+/** Assert the mirror is actually live: a brief flood must grow the feed log. */
+async function assertLive() {
+  truncate(FEED_LOG);
+  runInTarget("for i in 1 2 3 4 5; do echo probe-$i; done");
+  await sleep(800);
+  const n = readCol(FEED_LOG, 1).length;
+  if (n === 0) {
+    const pane = tmuxQuiet(["capture-pane", "-t", HOST, "-p"]).slice(0, 800);
+    throw new Error(
+      `mirror never went live — no %output feed after a probe.\n--- host pane ---\n${pane}`,
+    );
+  }
+  calmTarget();
+  await sleep(500);
+}
+
+// ── scenarios ────────────────────────────────────────────────────────────────
+
+/** Idle: quiet pane; capture the low-water feed/snapshot floor. */
+async function scenarioIdle() {
+  calmTarget();
+  await sleep(600);
+  truncate(FEED_LOG);
+  truncate(SNAP_LOG);
+  await sleep(cfg.idleMs);
+  return { feed: readCol(FEED_LOG, 1), snap: readCol(SNAP_LOG, 0) };
+}
+
+/** Flood: a steady stream of new lines (scrollback growth + re-snapshot). */
+async function scenarioFlood() {
+  calmTarget();
+  await sleep(500);
+  truncate(FEED_LOG);
+  truncate(SNAP_LOG);
+  // ~200 lines/sec — a busy build/test log, not a fork bomb.
+  runInTarget(
+    'i=0; while true; do echo "flood line $i $(date +%s%N)"; i=$((i+1)); sleep 0.005; done',
+  );
+  await sleep(cfg.floodMs);
+  const out = { feed: readCol(FEED_LOG, 1), snap: readCol(SNAP_LOG, 0) };
+  calmTarget();
+  await sleep(500);
+  return out;
+}
+
+/** Alt-screen: an app that repaints in place (cursor addressing, no scrollback). */
+async function scenarioAlt() {
+  calmTarget();
+  await sleep(500);
+  truncate(FEED_LOG);
+  truncate(SNAP_LOG);
+  runInTarget(
+    "printf '\\033[?1049h'; while true; do printf '\\033[H\\033[2J'; date +%s.%N; seq 1 30; sleep 0.05; done",
+  );
+  await sleep(cfg.altMs);
+  const out = { feed: readCol(FEED_LOG, 1), snap: readCol(SNAP_LOG, 0) };
+  calmTarget();
+  await sleep(500);
+  return out;
+}
+
+/** Input latency: type single chars into the app at a shell prompt; each echoes. */
+async function scenarioInput() {
+  calmTarget();
+  await sleep(600);
+  truncate(INPUT_LOG);
+  const glyphs = "abcdefghijklmnopqrstuvwxyz0123456789";
+  for (let k = 0; k < cfg.keys; k++) {
+    sendHostChar(glyphs[k % glyphs.length]);
+    await sleep(cfg.keyGapMs);
+  }
+  await sleep(400);
+  const out = { echo: readCol(INPUT_LOG, 1), paint: readCol(INPUT_LOG, 2) };
+  // Drop the half-typed line by interrupting the TARGET pane directly. NEVER
+  // send C-c to the host: the app exits on ctrl-c, which would kill the mirror
+  // and silence every later scenario.
+  tmuxQuiet(["send-keys", "-t", TARGET, "C-c"]);
+  return out;
+}
+
+// ── reporting ────────────────────────────────────────────────────────────────
+
+function fmt(n) {
+  return n.toFixed(2).padStart(8);
+}
+function row(label, s) {
+  return `  ${label.padEnd(26)} ${String(s.count).padStart(6)} ${fmt(s.p50)} ${fmt(s.p95)} ${fmt(s.max)} ${fmt(s.mean)}`;
+}
+function table(rows) {
+  const head = `  ${"metric".padEnd(26)} ${"n".padStart(6)} ${"p50".padStart(8)} ${"p95".padStart(8)} ${"max".padStart(8)} ${"mean".padStart(8)}`;
+  return [head, "  " + "-".repeat(head.length - 2), ...rows].join("\n");
+}
+
+function machineInfo() {
+  const cpu = os.cpus()[0]?.model ?? "unknown";
+  let tmuxV = "unknown";
+  try {
+    tmuxV = tmux(["-V"]).trim();
+  } catch {
+    /* ignore */
+  }
+  let opentui = "unknown";
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(REPO, "packages/daemon/package.json"), "utf8"));
+    opentui =
+      pkg.dependencies?.["@opentui/core"] ?? pkg.dependencies?.["@opentui/solid"] ?? "unknown";
+  } catch {
+    /* ignore */
+  }
+  return {
+    date: new Date().toISOString(),
+    platform: `${os.platform()} ${os.release()} (${os.arch()})`,
+    cpu: `${cpu} × ${os.cpus().length}`,
+    mem: `${(os.totalmem() / 1024 ** 3).toFixed(0)} GB`,
+    bun: process.versions.bun ?? "n/a",
+    node: process.versions.node,
+    tmux: tmuxV,
+    opentui,
+  };
+}
+
+async function main() {
+  const info = machineInfo();
+  process.stdout.write("perf-mirror — M21 baseline harness\n");
+  process.stdout.write(
+    `  ${info.platform} · ${info.cpu} · bun ${info.bun} · ${info.tmux} · @opentui ${info.opentui}\n\n`,
+  );
+
+  await setup();
+  await assertLive();
+
+  process.stdout.write("  running IDLE…\n");
+  const idle = await scenarioIdle();
+  process.stdout.write("  running INPUT…\n");
+  const input = await scenarioInput();
+  process.stdout.write("  running FLOOD…\n");
+  const flood = await scenarioFlood();
+  process.stdout.write("  running ALT-SCREEN…\n\n");
+  const alt = await scenarioAlt();
+
+  const rows = [
+    row("feed-parse ms/chunk [idle]", summarize(idle.feed)),
+    row("feed-parse ms/chunk [flood]", summarize(flood.feed)),
+    row("feed-parse ms/chunk [alt]", summarize(alt.feed)),
+    row("snapshot ms/tick [idle]", summarize(idle.snap)),
+    row("snapshot ms/tick [flood]", summarize(flood.snap)),
+    row("snapshot ms/tick [alt]", summarize(alt.snap)),
+    row("input echo ms (t1-t0)", summarize(input.echo)),
+    row("input paint ms (t2-t0)", summarize(input.paint)),
+  ];
+  process.stdout.write(table(rows) + "\n");
+
+  return { info, rows };
+}
+
+let exitCode = 0;
+try {
+  await main();
+} catch (err) {
+  exitCode = 1;
+  process.stderr.write(`\nperf-mirror FAILED: ${err?.stack ?? err}\n`);
+} finally {
+  cleanup();
+  // Best-effort confirmation the zz-perf-* sessions are gone.
+  const leftover = [HOST, TARGET].filter(sessionExists);
+  if (leftover.length)
+    process.stderr.write(`  WARNING leftover sessions: ${leftover.join(", ")}\n`);
+  else process.stdout.write("\n  cleanup: zz-perf-* sessions removed.\n");
+}
+process.exit(exitCode);

package/skill/SKILL.md

@@ -123,6 +123,28 @@ One interaction grammar everywhere: `j`/`k` move, `enter` opens, `/` filters,
 `esc` backs out, `?` asks. Bare `tmux-ide` with no `ide.yml` opens the **home
 cockpit** (the fleet home screen). `tmux-ide cheatsheet` prints the full sheet.
 
+## The app — `tmux-ide app` (the terminal IDE)
+
+v2.7 adds a full-screen unified app: tmux stays the engine (PTYs, agents,
+persistence); the app is the IDE around it. Launch `tmux-ide app` (bare = home
+screen) or `tmux-ide app <session>`. Needs `bun`, or a downloaded binary:
+`tmux-ide update --tui-binary`.
+
+- **Tabs** `F1`–`F4`: Home (fleet, pick a session = set the workspace) ·
+  Terminal (the session mirrored live — it keeps streaming while you're on
+  other tabs) · Files (tree + built-in editor: `^s` save, `^z` undo, click to
+  place the cursor) · Diff (colored working-tree changes, `^e` opens the file
+  in the editor). `F5` = command palette (fuzzy everything).
+- **Mouse-native**: hover highlights; right-click = context menus (split/zoom/
+  kill panes, layouts, synchronize-panes, kill/rename sessions & windows —
+  destructive actions confirm); drag pane borders to resize; drag-select text →
+  clipboard via OSC52 (works through ssh); scrollbars; clickable buttons.
+- **tmux parity**: `[⛶]` zoom, window verbs, layout presets, `/` scrollback
+  search with `n`/`N`, paste-buffer picker. `^q` quits — the session is
+  untouched, like you were never there.
+- State persists across launches (~/.tmux-ide/app-state.json): last tab,
+  session, open file.
+
 ## ide.yml (optional)
 
 Adopt works on any session. If you'd rather have tmux-ide build the layout, describe

package/templates/AGENTS.md

@@ -5,16 +5,23 @@
 ## Boundaries
 
 - Stay within the scope of your assigned task
-- Report out-of-scope issues via --discovered-issues
+- Surface out-of-scope issues to the lead instead of silently expanding scope
 - Do not modify files outside your task scope without coordination
 
 ## Conventions
 
-- Run tests before marking tasks done
-- Use the project existing code style
-- Commit messages should reference the task ID
+- Run tests before reporting your work done
+- Use the project's existing code style
+- Reference the task or branch in commit messages
 
-## Completion Protocol
+## Status & Reporting
 
-- tmux-ide task done <ID> --proof "summary" --summary "key learnings"
-- Report issues: include --discovered-issues for anything out of scope
+Report your state so the fleet tabs show ground truth. Claude Code does this
+automatically once `tmux-ide integration install claude` is run; any agent can
+self-report the same way:
+
+    tmux set-option -p @agent_state "working:$(date +%s)"   # working|blocked|done|idle
+
+Coordinate with the lead or a teammate pane:
+
+    tmux-ide send <session-or-pane> "what changed, how you verified it, follow-ups"

package/templates/agent-team-monorepo.yml

@@ -1,8 +1,16 @@
 name: my-monorepo
 
+# Ground-truth agent status (working/blocked/done glyphs on the fleet tabs)
+# comes from Claude Code's lifecycle hooks. Wire them once with:
+#   tmux-ide integration install claude
+
 team:
   name: my-monorepo
 
+sidebar: true # fleet nav column — jump between agents (toggle: prefix b)
+
+before: pnpm install
+
 rows:
   - size: 70%
     panes:

package/templates/agent-team-nextjs.yml

@@ -1,8 +1,14 @@
 name: my-app
 
+# Ground-truth agent status (working/blocked/done glyphs on the fleet tabs)
+# comes from Claude Code's lifecycle hooks. Wire them once with:
+#   tmux-ide integration install claude
+
 team:
   name: my-app
 
+sidebar: true # fleet nav column — jump between agents (toggle: prefix b)
+
 before: pnpm install
 
 rows:
@@ -24,4 +30,6 @@ rows:
   - panes:
       - title: Next.js
         command: pnpm dev
+      - title: Changes
+        type: changes # live git changes widget
       - title: Shell

package/templates/agent-team.yml

@@ -1,8 +1,16 @@
 name: my-project
 
+# Ground-truth agent status (working/blocked/done glyphs on the fleet tabs)
+# comes from Claude Code's lifecycle hooks. Wire them once with:
+#   tmux-ide integration install claude
+
 team:
   name: my-project
 
+sidebar: true # fleet nav column — jump between agents (toggle: prefix b)
+
+# before: npm install
+
 rows:
   - size: 70%
     panes:
@@ -18,6 +26,8 @@ rows:
         role: teammate
 
   - panes:
+      - title: Changes
+        type: changes # live git changes widget
       - title: Dev Server
         # command: npm run dev
       - title: Shell

package/templates/convex.yml

@@ -1,5 +1,7 @@
 name: my-app
 
+before: pnpm install
+
 rows:
   - size: 70%
     panes: