pi-supernova 0.9.0 → 0.10.0

package/src/context/snap-search.js

@@ -15,17 +15,15 @@ function inScope(filePath, dir, includeHidden) {
   return !parts.includes(".git") && (includeHidden || !parts.some(part => part.startsWith(".") && part.length > 1));
 }
 
-function makeCandidate(filePath, dir, query, tokens, flags) {
+function makeCandidate(filePath, dir, query, tokens, flags, needles = tokens.map(token => stem(token).slice(0, MAX_NEEDLE_CHARS))) {
   const relative = path.relative(dir, filePath);
   const lower = relative.toLowerCase();
   const base = path.basename(lower);
 
   const extension = path.extname(base);
   const stemBase = extension ? base.slice(0, -extension.length) : base;
-  const exactPath = lower === query.toLowerCase() || base === query.toLowerCase()
-    || stemBase === query.toLowerCase();
-
-  const needles = tokens.map(token => stem(token).slice(0, MAX_NEEDLE_CHARS));
+  const queryLower = query.toLowerCase();
+  const exactPath = lower === queryLower || base === queryLower || stemBase === queryLower;
 
   return { path: filePath, pathScore: scorePathTopology(relative, tokens, flags), exactPath,
     pathCoverage: tokens.filter((token, index) => lower.includes(needles[index] ?? token)).length,
@@ -120,7 +118,7 @@ function parseRgRecord(line, truncated, isLast) {
   }
 }
 
-function absorbRgHit(candidates, record, dir, includeHidden, overlayText, candidateRoot, query, tokens, flags, needles) {
+function absorbRgHit(candidates, record, dir, includeHidden, overlayText, candidateRoot, query, tokens, flags, needles, candidateNeedles) {
   if (record.type !== "match" && record.type !== "context") return;
   const data = record.data;
 
@@ -131,21 +129,21 @@ function absorbRgHit(candidates, record, dir, includeHidden, overlayText, candid
   let candidate = candidates.get(filePath);
 
   if (!candidate) {
-    candidate = makeCandidate(filePath, candidateRoot, query, tokens, flags);
+    candidate = makeCandidate(filePath, candidateRoot, query, tokens, flags, candidateNeedles);
     candidates.set(filePath, candidate);
   }
 
   inspectLine(candidate, data.line_number, data.lines.text, query, tokens, needles, record.type === "match");
 }
 
-function overlayCandidates(candidates, pendingPaths, overlayText, candidateRoot, query, tokens, flags, needles, signal) {
+function overlayCandidates(candidates, pendingPaths, overlayText, candidateRoot, query, tokens, flags, needles, candidateNeedles, signal) {
   let overlayTruncated = false;
 
   for (const filePath of pendingPaths) {
     const pending = overlayText(filePath);
 
     if (pending === undefined) continue;
-    const candidate = makeCandidate(filePath, candidateRoot, query, tokens, flags);
+    const candidate = makeCandidate(filePath, candidateRoot, query, tokens, flags, candidateNeedles);
     overlayTruncated = inspectOverlay(candidate, pending, needles, query, tokens, signal) || overlayTruncated;
 
     if (candidate.matched.size) candidates.set(filePath, candidate);
@@ -176,7 +174,7 @@ async function runContentSearch({ dir, includeHidden, searchNeedles, run, overla
   return response;
 }
 
-function absorbRgRecords(candidates, response, dir, includeHidden, overlayText, candidateRoot, query, tokens, flags, needles, signal) {
+function absorbRgRecords(candidates, response, dir, includeHidden, overlayText, candidateRoot, query, tokens, flags, needles, candidateNeedles, signal) {
   const records = response.stdout.split("\n");
 
   for (let i = 0; i < records.length; i++) {
@@ -185,17 +183,20 @@ function absorbRgRecords(candidates, response, dir, includeHidden, overlayText,
 
     if (record === undefined) break;
     if (!record) continue;
-    absorbRgHit(candidates, record, dir, includeHidden, overlayText, candidateRoot, query, tokens, flags, needles);
+    absorbRgHit(candidates, record, dir, includeHidden, overlayText, candidateRoot, query, tokens, flags, needles, candidateNeedles);
   }
 }
 
 async function contentCandidates({ dir, includeHidden, query, tokens, flags, pendingPaths, run, overlayText, signal, exact, diskFiles, focusFile }) {
   const needles = exact ? [query.toLowerCase().slice(0, MAX_NEEDLE_CHARS)] : tokens.map(token => stem(token).slice(0, MAX_NEEDLE_CHARS));
+  // Coverage needles are always token-derived (even in exact mode, where the
+  // search needles collapse to the query): computed once, not once per file.
+  const candidateNeedles = exact ? tokens.map(token => stem(token).slice(0, MAX_NEEDLE_CHARS)) : needles;
   const candidateRoot = focusFile ? path.dirname(focusFile) : dir;
   const candidates = new Map();
   const response = await runContentSearch({ dir, includeHidden, searchNeedles: [...new Set(needles)], run, overlayText, signal, diskFiles, focusFile });
-  absorbRgRecords(candidates, response, dir, includeHidden, overlayText, candidateRoot, query, tokens, flags, needles, signal);
-  const overlayTruncated = overlayCandidates(candidates, pendingPaths, overlayText, candidateRoot, query, tokens, flags, needles, signal);
+  absorbRgRecords(candidates, response, dir, includeHidden, overlayText, candidateRoot, query, tokens, flags, needles, candidateNeedles, signal);
+  const overlayTruncated = overlayCandidates(candidates, pendingPaths, overlayText, candidateRoot, query, tokens, flags, needles, candidateNeedles, signal);
 
   return { candidates, truncated: response.outputTruncated === true || overlayTruncated };
 }

package/src/context/snap.js

@@ -1,6 +1,8 @@
 import {inScope,makeCandidate,contentCandidates,MAX_SEARCH_CHARS} from './snap-search.js';
 import { tokenizeQuery, stem } from "./query.js";
+
 export {tokenizeQuery,scorePathTopology,stem} from './query.js';
+
 import * as path from "node:path";
 
 import * as fs from "node:fs/promises";
@@ -22,13 +24,13 @@ function rankScore(candidate, tokenCount) {
 function location(candidate, root) {
   const context = candidate.context;
 
-  return { path: path.relative(root, candidate.path), line: candidate.line, signature: candidate.signature,
+  return { path: relativeSlash(root, candidate.path), line: candidate.line, signature: candidate.signature,
     context: [...context].sort((a, b) => a[0] - b[0]).map(([line, text]) => (line === candidate.line ? "►" : " ") + line + " " + text) };
 }
 
 async function spanCandidates(filePath, lines, root, overlayText, signal) {
   const staged = overlayText(filePath);
-  const rel = path.relative(root, filePath);
+  const rel = relativeSlash(root, filePath);
   let text = staged;
 
   if (text === undefined) {
@@ -38,10 +40,12 @@ async function spanCandidates(filePath, lines, root, overlayText, signal) {
       const stat = await file.stat();
 
       if (!stat.isFile()) throw new Error("source candidate is not a regular file: " + filePath);
+
       if (stat.size > 512 * 1024) return lines.map(line => ({ path: rel, line, signature: "", context: [] }));
       text = await file.readFile({ encoding: "utf8", signal });
     } finally { await file.close(); }
   }
+
   const spans = WorkspaceIndex.spansOf(WorkspaceIndex.fromText(filePath, text));
 
   return lines.map(line => {
@@ -68,6 +72,7 @@ async function rankedSpanCandidates(ranked, root, overlayText, signal) {
       try { out.push(...await spanCandidates(candidate.path, lines, root, overlayText, signal)); }
       catch { signal?.throwIfAborted(); out.push(location(candidate, root)); }
     }
+
     if (out.length >= MAX_ALTERNATIVES) break;
   }
 
@@ -104,7 +109,9 @@ function listedSnapPaths(listing, dir, includeHidden, focusFile, pendingPaths) {
 
 function filenameEligible(search, filePath, relative, tokens, exact, queryLower) {
   if (search.candidates.has(filePath)) return false;
+
   if (!tokens.some(token => relative.includes(token))) return false;
+
   if (exact && tokens.length > 1 && !relative.includes(queryLower)) return false;
 
   return true;
@@ -174,6 +181,7 @@ async function decideSnapResult(ranked, tokens, empty, candidates, relativeRoot,
 function fuzzySnapMiss(exact, query, paths, pathContext, relativeRoot, empty) {
   const eligible = exact && query.length >= 4 && query.length <= 64;
   const limited = eligible && paths.length > 1024;
+
   const fuzzy = eligible ? rankPaths(query, paths.slice(0, 1024).map(file => relativeSlash(relativeRoot, file)),
     { ...pathContext, maxTypos: 1 }).filter(hit => hit.score > 0).slice(0, MAX_ALTERNATIVES) : [];
 
@@ -209,6 +217,7 @@ export async function executeSnap({ query, searchDir, root, includeHidden = fals
   signal?.throwIfAborted();
 
   const empty = emptySnap();
+
   const dirStat = await fs.stat(dir).catch(error => {
     if (error.code !== "ENOENT" && error.code !== "ENOTDIR") throw error;
 

package/src/contract/bash.js

@@ -2,13 +2,10 @@ import { isString, isObject } from "../shared/decode.js";
 
 const ARGV_ERROR = "bash argv requires a command string and an array of string args";
 
-function quoteShellArg(value) {
-  return "'" + String(value).replaceAll("'", "'\\''") + "'";
-}
-
 /** Normalize guest bash(command, opts) / bash({command, args}) into host args. */
 function normalizeArgv(args) {
   if (args.args === undefined) return;
+
   if (!isString(args.command) || !Array.isArray(args.args)) throw new Error(ARGV_ERROR);
 
   for (let i = 0; i < args.args.length; i++) {
@@ -17,30 +14,39 @@ function normalizeArgv(args) {
       throw new Error(`${ARGV_ERROR}; args[${i}] is ${type}; check the supplied data fields and pass each argument as a string`);
     }
   }
+
   args.args = args.args.map((arg, i) => {
     if (arg.includes("\0")) throw new Error(`bash args[${i}] must not contain null bytes`);
+
     return String(arg);
   });
 
-  if (process.platform === "win32") {
-    delete args._directArgv;
-    args.command = [args.command, ...args.args].map(quoteShellArg).join(" ");
-    delete args.args;
-  } else args._directArgv = true;
+  args._directArgv = true;
 }
 
-const BASH_OPTION_KEYS = ["command", "args", "cwd", "timeout", "timeoutMs", "_directArgv"];
+const BASH_OPTION_KEYS = ["command", "args", "cwd", "timeout", "timeoutMs", "_directArgv", "background", "pty"];
 
 /** Unknown options used to be dropped silently: env/maxOutputChars never applied. */
 function assertBashOptions(args) {
   const unknown = Object.keys(args).filter(key => !BASH_OPTION_KEYS.includes(key));
 
-  if (unknown.length) throw new Error("bash does not accept option " + unknown.map(key => JSON.stringify(key)).join(", ") + "; supported options are command, args, cwd, timeout, timeoutMs");
+  if (unknown.length) throw new Error("bash does not accept option " + unknown.map(key => JSON.stringify(key)).join(", ") + "; supported options are command, args, cwd, timeout, timeoutMs, background, pty");
 }
+
 export function normalizeBash(command, opts) {
   const args = isObject(command) ? { ...opts, ...command } : { command, ...opts };
+
+  if (args.action !== undefined || args.sessionId !== undefined) return normalizeTerminalControl(args);
   assertBashOptions(args);
+
+  for (const key of ["background", "pty"]) {
+    if (args[key] !== undefined && args[key] !== true && args[key] !== false) throw new Error(`bash ${key} must be boolean`);
+  }
+
+  if (args.pty !== undefined && args.background !== true) throw new Error("bash pty requires background:true");
+
   if (!isString(args.command) || !args.command.trim()) throw new Error("bash requires a non-empty command string");
+
   if (args.command.includes("\0")) throw new Error("bash command must not contain null bytes");
   normalizeArgv(args);
 
@@ -49,11 +55,37 @@ export function normalizeBash(command, opts) {
   return args;
 }
 
+function normalizeTerminalControl(args) {
+  const fields = {
+    list: ["action"],
+    poll: ["action", "sessionId", "cursor", "waitMs"],
+    write: ["action", "sessionId", "input"],
+    stop: ["action", "sessionId"],
+  };
+
+  if (!Object.hasOwn(fields, args.action)) throw new Error("bash terminal action must be list, poll, write or stop");
+  const unknown = Object.keys(args).filter(key => !fields[args.action].includes(key));
+
+  if (unknown.length) throw new Error(`bash ${args.action} does not accept option ${unknown.join(", ")}`);
+
+  if (args.action !== "list" && (!isString(args.sessionId) || !args.sessionId.trim())) throw new Error("bash terminal action requires sessionId");
+
+  if (args.action === "write" && (!isString(args.input) || args.input.length > 16384)) throw new Error("bash terminal input must be a string of at most 16384 characters");
+
+  if (args.cursor !== undefined && (!Number.isSafeInteger(args.cursor) || args.cursor < 0)) throw new Error("bash terminal cursor must be a non-negative safe integer");
+
+  if (args.waitMs !== undefined && (!Number.isInteger(args.waitMs) || args.waitMs < 0 || args.waitMs > 30000)) throw new Error("bash terminal waitMs must be an integer from 0 to 30000");
+
+  return args;
+}
+
 function normalizeTimeout(args) {
   if (args.timeout !== undefined && args.timeoutMs === undefined) args.timeoutMs = args.timeout * 1000;
+
   // Reject before the host's external-mutation barrier can flush staged files.
   if (args.timeoutMs !== undefined) {
     const timeout = Number(args.timeoutMs);
+
     if (!Number.isFinite(timeout) || timeout <= 0) throw new Error("command timeoutMs must be a positive finite number");
     args.timeoutMs = Math.max(1, Math.min(2_147_483_647, Math.floor(timeout)));
   }

package/src/contract/read.js

@@ -12,6 +12,7 @@ function assertReadOptions(args) {
   const unknown = Object.keys(args).filter(key => !READ_OPTION_KEYS.includes(key));
 
   if (unknown.length === 0) return;
+
   const windowHint = unknown.some(key => key === "start" || key === "end")
     ? " For a line window use read(path, {offset:1, limit:80}): offset is the first line and limit is the line count."
     : "";
@@ -33,11 +34,14 @@ export function gatherReadArgs(p, a, b) {
     return args;
   }
 
-  return isObject(a) && !Array.isArray(a) ? { path: p, ...a } : { path: p, offset: a, limit: b };
+  // Only the string shorthand guesses between a path and a symbol. Explicit
+  // path/target objects and path arrays must not turn missing files into search.
+  return autoResolve(isObject(a) && !Array.isArray(a) ? { path: p, ...a } : { path: p, offset: a, limit: b });
 }
 
 export function assertReadPaths(targetParam) {
   if (!Array.isArray(targetParam)) return;
+
   if (targetParam.length > 64) throw new Error("read accepts at most 64 paths per batch");
 
   for (const item of targetParam) if (!isString(item) || !item.trim()) throw new Error("read paths must be non-empty strings");
@@ -49,6 +53,7 @@ function assertReadFlags(args) {
   }
 
   if (args.about !== undefined && !isString(args.about)) throw new Error("read about must be a string");
+
   if (args.query !== undefined && !isString(args.query)) throw new Error("read query must be a string");
 }
 
@@ -56,20 +61,24 @@ function assertExclusiveRead(args) {
   const focusModes = [args.about !== undefined, args.query !== undefined, args.outline === true].filter(Boolean).length;
 
   if (focusModes > 1 || (args.outline === true && args.evidence === true)) throw new Error("read accepts only one of about, query, outline, or evidence");
+
   if (args.resolve === true && args.complete === true) throw new Error("read accepts either resolve or complete, not both");
+
   if ((focusModes === 1 || args.evidence === true) && args.complete === true) throw new Error("complete:true requires a raw file read, not a source view");
 }
 
 function autoResolve(args) {
   if (!isString(args.path) || args.resolve !== undefined || args.complete === true || args.json !== undefined) return args;
-  if (args.about !== undefined || args.query !== undefined || looksLikePath(args.path) || isSessionUri(args.path)) return args;
+
+  if (args.about !== undefined || args.query !== undefined || args.offset !== undefined || args.limit !== undefined || looksLikePath(args.path) || isSessionUri(args.path)) return args;
 
   return { ...args, resolve: true };
 }
 
-/** Exclusive-mode + JSON + auto-resolve. Same rules for guest and host. */
+/** Preserve explicit intent across guest, host, and coalesced batch normalization. */
 export function normalizeRead(params) {
   if (!isObject(params)) throw new Error("read requires an options object");
+
   if (params.path !== undefined && params.target !== undefined && params.path !== params.target) {
     throw new Error("read accepts either path or target, not both");
   }
@@ -81,7 +90,7 @@ export function normalizeRead(params) {
   assertExclusiveRead(args);
   assertReadPaths(args.path);
 
-  return autoResolve(args);
+  return args;
 }
 
 export function needsProbe(params) {
@@ -126,7 +135,7 @@ function classifyEvidence(params, target) {
 }
 
 function classifyBarePath(params, target) {
-  if (params.json === undefined && !looksLikePath(target)) {
+  if (params.resolve === true && params.json === undefined && !looksLikePath(target)) {
     return { kind: "snap", query: isString(params.about) ? params.about : target, scoped: isString(params.about) };
   }
 
@@ -139,9 +148,13 @@ export function classifyRead(params, existing) {
   const target = params.path;
 
   if (isSessionUri(target)) return classifySession(params);
+
   if (params.evidence === true) return classifyEvidence(params, target);
+
   if (isString(params.query)) return { kind: "snap", query: params.query, scoped: Boolean(target && target !== params.query) };
+
   if (params.outline === true) return { kind: "outline" };
+
   if (existing) return classifyExisting(params, existing);
 
   return classifyBarePath(params, target);
@@ -186,5 +199,6 @@ export function decodeReadValue(args, value) {
 
 function jsonReadError(args, error) {
   const target = String(args.path ?? args.target ?? "resource");
+
   return new Error("JSON read failed for " + target + jsonSelectorNote(args) + ": " + errorMessage(error));
 }

package/src/fs/background.js

@@ -0,0 +1,304 @@
+import { spawnCommand, commandSpawnError } from "./workspace.js";
+import { retireProcessTree } from "./process-tree.js";
+import { randomUUID } from "node:crypto";
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+
+const MAX_RUNNING = 8;
+
+const MAX_RETAINED = 32;
+
+const OUTPUT_CHARS = 65536;
+
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+
+function terminalArgv(argv) {
+  // The PTY child is a process-group leader. Capture that identity before exec,
+  // then close the control FD so commands cannot hold it open or forge messages.
+  const command = ["/bin/sh", "-c", 'printf "group:%s\\n" "$$" >&3; /bin/stty cols 80 rows 24 || exit; exec "$@" 3>&-', "supernova-command", ...argv];
+
+  // Node uses socketpairs for stdio; macOS script needs a real input pipe.
+  // Report script's exit separately from the feeder, which may still await input.
+  if (process.platform === "darwin") return ["/bin/sh", "-c", '/bin/cat | { "$@"; code=$?; printf "exit:%s\\n" "$code" >&3; }', "supernova-pty", "/usr/bin/script", "-q", "-F", "/dev/null", ...command];
+  const quote = value => "'" + value.replaceAll("'", "'\\''") + "'";
+
+  return ["/usr/bin/script", "-q", "-e", "-f", "-c", "exec " + command.map(quote).join(" "), "/dev/null"];
+}
+
+function notifyChanged(job) {
+  // Advisory invalidation must not prevent resource cleanup or escape an event.
+  try { job.changed?.(); } catch {}
+
+  if (job.cleaned) job.changed = undefined;
+}
+
+function wake(job) {
+  for (const notify of job.waiters) notify();
+}
+
+function appendOutput(job, chunk) {
+  job.total += chunk.length;
+  job.output = (job.output + chunk).slice(-OUTPUT_CHARS);
+  wake(job);
+}
+
+function snapshot(job, cursor = 0) {
+  if (cursor > job.total) throw new Error("terminal cursor is beyond available output");
+  const start = job.total - job.output.length;
+  const outputStart = Math.max(start, cursor);
+
+  const result = {
+    sessionId:job.id, pid:job.child.pid, status:job.status, pty:job.pty,
+    exitCode:job.exitCode, signal:job.signal, outputStart, cursor:job.total,
+    truncated:cursor < start, output:job.output.slice(outputStart-start),
+  };
+
+  if (job.error) result.error = job.error;
+
+  return result;
+}
+
+function waitForChange(job, waitMs, signal) {
+  signal?.throwIfAborted();
+
+  return new Promise((resolve, reject) => {
+    const done = error => {
+      clearTimeout(timer);
+      job.waiters.delete(changed);
+      signal?.removeEventListener("abort", aborted);
+
+      if (error) reject(error); else resolve();
+    };
+
+    const changed = () => done();
+    const aborted = () => done(new Error("terminal poll aborted; job remains running"));
+    const timer = setTimeout(changed, waitMs);
+    job.waiters.add(changed);
+    signal?.addEventListener("abort", aborted, {once:true});
+  });
+}
+
+function sendInput(job, input, signal) {
+  signal?.throwIfAborted();
+
+  if (job.child.stdin.writableLength > OUTPUT_CHARS) throw new Error("terminal input queue is full; wait before writing more");
+
+  return new Promise((resolve, reject) => {
+    const done = error => {
+      signal?.removeEventListener("abort", aborted);
+
+      if (error) reject(error); else resolve();
+    };
+
+    const aborted = () => done(new Error("terminal input aborted; input may have been sent"));
+    signal?.addEventListener("abort", aborted, {once:true});
+    job.child.stdin.write(input, done);
+  });
+}
+
+export function createBackgroundTerminals() {
+  const jobs = new Map();
+  let closed = false;
+  let generation = 0;
+  let closing;
+
+  function lookup(id, owner) {
+    const job = jobs.get(id);
+
+    if (!job || job.owner !== owner) throw new Error("unknown background terminal session: " + id);
+
+    return job;
+  }
+
+  function assertCapacity(expectedGeneration) {
+    if (closed || expectedGeneration !== generation) throw new Error("background terminal session changed or closed; start a new call");
+
+    if ([...jobs.values()].filter(job=>!job.cleaned).length >= MAX_RUNNING) throw new Error("background terminal limit reached (8 running); stop a session first");
+  }
+
+  async function validateStart(params, expectedGeneration = generation) {
+    assertCapacity(expectedGeneration);
+
+    if (params.pty) {
+      if (!["darwin","linux"].includes(process.platform)) throw new Error("PTY background terminals require macOS or Linux; use pty:false for pipes");
+      await access("/usr/bin/script", constants.X_OK).catch(()=>{throw new Error("PTY background terminals require executable /usr/bin/script; use pty:false for pipes");});
+    }
+  }
+
+  async function terminate(job, status) {
+    if (job.stopping) return job.stopping;
+
+    if (job.cleaned) return;
+    job.stopping = (async () => {
+      clearTimeout(job.timer);
+      await retireProcessTree(job);
+      job.cleaned = true;
+      job.error = job.processError;
+      job.status = job.error ? "failed" : status;
+      notifyChanged(job);
+      wake(job);
+    })().catch(error => {
+      job.stopping = null; // A later stop/shutdown must be able to retry cleanup.
+      job.status = "failed";
+      job.error = "terminal cleanup failed: " + error.message;
+      notifyChanged(job);
+      wake(job);
+      throw error;
+    });
+
+    return job.stopping;
+  }
+
+  async function start(argv, options) {
+    const startedGeneration = options.generation ?? generation;
+    await validateStart(options, startedGeneration);
+    options.signal?.throwIfAborted();
+    // Capacity and lifecycle can change while the PTY capability check awaits.
+    assertCapacity(startedGeneration);
+
+    while (jobs.size >= MAX_RETAINED) {
+      const old = [...jobs.values()].find(job=>job.cleaned);
+
+      if (!old) break;
+      jobs.delete(old.id);
+    }
+
+    const command = options.pty ? terminalArgv(argv) : argv;
+
+    const child = spawnCommand(command, {
+      cwd:options.cwd, env:options.pty ? {...options.env,TERM:options.env.TERM || "xterm-256color"} : options.env,
+      stdio:options.pty ? ["pipe","pipe","pipe","pipe"] : ["pipe","pipe","pipe"],
+    });
+
+    const job = {
+      id:randomUUID(), owner:options.owner, child, pty:options.pty === true,
+      status:"running", output:"", total:0, exitCode:null, signal:null,
+      waiters:new Set(), changed:options.changed, groups:new Set(child.pid ? [child.pid] : []), killedGroups:new Set(), cleaned:false,
+    };
+
+    jobs.set(job.id,job);
+    child.stdin.on("error",()=>{}); // EPIPE is delivered to each write callback, never uncaught.
+
+    if (job.pty) {
+      let control = "";
+      child.stdio[3].setEncoding("utf8");
+      child.stdio[3].on("data",chunk=>{
+        control += chunk;
+
+        if (control.length > 128) {
+          job.processError = "invalid PTY control message";
+          void terminate(job,"failed").catch(()=>{});
+
+          return;
+        }
+
+        let newline;
+
+        while ((newline = control.indexOf("\n")) >= 0) {
+          const message = control.slice(0,newline);
+          control = control.slice(newline+1);
+
+          if (/^group:[1-9]\d*$/.test(message)) job.groups.add(Number(message.slice(6)));
+          else if (/^exit:\d+$/.test(message)) {
+            job.commandExitCode = Number(message.slice(5));
+            void terminate(job,"exited").catch(()=>{});
+          } else job.processError = "invalid PTY control message";
+        }
+      });
+      child.stdio[3].on("error",error=>{
+        job.processError = error.message;
+        void terminate(job,"failed").catch(()=>{});
+      });
+    }
+
+    for (const stream of [child.stdout,child.stderr]) {
+      stream.setEncoding("utf8");
+      stream.on("data",chunk=>appendOutput(job,chunk));
+    }
+
+    child.once("exit",(code,signal)=>{
+      job.processExited = true;
+      job.exitCode = job.commandExitCode ?? code;
+      job.signal = job.commandExitCode === undefined ? signal : null;
+      void terminate(job,"exited").catch(()=>{});
+    });
+    child.once("close",(code,signal)=>{
+      job.processClosed = true;
+      job.exitCode = job.commandExitCode ?? code;
+      job.signal = job.commandExitCode === undefined ? signal : null;
+    });
+
+    try {
+      await new Promise((resolve,reject)=>{
+        child.once("spawn",resolve);
+        child.once("error",error=>{const mapped=commandSpawnError(error,command[0]);job.error=mapped.message;reject(mapped);});
+      });
+
+      if (options.signal?.aborted || closed || startedGeneration !== generation) {
+        await terminate(job,"stopped");
+        throw new Error("background terminal start aborted");
+      }
+    } catch (error) {
+      if (!child.pid || job.cleaned) jobs.delete(job.id);
+      throw error;
+    }
+
+    job.timer = setTimeout(()=>{void terminate(job,"timed_out").catch(()=>{});},options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    job.timer.unref?.();
+
+    return snapshot(job);
+  }
+
+  function validateControl(params, owner, expectedGeneration = generation) {
+    if (expectedGeneration !== generation) throw new Error("background terminal session changed; start a new call");
+
+    if (params.action === "list") return;
+    const job = lookup(params.sessionId,owner);
+
+    if (params.action === "write" && (job.status !== "running" || job.stopping)) throw new Error("background terminal is not running");
+
+    if (params.cursor !== undefined && params.cursor > job.total) throw new Error("terminal cursor is beyond available output");
+  }
+
+  async function control(params, owner, signal, expectedGeneration = generation) {
+    validateControl(params,owner,expectedGeneration);
+    signal?.throwIfAborted();
+
+    if (params.action === "list") return [...jobs.values()].flatMap(job=>job.owner === owner ? [snapshot(job,job.total)] : []);
+    const job = lookup(params.sessionId,owner);
+
+    if (params.action === "write") await sendInput(job,params.input,signal);
+    else if (params.action === "stop") await terminate(job,"stopped");
+    else if (job.status === "running" && (params.cursor ?? 0) === job.total && params.waitMs) await waitForChange(job,params.waitMs,signal);
+
+    // Polls, writes and stops can cross a session shutdown while awaiting I/O.
+    // Do not return a result owned by the session that just closed.
+    // Polls, writes and stops can cross a session shutdown while awaiting I/O.
+    // Do not return a result owned by the session that just closed.
+    if (expectedGeneration !== generation) throw new Error("background terminal session changed; start a new call");
+
+    return snapshot(job,params.cursor);
+  }
+
+  function shutdown() {
+    if (closing) return closing;
+    closed = true;
+    generation++;
+    const retiring = [...jobs.values()];
+    closing = Promise.allSettled(retiring.map(job=>terminate(job,"stopped"))).then(results=>{
+      for (const job of retiring) if (job.cleaned) jobs.delete(job.id);
+      const failure = results.find(result=>result.status === "rejected");
+
+      if (failure) throw failure.reason;
+    }).finally(()=>{closing=undefined;});
+
+    return closing;
+  }
+
+  function reopen() {
+    if (closing || [...jobs.values()].some(job=>!job.cleaned)) throw new Error("background terminal session cleanup is incomplete");
+    closed = false;
+  }
+
+  return {start, control, validateStart, validateControl, shutdown, reopen, getGeneration:()=>generation};
+}