tmux-ide 2.6.0 → 2.7.0

package/packages/daemon/dist/lib/tui-binary.d.ts

@@ -0,0 +1,57 @@
+/** The `<os>-<arch>` tags we publish a prebuilt TUI binary for. */
+export type TuiPlatformTag = "darwin-arm64" | "darwin-x64" | "linux-x64" | "linux-arm64";
+/** The GitHub repo the release assets live under. */
+export declare const RELEASE_REPO = "wavyrai/tmux-ide";
+/** A downloaded binary smaller than this is treated as corrupt/truncated. */
+export declare const MIN_TUI_BINARY_BYTES: number;
+/**
+ * PURE — map a Node `process.platform`/`process.arch` pair to the release tag,
+ * or null when we don't publish a binary for it (e.g. windows, freebsd) so the
+ * caller can fall back to the "install bun" message.
+ */
+export declare function tuiPlatformTag(platform?: NodeJS.Platform, arch?: string): TuiPlatformTag | null;
+/** PURE — the `bun build --compile --target` flag for a tag (`bun-<tag>`). */
+export declare function bunTargetForTag(tag: TuiPlatformTag): string;
+/** PURE — the release asset filename for a tag (gzip-compressed binary). */
+export declare function releaseAssetName(tag: TuiPlatformTag): string;
+/** PURE — strip a leading `v` from a version string; `2.6.1` and `v2.6.1` both → `2.6.1`. */
+export declare function normalizeVersion(version: string): string;
+/**
+ * PURE — the GitHub download URL for a platform's asset at a given version:
+ * `https://github.com/<repo>/releases/download/v<version>/tmux-ide-tui-<tag>.gz`.
+ */
+export declare function releaseAssetUrl(version: string, tag: TuiPlatformTag): string;
+/**
+ * PURE — where a downloaded binary lives: `<home>/bin/tmux-ide-tui-<tag>-<version>`.
+ * The version is stamped INTO the name so a `tmux-ide update` to a new version
+ * misses the old download and re-fetches (rather than launching a stale binary).
+ */
+export declare function downloadedTuiPath(home: string, tag: TuiPlatformTag, version: string): string;
+/**
+ * io — the tmux-ide state home (`TMUX_IDE_HOME` override, else `~/.tmux-ide`),
+ * the same resolution the update-check cache and welcome marker use.
+ */
+export declare function tuiStateHome(): string;
+/**
+ * io — locate a previously downloaded per-platform binary for THIS version and
+ * platform, or null. Feeds the resolution order in `tui/compiled.ts` after the
+ * shipped/local compiled binary and before the honest "unavailable" error.
+ */
+export declare function findDownloadedTui(version?: string): string | null;
+/**
+ * io — download, verify, and install the per-platform TUI binary for the running
+ * version. Fetches the gzip asset, inflates it, rejects anything under
+ * {@link MIN_TUI_BINARY_BYTES} (a truncated download or an HTML error page),
+ * writes it `0o755`, and atomically renames it into place (temp-in-same-dir →
+ * rename, so a crashed download never leaves a half-written executable).
+ *
+ * Throws with an actionable message on an unsupported platform or a failed
+ * fetch. Returns the installed path and byte size.
+ */
+export declare function downloadTuiBinary(opts?: {
+    version?: string;
+    log?: (msg: string) => void;
+}): Promise<{
+    path: string;
+    bytes: number;
+}>;

package/packages/daemon/dist/lib/tui-binary.js

@@ -0,0 +1,130 @@
+/**
+ * Per-platform TUI binary: the runtime-download fallback that lets a clean
+ * `npm i -g tmux-ide` run the full OpenTUI/Solid cockpit WITHOUT `bun`.
+ *
+ * The dev checkout runs the `.tsx` surfaces via bun; an npm install with no bun
+ * needs a self-contained binary. We do NOT bundle that ~70MB blob in the npm
+ * tarball (a surprise on every install) — instead the release workflow
+ * (`.github/workflows/release-binaries.yml`) cross-compiles one per platform and
+ * uploads them as GitHub release assets, and this module downloads the right one
+ * on demand (explicit `tmux-ide update --tui-binary`, or a consented first run).
+ *
+ * The mapping/URL/path helpers are PURE (unit-tested); {@link downloadTuiBinary}
+ * and {@link findDownloadedTui} are the thin io that fetch and probe.
+ */
+import { chmodSync, existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { gunzipSync } from "node:zlib";
+import { getCurrentVersion } from "./update-check.js";
+/** The GitHub repo the release assets live under. */
+export const RELEASE_REPO = "wavyrai/tmux-ide";
+/** A downloaded binary smaller than this is treated as corrupt/truncated. */
+export const MIN_TUI_BINARY_BYTES = 10 * 1024 * 1024;
+const SUPPORTED = {
+    "darwin-arm64": "darwin-arm64",
+    "darwin-x64": "darwin-x64",
+    "linux-x64": "linux-x64",
+    "linux-arm64": "linux-arm64",
+};
+// ---------------------------------------------------------------------------
+// Pure
+// ---------------------------------------------------------------------------
+/**
+ * PURE — map a Node `process.platform`/`process.arch` pair to the release tag,
+ * or null when we don't publish a binary for it (e.g. windows, freebsd) so the
+ * caller can fall back to the "install bun" message.
+ */
+export function tuiPlatformTag(platform = process.platform, arch = process.arch) {
+    return SUPPORTED[`${platform}-${arch}`] ?? null;
+}
+/** PURE — the `bun build --compile --target` flag for a tag (`bun-<tag>`). */
+export function bunTargetForTag(tag) {
+    return `bun-${tag}`;
+}
+/** PURE — the release asset filename for a tag (gzip-compressed binary). */
+export function releaseAssetName(tag) {
+    return `tmux-ide-tui-${tag}.gz`;
+}
+/** PURE — strip a leading `v` from a version string; `2.6.1` and `v2.6.1` both → `2.6.1`. */
+export function normalizeVersion(version) {
+    return version.startsWith("v") ? version.slice(1) : version;
+}
+/**
+ * PURE — the GitHub download URL for a platform's asset at a given version:
+ * `https://github.com/<repo>/releases/download/v<version>/tmux-ide-tui-<tag>.gz`.
+ */
+export function releaseAssetUrl(version, tag) {
+    return `https://github.com/${RELEASE_REPO}/releases/download/v${normalizeVersion(version)}/${releaseAssetName(tag)}`;
+}
+/**
+ * PURE — where a downloaded binary lives: `<home>/bin/tmux-ide-tui-<tag>-<version>`.
+ * The version is stamped INTO the name so a `tmux-ide update` to a new version
+ * misses the old download and re-fetches (rather than launching a stale binary).
+ */
+export function downloadedTuiPath(home, tag, version) {
+    return join(home, "bin", `tmux-ide-tui-${tag}-${normalizeVersion(version)}`);
+}
+// ---------------------------------------------------------------------------
+// io
+// ---------------------------------------------------------------------------
+/**
+ * io — the tmux-ide state home (`TMUX_IDE_HOME` override, else `~/.tmux-ide`),
+ * the same resolution the update-check cache and welcome marker use.
+ */
+export function tuiStateHome() {
+    return process.env.TMUX_IDE_HOME ?? join(homedir(), ".tmux-ide");
+}
+/**
+ * io — locate a previously downloaded per-platform binary for THIS version and
+ * platform, or null. Feeds the resolution order in `tui/compiled.ts` after the
+ * shipped/local compiled binary and before the honest "unavailable" error.
+ */
+export function findDownloadedTui(version = getCurrentVersion()) {
+    const tag = tuiPlatformTag();
+    if (!tag)
+        return null;
+    const path = downloadedTuiPath(tuiStateHome(), tag, version);
+    return existsSync(path) ? path : null;
+}
+/**
+ * io — download, verify, and install the per-platform TUI binary for the running
+ * version. Fetches the gzip asset, inflates it, rejects anything under
+ * {@link MIN_TUI_BINARY_BYTES} (a truncated download or an HTML error page),
+ * writes it `0o755`, and atomically renames it into place (temp-in-same-dir →
+ * rename, so a crashed download never leaves a half-written executable).
+ *
+ * Throws with an actionable message on an unsupported platform or a failed
+ * fetch. Returns the installed path and byte size.
+ */
+export async function downloadTuiBinary(opts = {}) {
+    const log = opts.log ?? (() => { });
+    const version = normalizeVersion(opts.version ?? getCurrentVersion());
+    const tag = tuiPlatformTag();
+    if (!tag) {
+        throw new Error(`no prebuilt TUI binary is published for ${process.platform}-${process.arch} — ` +
+            `install bun (https://bun.sh) to run the TUI surfaces from source instead`);
+    }
+    const url = releaseAssetUrl(version, tag);
+    const dest = downloadedTuiPath(tuiStateHome(), tag, version);
+    mkdirSync(dirname(dest), { recursive: true });
+    log(`downloading ${url}`);
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`could not download the TUI binary (${url} → HTTP ${res.status} ${res.statusText}). ` +
+            `Check that release v${version} exists and published its assets.`);
+    }
+    const gz = Buffer.from(await res.arrayBuffer());
+    const bin = gunzipSync(gz);
+    if (bin.byteLength < MIN_TUI_BINARY_BYTES) {
+        throw new Error(`the downloaded TUI binary is only ${bin.byteLength} bytes (expected >10MB) — ` +
+            `treating it as corrupt and leaving the previous binary (if any) in place`);
+    }
+    const tmp = `${dest}.${process.pid}.tmp`;
+    writeFileSync(tmp, bin, { mode: 0o755 });
+    chmodSync(tmp, 0o755);
+    renameSync(tmp, dest);
+    const mb = (bin.byteLength / 1024 / 1024).toFixed(1);
+    log(`installed ${dest} (${mb} MB)`);
+    return { path: dest, bytes: bin.byteLength };
+}

package/packages/daemon/dist/widgets/explorer/breadcrumbs.d.ts

@@ -6,5 +6,5 @@ interface BreadcrumbsProps {
     theme: WidgetTheme;
     onNavigate: (absolutePath: string) => void;
 }
-export declare function Breadcrumbs(props: BreadcrumbsProps): any;
+export declare function Breadcrumbs(props: BreadcrumbsProps): import("solid-js").JSX.Element;
 export {};

package/packages/daemon/dist/widgets/explorer/footer.d.ts

@@ -2,5 +2,5 @@ import type { WidgetTheme } from "../lib/theme.ts";
 interface FooterProps {
     theme: WidgetTheme;
 }
-export declare function Footer(props: FooterProps): any;
+export declare function Footer(props: FooterProps): import("solid-js").JSX.Element;
 export {};

package/packages/daemon/dist/widgets/explorer/tree.d.ts

@@ -9,5 +9,5 @@ interface FileTreeProps {
     onActivate: (node: TreeNode) => void;
     onInputModeChange: (mode: "keyboard" | "mouse") => void;
 }
-export declare function FileTree(props: FileTreeProps): any;
+export declare function FileTree(props: FileTreeProps): import("solid-js").JSX.Element;
 export {};

package/packages/daemon/dist/widgets/lib/help-overlay.d.ts

@@ -16,4 +16,4 @@ export interface HelpOverlayProps {
  * the surface's own keys. Replaces the surface body while `?` is held open;
  * `esc`/`q`/`?` close it.
  */
-export declare function HelpOverlay(props: HelpOverlayProps): any;
+export declare function HelpOverlay(props: HelpOverlayProps): import("solid-js").JSX.Element;

package/packages/daemon/dist/widgets/setup/agent-naming.d.ts

@@ -5,5 +5,5 @@ interface AgentNamingProps {
     onContinue: (names: string[]) => void;
     theme: WidgetTheme;
 }
-export declare function AgentNaming(props: AgentNamingProps): any;
+export declare function AgentNaming(props: AgentNamingProps): import("solid-js").JSX.Element;
 export {};

package/packages/daemon/dist/widgets/setup/config-tree.d.ts

@@ -9,5 +9,5 @@ interface ConfigTreeProps {
     onConfigChange: (config: IdeConfig) => void;
     theme: WidgetTheme;
 }
-export declare function ConfigTree(props: ConfigTreeProps): any;
+export declare function ConfigTree(props: ConfigTreeProps): import("solid-js").JSX.Element;
 export {};

package/packages/daemon/dist/widgets/setup/detect-panel.d.ts

@@ -10,5 +10,5 @@ interface DetectPanelProps {
     onContinue: () => void;
     theme: WidgetTheme;
 }
-export declare function DetectPanel(props: DetectPanelProps): any;
+export declare function DetectPanel(props: DetectPanelProps): import("solid-js").JSX.Element;
 export {};

package/packages/daemon/dist/widgets/setup/field-editor.d.ts

@@ -9,4 +9,4 @@ export interface FieldEditorProps {
     onCancel: () => void;
     theme: WidgetTheme;
 }
-export declare function FieldEditor(props: FieldEditorProps): any;
+export declare function FieldEditor(props: FieldEditorProps): import("solid-js").JSX.Element;

package/packages/daemon/dist/widgets/setup/footer.d.ts

@@ -13,5 +13,5 @@ interface FooterProps {
     theme: WidgetTheme;
     actions?: FooterActions;
 }
-export declare function Footer(props: FooterProps): any;
+export declare function Footer(props: FooterProps): import("solid-js").JSX.Element;
 export {};

package/packages/daemon/dist/widgets/setup/layout-picker.d.ts

@@ -5,5 +5,5 @@ interface LayoutPickerProps {
     onSelect: (preset: LayoutPreset) => void;
     theme: WidgetTheme;
 }
-export declare function LayoutPicker(props: LayoutPickerProps): any;
+export declare function LayoutPicker(props: LayoutPickerProps): import("solid-js").JSX.Element;
 export {};

package/packages/daemon/src/agent-explain.ts

@@ -0,0 +1,298 @@
+/**
+ * `tmux-ide agent explain <pane>` — the detection debugger.
+ *
+ * For a single pane it prints EVERYTHING the fleet detector reasons over:
+ *   - the pane's command + pid,
+ *   - the `@agent_state` authority option (raw + parsed verdict + staleness),
+ *   - the `@agent_hint` override option,
+ *   - which manifest resolved and via which path (hint/fast/tree),
+ *   - each state's rule → matched or not (via `explain()`),
+ *   - the winning instantaneous classification, and
+ *   - the bottom 5 snapshot lines it judged.
+ *
+ * This is READ-ONLY: it captures and inspects, it never sends keys or mutates
+ * the target pane.
+ */
+import { execFileSync } from "node:child_process";
+import { explain, type DetectedState, type ManifestConfidence } from "./tui/detect/manifest.ts";
+import {
+  classifyInstant,
+  parseAuthority,
+  type AgentStatus,
+  type InstantState,
+} from "./tui/detect/classify.ts";
+import { getManifests } from "./tui/detect/manifest-loader.ts";
+import {
+  describeSubtree,
+  readProcessTable,
+  resolveAgentCommand,
+} from "./tui/detect/process-tree.ts";
+import { readPaneSnapshot } from "./tui/detect/snapshot.ts";
+import { IdeError } from "./lib/errors.ts";
+
+/** Working/blocked authority reports older than this are stale (mirrors classify.ts). */
+const AUTHORITY_STALE_SECONDS = 600;
+
+interface PaneInfo {
+  id: string;
+  pid: number;
+  cmd: string;
+  title: string;
+  authorityRaw: string;
+  hintRaw: string;
+}
+
+export interface ExplainReport {
+  pane: { id: string; cmd: string; pid: number; title: string };
+  authority: {
+    raw: string | null;
+    state: string | null;
+    epoch: number | null;
+    ageSeconds: number | null;
+    stale: boolean;
+    verdict: AgentStatus | null;
+  };
+  hint: { raw: string | null; applied: boolean };
+  resolution: {
+    manifestId: string | null;
+    matchedCommand: string;
+    source: "hint" | "fast" | "tree" | "none";
+    /** The matched manifest's evidence confidence (null when nothing resolved). */
+    confidence: ManifestConfidence | null;
+    /**
+     * Executable-ish tokens seen in the pane's process subtree. Populated for
+     * the "no manifest matched" case so the report can say what it DID find.
+     */
+    subtree: string[];
+  };
+  states: Array<{ state: DetectedState; matched: boolean }>;
+  winner: DetectedState | null;
+  instant: InstantState;
+  classification: AgentStatus;
+  bottomLines: string[];
+}
+
+function tmux(args: string[]): string {
+  try {
+    return execFileSync("tmux", args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Resolve a target to a concrete pane's fields. `%N` is a pane id; anything
+ * else is treated as a session (or any tmux target) whose ACTIVE pane is used.
+ */
+function readPaneInfo(target: string): PaneInfo | null {
+  const fmt =
+    "#{pane_id}\t#{pane_pid}\t#{pane_current_command}\t#{@agent_state}\t#{@agent_hint}\t#{pane_title}";
+  const raw = tmux(["display-message", "-p", "-t", target, "-F", fmt]);
+  if (!raw) return null;
+  const [id = "", pid = "", cmd = "", authorityRaw = "", hintRaw = "", ...titleParts] =
+    raw.split("\t");
+  if (!id) return null;
+  return {
+    id,
+    pid: Number(pid) || 0,
+    cmd,
+    authorityRaw,
+    hintRaw,
+    title: titleParts.join("\t"),
+  };
+}
+
+/** Build the full report for a pane. Does all the io (tmux + ps + capture). */
+export function buildReport(target: string): ExplainReport {
+  const info = readPaneInfo(target);
+  if (!info) {
+    throw new IdeError(
+      `No pane found for "${target}". Pass a pane id (%N) or a live session name.`,
+      { code: "USAGE", exitCode: 1 },
+    );
+  }
+
+  const nowSec = Math.floor(Date.now() / 1000);
+
+  // Authority: parse richly for the report (parseAuthority collapses to a
+  // verdict; here we also expose the raw state/epoch/staleness).
+  const authRaw = info.authorityRaw || null;
+  let authState: string | null = null;
+  let authEpoch: number | null = null;
+  let ageSeconds: number | null = null;
+  let stale = false;
+  if (authRaw) {
+    const sep = authRaw.lastIndexOf(":");
+    if (sep !== -1) {
+      authState = authRaw.slice(0, sep);
+      const epoch = Number(authRaw.slice(sep + 1));
+      if (Number.isFinite(epoch)) {
+        authEpoch = epoch;
+        ageSeconds = nowSec - epoch;
+        stale =
+          (authState === "working" || authState === "blocked") &&
+          ageSeconds > AUTHORITY_STALE_SECONDS;
+      }
+    }
+  }
+  const verdict = parseAuthority(info.authorityRaw, nowSec);
+
+  // Resolution: hint > fast > tree, over the loaded (bundled + override) set.
+  const manifests = getManifests();
+  const table = readProcessTable();
+  const resolved = resolveAgentCommand(info.cmd, info.pid, table, {
+    manifests,
+    hint: info.hintRaw,
+  });
+  const manifest = resolved.manifest;
+  // When nothing resolved, record what the process-tree DID see so `explain`
+  // can point the user at an `@agent_hint` target instead of a dead end.
+  const subtree = manifest ? [] : describeSubtree(table, info.pid);
+
+  // Snapshot + per-state explanation.
+  const snapshot = { ...readPaneSnapshot(info.id), title: info.title };
+  const explained = manifest
+    ? explain(snapshot, manifest)
+    : {
+        state: null as DetectedState | null,
+        checked: [] as Array<{ state: DetectedState; matched: boolean }>,
+      };
+  const instant = classifyInstant(snapshot, manifest);
+
+  // Final classification mirrors sessions.ts: a fresh authority verdict wins;
+  // otherwise the instantaneous manifest classification. (The cross-tick `done`
+  // is not derivable from a single snapshot, so this is instant-only.)
+  const classification: AgentStatus = verdict ?? instant;
+
+  return {
+    pane: { id: info.id, cmd: info.cmd, pid: info.pid, title: info.title },
+    authority: {
+      raw: authRaw,
+      state: authState,
+      epoch: authEpoch,
+      ageSeconds,
+      stale,
+      verdict,
+    },
+    hint: { raw: info.hintRaw || null, applied: resolved.source === "hint" },
+    resolution: {
+      manifestId: manifest?.id ?? null,
+      matchedCommand: resolved.matchedCommand,
+      source: resolved.source,
+      confidence: manifest ? (manifest.confidence ?? "conservative") : null,
+      subtree,
+    },
+    states: explained.checked,
+    winner: explained.state,
+    instant,
+    classification,
+    bottomLines: snapshot.bottomNonEmpty.slice(-5),
+  };
+}
+
+const STATUS_COLOR: Record<AgentStatus, string> = {
+  blocked: "\x1b[31m", // red
+  working: "\x1b[33m", // yellow
+  done: "\x1b[32m", // green
+  idle: "\x1b[36m", // cyan
+  unknown: "\x1b[90m", // grey
+};
+
+/** Render the report as colored human-readable text. */
+export function renderReport(r: ExplainReport, opts: { color?: boolean } = {}): string {
+  const color = opts.color ?? !("NO_COLOR" in process.env);
+  const c = (code: string, s: string) => (color ? `${code}${s}\x1b[0m` : s);
+  const bold = (s: string) => c("\x1b[1m", s);
+  const dim = (s: string) => c("\x1b[2m", s);
+  const label = (s: string) => c("\x1b[36m", s);
+  const status = (s: AgentStatus) => c(STATUS_COLOR[s] ?? "", s);
+  const yesno = (v: boolean) => (v ? c("\x1b[32m", "yes") : dim("no"));
+
+  const out: string[] = [];
+  out.push(bold(`agent explain — ${r.pane.id}`));
+  out.push(`  ${label("command")}   ${r.pane.cmd}  ${dim(`(pid ${r.pane.pid})`)}`);
+  if (r.pane.title) out.push(`  ${label("title")}     ${r.pane.title}`);
+
+  // Authority
+  if (r.authority.raw) {
+    const age =
+      r.authority.ageSeconds !== null ? ` ${dim(`(${r.authority.ageSeconds}s ago)`)}` : "";
+    const staleTag = r.authority.stale ? " " + c("\x1b[31m", "[STALE → ignored]") : "";
+    const verdict = r.authority.verdict
+      ? status(r.authority.verdict)
+      : dim("none (stale/malformed)");
+    out.push(`  ${label("authority")} ${r.authority.raw}${age}${staleTag} → ${verdict}`);
+  } else {
+    out.push(`  ${label("authority")} ${dim("(unset — falling back to scraping)")}`);
+  }
+
+  // Hint
+  if (r.hint.raw) {
+    out.push(
+      `  ${label("hint")}      @agent_hint=${r.hint.raw} → ${yesno(r.hint.applied)} applied`,
+    );
+  } else {
+    out.push(`  ${label("hint")}      ${dim("(unset)")}`);
+  }
+
+  // Resolution
+  if (r.resolution.manifestId) {
+    const conf =
+      r.resolution.confidence === "tuned"
+        ? c("\x1b[32m", "tuned")
+        : dim(r.resolution.confidence ?? "conservative");
+    out.push(
+      `  ${label("manifest")}  ${r.resolution.manifestId}  ${dim(`via ${r.resolution.source}` + (r.resolution.matchedCommand ? ` "${r.resolution.matchedCommand}"` : ""))}  [${conf}]`,
+    );
+  } else {
+    // No manifest matched — say so, and report what the process-tree DID see so
+    // the user can set an `@agent_hint` or add a manifest.
+    const saw =
+      r.resolution.subtree.length > 0 ? r.resolution.subtree.join(", ") : r.pane.cmd || "(nothing)";
+    out.push(`  ${label("manifest")}  ${dim("none matched")} — ${dim(`process-tree saw: ${saw}`)}`);
+    out.push(`            ${dim("set `tmux set-option -p @agent_hint <agent>` to force one")}`);
+  }
+
+  // Per-state rule results
+  out.push("");
+  out.push(bold("  state rules"));
+  if (r.states.length === 0) {
+    out.push(`    ${dim("(no manifest resolved — nothing to evaluate)")}`);
+  } else {
+    for (const s of r.states) {
+      const mark = s.matched ? c("\x1b[32m", "✓ matched") : dim("· no match");
+      const win = r.winner === s.state ? "  " + c("\x1b[1m", "← winner") : "";
+      out.push(`    ${s.state.padEnd(8)} ${mark}${win}`);
+    }
+  }
+
+  // Final classification
+  out.push("");
+  out.push(
+    `  ${bold("classification")}  ${status(r.classification)}  ${dim(`(instant: ${r.instant})`)}`,
+  );
+
+  // Snapshot tail
+  out.push("");
+  out.push(bold("  bottom 5 lines judged"));
+  if (r.bottomLines.length === 0) {
+    out.push(`    ${dim("(empty capture)")}`);
+  } else {
+    for (const line of r.bottomLines) out.push(`    ${dim("│")} ${line}`);
+  }
+
+  return out.join("\n");
+}
+
+/** CLI entry: build + print the report (human or JSON). */
+export function agentExplain(target: string, opts: { json?: boolean } = {}): void {
+  const report = buildReport(target);
+  if (opts.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(renderReport(report));
+  }
+}

package/packages/daemon/src/attach.ts

@@ -0,0 +1,20 @@
+import { resolve } from "node:path";
+import { getSessionName } from "./lib/yaml-io.ts";
+import { outputError } from "./lib/output.ts";
+import { attachSession, getSessionState } from "@tmux-ide/tmux-bridge";
+
+export async function attach(
+  targetDir: string | undefined,
+  { json: _json }: { json?: boolean } = {},
+): Promise<void> {
+  const dir = resolve(targetDir ?? ".");
+  const { name: session } = getSessionName(dir);
+  const state = getSessionState(session);
+
+  if (!state.running) {
+    outputError(`Session "${session}" is not running. Start it with: tmux-ide`, "NOT_RUNNING");
+    return;
+  }
+
+  attachSession(session);
+}

package/packages/daemon/src/bin.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { main } from "./cli.ts";
+
+main();

package/packages/daemon/src/canonical.ts

@@ -0,0 +1,7 @@
+export {
+  clearCanonicalDaemonInfo,
+  isCanonicalDaemonAlive,
+  readCanonicalDaemonInfo,
+  writeCanonicalDaemonInfo,
+} from "./lib/canonical-daemon.ts";
+export type { CanonicalDaemonInfo } from "./lib/canonical-daemon.ts";