@arnilo/prism-tools 0.0.0-stage → 0.13.0

package/coding/src/agent/repository/types.ts

@@ -0,0 +1,243 @@
+/** Repository types family (0.2.5 plan 025 Task 1 split).
+ * Moved verbatim from repository.ts; public surface unchanged behind the barrel. */
+import {
+  DEFAULT_BINARY_SNIFF_BYTES,
+  DEFAULT_MAX_REPO_CONCURRENCY,
+  DEFAULT_MAX_REPO_DEPTH,
+  DEFAULT_MAX_REPO_ENTRIES,
+  DEFAULT_MAX_REPO_FILES,
+  DEFAULT_MAX_REPO_RESULTS,
+  DEFAULT_MAX_SEARCH_CONTEXT_LINES,
+  DEFAULT_MAX_SEARCH_FILE_BYTES,
+  DEFAULT_MAX_SEARCH_LINE_BYTES,
+  DEFAULT_MAX_SEARCH_MATCHES,
+  DEFAULT_MAX_SEARCH_PATTERN_BYTES,
+  DEFAULT_MAX_SEARCH_SCAN_BYTES,
+  DEFAULT_MAX_SEARCH_TIME_MS,
+  HARD_MAX_REPO_CONCURRENCY,
+  HARD_MAX_REPO_DEPTH,
+  HARD_MAX_REPO_ENTRIES,
+  HARD_MAX_REPO_FILES,
+  HARD_MAX_REPO_RESULTS,
+  HARD_MAX_SEARCH_CONTEXT_LINES,
+  HARD_MAX_SEARCH_FILE_BYTES,
+  HARD_MAX_SEARCH_LINE_BYTES,
+  HARD_MAX_SEARCH_MATCHES,
+  HARD_MAX_SEARCH_PATTERN_BYTES,
+  HARD_MAX_SEARCH_SCAN_BYTES,
+  HARD_MAX_SEARCH_TIME_MS,
+  validateCodingLimit,
+  validateCodingLimitAllowZero,
+} from "../limits.js";
+
+export type RepoEntryKind = "file" | "directory" | "symlink" | "other";
+
+export interface RepoListEntry {
+  readonly path: string;
+  readonly kind: RepoEntryKind;
+  readonly size?: number;
+}
+
+export interface RepositoryListResult {
+  readonly entries: readonly RepoListEntry[];
+  readonly truncated: boolean;
+  readonly truncatedBy: "results" | "entries" | "files" | "depth" | "time" | "abort" | null;
+  readonly scannedEntries: number;
+  readonly scannedFiles: number;
+  readonly nextOffset?: number;
+  readonly offset: number;
+}
+
+export interface RepositoryGlobResult {
+  readonly paths: readonly string[];
+  readonly truncated: boolean;
+  readonly truncatedBy: RepositoryListResult["truncatedBy"];
+  readonly scannedEntries: number;
+  readonly scannedFiles: number;
+  readonly nextOffset?: number;
+  readonly offset: number;
+}
+
+export type RepoSearchMode = "literal" | "indexed_literal" | "semantic";
+
+export type RepoSearchOutputMode = "content" | "files_with_matches" | "count";
+
+export interface RepositorySearchMatch {
+  readonly path: string;
+  readonly line: number;
+  readonly column: number;
+  readonly text: string;
+  readonly before: readonly string[];
+  readonly after: readonly string[];
+  /** Host index relevance in [0,1]; present only for indexed_literal/semantic results. */
+  readonly score?: number;
+}
+
+export interface RepositorySearchResult {
+  readonly matches: readonly RepositorySearchMatch[];
+  readonly truncated: boolean;
+  readonly truncatedBy: "matches" | "scan" | "file" | "entries" | "files" | "depth" | "time" | "abort" | "pattern" | "index" | null;
+  readonly scannedBytes: number;
+  readonly scannedFiles: number;
+  readonly scannedEntries: number;
+  readonly filesSkippedBinary: number;
+  readonly filesSkippedOversize: number;
+  /** Present only for indexed_literal/semantic queries: provenance and freshness. */
+  readonly indexed?: {
+    readonly mode: "indexed_literal" | "semantic";
+    readonly state: "empty" | "building" | "ready" | "stale" | "failed";
+    readonly sourceRevision?: string;
+    readonly updatedAt?: number;
+  };
+  /** True when match content came from a host index; index text is untrusted. */
+  readonly untrusted_index?: boolean;
+}
+
+export interface ResolvedRepositoryLimits {
+  readonly maxDepth: number;
+  readonly maxEntries: number;
+  readonly maxFiles: number;
+  readonly maxResults: number;
+  readonly maxConcurrency: number;
+  readonly maxScanBytes: number;
+  readonly maxFileBytes: number;
+  readonly maxMatches: number;
+  readonly maxPatternBytes: number;
+  readonly maxLineBytes: number;
+  readonly maxContextLines: number;
+  readonly maxTimeMs: number;
+  readonly binarySniffBytes: number;
+  readonly exclude: readonly string[];
+}
+
+export interface RepositoryLimitOptions {
+  readonly maxDepth?: number;
+  readonly maxEntries?: number;
+  readonly maxFiles?: number;
+  readonly maxResults?: number;
+  readonly maxConcurrency?: number;
+  readonly maxScanBytes?: number;
+  readonly maxFileBytes?: number;
+  readonly maxMatches?: number;
+  readonly maxPatternBytes?: number;
+  readonly maxLineBytes?: number;
+  readonly maxContextLines?: number;
+  readonly maxTimeMs?: number;
+  /** Basename denylist skipped during descent (default `.git`, `node_modules`, `dist`). */
+  readonly exclude?: readonly string[];
+}
+
+export interface RepositoryListRequest {
+  readonly root: string;
+  readonly path?: string;
+  readonly includeHidden?: boolean;
+  readonly exclude?: readonly string[];
+  readonly maxDepth?: number;
+  readonly maxResults?: number;
+  readonly offset?: number;
+  readonly signal?: AbortSignal;
+  readonly deadlineMs?: number;
+}
+
+export interface RepositorySearchRequest {
+  readonly root: string;
+  readonly query: string;
+  readonly path?: string;
+  readonly mode?: RepoSearchMode;
+  readonly outputMode?: RepoSearchOutputMode;
+  readonly caseSensitive?: boolean;
+  readonly includeHidden?: boolean;
+  readonly exclude?: readonly string[];
+  readonly context?: number;
+  readonly maxMatches?: number;
+  /** Only search files whose workspace-relative path matches this glob (`*`, `?`, `**`). */
+  readonly glob?: string;
+  /**
+   * Injected line matcher: `(fileText, context) => matches`. The `grep` tool passes a
+   * worker-backed regex matcher; a backend that does not honor it cannot run regex.
+   */
+  readonly matcher?: RepositoryFileMatcher;
+  readonly signal?: AbortSignal;
+  readonly deadlineMs?: number;
+}
+
+/** One matching line of one file, with its context window. */
+export interface RepositoryLineMatch {
+  /** 1-based line number. */
+  readonly line: number;
+  /** 1-based column of the first match on the line. */
+  readonly column: number;
+  readonly text: string;
+  readonly before: readonly string[];
+  readonly after: readonly string[];
+}
+
+/** One file's text → its line matches. Sync (literal) or async (worker-backed regex). */
+export type RepositoryFileMatcher = (
+  text: string,
+  context: number,
+) => Promise<readonly RepositoryLineMatch[]> | readonly RepositoryLineMatch[];
+
+export interface RepositoryGlobRequest {
+  readonly root: string;
+  readonly pattern: string;
+  readonly path?: string;
+  readonly includeHidden?: boolean;
+  readonly exclude?: readonly string[];
+  readonly maxDepth?: number;
+  readonly maxResults?: number;
+  readonly offset?: number;
+  /** Bounded `{a,b}` expansion (default true; set `false` to reject braces; bounds in glob-match.ts). */
+  readonly braceExpansion?: boolean;
+  readonly signal?: AbortSignal;
+  readonly deadlineMs?: number;
+}
+
+export interface RepositoryOperations {
+  list(request: RepositoryListRequest): Promise<RepositoryListResult>;
+  search(request: RepositorySearchRequest): Promise<RepositorySearchResult>;
+  glob(request: RepositoryGlobRequest): Promise<RepositoryGlobResult>;
+}
+
+export const DEFAULT_REPO_EXCLUDE = Object.freeze([".git", "node_modules", "dist"]);
+
+export class RepositoryError extends Error {
+  readonly code = "ERR_PRISM_REPOSITORY";
+  constructor(message: string) {
+    super(message);
+    this.name = "RepositoryError";
+  }
+}
+
+export function resolveRepositoryLimits(options?: RepositoryLimitOptions): ResolvedRepositoryLimits {
+  return {
+    maxDepth: validateCodingLimit("maxDepth", options?.maxDepth ?? DEFAULT_MAX_REPO_DEPTH, HARD_MAX_REPO_DEPTH),
+    maxEntries: validateCodingLimit("maxEntries", options?.maxEntries ?? DEFAULT_MAX_REPO_ENTRIES, HARD_MAX_REPO_ENTRIES),
+    maxFiles: validateCodingLimit("maxFiles", options?.maxFiles ?? DEFAULT_MAX_REPO_FILES, HARD_MAX_REPO_FILES),
+    maxResults: validateCodingLimit("maxResults", options?.maxResults ?? DEFAULT_MAX_REPO_RESULTS, HARD_MAX_REPO_RESULTS),
+    maxConcurrency: validateCodingLimit(
+      "maxConcurrency",
+      options?.maxConcurrency ?? DEFAULT_MAX_REPO_CONCURRENCY,
+      HARD_MAX_REPO_CONCURRENCY,
+    ),
+    maxScanBytes: validateCodingLimit("maxScanBytes", options?.maxScanBytes ?? DEFAULT_MAX_SEARCH_SCAN_BYTES, HARD_MAX_SEARCH_SCAN_BYTES),
+    maxFileBytes: validateCodingLimit("maxFileBytes", options?.maxFileBytes ?? DEFAULT_MAX_SEARCH_FILE_BYTES, HARD_MAX_SEARCH_FILE_BYTES),
+    maxMatches: validateCodingLimit("maxMatches", options?.maxMatches ?? DEFAULT_MAX_SEARCH_MATCHES, HARD_MAX_SEARCH_MATCHES),
+    maxPatternBytes: validateCodingLimit(
+      "maxPatternBytes",
+      options?.maxPatternBytes ?? DEFAULT_MAX_SEARCH_PATTERN_BYTES,
+      HARD_MAX_SEARCH_PATTERN_BYTES,
+    ),
+    maxLineBytes: validateCodingLimit("maxLineBytes", options?.maxLineBytes ?? DEFAULT_MAX_SEARCH_LINE_BYTES, HARD_MAX_SEARCH_LINE_BYTES),
+    maxContextLines: validateCodingLimitAllowZero(
+      "maxContextLines",
+      options?.maxContextLines ?? DEFAULT_MAX_SEARCH_CONTEXT_LINES,
+      HARD_MAX_SEARCH_CONTEXT_LINES,
+    ),
+    maxTimeMs: validateCodingLimit("maxTimeMs", options?.maxTimeMs ?? DEFAULT_MAX_SEARCH_TIME_MS, HARD_MAX_SEARCH_TIME_MS),
+    binarySniffBytes: DEFAULT_BINARY_SNIFF_BYTES,
+    exclude: Object.freeze([...(options?.exclude ?? DEFAULT_REPO_EXCLUDE)]),
+  };
+}
+
+/** Normalize a workspace-relative path to stable forward-slash form. */

package/coding/src/agent/repository/walk.ts

@@ -0,0 +1,126 @@
+/** Repository walk family (0.2.5 plan 025 Task 1 split).
+ * Moved verbatim from repository.ts; public surface unchanged behind the barrel. */
+import type { Dir, Dirent } from "node:fs";
+import { lstat, opendir } from "node:fs/promises";
+import { join } from "node:path";
+import { assertDeadline, assertNotAborted, isPathInsideRoot, kindFromDirent, shouldSkipName, toRepoRelative } from "./path.js";
+import type { RepoListEntry } from "./types.js";
+import { RepositoryError } from "./types.js";
+
+export interface RepositoryWalkLimits {
+  maxDepth: number;
+  maxEntries: number;
+  maxFiles: number;
+  exclude: ReadonlySet<string>;
+  includeHidden: boolean;
+  signal?: AbortSignal;
+  deadlineAt?: number;
+}
+
+export type RepositoryWalkEvent =
+  | { type: "entry"; entry: RepoListEntry; absolutePath: string; depth: number }
+  | { type: "limit"; truncatedBy: "entries" | "files" | "depth" };
+
+/** Injectable enumerator for list/search/glob. Default is the native opendir walker. */
+export type RepositoryWalk = (rootReal: string, startAbsolute: string, limits: RepositoryWalkLimits) => AsyncGenerator<RepositoryWalkEvent>;
+
+export async function* walkRepository(
+  rootReal: string,
+  startAbsolute: string,
+  limits: RepositoryWalkLimits,
+): AsyncGenerator<RepositoryWalkEvent> {
+  const queue: Array<{ absolute: string; relative: string; depth: number }> = [
+    {
+      absolute: startAbsolute,
+      relative: toRepoRelative(rootReal, startAbsolute),
+      depth: 0,
+    },
+  ];
+  let scannedEntries = 0;
+  let scannedFiles = 0;
+
+  while (queue.length > 0) {
+    assertNotAborted(limits.signal);
+    assertDeadline(limits.deadlineAt);
+    const current = queue.shift()!;
+    if (current.depth > limits.maxDepth) {
+      yield { type: "limit", truncatedBy: "depth" };
+      return;
+    }
+
+    let dir: Dir;
+    try {
+      dir = await opendir(current.absolute);
+    } catch (error) {
+      if (current.relative === "." || current.depth === 0) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new RepositoryError(`cannot open directory: ${message}`);
+      }
+      continue;
+    }
+
+    const names: Dirent[] = [];
+    try {
+      for await (const dirent of dir) {
+        assertNotAborted(limits.signal);
+        assertDeadline(limits.deadlineAt);
+        names.push(dirent);
+      }
+    } finally {
+      await dir.close().catch(() => undefined);
+    }
+
+    names.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+    for (const dirent of names) {
+      assertNotAborted(limits.signal);
+      assertDeadline(limits.deadlineAt);
+      if (shouldSkipName(dirent.name, limits.includeHidden, limits.exclude)) continue;
+
+      if (scannedEntries >= limits.maxEntries) {
+        yield { type: "limit", truncatedBy: "entries" };
+        return;
+      }
+      scannedEntries++;
+
+      const absolutePath = join(current.absolute, dirent.name);
+      if (!isPathInsideRoot(rootReal, absolutePath)) continue;
+
+      let kind = kindFromDirent(dirent);
+      let size: number | undefined;
+
+      // Re-check with lstat so we never follow symlinks for type/size.
+      try {
+        const st = await lstat(absolutePath);
+        if (st.isSymbolicLink()) kind = "symlink";
+        else if (st.isDirectory()) kind = "directory";
+        else if (st.isFile()) kind = "file";
+        else kind = "other";
+        if (kind === "file") size = st.size;
+      } catch {
+        continue;
+      }
+
+      if (kind === "file") {
+        if (scannedFiles >= limits.maxFiles) {
+          yield { type: "limit", truncatedBy: "files" };
+          return;
+        }
+        scannedFiles++;
+      }
+
+      const relativePath = current.relative === "." ? dirent.name : `${current.relative}/${dirent.name}`;
+      const entry: RepoListEntry = size === undefined ? { path: relativePath, kind } : { path: relativePath, kind, size };
+      yield { type: "entry", entry, absolutePath, depth: current.depth };
+
+      if (kind === "directory") {
+        const nextDepth = current.depth + 1;
+        if (nextDepth > limits.maxDepth) {
+          yield { type: "limit", truncatedBy: "depth" };
+          return;
+        }
+        queue.push({ absolute: absolutePath, relative: relativePath, depth: nextDepth });
+      }
+    }
+  }
+}

package/coding/src/agent/repository.ts

@@ -0,0 +1,12 @@
+/** Repository barrel (0.2.5 plan 025 Task 1 god-module split): re-exports the public
+ * repository surface from cohesive family modules so the import surface of
+ * `./repository.js` is unchanged (0.1.4 barrel precedent). */
+
+export * from "./repository/glob.js";
+export * from "./repository/indexed-search.js";
+export * from "./repository/list.js";
+export * from "./repository/operations.js";
+export * from "./repository/path.js";
+export * from "./repository/search.js";
+export * from "./repository/types.js";
+export * from "./repository/walk.js";

package/coding/src/agent/shell-background.ts

@@ -0,0 +1,264 @@
+/**
+ * Background processes for the coding tools (plan 189 Task 9).
+ *
+ * One lazy runtime over the process-session library: nothing is constructed until the first
+ * `shell({ background: true })` call, so a session that never backgrounds a command pays nothing.
+ * Every process is owned by the calling session (`owner: sessionId`), which gives the invariants
+ * for free: `get(id, sessionId)` refuses another session's id, `cancelOwned(sessionId)` kills
+ * exactly that session's processes without touching another's, and the listener in `src/index.ts`
+ * makes `session.closed` — also emitted for every open session by `agent.dispose()` — the kill
+ * switch.
+ *
+ * The process-session registry is the single spawner: this module never spawns a child itself.
+ */
+
+import type { ExecutionPolicy } from "./execution-policy.js";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, HARD_MAX_LINES, validateCodingLimit } from "./limits.js";
+import { createProcessSessions } from "./process/sessions.js";
+import type { ProcessSandboxBackend, ProcessSession, ProcessSessions } from "./process/types.js";
+import { ProcessSessionError } from "./process/types.js";
+import type { ShellConfig } from "./shell.js";
+import { formatSize, truncateTail } from "./truncate.js";
+
+/** Default live background processes per session. */
+export const DEFAULT_MAX_BACKGROUND_PROCESSES = 4;
+/** Hard cap on live background processes per session. */
+export const HARD_MAX_BACKGROUND_PROCESSES = 16;
+/** How long `shell({ background: true })` waits for first output before returning. */
+export const BACKGROUND_FIRST_OUTPUT_MS = 1000;
+/** Longest `shell_output({ waitSeconds })` may wait. */
+export const HARD_MAX_BACKGROUND_WAIT_SECONDS = 60;
+
+export interface BackgroundProcessOptions {
+  /** Per-session live process cap (default 4, hard 16). */
+  readonly maxProcesses?: number;
+  /** Per-process wall lifetime (default: the process-session default, 4 h). */
+  readonly maxLifetimeMs?: number;
+  /** Caps for the output `shell_output` returns (default 2000 lines / 50KB tail). */
+  readonly maxLines?: number;
+  readonly maxBytes?: number;
+  /** Resolved shell (`<shell> -c <command>`), so background commands run exactly like foreground ones. */
+  readonly shell?: ShellConfig;
+  /** The same adapter the shell uses; absent means native spawn on the host. */
+  readonly sandbox?: ProcessSandboxBackend;
+  readonly policy?: ExecutionPolicy;
+}
+
+export interface BackgroundStartInput {
+  /** The command as the shell tool would run it (after `commandPrefix`, `spawnHook`, policy rewrite). */
+  readonly command: string;
+  readonly cwd: string;
+  readonly env: NodeJS.ProcessEnv;
+  readonly sessionId: string;
+}
+
+export interface BackgroundStarted {
+  readonly id: string;
+  /** Output that arrived within {@link BACKGROUND_FIRST_OUTPUT_MS}, formatted with the shell's caps. */
+  readonly output: string;
+  readonly running: boolean;
+  readonly exitCode: number | null;
+}
+
+export interface BackgroundReadInput {
+  readonly id: string;
+  readonly sessionId: string;
+  readonly waitSeconds: number;
+  readonly kill: boolean;
+}
+
+export interface BackgroundRead {
+  readonly id: string;
+  /** Output produced since the previous `shell_output` call for this id. */
+  readonly output: string;
+  readonly running: boolean;
+  readonly exitCode: number | null;
+  readonly state: string;
+}
+
+export interface BackgroundProcesses {
+  readonly maxProcesses: number;
+  start(input: BackgroundStartInput): Promise<BackgroundStarted>;
+  read(input: BackgroundReadInput): Promise<BackgroundRead>;
+  /** Kill every process this session owns. Idempotent; also runs on `session.closed`. */
+  killSession(sessionId: string): Promise<void>;
+  /** Live (starting/running) processes owned by `sessionId`. */
+  liveCount(sessionId: string): number;
+}
+
+interface Tracked {
+  readonly handle: ProcessSession;
+  readonly cwd: string;
+  cursor: number;
+}
+
+export function createBackgroundProcesses(options: BackgroundProcessOptions = {}): BackgroundProcesses {
+  const maxProcesses = validateCodingLimit(
+    "maxProcesses",
+    options.maxProcesses ?? DEFAULT_MAX_BACKGROUND_PROCESSES,
+    HARD_MAX_BACKGROUND_PROCESSES,
+  );
+  const maxLines = validateCodingLimit("maxLines", options.maxLines ?? DEFAULT_MAX_LINES, HARD_MAX_LINES);
+  const shell: ShellConfig = options.shell ?? { shell: "/bin/sh", args: ["-c"] };
+  const tracked = new Map<string, Tracked>();
+  // One registry per workspace root: the session library contains every cwd under its own root,
+  // and a worktree-bound session runs in a directory outside the package root.
+  const registries = new Map<string, ProcessSessions>();
+
+  const sessions = (cwd: string): ProcessSessions => {
+    const existing = registries.get(cwd);
+    if (existing !== undefined) return existing;
+    const created = createProcessSessions({
+      cwd,
+      ...(options.sandbox !== undefined ? { sandbox: options.sandbox } : {}),
+      ...(options.policy !== undefined ? { policy: options.policy } : {}),
+      // The per-session cap below is the real bound; this only bounds the total.
+      limits: {
+        maxSessions: HARD_MAX_BACKGROUND_PROCESSES * 2,
+        ...(options.maxLifetimeMs !== undefined ? { maxLifetimeMs: options.maxLifetimeMs } : {}),
+      },
+    });
+    registries.set(cwd, created);
+    return created;
+  };
+
+  /** The registries this session actually owns processes in. */
+  const registriesOf = (sessionId: string): ProcessSessions[] => [...new Set(owned(sessionId).map((entry) => sessions(entry.cwd)))];
+
+  const owned = (sessionId: string): Tracked[] => [...tracked.values()].filter((e) => e.handle.owner === sessionId);
+  const alive = (handle: ProcessSession): boolean => handle.state === "starting" || handle.state === "running";
+  const live = (sessionId: string): Tracked[] => owned(sessionId).filter((e) => alive(e.handle));
+
+  const exitOf = async (handle: ProcessSession): Promise<number | null> => {
+    if (alive(handle)) return null;
+    // Resolves immediately for a finished record; never a fabricated code for a live one.
+    return (await handle.wait()).exitCode;
+  };
+
+  const format = (data: string): string => {
+    if (data.length === 0) return "";
+    const truncation = truncateTail(data, { maxLines, maxBytes: options.maxBytes ?? DEFAULT_MAX_BYTES });
+    return truncation.truncated
+      ? `${truncation.content}\n\n[showing the last ${formatSize(truncation.outputBytes)} of ${truncation.totalLines} new line(s)]`
+      : truncation.content;
+  };
+
+  /** Keep at most 32 finished records per session so a chatty session cannot grow the map. */
+  const prune = (sessionId: string): void => {
+    const finished = owned(sessionId).filter((e) => !alive(e.handle));
+    for (const entry of finished.slice(0, Math.max(0, finished.length - 32))) tracked.delete(entry.handle.id);
+  };
+
+  /** One chunk from the cursor; the chunk cap keeps each read bounded. */
+  const readOnce = async (entry: Tracked): Promise<string> => {
+    const chunk = await entry.handle.output({ cursor: entry.cursor });
+    entry.cursor = chunk.cursor;
+    return chunk.data;
+  };
+
+  /**
+   * Everything that accumulated since the last call, in whole chunks, so one `shell_output` sees a
+   * burst instead of only its first chunk. Bounded at twice the format cap: anything past that is
+   * truncated away by `format` anyway.
+   */
+  const drainLimitBytes = (options.maxBytes ?? DEFAULT_MAX_BYTES) * 2;
+  const readAvailable = async (entry: Tracked): Promise<string> => {
+    let data = "";
+    while (data.length < drainLimitBytes) {
+      const chunk = await readOnce(entry);
+      data += chunk;
+      if (chunk.length === 0) break;
+    }
+    return data;
+  };
+
+  /**
+   * Waits for the next publication (`ProcessSession.onOutput`: a chunk or the terminal transition)
+   * or `ms`, never polls. Returns what accumulated in the meantime.
+   */
+  const waitFor = async (entry: Tracked, ms: number): Promise<string> => {
+    let stopped = false;
+    let timer: NodeJS.Timeout | undefined;
+    let unsubscribe = (): void => undefined;
+    const stop = (): void => {
+      if (stopped) return;
+      stopped = true;
+      if (timer !== undefined) clearTimeout(timer);
+      unsubscribe();
+    };
+    const signalled = new Promise<void>((resolve) => {
+      // Subscribe before the first read, so a chunk published in between cannot be missed.
+      unsubscribe = entry.handle.onOutput(() => {
+        stop();
+        resolve();
+      });
+      timer = setTimeout(() => {
+        stop();
+        resolve();
+      }, ms);
+    });
+    try {
+      const immediate = await readAvailable(entry);
+      if (immediate.length > 0 || !alive(entry.handle)) return immediate;
+      await signalled;
+      return await readAvailable(entry);
+    } finally {
+      stop();
+    }
+  };
+
+  return {
+    maxProcesses,
+
+    async start(input) {
+      const running = live(input.sessionId).length;
+      if (running >= maxProcesses) {
+        throw new ProcessSessionError(
+          "ERR_PRISM_PROCESS_LIMIT",
+          `session already has ${running} background process(es) (max ${maxProcesses}); call shell_output({ id, kill: true }) first`,
+        );
+      }
+      const env: Record<string, string> = {};
+      for (const [name, value] of Object.entries(input.env)) if (value !== undefined) env[name] = value;
+      const handle = await sessions(input.cwd).start({
+        command: shell.shell,
+        args: [...shell.args, input.command],
+        cwd: input.cwd,
+        env,
+        owner: input.sessionId,
+      });
+      const entry: Tracked = { handle, cwd: input.cwd, cursor: 0 };
+      tracked.set(handle.id, entry);
+      prune(input.sessionId);
+      const output = format(await waitFor(entry, BACKGROUND_FIRST_OUTPUT_MS));
+      return { id: handle.id, output, running: alive(handle), exitCode: await exitOf(handle) };
+    },
+
+    async read(input) {
+      const entry = tracked.get(input.id);
+      if (entry === undefined) {
+        throw new ProcessSessionError("ERR_PRISM_PROCESS_STATE", `unknown process: ${input.id}`);
+      }
+      // Throws ERR_PRISM_PROCESS_OWNERSHIP for another session's id; never leaks its output.
+      const handle = sessions(entry.cwd).get(input.id, input.sessionId);
+      if (input.kill && alive(handle)) await handle.kill();
+      const output = format(
+        input.waitSeconds > 0
+          ? await waitFor(entry, Math.min(input.waitSeconds, HARD_MAX_BACKGROUND_WAIT_SECONDS) * 1000)
+          : await readAvailable(entry),
+      );
+      return { id: handle.id, output, running: alive(handle), exitCode: await exitOf(handle), state: handle.state };
+    },
+
+    async killSession(sessionId) {
+      const entries = owned(sessionId);
+      if (entries.length === 0) return;
+      for (const registry of registriesOf(sessionId)) await registry.cancelOwned(sessionId);
+      for (const [id, entry] of tracked) if (entry.handle.owner === sessionId) tracked.delete(id);
+    },
+
+    liveCount(sessionId) {
+      return live(sessionId).length;
+    },
+  };
+}