@spunto/build 0.4.1 → 0.5.1

package/README.md

@@ -148,6 +148,29 @@ time a vendor reshuffles a field.
 Here for the reason that inverts the rest of the package: **nothing has forked this yet.** Putting
 it in the shared package now costs nothing and means the second product never writes its own.
 
+### `@spunto/build/terminal` — the half of a persistent terminal that is a string
+
+A worker's terminal is an exec attached to a session that outlives it, so closing a browser tab
+doesn't kill a build. The attaching is I/O and stays with whoever owns the Docker socket; the shell
+that gets attached, the layout it writes into, and the parsing of what it prints back are here.
+
+```ts
+import { sanitizeSessionName, buildDtachCommand, parseSessionList } from "@spunto/build/terminal"
+
+const name = sanitizeSessionName(fromQuery)        // every name MUST come through this
+await exec(container, ["/bin/sh", "-c", buildDtachCommand()], { env: { MP_TERM_SESSION: name } })
+```
+
+**dtach, not tmux.** tmux's only knob for "the wheel scrolls history" is `mouse on`, which also
+makes it swallow every drag — the frontend then has to forge Shift-drags to get a native selection
+back. dtach does only persistence, so the emulator keeps the mouse, its scrollback and its search.
+What dtach doesn't do is remember the screen, so the session is recorded inside the container with
+`script(1)` and the tail replayed on attach.
+
+`sanitizeSessionName` is a security boundary, not tidiness: names are interpolated into the shell
+scripts this module builds, so anything that doesn't come through it is a command injection into
+someone's container.
+
 ## The rule
 
 A module belongs in this package only if it imports **no** ORM schema, **no** HTTP framework, **no**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spunto/build",
-  "version": "0.4.1",
-  "description": "Spunto's shared Build engine \u2014 the devcontainer image protocol and VS Code extension registry clients, with no database, no HTTP framework and no UI.",
+  "version": "0.5.1",
+  "description": "Spunto's shared Build engine — the devcontainer image protocol and VS Code extension registry clients, with no database, no HTTP framework and no UI.",
   "type": "module",
   "license": "MIT",
   "homepage": "https://spunto.net",
@@ -55,6 +55,10 @@
       "types": "./src/script/index.ts",
       "import": "./src/script/index.ts"
     },
+    "./terminal": {
+      "types": "./src/terminal/index.ts",
+      "import": "./src/terminal/index.ts"
+    },
     "./agent-stream": {
       "types": "./src/agent-stream/index.ts",
       "import": "./src/agent-stream/index.ts"

package/src/index.ts

@@ -12,4 +12,5 @@ export * from "./spec/index"
 export * from "./types/index"
 export * from "./catalogs/index"
 export * from "./script/index"
+export * from "./terminal/index"
 export * from "./agent-stream/index"

package/src/script/setup-script.ts

@@ -35,6 +35,37 @@ function shQuote(v: string): string {
   return `'${v.replace(/'/g, `'\\''`)}'`
 }
 
+/**
+ * Runs a command as the workspace user instead of root.
+ *
+ * The setup script itself is the container's CMD, so it runs as root — it has to, to chown
+ * /workspace and write under /etc. Everything it *clones*, though, belongs to the user, and
+ * cloning as root has cost us twice: once as `npm install` failing with EACCES on a root-owned
+ * node_modules (hence the re-chown after the repo clones), and once as a private dotfiles repo
+ * that authenticated with no key at all, because root has no `~/.ssh` and the identity was only
+ * named on the repo clones.
+ *
+ * `su` gives the command `HOME=/home/vscode`, which is what makes ssh pick up the `~/.ssh/config`
+ * written in the credentials step — so a clone over SSH needs nothing else to find the user's key.
+ */
+function asUser(username: string, cmd: string): string {
+  return `su ${username} -c ${shQuote(cmd)}`
+}
+
+/**
+ * A dotfiles setting, as a clonable URL.
+ *
+ * Anything already naming a transport is left alone; only a bare `owner/repo` shorthand is
+ * expanded against GitHub. The previous test — `startsWith("http") || startsWith("git@")` — turned
+ * `ssh://git@host/me/dotfiles.git` into `https://github.com/ssh://git@host/me/dotfiles.git`.
+ */
+function normalizeDotfilesUrl(raw: string): string {
+  const v = raw.trim()
+  return /^(https?:\/\/|ssh:\/\/|git:\/\/|file:\/\/|[^/\s]+@[^/\s]+:)/.test(v)
+    ? v
+    : `https://github.com/${v.replace(/^\/+|\/+$/g, "")}`
+}
+
 /**
  * `export EXTENSIONS_GALLERY=…`, or nothing when the org is on the default (Open VSX) registry.
  *
@@ -105,11 +136,13 @@ function cloneRepoBlock(params: {
   index: number
   total: number
   homeDir: string
+  /** Who the checkout belongs to — the clone runs as them. */
+  username: string
   branch?: string
   githubInstallationTokens?: Record<string, string>
   userSshPrivateKey?: string
 }): { header: string; lines: string[] } {
-  const { repo: r, index, total, homeDir, branch, githubInstallationTokens, userSshPrivateKey } = params
+  const { repo: r, index, total, homeDir, username, branch, githubInstallationTokens, userSshPrivateKey } = params
   // Pick the installation token for this repo's owner. A GitHub App installation only grants
   // access to repos owned by its account, so the owner login (== installation accountLogin)
   // uniquely selects the right token among the org's connected installations. Covers legacy
@@ -117,13 +150,16 @@ function cloneRepoBlock(params: {
   const owner = (r.project.split("/")[0] ?? "").toLowerCase()
   const repoToken = githubInstallationTokens?.[owner]
   const b = branch ? ` --branch ${shQuote(branch)}` : ""
-  const cloneCmd = r.provider === "git" && r.cloneUrl
+  const rawCloneCmd = r.provider === "git" && r.cloneUrl
     ? `GIT_SSH_COMMAND="ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -i ${homeDir}/.ssh/mp_deploy_key" git clone${b} ${shQuote(r.cloneUrl)} /workspace/${r.workspacePath}`
     : r.provider === "github" && repoToken
     ? `git clone${b} https://x-access-token:${repoToken}@github.com/${r.project}.git /workspace/${r.workspacePath} && git -C /workspace/${r.workspacePath} remote set-url origin git@github.com:${r.project}.git`
     : r.provider === "github" && userSshPrivateKey
     ? `GIT_SSH_COMMAND="ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -i ${homeDir}/.ssh/mp_user_key" git clone${b} git@github.com:${r.project}.git /workspace/${r.workspacePath}`
     : `git clone${b} https://github.com/${r.project} /workspace/${r.workspacePath}`
+  // Cloned as the user, not as root: /workspace is already theirs (the ownership step runs
+  // first), so the checkout lands with the right owner and needs no chown afterwards.
+  const cloneCmd = asUser(username, rawCloneCmd)
 
   // Single-quoted only when a (user-provided) branch is interpolated; the plain form is kept
   // verbatim for the no-branch case so the generated script is unchanged there.
@@ -851,23 +887,23 @@ export function buildSetupScript(params: SetupScriptParams): { script: string }
 
   // ── 4. Dotfiles ───────────────────────────────────────────────────────────
   if (dotfilesRepo) {
-    const dotfilesUrl = dotfilesRepo.startsWith("http") || dotfilesRepo.startsWith("git@")
-      ? dotfilesRepo
-      : `https://github.com/${dotfilesRepo}`
+    const dotfilesUrl = normalizeDotfilesUrl(dotfilesRepo)
     push(...banner("SETUP: DOTFILES"))
     mpAt(mkStatus("dotfiles", allReposPending, pc0, null), "dotfiles")
     push(
       `echo "Cloning dotfiles from ${dotfilesUrl}..."`,
       `set +e`,
-      `git clone ${JSON.stringify(dotfilesUrl)} ${homeDir}/dotfiles 2>&1`,
+      // As the user, like every other clone: root has no `~/.ssh`, so a private dotfiles repo
+      // over SSH would authenticate with no key at all.
+      `${asUser(username, `git clone ${shQuote(dotfilesUrl)} ${homeDir}/dotfiles`)} 2>&1`,
       `_DOTS_EXIT=$?`,
       `set -e`,
       `if [ $_DOTS_EXIT -ne 0 ]; then`,
       `  echo "Dotfiles clone failed (exit $_DOTS_EXIT) — continuing without dotfiles"`,
       `else`,
       `  echo "Dotfiles cloned"`,
-      // Cloned as root, but the install script below runs as the user (and so does whoever edits
-      // these files later) — hand the clone over before touching it.
+      // The clone above already lands as the user. Kept for a worker whose ~/dotfiles was left
+      // root-owned by an earlier release, where the install script below would fail on it.
       `  chown -R ${username}:${username} ${homeDir}/dotfiles`,
       `  _INSTALL_SCRIPT=""`,
       `  for _candidate in install.sh bootstrap.sh setup.sh script/setup; do`,
@@ -911,6 +947,7 @@ export function buildSetupScript(params: SetupScriptParams): { script: string }
       index: i,
       total: project.repositories.length,
       homeDir,
+      username,
       branch: resolveRepoBranch(r, branch),
       githubInstallationTokens,
       userSshPrivateKey,
@@ -924,11 +961,10 @@ export function buildSetupScript(params: SetupScriptParams): { script: string }
   })
 
   // ── 5b. Re-own /workspace after cloning ───────────────────────────────────
-  // Repos are cloned as root (the setup script runs as root), so the cloned
-  // directories end up root-owned. The initial chown (step 1) ran *before* the
-  // clone, so it didn't cover them. postCreateCommand runs as vscode, so without
-  // this the user can't write into the repo (e.g. `npm install` → EACCES on
-  // node_modules). Must run before postCreate, not just in the final step.
+  // The clones above run as the user, so their checkouts already belong to them. This stays as a
+  // net: a repo left root-owned by an earlier release (when cloning *was* done as root) would
+  // otherwise keep failing postCreate with EACCES — `npm install` on a root-owned node_modules —
+  // and the final chown in step 8 comes too late for that.
   if (project.repositories.length > 0) {
     push("", `chown -R ${username}:${username} /workspace`)
   }
@@ -1774,21 +1810,21 @@ export function buildSetupPlan(params: SetupScriptParams): {
 
   // ── dotfiles ──────────────────────────────────────────────────────────────
   if (dotfilesRepo) {
-    const dotfilesUrl = dotfilesRepo.startsWith("http") || dotfilesRepo.startsWith("git@")
-      ? dotfilesRepo
-      : `https://github.com/${dotfilesRepo}`
+    const dotfilesUrl = normalizeDotfilesUrl(dotfilesRepo)
     const l: string[] = ["set -e", ...banner("SETUP: DOTFILES"),
       `echo "Cloning dotfiles from ${dotfilesUrl}..."`,
       `set +e`,
-      `git clone ${JSON.stringify(dotfilesUrl)} ${homeDir}/dotfiles 2>&1`,
+      // As the user, like every other clone: root has no `~/.ssh`, so a private dotfiles repo
+      // over SSH would authenticate with no key at all.
+      `${asUser(username, `git clone ${shQuote(dotfilesUrl)} ${homeDir}/dotfiles`)} 2>&1`,
       `_DOTS_EXIT=$?`,
       `set -e`,
       `if [ $_DOTS_EXIT -ne 0 ]; then`,
       `  echo "Dotfiles clone failed (exit $_DOTS_EXIT) — continuing without dotfiles"`,
       `else`,
       `  echo "Dotfiles cloned"`,
-      // Cloned as root, but the install script below runs as the user (and so does whoever edits
-      // these files later) — hand the clone over before touching it.
+      // The clone above already lands as the user. Kept for a worker whose ~/dotfiles was left
+      // root-owned by an earlier release, where the install script below would fail on it.
       `  chown -R ${username}:${username} ${homeDir}/dotfiles`,
       `  _INSTALL_SCRIPT=""`,
       `  for _candidate in install.sh bootstrap.sh setup.sh script/setup; do`,
@@ -1833,6 +1869,7 @@ export function buildSetupPlan(params: SetupScriptParams): {
         index: i,
         total: project.repositories.length,
         homeDir,
+        username,
         branch: resolveRepoBranch(r, branch),
         githubInstallationTokens,
         userSshPrivateKey,

package/src/terminal/dtach.ts

@@ -0,0 +1,302 @@
+// The half of a persistent terminal that is a string, not a socket.
+//
+// A worker's terminal is a `docker exec` attached to a session that outlives it — so that closing a
+// browser tab does not kill a build. The *attaching* is I/O and stays with whoever owns the Docker
+// socket; everything here is the shell that gets attached, the layout it writes into, and the
+// parsing of what it prints back.
+//
+// **dtach, not tmux** (RFC 0019). tmux is a full multiplexer, and its only knob for "the wheel
+// scrolls history" is `mouse on` — which also makes tmux swallow every drag, so the frontend has to
+// forge Shift-drags to get a native selection back. dtach does only persistence: it owns a pty,
+// lets clients attach and detach, and forwards every byte, mouse included. The terminal emulator
+// keeps the mouse, its own scrollback and its own search.
+//
+// What dtach does not do is remember what was on screen. `-r winch` makes the running program
+// redraw on attach, but the history is gone. So the session is recorded inside the container with
+// script(1) and the tail of that recording is replayed just before attaching:
+//
+//   docker exec ──> sh ──> [replay: tail of the log] ──> exec dtach -A ──> script -f log ──> $SHELL
+//                                                             │
+//                                                    persistent master
+//
+// Recording inside the container rather than in an agent-side ring buffer is what makes the buffer
+// survive a control-plane restart with nothing permanently attached.
+
+/**
+ * Where a session's socket and recording live. One directory, two files per session.
+ *
+ * The name deliberately avoids the substring "dtach": the listing and kill scripts match processes
+ * by the socket path, and a path containing "dtach" would make every helper's own shell look like a
+ * dtach process to its own grep.
+ */
+export const TERMINAL_DIR = "/tmp/spunto-term"
+
+/** Bytes of recording replayed on attach. ~64 lines of 120 cols is 8 KB; 256 KB is a few screens of a chatty build. */
+export const REPLAY_BYTES = 262144
+
+/**
+ * Below this there is nothing worth replaying: a session created from a "+" button has already
+ * recorded its prompt, and replaying that would greet the user with a "replay" banner on a terminal
+ * they just opened. The attach redraw paints the prompt anyway.
+ */
+export const REPLAY_MIN_BYTES = 512
+
+/** Above this, the recording is trimmed to `TRIM_TO` bytes on the next attach. */
+export const MAX_LOG_BYTES = 4194304
+export const TRIM_TO = 1048576
+
+/**
+ * Session name a control plane may safely interpolate into the shell scripts below.
+ *
+ * Restricted to `[A-Za-z0-9_-]` — which is both what a socket filename can hold without quoting and
+ * what the listing script's `awk` can match on. **Every name reaching the builders below must come
+ * through here**: they interpolate it into shell, so anything else is an injection.
+ */
+export function sanitizeSessionName(name: string | undefined): string {
+  const cleaned = (name ?? "main").replace(/[^A-Za-z0-9_-]/g, "-").replace(/^-+|-+$/g, "").slice(0, 40)
+  return cleaned || "main"
+}
+
+export function buildDtachCommand(): string {
+  return [
+    `D=${TERMINAL_DIR}`,
+    'N="$MP_TERM_SESSION"',
+    'SOCK="$D/$N.sock"',
+    'LOG="$D/$N.log"',
+    'mkdir -p "$D" 2>/dev/null; chmod 700 "$D" 2>/dev/null',
+    '_SH=$(getent passwd "$(id -un)" 2>/dev/null | cut -d: -f7); _SH=${_SH:-/bin/bash}',
+    // No dtach → say so plainly and degrade to a non-persistent shell.
+    "if ! command -v dtach >/dev/null 2>&1; then",
+    `  printf '\\033[33m[spunto] dtach absent de ce conteneur — shell simple, sans persistance.\\033[0m\\r\\n'`,
+    '  exec "$_SH" -l',
+    "fi",
+    // A session is live only if some process still holds its socket: a leftover
+    // socket file (container restarted, program exited) means the recorded log
+    // belongs to a session that no longer exists, so it is dropped rather than
+    // replayed into a brand new shell.
+    'LIVE=0',
+    'if [ -S "$SOCK" ] && ps -eo args= 2>/dev/null | grep -qF "$SOCK"; then LIVE=1; fi',
+    'if [ "$LIVE" = 0 ]; then rm -f "$SOCK" 2>/dev/null; : > "$LOG" 2>/dev/null; fi',
+    // ── replay buffer ────────────────────────────────────────────────────────
+    // Trim first (the log is append-only and would otherwise grow forever), then
+    // dump its tail. The dump is preceded by a reset because the tail can start
+    // mid-escape-sequence or while the alternate screen / mouse tracking was on;
+    // `tail -n +2` drops the (possibly truncated) first line.
+    'if [ "$LIVE" = 1 ] && [ -f "$LOG" ]; then',
+    '  SZ=$(wc -c < "$LOG" 2>/dev/null || echo 0)',
+    `  if [ "$SZ" -gt ${MAX_LOG_BYTES} ] 2>/dev/null; then`,
+    `    tail -c ${TRIM_TO} "$LOG" > "$LOG.trim" 2>/dev/null && cat "$LOG.trim" > "$LOG" 2>/dev/null; rm -f "$LOG.trim"`,
+    "  fi",
+    `  if [ "$SZ" -gt ${REPLAY_MIN_BYTES} ] 2>/dev/null; then`,
+    `    printf '\\033[?1049l\\033[?1000l\\033[?1002l\\033[?1003l\\033[?1006l\\033c'`,
+    `    printf '\\033[2m── replay ──\\033[0m\\r\\n'`,
+    `    tail -c ${REPLAY_BYTES} "$LOG" 2>/dev/null | tail -n +2`,
+    "  fi",
+    "fi",
+    // ── attach ───────────────────────────────────────────────────────────────
+    // script(1) records the session's raw output for the replay above. Without it
+    // the session still works, it just comes back blank.
+    "if command -v script >/dev/null 2>&1; then",
+    '  exec dtach -A "$SOCK" -r winch -E -z script -q -a -f "$LOG" -c "$_SH -l"',
+    "else",
+    '  exec dtach -A "$SOCK" -r winch -E -z "$_SH" -l',
+    "fi",
+  ].join("\n")
+}
+
+// A dtach session is a socket file, nothing more — no server to ask. Name and
+// creation date come from the socket itself; the foreground command has to be
+// recovered from the container's process table (this is the metadata tmux gives
+// away for free, see the RFC): walk the process tree down from the dtach master
+// and keep the deepest descendant that sits in its pty's foreground process
+// group (the `+` in ps's STAT), which is exactly what `pane_current_command` means.
+export const LIST_SESSIONS_SCRIPT = [
+  `D=${TERMINAL_DIR}`,
+  '[ -d "$D" ] || exit 0',
+  'PSOUT=$(ps -eo pid=,ppid=,stat=,args= 2>/dev/null || true)',
+  'ESC=$(printf "\\033"); BEL=$(printf "\\007")',
+  'for s in "$D"/*.sock; do',
+  '  [ -S "$s" ] || continue',
+  '  n=$(basename "$s" .sock)',
+  '  created=$(stat -c %Y "$s" 2>/dev/null || echo 0)',
+  '  cmd=$(printf "%s\\n" "$PSOUT" | awk -v sock="$s" \'',
+  "    {",
+  "      pid=$1; ppid=$2; st=$3;",
+  '      args=""; for (i=4; i<=NF; i++) args = args (i>4 ? " " : "") $i;',
+  "      n++; order[n]=pid; P[pid]=ppid; S[pid]=st; A[pid]=args;",
+  '      if (index(args, sock) > 0) d[pid]=0;',
+  "    }",
+  "    END {",
+  "      for (iter=0; iter<12; iter++)",
+  "        for (i=1; i<=n; i++) { p=order[i]; if (!(p in d) && (P[p] in d)) d[p]=d[P[p]]+1 }",
+  '      best=""; bestd=0;',
+  "      for (i=1; i<=n; i++) {",
+  "        p=order[i];",
+  "        if (!(p in d) || d[p]==0) continue;",
+  '        if (S[p] !~ /\\+/) continue;',
+  '        c=A[p]; sub(/ .*/, "", c); sub(/.*\\//, "", c); sub(/^-/, "", c);',
+  '        if (c=="script" || c=="dtach") continue;',
+  "        if (d[p] >= bestd) { bestd=d[p]; best=c }",
+  "      }",
+  "      print best",
+  "    }')",
+  // Reported title (OSC 0/2, see terminal-title.ts). tmux keeps it in
+  // `pane_title`; dtach forwards every byte to the terminal and remembers
+  // nothing, so it is dug out of the replay log: the last `ESC ] 0|2 ; … BEL`
+  // written is the title currently on screen. Best effort — a container whose
+  // grep lacks `-a` simply yields no title and the UI falls back to the name.
+  '  t=$(tail -c 65536 "$D/$n.log" 2>/dev/null | LC_ALL=C grep -ao "$ESC][02];[^$BEL$ESC]*" 2>/dev/null | tail -n 1 | LC_ALL=C cut -c5-)',
+  '  echo "$n|1|0|$created|$cmd|$t"',
+  "done",
+].join("\n")
+
+/** Longest title kept — anything past that is a program dumping data, not naming itself. */
+const MAX_TITLE_LENGTH = 120
+
+/**
+ * Normalize a reported title, or return "" when there is nothing worth showing.
+ *
+ * `placeholders` are the values that mean "no one reported anything": tmux seeds
+ * `pane_title` with the container hostname, so a title still equal to it says
+ * only that the session never set one.
+ */
+export function sanitizeReportedTitle(raw: string | undefined, placeholders: string[] = []): string {
+  const title = (raw ?? "")
+    // Control characters (a stray BEL/ESC from a truncated read, a newline) would
+    // land as-is in a JSON payload and then in a React tree.
+    .replace(/[\u0000-\u001f\u007f]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, MAX_TITLE_LENGTH)
+  if (!title) return ""
+  if (placeholders.some((p) => p && p.trim() === title)) return ""
+  return title
+}
+
+/**
+ * dtach clears the screen as soon as a client attaches — a bare `ESC[H ESC[J` ("Clear the screen.
+ * This assumes VT100." in dtach's own source). That write lands *after* the replay the attach
+ * script just printed, and wipes exactly what the replay exists to show.
+ *
+ * So it is dropped: once, and only in the first seconds of an attach — long enough to cover
+ * dtach's write, short enough that a program legitimately clearing its screen later is never
+ * touched. (`clear` emits `ESC[H ESC[2J ESC[3J`, different bytes, so it would not match anyway.)
+ *
+ * `Uint8Array` in and out rather than Node's Buffer: a Buffer is one, so a Node caller passes its
+ * chunks straight through, and the package stays runnable anywhere.
+ */
+export function makeAttachClearStripper(
+  windowMs = 5000,
+  now: () => number = Date.now,
+): (chunk: Uint8Array) => Uint8Array {
+  const CLEAR = new TextEncoder().encode("\x1b[H\x1b[J")
+  const deadline = now() + windowMs
+  let done = false
+  return (chunk) => {
+    if (done) return chunk
+    if (now() > deadline) {
+      done = true
+      return chunk
+    }
+    const i = indexOfBytes(chunk, CLEAR)
+    if (i === -1) return chunk
+    done = true
+    const out = new Uint8Array(chunk.length - CLEAR.length)
+    out.set(chunk.subarray(0, i), 0)
+    out.set(chunk.subarray(i + CLEAR.length), i)
+    return out
+  }
+}
+
+/** `Buffer.indexOf` for a plain Uint8Array — the needle is 6 bytes, so the naive scan is the right one. */
+function indexOfBytes(haystack: Uint8Array, needle: Uint8Array): number {
+  outer: for (let i = 0; i + needle.length <= haystack.length; i++) {
+    for (let j = 0; j < needle.length; j++) if (haystack[i + j] !== needle[j]) continue outer
+    return i
+  }
+  return -1
+}
+
+/** One persistent session of a worker, as a control plane reports it. */
+export type TerminalSession = {
+  name: string
+  /** Always 1 — dtach has no windows. Kept so a UI written against a multiplexer still renders. */
+  windows: number
+  /**
+   * Decided by the caller, not by this parse: a socket says nothing about who is connected, and the
+   * process that attaches is the one that knows.
+   */
+  attached: boolean
+  createdAt: number
+  command: string
+  /** Title the running program reported over OSC 0/2 ("" when it reported none). */
+  title: string
+}
+
+/**
+ * Parse what `LIST_SESSIONS_SCRIPT` printed into sessions.
+ *
+ * Separate from running it: executing a command inside a container is the caller's business, and
+ * keeping the parse here is what lets it be tested without a container.
+ */
+export function parseSessionList(output: string, isAttached: (session: string) => boolean): TerminalSession[] {
+  return output
+    .trim()
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      // The title is free-form and last, so it keeps any "|" it contains.
+      const parts = line.split("|")
+      const [name = "", , , created = "0", command = ""] = parts
+      return {
+        name: name.trim(),
+        windows: 1,
+        attached: isAttached(name.trim()),
+        createdAt: (parseInt(created) || 0) * 1000,
+        command: command.trim(),
+        title: sanitizeReportedTitle(parts.slice(5).join("|")),
+      }
+    })
+    .filter((s) => s.name)
+}
+
+/**
+ * Shell that creates a session without attaching to it — `dtach -n` daemonizes the master.
+ *
+ * `session` must already have been through `sanitizeSessionName`: it is interpolated into the
+ * script.
+ */
+export function buildCreateSessionCommand(session: string): string {
+  return [
+    `D=${TERMINAL_DIR}`,
+    `N="${session}"`,
+    'mkdir -p "$D" 2>/dev/null; chmod 700 "$D" 2>/dev/null',
+    "command -v dtach >/dev/null 2>&1 || exit 0",
+    '[ -S "$D/$N.sock" ] && exit 0',
+    '_SH=$(getent passwd "$(id -un)" 2>/dev/null | cut -d: -f7); _SH=${_SH:-/bin/bash}',
+    // stdio redirected: the daemonized master inherits the exec's fds and would otherwise hold its
+    // stdout open long after the session exists.
+    "if command -v script >/dev/null 2>&1; then",
+    '  dtach -n "$D/$N.sock" -r winch -E -z script -q -a -f "$D/$N.log" -c "$_SH -l" </dev/null >/dev/null 2>&1',
+    "else",
+    '  dtach -n "$D/$N.sock" -r winch -E -z "$_SH" -l </dev/null >/dev/null 2>&1',
+    "fi",
+  ].join("\n")
+}
+
+/**
+ * Shell that kills a session: SIGTERM every process holding its socket (master and any client),
+ * then drop the socket and the recording.
+ *
+ * `session` must already have been through `sanitizeSessionName`.
+ */
+export function buildKillSessionCommand(session: string): string {
+  return [
+    `SOCK=${TERMINAL_DIR}/${session}.sock`,
+    'for p in $(ps -eo pid=,args= 2>/dev/null | awk -v sock="$SOCK" -v me=$$ \'$1 != me && index($0, sock) > 0 && index($0, "dtach") > 0 { print $1 }\'); do',
+    '  kill "$p" 2>/dev/null',
+    "done",
+    `rm -f "$SOCK" ${TERMINAL_DIR}/${session}.log 2>/dev/null`,
+    "true",
+  ].join("\n")
+}

package/src/terminal/index.ts

@@ -0,0 +1,22 @@
+// The half of a persistent terminal that is a string, not a socket: the shell that gets attached,
+// the layout it writes into, and the parsing of what it prints back. Attaching is I/O and stays
+// with whoever owns the Docker socket.
+//
+// See `./dtach` for why dtach and not tmux (RFC 0019).
+
+export {
+  buildCreateSessionCommand,
+  buildDtachCommand,
+  buildKillSessionCommand,
+  LIST_SESSIONS_SCRIPT,
+  makeAttachClearStripper,
+  MAX_LOG_BYTES,
+  parseSessionList,
+  REPLAY_BYTES,
+  REPLAY_MIN_BYTES,
+  sanitizeReportedTitle,
+  sanitizeSessionName,
+  TERMINAL_DIR,
+  TRIM_TO,
+} from "./dtach"
+export type { TerminalSession } from "./dtach"