@procedures/shell 0.3.0 → 0.5.0

package/dist/command/index.d.ts

@@ -11,7 +11,7 @@
  */
 export { runCommand, type CommandOptions, type CommandResult } from "./run.js";
 export { streamCommand, type StreamCommandOptions, type CommandStreamItem } from "./stream.js";
-export { ProcessRegistry, processes, type ManagedProcessInfo, type StartProcessOptions, type StopResult, } from "./processes.js";
+export { ProcessRegistry, processes, FOLLOW_BUFFER_BYTES, type ManagedProcessInfo, type StartProcessOptions, type StopResult, type ProcessOutputChunk, type ProcessOutputListener, type ProcessFollowItem, type FollowOptions, } from "./processes.js";
 export { killTree } from "./tree-kill.js";
 export type { SpawnOptions } from "./spawn.js";
 export { DEFAULT_MAX_OUTPUT_BYTES } from "./output.js";

package/dist/command/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/command/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC/F,OAAO,EACL,eAAe,EACf,SAAS,EACT,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,UAAU,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/command/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC/F,OAAO,EACL,eAAe,EACf,SAAS,EACT,mBAAmB,EACnB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC"}

package/dist/command/index.js

@@ -11,7 +11,7 @@
  */
 export { runCommand } from "./run.js";
 export { streamCommand } from "./stream.js";
-export { ProcessRegistry, processes, } from "./processes.js";
+export { ProcessRegistry, processes, FOLLOW_BUFFER_BYTES, } from "./processes.js";
 export { killTree } from "./tree-kill.js";
 export { DEFAULT_MAX_OUTPUT_BYTES } from "./output.js";
 //# sourceMappingURL=index.js.map

package/dist/command/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/command/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAA2C,MAAM,UAAU,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAqD,MAAM,aAAa,CAAC;AAC/F,OAAO,EACL,eAAe,EACf,SAAS,GAIV,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/command/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAA2C,MAAM,UAAU,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAqD,MAAM,aAAa,CAAC;AAC/F,OAAO,EACL,eAAe,EACf,SAAS,EACT,mBAAmB,GAQpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC"}

package/dist/command/processes.d.ts

@@ -7,6 +7,7 @@
  * - a record (id, pid, status, exit code), which `list` and `get` give;
  * - a `stop` that kills the whole process tree;
  * - the end of its output (the last 64 KiB), which also keeps its pipes from filling;
+ * - the output after a time, for a follower: `subscribe` and `follow`;
  * - an end with the host: the host does not wait for the process, and kills it when it ends.
  *
  * The registry keeps the records of ended processes, up to `keepExited` of them.
@@ -40,6 +41,58 @@ export interface StopResult {
     exitCode?: number;
     signal?: string;
 }
+/** One piece of the output of a process, as `subscribe` gives it. */
+export interface ProcessOutputChunk {
+    /** The stream of the piece. */
+    stream: "stdout" | "stderr";
+    /** The bytes of the piece. A piece can end in a line or in a UTF-8 character. */
+    data: Buffer;
+}
+/** The functions that `subscribe` calls for one subscriber. */
+export interface ProcessOutputListener {
+    /** This function gets each piece of output that the process writes after the subscription. */
+    output?(chunk: ProcessOutputChunk): void;
+    /** This function gets a copy of the record when the process ends. After it, no call comes. */
+    end?(info: ManagedProcessInfo): void;
+}
+/** One item of `follow`. */
+export type ProcessFollowItem = 
+/** The output that the registry kept before the subscription: the first item with `backlog`. */
+{
+    type: "backlog";
+    text: string;
+}
+/** A piece of new output, decoded as UTF-8. A piece can end in the middle of a line. */
+ | {
+    type: "output";
+    stream: "stdout" | "stderr";
+    text: string;
+}
+/** The reader was slow, so the follower dropped the oldest pieces: this many bytes. */
+ | {
+    type: "dropped";
+    bytes: number;
+}
+/** The end of the process: the last item. */
+ | {
+    type: "end";
+    info: ManagedProcessInfo;
+};
+/** The options of `follow`. */
+export interface FollowOptions {
+    /** True: the first item is the output that the registry kept before the subscription. */
+    backlog?: boolean | undefined;
+    /** An abort ends the stream. The process continues. */
+    signal?: AbortSignal | undefined;
+    /**
+     * The most bytes of output that wait for the reader. Above it, the follower drops the oldest
+     * pieces and gives a `dropped` item, because the registry cannot slow the process.
+     * @default 1 MiB
+     */
+    maxBufferedBytes?: number | undefined;
+}
+/** The default of `maxBufferedBytes` of `follow`. */
+export declare const FOLLOW_BUFFER_BYTES: number;
 /** This function removes the ANSI escape sequences from a text. */
 export declare function stripAnsi(text: string): string;
 export declare class ProcessRegistry {
@@ -59,6 +112,22 @@ export declare class ProcessRegistry {
     }): ManagedProcessInfo[];
     /** This function gives the end of the output of a process (stdout and stderr together). */
     output(id: string): string;
+    /**
+     * This function subscribes to the output of a process. `listener.output` gets each piece of
+     * output after this call, with its stream. `listener.end` gets the record at the end of the
+     * process, and then the registry forgets the subscriber. For a process that ended already,
+     * `listener.end` runs at once. The result removes the subscriber. It is undefined when the
+     * registry has no process of this id.
+     */
+    subscribe(id: string, listener: ProcessOutputListener): (() => void) | undefined;
+    /**
+     * This function gives the output of a process as a stream, until the process ends or the
+     * signal aborts. The subscription starts when the reader asks for the first item, and the
+     * end of the stream removes it: an end of the process, an abort, or a reader that stops. With
+     * `backlog`, the first item is the output that the registry kept until then, without a gap.
+     * The last item of an ended process is `end`. An unknown id throws at the first item.
+     */
+    follow(id: string, options?: FollowOptions): AsyncGenerator<ProcessFollowItem, void, undefined>;
     /** This function waits until the process ends, then gives its record. */
     exited(id: string): Promise<ManagedProcessInfo | undefined>;
     /**

package/dist/command/processes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"processes.d.ts","sourceRoot":"","sources":["../../src/command/processes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAA0B,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAEvE,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wFAAwF;IACxF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACvD,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAUD,mEAAmE;AACnE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAWD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,OAAO,CAAK;IAEpB,YAAY,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO,EAEhD;IAED,oFAAoF;IACpF,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,kBAAkB,CA+D5E;IAED,6DAA6D;IAC7D,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAG9C;IAED,+DAA+D;IAC/D,IAAI,CAAC,MAAM,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAO,GAAG,kBAAkB,EAAE,CAOtE;IAED,2FAA2F;IAC3F,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEzB;IAED,yEAAyE;IACnE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAKhE;IAED;;;;;OAKG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA0BhF;IAED;;;OAGG;IACG,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,OAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,CAW9E;IAED,mFAAmF;IAC7E,OAAO,CAAC,MAAM,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAI1E;IAED,kGAAkG;IAClG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAI1B;IAED,qFAAqF;IACrF,IAAI,IAAI,MAAM,CAKb;IAED,OAAO,CAAC,UAAU;YAOJ,UAAU;CAWzB;AAED,uFAAuF;AACvF,eAAO,MAAM,SAAS,EAAE,eAAuC,CAAC"}
+{"version":3,"file":"processes.d.ts","sourceRoot":"","sources":["../../src/command/processes.ts"],"names":[],"mappings":"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"}

package/dist/command/processes.js

@@ -7,13 +7,17 @@
  * - a record (id, pid, status, exit code), which `list` and `get` give;
  * - a `stop` that kills the whole process tree;
  * - the end of its output (the last 64 KiB), which also keeps its pipes from filling;
+ * - the output after a time, for a follower: `subscribe` and `follow`;
  * - an end with the host: the host does not wait for the process, and kills it when it ends.
  *
  * The registry keeps the records of ended processes, up to `keepExited` of them.
  */
+import { StringDecoder } from "node:string_decoder";
 import { killTree } from "./tree-kill.js";
 import { OutputCollector } from "./output.js";
 import { startChild, startError } from "./spawn.js";
+/** The default of `maxBufferedBytes` of `follow`. */
+export const FOLLOW_BUFFER_BYTES = 1024 * 1024;
 /** The end of the output that the registry keeps for each process. */
 const OUTPUT_TAIL_BYTES = 64 * 1024;
 /** How long `stop` waits after the first kill, before it kills again with SIGKILL. */
@@ -24,6 +28,15 @@ const ANSI = /\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g;
 export function stripAnsi(text) {
     return text.replace(ANSI, "");
 }
+/** This function calls a function of a subscriber. An error of a subscriber does not reach the registry. */
+function notify(run) {
+    try {
+        run();
+    }
+    catch (error) {
+        console.error("A subscriber of the process registry failed:", error);
+    }
+}
 export class ProcessRegistry {
     entries = new Map();
     keepExited;
@@ -51,18 +64,19 @@ export class ProcessRegistry {
             info.label = options.label;
         const output = new OutputCollector(OUTPUT_TAIL_BYTES, "tail");
         const watchers = new Set();
+        const listeners = new Set();
         const changed = () => {
             for (const watcher of [...watchers])
                 watcher();
         };
-        child.stdout.on("data", (chunk) => {
-            output.add(chunk);
-            changed();
-        });
-        child.stderr.on("data", (chunk) => {
+        const received = (stream, chunk) => {
             output.add(chunk);
+            for (const listener of [...listeners])
+                notify(() => listener.output?.({ stream, data: chunk }));
             changed();
-        });
+        };
+        child.stdout.on("data", (chunk) => received("stdout", chunk));
+        child.stderr.on("data", (chunk) => received("stderr", chunk));
         const done = new Promise((resolve) => {
             let finished = false;
             const finish = () => {
@@ -72,6 +86,11 @@ export class ProcessRegistry {
                 info.exitedAt = new Date().toISOString();
                 resolve();
                 changed();
+                // The end is the last call to a subscriber: the registry then forgets each subscriber
+                const ending = [...listeners];
+                listeners.clear();
+                for (const listener of ending)
+                    notify(() => listener.end?.({ ...info, args: [...info.args] }));
                 this.reap();
             };
             child.on("error", (error) => {
@@ -95,7 +114,7 @@ export class ProcessRegistry {
         for (const stream of [child.stdout, child.stderr]) {
             stream?.unref?.();
         }
-        this.entries.set(id, { info, child, output, watchers, done });
+        this.entries.set(id, { info, child, output, watchers, listeners, done });
         this.reap();
         return { ...info };
     }
@@ -118,6 +137,109 @@ export class ProcessRegistry {
     output(id) {
         return this.entries.get(id)?.output.text() ?? "";
     }
+    /**
+     * This function subscribes to the output of a process. `listener.output` gets each piece of
+     * output after this call, with its stream. `listener.end` gets the record at the end of the
+     * process, and then the registry forgets the subscriber. For a process that ended already,
+     * `listener.end` runs at once. The result removes the subscriber. It is undefined when the
+     * registry has no process of this id.
+     */
+    subscribe(id, listener) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return undefined;
+        if (entry.info.exitedAt) {
+            notify(() => listener.end?.({ ...entry.info, args: [...entry.info.args] }));
+            return () => undefined;
+        }
+        entry.listeners.add(listener);
+        return () => {
+            entry.listeners.delete(listener);
+        };
+    }
+    /**
+     * This function gives the output of a process as a stream, until the process ends or the
+     * signal aborts. The subscription starts when the reader asks for the first item, and the
+     * end of the stream removes it: an end of the process, an abort, or a reader that stops. With
+     * `backlog`, the first item is the output that the registry kept until then, without a gap.
+     * The last item of an ended process is `end`. An unknown id throws at the first item.
+     */
+    async *follow(id, options = {}) {
+        const limit = Math.max(1, options.maxBufferedBytes ?? FOLLOW_BUFFER_BYTES);
+        const signal = options.signal;
+        const queue = [];
+        let queued = 0;
+        let dropped = 0;
+        let ended;
+        let wake;
+        const wakeUp = () => {
+            const resolve = wake;
+            wake = undefined;
+            resolve?.();
+        };
+        const decoders = { stdout: new StringDecoder("utf8"), stderr: new StringDecoder("utf8") };
+        const add = (stream, text, bytes) => {
+            if (text === "")
+                return;
+            queue.push({ item: { type: "output", stream, text }, bytes });
+            queued += bytes;
+            // The registry cannot slow the process: above the limit, the oldest pieces go
+            while (queued > limit && queue.length > 1) {
+                const oldest = queue.shift();
+                queued -= oldest.bytes;
+                dropped += oldest.bytes;
+            }
+        };
+        if (signal?.aborted)
+            return;
+        const backlog = options.backlog ? this.output(id) : "";
+        const unsubscribe = this.subscribe(id, {
+            output: ({ stream, data }) => {
+                add(stream, decoders[stream].write(data), data.length);
+                wakeUp();
+            },
+            end: (info) => {
+                for (const stream of ["stdout", "stderr"]) {
+                    const rest = decoders[stream].end();
+                    add(stream, rest, Buffer.byteLength(rest));
+                }
+                ended = info;
+                wakeUp();
+            },
+        });
+        if (!unsubscribe)
+            throw new Error(`No process ${id}`);
+        signal?.addEventListener("abort", wakeUp, { once: true });
+        try {
+            if (options.backlog)
+                yield { type: "backlog", text: backlog };
+            for (;;) {
+                if (signal?.aborted)
+                    return;
+                if (dropped > 0) {
+                    const bytes = dropped;
+                    dropped = 0;
+                    yield { type: "dropped", bytes };
+                    continue;
+                }
+                const next = queue.shift();
+                if (next) {
+                    queued -= next.bytes;
+                    yield next.item;
+                    continue;
+                }
+                if (ended) {
+                    yield { type: "end", info: ended };
+                    return;
+                }
+                await new Promise((resolve) => (wake = resolve));
+            }
+        }
+        finally {
+            unsubscribe();
+            signal?.removeEventListener("abort", wakeUp);
+        }
+    }
     /** This function waits until the process ends, then gives its record. */
     async exited(id) {
         const entry = this.entries.get(id);

package/dist/command/processes.js.map

@@ -1 +1 @@
-{"version":3,"file":"processes.js","sourceRoot":"","sources":["../../src/command/processes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"processes.js","sourceRoot":"","sources":["../../src/command/processes.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/shell",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Safe command execution for TypeScript: shell.run with argv and no shell, shell.stream line streaming with backpressure, process-tree kill, timeouts and output caps.",
   "keywords": [
     "shell",
@@ -68,7 +68,7 @@
     "vitest": "^5.0.3"
   },
   "dependencies": {
-    "@procedures/client": "0.3.0",
+    "@procedures/client": "0.5.0",
     "zod": "^4.6.5"
   },
   "client": {

package/src/command/index.ts

@@ -15,9 +15,14 @@ export { streamCommand, type StreamCommandOptions, type CommandStreamItem } from
 export {
   ProcessRegistry,
   processes,
+  FOLLOW_BUFFER_BYTES,
   type ManagedProcessInfo,
   type StartProcessOptions,
   type StopResult,
+  type ProcessOutputChunk,
+  type ProcessOutputListener,
+  type ProcessFollowItem,
+  type FollowOptions,
 } from "./processes.js";
 export { killTree } from "./tree-kill.js";
 export type { SpawnOptions } from "./spawn.js";

package/src/command/processes.ts

@@ -7,12 +7,14 @@
  * - a record (id, pid, status, exit code), which `list` and `get` give;
  * - a `stop` that kills the whole process tree;
  * - the end of its output (the last 64 KiB), which also keeps its pipes from filling;
+ * - the output after a time, for a follower: `subscribe` and `follow`;
  * - an end with the host: the host does not wait for the process, and kills it when it ends.
  *
  * The registry keeps the records of ended processes, up to `keepExited` of them.
  */
 
 import type { ChildProcess } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
 import { killTree } from "./tree-kill.js";
 import { OutputCollector } from "./output.js";
 import { startChild, startError, type SpawnOptions } from "./spawn.js";
@@ -48,6 +50,50 @@ export interface StopResult {
   signal?: string;
 }
 
+/** One piece of the output of a process, as `subscribe` gives it. */
+export interface ProcessOutputChunk {
+  /** The stream of the piece. */
+  stream: "stdout" | "stderr";
+  /** The bytes of the piece. A piece can end in a line or in a UTF-8 character. */
+  data: Buffer;
+}
+
+/** The functions that `subscribe` calls for one subscriber. */
+export interface ProcessOutputListener {
+  /** This function gets each piece of output that the process writes after the subscription. */
+  output?(chunk: ProcessOutputChunk): void;
+  /** This function gets a copy of the record when the process ends. After it, no call comes. */
+  end?(info: ManagedProcessInfo): void;
+}
+
+/** One item of `follow`. */
+export type ProcessFollowItem =
+  /** The output that the registry kept before the subscription: the first item with `backlog`. */
+  | { type: "backlog"; text: string }
+  /** A piece of new output, decoded as UTF-8. A piece can end in the middle of a line. */
+  | { type: "output"; stream: "stdout" | "stderr"; text: string }
+  /** The reader was slow, so the follower dropped the oldest pieces: this many bytes. */
+  | { type: "dropped"; bytes: number }
+  /** The end of the process: the last item. */
+  | { type: "end"; info: ManagedProcessInfo };
+
+/** The options of `follow`. */
+export interface FollowOptions {
+  /** True: the first item is the output that the registry kept before the subscription. */
+  backlog?: boolean | undefined;
+  /** An abort ends the stream. The process continues. */
+  signal?: AbortSignal | undefined;
+  /**
+   * The most bytes of output that wait for the reader. Above it, the follower drops the oldest
+   * pieces and gives a `dropped` item, because the registry cannot slow the process.
+   * @default 1 MiB
+   */
+  maxBufferedBytes?: number | undefined;
+}
+
+/** The default of `maxBufferedBytes` of `follow`. */
+export const FOLLOW_BUFFER_BYTES: number = 1024 * 1024;
+
 /** The end of the output that the registry keeps for each process. */
 const OUTPUT_TAIL_BYTES = 64 * 1024;
 /** How long `stop` waits after the first kill, before it kills again with SIGKILL. */
@@ -67,9 +113,20 @@ interface Entry {
   output: OutputCollector;
   /** Called after each output chunk and at the end. */
   watchers: Set<() => void>;
+  /** The subscribers of `subscribe`. The end of the process removes them. */
+  listeners: Set<ProcessOutputListener>;
   done: Promise<void>;
 }
 
+/** This function calls a function of a subscriber. An error of a subscriber does not reach the registry. */
+function notify(run: () => void): void {
+  try {
+    run();
+  } catch (error) {
+    console.error("A subscriber of the process registry failed:", error);
+  }
+}
+
 export class ProcessRegistry {
   private readonly entries = new Map<string, Entry>();
   private readonly keepExited: number;
@@ -97,17 +154,17 @@ export class ProcessRegistry {
 
     const output = new OutputCollector(OUTPUT_TAIL_BYTES, "tail");
     const watchers = new Set<() => void>();
+    const listeners = new Set<ProcessOutputListener>();
     const changed = (): void => {
       for (const watcher of [...watchers]) watcher();
     };
-    child.stdout!.on("data", (chunk: Buffer) => {
-      output.add(chunk);
-      changed();
-    });
-    child.stderr!.on("data", (chunk: Buffer) => {
+    const received = (stream: "stdout" | "stderr", chunk: Buffer): void => {
       output.add(chunk);
+      for (const listener of [...listeners]) notify(() => listener.output?.({ stream, data: chunk }));
       changed();
-    });
+    };
+    child.stdout!.on("data", (chunk: Buffer) => received("stdout", chunk));
+    child.stderr!.on("data", (chunk: Buffer) => received("stderr", chunk));
 
     const done = new Promise<void>((resolve) => {
       let finished = false;
@@ -117,6 +174,10 @@ export class ProcessRegistry {
         info.exitedAt = new Date().toISOString();
         resolve();
         changed();
+        // The end is the last call to a subscriber: the registry then forgets each subscriber
+        const ending = [...listeners];
+        listeners.clear();
+        for (const listener of ending) notify(() => listener.end?.({ ...info, args: [...info.args] }));
         this.reap();
       };
       child.on("error", (error) => {
@@ -140,7 +201,7 @@ export class ProcessRegistry {
       (stream as unknown as { unref?: () => void } | null)?.unref?.();
     }
 
-    this.entries.set(id, { info, child, output, watchers, done });
+    this.entries.set(id, { info, child, output, watchers, listeners, done });
     this.reap();
     return { ...info };
   }
@@ -166,6 +227,105 @@ export class ProcessRegistry {
     return this.entries.get(id)?.output.text() ?? "";
   }
 
+  /**
+   * This function subscribes to the output of a process. `listener.output` gets each piece of
+   * output after this call, with its stream. `listener.end` gets the record at the end of the
+   * process, and then the registry forgets the subscriber. For a process that ended already,
+   * `listener.end` runs at once. The result removes the subscriber. It is undefined when the
+   * registry has no process of this id.
+   */
+  subscribe(id: string, listener: ProcessOutputListener): (() => void) | undefined {
+    const entry = this.entries.get(id);
+    if (!entry) return undefined;
+    if (entry.info.exitedAt) {
+      notify(() => listener.end?.({ ...entry.info, args: [...entry.info.args] }));
+      return () => undefined;
+    }
+    entry.listeners.add(listener);
+    return () => {
+      entry.listeners.delete(listener);
+    };
+  }
+
+  /**
+   * This function gives the output of a process as a stream, until the process ends or the
+   * signal aborts. The subscription starts when the reader asks for the first item, and the
+   * end of the stream removes it: an end of the process, an abort, or a reader that stops. With
+   * `backlog`, the first item is the output that the registry kept until then, without a gap.
+   * The last item of an ended process is `end`. An unknown id throws at the first item.
+   */
+  async *follow(id: string, options: FollowOptions = {}): AsyncGenerator<ProcessFollowItem, void, undefined> {
+    const limit = Math.max(1, options.maxBufferedBytes ?? FOLLOW_BUFFER_BYTES);
+    const signal = options.signal;
+    const queue: Array<{ item: ProcessFollowItem; bytes: number }> = [];
+    let queued = 0;
+    let dropped = 0;
+    let ended: ManagedProcessInfo | undefined;
+    let wake: (() => void) | undefined;
+    const wakeUp = (): void => {
+      const resolve = wake;
+      wake = undefined;
+      resolve?.();
+    };
+    const decoders = { stdout: new StringDecoder("utf8"), stderr: new StringDecoder("utf8") };
+    const add = (stream: "stdout" | "stderr", text: string, bytes: number): void => {
+      if (text === "") return;
+      queue.push({ item: { type: "output", stream, text }, bytes });
+      queued += bytes;
+      // The registry cannot slow the process: above the limit, the oldest pieces go
+      while (queued > limit && queue.length > 1) {
+        const oldest = queue.shift()!;
+        queued -= oldest.bytes;
+        dropped += oldest.bytes;
+      }
+    };
+
+    if (signal?.aborted) return;
+    const backlog = options.backlog ? this.output(id) : "";
+    const unsubscribe = this.subscribe(id, {
+      output: ({ stream, data }) => {
+        add(stream, decoders[stream].write(data), data.length);
+        wakeUp();
+      },
+      end: (info) => {
+        for (const stream of ["stdout", "stderr"] as const) {
+          const rest = decoders[stream].end();
+          add(stream, rest, Buffer.byteLength(rest));
+        }
+        ended = info;
+        wakeUp();
+      },
+    });
+    if (!unsubscribe) throw new Error(`No process ${id}`);
+    signal?.addEventListener("abort", wakeUp, { once: true });
+    try {
+      if (options.backlog) yield { type: "backlog", text: backlog };
+      for (;;) {
+        if (signal?.aborted) return;
+        if (dropped > 0) {
+          const bytes = dropped;
+          dropped = 0;
+          yield { type: "dropped", bytes };
+          continue;
+        }
+        const next = queue.shift();
+        if (next) {
+          queued -= next.bytes;
+          yield next.item;
+          continue;
+        }
+        if (ended) {
+          yield { type: "end", info: ended };
+          return;
+        }
+        await new Promise<void>((resolve) => (wake = resolve));
+      }
+    } finally {
+      unsubscribe();
+      signal?.removeEventListener("abort", wakeUp);
+    }
+  }
+
   /** This function waits until the process ends, then gives its record. */
   async exited(id: string): Promise<ManagedProcessInfo | undefined> {
     const entry = this.entries.get(id);