pi-posthorse 0.8.0 → 0.8.2

package/package.json

@@ -1,29 +1,51 @@
 {
 	"name": "pi-posthorse",
-	"version": "0.8.0",
+	"version": "0.8.2",
 	"type": "module",
 	"description": "Posthorse: fresh context, same journey. No-summary context rollover for Pi, with sparse budget reminders, handoffs, notes, and history.",
-	"keywords": ["pi-package", "pi-extension", "context", "posthorse", "rollover"],
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"context",
+		"posthorse",
+		"rollover"
+	],
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/fitchmultz/pi-posthorse.git"
 	},
 	"license": "MIT",
-	"files": ["index.ts", "ui.ts"],
+	"files": [
+		"index.ts",
+		"ui.ts",
+		"src"
+	],
 	"engines": {
 		"node": ">=24.12.0"
 	},
 	"packageManager": "npm@12.2.0",
 	"pi": {
-		"extensions": ["./index.ts"],
+		"extensions": [
+			"./index.ts"
+		],
 		"image": "https://raw.githubusercontent.com/fitchmultz/pi-posthorse/main/diagram.png"
 	},
 	"scripts": {
 		"check": "tsc",
+		"quality:prepare": "node scripts/setup-oxlint-engine.ts && node scripts/setup-quality-engine.ts",
+		"quality:policy": "node scripts/quality-policy.ts",
+		"quality:probes": "npm run quality:prepare && node --test test/quality*.test.ts",
+		"lint": "npm run quality:prepare && npm run quality:policy && oxlint --deny-warnings .",
+		"lint:agent": "npm run quality:prepare && npm run quality:policy && oxlint --deny-warnings --format=agent .",
+		"lint:fix": "npm run quality:prepare && npm run quality:policy && oxlint --fix .",
+		"format": "oxfmt --write .",
+		"format:check": "oxfmt --check .",
+		"build": "npm pack --dry-run",
+		"verify": "npm run lint && npm run format:check && npm run check:compat && npm run build",
 		"check:compat": "npm run check && npm test && npm run test:native",
 		"test:native": "node --import ./test/pi-loader.ts --test test/host.test.mjs",
-		"test": "node --import ./test/pi-loader.ts --test test/*.test.ts",
-		"prepublishOnly": "npm test && npm run check"
+		"test": "npm run quality:prepare && node --import ./test/pi-loader.ts --test test/*.test.ts",
+		"prepublishOnly": "npm run verify"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-coding-agent": "*",
@@ -45,7 +67,11 @@
 		"@earendil-works/pi-ai": "1.0.0",
 		"@earendil-works/pi-coding-agent": "1.0.0",
 		"@earendil-works/pi-tui": "1.0.0",
-		"@types/node": "24.19.0",
+		"@types/node": "24.19.1",
+		"oxc-parser": "0.153.0",
+		"oxfmt": "0.72.0",
+		"oxlint": "1.87.0",
+		"oxlint-tsgolint": "7.0.2003",
 		"typebox": "1.3.27",
 		"typescript": "7.0.2"
 	}

package/src/budget.ts

@@ -0,0 +1,168 @@
+import {
+	estimateTokens,
+	getAgentDir,
+	SettingsManager,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+	ESTIMATED_IMAGE_CHARS,
+	MAX_HANDOFF_CHARS,
+	MAX_PAGE_CHARS,
+	PAGE_MARGIN_TOKENS,
+	type CompactionPolicy,
+	type ContextUsage,
+	type MessageLike,
+	type PolicyContext,
+	type PolicyReader,
+} from "./contracts.ts";
+import { imagesOf, textOf } from "./message-text.ts";
+
+const MIN_USABLE_TOKENS = Math.ceil(MAX_HANDOFF_CHARS / 4) * 2;
+export const SNAPSHOT_NOTE =
+	"Reminder and budget policy uses available settings (a persisted CLI snapshot by default); Pi's live settings control automatic compaction.";
+export const CHECKPOINT_STEPS =
+	"update the task's current-state note (goal, progress, decisions, next steps) with available file-editing tools at its absolute path; use notes write only for creation, substantial restructuring, or when editing tools are unavailable. If the note is already current, leave it unchanged. Then call new_context";
+export type Budget = {
+	readonly contextWindow: number;
+	readonly reserveTokens: number;
+	readonly enabled: boolean;
+	readonly usable: number;
+	readonly rolloverAt: number;
+	readonly supported: boolean;
+};
+export function persistedPolicy(ctx: ExtensionContext): CompactionPolicy {
+	const settings = SettingsManager.create(ctx.cwd, getAgentDir(), {
+		projectTrusted: ctx.isProjectTrusted(),
+	});
+	const errors = settings.drainErrors();
+	if (errors.length > 0) {
+		throw new Error(
+			`Posthorse could not read persisted Pi settings: ${errors.map((error) => error.error.message).join("; ")}`,
+		);
+	}
+	return settings.getCompactionSettings(ctx.model);
+}
+/** A synchronous evaluation owns one snapshot; never carry it across an await. */
+export function policySnapshot(
+	ctx: ExtensionContext,
+	getPolicy: PolicyReader,
+	livePolicy?: CompactionPolicy,
+): PolicyContext {
+	let usageRead = false;
+	let usage: ContextUsage | undefined;
+	let settings: CompactionPolicy | undefined;
+	return {
+		getCompactionSettings: () => {
+			settings ??= { ...(livePolicy ?? getPolicy(ctx)) };
+			return settings;
+		},
+		getContextUsage: () => {
+			if (!usageRead) {
+				usage = ctx.getContextUsage();
+				usageRead = true;
+			}
+			return usage;
+		},
+		getSystemPrompt: () => ctx.getSystemPrompt(),
+	};
+}
+export function budgetFor(
+	ctx: PolicyContext,
+	contextWindow = ctx.getContextUsage()?.contextWindow,
+): Budget | undefined {
+	if (contextWindow === undefined || contextWindow <= 0) {
+		return undefined;
+	}
+	const { enabled, reserveTokens } = ctx.getCompactionSettings();
+	const usable = contextWindow - reserveTokens;
+	return {
+		contextWindow,
+		reserveTokens,
+		enabled,
+		usable,
+		rolloverAt: usable + 1,
+		supported: !enabled || usable >= MIN_USABLE_TOKENS,
+	};
+}
+export function unsupportedMessage(budget: Budget): string {
+	const n = (value: number) => value.toLocaleString("en-US");
+	return `Posthorse: unsupported configuration. The model's context window (${n(budget.contextWindow)} tokens) minus Pi's compaction.reserveTokens (${n(budget.reserveTokens)}) leaves ${n(budget.usable)} usable tokens; Posthorse needs at least ${n(MIN_USABLE_TOKENS)}. Automatic Posthorse rollover and checkpoint reminders are off for this model, so Pi's own compaction applies. Lower compaction.reserveTokens in Pi settings or use a larger-context model. new_context remains available with a model-aware handoff limit.`;
+}
+function automaticGuidance(budget: Budget | undefined, enabled: boolean): string {
+	if (!enabled) {
+		return "Pi compaction is disabled in the available settings, so Posthorse sends no checkpoint reminder. new_context remains available.";
+	}
+	if (budget !== undefined && !budget.supported) {
+		return unsupportedMessage(budget);
+	}
+	const deadline =
+		budget === undefined
+			? "the configured Pi context limit"
+			: `${Math.max(1, Math.round((budget.rolloverAt / budget.contextWindow) * 100))}% used`;
+	const line =
+		budget === undefined
+			? ""
+			: ` The rollover line is ${budget.rolloverAt.toLocaleString("en-US")} tokens used under the available Pi settings.`;
+	return `Automatic rollover follows Pi's compaction setting.${line} At most one checkpoint reminder may arrive before the rollover line (${deadline}); when it does, stop normal work, ${CHECKPOINT_STEPS}.`;
+}
+export function buildGuidance(ctx: PolicyContext): string {
+	const budget = budgetFor(ctx);
+	const enabled = budget?.enabled ?? ctx.getCompactionSettings().enabled;
+	const capacity =
+		budget === undefined
+			? "Configured context capacity is unknown."
+			: `Configured context capacity: ${budget.contextWindow.toLocaleString("en-US")} tokens. This is Pi's best available native limit, not remaining space or a measured provider boundary. Fresh windows use the active configuration; system instructions, tools, the handoff, and new messages consume part of it.`;
+	return `## Context self-management (Posthorse)
+${capacity}
+Do not guess context capacity or remaining space from response-token limits or reasoning budgets. Before reporting a remaining-token count or changing your work plan because of context limits, call get_context_remaining. If usage is unknown, report it as unknown. No routine budget checks are needed.
+${automaticGuidance(budget, enabled)}
+After a rollover, earlier conversation stays in history. Restore notes and todos, then verify live state before stateful or external work; automatic handoffs record inputs, not progress.
+Keep one concise current-state note per task. Preserve decisions and safety constraints; link fuller evidence and history instead of copying them. Edit changed sections rather than resending unchanged content.
+Write handoffs and notes as normal readable prose; notes and history search match literal text.`;
+}
+/** ponytail: native estimates omit request-local guidance; reserve it until post-transform usage is exposed. */
+export function guidanceTokens(ctx: PolicyContext): number {
+	return estimateTokens({
+		role: "system",
+		content: `<posthorse>\n${buildGuidance(ctx)}\n</posthorse>`,
+		timestamp: 0,
+	});
+}
+/** Half the fresh capacity after prompt/tool/input overhead remains for continued work. */
+export function freshPayloadChars(
+	ctx: PolicyContext,
+	toolTokens: number,
+	pendingMessages: readonly MessageLike[] = [],
+	cap = MAX_HANDOFF_CHARS,
+): number {
+	const budget = budgetFor(ctx);
+	if (budget === undefined) {
+		return cap;
+	}
+	const line = budget.enabled && budget.supported ? budget.rolloverAt : budget.contextWindow;
+	const promptTokens = Math.ceil(ctx.getSystemPrompt().length / 4) + guidanceTokens(ctx);
+	const pendingTokens = pendingMessages.reduce(
+		(total, message) =>
+			total +
+			Math.ceil(textOf(message).length / 4) +
+			imagesOf(message.content).length * (ESTIMATED_IMAGE_CHARS / 4),
+		0,
+	);
+	return Math.min(
+		cap,
+		Math.max(
+			0,
+			Math.floor((line - PAGE_MARGIN_TOKENS - promptTokens - toolTokens - pendingTokens) / 2),
+		) * 4,
+	);
+}
+export function pageCapacity(ctx: PolicyContext, toolTokens: number): number {
+	const usage = ctx.getContextUsage();
+	if (usage === undefined || usage.tokens === null) {
+		return freshPayloadChars(ctx, toolTokens, [], MAX_PAGE_CHARS) / 4 + PAGE_MARGIN_TOKENS;
+	}
+	const budget = budgetFor(ctx, usage.contextWindow);
+	const line =
+		budget?.enabled === true && budget.supported ? budget.rolloverAt : usage.contextWindow;
+	return line - usage.tokens - guidanceTokens(ctx);
+}

package/src/context-tools.ts

@@ -0,0 +1,113 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { toolCards, type PosthorseDisplay } from "../ui.ts";
+import {
+	budgetFor,
+	freshPayloadChars,
+	SNAPSHOT_NOTE,
+	unsupportedMessage,
+	type Budget,
+} from "./budget.ts";
+import {
+	EMPTY_HANDOFF,
+	MAX_HANDOFF_CHARS,
+	textResult,
+	type PolicyContext,
+	type TextResult,
+} from "./contracts.ts";
+
+function rolloverStatus(budget: Budget | undefined): "disabled" | "enabled" | "unsupported" {
+	if (budget?.enabled !== true) {
+		return "disabled";
+	}
+	return budget.supported ? "enabled" : "unsupported";
+}
+function contextReport(host: PolicyContext): TextResult {
+	const usage = host.getContextUsage();
+	if (usage === undefined || usage.tokens === null) {
+		return textResult("Context usage is not known until the next model response.", [], {
+			kind: "context",
+		});
+	}
+	const n = (value: number) => value.toLocaleString("en-US");
+	const budget = budgetFor(host, usage.contextWindow);
+	const rollover = rolloverStatus(budget);
+	const display: PosthorseDisplay = {
+		kind: "context",
+		usage,
+		rollover,
+		rolloverAt: budget?.rolloverAt,
+	};
+	const configured = `≈${n(Math.max(0, usage.contextWindow - usage.tokens))} tokens until the configured context limit (${n(usage.tokens)}/${n(usage.contextWindow)} used, ${Math.round(usage.percent ?? 0)}%). Best available native estimate. ${SNAPSHOT_NOTE}`;
+	if (budget?.enabled !== true) {
+		return textResult(
+			`Automatic rollover is disabled in the available settings (Pi compaction.enabled=false). ${configured}`,
+			[],
+			display,
+		);
+	}
+	if (!budget.supported) {
+		return textResult(`${unsupportedMessage(budget)} ${configured}`, [], display);
+	}
+	return textResult(
+		`≈${n(Math.max(0, budget.rolloverAt - usage.tokens))} tokens until automatic rollover (line at ${n(budget.rolloverAt)}); ${configured}`,
+		[],
+		display,
+	);
+}
+export function registerContextTools(
+	pi: ExtensionAPI,
+	policy: (ctx: ExtensionContext) => PolicyContext,
+	activeToolTokens: () => number,
+	requestReset: (id: string, handoff: string) => void,
+): void {
+	pi.registerTool({
+		name: "new_context",
+		label: "New Context",
+		...toolCards("new_context"),
+		description:
+			"Start a fresh context window once the current foreground tools succeed; background work continues across the reset. Earlier conversation stays recoverable through history. Put continuation state in handoff, or save fuller state in notes first.",
+		promptSnippet: "request a fresh context window with an optional handoff",
+		parameters: Type.Object({
+			handoff: Type.Optional(
+				Type.String({
+					description: "What the fresh window needs to continue, as readable prose",
+					maxLength: MAX_HANDOFF_CHARS,
+				}),
+			),
+		}),
+		// Pi's fixed tool contract supplies id, params, signal, updates, and context.
+		// oxlint-disable-next-line max-params
+		async execute(id, { handoff }, _signal, _onUpdate, ctx) {
+			const trimmed = handoff?.trim();
+			const limit = freshPayloadChars(policy(ctx), activeToolTokens());
+			if (trimmed !== undefined && trimmed !== "" && trimmed.length > limit) {
+				throw new Error(
+					`Handoff is too large for the active model (${trimmed.length.toLocaleString("en-US")} characters; limit ${limit.toLocaleString("en-US")}). Save fuller state in notes, then retry with a shorter handoff or no handoff.`,
+				);
+			}
+			const result = textResult(
+				"Requested a fresh Pi context after the current foreground tools succeed. Background work continues across the reset. Earlier conversation stays in session history.",
+				[],
+				{ kind: "new-context" },
+			);
+			requestReset(id, trimmed === undefined || trimmed === "" ? EMPTY_HANDOFF : trimmed);
+			return result;
+		},
+	});
+	pi.registerTool({
+		name: "get_context_remaining",
+		label: "Context Remaining",
+		...toolCards("get_context_remaining"),
+		description:
+			"Estimate tokens left before Pi's automatic rollover and the configured context limit. Check before reporting remaining space or changing your work plan because of context limits. A checkpoint reminder already arrives before rollover; no routine checks are needed.",
+		promptSnippet:
+			"verify remaining context before reporting a token count or changing plans because of context limits",
+		parameters: Type.Object({}),
+		// Pi's fixed tool contract supplies id, params, signal, updates, and context.
+		// oxlint-disable-next-line max-params
+		async execute(_id, _params, _signal, _onUpdate, ctx) {
+			return contextReport(policy(ctx));
+		},
+	});
+}

package/src/contracts.ts

@@ -0,0 +1,124 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { PosthorseDisplay } from "../ui.ts";
+
+export type CompactionPolicy = {
+	readonly enabled: boolean;
+	readonly reserveTokens: number;
+};
+export type ContextUsage = {
+	readonly tokens: number | null;
+	readonly contextWindow: number;
+	readonly percent: number | null;
+};
+export type PolicyContext = {
+	readonly getCompactionSettings: () => CompactionPolicy;
+	readonly getContextUsage: () => ContextUsage | undefined;
+	readonly getSystemPrompt: () => string;
+};
+export type PolicyReader = (ctx: ExtensionContext) => CompactionPolicy;
+export type ImageLike = {
+	readonly type: "image";
+	readonly data: string;
+	readonly mimeType: string;
+};
+export type ToolCallLike = {
+	readonly type?: string;
+	readonly id?: string;
+	readonly name?: string;
+	readonly namespace?: string;
+	readonly arguments?: unknown;
+	readonly executionArguments?: unknown;
+	readonly async?: boolean;
+};
+export type MessageLike = {
+	readonly role?: string;
+	readonly stopReason?: string;
+	readonly errorMessage?: string;
+	readonly content?: unknown;
+	readonly summary?: string;
+	readonly toolName?: string;
+	readonly namespace?: string;
+	readonly toolCallId?: string;
+	readonly isError?: boolean;
+	readonly command?: string;
+	readonly output?: string;
+	readonly excludeFromContext?: boolean;
+};
+export type EntryLike = {
+	readonly type?: string;
+	readonly id?: string;
+	readonly parentId?: string | null;
+	readonly timestamp?: string;
+	readonly message?: MessageLike;
+	readonly summary?: string;
+	readonly customType?: string;
+	readonly content?: unknown;
+	readonly details?: unknown;
+	readonly display?: boolean;
+	readonly handoff?: string;
+	readonly firstKeptEntryId?: string | null;
+	readonly targetId?: string;
+	readonly replacement?: { readonly content: unknown } | null;
+};
+export type WindowedEntry = {
+	readonly entry: EntryLike;
+	readonly windowId: string;
+	readonly text: string;
+	readonly images: readonly ImageLike[];
+};
+export type ProjectedEntry = {
+	readonly sourceEntry: EntryLike;
+	readonly messages: readonly MessageLike[];
+};
+export type HistoryHit = {
+	readonly id: string;
+	readonly text: string;
+	readonly headerLength: number;
+	readonly priority: 0 | 1;
+};
+export type ReminderFingerprint = {
+	readonly windowId: string;
+	readonly contextWindow?: number;
+	readonly reserveTokens?: number;
+};
+export type TextResult = {
+	content: Array<
+		{ type: "text"; text: string } | { type: "image"; data: string; mimeType: string }
+	>;
+	details: PosthorseDisplay | undefined;
+};
+
+export const MAX_HANDOFF_CHARS = 20_000;
+export const MAX_PAGE_CHARS = 40_000;
+export const MIN_PAGE_CHARS = 1_000;
+export const PAGE_MARGIN_TOKENS = 1_000;
+export const ESTIMATED_IMAGE_CHARS = 4_800;
+export const REMINDER_TYPE = "posthorse-reminder";
+export const AUTO_HANDOFF_PREFIX = "Automatic context rollover recovery record.";
+export const EMPTY_HANDOFF = "Fresh context. Restore relevant notes and history before continuing.";
+
+export function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function unknownArray(value: unknown): readonly unknown[] | undefined {
+	return Array.isArray(value) ? value : undefined;
+}
+export function optionalString(value: unknown): string | undefined {
+	return typeof value === "string" ? value : undefined;
+}
+export function requireValue(value: string | undefined, name: string, op: string): string {
+	if (value === undefined || value === "") {
+		throw new Error(`"${name}" is required for op "${op}".`);
+	}
+	return value;
+}
+export function isReminderType(customType: unknown): boolean {
+	return customType === REMINDER_TYPE;
+}
+export function textResult(
+	text: string,
+	images: readonly ImageLike[] = [],
+	display?: PosthorseDisplay,
+): TextResult {
+	return { content: [{ type: "text", text }, ...images], details: display };
+}

package/src/files.ts

@@ -0,0 +1,182 @@
+import { randomUUID } from "node:crypto";
+import { createReadStream, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import {
+	access,
+	constants,
+	lstat,
+	open,
+	readFile,
+	readlink,
+	realpath,
+	rename,
+	stat,
+	unlink,
+} from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { isRecord } from "./contracts.ts";
+
+async function lstatOrMissing(path: string) {
+	try {
+		return await lstat(path);
+	} catch (error) {
+		if (isRecord(error) && error.code === "ENOENT") {
+			return;
+		}
+		throw error;
+	}
+}
+/** Resolve every link before normalization, preserving path traversal constraints. */
+export async function resolveFileTarget(absolutePath: string): Promise<string> {
+	let target = absolutePath;
+	const links = new Set<string>();
+	for (;;) {
+		if (target.endsWith(sep) || target.endsWith("/")) {
+			// Trailing separators require an existing directory, never a new regular file.
+			// Resolution follows dependent links in filesystem order.
+			// oxlint-disable-next-line no-await-in-loop
+			await stat(target);
+			return realpath(target);
+		}
+		const parentInput = dirname(target);
+		// stat enforces regular-file/.. traversal that macOS realpath alone accepts.
+		// oxlint-disable-next-line no-await-in-loop
+		if (!(await stat(parentInput)).isDirectory()) {
+			throw Object.assign(new Error(`Not a directory: ${parentInput}`), { code: "ENOTDIR" });
+		}
+		// Each parent must resolve before its child link can be examined.
+		// oxlint-disable-next-line no-await-in-loop
+		const parent = await realpath(parentInput);
+		target = join(parent, basename(target));
+		// Link targets cannot be known before examining the current link.
+		// oxlint-disable-next-line no-await-in-loop
+		const info = await lstatOrMissing(target);
+		if (info === undefined) {
+			return target;
+		}
+		if (!info.isSymbolicLink()) {
+			return realpath(target);
+		}
+		if (links.has(target)) {
+			throw Object.assign(new Error(`Symlink cycle: ${absolutePath}`), { code: "ELOOP" });
+		}
+		links.add(target);
+		// Preserve .. until the preceding directory symlink has been followed.
+		// oxlint-disable-next-line no-await-in-loop
+		const link = await readlink(target);
+		target = isAbsolute(link) ? link : `${parent}${sep}${link}`;
+	}
+}
+async function existingNote(target: string) {
+	const previous = await lstatOrMissing(target);
+	if (previous !== undefined && !previous.isFile()) {
+		throw Object.assign(new Error(`Cannot publish to a non-regular file: ${target}`), {
+			code: previous.isDirectory() ? "EISDIR" : "EINVAL",
+			path: target,
+		});
+	}
+	if (previous !== undefined) {
+		await access(target, constants.W_OK);
+	}
+	return previous;
+}
+/** Same-directory replacement; pre-rename failures preserve the old note and its metadata. */
+export async function publishFile(
+	path: string,
+	content: string,
+	signal?: AbortSignal,
+): Promise<void> {
+	signal?.throwIfAborted();
+	const target = await resolveFileTarget(path);
+	const previous = await existingNote(target);
+	const temporary = join(dirname(target), `.posthorse-${randomUUID()}.tmp`);
+	const file = await open(temporary, "wx", previous === undefined ? 0o666 : 0o600);
+	try {
+		await file.writeFile(content, { signal });
+		if (previous !== undefined) {
+			const staged = await file.stat();
+			if (staged.uid !== previous.uid || staged.gid !== previous.gid) {
+				await file.chown(previous.uid, previous.gid);
+			}
+			await file.chmod(previous.mode & 0o777);
+		}
+		await file.close();
+		signal?.throwIfAborted();
+		await rename(temporary, target);
+	} catch (error) {
+		await file.close().catch(() => {
+			/* Preserve the publication failure if closing also fails. */
+		});
+		await unlink(temporary).catch(() => {
+			/* Cleanup must not replace the original publication failure. */
+		});
+		throw error;
+	}
+}
+/** Split on LF only; Unicode line separators are valid inside JSONL strings and notes. */
+export async function* lfLines(file: string, signal?: AbortSignal): AsyncGenerator<string> {
+	const stream = createReadStream(file, { encoding: "utf8", signal });
+	let pending: string[] = [];
+	for await (const chunk of stream) {
+		if (typeof chunk !== "string") {
+			throw new Error("Expected a UTF-8 text stream.");
+		}
+		const lines = chunk.split("\n");
+		pending.push(lines[0] ?? "");
+		if (lines.length > 1) {
+			yield pending.join("");
+			yield* lines.slice(1, -1);
+			pending = [lines.at(-1) ?? ""];
+		}
+	}
+	const last = pending.join("");
+	if (last !== "") {
+		yield last;
+	}
+}
+/** Git's heuristic: a NUL in the first 8,000 bytes marks binary content. */
+export async function isBinaryFile(path: string): Promise<boolean> {
+	const file = await open(path, "r");
+	try {
+		const { buffer, bytesRead } = await file.read(Buffer.alloc(8_000), 0, 8_000, 0);
+		return buffer.subarray(0, bytesRead).includes(0);
+	} finally {
+		await file.close();
+	}
+}
+/** A whole file as UTF-8 text, or undefined when `isBinaryFile` would call it binary. */
+export async function readText(path: string, signal?: AbortSignal): Promise<string | undefined> {
+	const bytes = await readFile(path, { signal });
+	return bytes.subarray(0, 8_000).includes(0) ? undefined : bytes.toString("utf8");
+}
+function gitRoot(dir: string, marker: string): string {
+	let target = marker;
+	if (!statSync(marker).isDirectory()) {
+		const gitdir = readFileSync(marker, "utf8").match(/^gitdir:\s*(.+?)\s*$/m)?.[1];
+		if (gitdir === undefined || gitdir === "") {
+			return dir;
+		}
+		target = resolve(dir, gitdir);
+	}
+	target = realpathSync(target);
+	const commonFile = join(target, "commondir");
+	const common = realpathSync(
+		existsSync(commonFile) ? resolve(target, readFileSync(commonFile, "utf8").trim()) : target,
+	);
+	return basename(common) === ".git" ? dirname(common) : common;
+}
+/** Conventional repos share the primary checkout; separate Git directories own their shared root. */
+export function notesRoot(cwd: string): string {
+	for (let dir = cwd; ; dir = dirname(dir)) {
+		const marker = join(dir, ".git");
+		if (existsSync(marker)) {
+			try {
+				return gitRoot(dir, marker);
+			} catch {
+				return dir;
+			} // Orphaned worktrees retain local notes.
+		}
+		if (dirname(dir) === dir) {
+			return cwd;
+		}
+	}
+}