@oh-my-pi/hashline 15.9.3 → 15.9.67

package/README.md

@@ -23,10 +23,10 @@ const snapshots = new InMemorySnapshotStore();
 const before = `const greeting = "hi";\nexport { greeting };\n`;
 await fs.writeText("hello.ts", before);
 
-const tag = snapshots.recordContiguous("hello.ts", 1, before.split("\n"), { fullText: before });
+const tag = snapshots.record("hello.ts", before);
 const patcher = new Patcher({ fs, snapshots });
-const patch = Patch.parse(String.raw`¶hello.ts#${tag}
-@@ 1..1 @@
+const patch = Patch.parse(String.raw`[hello.ts#${tag}]
+replace 1..1:
 +const greeting = "hello";`);
 const result = await patcher.apply(patch);
 
@@ -39,19 +39,19 @@ console.log(await fs.readText("hello.ts"));
 See [`src/prompt.md`](./src/prompt.md) for the user-facing description and
 [`src/grammar.lark`](./src/grammar.lark) for the formal grammar.
 
-Each file section starts with `¶PATH#TAG`. The tag is a 3-hex opaque
-pointer into the `SnapshotStore` that minted it; it is not content-derived
-and is not meaningful outside that store. The patcher protects against
-stale anchors by resolving the tag, verifying the recorded snapshot lines
-against live file content, and refusing or attempting session-aware
-recovery on mismatch.
+Each file section starts with `[PATH#TAG]`. The tag is a 4-hex
+content hash of the full normalized file text recorded by the
+`SnapshotStore`, and it is not meaningful outside that store. The patcher
+protects against stale anchors by resolving the tag, verifying the live file
+still matches the recorded content hash, and refusing or attempting
+session-aware recovery on mismatch.
 
 Inside a section:
-- `@@ A..B @@` — open a hunk on lines A..B (use `@@ A,A @@` for a single line; bare `@@ A @@` is also accepted).
-- `@@ BOF @@` / `@@ EOF @@` — virtual hunks at the beginning/end of file.
+- `replace A..B:` — replace lines A..B with following `+TEXT` body rows.
+- `replace block A:` — replace the syntactic block beginning on line A.
+- `delete A..B` / `delete block A` — delete concrete lines or a resolved block.
+- `insert before A:` / `insert after A:` / `insert head:` / `insert tail:` — insert following body rows.
 - `+TEXT` — literal body row (use `+` alone for a blank line).
-- `&A..B` — repeat original file lines A..B inline (`&A` for one line).
-- Empty body — delete the selected range.
 
 ## Abstractions
 
@@ -67,9 +67,10 @@ text-document protocol, a Git tree, anything.
 
 ### `SnapshotStore`
 
-Required. Hashline tags are opaque store pointers, so `Patcher` must receive
-the store that minted them. Recovery replays edits against the cached pre-edit
-snapshot and 3-way-merges onto current content when the live file diverged.
+Required. Hashline tags are full-file content hashes recorded per path, so
+`Patcher` must receive the store that observed them. Recovery replays edits
+against the cached pre-edit snapshot and 3-way-merges onto current content
+when the live file diverged.
 
 ### `Patcher`
 

package/dist/types/format.d.ts

@@ -4,8 +4,9 @@
  * tokenizer, the prompt, and the formal grammar.
  */
 import type { Cursor } from "./types";
-/** File-section header prefix: `¶path#hash`. */
-export declare const HL_FILE_PREFIX = "\u00B6";
+/** File-section header delimiters: `[path#hash]`. */
+export declare const HL_FILE_PREFIX = "[";
+export declare const HL_FILE_SUFFIX = "]";
 /** Payload sigil for literal body rows. */
 export declare const HL_PAYLOAD_REPLACE = "+";
 /** Hunk-header keyword for concrete line replacement. */

package/dist/types/input.d.ts

@@ -69,7 +69,7 @@ export declare class PatchSection {
 }
 /**
  * A parsed hashline patch — zero or more {@link PatchSection}s, each rooted
- * at a `¶PATH#HASH` header. Construct via {@link Patch.parse}.
+ * at a `[PATH#HASH]` header. Construct via {@link Patch.parse}.
  *
  * `Patch` is pure data: parsing is line-anchored and does not look at the
  * filesystem. To apply a patch, hand it to {@link Patcher.apply}.

package/dist/types/patcher.d.ts

@@ -32,9 +32,9 @@ export interface PatchSectionResult {
     persisted: string;
     /** Final text that the {@link Filesystem} actually wrote (may differ if the FS transformed it). */
     written: string;
-    /** 3-hex opaque snapshot tag for `after`. Use to anchor follow-up edits. */
+    /** 4-hex content-hash tag for `after`. Use to anchor follow-up edits. */
     fileHash: string;
-    /** Hashline section header (`¶path#tag`) of the post-edit content. */
+    /** Hashline section header (`[path#tag]`) of the post-edit content. */
     header: string;
     /** 1-indexed first changed line in `after`, or `undefined` for noops. */
     firstChangedLine?: number;

package/dist/types/types.d.ts

@@ -75,7 +75,7 @@ export interface SplitOptions {
     /** Resolves absolute paths inside hashline headers to cwd-relative form. */
     cwd?: string;
     /**
-     * Fallback path used when the input lacks a `¶PATH` header but contains
+     * Fallback path used when the input lacks a `[PATH]` header but contains
      * recognizable hashline operations. Lets streaming previews work before
      * the model has written the header.
      */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/hashline",
-	"version": "15.9.3",
+	"version": "15.9.67",
 	"description": "Hashline: a compact, line-anchored patch language and applier. Pluggable FS/IO so it works over disk, in-memory, or any custom backend.",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",

package/src/format.ts

@@ -6,8 +6,9 @@
 
 import type { Cursor } from "./types";
 
-/** File-section header prefix: `¶path#hash`. */
-export const HL_FILE_PREFIX = "¶";
+/** File-section header delimiters: `[path#hash]`. */
+export const HL_FILE_PREFIX = "[";
+export const HL_FILE_SUFFIX = "]";
 
 /** Payload sigil for literal body rows. */
 export const HL_PAYLOAD_REPLACE = "+";
@@ -118,7 +119,7 @@ export function describeAnchorExamples(linePrefix = ""): string {
 
 /** Format a hashline section header for a file path and snapshot tag. */
 export function formatHashlineHeader(filePath: string, fileHash: string): string {
-	return `${HL_FILE_PREFIX}${filePath}${HL_FILE_HASH_SEP}${fileHash}`;
+	return `${HL_FILE_PREFIX}${filePath}${HL_FILE_HASH_SEP}${fileHash}${HL_FILE_SUFFIX}`;
 }
 
 /** Formats a single numbered line as `LINE:TEXT`. */

package/src/grammar.lark

@@ -3,9 +3,9 @@ begin_patch: "*** Begin Patch" LF
 end_patch:   "*** End Patch" LF?
 
 file_patch: file_header hunk+
-file_header: "¶" filename "#" file_hash LF
+file_header: "[" filename "#" file_hash "]" LF
 file_hash: /[0-9A-F]{4}/
-filename: /[^\s#]+/
+filename: /[^#\r\n]+/
 
 hunk: replace_hunk | replace_block_hunk | insert_hunk | delete_hunk | delete_block_hunk
 replace_hunk: replace_anchor LF emit_op*

package/src/input.ts

@@ -1,6 +1,6 @@
 /**
  * Top-level patch parser. Splits an authored hashline input into a list of
- * {@link PatchSection}s, each rooted at a `¶PATH#HASH` header, then exposes
+ * {@link PatchSection}s, each rooted at a `[PATH#HASH]` header, then exposes
  * a {@link Patch} class that gives lazy access to the parsed edits per
  * section.
  *
@@ -10,7 +10,7 @@
 import * as path from "node:path";
 import { applyEdits } from "./apply";
 import { resolveBlockEdits } from "./block";
-import { HL_FILE_HASH_LENGTH, HL_FILE_HASH_SEP, HL_FILE_PREFIX } from "./format";
+import { HL_FILE_HASH_EXAMPLES, HL_FILE_HASH_LENGTH, HL_FILE_HASH_SEP, HL_FILE_PREFIX, HL_FILE_SUFFIX } from "./format";
 import { parsePatch, parsePatchStreaming } from "./parser";
 import { Tokenizer } from "./tokenizer";
 import type { ApplyResult, BlockResolver, Edit, SplitOptions } from "./types";
@@ -47,21 +47,41 @@ function stripApplyPatchPathNoise(pathText: string): string {
 }
 
 /**
- * Best-effort recovery for `¶`-prefixed lines the strict tokenizer
+ * Best-effort recovery for bracketed header lines the strict tokenizer
  * rejects. Strips apply_patch keyword noise (`Update File:`, `Update:`,
- * etc.) and an extra leading `***` (some models emit a hybrid `¶***foo.ts`
- * shape), then expects `PATH(#HASH)?` with no embedded whitespace.
+ * etc.) and an extra leading `***` (some models emit a hybrid
+ * `[***foo.ts#HASH]` shape), then expects `PATH(#HASH)?`.
  * Returns `null` when no clean path can be salvaged.
  */
 function tryParseRecoveryHeader(line: string, cwd?: string): RawSection | null {
-	if (!line.startsWith(HL_FILE_PREFIX)) return null;
-	const body = stripApplyPatchPathNoise(line.slice(HL_FILE_PREFIX.length).trim());
+	if (!line.startsWith(HL_FILE_PREFIX) || !line.endsWith(HL_FILE_SUFFIX)) return null;
+	const body = stripApplyPatchPathNoise(line.slice(HL_FILE_PREFIX.length, line.length - HL_FILE_SUFFIX.length).trim());
 	if (body.length === 0) return null;
-	const match = new RegExp(`^(\\S+?)(?:#([0-9A-Fa-f]{${HL_FILE_HASH_LENGTH}}))?\\s*$`).exec(body);
-	if (match === null) return null;
-	const path = normalizeHashlinePath(match[1], cwd);
+
+	// Trailing `#XXXX` is the tag; everything before it is the path. The
+	// path may contain whitespace (Windows OneDrive folders, Program Files,
+	// etc.), so we anchor the tag at end-of-body rather than scanning
+	// forward and stopping at the first space.
+	const trailing = new RegExp(`#([0-9A-Fa-f]{${HL_FILE_HASH_LENGTH}})\\s*$`).exec(body);
+	let pathText: string;
+	let fileHash: string | undefined;
+	if (trailing !== null) {
+		pathText = body.slice(0, trailing.index);
+		fileHash = trailing[1].toUpperCase();
+	} else {
+		pathText = body.replace(/\s+$/, "");
+	}
+
+	// Same rule as the strict tokenizer: the hashline header grammar uses
+	// `#` as the path/tag separator and does not allow `#` inside
+	// filenames. Anything `#` left in the path body — short tags, non-hex
+	// tags, over-long tags, stale-tag copy-paste, line-suffixed tags —
+	// means the header is malformed, not a path with an embedded hash.
+	if (pathText.includes("#")) return null;
+
+	const path = normalizeHashlinePath(pathText, cwd);
 	if (path.length === 0) return null;
-	return match[2] !== undefined ? { path, fileHash: match[2].toUpperCase(), diff: "" } : { path, diff: "" };
+	return fileHash !== undefined ? { path, fileHash, diff: "" } : { path, diff: "" };
 }
 
 function normalizeHashlinePath(rawPath: string, cwd?: string): string {
@@ -79,9 +99,9 @@ interface RawSection {
 }
 
 /**
- * Parse a `¶PATH[#hash]` header line. Returns `null` for lines that do
- * not start with `¶`. Throws the strict "Input header must be …" error
- * when a `¶`-prefixed line fails the strict shape (so malformed paths
+ * Parse a `[PATH]` or `[PATH#hash]` header line. Returns `null` for lines that do
+ * not start with `[`. Throws the strict "Input header must be …" error
+ * when a bracketed line fails the strict shape (so malformed paths
  * surface immediately instead of being silently re-classified as payload).
  */
 function parseHashlineHeaderLine(line: string, cwd?: string): RawSection | null {
@@ -91,18 +111,18 @@ function parseHashlineHeaderLine(line: string, cwd?: string): RawSection | null
 	const token = TOKENIZER.tokenize(trimmed);
 	if (token.kind !== "header") {
 		// Recovery: try to extract a path from the raw line after stripping
-		// apply_patch noise. This handles `*** Update File:foo.ts#CB5` and
+		// apply_patch noise. This handles `[*** Update File:foo.ts#CB5A]` and
 		// the half-dozen variants models actually emit.
 		const recovered = tryParseRecoveryHeader(trimmed, cwd);
 		if (recovered !== null) return recovered;
 		throw new Error(
-			`Input header must be ${HL_FILE_PREFIX}PATH or ${HL_FILE_PREFIX}PATH${HL_FILE_HASH_SEP}TAG with a ${HL_FILE_HASH_LENGTH}-hex content-hash tag; got ${JSON.stringify(trimmed)}.`,
+			`Input header must be ${HL_FILE_PREFIX}PATH${HL_FILE_SUFFIX} or ${HL_FILE_PREFIX}PATH${HL_FILE_HASH_SEP}TAG${HL_FILE_SUFFIX} with a ${HL_FILE_HASH_LENGTH}-hex content-hash tag; got ${JSON.stringify(trimmed)}.`,
 		);
 	}
 
 	const parsedPath = normalizeHashlinePath(token.path, cwd);
 	if (parsedPath.length === 0) {
-		throw new Error(`Input header "${HL_FILE_PREFIX}" is empty; provide a file path.`);
+		throw new Error(`Input header "${HL_FILE_PREFIX}${HL_FILE_SUFFIX}" is empty; provide a file path.`);
 	}
 	return token.fileHash !== undefined
 		? { path: parsedPath, fileHash: token.fileHash, diff: "" }
@@ -145,7 +165,7 @@ function normalizeFallbackInput(input: string, options: SplitOptions): string {
 	if (!options.path || !containsRecognizableHashlineOperations(input)) return input;
 	const fallbackPath = normalizeHashlinePath(options.path, options.cwd);
 	if (fallbackPath.length === 0) return input;
-	return `${HL_FILE_PREFIX}${fallbackPath}\n${input}`;
+	return `${HL_FILE_PREFIX}${fallbackPath}${HL_FILE_SUFFIX}\n${input}`;
 }
 
 function splitRawSections(input: string, options: SplitOptions = {}): RawSection[] {
@@ -160,13 +180,13 @@ function splitRawSections(input: string, options: SplitOptions = {}): RawSection
 		if (/^@@\s+[-+]?\d+,\d+\s+[-+]?\d+,\d+\s+@@/.test(firstTrimmed)) {
 			throw new Error(
 				"unified-diff hunk header (`@@ -N,M +N,M @@`) is not valid in hashline. " +
-					"File sections start with `¶path#HASH`; use `replace`, `delete`, or `insert` ops.",
+					`File sections start with \`${HL_FILE_PREFIX}path${HL_FILE_HASH_SEP}HASH${HL_FILE_SUFFIX}\`; use \`replace\`, \`delete\`, or \`insert\` ops.`,
 			);
 		}
 		const preview = JSON.stringify(firstLine.slice(0, 120));
 		throw new Error(
-			`input must begin with "${HL_FILE_PREFIX}PATH${HL_FILE_HASH_SEP}HASH" on the first non-blank line for anchored edits; got: ${preview}. ` +
-				`Example: "${HL_FILE_PREFIX}src/foo.ts${HL_FILE_HASH_SEP}0A3" then edit ops.`,
+			`input must begin with "${HL_FILE_PREFIX}PATH${HL_FILE_HASH_SEP}HASH${HL_FILE_SUFFIX}" on the first non-blank line for anchored edits; got: ${preview}. ` +
+				`Example: "${HL_FILE_PREFIX}src/foo.ts${HL_FILE_HASH_SEP}${HL_FILE_HASH_EXAMPLES[0]}${HL_FILE_SUFFIX}" then edit ops.`,
 		);
 	}
 
@@ -187,7 +207,7 @@ function splitRawSections(input: string, options: SplitOptions = {}): RawSection
 		if (token.kind === "envelope-end" || token.kind === "abort") break;
 		if (token.kind === "envelope-begin") continue;
 
-		// Route every `¶`-prefixed line through parseHashlineHeaderLine so
+		// Route every bracket-prefixed line through parseHashlineHeaderLine so
 		// malformed headers still raise the strict "Input header must be …"
 		// diagnostic (the tokenizer alone would silently classify them as
 		// payload).
@@ -323,7 +343,7 @@ export class PatchSection {
 
 /**
  * A parsed hashline patch — zero or more {@link PatchSection}s, each rooted
- * at a `¶PATH#HASH` header. Construct via {@link Patch.parse}.
+ * at a `[PATH#HASH]` header. Construct via {@link Patch.parse}.
  *
  * `Patch` is pure data: parsing is line-anchored and does not look at the
  * filesystem. To apply a patch, hand it to {@link Patcher.apply}.

package/src/messages.ts

@@ -5,7 +5,7 @@
  * them.
  */
 
-import { HL_FILE_HASH_SEP, HL_FILE_PREFIX } from "./format";
+import { HL_FILE_HASH_SEP, HL_FILE_PREFIX, HL_FILE_SUFFIX } from "./format";
 
 /** Lines of context shown either side of a hash mismatch. */
 export const MISMATCH_CONTEXT = 2;
@@ -124,5 +124,5 @@ export const HEADTAIL_DRIFT_WARNING =
  * this single builder to stay in lockstep.
  */
 export function missingSnapshotTagMessage(sectionPath: string): string {
-	return `Missing hashline snapshot tag for edit to ${sectionPath}; use \`${HL_FILE_PREFIX}${sectionPath}${HL_FILE_HASH_SEP}tag\` from your latest read/search output. To create a new file, use the write tool.`;
+	return `Missing hashline snapshot tag for edit to ${sectionPath}; use \`${HL_FILE_PREFIX}${sectionPath}${HL_FILE_HASH_SEP}tag${HL_FILE_SUFFIX}\` from your latest read/search output. To create a new file, use the write tool.`;
 }

package/src/mismatch.ts

@@ -6,7 +6,7 @@
  * plus a couple of lines of surrounding context. The {@link MismatchError}
  * formats this into a message at construction time.
  */
-import { formatNumberedLine, HL_FILE_HASH_EXAMPLES, HL_FILE_HASH_SEP, HL_FILE_PREFIX } from "./format";
+import { formatNumberedLine, HL_FILE_HASH_EXAMPLES, HL_FILE_HASH_SEP, HL_FILE_PREFIX, HL_FILE_SUFFIX } from "./format";
 import { MISMATCH_CONTEXT } from "./messages";
 
 const LINE_REF_RE = /^\s*[>+\-*]*\s*(\d+)(?::.*)?\s*$/;
@@ -15,7 +15,7 @@ export function formatFullAnchorRequirement(raw?: string): string {
 	const received = raw === undefined ? "" : ` Received ${JSON.stringify(raw)}.`;
 	return (
 		`a bare line number from read/search output plus the section header content-hash tag ` +
-		`(for example ${HL_FILE_PREFIX}src/foo.ts${HL_FILE_HASH_SEP}${HL_FILE_HASH_EXAMPLES[0]} and line "160")${received}`
+		`(for example ${HL_FILE_PREFIX}src/foo.ts${HL_FILE_HASH_SEP}${HL_FILE_HASH_EXAMPLES[0]}${HL_FILE_SUFFIX} and line "160")${received}`
 	);
 }
 
@@ -99,12 +99,12 @@ export class MismatchError extends Error {
 		if (!hashRecognized) {
 			return [
 				`Edit rejected${pathText}: hash ${HL_FILE_HASH_SEP}${details.expectedFileHash} is not from this session.`,
-				`The current file hashes to ${HL_FILE_HASH_SEP}${details.actualFileHash}. Re-read the file with \`read\` to copy a current ${HL_FILE_PREFIX}path${HL_FILE_HASH_SEP}tag header — never invent the tag and never reuse one from a prior session.`,
+				`The current file hashes to ${HL_FILE_HASH_SEP}${details.actualFileHash}. Re-read the file with \`read\` to copy a current ${HL_FILE_PREFIX}path${HL_FILE_HASH_SEP}tag${HL_FILE_SUFFIX} header — never invent the tag and never reuse one from a prior session.`,
 			];
 		}
 		return [
 			`Edit rejected${pathText}: file changed between read and edit.`,
-			`Section is bound to ${HL_FILE_HASH_SEP}${details.expectedFileHash}, but the current file hashes to ${HL_FILE_HASH_SEP}${details.actualFileHash}. If a prior edit in this session modified this file, copy the ${HL_FILE_PREFIX}path${HL_FILE_HASH_SEP}newhash header from that edit's response; otherwise re-read the file with \`read\` to refresh the tag before retrying.`,
+			`Section is bound to ${HL_FILE_HASH_SEP}${details.expectedFileHash}, but the current file hashes to ${HL_FILE_HASH_SEP}${details.actualFileHash}. If a prior edit in this session modified this file, copy the ${HL_FILE_PREFIX}path${HL_FILE_HASH_SEP}newhash${HL_FILE_SUFFIX} header from that edit's response; otherwise re-read the file with \`read\` to refresh the tag before retrying.`,
 		];
 	}
 

package/src/parser.ts

@@ -43,7 +43,7 @@ function detectApplyPatchContamination(text: string, _hasPending: boolean): stri
 		const preview = trimmed.length > 48 ? `${trimmed.slice(0, 48)}…` : trimmed;
 		return (
 			`apply_patch sentinel ${JSON.stringify(preview)} is not valid in hashline. ` +
-			"File sections start with `¶path#HASH` (no `Update File:` / `Add File:` keyword). " +
+			"File sections start with `[path#HASH]` (no `Update File:` / `Add File:` keyword). " +
 			"Use `replace N..M:`, `delete N..M`, or `insert before|after|head|tail:` ops."
 		);
 	}

package/src/patcher.ts

@@ -64,9 +64,9 @@ export interface PatchSectionResult {
 	persisted: string;
 	/** Final text that the {@link Filesystem} actually wrote (may differ if the FS transformed it). */
 	written: string;
-	/** 3-hex opaque snapshot tag for `after`. Use to anchor follow-up edits. */
+	/** 4-hex content-hash tag for `after`. Use to anchor follow-up edits. */
 	fileHash: string;
-	/** Hashline section header (`¶path#tag`) of the post-edit content. */
+	/** Hashline section header (`[path#tag]`) of the post-edit content. */
 	header: string;
 	/** 1-indexed first changed line in `after`, or `undefined` for noops. */
 	firstChangedLine?: number;

package/src/prefixes.ts

@@ -14,9 +14,11 @@
  * otherwise turn every content line into a (malformed) op.
  */
 
+import { HL_FILE_HASH_LENGTH } from "./format";
+
 const HL_PREFIX_RE = /^\s*(?:>>>|>>)?\s*(?:[+*-]\s*)?\d+:/;
 const HL_PREFIX_PLUS_RE = /^\s*(?:>>>|>>)?\s*\+\s*\d+:/;
-const HL_HEADER_RE = /^\s*¶\S+#[0-9a-fA-F]{3}\s*$/;
+const HL_HEADER_RE = new RegExp(`^\\s*\\[[^#\\r\\n]+#[0-9a-fA-F]{${HL_FILE_HASH_LENGTH}}\\]\\s*$`);
 const DIFF_PLUS_RE = /^[+](?![+])/;
 const READ_TRUNCATION_NOTICE_RE = /^\[(?:Showing lines \d+-\d+ of \d+|\d+ more lines? in (?:file|\S+))\b.*\bUse :L?\d+/;
 

package/src/prompt.md

@@ -1,7 +1,7 @@
 Your patch language names lines to replace, delete, or insert at, then lists the new content. Rule of thumb: a header ending in `:` is followed by `+` body rows; `delete` has no body.
 
 <headers>
-Every file section starts with `¶PATH#TAG`. `TAG` is the 4-hex snapshot tag from your latest `read`/`search`, and is REQUIRED on every section — there is no hashless form. To create a new file, use the `write` tool; hashline only edits files that already exist.
+Every file section starts with `[PATH#TAG]`. `TAG` is the 4-hex snapshot tag from your latest `read`/`search`, and is REQUIRED on every section — there is no hashless form. To create a new file, use the `write` tool; hashline only edits files that already exist.
 </headers>
 
 <ops>
@@ -23,9 +23,9 @@ There is NO other body row kind. NEVER write `-old` or a bare/context line. To k
 </body-rows>
 
 <rules>
-- Line numbers come from `read`/`search` (`LINE:TEXT`). Copy the `¶PATH#TAG` header; use the bare LINE numbers.
+- Line numbers come from `read`/`search` (`LINE:TEXT`). Copy the `[PATH#TAG]` header; use the bare LINE numbers.
 - Numbers refer to the ORIGINAL file and stay valid for the whole patch — they do not shift as hunks apply.
-- Across calls they do NOT survive: each applied edit mints a fresh `#TAG` and renumbers the file, so the tag and line numbers you just used are dead. Anchor the next edit on the `¶PATH#TAG` and lines from the edit response (or re-`read`), never on pre-edit numbers.
+- Across calls they do NOT survive: each applied edit mints a fresh `#TAG` and renumbers the file, so the tag and line numbers you just used are dead. Anchor the next edit on the `[PATH#TAG]` and lines from the edit response (or re-`read`), never on pre-edit numbers.
 - A line number is an offset, not a structural boundary: never `insert after N` into a construct you have not read, and never start or end a `replace`/`delete` range mid-expression or mid-block. If unsure what is on those lines, `read` them first.
 - On a stale-tag rejection — or any result you cannot fully account for — STOP and re-`read`. Never stack more line-numbered edits onto output you have not re-grounded; that compounds corruption.
 - One hunk per range; the body is the final content, never an old/new pair.
@@ -37,7 +37,7 @@ There is NO other body row kind. NEVER write `-old` or a bare/context line. To k
 <example>
 Original (the exact shape `read` returns):
 ```
-¶greet.py#A1B2
+[greet.py#A1B2]
 1:def greet(name):
 2:    msg = "Hello, " + name
 3:    print(msg)
@@ -46,14 +46,14 @@ Original (the exact shape `read` returns):
 
 Insert a guard after line 1:
 ```
-¶greet.py#A1B2
+[greet.py#A1B2]
 insert after 1:
 +    if not name: name = "stranger"
 ```
 
 Replace line 2 with two lines:
 ```
-¶greet.py#A1B2
+[greet.py#A1B2]
 replace 2..2:
 +    greeting = "Hi"
 +    msg = f"{greeting}, {name}"
@@ -61,13 +61,13 @@ replace 2..2:
 
 Delete line 3:
 ```
-¶greet.py#A1B2
+[greet.py#A1B2]
 delete 3
 ```
 
 Add a header and trailer:
 ```
-¶greet.py#A1B2
+[greet.py#A1B2]
 insert head:
 +# generated header
 insert tail:
@@ -76,7 +76,7 @@ insert tail:
 
 Replace the whole `greet` function block — `replace block 1:` resolves lines 1–3 (the `def` header through `print(msg)`); line 4 is a separate statement and stays:
 ```
-¶greet.py#A1B2
+[greet.py#A1B2]
 replace block 1:
 +def greet(name):
 +    print(f"Hello, {name}")

package/src/tokenizer.ts

@@ -3,7 +3,7 @@
  *
  * Format shape:
  * ```
- * ¶path/to/file.ts#0A3
+ * [path/to/file.ts#1A2B]
  * replace 5..7:
  * +literal new line
  * ```
@@ -15,6 +15,7 @@ import {
 	HL_FILE_HASH_LENGTH,
 	HL_FILE_HASH_SEP,
 	HL_FILE_PREFIX,
+	HL_FILE_SUFFIX,
 	HL_HEADER_COLON,
 	HL_INSERT_AFTER,
 	HL_INSERT_BEFORE,
@@ -45,6 +46,7 @@ const CHAR_LOWER_F = 102;
 const CHAR_PAYLOAD_REPLACE = HL_PAYLOAD_REPLACE.charCodeAt(0);
 const CHAR_COLON = HL_HEADER_COLON.charCodeAt(0);
 const FILE_PREFIX_LENGTH = HL_FILE_PREFIX.length;
+const FILE_SUFFIX_LENGTH = HL_FILE_SUFFIX.length;
 
 function isDigitCode(code: number): boolean {
 	return code >= CHAR_ZERO && code <= CHAR_NINE;
@@ -137,7 +139,7 @@ export function parseLid(raw: string, lineNum: number): Anchor {
 	if (number === null || skipWhitespace(raw, number.nextIndex, end) !== end) {
 		throw new Error(
 			`line ${lineNum}: expected a line number such as ${describeAnchorExamples("119")}; ` +
-				`got ${JSON.stringify(raw)}. Use ${HL_FILE_PREFIX}PATH${HL_FILE_HASH_SEP}hash from your latest read for file-version binding.`,
+				`got ${JSON.stringify(raw)}. Use ${HL_FILE_PREFIX}PATH${HL_FILE_HASH_SEP}hash${HL_FILE_SUFFIX} from your latest read for file-version binding.`,
 		);
 	}
 	return { line: number.line };
@@ -312,28 +314,44 @@ function tryParseHunkHeader(line: string): ParsedHunkHeader | null {
 function tryParseHeader(line: string): { path: string; fileHash?: string } | null {
 	if (!line.startsWith(HL_FILE_PREFIX)) return null;
 	const end = trimEndIndex(line);
-	let index = FILE_PREFIX_LENGTH;
-	if (index >= end) return null;
-	const pathStart = index;
-	while (index < end) {
-		const code = line.charCodeAt(index);
-		if (code === CHAR_HASH || code === CHAR_SPACE || code === CHAR_TAB) break;
-		index++;
-	}
-	if (index === pathStart) return null;
-	const path = line.slice(pathStart, index);
+	if (FILE_PREFIX_LENGTH + FILE_SUFFIX_LENGTH >= end) return null;
+	if (!line.endsWith(HL_FILE_SUFFIX, end)) return null;
+	const bodyEnd = end - FILE_SUFFIX_LENGTH;
+	if (FILE_PREFIX_LENGTH >= bodyEnd) return null;
+
+	// The snapshot tag, when present, is the trailing `#XXXX` block inside the
+	// bracketed header. We detect it from the suffix so the path may
+	// legitimately contain whitespace (e.g. `OneDrive - Company/file.ts`).
+	let pathEnd = bodyEnd;
 	let fileHash: string | undefined;
-	if (index < end && line.charCodeAt(index) === CHAR_HASH) {
-		const hashStart = index + 1;
-		const hashEnd = hashStart + HL_FILE_HASH_LENGTH;
-		if (hashEnd > end) return null;
-		for (let probe = hashStart; probe < hashEnd; probe++) {
-			if (!isHexDigitCode(line.charCodeAt(probe))) return null;
+	const trailingHashStart = bodyEnd - HL_FILE_HASH_LENGTH - 1;
+	if (trailingHashStart >= FILE_PREFIX_LENGTH && line.charCodeAt(trailingHashStart) === CHAR_HASH) {
+		let allHex = true;
+		for (let probe = trailingHashStart + 1; probe < bodyEnd; probe++) {
+			if (!isHexDigitCode(line.charCodeAt(probe))) {
+				allHex = false;
+				break;
+			}
+		}
+		if (allHex) {
+			pathEnd = trailingHashStart;
+			fileHash = line.slice(trailingHashStart + 1, bodyEnd).toUpperCase();
 		}
-		fileHash = line.slice(hashStart, hashEnd).toUpperCase();
-		index = hashEnd;
 	}
-	if (skipWhitespace(line, index, end) !== end) return null;
+
+	// The hashline header grammar uses `#` as the path/tag separator and
+	// does not allow `#` inside filenames. Anything `#` left in the path
+	// body — short tags (`#1A2`), non-hex tags (`#1A2G`), over-long tags
+	// (`#1A2B5`), stale-tag copy-paste (`#1A2B copied from read`), or
+	// line-suffixed tags (`#1A2B:42`) — means the header is malformed.
+	// Surface the focused diagnostic instead of silently mis-routing the
+	// edit or reporting a missing tag downstream.
+	for (let i = FILE_PREFIX_LENGTH; i < pathEnd; i++) {
+		if (line.charCodeAt(i) === CHAR_HASH) return null;
+	}
+
+	if (pathEnd === FILE_PREFIX_LENGTH) return null;
+	const path = line.slice(FILE_PREFIX_LENGTH, pathEnd);
 	return fileHash !== undefined ? { path, fileHash } : { path };
 }
 

package/src/types.ts

@@ -72,7 +72,7 @@ export interface SplitOptions {
 	/** Resolves absolute paths inside hashline headers to cwd-relative form. */
 	cwd?: string;
 	/**
-	 * Fallback path used when the input lacks a `¶PATH` header but contains
+	 * Fallback path used when the input lacks a `[PATH]` header but contains
 	 * recognizable hashline operations. Lets streaming previews work before
 	 * the model has written the header.
 	 */