@gavin-hu/my-pi-agent 0.13.1 → 0.15.0

package/lib/config.ts

@@ -54,6 +54,24 @@ export function cleanString(value: unknown, fallback: string): string {
 	return typeof value === "string" && value.trim() ? value.trim() : fallback;
 }
 
+/** A trimmed non-empty string, or `undefined` when the value is unset or blank. */
+export function optionalString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+/** A boolean, or the fallback when the value is anything else. */
+export function asBoolean(value: unknown, fallback: boolean): boolean {
+	return typeof value === "boolean" ? value : fallback;
+}
+
+/** Kept trimmed, non-empty strings from an untrusted array, or the fallback. */
+export function stringList(value: unknown, fallback: string[]): string[] {
+	if (!Array.isArray(value)) return fallback;
+	return value
+		.filter((item): item is string => typeof item === "string" && item.trim().length > 0)
+		.map((item) => item.trim());
+}
+
 /**
  * `value` when it is a plain object, otherwise `undefined`.
  *
@@ -225,10 +243,39 @@ export function writeConfigValue(path: string, section: string, key: string, val
  * malformed document and an empty path.
  */
 export function writeConfigValueAt(path: string, section: string, keyPath: readonly string[], value: unknown): void {
-	if (keyPath.length === 0) throw new Error(`Cannot update ${path}: empty key path`);
+	writeConfigValuesAt(path, [{ section, path: keyPath, value }]);
+}
+
+/** One leaf edit for {@link writeConfigValuesAt}. */
+export interface ConfigLeafEdit {
+	section: string;
+	path: readonly string[];
+	value: unknown;
+}
+
+/**
+ * Set several leaves in one document pass, with the guarantees of
+ * {@link writeConfigValueAt}.
+ *
+ * A row that also writes a companion leaf (the currency writes its default
+ * precision) must not read, write, and re-read the file between the two: a
+ * failure in the second write would leave the first one on disk while the
+ * caller reports that nothing was saved. Every edit is applied to one parsed
+ * document and written once, so the file is either wholly updated or untouched.
+ * Later edits see the sections earlier ones built.
+ */
+export function writeConfigValuesAt(path: string, edits: readonly ConfigLeafEdit[]): void {
+	if (edits.length === 0) return;
+	for (const edit of edits) {
+		if (edit.path.length === 0) throw new Error(`Cannot update ${path}: empty key path`);
+	}
 	const document = readEditableDocument(path);
-	const current = configSection(document, section) ?? {};
-	document[section] = setPath(current, keyPath, value);
+	const sections = new Map<string, Record<string, unknown>>();
+	for (const edit of edits) {
+		const current = sections.get(edit.section) ?? configSection(document, edit.section) ?? {};
+		sections.set(edit.section, setPath(current, edit.path, edit.value));
+	}
+	for (const [section, value] of sections) document[section] = value;
 	writeConfigFile(path, document);
 }
 
@@ -246,27 +293,51 @@ function setPath(source: Record<string, unknown>, path: readonly string[], value
 }
 
 /**
- * Delete one key from one top-level section, preserving its siblings and the
- * rest of the document. An emptied section is removed rather than left as `{}`.
- * A no-op when the file, section, or key is absent; refuses a malformed
- * document.
+ * Delete the leaf at `keyPath` from one top-level section, preserving every
+ * sibling key, every other section, and document metadata. An object left empty
+ * by the deletion goes with it, the section included, so a file does not fill
+ * with `{}` shells. A no-op when the file, section, or leaf is absent; refuses a
+ * malformed document and an empty path.
  */
-export function unsetConfigValue(path: string, section: string, key: string): void {
+export function unsetConfigValueAt(path: string, section: string, keyPath: readonly string[]): void {
+	if (keyPath.length === 0) throw new Error(`Cannot update ${path}: empty key path`);
 	const result = readJsonResult(path);
 	if (result.state === "absent") return;
 	if (result.state === "error") throw new Error(`Cannot update ${path}: ${result.error}`);
 
 	const document = result.value;
 	const current = configSection(document, section);
-	if (!current || !(key in current)) return;
+	if (!current) return;
 
-	const next = { ...current };
-	delete next[key];
-	if (Object.keys(next).length === 0) delete document[section];
+	const next = withoutPath(current, keyPath);
+	if (next === current) return;
+	if (next === undefined) delete document[section];
 	else document[section] = next;
 	writeConfigFile(path, document);
 }
 
+/**
+ * Copy `source` without the leaf at `path`, or `undefined` once nothing is left.
+ * Returns `source` itself when the leaf is absent or sits behind a non-object,
+ * so the caller can tell "nothing to delete" from "a deletion happened".
+ */
+function withoutPath(source: Record<string, unknown>, path: readonly string[]): Record<string, unknown> | undefined {
+	const [head, ...rest] = path;
+	if (head === undefined || !(head in source)) return source;
+	const next = { ...source };
+	if (rest.length === 0) {
+		delete next[head];
+	} else {
+		const child = asRecord(source[head]);
+		if (!child) return source;
+		const pruned = withoutPath(child, rest);
+		if (pruned === child) return source;
+		if (pruned === undefined) delete next[head];
+		else next[head] = pruned;
+	}
+	return Object.keys(next).length === 0 ? undefined : next;
+}
+
 /** Write a whole config document atomically (sibling temp file, then rename). */
 export function writeConfigFile(path: string, document: Record<string, unknown>): void {
 	mkdirSync(dirname(path), { recursive: true });

package/lib/errors.ts

@@ -0,0 +1,12 @@
+/**
+ * One error-to-line helper for an unknown thrown value.
+ *
+ * Extensions report a rejected promise, a failed child process, and a parser
+ * error the same way: an `Error` yields its message, and anything else is
+ * stringified. Kept value-only so every extension has one definition.
+ */
+
+/** A user-facing message for an unknown thrown value. */
+export function messageOf(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}

package/lib/format.ts

@@ -49,6 +49,23 @@ export function formatDuration(ms: number): string {
 	return `${hours}h${String(minutes % 60).padStart(2, "0")}m`;
 }
 
+/** `1 tool`, `3 tools`: a tool count with the right word. */
+export function formatToolCount(count: number): string {
+	const n = Number.isFinite(count) ? Math.max(0, Math.trunc(count)) : 0;
+	return `${formatCount(n)} ${n === 1 ? "tool" : "tools"}`;
+}
+
+/**
+ * A tail bounded to `maxChars`: the end of the joined lines, with the truncation
+ * flag. The header and the truncation suffix belong to the caller, because each
+ * surface says something different about where the rest of the output lives.
+ */
+export function boundedTail(lines: readonly string[], maxChars: number): { text: string; truncated: boolean } {
+	const body = lines.join("\n");
+	if (body.length <= maxChars) return { text: body, truncated: false };
+	return { text: body.slice(body.length - maxChars), truncated: true };
+}
+
 /**
  * Replace terminal control characters (including ESC and the C1 block) with
  * spaces, keeping `\n` and `\t` for callers that render multi-line text.
@@ -90,6 +107,45 @@ export function sanitizeLine(text: string): string {
 	return sanitize(stripControlChars(text));
 }
 
+/** A string read as one sanitized line; any other value reads empty. */
+export function lineOf(value: unknown): string {
+	return typeof value === "string" ? sanitizeLine(value) : "";
+}
+
+/** Longest untrusted line kept for display; longer lines are clipped. */
+export const MAX_OUTPUT_LINE = 200;
+
+/** ESC-introduced sequences: OSC, CSI, and single-character escapes. */
+const OSC = /\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g;
+const CSI = /\u001b\[[0-?]*[ -/]*[@-~]/g;
+const OTHER_ESC = /\u001b[@-Z\\-_]/g;
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/g;
+
+/**
+ * The boundary for one line of **program output**: a log file, a child's
+ * stdout, a tailed file.
+ *
+ * Stronger than {@link sanitizeLine}, which strips control characters but leaves
+ * the printable tail of an ANSI sequence behind. This removes whole OSC, CSI,
+ * and single-character escapes first, then resolves carriage returns the way a
+ * terminal would (keep the text after the last `\r`, so progress rewrites
+ * collapse to their final state), squeezes whitespace, and clips the result.
+ *
+ * The escape-stripping has to happen before the control-character pass: once
+ * ESC has become a space, the rest of the sequence is ordinary text.
+ */
+export function sanitizeUntrustedLine(raw: string, maxLength: number = MAX_OUTPUT_LINE): string {
+	const withoutAnsi = raw.replace(OSC, "").replace(CSI, "").replace(OTHER_ESC, "");
+	const afterCr = withoutAnsi.slice(withoutAnsi.lastIndexOf("\r") + 1);
+	const cleaned = afterCr.replace(CONTROL, " ").replace(/\s+/g, " ").trim();
+	return cleaned.length > maxLength ? `${cleaned.slice(0, maxLength - 1)}…` : cleaned;
+}
+
+/** {@link sanitizeUntrustedLine} for a block of output, one entry per line. */
+export function sanitizeUntrustedText(raw: string, maxLength: number = MAX_OUTPUT_LINE): string[] {
+	return raw.split("\n").map((line) => sanitizeUntrustedLine(line, maxLength));
+}
+
 /**
  * Replace a home-directory prefix with `~`, matching at a path boundary so
  * `/home/bob` does not shorten `/home/bobby`. Separators are normalized to `/`

package/lib/git/read.ts

@@ -54,6 +54,14 @@ export async function gitDir(runGit: RunGit, cwd: string): Promise<string | unde
 	return dir || undefined;
 }
 
+/** Absolute path of the repository's common git directory, shared by its worktrees. */
+export async function gitCommonDir(runGit: RunGit, cwd: string): Promise<string | undefined> {
+	const result = await runGit(["rev-parse", "--path-format=absolute", "--git-common-dir"], { cwd });
+	if (result.code !== 0) return undefined;
+	const dir = result.stdout.trim();
+	return dir || undefined;
+}
+
 /** Resolve a revision to a full object id, or undefined when it does not exist. */
 export async function revParse(runGit: RunGit, cwd: string, rev: string): Promise<string | undefined> {
 	const result = await runGit(["rev-parse", "--verify", "--quiet", rev], { cwd });

package/lib/goal-state.ts

@@ -6,8 +6,13 @@
  * `error`, which is not a write — and the `/goal` command appends a `goal` custom
  * entry whose `data.goal` is `null` when the goal is cleared. Replaying the branch
  * in order is how another extension reads the goal without importing goal's
- * modules: `plan` restates an active goal in its planning context and offers to
- * record one when a plan is approved with none.
+ * modules: `plan` restates a pursued goal in its planning context, promotes a
+ * `planning` goal at plan exit, and offers to record one when a plan is approved
+ * with none.
+ *
+ * The status is the goal's phase: `planning` while a plan is being designed,
+ * `active` once the objective is final, `achieved` when it is done. Only `goal`
+ * writes it; the promotion out of `planning` runs through the `goal` tool.
  *
  * Stored values are re-validated and re-sanitized here. Branch data can be
  * tampered with, migrated, or written by an older version, and a reader must not
@@ -15,9 +20,10 @@
  * ignored rather than clearing a goal that is still valid.
  *
  * The entry type and the objective limit live here and are imported by `goal`, so
- * the publisher and the reader cannot drift. `goal` keeps its own reconstruction
- * (`extensions/goal/state.ts`) because it also drives the widget; this module is
- * the minimal contract other extensions may depend on.
+ * the publisher and the reader cannot drift. `goal` reads the branch through
+ * {@link lastGoal} as well — [`extensions/goal/state.ts`](../extensions/goal/state.ts)
+ * adds only the widget's active check and the open-todo count on top — so there
+ * is one replay, not two.
  */
 
 import { sanitizeLine } from "./format.ts";
@@ -29,8 +35,8 @@ export const GOAL_ENTRY_TYPE = "goal";
 /** Longest objective the goal tool accepts, and the most a reader will replay. */
 export const MAX_GOAL_OBJECTIVE = 2000;
 
-/** Whether the goal is still being pursued, or already done. */
-export type PublishedGoalStatus = "active" | "achieved";
+/** The goal's phase: being designed, final and pursued, or done. */
+export type PublishedGoalStatus = "planning" | "active" | "achieved";
 
 /** The goal as another extension may read it. */
 export interface PublishedGoal {
@@ -60,12 +66,21 @@ function readGoal(value: unknown): PublishedGoal | null | undefined {
 	if (!value || typeof value !== "object") return undefined;
 	const goal = value as { objective?: unknown; status?: unknown };
 	if (typeof goal.objective !== "string") return undefined;
-	if (goal.status !== "active" && goal.status !== "achieved") return undefined;
+	if (goal.status !== "planning" && goal.status !== "active" && goal.status !== "achieved") return undefined;
 	const objective = sanitizeLine(goal.objective);
 	if (!objective || objective.length > MAX_GOAL_OBJECTIVE) return undefined;
 	return { objective, status: goal.status };
 }
 
+/**
+ * True while the goal steers the session: `planning` or `active`, never
+ * `achieved`. Both the reminder and the plan-mode context read this, so a goal
+ * being designed is restated like one being executed.
+ */
+export function isPursuedGoal(goal: PublishedGoal | null): goal is PublishedGoal {
+	return goal?.status === "planning" || goal?.status === "active";
+}
+
 /** The last goal written on the branch, or `null` when the session has none. */
 export function lastGoal(entries: Iterable<unknown>): PublishedGoal | null {
 	let goal: PublishedGoal | null = null;

package/lib/http/headers.ts

@@ -0,0 +1,54 @@
+/**
+ * The response header sets both loopback servers answer with.
+ *
+ * One policy, declared once: the pages `file-browse` and `plan` serve are the
+ * same kind of document — a same-origin script, inline styles, and no network
+ * — so they must not drift into different envelopes, and a page that refuses to
+ * be framed cannot quietly stop doing so on one surface only.
+ *
+ * Every builder returns a fresh object, so a caller may add to a response
+ * without writing into another one. The policy itself is a code-authored
+ * constant; nothing here is model- or file-derived.
+ */
+
+/**
+ * The page policy. `default-src 'none'` makes every fetch opt-in; the inline
+ * style allowance is the page's own `<style>` block, `script-src 'self'` the
+ * same-origin client, and `connect-src 'self'` the page's own API routes.
+ *
+ * The last three directives are the ones that make a local page safe to leave
+ * open: `frame-ancestors 'none'` (with the legacy `X-Frame-Options`) stops a
+ * local page from framing the surface and clickjacking a control with a side
+ * effect, `base-uri 'self'` stops an injected `<base>` from re-pointing every
+ * relative URL, and `form-action 'none'` stops a submission anywhere.
+ */
+export const PAGE_CSP =
+	"default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'; script-src 'self'; " +
+	"connect-src 'self'; frame-ancestors 'none'; base-uri 'self'; form-action 'none'";
+
+/** The security and caching headers every response carries, whatever its body. */
+function secured(contentType: string): Record<string, string> {
+	return {
+		"Content-Type": contentType,
+		"Content-Security-Policy": PAGE_CSP,
+		"X-Frame-Options": "DENY",
+		"X-Content-Type-Options": "nosniff",
+		"Referrer-Policy": "no-referrer",
+		"Cache-Control": "no-store",
+	};
+}
+
+/** Headers for a served HTML page. */
+export function pageHeaders(): Record<string, string> {
+	return secured("text/html; charset=utf-8");
+}
+
+/** Headers for a same-origin script: the page policy, with the script's own type. */
+export function scriptHeaders(): Record<string, string> {
+	return secured("text/javascript; charset=utf-8");
+}
+
+/** Headers for a JSON API reply: the same envelope, a JSON type. */
+export function jsonHeaders(): Record<string, string> {
+	return secured("application/json; charset=utf-8");
+}

package/lib/http/index.ts

@@ -0,0 +1,13 @@
+/**
+ * The loopback HTTP layer shared by `file-browse` and `plan`: the response
+ * shape, the header policy, the request-envelope helpers, and the socket seam.
+ *
+ * Import from here rather than a leaf module, so the layer reads as one kit.
+ * Value-only, like the rest of `lib/`: the only state is what a returned closure
+ * carries (`createCloser`).
+ */
+
+export * from "./headers.ts";
+export * from "./response.ts";
+export * from "./router.ts";
+export * from "./server.ts";

package/lib/http/response.ts

@@ -0,0 +1,46 @@
+/**
+ * The response shape both loopback servers answer with, and the builders that
+ * pair a body with the header set it needs.
+ *
+ * A router returns one of these instead of touching a socket, so every route is
+ * testable without a server, and `server.ts` in this directory is the only code
+ * that writes one out. The shape carries the two ways a response is not a
+ * buffered body — a file to stream and a stream to hold open — because those are
+ * properties of the answer, not of the server that serves it.
+ */
+
+import { jsonHeaders, pageHeaders } from "./headers.ts";
+
+/** One HTTP response, before it reaches a socket. */
+export interface ServeResponse {
+	/** HTTP status code. */
+	status: number;
+	/** Headers to send verbatim. */
+	headers: Record<string, string>;
+	/** The buffered body; omitted for an empty response or a streamed file. */
+	body?: string | Buffer;
+	/** When set, the server streams this file instead of `body`. */
+	filePath?: string;
+	/** When true, the server keeps the connection open as a Server-Sent Events stream. */
+	stream?: boolean;
+}
+
+/** An HTML page, with any headers the route needs to add to the page policy. */
+export function htmlResponse(status: number, body: string, extra?: Record<string, string>): ServeResponse {
+	return { status, headers: { ...pageHeaders(), ...extra }, body };
+}
+
+/** A JSON body, serialized once. */
+export function jsonResponse(status: number, value: unknown): ServeResponse {
+	return { status, headers: jsonHeaders(), body: JSON.stringify(value) };
+}
+
+/** The JSON error envelope both API surfaces share: `{ error }`. */
+export function jsonError(status: number, message: string): ServeResponse {
+	return jsonResponse(status, { error: message });
+}
+
+/** A plain-text body, for the internal-error fallback a server sends itself. */
+export function textResponse(status: number, body: string): ServeResponse {
+	return { status, headers: { ...pageHeaders(), "Content-Type": "text/plain; charset=utf-8" }, body };
+}

package/lib/http/router.ts

@@ -0,0 +1,52 @@
+/**
+ * The request-envelope helpers both loopback routers apply before a route runs:
+ * the request target, and the `Host` allowlist.
+ *
+ * Both surfaces bind `127.0.0.1`, so a `Host` naming anything else is a
+ * DNS-rebinding attempt against a local page. How strictly a missing `Host` is
+ * treated is the caller's decision: the browse server accepts one, because its
+ * router is also driven directly from tests and a plain `GET` with no header is
+ * not a rebinding, while the review server fails closed.
+ */
+
+/** The `Host` names a loopback interface, with or without a port. */
+const LOCAL_HOST = /^(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/i;
+
+/** A request target split into the parts a router matches on. */
+export interface ParsedRequestUrl {
+	/** The path, with the leading slash and no query. */
+	pathname: string;
+	/** The parsed query string. */
+	search: URLSearchParams;
+}
+
+/**
+ * Parse a raw request target (`path?query`) against a loopback base. Returns
+ * `undefined` for a target that cannot be parsed, which a router answers with
+ * `400` rather than a route.
+ */
+export function parseRequestUrl(rawUrl: string): ParsedRequestUrl | undefined {
+	try {
+		const url = new URL(rawUrl, "http://127.0.0.1");
+		return { pathname: url.pathname, search: url.searchParams };
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Whether the request's `Host` names this loopback server.
+ *
+ * With `required: false`, only a present, non-empty foreign name is refused, so
+ * a header-less request from another caller still routes. With `required: true`,
+ * a missing or non-string `Host` is refused too, so the guard cannot be skipped
+ * by omitting the header.
+ */
+export function isLocalHostHeader(
+	headers: Record<string, string | string[] | undefined>,
+	options: { required: boolean },
+): boolean {
+	const host = headers.host;
+	if (typeof host !== "string" || host === "") return !options.required;
+	return LOCAL_HOST.test(host);
+}

package/lib/http/server.ts

@@ -0,0 +1,91 @@
+/**
+ * The socket seam shared by the two loopback servers: bind, write a response
+ * out, and close.
+ *
+ * Everything here is behavior a caller cannot get right by accident: a bind on
+ * `127.0.0.1` only, an accept-level `error` listener so a transient failure
+ * cannot take the host down, a `HEAD` that sends headers and no body, a `filePath`
+ * response streamed instead of buffered, and a close that is safe to call twice
+ * and drops keep-alive connections. What each server does *around* this — SSE
+ * streams, request bodies, session settling — stays with that server.
+ */
+
+import { createReadStream } from "node:fs";
+import type { IncomingMessage, Server, ServerResponse } from "node:http";
+import type { ServeResponse } from "./response.ts";
+
+/**
+ * Bind `server` to `127.0.0.1:port` and resolve the port it actually bound
+ * (`0` asks the OS to pick one). Rejects when the bind fails, so a caller that
+ * wants a fallback can retry with another port.
+ */
+export async function bindLoopback(server: Server, port: number): Promise<number> {
+	await new Promise<void>((resolve, reject) => {
+		const onError = (error: Error) => reject(error);
+		server.once("error", onError);
+		server.listen(port, "127.0.0.1", () => {
+			server.off("error", onError);
+			resolve();
+		});
+	});
+	// An accept-level failure (EMFILE and friends) is emitted on the server, and an
+	// `error` event with no listener would take the host down mid-session. The
+	// affected request fails on its own and is answered as an error by the caller.
+	server.on("error", () => {});
+	const address = server.address();
+	return typeof address === "object" && address ? address.port : port;
+}
+
+/**
+ * Write one routed response: headers first, then no body for `HEAD`, the file
+ * for a `filePath` response, or the buffered body.
+ *
+ * A `stream` response is deliberately not handled here: keeping a connection
+ * open is the owning server's lifecycle, so it must check `stream` before
+ * calling this.
+ *
+ * `afterFlush` runs once a buffered body is on the wire, which is the point a
+ * server may resolve a session without the client seeing a dropped connection.
+ * A streamed file has no such single point, so `respond` never calls it for one.
+ */
+export function respond(
+	request: IncomingMessage,
+	response: ServerResponse,
+	result: ServeResponse,
+	afterFlush?: () => void,
+): void {
+	response.writeHead(result.status, result.headers);
+	if ((request.method ?? "GET").toUpperCase() === "HEAD") {
+		response.end(afterFlush);
+		return;
+	}
+	if (result.filePath) {
+		const stream = createReadStream(result.filePath);
+		stream.on("error", () => response.destroy());
+		stream.pipe(response);
+		return;
+	}
+	response.end(result.body ?? "", afterFlush);
+}
+
+/**
+ * An idempotent `close()` for `server`.
+ *
+ * The second call resolves at once, so a shutdown path and a stop path can both
+ * await it. `closeAllConnections` is not on the `Server` type of every supported
+ * Node version, so it is probed: without it a keep-alive connection could hold
+ * the close open.
+ */
+export function createCloser(server: Server): () => Promise<void> {
+	let closed = false;
+	return () =>
+		new Promise<void>((resolve) => {
+			if (closed) {
+				resolve();
+				return;
+			}
+			closed = true;
+			server.close(() => resolve());
+			(server as { closeAllConnections?: () => void }).closeAllConnections?.();
+		});
+}

package/lib/lines.ts

@@ -0,0 +1,77 @@
+/**
+ * Line splitting for a stream of untrusted output.
+ *
+ * A child's stdout, or a file read, arrives in arbitrary byte chunks: a chunk
+ * boundary can fall in the middle of a line, and — the case a naive
+ * `chunk.toString()` gets wrong — in the middle of a multi-byte UTF-8
+ * character. This buffers the bytes and decodes only at a newline, so a split
+ * character survives intact.
+ *
+ * `\r` is not treated as a break: a progress rewrite belongs to the sanitizer
+ * (`sanitizeUntrustedLine` in `lib/format.ts`, which keeps the text after the
+ * last carriage return), and breaking on it here would turn one rewritten line
+ * into several.
+ *
+ * Value-only: the buffer lives on the instance, so each reader owns one.
+ */
+
+/** Bytes buffered for one incomplete line before it is emitted anyway. */
+export const MAX_LINE_BYTES = 1024 * 1024;
+
+export interface LineSplitterOptions {
+	/** Emit an unfinished line once it grows past this many bytes. Default 1 MiB. */
+	maxLineBytes?: number;
+}
+
+export class LineSplitter {
+	private pending: Buffer = Buffer.alloc(0);
+	private readonly maxLineBytes: number;
+
+	constructor(options: LineSplitterOptions = {}) {
+		this.maxLineBytes = options.maxLineBytes ?? MAX_LINE_BYTES;
+	}
+
+	/** Bytes held for the unfinished line. */
+	get pendingBytes(): number {
+		return this.pending.length;
+	}
+
+	/**
+	 * Feed one chunk and take every complete line it finishes.
+	 *
+	 * A line far longer than any display can show is emitted once it reaches the
+	 * cap instead of being dropped, so a program that never prints a newline still
+	 * produces output.
+	 */
+	push(chunk: Uint8Array | string): string[] {
+		const bytes = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : Buffer.from(chunk);
+		const combined = this.pending.length > 0 ? Buffer.concat([this.pending, bytes]) : bytes;
+		const lines: string[] = [];
+		let start = 0;
+		for (let newline = combined.indexOf(0x0a); newline >= 0; newline = combined.indexOf(0x0a, start)) {
+			lines.push(combined.subarray(start, newline).toString("utf8"));
+			start = newline + 1;
+		}
+		let rest = combined.subarray(start);
+		if (rest.length > this.maxLineBytes) {
+			lines.push(rest.toString("utf8"));
+			rest = combined.subarray(0, 0);
+		}
+		// Copy, so a caller that reuses its read buffer cannot rewrite the tail.
+		this.pending = Buffer.from(rest);
+		return lines;
+	}
+
+	/** Take the unfinished line, for a stream that has ended. */
+	flush(): string[] {
+		if (this.pending.length === 0) return [];
+		const line = this.pending.toString("utf8");
+		this.pending = Buffer.alloc(0);
+		return [line];
+	}
+
+	/** Drop the unfinished line, for a source that was truncated or replaced. */
+	reset(): void {
+		this.pending = Buffer.alloc(0);
+	}
+}