@bdsqqq/pi 0.0.1

package/dist/core/interpolate.js

@@ -0,0 +1,475 @@
+import { n as __require } from "../chunk-DsIazq42.js";
+import { clearConfigCache, getGlobalConfig, resolveConfigDir, setGlobalSettingsPath } from "./config.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { execSync } from "node:child_process";
+import * as os from "node:os";
+//#region packages/core/interpolate/index.ts
+/**
+* template variable interpolation for subagent system prompts.
+*
+* variables and their resolution strategies are declarative — defined in
+* bds-pi.json config or passed at call-time. resolver types: runtime,
+* literal, alias, file, env, dangerously_evaluate_js, dangerously_evaluate_sh.
+*
+* resolution order follows a topological sort of inter-variable references,
+* so {varA} can appear inside another variable's expression.
+*/
+const DEFAULT_PROMPT_VARIABLES = {
+	cwd: { runtime: "cwd" },
+	roots: { runtime: "roots" },
+	wsroot: { alias: "roots" },
+	workingDir: { alias: "cwd" },
+	date: { runtime: "date" },
+	os: { runtime: "os" },
+	repo: { runtime: "repo" },
+	sessionId: { runtime: "sessionId" },
+	ls: { runtime: "ls" },
+	identity: {
+		runtime: "identity",
+		default: "Amp"
+	},
+	harness: {
+		runtime: "harness",
+		default: "pi"
+	},
+	harness_docs_section: { runtime: "harnessDocsSection" }
+};
+/** walk up from dir looking for .git to find the workspace root. falls back to dir itself. */
+function findGitRoot(dir) {
+	let current = path.resolve(dir);
+	while (true) {
+		try {
+			const gitPath = path.join(current, ".git");
+			const stat = fs.statSync(gitPath);
+			if (stat.isDirectory() || stat.isFile()) return current;
+		} catch {}
+		const parent = path.dirname(current);
+		if (parent === current) return dir;
+		current = parent;
+	}
+}
+/** try to get the git remote origin URL for a directory. */
+function getGitRemoteUrl(dir) {
+	try {
+		return execSync("git remote get-url origin", {
+			cwd: dir,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).toString().trim();
+	} catch {
+		return "";
+	}
+}
+/** compute the built-in runtime variables map from cwd + extra context. */
+function computeRuntimeVars(cwd, extra) {
+	const roots = findGitRoot(cwd);
+	const date = (/* @__PURE__ */ new Date()).toLocaleDateString("en-US", {
+		weekday: "short",
+		year: "numeric",
+		month: "short",
+		day: "numeric"
+	});
+	const repo = extra?.repo ?? getGitRemoteUrl(roots);
+	const sessionId = extra?.sessionId ?? "";
+	let ls = "";
+	try {
+		ls = fs.readdirSync(roots).map((e) => {
+			const full = path.join(roots, e);
+			try {
+				return fs.statSync(full).isDirectory() ? `${full}/` : full;
+			} catch {
+				return full;
+			}
+		}).join("\n");
+	} catch {}
+	return {
+		cwd,
+		roots,
+		date,
+		os: `${os.platform()} (${os.release()}) on ${os.arch()}`,
+		repo,
+		sessionId,
+		ls,
+		identity: extra?.identity ?? "",
+		harness: extra?.harness ?? "",
+		harnessDocsSection: extra?.harnessDocsSection ?? ""
+	};
+}
+/** find {varName} patterns in a string that reference known variable names. */
+function extractRefs(s, knownVars) {
+	if (!s) return [];
+	const refs = [];
+	const re = /\{(\w+)\}/g;
+	let m;
+	while ((m = re.exec(s)) !== null) if (knownVars.has(m[1])) refs.push(m[1]);
+	return refs;
+}
+/** collect all variable dependencies for a single definition. */
+function getDeps(def, knownVars) {
+	const deps = /* @__PURE__ */ new Set();
+	if (def.alias !== void 0 && knownVars.has(def.alias)) deps.add(def.alias);
+	for (const ref of extractRefs(def.file, knownVars)) deps.add(ref);
+	for (const ref of extractRefs(def.dangerously_evaluate_js, knownVars)) deps.add(ref);
+	for (const ref of extractRefs(def.dangerously_evaluate_sh, knownVars)) deps.add(ref);
+	for (const ref of extractRefs(def.cwd, knownVars)) deps.add(ref);
+	for (const ref of extractRefs(def.default, knownVars)) deps.add(ref);
+	return [...deps];
+}
+/** topological sort of variable definitions. throws on cycles. */
+function topoSort(defs) {
+	const names = Object.keys(defs);
+	const knownVars = new Set(names);
+	const visited = /* @__PURE__ */ new Set();
+	const visiting = /* @__PURE__ */ new Set();
+	const order = [];
+	function visit(name) {
+		if (visited.has(name)) return;
+		if (visiting.has(name)) throw new Error(`cycle detected in prompt variables: ${name}`);
+		visiting.add(name);
+		const def = defs[name];
+		if (def) for (const dep of getDeps(def, knownVars)) visit(dep);
+		visiting.delete(name);
+		visited.add(name);
+		order.push(name);
+	}
+	for (const name of names) visit(name);
+	return order;
+}
+/** substitute already-resolved vars into a string. */
+function subVars(s, resolved) {
+	return s.replace(/\{(\w+)\}/g, (match, key) => key in resolved ? resolved[key] : match);
+}
+/** resolve a single variable definition to a string value. */
+function resolveVariable(def, resolved, runtimeVars, configDir) {
+	let value = "";
+	if (def.runtime !== void 0) value = runtimeVars[def.runtime] ?? "";
+	else if (def.literal !== void 0) value = def.literal;
+	else if (def.alias !== void 0) value = resolved[def.alias] ?? "";
+	else if (def.file !== void 0) {
+		const relPath = subVars(def.file, resolved);
+		const base = configDir ?? ".";
+		const absPath = path.resolve(base, relPath);
+		try {
+			value = fs.readFileSync(absPath, "utf-8");
+		} catch {
+			value = "";
+		}
+	} else if (def.env !== void 0) value = process.env[def.env] ?? "";
+	else if (def.dangerously_evaluate_js !== void 0) {
+		const expr = subVars(def.dangerously_evaluate_js, resolved);
+		try {
+			const result = new Function("require", `return (${expr})`)(__require);
+			value = String(result ?? "");
+		} catch {
+			value = "";
+		}
+	} else if (def.dangerously_evaluate_sh !== void 0) {
+		const cmd = subVars(def.dangerously_evaluate_sh, resolved);
+		const shCwd = def.cwd ? subVars(def.cwd, resolved) : void 0;
+		try {
+			value = execSync(cmd, {
+				cwd: shCwd,
+				timeout: 5e3,
+				stdio: [
+					"ignore",
+					"pipe",
+					"ignore"
+				]
+			}).toString().trim();
+		} catch {
+			value = "";
+		}
+	}
+	if (!value && def.default !== void 0) value = subVars(def.default, resolved);
+	return value;
+}
+/**
+* resolve template variables in agent prompts (e.g. {cwd}, {roots}, {date}).
+*
+* when a value is unavailable and dropLineIfEmpty is true (default),
+* the entire line containing the placeholder is removed rather than
+* leaving an empty label like "Repository: ".
+*
+* merge order: DEFAULT_PROMPT_VARIABLES → global config promptVariables → variables arg.
+*/
+function interpolatePromptVars(prompt, cwd, extra, variables) {
+	const configVars = variables === void 0 ? getGlobalConfig("promptVariables") ?? {} : {};
+	const merged = {
+		...DEFAULT_PROMPT_VARIABLES,
+		...configVars,
+		...variables ?? {}
+	};
+	const runtimeVars = computeRuntimeVars(cwd, extra);
+	const configDir = resolveConfigDir();
+	const order = topoSort(merged);
+	const resolved = {};
+	for (const name of order) resolved[name] = resolveVariable(merged[name], resolved, runtimeVars, configDir);
+	const dropKeys = [];
+	const filled = {};
+	for (const [key, value] of Object.entries(resolved)) {
+		const drop = merged[key]?.dropLineIfEmpty ?? true;
+		if (!value && drop) dropKeys.push(key);
+		else filled[key] = value;
+	}
+	let result = prompt;
+	if (dropKeys.length > 0) result = result.replace(new RegExp(`^.*\\{(${dropKeys.join("|")})\\}.*\\n?`, "gm"), "");
+	const filledKeys = Object.keys(filled);
+	if (filledKeys.length > 0) result = result.replace(new RegExp(`\\{(${filledKeys.join("|")})\\}`, "g"), (match, key) => filled[key] ?? match);
+	return result;
+}
+if (import.meta.vitest) {
+	const { afterEach, describe, expect, test } = import.meta.vitest;
+	const cwd = "/home/user/project";
+	afterEach(() => {
+		clearConfigCache();
+	});
+	describe("interpolatePromptVars", () => {
+		test("resolves all basic vars", () => {
+			const result = interpolatePromptVars("cwd={cwd} roots={roots} wsroot={wsroot} workingDir={workingDir} date={date} os={os}", cwd, {
+				repo: "gh:test",
+				sessionId: "s-123"
+			});
+			expect(result).toContain(`cwd=${cwd}`);
+			expect(result).toContain("roots=");
+			expect(result).toContain("wsroot=");
+			expect(result).toContain(`workingDir=${cwd}`);
+			expect(result).toContain("os=");
+			expect(result).not.toContain("{cwd}");
+			expect(result).not.toContain("{roots}");
+			expect(result).not.toContain("{date}");
+			expect(result).not.toContain("{os}");
+		});
+		test("resolves repo and sessionId from extra context", () => {
+			const result = interpolatePromptVars("Repository: {repo}\nSession: {sessionId}", cwd, {
+				repo: "https://github.com/test/repo",
+				sessionId: "abc-123"
+			});
+			expect(result).toContain("Repository: https://github.com/test/repo");
+			expect(result).toContain("Session: abc-123");
+		});
+		test("drops entire line when value is empty", () => {
+			const result = interpolatePromptVars("Working directory: {cwd}\nRepository: {repo}\nSession ID: {sessionId}\nDone.", cwd, {
+				repo: "",
+				sessionId: ""
+			});
+			expect(result).toContain(`Working directory: ${cwd}`);
+			expect(result).not.toContain("Repository");
+			expect(result).not.toContain("Session ID");
+			expect(result).toContain("Done.");
+		});
+		test("drops line when extra context is omitted entirely", () => {
+			const result = interpolatePromptVars("Dir: {cwd}\nRepo: {repo}\nEnd.", cwd);
+			expect(result).toContain(`Dir: ${cwd}`);
+			expect(result).not.toContain("Repo");
+			expect(result).toContain("End.");
+		});
+		test("no double-interpolation when a value contains another var pattern", () => {
+			const result = interpolatePromptVars("Repo: {repo}\nDate: {date}", cwd, {
+				repo: "my-{date}-repo",
+				sessionId: ""
+			});
+			expect(result).toContain("Repo: my-{date}-repo");
+			expect(result).toMatch(/Date: \w+/);
+		});
+		test("replaces multiple occurrences of same var", () => {
+			expect(interpolatePromptVars("{cwd} and also {cwd}", cwd, {
+				repo: "x",
+				sessionId: "y"
+			})).toBe(`${cwd} and also ${cwd}`);
+		});
+		test("multiline ls expansion preserves surrounding content", () => {
+			expect(interpolatePromptVars("Files:\n{ls}\nEnd.", cwd, {
+				repo: "x",
+				sessionId: "y"
+			})).toContain("End.");
+		});
+		test("empty ls drops the line", () => {
+			const result = interpolatePromptVars("Before\n{ls}\nAfter", "/nonexistent/path/unlikely", {
+				repo: "x",
+				sessionId: "y"
+			});
+			expect(result).toContain("Before");
+			expect(result).toContain("After");
+		});
+	});
+	describe("findGitRoot", () => {
+		test("finds git root from cwd", () => {
+			const root = findGitRoot(process.cwd());
+			const { existsSync } = __require("node:fs");
+			const { join } = __require("node:path");
+			expect(existsSync(join(root, ".git"))).toBe(true);
+		});
+		test("falls back to dir when no git root exists", () => {
+			expect(findGitRoot("/tmp/nonexistent-no-git-here")).toBe("/tmp/nonexistent-no-git-here");
+		});
+	});
+	describe("literal resolver", () => {
+		test("returns static string", () => {
+			expect(interpolatePromptVars("val={myVar}", cwd, {
+				repo: "x",
+				sessionId: "y"
+			}, { myVar: { literal: "hello world" } })).toContain("val=hello world");
+		});
+	});
+	describe("alias resolver", () => {
+		test("resolves to another variable's value", () => {
+			const result = interpolatePromptVars("a={a} b={b}", cwd, {
+				repo: "x",
+				sessionId: "y"
+			}, {
+				a: { literal: "alpha" },
+				b: { alias: "a" }
+			});
+			expect(result).toContain("a=alpha");
+			expect(result).toContain("b=alpha");
+		});
+	});
+	describe("file resolver", () => {
+		test("reads file contents relative to config dir", () => {
+			const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-interp-test-"));
+			const filePath = path.join(tmpDir, "test.txt");
+			fs.writeFileSync(filePath, "file content here");
+			setGlobalSettingsPath(path.join(tmpDir, "bds-pi.json"));
+			expect(interpolatePromptVars("content={f}", cwd, {
+				repo: "x",
+				sessionId: "y"
+			}, { f: { file: "test.txt" } })).toContain("content=file content here");
+		});
+	});
+	describe("env resolver", () => {
+		test("reads environment variable", () => {
+			const key = `PI_TEST_ENV_${Date.now()}`;
+			process.env[key] = "env_value";
+			try {
+				expect(interpolatePromptVars("e={e}", cwd, {
+					repo: "x",
+					sessionId: "y"
+				}, { e: { env: key } })).toContain("e=env_value");
+			} finally {
+				delete process.env[key];
+			}
+		});
+	});
+	describe("dangerously_evaluate_js resolver", () => {
+		test("evaluates JS expression", () => {
+			expect(interpolatePromptVars("n={n}", cwd, {
+				repo: "x",
+				sessionId: "y"
+			}, { n: { dangerously_evaluate_js: "2 + 2" } })).toContain("n=4");
+		});
+		test("returns empty on error", () => {
+			const result = interpolatePromptVars("n={n}\nend", cwd, {
+				repo: "x",
+				sessionId: "y"
+			}, { n: { dangerously_evaluate_js: "throw new Error('boom')" } });
+			expect(result).not.toContain("n=");
+			expect(result).toContain("end");
+		});
+	});
+	describe("dangerously_evaluate_sh resolver", () => {
+		test("captures stdout from shell command", () => {
+			expect(interpolatePromptVars("v={v}", cwd, {
+				repo: "x",
+				sessionId: "y"
+			}, { v: { dangerously_evaluate_sh: "echo hello_from_sh" } })).toContain("v=hello_from_sh");
+		});
+		test("cwd supports {var} refs", () => {
+			const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-interp-sh-"));
+			expect(interpolatePromptVars("v={v}", cwd, {
+				repo: "x",
+				sessionId: "y"
+			}, {
+				dir: { literal: tmpDir },
+				v: {
+					dangerously_evaluate_sh: "pwd",
+					cwd: "{dir}"
+				}
+			})).toContain(tmpDir);
+		});
+	});
+	describe("default value", () => {
+		test("falls back to default when resolver returns empty", () => {
+			const key = `PI_TEST_MISSING_${Date.now()}`;
+			delete process.env[key];
+			expect(interpolatePromptVars("v={v}", cwd, {
+				repo: "x",
+				sessionId: "y"
+			}, { v: {
+				env: key,
+				default: "fallback"
+			} })).toContain("v=fallback");
+		});
+		test("default supports {var} refs", () => {
+			const key = `PI_TEST_MISSING2_${Date.now()}`;
+			delete process.env[key];
+			expect(interpolatePromptVars("v={v}", cwd, {
+				repo: "x",
+				sessionId: "y"
+			}, {
+				base: { literal: "hello" },
+				v: {
+					env: key,
+					default: "{base}-world"
+				}
+			})).toContain("v=hello-world");
+		});
+	});
+	describe("topo sort", () => {
+		test("resolves dependencies in correct order", () => {
+			const result = interpolatePromptVars("a={a} b={b} c={c}", cwd, {
+				repo: "x",
+				sessionId: "y"
+			}, {
+				c: { alias: "b" },
+				b: { alias: "a" },
+				a: { literal: "root" }
+			});
+			expect(result).toContain("a=root");
+			expect(result).toContain("b=root");
+			expect(result).toContain("c=root");
+		});
+		test("throws on cycle", () => {
+			expect(() => interpolatePromptVars("x={x}", cwd, {
+				repo: "x",
+				sessionId: "y"
+			}, {
+				x: { alias: "y" },
+				y: { alias: "x" }
+			})).toThrow(/cycle/i);
+		});
+	});
+	describe("dropLineIfEmpty", () => {
+		test("preserves line when dropLineIfEmpty is false", () => {
+			const key = `PI_TEST_DROP_${Date.now()}`;
+			delete process.env[key];
+			const result = interpolatePromptVars("Before\nLabel: {v}\nAfter", cwd, {
+				repo: "x",
+				sessionId: "y"
+			}, { v: {
+				env: key,
+				dropLineIfEmpty: false
+			} });
+			expect(result).toContain("Label: ");
+			expect(result).toContain("Before");
+			expect(result).toContain("After");
+		});
+	});
+	describe("config-driven variables", () => {
+		test("reads promptVariables from global config", () => {
+			const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-interp-cfg-"));
+			const settingsPath = path.join(tmpDir, "bds-pi.json");
+			fs.writeFileSync(settingsPath, JSON.stringify({ promptVariables: { custom: { literal: "from config" } } }));
+			setGlobalSettingsPath(settingsPath);
+			expect(interpolatePromptVars("v={custom}", cwd, {
+				repo: "x",
+				sessionId: "y"
+			})).toContain("v=from config");
+		});
+	});
+}
+//#endregion
+export { DEFAULT_PROMPT_VARIABLES, computeRuntimeVars, findGitRoot, getGitRemoteUrl, interpolatePromptVars };

package/dist/core/mutex.d.ts

@@ -0,0 +1,8 @@
+//#region packages/core/mutex/index.d.ts
+/**
+* execute `fn` while holding an exclusive lock on `filePath`.
+* concurrent calls for the same resolved path queue sequentially.
+*/
+declare function withFileLock<T>(filePath: string, fn: () => Promise<T>): Promise<T>;
+//#endregion
+export { withFileLock };

package/dist/core/mutex.js

@@ -0,0 +1,142 @@
+import * as path from "node:path";
+//#region packages/core/mutex/index.ts
+/**
+* per-path async mutex for file operations.
+*
+* serializes concurrent edits to the same file path to prevent
+* partial writes and race conditions. pi's built-in edit tool doesn't.
+* this mutex is keyed by resolved absolute path — two relative paths
+* pointing to the same file share one lock.
+*/
+const locks = /* @__PURE__ */ new Map();
+/**
+* execute `fn` while holding an exclusive lock on `filePath`.
+* concurrent calls for the same resolved path queue sequentially.
+*/
+async function withFileLock(filePath, fn) {
+	const key = path.resolve(filePath);
+	while (locks.has(key)) await locks.get(key);
+	let resolve;
+	const promise = new Promise((r) => {
+		resolve = r;
+	});
+	locks.set(key, promise);
+	try {
+		return await fn();
+	} finally {
+		locks.delete(key);
+		resolve();
+	}
+}
+if (import.meta.vitest) {
+	const { describe, it, expect } = import.meta.vitest;
+	describe("withFileLock", () => {
+		it("executes function and returns result", async () => {
+			expect(await withFileLock("/tmp/test.txt", async () => {
+				return "success";
+			})).toBe("success");
+		});
+		it("propagates errors from the function", async () => {
+			try {
+				await withFileLock("/tmp/error.txt", async () => {
+					throw new Error("test error");
+				});
+				expect(true).toBe(false);
+			} catch (e) {
+				expect(e.message).toBe("test error");
+			}
+		});
+		it("serializes concurrent calls for the same path", async () => {
+			const order = [];
+			const path = "/tmp/same-path.txt";
+			const makeOp = (id, delayMs) => withFileLock(path, async () => {
+				order.push(`${id}-start`);
+				await new Promise((r) => setTimeout(r, delayMs));
+				order.push(`${id}-end`);
+				return id;
+			});
+			expect(await Promise.all([
+				makeOp("a", 50),
+				makeOp("b", 30),
+				makeOp("c", 10)
+			])).toEqual([
+				"a",
+				"b",
+				"c"
+			]);
+			expect(order).toEqual([
+				"a-start",
+				"a-end",
+				"b-start",
+				"b-end",
+				"c-start",
+				"c-end"
+			]);
+		});
+		it("allows parallel execution for different paths", async () => {
+			const order = [];
+			const makeOp = (path, id, delayMs) => withFileLock(path, async () => {
+				order.push(`${id}-start`);
+				await new Promise((r) => setTimeout(r, delayMs));
+				order.push(`${id}-end`);
+				return id;
+			});
+			const start = Date.now();
+			const results = await Promise.all([
+				makeOp("/tmp/path-a.txt", "a", 50),
+				makeOp("/tmp/path-b.txt", "b", 50),
+				makeOp("/tmp/path-c.txt", "c", 50)
+			]);
+			const elapsed = Date.now() - start;
+			expect(results).toEqual([
+				"a",
+				"b",
+				"c"
+			]);
+			expect(elapsed).toBeLessThan(120);
+			const starts = order.filter((o) => o.endsWith("-start"));
+			const ends = order.filter((o) => o.endsWith("-end"));
+			expect(starts).toHaveLength(3);
+			expect(ends).toHaveLength(3);
+		});
+		it("handles same path resolved differently", async () => {
+			const order = [];
+			expect(await Promise.all([withFileLock("/tmp/same-file.txt", async () => {
+				order.push("abs-start");
+				await new Promise((r) => setTimeout(r, 20));
+				order.push("abs-end");
+				return "abs";
+			})])).toEqual(["abs"]);
+		});
+		it("releases lock after error", async () => {
+			const path = "/tmp/error-release.txt";
+			try {
+				await withFileLock(path, async () => {
+					throw new Error("first fails");
+				});
+				expect(true).toBe(false);
+			} catch (e) {
+				expect(e.message).toBe("first fails");
+			}
+			expect(await withFileLock(path, async () => {
+				return "second succeeds";
+			})).toBe("second succeeds");
+		});
+		it("handles rapid sequential calls on same path", async () => {
+			const path = "/tmp/rapid.txt";
+			let counter = 0;
+			expect(await Promise.all([
+				withFileLock(path, async () => ++counter),
+				withFileLock(path, async () => ++counter),
+				withFileLock(path, async () => ++counter)
+			])).toEqual([
+				1,
+				2,
+				3
+			]);
+			expect(counter).toBe(3);
+		});
+	});
+}
+//#endregion
+export { withFileLock };

package/dist/core/output-buffer.d.ts

@@ -0,0 +1,80 @@
+//#region packages/core/output-buffer/index.d.ts
+/**
+* truncate an array to head + tail, returning formatted result.
+* simpler than OutputBuffer — for when you have all items upfront (not streaming).
+*
+* @param items - array to truncate
+* @param maxItems - total items to show (split evenly between head/tail)
+* @returns { head, tail, truncated, truncatedCount }
+*/
+declare function headTail<T>(items: T[], maxItems?: number): {
+  head: T[];
+  tail: T[];
+  truncated: T[];
+  truncatedCount: number;
+};
+/**
+* format head+tail arrays with truncation marker.
+* returns a single string with items joined by newlines.
+*/
+declare function formatHeadTail<T>(items: T[], maxItems?: number, truncatedMsg?: (count: number) => string): string;
+/**
+* truncate raw text to head + tail by characters.
+* for when you have a single string (not lines) that needs truncation.
+*/
+declare function headTailChars(text: string, maxChars?: number): {
+  text: string;
+  truncated: boolean;
+  totalChars: number;
+};
+declare class OutputBuffer {
+  private maxHead;
+  private maxTail;
+  private head;
+  private tail;
+  private headComplete;
+  private pendingLine;
+  totalLines: number;
+  constructor(maxHead?: number, maxTail?: number);
+  /**
+  * add a chunk of output. handles partial lines at boundaries.
+  * chunks may end mid-line, so we buffer the incomplete part.
+  */
+  add(chunk: string): void;
+  /**
+  * add a complete line to the appropriate buffer.
+  * fills head first, then rolls tail.
+  */
+  private addLine;
+  /**
+  * finalize and format the output.
+  * returns the formatted text and count of truncated lines.
+  *
+  * small output (<= head + tail): dedupes overlap, no truncation marker
+  * large output: head + marker + tail
+  */
+  format(): {
+    text: string;
+    truncatedLines: number;
+  };
+  /**
+  * deduplicate overlapping head/tail for small outputs.
+  *
+  * when total lines <= maxHead + maxTail, the tail buffer
+  * may contain lines already in head. we merge them using
+  * positional overlap (not value matching) to avoid dropping
+  * legitimate lines when content has duplicates.
+  */
+  private dedupe;
+  /**
+  * get current buffer state for debugging.
+  */
+  debug(): {
+    head: string[];
+    tail: string[];
+    totalLines: number;
+    pendingLine: string;
+  };
+}
+//#endregion
+export { OutputBuffer, formatHeadTail, headTail, headTailChars };