very-happy-cli 0.2.97 → 0.2.98

package/dist/{types-xZOYW0_G.mjs → types-Cl4vWuDY.mjs}

@@ -29,7 +29,7 @@ import { SandboxManager } from '@anthropic-ai/sandbox-runtime';
 import { Expo } from 'expo-server-sdk';
 
 var name = "very-happy-cli";
-var version = "0.2.97";
+var version = "0.2.98";
 var description = "Remote multi-agent workspace CLI with deep Claude integration, native terminal streaming, and self-hosting.";
 var author = "Kirill Dubovitskiy";
 var contributors = [
@@ -142,12 +142,12 @@ var dependencies = {
 	zod: "^4.0.0"
 };
 var optionalDependencies = {
-	"very-happy-tools-arm64-darwin": "0.2.97",
-	"very-happy-tools-x64-darwin": "0.2.97",
-	"very-happy-tools-arm64-linux": "0.2.97",
-	"very-happy-tools-x64-linux": "0.2.97",
-	"very-happy-tools-arm64-win32": "0.2.97",
-	"very-happy-tools-x64-win32": "0.2.97"
+	"very-happy-tools-arm64-darwin": "0.2.98",
+	"very-happy-tools-x64-darwin": "0.2.98",
+	"very-happy-tools-arm64-linux": "0.2.98",
+	"very-happy-tools-x64-linux": "0.2.98",
+	"very-happy-tools-arm64-win32": "0.2.98",
+	"very-happy-tools-x64-win32": "0.2.98"
 };
 var devDependencies = {
 	"@slopus/happy-wire": "workspace:*",
@@ -1019,7 +1019,9 @@ const WebTerminalListItemSchema = z$1.object({
    *  conversation carried over, the processes did not. Cleared once opened. */
   restoredAt: z$1.number().optional(),
   /** B-265: @vh_title_manual is set (user renamed it). */
-  manual: z$1.boolean().optional()
+  manual: z$1.boolean().optional(),
+  /** B-273: opened attached to the user's tmux session of this name. */
+  attachTmux: z$1.string().optional()
 });
 const ClosedTerminalRecordSchema = z$1.object({
   id: z$1.string(),
@@ -1036,6 +1038,8 @@ const ClosedTerminalRecordSchema = z$1.object({
   /** B-265: tags + manual-rename flag at close time (restored verbatim). */
   tags: z$1.array(z$1.string()).optional(),
   manual: z$1.boolean().optional(),
+  /** B-273: attached user tmux session name — restore re-attaches. */
+  attachTmux: z$1.string().optional(),
   closedAt: z$1.number()
 });
 z$1.object({
@@ -1089,6 +1093,16 @@ z$1.object({
     rpcAvailable: z$1.boolean(),
     detectedAt: z$1.number()
   }).optional(),
+  /**
+   * B-273 capability flag: this daemon answers `list-tmux-sessions` and
+   * honours `open-terminal.attachTmux`. Same trust rule (`detectedAt >=
+   * startedAt`). Stamped unconditionally — on a machine without tmux the
+   * RPC just answers an empty list.
+   */
+  tmuxSessions: z$1.object({
+    rpcAvailable: z$1.boolean(),
+    detectedAt: z$1.number()
+  }).optional(),
   /** Relay-owned CLI compatibility/update policy last checked by this daemon. */
   cliUpdate: CliUpdateStateSchema.optional(),
   /**
@@ -4790,7 +4804,7 @@ function sanitizeLiveSnapshot(raw, now, ttlMs = LIVE_SNAPSHOT_TTL_MS, max = LIVE
   const rows = [];
   for (const [id, value] of Object.entries(raw)) {
     if (!id || !value || typeof value !== "object") continue;
-    const { title, cwd, seenAt, tags, manual } = value;
+    const { title, cwd, seenAt, tags, manual, attachTmux } = value;
     if (typeof seenAt !== "number" || !Number.isFinite(seenAt)) continue;
     if (now - seenAt >= ttlMs) continue;
     const tagList = sanitizeTagList(tags);
@@ -4799,6 +4813,7 @@ function sanitizeLiveSnapshot(raw, now, ttlMs = LIVE_SNAPSHOT_TTL_MS, max = LIVE
       cwd: typeof cwd === "string" && cwd ? cwd : void 0,
       ...tagList !== void 0 ? { tags: tagList } : {},
       ...manual === true ? { manual: true } : {},
+      ...typeof attachTmux === "string" && attachTmux ? { attachTmux } : {},
       seenAt
     }]);
   }
@@ -4819,6 +4834,7 @@ function liveSnapshotChanged(prev, next) {
     if (!before) return true;
     if (before.title !== info.title || before.cwd !== info.cwd) return true;
     if (!!before.manual !== !!info.manual) return true;
+    if ((before.attachTmux ?? "") !== (info.attachTmux ?? "")) return true;
     if ((before.tags ?? []).join("\0") !== (info.tags ?? []).join("\0")) return true;
   }
   return false;
@@ -4844,9 +4860,89 @@ function pickMirrorForTerminal(sessions, terminalId) {
   return best ? { sessionId: best.id, claudeSessionId: best.claude } : null;
 }
 
+function shellescape(s) {
+  return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+
+const USER_SESSION_FIELD_SEP = "<~|~>";
+const USER_SESSIONS_FORMAT = [
+  "#{session_id}",
+  "#{session_name}",
+  "#{session_windows}",
+  "#{session_attached}",
+  "#{session_activity}",
+  "#{session_created}",
+  "#{pane_current_command}",
+  "#{pane_current_path}"
+].join(USER_SESSION_FIELD_SEP);
+const TMUX_SESSION_ID_RE = /^\$\d{1,9}$/;
+const TMUX_SESSION_NAME_MAX = 128;
+function isSafeTmuxSessionName(name) {
+  if (typeof name !== "string") return false;
+  if (name.length === 0 || name.length > TMUX_SESSION_NAME_MAX) return false;
+  return !/[\x00-\x1f\x7f]/.test(name);
+}
+function isVhSessionName(name) {
+  return name.startsWith("vh-");
+}
+function parseUserSessionLine(line) {
+  if (!line) return void 0;
+  const parts = line.split(USER_SESSION_FIELD_SEP);
+  if (parts.length < 8) return void 0;
+  const [id, name, windows, attached, activity, created, command] = parts;
+  if (!TMUX_SESSION_ID_RE.test(id) || !isSafeTmuxSessionName(name)) return void 0;
+  const cwd = parts.slice(7).join(USER_SESSION_FIELD_SEP);
+  const num = (v) => {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : void 0;
+  };
+  return {
+    id,
+    name,
+    windows: Math.max(0, Math.floor(num(windows) ?? 0)),
+    attached: (num(attached) ?? 0) > 0,
+    activityAt: activity ? (num(activity) ?? 0) * 1e3 || void 0 : void 0,
+    createdAt: created ? (num(created) ?? 0) * 1e3 || void 0 : void 0,
+    command: command.trim() || void 0,
+    cwd: cwd || void 0
+  };
+}
+const USER_SESSIONS_MAX = 50;
+function parseUserSessions(stdout, max = USER_SESSIONS_MAX) {
+  const out = [];
+  for (const line of stdout.split("\n")) {
+    const s = parseUserSessionLine(line);
+    if (!s || isVhSessionName(s.name)) continue;
+    out.push(s);
+  }
+  out.sort((a, b) => (b.activityAt ?? 0) - (a.activityAt ?? 0));
+  return out.slice(0, max);
+}
+function attachStartupCommand(sessionId, socket) {
+  if (!TMUX_SESSION_ID_RE.test(sessionId)) throw new Error(`not a tmux session id: ${sessionId}`);
+  const sock = socket ? ` -S ${shellescape(socket)}` : "";
+  return ` TMUX= tmux${sock} attach-session -t ${shellescape(sessionId)}`;
+}
+
 const TERMINAL_ID_RE$1 = /^[a-zA-Z0-9_-]{1,64}$/;
 function planTerminalRestore(record, facts) {
   if (facts.tmuxAlive) return { kind: "already-live" };
+  if (record.attachTmux) {
+    const matches = (facts.userSessions ?? []).filter((s) => s.name === record.attachTmux);
+    if (matches.length !== 1) return { kind: "error", reason: "tmux-session-gone" };
+    const cwd = record.cwd && facts.cwdExists(record.cwd) ? record.cwd : facts.homeDir;
+    if (!cwd) return { kind: "error", reason: "missing-cwd" };
+    return {
+      kind: "create",
+      terminalId: record.id,
+      cwd,
+      title: record.title ?? record.attachTmux,
+      manual: true,
+      tags: record.tags,
+      command: attachStartupCommand(matches[0].id, facts.attachSocket),
+      attachTmux: record.attachTmux
+    };
+  }
   if (!record.cwd || !facts.cwdExists(record.cwd)) return { kind: "error", reason: "missing-cwd" };
   const resumable = isClaudeSessionId(record.claudeSessionId) && facts.conversationExists(record.cwd, record.claudeSessionId);
   return {
@@ -4860,6 +4956,20 @@ function planTerminalRestore(record, facts) {
   };
 }
 
+const VH_TMUX_SOCKET_ENV = "VH_TMUX_SOCKET";
+function tmuxSocketFlags(env = process.env) {
+  const socket = env[VH_TMUX_SOCKET_ENV];
+  return socket ? ["-S", socket] : [];
+}
+function tmuxArgs(args, env = process.env) {
+  return [...tmuxSocketFlags(env), ...args];
+}
+function scrubTmuxClientEnv(env) {
+  delete env.TMUX;
+  delete env.TMUX_PANE;
+  return env;
+}
+
 function getProjectPath(workingDirectory) {
   const projectId = resolve$1(workingDirectory).replace(/[^a-zA-Z0-9-]/g, "-");
   const claudeConfigDir = process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
@@ -9193,20 +9303,6 @@ function previewAscii(line) {
   return line.length > 80 ? `${out}\u2026` : out;
 }
 
-const VH_TMUX_SOCKET_ENV = "VH_TMUX_SOCKET";
-function tmuxSocketFlags(env = process.env) {
-  const socket = env[VH_TMUX_SOCKET_ENV];
-  return socket ? ["-S", socket] : [];
-}
-function tmuxArgs(args, env = process.env) {
-  return [...tmuxSocketFlags(env), ...args];
-}
-function scrubTmuxClientEnv(env) {
-  delete env.TMUX;
-  delete env.TMUX_PANE;
-  return env;
-}
-
 const CONTROL_CLIENT_KILL_GRACE_MS = 2e3;
 const CONTROL_COMMAND_TIMEOUT_MS = 1e4;
 function isSafeControlCommand(command) {
@@ -10024,7 +10120,7 @@ function sanitizeClosedTerminals(raw, max = CLOSED_TERMINALS_MAX) {
   const out = [];
   for (const item of raw) {
     if (!item || typeof item !== "object") continue;
-    const { id, title, cwd, mirrorSessionId, claudeSessionId, reason, closedAt, tags, manual } = item;
+    const { id, title, cwd, mirrorSessionId, claudeSessionId, reason, closedAt, tags, manual, attachTmux } = item;
     if (typeof id !== "string" || id.length === 0 || typeof closedAt !== "number") continue;
     if (seen.has(id)) continue;
     seen.add(id);
@@ -10038,6 +10134,7 @@ function sanitizeClosedTerminals(raw, max = CLOSED_TERMINALS_MAX) {
       reason: reason === "daemon-gap" || reason === "closed" ? reason : void 0,
       ...tagList !== void 0 ? { tags: tagList } : {},
       ...manual === true ? { manual: true } : {},
+      ...typeof attachTmux === "string" && attachTmux ? { attachTmux } : {},
       closedAt
     });
   }
@@ -10162,7 +10259,7 @@ function startupInjectionArgs(tmuxSession, command) {
   ];
 }
 function seenInfoOf(t) {
-  return { title: t.title, cwd: t.cwd, tags: t.tags, manual: t.manual };
+  return { title: t.title, cwd: t.cwd, tags: t.tags, manual: t.manual, attachTmux: t.attachTmux };
 }
 function terminalListSignature(items) {
   const canon = [...items].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0).map((t) => [
@@ -10175,7 +10272,8 @@ function terminalListSignature(items) {
     t.agentState ?? "",
     // B-105: a mirror binding appearing/disappearing MUST push the
     // list, or the web never learns the toggle became available.
-    t.mirrorSessionId ?? ""
+    t.mirrorSessionId ?? "",
+    t.attachTmux ?? ""
   ]);
   return JSON.stringify(canon);
 }
@@ -10194,7 +10292,7 @@ function deriveAutoTitle(paneTitle, hostname) {
   const chars = Array.from(t);
   return chars.length > TITLE_MAX_CHARS ? chars.slice(0, TITLE_MAX_CHARS).join("") : t;
 }
-const LIST_FIELD_SEP = "";
+const LIST_FIELD_SEP = "<~|~>";
 const LIST_SESSIONS_FORMAT = [
   "#{session_name}",
   "#{session_created}",
@@ -10203,6 +10301,9 @@ const LIST_SESSIONS_FORMAT = [
   "#{@vh_title}",
   "#{@vh_title_manual}",
   "#{@vh_tags}",
+  // B-273: the user tmux session this terminal was opened to attach (name),
+  // carried into close records so a restore can re-attach.
+  "#{@vh_attach}",
   // B-121: the control-mode client has no `pty.process`, so the agent-state
   // fast path lost its live `#{pane_current_command}` equivalent. Carry it in
   // the ONE list-sessions call the tracker already makes — the value goes
@@ -10217,8 +10318,8 @@ const LIST_SESSIONS_FORMAT = [
 function parseSessionListLine(line) {
   if (!line) return void 0;
   const parts = line.split(LIST_FIELD_SEP);
-  if (parts.length < 9) return void 0;
-  const [name, created, activity, cwd, vhTitle, manual, vhTags, paneCommand] = parts;
+  if (parts.length < 10) return void 0;
+  const [name, created, activity, cwd, vhTitle, manual, vhTags, vhAttach, paneCommand] = parts;
   if (!name) return void 0;
   return {
     name,
@@ -10229,9 +10330,12 @@ function parseSessionListLine(line) {
     manual: manual.trim().length > 0,
     tags: parseTerminalTags(vhTags),
     paneCurrentCommand: paneCommand.trim() || void 0,
-    // pane_title is last, so anything after field 8 is title content that
+    // Verbatim (no trim): tmux allows edge spaces in a session name and the
+    // restore lookup / attach echo compare it exactly.
+    attachTmux: isSafeTmuxSessionName(vhAttach) ? vhAttach : void 0,
+    // pane_title is last, so anything after field 9 is title content that
     // contained the separator — rejoin it rather than dropping it.
-    paneTitle: parts.slice(8).join(LIST_FIELD_SEP) || void 0
+    paneTitle: parts.slice(9).join(LIST_FIELD_SEP) || void 0
   };
 }
 const TERMINAL_TAG_MAX_COUNT = 64;
@@ -10288,12 +10392,12 @@ function isClaudeConfident(tail) {
   const last15 = lines.slice(-15).join("\n");
   return last15.includes("Do you want") || last15.includes("Would you like to proceed") || /^[\s│]*[❯>]\s*1\.\s/m.test(last15) || text.includes("esc to interrupt") || text.includes("? for shortcuts") || text.includes("bypass permissions on") || text.includes("\u23F5\u23F5");
 }
-function planScrollAction(paneInMode, alternateOn, paneWantsMouse, lines, claudeLike = false, paneRows = 24) {
+function planScrollAction(paneInMode, alternateOn, paneWantsMouse, lines, claudeLike = false, paneRows = 24, nestedTmux = false) {
   const count = Math.min(Math.abs(Math.trunc(lines)), 200);
   if (count === 0) return { kind: "none" };
   const up = lines > 0;
   if (paneInMode) return { kind: "copy-scroll", dir: up ? "up" : "down", count };
-  if (alternateOn && paneWantsMouse) return { kind: "mouse-wheel", dir: up ? "up" : "down", count };
+  if (alternateOn && (paneWantsMouse || nestedTmux)) return { kind: "mouse-wheel", dir: up ? "up" : "down", count };
   if (alternateOn && claudeLike) {
     const halfPage = Math.max(1, Math.floor(paneRows / 2));
     const pages = Math.max(1, Math.round(count / halfPage));
@@ -10408,6 +10512,9 @@ class TerminalSession {
   id;
   tmuxSession;
   transport;
+  /** B-273: the user tmux session this terminal was created to attach —
+   *  echoed to any later open of the same live session. */
+  attachedTmux;
   /**
    * The pane this terminal follows, latched from the open capture's
    * `list-panes` (first pane of the window). `%output` from any OTHER pane is
@@ -10918,6 +11025,7 @@ class WebTerminalManager {
         cwd: info.cwd,
         tags: info.tags,
         manual: info.manual,
+        ...info.attachTmux ? { attachTmux: info.attachTmux } : {},
         // Live binding first (authoritative while it exists), persisted
         // metadata as the fallback once the mirror has been torn down.
         mirrorSessionId: this.mirrorResolver?.(id) ?? mirror?.sessionId,
@@ -10970,6 +11078,7 @@ class WebTerminalManager {
         cwd: info.cwd,
         tags: info.tags,
         manual: info.manual,
+        ...info.attachTmux ? { attachTmux: info.attachTmux } : {},
         mirrorSessionId: mirror?.sessionId,
         claudeSessionId: mirror?.claudeSessionId,
         reason: "daemon-gap",
@@ -11089,12 +11198,17 @@ class WebTerminalManager {
           return false;
         }
       },
-      conversationExists: (cwd, claudeSessionId) => existsSync(join(getProjectPath(cwd), `${claudeSessionId}.jsonl`))
+      conversationExists: (cwd, claudeSessionId) => existsSync(join(getProjectPath(cwd), `${claudeSessionId}.jsonl`)),
+      // B-273: only consulted for records that were attach terminals.
+      // Unbounded: the panel's 50-row cap must not hide a restore target.
+      userSessions: record.attachTmux ? this.listUserTmuxSessions(Infinity) : [],
+      attachSocket: process.env[VH_TMUX_SOCKET_ENV],
+      homeDir: os$1.homedir()
     });
     if (plan.kind === "already-live") return { type: "success", terminalId };
     if (plan.kind === "error") return { type: "error", reason: plan.reason };
     if (!this.createDetachedTerminal(plan)) return { type: "error", reason: "create-failed" };
-    logger.info(`[WEB TERMINAL] restored closed terminal ${terminalId} in ${plan.cwd}${plan.command ? " (conversation resumed)" : ""}`);
+    logger.info(`[WEB TERMINAL] restored closed terminal ${terminalId} in ${plan.cwd}${plan.attachTmux ? ` (attached tmux session ${plan.attachTmux})` : plan.command ? " (conversation resumed)" : ""}`);
     this.kickListRefresh();
     return { type: "success", terminalId };
   }
@@ -11154,6 +11268,13 @@ class WebTerminalManager {
         { stdio: "ignore", timeout: TMUX_PROBE_TIMEOUT_MS, env }
       );
     }
+    if (plan.attachTmux) {
+      spawnSync(
+        "tmux",
+        tmuxArgs(["set-option", "-t", `=${name}:`, "@vh_attach", plan.attachTmux]),
+        { stdio: "ignore", timeout: TMUX_PROBE_TIMEOUT_MS, env }
+      );
+    }
     if (plan.command) {
       for (const argv of startupInjectionArgs(name, plan.command)) {
         spawnSync("tmux", tmuxArgs(argv), { stdio: "ignore", timeout: TMUX_PROBE_TIMEOUT_MS, env });
@@ -11166,7 +11287,7 @@ class WebTerminalManager {
    *  would care about changed (see liveSnapshotChanged). */
   persistLiveSnapshot(live, now) {
     const candidate = /* @__PURE__ */ new Map();
-    for (const [id, info] of live) candidate.set(id, { title: info.title, cwd: info.cwd, tags: info.tags, manual: info.manual, seenAt: now });
+    for (const [id, info] of live) candidate.set(id, { title: info.title, cwd: info.cwd, tags: info.tags, manual: info.manual, ...info.attachTmux ? { attachTmux: info.attachTmux } : {}, seenAt: now });
     if (!liveSnapshotChanged(this.lastPersistedSnapshot, candidate)) return;
     this.lastPersistedSnapshot = candidate;
     saveLiveSnapshot(candidate);
@@ -11264,6 +11385,7 @@ class WebTerminalManager {
     const lines = opts.streamMode === "lines";
     const existing = this.terminals.get(id);
     if (existing) {
+      const echo2 = opts.attachTmux && !(opts.attachOnly || opts.resub) && existing.attachedTmux?.name === opts.attachTmux.name ? { attachedTmux: existing.attachedTmux } : {};
       if (!opts.resub || existing.subscribers === 0) existing.subscribers += 1;
       existing.lastTouch = Date.now();
       this.applyResize(existing, cols, rows);
@@ -11276,15 +11398,16 @@ class WebTerminalManager {
           seq: existing.seq,
           mode: "replay",
           chunks,
-          ...lines ? { streamMode: "lines" } : {}
+          ...lines ? { streamMode: "lines" } : {},
+          ...echo2
         };
       }
       if (lines && existing.transport.kind === "control") {
-        return await this.linesSnapshotResponse(id, existing);
+        return { ...await this.linesSnapshotResponse(id, existing), ...echo2 };
       }
       const state = existing.subscribeState(opts.fromSeq);
       logger.debug(`[WEB TERMINAL] re-subscribed ${id} (subs=${existing.subscribers}, mode=${state.mode}, seq=${state.seq})`);
-      return { terminalId: id, tmuxSession: existing.tmuxSession, ...state };
+      return { terminalId: id, tmuxSession: existing.tmuxSession, ...state, ...echo2 };
     }
     if (opts.attachOnly || opts.resub) {
       const alive = isTmuxAvailable() && spawnSync(
@@ -11309,6 +11432,10 @@ class WebTerminalManager {
     let file = defaultShell();
     let args = [];
     let tmuxSession;
+    let attachedTmux;
+    if (opts.attachTmux && !(opts.attachOnly || opts.resub) && !isTmuxAvailable()) {
+      throw new Error("tmux-unavailable");
+    }
     if (isTmuxAvailable()) {
       tmuxSession = `vh-${id}`;
       let createdNew = false;
@@ -11321,6 +11448,7 @@ class WebTerminalManager {
         `VH_HAPPY_HOME_DIR=${configuration.happyHomeDir}`
       ] : [];
       const attachOnly = !!(opts.attachOnly || opts.resub);
+      const attachTarget = !attachOnly && opts.attachTmux ? this.resolveAttachTarget(opts.attachTmux) : void 0;
       if (!attachOnly) {
         try {
           const created = spawnSync(
@@ -11362,16 +11490,15 @@ class WebTerminalManager {
         }
       }
       if (createdNew) {
-        const startup = normalizeStartupCommand(opts.startupCommand);
-        if (startup) {
-          try {
-            for (const a of startupInjectionArgs(tmuxSession, startup)) {
-              spawnSync("tmux", tmuxArgs(a), { stdio: "ignore", timeout: TMUX_PROBE_TIMEOUT_MS, env });
-            }
-            logger.debug(`[WEB TERMINAL] injected startup command into new session ${tmuxSession}`);
-          } catch {
-          }
-        }
+        attachedTmux = this.injectIntoCreated(tmuxSession, attachTarget, opts.startupCommand, env);
+      } else if (opts.attachTmux && !attachOnly) {
+        const stored = spawnSync(
+          "tmux",
+          tmuxArgs(["show-options", "-qv", "-t", `=${tmuxSession}:`, "@vh_attach"]),
+          { encoding: "utf8", timeout: TMUX_PROBE_TIMEOUT_MS, env }
+        );
+        const name = stored.status === 0 && typeof stored.stdout === "string" ? stored.stdout.replace(/\r?\n$/, "") : "";
+        if (name && name === opts.attachTmux.name) attachedTmux = { id: opts.attachTmux.id, name };
       }
       if (!attachOnly && !createdNew) {
         const alive = spawnSync(
@@ -11386,17 +11513,7 @@ class WebTerminalManager {
             { stdio: "ignore", timeout: TMUX_CREATE_TIMEOUT_MS, env }
           );
           createdNew = retry.status === 0;
-          if (createdNew) {
-            const startup = normalizeStartupCommand(opts.startupCommand);
-            if (startup) {
-              for (const a of startupInjectionArgs(tmuxSession, startup)) {
-                try {
-                  spawnSync("tmux", tmuxArgs(a), { stdio: "ignore", timeout: TMUX_PROBE_TIMEOUT_MS, env });
-                } catch {
-                }
-              }
-            }
-          }
+          if (createdNew) attachedTmux = this.injectIntoCreated(tmuxSession, attachTarget, opts.startupCommand, env);
         }
       }
       if (!attachOnly && !createdNew) {
@@ -11406,6 +11523,7 @@ class WebTerminalManager {
           { stdio: "ignore", timeout: TMUX_PROBE_TIMEOUT_MS, env }
         ).status === 0;
         if (!alive) {
+          if (attachTarget) throw new Error("tmux-unavailable");
           logger.info(`[WEB TERMINAL] tmux session creation unavailable; using direct PTY for ${id}`);
           tmuxSession = void 0;
         }
@@ -11488,20 +11606,110 @@ class WebTerminalManager {
       session = created;
     }
     session.subscribers = 1;
+    if (attachedTmux) session.attachedTmux = attachedTmux;
     this.terminals.set(id, session);
     session.onTitleChange(() => this.kickListRefresh());
     logger.debug(`[WEB TERMINAL] opened ${id} (${tmuxSession ? "control" : "pty"}) ${cols}x${rows} cwd=${cwd}`);
     this.kickListRefresh();
+    const echo = attachedTmux ? { attachedTmux } : {};
     if (session.transport.kind !== "control") {
       const state = session.subscribeState(void 0);
-      return { terminalId: id, tmuxSession, ...state, ...lines ? { streamMode: "lines" } : {} };
+      return { terminalId: id, tmuxSession, ...state, ...lines ? { streamMode: "lines" } : {}, ...echo };
     }
     const restored = await this.captureRestore(session, true);
     if (!lines) {
       const state = session.subscribeState(void 0);
-      return { terminalId: id, tmuxSession, ...state };
+      return { terminalId: id, tmuxSession, ...state, ...echo };
+    }
+    return { ...this.linesResponse(id, session, restored), ...echo };
+  }
+  /**
+   * Post-create injection shared by BOTH creation sites in open(): an attach
+   * request (B-273) pins the title to the user session's name (the inner
+   * tmux's pane title is not reliable), stores `@vh_attach` for close
+   * records / restore and types the attach line; otherwise the ordinary
+   * startup command runs. Returns what to echo as `attachedTmux`.
+   */
+  injectIntoCreated(tmuxSession, attachTarget, startupCommand, env) {
+    if (attachTarget) {
+      for (const a of [
+        ["set-option", "-t", `=${tmuxSession}:`, "@vh_title", attachTarget.name],
+        ["set-option", "-t", `=${tmuxSession}:`, "@vh_title_manual", "1"],
+        ["set-option", "-t", `=${tmuxSession}:`, "@vh_attach", attachTarget.name],
+        ...startupInjectionArgs(tmuxSession, attachStartupCommand(attachTarget.id, process.env[VH_TMUX_SOCKET_ENV]))
+      ]) {
+        try {
+          spawnSync("tmux", tmuxArgs(a), { stdio: "ignore", timeout: TMUX_PROBE_TIMEOUT_MS, env });
+        } catch {
+        }
+      }
+      logger.debug(`[WEB TERMINAL] ${tmuxSession} attaches user tmux session ${attachTarget.id} (${attachTarget.name})`);
+      return { id: attachTarget.id, name: attachTarget.name };
+    }
+    const startup = normalizeStartupCommand(startupCommand);
+    if (startup) {
+      try {
+        for (const a of startupInjectionArgs(tmuxSession, startup)) {
+          spawnSync("tmux", tmuxArgs(a), { stdio: "ignore", timeout: TMUX_PROBE_TIMEOUT_MS, env });
+        }
+        logger.debug(`[WEB TERMINAL] injected startup command into new session ${tmuxSession}`);
+      } catch {
+      }
+    }
+    return void 0;
+  }
+  /**
+   * B-273: check an attach request against the live tmux server. The id
+   * must be a real `$N` (session ids only reset when the tmux server
+   * restarts, so a stale id from an older list simply does not exist)
+   * whose CURRENT name equals the name the web saw — the name cross-check
+   * is what refuses a target that was killed and re-created in between —
+   * and must not be a vh-* web terminal. Throws the 'tmux-session-gone'
+   * contract string. Note `display-message -t '$N'` exits 0 with an EMPTY
+   * line for an unknown id (its target lookup may fail silently), which is
+   * why existence is probed with `has-session` first.
+   */
+  resolveAttachTarget(req) {
+    const id = typeof req?.id === "string" ? req.id : "";
+    const name = typeof req?.name === "string" ? req.name : "";
+    if (!TMUX_SESSION_ID_RE.test(id) || !isSafeTmuxSessionName(name) || isVhSessionName(name)) throw new Error("tmux-session-gone");
+    const env = ptyEnv();
+    const exists = spawnSync("tmux", tmuxArgs(["has-session", "-t", id]), { stdio: "ignore", timeout: TMUX_PROBE_TIMEOUT_MS, env }).status === 0;
+    if (!exists) throw new Error("tmux-session-gone");
+    const r = spawnSync(
+      "tmux",
+      tmuxArgs(["display-message", "-p", "-t", id, "#{session_name}"]),
+      { encoding: "utf8", timeout: TMUX_PROBE_TIMEOUT_MS, env }
+    );
+    const current = r.status === 0 && typeof r.stdout === "string" ? r.stdout.replace(/\r?\n$/, "") : void 0;
+    if (current !== name) throw new Error("tmux-session-gone");
+    return { id, name };
+  }
+  /** B-273: the user's own tmux sessions (never vh-*), newest activity
+   *  first. Empty when tmux is missing or no server runs. */
+  /** Last raw outcome of the list-tmux-sessions spawn (diagnostics only). */
+  lastUserSessionsProbe;
+  listUserTmuxSessions(max) {
+    if (!isTmuxAvailable()) {
+      this.lastUserSessionsProbe = { status: null, error: "tmux-unavailable", stdoutBytes: 0 };
+      return [];
+    }
+    try {
+      const r = spawnSync(
+        "tmux",
+        tmuxArgs(["list-sessions", "-F", USER_SESSIONS_FORMAT]),
+        { encoding: "utf8", timeout: TMUX_CREATE_TIMEOUT_MS, env: ptyEnv() }
+      );
+      this.lastUserSessionsProbe = { status: r.status, error: r.error?.message, stderr: (r.stderr || "").toString().trim() || void 0, stdoutBytes: typeof r.stdout === "string" ? r.stdout.length : 0 };
+      if (r.status !== 0 || typeof r.stdout !== "string") {
+        logger.debug(`[WEB TERMINAL] list-tmux-sessions failed: ${JSON.stringify(this.lastUserSessionsProbe)}`);
+        return [];
+      }
+      return parseUserSessions(r.stdout, max);
+    } catch (e) {
+      this.lastUserSessionsProbe = { status: null, error: e instanceof Error ? e.message : String(e), stdoutBytes: 0 };
+      return [];
     }
-    return this.linesResponse(id, session, restored);
   }
   /**
    * Run the opening/catch-up capture for a control session and prime the
@@ -11743,6 +11951,7 @@ class WebTerminalManager {
         cwd: info.cwd,
         tags: info.tags,
         manual: info.manual,
+        ...info.attachTmux ? { attachTmux: info.attachTmux } : {},
         mirrorSessionId: this.mirrorResolver?.(terminalId) ?? mirror?.sessionId,
         claudeSessionId: mirror?.claudeSessionId,
         reason: "closed",
@@ -11831,7 +12040,8 @@ class WebTerminalManager {
           // Daemon-internal (not pushed to web / not in the signature):
           // the mirror reconciler's stricter "claude is really here" gate.
           claudeConfident: probe.claudeConfident,
-          manual: s.manual
+          manual: s.manual,
+          ...s.attachTmux ? { attachTmux: s.attachTmux } : {}
         });
       }
       return out;
@@ -11898,18 +12108,19 @@ class WebTerminalManager {
     try {
       const probe = spawnSync(
         "tmux",
-        tmuxArgs(["display-message", "-p", "-t", name, "#{pane_in_mode}	#{alternate_on}	#{mouse_any_flag}	#{pane_width}	#{pane_height}	#{pane_current_command}"]),
+        tmuxArgs(["display-message", "-p", "-t", name, ["#{pane_in_mode}", "#{alternate_on}", "#{mouse_any_flag}", "#{pane_width}", "#{pane_height}", "#{pane_current_command}"].join(LIST_FIELD_SEP)]),
         { encoding: "utf8", timeout: TMUX_PROBE_TIMEOUT_MS, env: ptyEnv() }
       );
       if (probe.status !== 0 || typeof probe.stdout !== "string") return;
-      const [inMode, altOn, wantsMouse, paneW, paneH, paneCmd] = probe.stdout.trim().split("	");
+      const [inMode, altOn, wantsMouse, paneW, paneH, paneCmd] = probe.stdout.trim().split(LIST_FIELD_SEP);
       const action = planScrollAction(
         inMode === "1",
         altOn === "1",
         wantsMouse === "1",
         lines,
         looksLikeClaudeCommand(paneCmd || ""),
-        Number(paneH) || 24
+        Number(paneH) || 24,
+        (paneCmd || "").trim() === "tmux"
       );
       if (action.kind === "none") return;
       if (action.kind === "mouse-wheel") {
@@ -13921,7 +14132,8 @@ class ApiMachineClient {
     this.syncResumeSessionRpcRegistration();
     this.syncRestartSessionRpcRegistration();
     this.rpcHandlerManager.registerHandler("open-terminal", async (params) => {
-      const { terminalId, cols, rows, cwd, fromSeq, encStream, startupCommand, resub, attachOnly, streamMode } = params || {};
+      const { terminalId, cols, rows, cwd, fromSeq, encStream, startupCommand, resub, attachOnly, streamMode, attachTmux } = params || {};
+      const attach = attachTmux && typeof attachTmux === "object" && typeof attachTmux.id === "string" && typeof attachTmux.name === "string" ? { id: attachTmux.id, name: attachTmux.name } : void 0;
       const result = await this.webTerminal.open({
         terminalId,
         cols,
@@ -13931,7 +14143,8 @@ class ApiMachineClient {
         startupCommand,
         resub,
         attachOnly,
-        streamMode: streamMode === "lines" ? "lines" : void 0
+        streamMode: streamMode === "lines" ? "lines" : void 0,
+        ...attach ? { attachTmux: attach } : {}
       });
       if (encStream) {
         this.encTerminals.add(result.terminalId);
@@ -14006,6 +14219,9 @@ class ApiMachineClient {
     this.rpcHandlerManager.registerHandler("list-terminals", async () => {
       return { type: "success", terminals: this.webTerminal.buildTerminalList() };
     });
+    this.rpcHandlerManager.registerHandler("list-tmux-sessions", async () => {
+      return { type: "success", sessions: this.webTerminal.listUserTmuxSessions() };
+    });
     this.rpcHandlerManager.registerHandler("set-terminal-title", async (params) => {
       const { terminalId, title, ifAbsent } = params || {};
       if (!terminalId || typeof title !== "string") {
@@ -14399,6 +14615,8 @@ class ApiMachineClient {
         // B-265 capability flag; restamped every connect so the
         // web's `detectedAt >= startedAt` trust rule holds.
         terminalRestore: { rpcAvailable: true, detectedAt: now },
+        // B-273 capability flag (same restamp discipline).
+        tmuxSessions: { rpcAvailable: true, detectedAt: now },
         // B-084: closed records survive daemon restarts (persisted
         // in closed-terminals.json), so the connect snapshot ships
         // them too — not just the incremental pushes.
@@ -15740,4 +15958,4 @@ const RawJSONLinesSchema = z$1.discriminatedUnion("type", [
   }).passthrough()
 ]);
 
-export { detectResumeSupport as $, ApiClient as A, deriveLocalCliUpdateSummary as B, updateSettings as C, encodeBase64Url as D, decodeBase64 as E, writeCredentialsLegacy as F, writeCredentialsDataKey as G, readCredentialsForConfiguredRelay as H, InvalidateSync as I, encrypt as J, isClaudeSessionId as K, getLocalHappyAgentCredentialPath as L, MAX_CHAT_ATTACHMENT_SOURCE_BYTES as M, readLocalHappyAgentCredentials as N, decryptWithDataKey as O, decryptLegacy as P, extractCompleteLines as Q, RawJSONLinesSchema as R, decideBackfill as S, parseTerminalHookPayload as T, tmuxArgs as U, scrubTmuxClientEnv as V, decideMirrorBinding as W, MIRROR_BACKFILL_LINES_DEFAULT as X, persistSession as Y, mirrorLineKey as Z, mirrorLocalId as _, ApiSessionClient as a, detectCLIAvailability as a0, acquireDaemonLock as a1, summarizeSpawnSessionForLog as a2, deletePersistedSessions as a3, decrypt as a4, writeDaemonState as a5, writeSettings as a6, fetchCliUpdateState as a7, resolveCliUpdateCheckInterval as a8, DEFAULT_CLI_UPDATE_CHECK_INTERVAL_MS as a9, releaseDaemonLock as aa, isValidSessionId as ab, listVhTerminals as ac, isValidTerminalId as ad, readVhTerminal as ae, sendToVhTerminal as af, startOfflineReconnection as ag, clearCredentials as ah, clearMachineId as ai, SandboxConfigSchema as aj, CodexAppServerClient as ak, getLatestDaemonLog as al, persistence as am, api as an, createEnvelope as b, configuration as c, contentLogMetadata as d, errorLogMetadata as e, packageJson as f, delay as g, connectionState as h, readSettings as i, encodeBase64 as j, ensurePrivateDirectorySync as k, logger as l, hardenPrivateFileSync as m, readDaemonState as n, clearDaemonState as o, projectPath as p, getProjectPath as q, readPersistedSessions as r, initializeSandbox as s, wrapCommand as t, AsyncLock as u, ensurePrivateDirectory as v, writePrivateFileSync as w, hardenPrivateFile as x, readCredentials as y, credentialRelayProblem as z };
+export { detectResumeSupport as $, ApiClient as A, deriveLocalCliUpdateSummary as B, updateSettings as C, encodeBase64Url as D, decodeBase64 as E, writeCredentialsLegacy as F, writeCredentialsDataKey as G, readCredentialsForConfiguredRelay as H, InvalidateSync as I, encrypt as J, isClaudeSessionId as K, getLocalHappyAgentCredentialPath as L, MAX_CHAT_ATTACHMENT_SOURCE_BYTES as M, readLocalHappyAgentCredentials as N, decryptWithDataKey as O, decryptLegacy as P, extractCompleteLines as Q, RawJSONLinesSchema as R, decideBackfill as S, parseTerminalHookPayload as T, tmuxArgs as U, scrubTmuxClientEnv as V, decideMirrorBinding as W, MIRROR_BACKFILL_LINES_DEFAULT as X, persistSession as Y, mirrorLineKey as Z, mirrorLocalId as _, ApiSessionClient as a, detectCLIAvailability as a0, acquireDaemonLock as a1, summarizeSpawnSessionForLog as a2, deletePersistedSessions as a3, shellescape as a4, decrypt as a5, writeDaemonState as a6, writeSettings as a7, fetchCliUpdateState as a8, resolveCliUpdateCheckInterval as a9, DEFAULT_CLI_UPDATE_CHECK_INTERVAL_MS as aa, releaseDaemonLock as ab, isValidSessionId as ac, listVhTerminals as ad, isValidTerminalId as ae, readVhTerminal as af, sendToVhTerminal as ag, startOfflineReconnection as ah, clearCredentials as ai, clearMachineId as aj, SandboxConfigSchema as ak, CodexAppServerClient as al, getLatestDaemonLog as am, persistence as an, api as ao, createEnvelope as b, configuration as c, contentLogMetadata as d, errorLogMetadata as e, packageJson as f, delay as g, connectionState as h, readSettings as i, encodeBase64 as j, ensurePrivateDirectorySync as k, logger as l, hardenPrivateFileSync as m, readDaemonState as n, clearDaemonState as o, projectPath as p, getProjectPath as q, readPersistedSessions as r, initializeSandbox as s, wrapCommand as t, AsyncLock as u, ensurePrivateDirectory as v, writePrivateFileSync as w, hardenPrivateFile as x, readCredentials as y, credentialRelayProblem as z };