@tsconfigdotjson/vibe-os 0.2.0 → 0.4.0

package/server/screens.ts

@@ -0,0 +1,392 @@
+// Reading what a window shows, with no terminal attached.
+//
+// dtach keeps no copy of what a program has drawn. It moves bytes from the pty
+// to whoever is attached and forgets them. So the server attaches as well: for
+// every running session it holds one connection to the dtach socket, speaking
+// dtach's own packet protocol, and feeds the output into a headless xterm. That
+// gives the API a screen it can read as text, and the time of the last output,
+// which is how an agent at work is told from one waiting at its prompt.
+//
+// The connection has to send MSG_ATTACH, because dtach only writes output to
+// attached clients. It never sends a size, except once to ask for a repaint (see
+// `repaint`), so the pty stays the size the browser or `vibe-os attach` gave it.
+// And it is not a `dtach -a` process, so `clientsOn` does not count it and
+// nothing about the one-client rule changes.
+
+import { execFile } from "node:child_process";
+import { readdir } from "node:fs/promises";
+import net from "node:net";
+import os from "node:os";
+import { promisify } from "node:util";
+import { type IBufferLine, Terminal } from "@xterm/headless";
+import type { Activity } from "../shared/wire.ts";
+import type { Config } from "./config.ts";
+import { sessionTty } from "./headless.ts";
+import { log } from "./log.ts";
+import { DETACHED_COLS, DETACHED_ROWS, socketPath } from "./session.ts";
+
+const run = promisify(execFile);
+
+/**
+ * Output within this long means the program is busy.
+ *
+ * Every harness animates something while it works (Claude's spinner redraws
+ * several times a second) and draws nothing at all while it waits for input,
+ * so a second and a half of quiet is a clear line between the two.
+ */
+export const QUIET_MS = 1_500;
+/** History kept per window, beyond the screen itself. */
+const SCROLLBACK = 1_000;
+/** How often to look for sessions started by something other than this server. */
+const SYNC_MS = 5_000;
+/** How often output may trigger a check that the pty is still the same size. */
+const SIZE_CHECK_MS = 1_000;
+/** How long the width stays one column short while asking for a repaint. */
+const NUDGE_MS = 200;
+const POLL_MS = 250;
+
+/**
+ * What a program waiting on a question looks like, as opposed to waiting at its
+ * prompt.
+ *
+ * Matched against the visible screen only, so a question answered long ago and
+ * scrolled away does not count. Claude's dialogs (trust this folder, allow this
+ * command) and Codex's approvals all end in a "confirm" or "cancel" line, and
+ * the rest are the shapes a numbered menu or a yes/no question take.
+ */
+export const QUESTION_PATTERNS: RegExp[] = [
+  /enter to confirm/i,
+  /esc to cancel/i,
+  /^\s*[❯›]\s*\d+\.\s+\S/m,
+  /\((y\/n)\)|\[(y\/n)\]/i,
+];
+
+// dtach's packet: a type byte, a length byte, then a `struct winsize` of four
+// unsigned shorts, in the machine's own byte order. See dtach.h.
+const MSG_ATTACH = 1;
+const MSG_REDRAW = 4;
+const REDRAW_WINCH = 3;
+const PACKET_BYTES = 10;
+
+export function packet(
+  type: number,
+  len = 0,
+  size?: { rows: number; cols: number },
+): Buffer {
+  const buf = Buffer.alloc(PACKET_BYTES);
+  buf[0] = type;
+  buf[1] = len;
+  if (size) {
+    if (os.endianness() === "LE") {
+      buf.writeUInt16LE(size.rows, 2);
+      buf.writeUInt16LE(size.cols, 4);
+    } else {
+      buf.writeUInt16BE(size.rows, 2);
+      buf.writeUInt16BE(size.cols, 4);
+    }
+  }
+  return buf;
+}
+
+/** Whether a program is working, waiting on a question, or at its prompt. */
+export function classify(
+  lastOutputAt: number | null,
+  now: number,
+  visible: string,
+): Activity {
+  if (lastOutputAt !== null && now - lastOutputAt < QUIET_MS) return "busy";
+  if (QUESTION_PATTERNS.some((p) => p.test(visible))) return "question";
+  return "idle";
+}
+
+/** Reads `stty size`: rows, then columns. */
+export function parseSize(out: string): { rows: number; cols: number } | null {
+  const m = /^\s*(\d+)\s+(\d+)\s*$/.exec(out);
+  if (!m) return null;
+  const rows = Number(m[1]);
+  const cols = Number(m[2]);
+  return rows > 0 && cols > 0 ? { rows, cols } : null;
+}
+
+async function ttySize(
+  tty: string,
+): Promise<{ rows: number; cols: number } | null> {
+  const flag = process.platform === "darwin" ? "-f" : "-F";
+  try {
+    const { stdout } = await run("stty", [flag, tty, "size"], {
+      timeout: 5_000,
+    });
+    return parseSize(stdout);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The last `count` lines of a terminal, as plain text.
+ *
+ * A line the terminal wrapped is joined back to the one it continues, so a
+ * long line reads as it was written rather than as the width it was drawn at.
+ * Blank lines at the bottom, which are only the unused part of the screen, are
+ * dropped.
+ *
+ * Faint text on the cursor's line is left out. That is where a harness draws a
+ * placeholder or a suggested prompt, greyed out with SGR 2 (Claude's `Try
+ * "…"`, Codex's hint), and as plain text it reads the same as something typed
+ * and not yet sent. The cursor is the input caret in both, so its line is the
+ * input line.
+ */
+export function bufferText(term: Terminal, count: number): string {
+  const buf = term.buffer.active;
+  const cursorRow = buf.baseY + buf.cursorY;
+  const lines: string[] = [];
+  for (let i = 0; i < buf.length; i++) {
+    const line = buf.getLine(i);
+    if (!line) continue;
+    // Untrimmed until joined, or a space at the wrap point would be lost.
+    const text =
+      i === cursorRow ? withoutFaint(line) : line.translateToString(true);
+    if (line.isWrapped && lines.length > 0) lines[lines.length - 1] += text;
+    else lines.push(text);
+  }
+  const trimmed = lines.map((l) => l.trimEnd());
+  while (trimmed.length > 0 && trimmed[trimmed.length - 1] === "")
+    trimmed.pop();
+  return trimmed.slice(-count).join("\n");
+}
+
+/** A line's text with every faint cell read as a blank. */
+function withoutFaint(line: IBufferLine): string {
+  let text = "";
+  for (let x = 0; x < line.length; x++) {
+    const cell = line.getCell(x);
+    // The second half of a wide character has width 0 and no text of its own.
+    if (!cell || cell.getWidth() === 0) continue;
+    text += cell.isDim() ? " ".repeat(cell.getWidth()) : cell.getChars() || " ";
+  }
+  return text.trimEnd();
+}
+
+/** One session's screen, kept up to date by its connection. */
+export class Screen {
+  readonly term = new Terminal({
+    rows: DETACHED_ROWS,
+    cols: DETACHED_COLS,
+    scrollback: SCROLLBACK,
+    allowProposedApi: true,
+  });
+  /** When the program last drew anything, or null if not since we attached. */
+  lastOutputAt: number | null = null;
+  private tty: string | null = null;
+  private sizeCheckedAt = 0;
+  private sizing = false;
+
+  constructor(
+    private readonly sock: string,
+    private readonly socket: net.Socket,
+  ) {}
+
+  feed(data: Buffer): void {
+    this.lastOutputAt = Date.now();
+    this.term.write(data);
+    if (Date.now() - this.sizeCheckedAt > SIZE_CHECK_MS) void this.syncSize();
+  }
+
+  activity(now = Date.now()): Activity {
+    return classify(this.lastOutputAt, now, this.visible());
+  }
+
+  /** What the screen shows right now: the bottom `rows` lines of the buffer. */
+  visible(): string {
+    const buf = this.term.buffer.active;
+    const out: string[] = [];
+    for (let i = buf.baseY; i < buf.baseY + this.term.rows; i++)
+      out.push(buf.getLine(i)?.translateToString(true) ?? "");
+    return out.join("\n");
+  }
+
+  text(lines: number): string {
+    return bufferText(this.term, lines);
+  }
+
+  /**
+   * Follows the pty's size, which whoever attaches last decides.
+   *
+   * Checked when output arrives rather than on a timer, because a resize is
+   * always followed by the program redrawing at the new size.
+   */
+  async syncSize(): Promise<{ rows: number; cols: number } | null> {
+    if (this.sizing) return null;
+    this.sizing = true;
+    this.sizeCheckedAt = Date.now();
+    try {
+      this.tty ??= await sessionTty(this.sock);
+      const size = this.tty ? await ttySize(this.tty) : null;
+      if (
+        size &&
+        (size.rows !== this.term.rows || size.cols !== this.term.cols)
+      )
+        this.term.resize(size.cols, size.rows);
+      return size;
+    } finally {
+      this.sizing = false;
+    }
+  }
+
+  /**
+   * Asks the program to draw its whole screen again, for a session that was
+   * running before we attached.
+   *
+   * dtach's redraw sends SIGWINCH, but a program that finds its size unchanged
+   * may not repaint (Claude does not). So the width goes one column narrower
+   * and back. Whoever is attached sees one extra repaint.
+   */
+  async repaint(): Promise<void> {
+    const size = await this.syncSize();
+    if (!size || size.cols < 2) return;
+    this.socket.write(
+      packet(MSG_REDRAW, REDRAW_WINCH, { ...size, cols: size.cols - 1 }),
+    );
+    await Bun.sleep(NUDGE_MS);
+    if (!this.socket.destroyed)
+      this.socket.write(packet(MSG_REDRAW, REDRAW_WINCH, size));
+  }
+
+  close(): void {
+    this.socket.destroy();
+    this.term.dispose();
+  }
+}
+
+/** Every running session's screen, keyed by session name. */
+export class Screens {
+  private readonly open = new Map<string, Screen>();
+  private readonly pending = new Map<string, Promise<Screen | undefined>>();
+  private timer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(private readonly config: Config) {}
+
+  /** Watches whatever is running now, then looks again every few seconds. */
+  start(): void {
+    void this.sync();
+    this.timer = setInterval(() => void this.sync(), SYNC_MS);
+  }
+
+  stop(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    for (const screen of this.open.values()) screen.close();
+    this.open.clear();
+  }
+
+  get(session: string): Screen | undefined {
+    return this.open.get(session);
+  }
+
+  /**
+   * Attaches to a session if nothing is yet, and returns its screen.
+   *
+   * Undefined when the session is not running. `fresh` is for a session this
+   * server has just created: it has drawn next to nothing yet, and asking it to
+   * repaint would only make it draw its startup twice.
+   */
+  watch(
+    session: string,
+    opts: { fresh?: boolean } = {},
+  ): Promise<Screen | undefined> {
+    const open = this.open.get(session);
+    if (open) return Promise.resolve(open);
+    let attempt = this.pending.get(session);
+    if (!attempt) {
+      attempt = this.connect(session, opts.fresh === true).finally(() =>
+        this.pending.delete(session),
+      );
+      this.pending.set(session, attempt);
+    }
+    return attempt;
+  }
+
+  private connect(
+    session: string,
+    fresh: boolean,
+  ): Promise<Screen | undefined> {
+    const sock = socketPath(this.config, session);
+    return new Promise((resolve) => {
+      const socket = net.createConnection(sock);
+      socket.once("error", () => resolve(undefined));
+      socket.once("connect", () => {
+        socket.write(packet(MSG_ATTACH));
+        const screen = new Screen(sock, socket);
+        this.open.set(session, screen);
+        socket.on("data", (data: Buffer) => screen.feed(data));
+        socket.on("error", () => {});
+        socket.on("close", () => {
+          if (this.open.get(session) === screen) this.open.delete(session);
+          screen.close();
+        });
+        log.debug(`watching ${session}`);
+        if (fresh) void screen.syncSize();
+        else void screen.repaint();
+        resolve(screen);
+      });
+    });
+  }
+
+  /** Attaches to every socket in the sessions directory not already watched. */
+  async sync(): Promise<void> {
+    let names: string[];
+    try {
+      names = await readdir(`${this.config.stateDir}/sessions`);
+    } catch {
+      return;
+    }
+    await Promise.all(
+      names
+        .filter((n) => n.endsWith(".sock"))
+        .map((n) => n.slice(0, -".sock".length))
+        .filter((s) => !this.open.has(s))
+        .map((s) => this.watch(s)),
+    );
+  }
+
+  /**
+   * Waits for a session to stop drawing, and says what it stopped on.
+   *
+   * The quiet has to be seen, not assumed: a session started a moment ago has
+   * drawn nothing yet, which looks the same as one that has finished. So the
+   * wait counts from when it began as if that were output, and always lasts at
+   * least `QUIET_MS`. Returns "busy" if it was still going when time ran out.
+   */
+  async settle(session: string, timeoutMs: number): Promise<Activity> {
+    const begun = Date.now();
+    const deadline = begun + timeoutMs;
+    for (;;) {
+      const screen = this.get(session) ?? (await this.watch(session));
+      const now = Date.now();
+      const state = screen
+        ? classify(
+            Math.max(screen.lastOutputAt ?? 0, begun),
+            now,
+            screen.visible(),
+          )
+        : "idle";
+      if (state !== "busy" || now > deadline) return state;
+      await Bun.sleep(POLL_MS);
+    }
+  }
+
+  /** Waits for any output after `since`. False if none came in time. */
+  async drewSince(
+    session: string,
+    since: number,
+    timeoutMs: number,
+  ): Promise<boolean> {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      const at = this.get(session)?.lastOutputAt ?? null;
+      if (at !== null && at > since) return true;
+      if (Date.now() > deadline) return false;
+      await Bun.sleep(POLL_MS / 5);
+    }
+  }
+}

package/server/session.ts

@@ -11,7 +11,10 @@
 // too, and api.ts needs attach.ts — importing in a circle to share three pure
 // functions is not a trade worth making.
 
+import { CUSTOM } from "../shared/harness.ts";
 import type { Config } from "./config.ts";
+import { harness } from "./harness.ts";
+import { effectiveLimits, SCOPE_PROBE, scopePrefix } from "./memory.ts";
 import type { Profile } from "./profiles.ts";
 import { SOCK_VAR } from "./reaper.ts";
 
@@ -21,63 +24,15 @@ export function shellQuote(value: string): string {
 }
 
 /**
- * Cursor's name for a directory, as it spells it under `~/.cursor/projects`.
+ * Whether a profile's harness can pick its last conversation back up.
  *
- * Every run of anything that is not a letter or a digit becomes one dash, and
- * the leading one that a path always starts with is dropped. Case survives.
- * Read off a real install rather than from documentation, which does not
- * mention the directory at all: `/home/ubuntu` is `home-ubuntu`, and
- * `/tmp/Cursor.Test_1 space/sub` is `tmp-Cursor-Test-1-space-sub`.
+ * Every agent harness here resumes the most recent conversation in the working
+ * directory. That is the window's own conversation as long as it is the only
+ * one of its harness in the worktree, which is what opening a profile normally
+ * guarantees.
  */
-export function cursorProjectSlug(dir: string): string {
-  return dir.replace(/[^A-Za-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-}
-
-/**
- * Shell that points this worktree's Cursor project at the box's MCP credentials.
- *
- * Cursor keeps MCP OAuth tokens per working directory, in
- * `~/.cursor/projects/<slug of the directory>/mcp-auth.json`. The server list is
- * global — `~/.cursor/mcp.json` — so a new window shows Linear as configured and
- * then says `requires_authentication`, because the tokens are somewhere else.
- * Every workspace here is a freshly cut worktree at a path Cursor has never
- * seen, which makes "log in once on this box" mean "log in once per window"
- * unless something intervenes.
- *
- * A symlink is what intervenes, and it is a symlink rather than a copy because
- * Cursor writes through it: an access token lasts a day, so the refresh that
- * happens in whichever window is open has to be the refresh every other window
- * sees. Copies would go stale a day apart and each one would race the others
- * for a refresh token the provider rotates.
- *
- * The link is only ever created where there is nothing at all. An existing file
- * is somebody's real per-directory login and is left alone; an existing link is
- * this, already done. Neither is worth overwriting to save a stat.
- *
- * The shared store is deliberately allowed not to exist yet. Writing through a
- * dangling symlink creates the target, so `cursor-agent mcp login linear` in any
- * window is the one login the box needs, wherever it happens — which is why the
- * store's directory is created here even though the file is not.
- *
- * Failure is silent on purpose, and inert rather than fatal. If Cursor ever
- * changes how it names these directories, or `CURSOR_DATA_DIR` moves them, the
- * link lands somewhere Cursor does not read and windows behave exactly as they
- * did before: a login prompt, not a broken window.
- */
-function cursorMcpLink(cwd: string, stateDir: string): string {
-  const store = `${stateDir}/cursor/mcp-auth.json`;
-  const storeDir = shellQuote(`${stateDir}/cursor`);
-  // The slug is letters, digits and dashes by construction, so it needs no
-  // quoting of its own; `$HOME` is left to the shell because the session runs as
-  // the user whose credentials these are.
-  const dir = `"$HOME/.cursor/projects/${cursorProjectSlug(cwd)}"`;
-  const link = `"$HOME/.cursor/projects/${cursorProjectSlug(cwd)}/mcp-auth.json"`;
-  return [
-    `mkdir -p ${dir} ${storeDir} 2>/dev/null`,
-    // Refresh tokens, so no wider than the state dir this sits in.
-    `chmod 700 ${storeDir} 2>/dev/null`,
-    `{ [ -e ${link} ] || [ -L ${link} ] || ln -s ${shellQuote(store)} ${link} 2>/dev/null; }`,
-  ].join("; ");
+export function canResume(profile: Profile | null | undefined): boolean {
+  return Boolean(profile && harness(profile.harness)?.spec.resume);
 }
 
 /**
@@ -102,40 +57,43 @@ function cursorMcpLink(cwd: string, stateDir: string): string {
  */
 export function harnessCommand(
   profile: Profile,
-  /** The worktree it runs in and the state dir, for the Cursor MCP link. */
+  /** The worktree it runs in and the state dir, for the harness's own setup. */
   where: { cwd: string; stateDir: string },
+  /** Pick up the last conversation instead of starting a new one. */
+  resume = false,
 ): string | undefined {
-  const executable =
-    profile.harness === "claude"
-      ? "claude"
-      : profile.harness === "hermes"
-        ? "hermes"
-        : // The unambiguous of the two names its installer symlinks — `agent`
-          // is the other, and too generic to be the one a PATH lookup bets on.
-          profile.harness === "cursor"
-          ? "cursor-agent"
-          : profile.harness === "custom"
-            ? profile.command
-            : null;
-  if (!executable) return undefined;
-  /*
-   * `hermes` on its own opens a chat, but `--model` and `--provider` belong to
-   * the `chat` subcommand rather than to the top-level command, so a profile
-   * that picks a model has to name it. It is prepended here rather than stored
-   * in the profile's argv because it is not a flag anyone should be able to
-   * delete in the editor: without it every model selection is silently ignored.
-   */
-  const leading = profile.harness === "hermes" ? ["chat"] : [];
-  const argv = [executable, ...leading, ...profile.args]
-    .map(shellQuote)
-    .join(" ");
+  if (profile.harness === CUSTOM) {
+    if (!profile.command) return undefined;
+    return launch(profile.command, profile.args, "");
+  }
+  const adapter = harness(profile.harness);
+  if (!adapter) return undefined;
+  const { spec } = adapter;
 
-  // Only Cursor keeps credentials per directory, so only Cursor pays for this.
-  const setup =
-    profile.harness === "cursor"
-      ? `${cursorMcpLink(where.cwd, where.stateDir)}; `
-      : "";
+  const before: string[] = [...(spec.leading ?? [])];
+  const after: string[] = [];
+  const unless = new Set(spec.resume?.unless ?? []);
+  if (
+    resume &&
+    spec.resume &&
+    !profile.args.some((a) => unless.has(a.split("=")[0]))
+  ) {
+    if (spec.resume.subcommand) before.push(...spec.resume.args);
+    else after.push(...spec.resume.args);
+  }
 
+  const setup = adapter.setup ? `${adapter.setup(where)}; ` : "";
+  return launch(spec.command, [...before, ...profile.args, ...after], setup);
+}
+
+/**
+ * The shell line that runs a harness: PATH restored, setup, then exec.
+ *
+ * Every token is quoted individually so a flag can contain spaces and cannot
+ * contain a second command.
+ */
+function launch(executable: string, args: string[], setup: string): string {
+  const argv = [executable, ...args].map(shellQuote).join(" ");
   /*
    * The PATH a forced command gets is not the PATH you get when you log in.
    *
@@ -154,6 +112,16 @@ export function harnessCommand(
   return `export PATH="$HOME/.local/bin:$PATH"; ${setup}exec ${argv}`;
 }
 
+/**
+ * The size a session started with no terminal gets.
+ *
+ * dtach copies the size of the terminal that creates a session, and a detached
+ * start has none, so the program would come up at 0x0. The first browser or
+ * `vibe-os attach` sends its real size and the program repaints.
+ */
+export const DETACHED_ROWS = 40;
+export const DETACHED_COLS = 120;
+
 /** Where a window's dtach socket lives. */
 export function socketPath(config: Config, session: string): string {
   return `${config.stateDir}/sessions/${session}.sock`;
@@ -209,14 +177,20 @@ export function windowCommand(
   cwd: string,
   config: Config,
   profile?: Profile | null,
-  /** `forDisplay` drops the locking wrapper, leaving the readable essentials. */
-  opts?: { forDisplay?: boolean },
+  /**
+   * `forDisplay` drops the locking wrapper, leaving the readable essentials.
+   * `resume` only matters if the session is created rather than attached to.
+   * `detached` creates the session and stops there, without attaching, for a
+   * window started before any terminal opens it. It has no pty to copy a size
+   * from, so it sets one.
+   */
+  opts?: { forDisplay?: boolean; resume?: boolean; detached?: boolean },
 ): string | undefined {
   if (!config.sessions) return undefined;
 
   const sock = socketPath(config, session);
   const harness = profile
-    ? harnessCommand(profile, { cwd, stateDir: config.stateDir })
+    ? harnessCommand(profile, { cwd, stateDir: config.stateDir }, opts?.resume)
     : undefined;
   // Falls back to the login shell, so a window with no profile is still a
   // session that survives a reload rather than a bare ssh command.
@@ -263,7 +237,9 @@ export function windowCommand(
    * reports. Failure is ignored on purpose — a box where `stty` is missing
    * should still open a window.
    */
-  const baud = "stty 38400 2>/dev/null;";
+  const baud = opts?.detached
+    ? `stty 38400 rows ${DETACHED_ROWS} cols ${DETACHED_COLS} 2>/dev/null;`
+    : "stty 38400 2>/dev/null;";
   const inner = `cd ${shellQuote(cwd)} && ${baud} ${env} ${harness ?? 'exec "$SHELL"'}`;
 
   // `dtach -p` writes to a live socket and fails on a dead one, which makes it
@@ -284,7 +260,19 @@ export function windowCommand(
    * what lets the reaper name the owner of a process found running in a
    * deleted worktree a week later. reaper.ts is the only reader.
    */
-  const create = `${SOCK_VAR}=${shellQuote(sock)} dtach -n ${shellQuote(sock)} -E -z /bin/sh -c ${shellQuote(inner)}`;
+  const dtachNew = `dtach -n ${shellQuote(sock)} -E -z /bin/sh -c ${shellQuote(inner)}`;
+  /*
+   * A scope of its own, with the memory limits, when the login has a user
+   * systemd to ask (see memory.ts). The marker goes on both branches: a
+   * `VAR=value` prefix cannot sit in front of an `if`, and exporting it would
+   * hand it to the attaching client below as well, which would then count as
+   * part of the session it is only looking at.
+   */
+  const scope = scopePrefix(effectiveLimits(config.memory, profile), session);
+  const marked = `${SOCK_VAR}=${shellQuote(sock)}`;
+  const create = scope
+    ? `if ${SCOPE_PROBE}; then ${marked} ${scope}${dtachNew}; else ${marked} ${dtachNew}; fi`
+    : `${marked} ${dtachNew}`;
   const attach = `exec dtach -a ${shellQuote(sock)} -E -z -r winch`;
 
   /*
@@ -315,16 +303,17 @@ export function windowCommand(
   const critical = `${probe} || { rm -f ${shellQuote(sock)}; ${create}; }`;
 
   // The banner wants to show what a window actually runs, which is the create
-  // and the attach. Printing the locking wrapper as well — twice, once per
-  // branch, with three levels of nested quoting — buries that in a wall of
-  // backslashes and tells the reader nothing they can act on.
-  if (opts?.forDisplay) return [create, attach].join("; ");
+  // (scoped, when it can be) and the attach. Printing the locking wrapper as
+  // well — twice, once per branch, with three levels of nested quoting — buries
+  // that in a wall of backslashes and tells the reader nothing they can act on.
+  if (opts?.forDisplay)
+    return [`${marked} ${scope}${dtachNew}`, attach].join("; ");
 
   return [
     `mkdir -p ${shellQuote(`${config.stateDir}/sessions`)}`,
     `if command -v flock > /dev/null 2>&1; then ` +
       `flock -o ${shellQuote(`${sock}.lock`)} -c ${shellQuote(critical)}; ` +
       `else { ${critical}; }; fi`,
-    attach,
+    ...(opts?.detached ? [] : [attach]),
   ].join("; ");
 }