@bastani/atomic 0.5.5 → 0.5.6

package/src/sdk/components/session-graph-panel.tsx

@@ -18,7 +18,14 @@ import {
   useRef,
   useContext,
 } from "react";
-import { tmuxRun } from "../runtime/tmux.ts";
+import {
+  tmuxRun,
+  escapeTmuxFormat,
+  TMUX_DEFAULT_STATUS_LEFT,
+  TMUX_DEFAULT_STATUS_LEFT_LENGTH,
+  TMUX_DEFAULT_STATUS_RIGHT,
+  TMUX_DEFAULT_STATUS_RIGHT_LENGTH,
+} from "../runtime/tmux.ts";
 import {
   useStore,
   useGraphTheme,
@@ -32,6 +39,7 @@ import { NodeCard } from "./node-card.tsx";
 import { Edge } from "./edge.tsx";
 import { Header } from "./header.tsx";
 import { Statusline } from "./statusline.tsx";
+import { CompactSwitcher } from "./compact-switcher.tsx";
 
 /** Interval (ms) between pulse animation frames — ~60fps feel. */
 const PULSE_INTERVAL_MS = 60;
@@ -75,6 +83,10 @@ export function SessionGraphPanel() {
   const focusedIdRef = useRef(focusedId);
   focusedIdRef.current = focusedId;
 
+  // Compact switcher state
+  const [switcherOpen, setSwitcherOpen] = useState(false);
+  const [switcherSel, setSwitcherSel] = useState(0);
+
   // Update focus when sessions first appear
   useEffect(() => {
     if (store.sessions.length > 0 && !layout.map[focusedId]) {
@@ -119,15 +131,40 @@ export function SessionGraphPanel() {
       const session = store.sessions.find((s) => s.name === id);
       if (!session || session.status === "pending") return;
 
+      // Orchestrator = the graph view itself
+      if (id === "orchestrator") {
+        store.setViewMode("graph");
+        return;
+      }
+
       if (attachTimerRef.current) clearTimeout(attachTimerRef.current);
       setAttachMsg(`\u2192 ${n.name}`);
       attachTimerRef.current = setTimeout(() => setAttachMsg(""), ATTACH_MSG_DISPLAY_MS);
 
+      setFocusedId(id);
+      store.setViewMode("attached", id);
       tmuxRun(["switch-client", "-t", `${tmuxSession}:${n.name}`]);
     },
     [layout.map, tmuxSession],
   );
 
+  const returnToGraph = useCallback(() => {
+    store.setViewMode("graph");
+  }, []);
+
+  const openSwitcher = useCallback(() => {
+    // Pre-select the current agent or focused node
+    const currentId = store.viewMode === "attached" ? store.activeAgentId : focusedIdRef.current;
+    const idx = store.sessions.findIndex((s) => s.name === currentId);
+    setSwitcherSel(Math.max(0, idx));
+    setSwitcherOpen(true);
+  }, []);
+
+  const closeSwitcher = useCallback(() => {
+    setSwitcherOpen(false);
+    setSwitcherSel(0);
+  }, []);
+
   // Spatial navigation
   const navigate = useCallback(
     (dir: "left" | "right" | "up" | "down") => {
@@ -168,18 +205,54 @@ export function SessionGraphPanel() {
     [layout.map, nodeList],
   );
 
-  // gg double-tap tracking
+  // gg double-tap tracking (graph mode only)
   const lastKeyRef = useRef({ key: "", time: 0 });
 
-  // Keyboard handling
+  // Keyboard handling — with Ctrl+G return-to-graph and auto-reset
   useKeyboard((key) => {
-    // Ctrl+C or q: quit the workflow (abort if running, exit if completed)
+    // ── Switcher open: intercept all keys ──
+    if (switcherOpen) {
+      if (key.name === "escape") {
+        closeSwitcher();
+        return;
+      }
+      if (key.name === "up" || key.name === "k") {
+        setSwitcherSel((s) => Math.max(0, s - 1));
+        return;
+      }
+      if (key.name === "down" || key.name === "j") {
+        setSwitcherSel((s) => Math.min(store.sessions.length - 1, s + 1));
+        return;
+      }
+      if (key.name === "return") {
+        const agent = store.sessions[switcherSel];
+        closeSwitcher();
+        if (agent) doAttach(agent.name);
+        return;
+      }
+      return; // Swallow all other keys while switcher is open
+    }
+
+    // ── Global: Ctrl+C or q quits ──
     if ((key.ctrl && key.name === "c") || key.name === "q") {
       store.requestQuit();
       return;
     }
 
-    // Arrow keys + hjkl navigation
+    // ── Auto-reset: receiving keys while "attached" means user returned to the orchestrator window ──
+    if (store.viewMode === "attached") {
+      returnToGraph();
+      // Fall through to process the key in graph mode
+    }
+
+    // ── / opens agent switcher ──
+    if (key.sequence === "/") {
+      openSwitcher();
+      return;
+    }
+
+    // ── Graph view navigation ──
+    // Arrow keys + hjkl
     if (key.name === "left" || key.name === "h") {
       navigate("left");
       return;
@@ -196,11 +269,6 @@ export function SessionGraphPanel() {
       navigate("down");
       return;
     }
-    if (key.name === "tab") {
-      navigate(key.shift ? "left" : "right");
-      return;
-    }
-
     // Enter: attach to focused node's tmux window
     if (key.name === "return") {
       doAttach(focusedIdRef.current);
@@ -285,6 +353,63 @@ export function SessionGraphPanel() {
     }
   }, [focusedId, focused, termW, termH, padX, padY, viewportH, layout.rowH]);
 
+  // ── Detect return to graph via Ctrl+G ─────────────────
+  // Ctrl+G is bound at the tmux level (select-window -t :0), so tmux
+  // swallows the key and the React app never receives it.  Poll the
+  // active window index while attached; when window 0 becomes active
+  // again we know the user returned and can reset viewMode immediately.
+  useEffect(() => {
+    if (store.viewMode !== "attached") return;
+
+    const check = () => {
+      const result = tmuxRun([
+        "display-message", "-t", tmuxSession, "-p", "#{window_index}",
+      ]);
+      if (result.ok && result.stdout.trim() === "0") {
+        store.setViewMode("graph");
+      }
+    };
+
+    const id = setInterval(check, 300);
+    return () => clearInterval(id);
+  }, [store.viewMode, tmuxSession]);
+
+  // ── Tmux status bar sync ──────────────────────────────
+  // When attached, the orchestrator panel is hidden (user views the agent's
+  // tmux window). Mirror the status line hints into tmux's own status bar
+  // so navigation keys remain discoverable.
+  const subagentCount = store.getSubagents().length;
+  const activeAgentIdx = store.getActiveAgentIndex();
+
+  useEffect(() => {
+    if (store.viewMode === "attached" && store.activeAgentId) {
+      const safeName = escapeTmuxFormat(store.activeAgentId);
+      const left = `#[bg=#6c7086,fg=#1e1e2e,bold] ATTACHED #[default] #[fg=#7f849c]\u203a #[fg=#cdd6f4]${safeName} #[fg=#7f849c]${activeAgentIdx + 1}/${subagentCount}`;
+      const right = `#[fg=#7f849c]Graph: #[fg=#cdd6f4]ctrl+g #[fg=#7f849c]| Next: #[fg=#cdd6f4]ctrl+\\ `;
+
+      tmuxRun(["set", "-g", "status-left", left]);
+      tmuxRun(["set", "-g", "status-left-length", "50"]);
+      tmuxRun(["set", "-g", "status-right", right]);
+      tmuxRun(["set", "-g", "status-right-length", "40"]);
+    } else {
+      // Graph mode: restore defaults (constants from tmux.ts match tmux.conf)
+      tmuxRun(["set", "-g", "status-left", TMUX_DEFAULT_STATUS_LEFT]);
+      tmuxRun(["set", "-g", "status-left-length", TMUX_DEFAULT_STATUS_LEFT_LENGTH]);
+      tmuxRun(["set", "-g", "status-right", TMUX_DEFAULT_STATUS_RIGHT]);
+      tmuxRun(["set", "-g", "status-right-length", TMUX_DEFAULT_STATUS_RIGHT_LENGTH]);
+    }
+  }, [store.viewMode, store.activeAgentId, activeAgentIdx, subagentCount]);
+
+  // Restore default tmux status bar on unmount
+  useEffect(() => {
+    return () => {
+      tmuxRun(["set", "-g", "status-left", TMUX_DEFAULT_STATUS_LEFT]);
+      tmuxRun(["set", "-g", "status-left-length", TMUX_DEFAULT_STATUS_LEFT_LENGTH]);
+      tmuxRun(["set", "-g", "status-right", TMUX_DEFAULT_STATUS_RIGHT]);
+      tmuxRun(["set", "-g", "status-right-length", TMUX_DEFAULT_STATUS_RIGHT_LENGTH]);
+    };
+  }, []);
+
   return (
     <box width="100%" height="100%" flexDirection="column" backgroundColor={theme.background}>
       <Header />
@@ -345,6 +470,9 @@ export function SessionGraphPanel() {
         </box>
       </scrollbox>
 
+      {/* Compact agent switcher overlay */}
+      {switcherOpen ? <CompactSwitcher selectedIndex={switcherSel} /> : null}
+
       <Statusline focusedNode={focused} attachMsg={attachMsg} />
     </box>
   );

package/src/sdk/components/statusline.tsx

@@ -1,7 +1,7 @@
 /** @jsxImportSource @opentui/react */
 
-import { useGraphTheme } from "./orchestrator-panel-contexts.ts";
-import { statusIcon, statusColor, statusLabel } from "./status-helpers.ts";
+import { useStore, useGraphTheme, useStoreVersion } from "./orchestrator-panel-contexts.ts";
+import { statusIcon, statusColor } from "./status-helpers.ts";
 import type { LayoutNode } from "./layout.ts";
 
 export function Statusline({
@@ -11,24 +11,25 @@ export function Statusline({
   focusedNode: LayoutNode | undefined;
   attachMsg: string;
 }) {
+  const store = useStore();
   const theme = useGraphTheme();
-  const ni = focusedNode ? statusIcon(focusedNode.status) : "";
-  const nc = focusedNode ? statusColor(focusedNode.status, theme) : theme.textDim;
+  useStoreVersion(store);
 
   return (
     <box height={1} flexDirection="row" backgroundColor={theme.backgroundElement}>
+      {/* Mode badge — always GRAPH since this bar is only visible in the orchestrator window */}
       <box backgroundColor={theme.primary} paddingLeft={1} paddingRight={1} alignItems="center">
         <text fg={theme.backgroundElement}>
           <strong>GRAPH</strong>
         </text>
       </box>
 
+      {/* Focused node info */}
       {focusedNode ? (
-        <box backgroundColor="transparent" paddingLeft={1} paddingRight={1} alignItems="center">
+        <box backgroundColor="transparent" paddingLeft={1} alignItems="center">
           <text>
-            <span fg={nc}>{ni} </span>
+            <span fg={statusColor(focusedNode.status, theme)}>{statusIcon(focusedNode.status)} </span>
             <span fg={theme.text}>{focusedNode.name}</span>
-            <span fg={theme.textMuted}> {"\u00B7"} {statusLabel(focusedNode.status)}</span>
             {focusedNode.error ? (
               <span fg={theme.error}> {"\u00B7"} {focusedNode.error}</span>
             ) : null}
@@ -38,6 +39,7 @@ export function Statusline({
 
       <box flexGrow={1} />
 
+      {/* Navigation hints — always graph-mode (tmux status bar handles attached-mode hints) */}
       <box paddingRight={2} alignItems="center">
         {attachMsg ? (
           <text fg={theme.text}>
@@ -45,12 +47,15 @@ export function Statusline({
           </text>
         ) : (
           <text>
-            <span fg={theme.text}>{"\u2191"} {"\u2193"} {"\u2190"} {"\u2192"}</span>
+            <span fg={theme.text}>{"\u2191\u2193\u2190\u2192"}</span>
             <span fg={theme.textMuted}> navigate</span>
             <span fg={theme.textDim}> {"\u00B7"} </span>
             <span fg={theme.text}>{"\u21B5"}</span>
             <span fg={theme.textMuted}> attach</span>
             <span fg={theme.textDim}> {"\u00B7"} </span>
+            <span fg={theme.text}>/</span>
+            <span fg={theme.textMuted}> agents</span>
+            <span fg={theme.textDim}> {"\u00B7"} </span>
             <span fg={theme.text}>q</span>
             <span fg={theme.textMuted}> quit</span>
           </text>

package/src/sdk/runtime/executor.ts

@@ -39,7 +39,7 @@ import type { SessionEvent } from "@github/copilot-sdk";
 import type { SessionPromptResponse } from "@opencode-ai/sdk/v2";
 import type { SessionMessage } from "@anthropic-ai/claude-agent-sdk";
 import * as tmux from "./tmux.ts";
-import { spawnMuxAttach, SOCKET_NAME } from "./tmux.ts";
+import { spawnMuxAttach } from "./tmux.ts";
 import { WorkflowLoader } from "./loader.ts";
 import {
   clearClaudeSession,
@@ -303,8 +303,9 @@ export function parseInputsEnv(raw: string | undefined): Record<string, string>
 /**
  * Called by `atomic workflow -n <name> -a <agent> <prompt>`.
  *
- * Creates a tmux session with the orchestrator as the initial pane,
- * then attaches so the user sees everything live.
+ * Always creates a tmux session in the atomic socket with the
+ * orchestrator as the initial pane, then attaches so the user sees
+ * everything live — even when invoked from inside another tmux session.
  */
 export async function executeWorkflow(
   options: WorkflowRunOptions,
@@ -318,7 +319,7 @@ export async function executeWorkflow(
   } = options;
 
   const workflowRunId = generateId();
-  const tmuxSessionName = `atomic-wf-${definition.name}-${workflowRunId}`;
+  const tmuxSessionName = `atomic-wf-${agent}-${definition.name}-${workflowRunId}`;
   const sessionsBaseDir = join(getSessionsBaseDir(), workflowRunId);
   await ensureDir(sessionsBaseDir);
 
@@ -364,30 +365,20 @@ export async function executeWorkflow(
 
   await writeFile(launcherPath, launcherScript, { mode: 0o755 });
 
-  console.log(`[atomic] Session: ${tmuxSessionName} (FYI all atomic sessions run on tmux -L ${SOCKET_NAME})`);
-
-  // Attach or spawn depending on whether we're already inside tmux
-  if (tmux.isInsideTmux()) {
-    // Inside tmux: create the session with just a shell (agent windows live here),
-    // then run the orchestrator directly in the user's current pane.
-    const defaultShell = process.env.SHELL || (isWin ? "pwsh" : "sh");
-    tmux.createSession(tmuxSessionName, defaultShell, "orchestrator");
-
-    const launcherCmd = isWin
-      ? ["pwsh", "-NoProfile", "-File", launcherPath]
-      : ["bash", launcherPath];
-    const proc = Bun.spawn(launcherCmd, {
-      stdio: ["inherit", "inherit", "inherit"],
-      cwd: projectRoot,
-    });
-    await proc.exited;
+  const shellCmd = isWin
+    ? `pwsh -NoProfile -File "${escPwsh(launcherPath)}"`
+    : `bash "${escBash(launcherPath)}"`;
+  tmux.createSession(tmuxSessionName, shellCmd, "orchestrator");
+  tmux.setSessionEnv(tmuxSessionName, "ATOMIC_AGENT", agent);
+
+  if (tmux.isInsideAtomicSocket()) {
+    // Already on the atomic server — just switch to the new session.
+    tmux.switchClient(tmuxSessionName);
+  } else if (tmux.isInsideTmux()) {
+    // Inside a different tmux server — detach and replace the client
+    // with an attach to the atomic socket (no nesting).
+    tmux.detachAndAttachAtomic(tmuxSessionName);
   } else {
-    // Outside tmux: create session with the orchestrator and attach to it
-    const shellCmd = isWin
-      ? `pwsh -NoProfile -File "${escPwsh(launcherPath)}"`
-      : `bash "${escBash(launcherPath)}"`;
-    tmux.createSession(tmuxSessionName, shellCmd, "orchestrator");
-
     const attachProc = spawnMuxAttach(tmuxSessionName);
     await attachProc.exited;
   }

package/src/sdk/runtime/tmux.conf

@@ -21,6 +21,8 @@ set -g focus-events on
 setw -g aggressive-resize on
 
 # Status bar — minimal
+# These defaults are mirrored by TMUX_DEFAULT_STATUS_* constants in tmux.ts.
+# Keep both in sync when changing.
 set -g status-left " "
 set -g status-right " #{session_name} | %H:%M "
 set -g status-right-length 60
@@ -43,6 +45,22 @@ bind-key -T copy-mode-vi v send-keys -X begin-selection
 bind-key -T copy-mode-vi C-v send-keys -X rectangle-toggle
 bind-key -T copy-mode-vi y send-keys -X copy-selection-and-cancel
 
+# ── Atomic workflow navigation (prefix-free) ──────────────
+# These bindings use `bind -n` (root table) so they work without a prefix key.
+# They only apply inside Atomic's isolated tmux server (-L atomic) and do NOT
+# affect the user's regular tmux or shell sessions.
+#
+# NOTE: Ctrl+\ overrides the default SIGQUIT signal.  Agent CLIs running in
+# these panes will not receive SIGQUIT via Ctrl+\.  Use `kill -QUIT <pid>` if
+# needed.  The integrated agents (Claude Code, OpenCode, Copilot CLI) use
+# Ctrl+C for interrupts and are not affected.
+
+# Ctrl+G: jump straight back to the graph (window 0) from any agent window
+bind -n C-g select-window -t :0
+
+# Ctrl+\: cycle to next agent window from anywhere
+bind -n C-\\ next-window
+
 # Escape exits copy-mode (clear selection first if one exists, otherwise cancel)
 bind-key -T copy-mode-vi Escape if-shell -F "#{selection_present}" "send-keys -X clear-selection" "send-keys -X cancel"
 

package/src/sdk/runtime/tmux.ts

@@ -30,6 +30,29 @@ export type TmuxResult =
 // Core tmux primitives
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// Default status-bar values — must match tmux.conf.
+// Centralised here so restore logic in session-graph-panel stays in sync.
+// ---------------------------------------------------------------------------
+
+export const TMUX_DEFAULT_STATUS_LEFT = " ";
+export const TMUX_DEFAULT_STATUS_LEFT_LENGTH = "10";
+export const TMUX_DEFAULT_STATUS_RIGHT = " #{session_name} | %H:%M ";
+export const TMUX_DEFAULT_STATUS_RIGHT_LENGTH = "60";
+
+/**
+ * Escape a string for safe interpolation into tmux format strings.
+ * Replaces `#` with `##` to prevent tmux from interpreting `#[...]`
+ * as style directives or `#(...)` as shell command expansions.
+ */
+export function escapeTmuxFormat(value: string): string {
+  return value.replace(/#/g, "##");
+}
+
+// ---------------------------------------------------------------------------
+// Core tmux primitives
+// ---------------------------------------------------------------------------
+
 /** Cached resolved multiplexer binary path. Resolved once on first use. */
 let resolvedMuxBinary: string | null | undefined; // undefined = not yet resolved
 
@@ -45,9 +68,14 @@ let resolvedMuxBinary: string | null | undefined; // undefined = not yet resolve
 export function getMuxBinary(): string | null {
   if (resolvedMuxBinary !== undefined) return resolvedMuxBinary;
 
+  // Bun.which() reads PATH from the original process environment at startup
+  // and ignores runtime mutations to process.env.PATH. Pass PATH explicitly
+  // so that callers who modify PATH (e.g. tests) get correct results.
+  const pathOpt = { PATH: process.env.PATH ?? "" };
+
   if (process.platform === "win32") {
     for (const candidate of ["psmux", "pmux", "tmux"]) {
-      if (Bun.which(candidate)) {
+      if (Bun.which(candidate, pathOpt)) {
         resolvedMuxBinary = candidate;
         return resolvedMuxBinary;
       }
@@ -57,7 +85,7 @@ export function getMuxBinary(): string | null {
   }
 
   // Unix / macOS
-  resolvedMuxBinary = Bun.which("tmux") ? "tmux" : null;
+  resolvedMuxBinary = Bun.which("tmux", pathOpt) ? "tmux" : null;
   return resolvedMuxBinary;
 }
 
@@ -83,6 +111,22 @@ export function isInsideTmux(): boolean {
   return process.env.TMUX !== undefined || process.env.PSMUX !== undefined;
 }
 
+/**
+ * Check if we're inside the atomic tmux socket specifically.
+ *
+ * The `TMUX` env var has the format `<socket_path>,<pid>,<index>`.
+ * On Unix this looks like `/tmp/tmux-1000/atomic,12345,0` when the
+ * socket name is "atomic".
+ */
+export function isInsideAtomicSocket(): boolean {
+  const tmuxEnv = process.env.TMUX ?? process.env.PSMUX ?? "";
+  // Socket path is everything before the first comma.
+  const socketPath = tmuxEnv.split(",")[0] ?? "";
+  // The socket name is the last path segment.
+  const socketName = socketPath.split("/").pop() ?? "";
+  return socketName === SOCKET_NAME;
+}
+
 /**
  * Run a tmux command and return a result object.
  * Prefers this over the throwing `tmux()` for cases where callers
@@ -176,6 +220,9 @@ export function createSession(
   }
   args.push(initialCommand);
   const paneId = tmux(args);
+  // Reload config into the running server so keybindings are always current
+  // (tmux only loads -f on first server start; source-file updates a running server).
+  tmuxRun(["source-file", CONFIG_PATH]);
   return paneId || tmux(["list-panes", "-t", sessionName, "-F", "#{pane_id}"]).split("\n")[0]!;
 }
 
@@ -229,36 +276,17 @@ export function createPane(sessionName: string, command: string): string {
 // Keystroke sending
 // ---------------------------------------------------------------------------
 
-/**
- * Maximum bytes per `send-keys -l` invocation.
- *
- * tmux passes the text as a single command-line argument to the child
- * process. On Linux the per-argument limit (`MAX_ARG_STRLEN`) is 128 KB;
- * on macOS the total `ARG_MAX` is ~1 MB but shared across all args.
- * We stay well under both limits with 50 KB chunks.
- */
-const SEND_KEYS_CHUNK_SIZE = 50_000;
-
 /**
  * Send literal text to a tmux pane using `-l` flag (no special key interpretation).
  * Uses `--` to prevent text starting with `-` from being parsed as flags.
  *
- * Long texts are chunked to avoid OS `ARG_MAX` / `MAX_ARG_STRLEN` limits
- * that cause `tmux send-keys` to fail with "command too long".
+ * For large text payloads, prefer {@link sendViaPasteBuffer} which bypasses
+ * tmux's ~16 KB internal message buffer limit.
  */
 export function sendLiteralText(paneId: string, text: string): void {
   // Replace newlines with spaces to avoid premature submission
   const normalized = text.replace(/[\r\n]+/g, " ");
-
-  if (normalized.length <= SEND_KEYS_CHUNK_SIZE) {
-    tmuxExec(["send-keys", "-t", paneId, "-l", "--", normalized]);
-    return;
-  }
-
-  for (let offset = 0; offset < normalized.length; offset += SEND_KEYS_CHUNK_SIZE) {
-    const chunk = normalized.slice(offset, offset + SEND_KEYS_CHUNK_SIZE);
-    tmuxExec(["send-keys", "-t", paneId, "-l", "--", chunk]);
-  }
+  tmuxExec(["send-keys", "-t", paneId, "-l", "--", normalized]);
 }
 
 /**
@@ -398,6 +426,118 @@ export function sessionExists(sessionName: string): boolean {
   return result.ok;
 }
 
+/**
+ * Set a session-level environment variable.
+ * Uses `tmux set-environment -t <session>` so the value is scoped to
+ * the individual session, not the global server environment.
+ */
+export function setSessionEnv(sessionName: string, key: string, value: string): void {
+  tmuxRun(["set-environment", "-t", sessionName, key, value]);
+}
+
+/**
+ * Read a session-level environment variable.
+ * Returns `null` when the session doesn't exist or the variable isn't set.
+ */
+export function getSessionEnv(sessionName: string, key: string): string | null {
+  const result = tmuxRun(["show-environment", "-t", sessionName, key]);
+  if (!result.ok) return null;
+  // Output format: "KEY=VALUE"
+  const eq = result.stdout.indexOf("=");
+  return eq >= 0 ? result.stdout.slice(eq + 1) : null;
+}
+
+/** Session type derived from the session name prefix. */
+export type SessionType = "chat" | "workflow";
+
+/**
+ * Parse a session name into its type and agent.
+ *
+ * Naming conventions:
+ *   Chat:     atomic-chat-<agent>-<id>
+ *   Workflow:  atomic-wf-<agent>-<name>-<id>
+ *
+ * Agent names are a known, hyphen-free set (claude, copilot, opencode)
+ * so parsing is unambiguous even when the workflow name contains hyphens.
+ */
+export function parseSessionName(name: string): { type?: SessionType; agent?: string } {
+  const KNOWN_AGENTS = new Set(["claude", "copilot", "opencode"]);
+
+  if (name.startsWith("atomic-chat-")) {
+    // atomic-chat-<agent>-<id>
+    const rest = name.slice("atomic-chat-".length);
+    const dash = rest.indexOf("-");
+    const candidate = dash >= 0 ? rest.slice(0, dash) : rest;
+    if (KNOWN_AGENTS.has(candidate)) {
+      return { type: "chat", agent: candidate };
+    }
+    return { type: "chat" };
+  }
+
+  if (name.startsWith("atomic-wf-")) {
+    // atomic-wf-<agent>-<name>-<id>
+    const rest = name.slice("atomic-wf-".length);
+    const dash = rest.indexOf("-");
+    const candidate = dash >= 0 ? rest.slice(0, dash) : rest;
+    if (KNOWN_AGENTS.has(candidate)) {
+      return { type: "workflow", agent: candidate };
+    }
+    return { type: "workflow" };
+  }
+
+  return {};
+}
+
+/** A single tmux session on the atomic socket. */
+export interface TmuxSession {
+  /** Session name (e.g. "atomic-chat-claude-a1b2c3d4") */
+  name: string;
+  /** Number of windows in the session */
+  windows: number;
+  /** ISO 8601 creation timestamp */
+  created: string;
+  /** Whether a client is currently attached */
+  attached: boolean;
+  /** Session type derived from the name prefix */
+  type?: SessionType;
+  /** Agent backend that owns this session (e.g. "claude", "copilot", "opencode") */
+  agent?: string;
+}
+
+/**
+ * List all sessions on the atomic tmux socket.
+ *
+ * Uses a custom format string so output is machine-parseable regardless of
+ * locale. Returns an empty array when the server isn't running or has no
+ * sessions (tmux exits non-zero in both cases).
+ */
+export function listSessions(): TmuxSession[] {
+  const fmt = "#{session_name}\t#{session_windows}\t#{session_created}\t#{session_attached}";
+  const result = tmuxRun(["list-sessions", "-F", fmt]);
+  if (!result.ok) return [];
+
+  const sessions = result.stdout
+    .split("\n")
+    .filter((line) => line.trim() !== "")
+    .map((line) => {
+      const [name, windowsStr, createdStr, attachedStr] = line.split("\t");
+      const epochSec = Number(createdStr);
+      const parsed = parseSessionName(name!);
+      return {
+        name: name!,
+        windows: Number(windowsStr) || 1,
+        created: Number.isFinite(epochSec) && epochSec > 0
+          ? new Date(epochSec * 1000).toISOString()
+          : createdStr!,
+        attached: attachedStr === "1",
+        type: parsed.type,
+        agent: parsed.agent ?? getSessionEnv(name!, "ATOMIC_AGENT") ?? undefined,
+      };
+    });
+
+  return sessions;
+}
+
 /** Build the full argument list for an attach-session command. */
 function buildAttachArgs(sessionName: string): string[] {
   const binary = getMuxBinary();
@@ -450,6 +590,10 @@ export function switchClient(sessionName: string): void {
  */
 export function getCurrentSession(): string | null {
   if (!isInsideTmux()) return null;
+  // Only query the atomic server if we're actually inside the atomic socket.
+  // Otherwise, display-message picks an arbitrary session on the atomic
+  // server that has nothing to do with our terminal.
+  if (!isInsideAtomicSocket()) return null;
   const result = tmuxRun(["display-message", "-p", "#{session_name}"]);
   if (!result.ok) return null;
   return result.stdout || null;
@@ -470,6 +614,36 @@ export function attachOrSwitch(sessionName: string): void {
   }
 }
 
+/**
+ * Detach from the user's current tmux session and replace the client
+ * with an attach to a session on the atomic socket.
+ *
+ * Uses `detach-client -E` so the user's terminal seamlessly transitions
+ * from their tmux session to the atomic session — no nesting.
+ * Their original tmux session stays alive; they can re-attach with
+ * `tmux attach` after leaving the atomic session.
+ *
+ * Only call when {@link isInsideTmux} returns `true`.
+ */
+export function detachAndAttachAtomic(sessionName: string): void {
+  const binary = getMuxBinary();
+  if (!binary) {
+    throw new Error("No terminal multiplexer (tmux/psmux) found on PATH");
+  }
+  // Build the shell command that will run on the freed terminal.
+  const attachArgs = buildAttachArgs(sessionName);
+  const attachCmd = attachArgs
+    .map((a) => `"${a.replace(/[\\"$`!]/g, "\\$&")}"`)
+    .join(" ");
+
+  // Target the user's current tmux server (no -L flag) and replace
+  // the client process with an attach to the atomic socket.
+  Bun.spawnSync({
+    cmd: [binary, "detach-client", "-E", attachCmd],
+    stdio: ["inherit", "inherit", "inherit"],
+  });
+}
+
 /**
  * Select (switch to) a window within the current tmux session.
  */