@gajae-code/coding-agent 0.18.1 → 0.18.6

package/src/exec/bash-shell-guardian.ts

@@ -1,6 +1,7 @@
 import { dlopen, FFIType, ptr } from "bun:ffi";
 import * as childProcess from "node:child_process";
 import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -63,10 +64,10 @@ export function extendOwnedDarwinAncestry<T extends { uniqueId: bigint; parentUn
 	return addedPids;
 }
 
-function authenticateOwnershipRecord(
+export function authenticateOwnershipRecord(
 	line: string,
 	ledgerToken: string,
-): { processRef?: NativeProcess; darwinUniqueId?: bigint } | undefined {
+): { processRef?: NativeProcess; darwinUniqueId?: bigint; pending?: true } | undefined {
 	const record = parseOwnershipRecord(line);
 	if (!record) return undefined;
 	const uniqueId = record.darwinUniqueId ?? "";
@@ -80,15 +81,20 @@ function authenticateOwnershipRecord(
 		return undefined;
 	}
 	if (received.byteLength !== expected.byteLength || !timingSafeEqual(received, expected)) return undefined;
-	if (process.platform === "darwin" && !record.darwinUniqueId) return undefined;
 	const { Process } = require("@gajae-code/natives") as NativeProcessBindings;
 	const owned = Process.fromPid(record.pid);
-	return {
-		...(owned?.incarnation === record.incarnation ? { processRef: owned } : {}),
-		...(record.darwinUniqueId ? { darwinUniqueId: BigInt(record.darwinUniqueId) } : {}),
-	};
+	const darwinUniqueId = record.darwinUniqueId ? { darwinUniqueId: BigInt(record.darwinUniqueId) } : {};
+	if (owned?.incarnation === record.incarnation) return { processRef: owned, ...darwinUniqueId };
+	// fromPid() conflates death with an inconclusive lookup. Only a confirmed
+	// absence or a different incarnation settles the record; an unknown result
+	// keeps it pending so the caller retries the line on the next scan.
+	if (!owned && Process.observe(record.pid).status === "unknown") return { pending: true, ...darwinUniqueId };
+	return darwinUniqueId;
 }
 
+/** Scans an inconclusive ledger record may stay pending before tracking fails closed. */
+const MAX_PENDING_LEDGER_ATTEMPTS = 50;
+
 function enableLinuxChildSubreaper(): boolean {
 	if (process.platform !== "linux") return true;
 	try {
@@ -157,14 +163,27 @@ function findDarwinLedgerHolders(device: number, inode: bigint): NativeProcess[]
 	}
 }
 
-type DarwinAncestryTracker = {
+export type DarwinAncestryTracker = {
 	seed(uniqueId: bigint): void;
 	track(processRef: NativeProcess, uniqueId?: bigint): boolean;
+	trackGuardian(processRef: NativeProcess, uniqueId?: bigint): boolean;
 	poll(): boolean;
 	close(): void;
 };
 
-function createDarwinAncestryTracker(owned: Map<string, NativeProcess>): DarwinAncestryTracker | undefined {
+export type DarwinIdentity = { uniqueId: bigint; parentUniqueId: bigint };
+
+/** Test seams for the Darwin tracker; production uses libproc and the natives binding. */
+export type DarwinAncestryTrackerDeps = {
+	uniqueIdentity?: (pid: number) => DarwinIdentity | undefined;
+	fromPid?: (pid: number) => NativeProcess | null | undefined;
+	observe?: (pid: number) => { status: "present" | "absent" | "unknown"; incarnation?: string };
+};
+
+export function createDarwinAncestryTracker(
+	owned: Map<string, NativeProcess>,
+	deps: DarwinAncestryTrackerDeps = {},
+): DarwinAncestryTracker | undefined {
 	if (process.platform !== "darwin") return undefined;
 	try {
 		const proc = dlopen("/usr/lib/libproc.dylib", {
@@ -180,10 +199,12 @@ function createDarwinAncestryTracker(owned: Map<string, NativeProcess>): DarwinA
 		// own children still chain, but it is retried on every poll until retained.
 		const retainedUniqueIds = new Set<bigint>();
 		const { Process } = require("@gajae-code/natives") as NativeProcessBindings;
+		const fromPid = deps.fromPid ?? ((pid: number) => Process.fromPid(pid));
+		const observe = deps.observe ?? ((pid: number) => Process.observe(pid));
 		// Reuse buffer across poll iterations to avoid allocations inside the loop.
 		const identityBuffer = new Uint8Array(56);
 		const identityView = new DataView(identityBuffer.buffer);
-		const uniqueIdentity = (pid: number): { uniqueId: bigint; parentUniqueId: bigint } | undefined => {
+		const defaultUniqueIdentity = (pid: number): { uniqueId: bigint; parentUniqueId: bigint } | undefined => {
 			const bytes = proc.symbols.proc_pidinfo(pid, 17, 0, ptr(identityBuffer), identityBuffer.byteLength);
 			if (bytes !== identityBuffer.byteLength) return undefined;
 			return {
@@ -191,9 +212,92 @@ function createDarwinAncestryTracker(owned: Map<string, NativeProcess>): DarwinA
 				parentUniqueId: identityView.getBigUint64(24, true),
 			};
 		};
+		const uniqueIdentity = deps.uniqueIdentity ?? defaultUniqueIdentity;
+		const incarnationOnlyAnchors: NativeProcess[] = [];
+		const anchorKeys = new Set<string>();
+		const addIncarnationOnlyAnchor = (processRef: NativeProcess): void => {
+			const key = `${processRef.pid}:${processRef.incarnation}`;
+			if (anchorKeys.has(key)) return;
+			anchorKeys.add(key);
+			incarnationOnlyAnchors.push(processRef);
+		};
+		// children() validates its parent and then snapshots the process table; the
+		// parent can exit and its pid be reused in between, returning a stranger's
+		// children. Only trust a snapshot if the parent still holds its incarnation
+		// after it was taken.
+		const childrenOf = (parent: NativeProcess): NativeProcess[] => {
+			const children = parent.children();
+			return fromPid(parent.pid)?.incarnation === parent.incarnation ? children : [];
+		};
+		const seedAnchorDescendants = (anchor: NativeProcess): void => {
+			const pending = [...childrenOf(anchor)];
+			while (pending.length > 0) {
+				const child = pending.pop()!;
+				retainOwnedProcess(owned, child);
+				// The unique id is read from a bare pid, so bracket it with incarnation
+				// checks against this handle: a pid reused in between would otherwise
+				// seed an unrelated process (and its descendants) as owned.
+				if (fromPid(child.pid)?.incarnation === child.incarnation) {
+					const childId = uniqueIdentity(child.pid)?.uniqueId;
+					if (fromPid(child.pid)?.incarnation === child.incarnation) {
+						if (childId !== undefined) {
+							knownUniqueIds.add(childId);
+							retainedUniqueIds.add(childId);
+						} else {
+							// Its flavor-17 query is denied too: without a unique id the
+							// ancestry walk can never reach its subtree, so it must outlive
+							// this anchor's pruning as an incarnation-only anchor itself.
+							addIncarnationOnlyAnchor(child);
+						}
+					}
+				}
+				pending.push(...childrenOf(child));
+			}
+		};
 		const track = (processRef: NativeProcess, signedUniqueId?: bigint): boolean => {
+			// The bare-pid unique-id query is only trusted if the same incarnation
+			// holds on both sides of it; otherwise a pid reused after the record was
+			// authenticated would seed the replacement's ancestry as owned.
+			let identity: { uniqueId: bigint; parentUniqueId: bigint } | undefined;
+			if (signedUniqueId === undefined) {
+				const queried = uniqueIdentity(processRef.pid);
+				const after = observe(processRef.pid);
+				if (
+					after.status === "absent" ||
+					(after.status === "present" && after.incarnation !== processRef.incarnation)
+				) {
+					// Confirmed exited or reused since authentication: retain nothing new.
+					return true;
+				}
+				// Present with the same incarnation keeps the queried id. An
+				// inconclusive lookup cannot vouch for it, so the record falls through
+				// as incarnation-only and is kept as an anchor rather than dropped.
+				identity = after.status === "present" ? queried : undefined;
+			}
+			const uniqueId = signedUniqueId ?? identity?.uniqueId;
+			if (uniqueId === undefined) {
+				// Incarnation-only record: the child has no unique id to anchor the
+				// ancestry graph. Keep it as an anchor whose live descendants poll()
+				// seeds by unique id, so their subtrees stay tracked after the child
+				// exits and they reparent (PPID discovery alone would lose them).
+				// Residual gap (accepted over #6085's exit 70): if the child forks a
+				// descendant that leaves the supervisor process group, then exits before
+				// this record is scanned, nothing links that descendant back to us. The
+				// ledger watcher scans on append to keep that window minimal.
+				retainOwnedProcess(owned, processRef);
+				addIncarnationOnlyAnchor(processRef);
+				seedAnchorDescendants(processRef);
+				return true;
+			}
+			knownUniqueIds.add(uniqueId);
+			retainedUniqueIds.add(uniqueId);
+			retainOwnedProcess(owned, processRef);
+			return true;
+		};
+		const trackGuardian = (processRef: NativeProcess, signedUniqueId?: bigint): boolean => {
 			const identity = signedUniqueId === undefined ? uniqueIdentity(processRef.pid) : undefined;
 			const uniqueId = signedUniqueId ?? identity?.uniqueId;
+			// Guardian registration is strict: must have a unique id
 			if (uniqueId === undefined) return false;
 			knownUniqueIds.add(uniqueId);
 			retainedUniqueIds.add(uniqueId);
@@ -205,7 +309,19 @@ function createDarwinAncestryTracker(owned: Map<string, NativeProcess>): DarwinA
 				knownUniqueIds.add(uniqueId);
 			},
 			track,
+			trackGuardian,
 			poll() {
+				// Re-seed live anchors, then drop exited ones: their descendants were
+				// seeded by unique id while the anchor was alive, and ancestry now
+				// carries them, so re-walking a dead anchor only costs time.
+				for (let index = incarnationOnlyAnchors.length - 1; index >= 0; index--) {
+					const anchor = incarnationOnlyAnchors[index]!;
+					seedAnchorDescendants(anchor);
+					if (fromPid(anchor.pid)?.incarnation !== anchor.incarnation) {
+						incarnationOnlyAnchors.splice(index, 1);
+						anchorKeys.delete(`${anchor.pid}:${anchor.incarnation}`);
+					}
+				}
 				const capacity = proc.symbols.proc_listallpids(null, 0);
 				if (capacity <= 0) return false;
 				const pids = new Int32Array(capacity + 64);
@@ -225,10 +341,10 @@ function createDarwinAncestryTracker(owned: Map<string, NativeProcess>): DarwinA
 				extendOwnedDarwinAncestry(knownUniqueIds, identities);
 				for (const [pid, listed] of identities) {
 					if (!knownUniqueIds.has(listed.uniqueId) || retainedUniqueIds.has(listed.uniqueId)) continue;
-					const before = Process.fromPid(pid);
+					const before = fromPid(pid);
 					if (!before) continue;
 					const identity = uniqueIdentity(pid);
-					const after = Process.fromPid(pid);
+					const after = fromPid(pid);
 					if (identity?.uniqueId === listed.uniqueId && after?.incarnation === before.incarnation) {
 						retainOwnedProcess(owned, after);
 						retainedUniqueIds.add(listed.uniqueId);
@@ -275,7 +391,7 @@ export async function runBashShellGuardian(): Promise<void> {
 	if (darwinTracker) {
 		const { Process } = require("@gajae-code/natives") as NativeProcessBindings;
 		const guardian = Process.fromPid(process.pid);
-		if (!guardian || !darwinTracker.track(guardian)) {
+		if (!guardian || !darwinTracker.trackGuardian(guardian)) {
 			darwinTracker.close();
 			await ledger.close();
 			await fs.rm(ownershipFilePath, { force: true });
@@ -306,6 +422,8 @@ export async function runBashShellGuardian(): Promise<void> {
 	input.once("close", () => supervisor.stdin.end());
 	let cleaning: Promise<void> | undefined;
 	let ledgerBuffer = "";
+	let pendingLedgerLines: string[] = [];
+	const pendingAttempts = new Map<string, number>();
 	let ownershipScan = Promise.resolve(true);
 	const scanOwnership = (): Promise<boolean> => {
 		ownershipScan = ownershipScan.then(async previousOk => {
@@ -317,11 +435,23 @@ export async function runBashShellGuardian(): Promise<void> {
 				return false;
 			}
 			ledgerBuffer += content;
-			const lines = ledgerBuffer.split("\n");
-			ledgerBuffer = lines.pop() ?? "";
+			const fresh = ledgerBuffer.split("\n");
+			ledgerBuffer = fresh.pop() ?? "";
+			const lines = [...pendingLedgerLines, ...fresh];
+			pendingLedgerLines = [];
 			for (const line of lines) {
 				if (!line) continue;
 				const owned = authenticateOwnershipRecord(line, ledgerToken);
+				if (owned?.pending) {
+					// Inconclusive lookup: retry next scan, bounded so a pid stuck in an
+					// unknown state cannot grow the queue or starve cleanup forever.
+					const attempts = (pendingAttempts.get(line) ?? 0) + 1;
+					if (attempts > MAX_PENDING_LEDGER_ATTEMPTS) return false;
+					pendingAttempts.set(line, attempts);
+					pendingLedgerLines.push(line);
+				} else {
+					pendingAttempts.delete(line);
+				}
 				if (owned?.darwinUniqueId && darwinTracker) darwinTracker.seed(owned.darwinUniqueId);
 				if (owned?.processRef && darwinTracker && !darwinTracker.track(owned.processRef, owned.darwinUniqueId))
 					return false;
@@ -335,28 +465,48 @@ export async function runBashShellGuardian(): Promise<void> {
 		return ownershipScan;
 	};
 	let periodicScanActive = false;
-	const ownershipScanTimer = darwinTracker
-		? setInterval(() => {
-				if (periodicScanActive) return;
-				periodicScanActive = true;
-				void scanOwnership()
-					.then(ok => {
-						if (ok || supervisor.exitCode !== null || supervisor.signalCode !== null) return;
-						if (supervisor.pid) {
-							try {
-								process.kill(-supervisor.pid, "SIGKILL");
-							} catch {}
-						}
-						supervisor.kill("SIGKILL");
-					})
-					.finally(() => {
-						periodicScanActive = false;
-					});
-			}, 100)
-		: undefined;
+	let periodicScanRequested = false;
+	const runPeriodicScan = (): void => {
+		if (periodicScanActive) {
+			periodicScanRequested = true;
+			return;
+		}
+		periodicScanActive = true;
+		void scanOwnership()
+			.then(ok => {
+				if (ok || supervisor.exitCode !== null || supervisor.signalCode !== null) return;
+				if (supervisor.pid) {
+					try {
+						process.kill(-supervisor.pid, "SIGKILL");
+					} catch {}
+				}
+				supervisor.kill("SIGKILL");
+			})
+			.finally(() => {
+				periodicScanActive = false;
+				if (periodicScanRequested && !cleaning) {
+					periodicScanRequested = false;
+					runPeriodicScan();
+				}
+			});
+	};
+	const ownershipScanTimer = darwinTracker ? setInterval(runPeriodicScan, 100) : undefined;
+	// Scan as soon as the supervisor appends a ledger record instead of waiting
+	// for the next tick. An incarnation-only record's descendants are only
+	// reachable while that child is alive, so the anchor must be taken promptly.
+	let ledgerWatcher: fsSync.FSWatcher | undefined;
+	if (darwinTracker) {
+		try {
+			ledgerWatcher = fsSync.watch(ownershipFilePath, runPeriodicScan);
+			ledgerWatcher.on("error", () => {});
+		} catch {
+			ledgerWatcher = undefined;
+		}
+	}
 	const cleanup = (): Promise<void> => {
 		cleaning ??= (async () => {
 			if (ownershipScanTimer) clearInterval(ownershipScanTimer);
+			ledgerWatcher?.close();
 			let trackingOk = await scanOwnership();
 			if (supervisor.exitCode === null && supervisor.signalCode === null) {
 				if (process.platform !== "win32" && supervisor.pid) {

package/src/exec/bash-shell-supervisor.ts

@@ -1,6 +1,7 @@
 import { dlopen, FFIType, ptr } from "bun:ffi";
 import * as childProcess from "node:child_process";
 import { createHmac } from "node:crypto";
+import type { EventEmitter } from "node:events";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -121,6 +122,63 @@ async function reapLinuxAdoptedZombies(excludedPid: number | undefined): Promise
 	}
 }
 
+/**
+ * Reap adopted zombies only when the kernel reports a child state change.
+ *
+ * As the Linux child subreaper, the supervisor inherits orphaned descendants
+ * and must reap them, but a full `/proc` sweep is expensive. Polling it on a
+ * short interval kept every idle supervisor busy (issue #5972), so sweeps are
+ * driven by SIGCHLD instead. At most one sweep runs at a time, and a SIGCHLD that
+ * arrives mid-sweep schedules exactly one follow-up so a zombie created after
+ * its `/proc` entry was passed is never missed. Returns the unsubscribe hook.
+ */
+export function startLinuxAdoptedZombieReaper(
+	excludedPid: number | undefined,
+	reap: (excludedPid: number | undefined) => Promise<void> = reapLinuxAdoptedZombies,
+	signals: Pick<EventEmitter, "on" | "off"> = process,
+): () => void {
+	if (process.platform !== "linux") return () => undefined;
+	let running = false;
+	let rerun = false;
+	let stopped = false;
+	let sweepPending = false;
+	const sweep = (): void => {
+		if (stopped) return;
+		if (running) {
+			rerun = true;
+			return;
+		}
+		if (sweepPending) return;
+		sweepPending = true;
+		running = true;
+		void reap(excludedPid)
+			.catch(() => undefined)
+			.finally(() => {
+				running = false;
+				sweepPending = false;
+				if (!rerun || stopped) return;
+				rerun = false;
+				// Defer recursive call to avoid stack overflow
+				setImmediate(() => {
+					if (!stopped && !running) sweep();
+				});
+			});
+	};
+	try {
+		signals.on("SIGCHLD", sweep);
+	} catch {
+		// Signal handler installation may fail in some environments
+	}
+	return () => {
+		stopped = true;
+		try {
+			signals.off("SIGCHLD", sweep);
+		} catch {
+			// Signal handler removal may fail in some environments
+		}
+	};
+}
+
 function signalFromExit(code: number | null, signal: NodeJS.Signals | null): NodeJS.Signals | null {
 	if (signal) return signal;
 	if (code === null || code <= 128) return null;
@@ -210,8 +268,7 @@ export async function runBashShellSupervisor(): Promise<void> {
 		stdio: ["pipe", "pipe", "pipe"],
 		windowsHide: true,
 	});
-	const zombieReaper = setInterval(() => void reapLinuxAdoptedZombies(worker.pid), 25);
-	zombieReaper.unref();
+	const stopZombieReaper = startLinuxAdoptedZombieReaper(worker.pid);
 	const pendingRuns: number[] = [];
 	let terminating = false;
 	let protocolToken: string | undefined;
@@ -315,7 +372,7 @@ export async function runBashShellSupervisor(): Promise<void> {
 		);
 	});
 	worker.once("exit", async (code, signal) => {
-		clearInterval(zombieReaper);
+		stopZombieReaper();
 		const resultSignal = signalFromExit(code, signal);
 		if (code === 0 && resultSignal === null) {
 			await reapLinuxSubreaperChildren();

package/src/hashline/execute.ts

@@ -11,12 +11,12 @@ import { assertEditableFileContent } from "../tools/auto-generated-guard";
 import { invalidateFsScanAfterWrite } from "../tools/fs-cache-invalidation";
 import { outputMeta } from "../tools/output-meta";
 import { enforcePlanModeWrite, resolvePlanPath } from "../tools/plan-mode-guard";
-import { HashlineMismatchError } from "./anchors";
+import { formatFullAnchorRequirement, HashlineMismatchError } from "./anchors";
 import { applyHashlineEdits, type HashlineApplyResult } from "./apply";
 import { buildCompactHashlineDiffPreview } from "./diff-preview";
 import { computeLineHash, HL_BODY_SEP } from "./hash";
 import { type HashlineInputSection, splitHashlineInputs } from "./input";
-import { HashlineMissingHashError, parseHashlineWithWarnings } from "./parser";
+import { HashlineMissingHashError, HashlineMissingLineError, parseHashlineWithWarnings } from "./parser";
 import { tryRecoverHashlineWithCache } from "./recovery";
 import type {
 	ExecuteHashlineSingleOptions,
@@ -88,6 +88,17 @@ function formatMissingHashAnchors(fileLines: string[], start: number, end: numbe
 	return [...head, "...", format(end)];
 }
 
+function formatMissingHashRetryHeader(
+	fileLines: string[],
+	start: number,
+	end: number,
+	opSigil: HashlineMissingHashError["opSigil"],
+): string {
+	const format = (line: number): string => `${line}${computeLineHash(line, fileLines[line - 1] ?? "")}`;
+	const anchorRange = start === end ? format(start) : `${format(start)}..${format(end)}`;
+	return `${opSigil}${anchorRange}`;
+}
+
 /**
  * Parse an edit section. When an op names lines by number only, answer with
  * the current full anchors for those lines so the model can retry without
@@ -101,7 +112,43 @@ async function parseHashlineSection(
 	try {
 		return parseHashlineWithWarnings(diff);
 	} catch (err) {
+		if (err instanceof HashlineMissingLineError) {
+			// When part of a range has a missing hash, suppress the "Did you mean" suggestion
+			// and require the full range to be re-supplied.
+			if (err.rangeRaw) {
+				throw new Error(
+					`Anchor "${err.hash}" lacks its line number. The range ${err.rangeRaw.start}..${err.rangeRaw.end} is incomplete. ` +
+						`Expected ${formatFullAnchorRequirement(err.hash)} Re-read the target to get the full range. ` +
+						`The edit was NOT applied.`,
+				);
+			}
+			const source = await readHashlineFile(absolutePath, pathText);
+			const fileLines = source.exists ? normalizeToLF(stripBom(source.rawContent).text).split("\n") : [];
+			let matchCount = 0;
+			let matchLine: number | undefined;
+			for (let index = 0; index < fileLines.length; index++) {
+				if (computeLineHash(index + 1, fileLines[index] ?? "") !== err.hash) continue;
+				matchCount++;
+				matchLine = index + 1;
+			}
+			if (matchCount === 1 && matchLine !== undefined) {
+				const suggestion = new HashlineMissingLineError(err.hash, matchLine, err.opSigil);
+				throw new Error(`${suggestion.message} The edit was NOT applied.`);
+			}
+			throw new Error(
+				`${err.message} Expected ${formatFullAnchorRequirement(err.hash)} ` +
+					`The hash matches ${matchCount} lines; re-read the target. The edit was NOT applied.`,
+			);
+		}
 		if (!(err instanceof HashlineMissingHashError)) throw err;
+		// When part of a range has a missing hash, suppress the copy-ready suggestion
+		// and require re-reading to get the full range.
+		if (err.rangeRaw) {
+			throw new Error(
+				`${err.message} The anchors are missing from the range ${err.rangeRaw.start}..${err.rangeRaw.end}. ` +
+					`Re-read the target to get the full range with hashes. The edit was NOT applied.`,
+			);
+		}
 		const source = await readHashlineFile(absolutePath, pathText);
 		if (!source.exists) throw err;
 		const fileLines = normalizeToLF(stripBom(source.rawContent).text).split("\n");
@@ -112,8 +159,9 @@ async function parseHashlineSection(
 			);
 		}
 		const anchors = formatMissingHashAnchors(fileLines, start, end);
+		const retryHeader = formatMissingHashRetryHeader(fileLines, start, end, err.opSigil);
 		throw new Error(
-			`${err.message}\nThe edit was NOT applied. Current anchors for ${pathText}:\n${anchors.join("\n")}`,
+			`${err.message}\nUse ${retryHeader}\nThe edit was NOT applied. Current anchors for ${pathText}:\n${anchors.join("\n")}`,
 		);
 	}
 }

package/src/hashline/parser.ts

@@ -20,35 +20,59 @@ import type { Anchor, HashlineCursor, HashlineEdit } from "./types";
 const LID_CAPTURE_RE = new RegExp(`^\\s*[>+\\-*]*\\s*${HL_HASH_CAPTURE_RE_RAW}(?:\\|.*)?\\s*$`);
 const regexEscape = (str: string): string => str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
-const BARE_LINE_REF_RE = /^\s*[>+\-*]*\s*([1-9]\d*)(?:\s*(?:-|\.\.)\s*([1-9]\d*))?\s*$/;
+// Dots in copied text are literal unless followed by a possible range endpoint.
+// Ambiguous copied ranges still require a re-read instead of a one-line retry.
+const BARE_LINE_REF_RE =
+	/^\s*[>+\-*]*\s*([1-9]\d*)(?:\s*(?:-|\.\.)\s*([1-9]\d*))?(?:\|(?:(?!\.\.\s*[>+\-*]*\s*(?:[1-9]\d*|[a-z]{2}(?:\||\s*$))).)*)?\s*$/;
+const HASH_ONLY_REF_RE = /^\s*[>+\-*]*\s*([a-z]{2})(?:\|.*)?\s*$/;
+type HashlineOpSigil = typeof HL_OP_INSERT_BEFORE | typeof HL_OP_INSERT_AFTER | typeof HL_OP_REPLACE;
 
 /**
- * An op referenced lines by number alone, without the content hash. The edit
- * is never applied on a line number alone; the executor answers with the
- * current full anchors for {@link lines} so the model can retry without an
- * extra read.
+ * An op referenced lines by number alone. The edit is never applied on a line
+ * number alone; the executor answers with the current full anchors so the model
+ * can retry without another read.
  */
 export class HashlineMissingHashError extends Error {
 	constructor(
 		message: string,
 		readonly lines: { start: number; end: number },
+		readonly opSigil: HashlineOpSigil,
+		readonly rangeRaw?: { start: string; end: string },
 	) {
 		super(message);
 		this.name = "HashlineMissingHashError";
 	}
 }
 
-function parseLid(raw: string, lineNum: number): Anchor {
+export class HashlineMissingLineError extends Error {
+	constructor(
+		readonly hash: string,
+		readonly lineNum: number | undefined,
+		readonly opSigil: HashlineOpSigil,
+		readonly rangeRaw?: { start: string; end: string },
+	) {
+		super(
+			lineNum === undefined
+				? `Anchor "${hash}" lacks its line number.`
+				: `Anchor "${hash}" lacks its line number. Did you mean ${opSigil}${lineNum}${hash}?`,
+		);
+		this.name = "HashlineMissingLineError";
+	}
+}
+
+function parseLid(raw: string, lineNum: number, opSigil: HashlineOpSigil): Anchor {
 	const match = LID_CAPTURE_RE.exec(raw);
 	if (!match) {
+		const hashOnly = HASH_ONLY_REF_RE.exec(raw);
+		if (hashOnly) throw new HashlineMissingLineError(hashOnly[1], undefined, opSigil);
 		const bare = BARE_LINE_REF_RE.exec(raw);
 		if (bare) {
 			const start = Number.parseInt(bare[1], 10);
 			const end = bare[2] === undefined ? start : Number.parseInt(bare[2], 10);
 			throw new HashlineMissingHashError(
-				`line ${lineNum}: anchor ${JSON.stringify(raw.trim())} is missing its hash; ` +
-					`use the full anchor such as ${describeAnchorExamples(String(start))}.`,
+				`line ${lineNum}: anchor ${JSON.stringify(raw.trim())} is missing its hash.`,
 				{ start: Math.min(start, end), end: Math.max(start, end) },
+				opSigil,
 			);
 		}
 		throw new Error(
@@ -64,12 +88,12 @@ interface ParsedRange {
 	end: Anchor;
 }
 
-function parseRange(raw: string, lineNum: number): ParsedRange {
+function parseRange(raw: string, lineNum: number, opSigil: HashlineOpSigil): ParsedRange {
 	// Reject an all-numeric range (`16..18`, `16-18`) as a whole so the error
 	// carries the full span rather than just its first endpoint.
-	if (BARE_LINE_REF_RE.test(raw)) parseLid(raw, lineNum);
+	if (BARE_LINE_REF_RE.test(raw)) parseLid(raw, lineNum, opSigil);
 	if (!raw.includes("..")) {
-		const start = parseLid(raw, lineNum);
+		const start = parseLid(raw, lineNum, opSigil);
 		return { start, end: { ...start } };
 	}
 	const [startRaw, endRaw, extra] = raw.split("..");
@@ -79,8 +103,30 @@ function parseRange(raw: string, lineNum: number): ParsedRange {
 				`For a one-line edit, repeat the same anchor on both sides.`,
 		);
 	}
-	const start = parseLid(startRaw, lineNum);
-	const end = parseLid(endRaw, lineNum);
+	let start: Anchor;
+	try {
+		start = parseLid(startRaw, lineNum, opSigil);
+	} catch (err) {
+		if (err instanceof HashlineMissingHashError) {
+			throw new HashlineMissingHashError(err.message, err.lines, err.opSigil, { start: startRaw, end: endRaw });
+		}
+		if (err instanceof HashlineMissingLineError) {
+			throw new HashlineMissingLineError(err.hash, err.lineNum, err.opSigil, { start: startRaw, end: endRaw });
+		}
+		throw err;
+	}
+	let end: Anchor;
+	try {
+		end = parseLid(endRaw, lineNum, opSigil);
+	} catch (err) {
+		if (err instanceof HashlineMissingHashError) {
+			throw new HashlineMissingHashError(err.message, err.lines, err.opSigil, { start: startRaw, end: endRaw });
+		}
+		if (err instanceof HashlineMissingLineError) {
+			throw new HashlineMissingLineError(err.hash, err.lineNum, err.opSigil, { start: startRaw, end: endRaw });
+		}
+		throw err;
+	}
 	if (end.line < start.line) {
 		throw new Error(`line ${lineNum}: range ${startRaw}..${endRaw} ends before it starts.`);
 	}
@@ -104,7 +150,8 @@ function parseInsertTarget(raw: string, lineNum: number, kind: "before" | "after
 	if (raw === "BOF") return { kind: "bof" };
 	if (raw === "EOF") return { kind: "eof" };
 	const cursorKind = kind === "before" ? "before_anchor" : "after_anchor";
-	return { kind: cursorKind, anchor: parseLid(raw, lineNum) };
+	const opSigil = kind === "before" ? HL_OP_INSERT_BEFORE : HL_OP_INSERT_AFTER;
+	return { kind: cursorKind, anchor: parseLid(raw, lineNum, opSigil) };
 }
 
 /**
@@ -137,7 +184,7 @@ const INSERT_BEFORE_OP_RE = new RegExp(
 const INSERT_AFTER_OP_RE = new RegExp(
 	`^${regexEscape(HL_OP_INSERT_AFTER)}\\s*([^|\\s]+)(?:${HL_BODY_SEP_RE_RAW}(.*))?\\s*$`,
 );
-const REPLACE_OP_RE = new RegExp(`^${regexEscape(HL_OP_REPLACE)}\\s*([^\\s+<\\-=]\\S*)\\s*$`);
+const REPLACE_OP_RE = new RegExp(`^${regexEscape(HL_OP_REPLACE)}\\s*([^\\s+<\\-=]\\S*(?:\\|.*)?)\\s*$`);
 
 function isEnvelopeOrAbortMarkerLine(line: string): boolean {
 	const trimmed = line.trimEnd();
@@ -240,7 +287,7 @@ export function parseHashlineWithWarnings(diff: string): { edits: HashlineEdit[]
 
 		const replaceMatch = REPLACE_OP_RE.exec(line);
 		if (replaceMatch) {
-			const range = parseRange(replaceMatch[1], lineNum);
+			const range = parseRange(replaceMatch[1], lineNum, HL_OP_REPLACE);
 			const { payload, nextIndex } = collectPayload(lines, i + 1, lineNum, false);
 			if (payload.length > 0) {
 				for (const text of payload) {