tmux-ide 2.6.1 → 2.8.0

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/scripts/postinstall.js

@@ -91,7 +91,14 @@ const nextSettings = {
   },
 };
 
-writeFileSync(settingsPath, `${JSON.stringify(nextSettings, null, 2)}\n`);
+try {
+  writeFileSync(settingsPath, `${JSON.stringify(nextSettings, null, 2)}\n`);
+} catch (error) {
+  // Best-effort like everything above: sandboxed installs (e.g. a package
+  // manager building in a $HOME-restricted sandbox) may deny this write —
+  // that must never fail the install itself.
+  console.warn(`[tmux-ide] Skipping Claude settings update: ${error.message}`);
+}
 
 function shouldInstallClaudeIntegration() {
   return process.env.npm_config_global === "true";

package/scripts/prepublish-check.mjs

@@ -10,7 +10,7 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { existsSync, statSync } from "node:fs";
+import { accessSync, constants, existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 
 function run(command, args) {
@@ -42,3 +42,39 @@ if (cliJsMtime < cliTsMtime) {
     "bin/cli.js is older than bin/cli.ts — run: pnpm build:cli && git add bin/cli.js",
   );
 }
+
+// ---------------------------------------------------------------
+// Native macOS notification sender — release.yml builds this on a macOS 26
+// runner and injects it into packages/daemon/dist before npm publish. npm and
+// Homebrew consume the same tarball, so a missing bundle would silently put
+// users back on an unbranded AppleScript fallback.
+// ---------------------------------------------------------------
+const notifierRoot = join(
+  process.cwd(),
+  "packages",
+  "daemon",
+  "dist",
+  "native",
+  "TmuxIdeNotifier.app",
+  "Contents",
+);
+for (const relative of [
+  "Info.plist",
+  join("Resources", "Assets.car"),
+  join("Resources", "AppIcon.icns"),
+]) {
+  const path = join(notifierRoot, relative);
+  if (!existsSync(path)) {
+    throw new Error(
+      `native macOS notifier is incomplete (${relative} missing) — run pnpm build:macos-notifier on macOS`,
+    );
+  }
+}
+const notifierExecutable = join(notifierRoot, "MacOS", "tmux-ide-notifier");
+try {
+  accessSync(notifierExecutable, constants.X_OK);
+} catch {
+  throw new Error(
+    "native macOS notifier executable is missing or not executable — run pnpm build:macos-notifier on macOS",
+  );
+}

package/scripts/publish-tap.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Publish packaging/homebrew/Formula/tmux-ide.rb to the Homebrew tap repo
+# (wavyrai/homebrew-tap), i.e. the one-time seeding the CI `bump_tap` job
+# assumes. After this, every release keeps the tap current automatically
+# (given the TAP_PUSH_TOKEN secret — see .github/workflows/release.yml).
+#
+# Usage:
+#   scripts/publish-tap.sh [path-to-tap-checkout]
+#
+# With no argument, clones git@github.com:wavyrai/homebrew-tap.git into a
+# temp dir. The tap repo must already exist on GitHub (create it empty —
+# the name MUST be exactly `homebrew-tap` for `brew install
+# wavyrai/tap/tmux-ide` to resolve).
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+formula="$repo_root/packaging/homebrew/Formula/tmux-ide.rb"
+[[ -f "$formula" ]] || {
+  echo "formula not found: $formula" >&2
+  exit 1
+}
+
+tap_dir="${1:-}"
+cleanup=""
+if [[ -z "$tap_dir" ]]; then
+  tap_dir="$(mktemp -d)/homebrew-tap"
+  cleanup="$(dirname "$tap_dir")"
+  git clone git@github.com:wavyrai/homebrew-tap.git "$tap_dir"
+fi
+[[ -d "$tap_dir/.git" ]] || {
+  echo "not a git checkout: $tap_dir" >&2
+  exit 1
+}
+
+version="$(sed -nE 's#^  url ".*/tmux-ide-([0-9][^"]*)\.tgz"$#\1#p' "$formula")"
+[[ -n "$version" ]] || {
+  echo "could not read the version from the formula url" >&2
+  exit 1
+}
+
+mkdir -p "$tap_dir/Formula"
+cp "$formula" "$tap_dir/Formula/tmux-ide.rb"
+
+cd "$tap_dir"
+git add Formula/tmux-ide.rb
+if git diff --cached --quiet; then
+  echo "tap already has this formula version (v$version) — nothing to push."
+else
+  git commit -m "tmux-ide $version"
+  git push origin HEAD
+  echo "pushed tmux-ide v$version to $(git remote get-url origin)"
+fi
+
+[[ -n "$cleanup" ]] && rm -rf "$cleanup"
+echo "install with: brew install wavyrai/tap/tmux-ide"

package/skill/SKILL.md

@@ -34,10 +34,26 @@ minutes is treated as stale (the detector falls back to Layer 2), so long-runnin
 agents should re-stamp periodically. Two optional companions:
 
 ```bash
-tmux set-option -p @agent_session_id "<id>"   # your Claude session id — powers restore --resume-agents
+tmux set-option -p @agent_session_id "<id>"   # your own session id — powers restore --resume-agents
 tmux set-option -p @agent_hint claude          # force which agent manifest Layer 2 uses for this pane
 ```
 
+**Display metadata** — say WHAT you're doing and WHO you are, right in the
+fleet UI. Two more optional pane-local options:
+
+```bash
+tmux set-option -p @agent_status_text "refactoring auth"  # one-liner, ≤32 chars — shows in the pane chip ("● claude · refactoring auth")
+tmux set-option -p @agent_display_name "reviewer"          # your name — replaces the detected kind in sidebar rows & chips
+```
+
+Plain text only (control characters are stripped, tabs break the line for your
+pane — don't stamp them; anything past 32 chars is ellipsized). Both surface in
+`tmux-ide team --json` (per-pane `statusText` / `displayName`), the unified
+app's pane chips, and the sidebar agent rows. They follow the SAME staleness
+rules as `@agent_state`: they only show while your state stamp is fresh, so
+re-stamp `@agent_state` alongside — update the text whenever your focus
+changes, and it disappears with a stale/cleared state instead of lying.
+
 **Claude Code users get this for free** — `tmux-ide integration install claude`
 writes a POSIX hook into `~/.claude/settings.json` that stamps `@agent_state` on
 every lifecycle event (UserPromptSubmit/PreToolUse → working, Notification →
@@ -45,6 +61,13 @@ blocked, Stop → done, SessionEnd → idle) and records `@agent_session_id`. It
 takes effect for **new** Claude Code sessions; the merge is reversible
 (`integration uninstall claude`).
 
+**Session-id capture for other kinds** (what `restore --resume-agents` resumes
+from): codex and cursor-agent panes are stamped **automatically** — the chrome
+updater reads each CLI's own on-disk session state; opencode gets a plugin via
+`tmux-ide integration install opencode`. `tmux-ide integration status` shows
+what's active. Kinds without a verified resume story (gemini, aider, copilot, …)
+can self-report the id as above.
+
 **How detection layers work:** Layer 1 is the authority above — a fresh
 `@agent_state` option is ground truth. When none is present, Layer 2 resolves the
 agent from the pane's process tree and reads the visible screen against
@@ -91,7 +114,7 @@ tmux-ide adopt --all                       # adopt every live session
 tmux-ide unadopt <session>                 # remove the dock — sessions keep running as plain tmux
 
 tmux-ide restore --dry-run --json          # preview rebuilding the fleet from the last snapshot
-tmux-ide restore --resume-agents           # rebuild after a tmux crash; revive Claude convos via claude --resume
+tmux-ide restore --resume-agents           # rebuild after a tmux crash; revive agent convos (claude/codex/cursor/opencode)
 
 tmux-ide worktree create <branch> --from <ref>   # git worktree on a new branch + a session in it
 tmux-ide worktree open <branch>            # open/switch to an existing worktree's session
@@ -102,6 +125,69 @@ tmux-ide update --dry-run                  # detect install method (dev checkout
 tmux-ide doctor                            # system + integration health (tmux version, TUI surfaces, skill freshness)
 ```
 
+## Drive tmux-ide over the socket (agent loops)
+
+The CLI above spawns a process per call. If you are driving the fleet in a
+loop — polling status, waiting on agents, reacting to transitions — start the
+control server once and keep ONE connection open instead:
+
+```bash
+tmux-ide serve &   # local Unix socket at ~/.tmux-ide/control.sock (0600, this user only)
+```
+
+**Frame format:** newline-delimited JSON, one object per line. Send
+`{"v":1,"id":<any>,"verb":"<verb>","params":{…}}`; you get back
+`{"v":1,"id":<same>,"ok":true,"data":…}` or
+`{"v":1,"id":<same>,"ok":false,"error":{"code","message"}}`. Responses
+correlate by `id` (they may arrive out of order — a long `wait` doesn't block
+other verbs on the same connection). After the `subscribe` verb the server
+also PUSHES unsolicited `{"v":1,"event":"agent-status","data":{ts,session,from,to}}`
+frames the moment its detection tick sees a session change state — no polling.
+
+**Verbs:** `fleet` (the `team --json` payload) · `agents` (per-pane entries,
+optional `{session}`) · `send` (`{session,target,message,noEnter?,dir?}`) ·
+`wait` (`{kind:"agent-status",session,status,timeoutMs?}` or
+`{kind:"output",target,match,timeoutMs?}`; a timeout is an error response with
+code `timeout`) · `spawn` (`{kind|command, session?|sessionName, dir?,
+placement?, paneId?}` → the new `paneId`) · `restart-agent` / `stop-agent`
+(`{paneId, kind|command}`) · `explain` (`{target}`) · `subscribe`.
+
+One-shot from a shell (nc keeps the pipe open for the response):
+
+```bash
+printf '{"v":1,"id":1,"verb":"fleet"}\n' | nc -U ~/.tmux-ide/control.sock | head -1
+```
+
+A subscribe loop from node:
+
+```js
+const net = require("node:net");
+const os = require("node:os");
+const sock = net.connect(`${os.homedir()}/.tmux-ide/control.sock`);
+let buf = "";
+sock.on("data", (chunk) => {
+  buf += chunk;
+  const lines = buf.split("\n");
+  buf = lines.pop();
+  for (const line of lines.filter(Boolean)) {
+    const frame = JSON.parse(line);
+    if (frame.event === "agent-status") console.log(frame.data); // react here
+  }
+});
+sock.write('{"v":1,"id":1,"verb":"subscribe"}\n');
+```
+
+Right after `subscribe`, the first tick reports every session once with
+`from:null` (a snapshot of where the fleet stands); real transitions follow.
+
+**Socket vs CLI:** prefer the socket for anything event-driven or repeated
+(subscribe replaces an `events --follow` poll; a server-held `wait` costs no
+spawn-per-poll). Prefer the CLI for one-shot reads and anything a human might
+re-run — it needs no server. With a server running, `tmux-ide events --follow
+--socket` and `tmux-ide wait … --socket` use it automatically and fall back to
+polling silently when it's gone. The server is local-only by design: no
+network listener, no tokens — filesystem permissions are the auth.
+
 ## Keys & surfaces to tell USERS about
 
 Once a session is adopted, the whole UI is a keystroke away. **Lead with the
@@ -123,6 +209,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