very-happy-cli 0.2.97 → 0.2.98

package/dist/{types-DoGaKVfK.cjs → types-BP-4phS_.cjs}

@@ -51,7 +51,7 @@ var z__namespace = /*#__PURE__*/_interopNamespaceDefault(z);
 var pty__namespace = /*#__PURE__*/_interopNamespaceDefault(pty);
 
 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 = [
@@ -164,12 +164,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:*",
@@ -1041,7 +1041,9 @@ const WebTerminalListItemSchema = z.z.object({
    *  conversation carried over, the processes did not. Cleared once opened. */
   restoredAt: z.z.number().optional(),
   /** B-265: @vh_title_manual is set (user renamed it). */
-  manual: z.z.boolean().optional()
+  manual: z.z.boolean().optional(),
+  /** B-273: opened attached to the user's tmux session of this name. */
+  attachTmux: z.z.string().optional()
 });
 const ClosedTerminalRecordSchema = z.z.object({
   id: z.z.string(),
@@ -1058,6 +1060,8 @@ const ClosedTerminalRecordSchema = z.z.object({
   /** B-265: tags + manual-rename flag at close time (restored verbatim). */
   tags: z.z.array(z.z.string()).optional(),
   manual: z.z.boolean().optional(),
+  /** B-273: attached user tmux session name — restore re-attaches. */
+  attachTmux: z.z.string().optional(),
   closedAt: z.z.number()
 });
 z.z.object({
@@ -1111,6 +1115,16 @@ z.z.object({
     rpcAvailable: z.z.boolean(),
     detectedAt: z.z.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.z.object({
+    rpcAvailable: z.z.boolean(),
+    detectedAt: z.z.number()
+  }).optional(),
   /** Relay-owned CLI compatibility/update policy last checked by this daemon. */
   cliUpdate: CliUpdateStateSchema.optional(),
   /**
@@ -1569,7 +1583,7 @@ class RpcHandlerManager {
   }
 }
 
-const __dirname$1 = path$1.dirname(url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('types-DoGaKVfK.cjs', document.baseURI).href))));
+const __dirname$1 = path$1.dirname(url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('types-BP-4phS_.cjs', document.baseURI).href))));
 function projectPath() {
   const path = path$1.resolve(__dirname$1, "..");
   return path;
@@ -4812,7 +4826,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);
@@ -4821,6 +4835,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
     }]);
   }
@@ -4841,6 +4856,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;
@@ -4866,9 +4882,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 {
@@ -4882,6 +4978,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 = path.resolve(workingDirectory).replace(/[^a-zA-Z0-9-]/g, "-");
   const claudeConfigDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
@@ -9215,20 +9325,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) {
@@ -10046,7 +10142,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);
@@ -10060,6 +10156,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
     });
   }
@@ -10184,7 +10281,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) => [
@@ -10197,7 +10294,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);
 }
@@ -10216,7 +10314,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}",
@@ -10225,6 +10323,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
@@ -10239,8 +10340,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,
@@ -10251,9 +10352,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;
@@ -10310,12 +10414,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));
@@ -10430,6 +10534,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
@@ -10940,6 +11047,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,
@@ -10992,6 +11100,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",
@@ -11111,12 +11220,17 @@ class WebTerminalManager {
           return false;
         }
       },
-      conversationExists: (cwd, claudeSessionId) => node_fs.existsSync(path.join(getProjectPath(cwd), `${claudeSessionId}.jsonl`))
+      conversationExists: (cwd, claudeSessionId) => node_fs.existsSync(path.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.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 };
   }
@@ -11176,6 +11290,13 @@ class WebTerminalManager {
         { stdio: "ignore", timeout: TMUX_PROBE_TIMEOUT_MS, env }
       );
     }
+    if (plan.attachTmux) {
+      node_child_process.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)) {
         node_child_process.spawnSync("tmux", tmuxArgs(argv), { stdio: "ignore", timeout: TMUX_PROBE_TIMEOUT_MS, env });
@@ -11188,7 +11309,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);
@@ -11286,6 +11407,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);
@@ -11298,15 +11420,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() && node_child_process.spawnSync(
@@ -11331,6 +11454,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;
@@ -11343,6 +11470,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 = node_child_process.spawnSync(
@@ -11384,16 +11512,15 @@ class WebTerminalManager {
         }
       }
       if (createdNew) {
-        const startup = normalizeStartupCommand(opts.startupCommand);
-        if (startup) {
-          try {
-            for (const a of startupInjectionArgs(tmuxSession, startup)) {
-              node_child_process.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 = node_child_process.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 = node_child_process.spawnSync(
@@ -11408,17 +11535,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 {
-                  node_child_process.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) {
@@ -11428,6 +11545,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;
         }
@@ -11510,20 +11628,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 {
+          node_child_process.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)) {
+          node_child_process.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 = node_child_process.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 = node_child_process.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 = node_child_process.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
@@ -11765,6 +11973,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",
@@ -11853,7 +12062,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;
@@ -11920,18 +12130,19 @@ class WebTerminalManager {
     try {
       const probe = node_child_process.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") {
@@ -13943,7 +14154,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,
@@ -13953,7 +14165,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);
@@ -14028,6 +14241,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") {
@@ -14421,6 +14637,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.
@@ -15830,6 +16048,7 @@ exports.releaseDaemonLock = releaseDaemonLock;
 exports.resolveCliUpdateCheckInterval = resolveCliUpdateCheckInterval;
 exports.scrubTmuxClientEnv = scrubTmuxClientEnv;
 exports.sendToVhTerminal = sendToVhTerminal;
+exports.shellescape = shellescape;
 exports.startOfflineReconnection = startOfflineReconnection;
 exports.summarizeSpawnSessionForLog = summarizeSpawnSessionForLog;
 exports.tmuxArgs = tmuxArgs;