pi-hashline-edit-pro 4.2.6 → 4.2.7

package/README.md

@@ -90,6 +90,7 @@ Single line: use the same anchor for `remove_from` and `remove_to`. `replace_fro
 The request is checked before any file I/O, so a bad request never touches the file.
 
 Common copy-paste slips are fixed automatically and reported as warnings: a leftover `anchor│` prefix in `replacement_lines` or the anchor fields (a prefix of 4 to 5 characters before `│`, for example `ab12│`), diff-preview rows pasted into the replacement, a reversed range, and a boundary line pasted twice. New lines that re-include a block adjacent to the range are stripped when that block is unique in the file. The whole run is stripped as one unit, so re-including an unchanged block next to the range never duplicates it. Boundary dedup has three modes in `/hashline-config`: `on` strips with a warning, `off` applies edits literally, and `strict` rejects the edit with `[E_BOUNDARY_STRICT]` when any replacement line would be stripped.
+Content containing a NUL byte (`U+0000`) is rejected with `[E_BAD_SHAPE]` before any file I/O: writing it would make the file binary, so use an empty replacement to delete. This applies to `replace`'s `replacement_lines` and `insert`'s `lines`.
 
 Every line in the removed range must match what was last shown to you. The extension records the `anchor│content` rows it serves (`read` output, `anchor_grep` output, the auto-read block after `write`, the `+anchor│` and ` anchor│` rows of post-edit diffs, the current-range rows of `[E_RANGE_STALE]` feedback, and the context rows of stale-anchor feedback) and verifies the whole range against that record before writing. A line that changed on disk since it was shown, or an anchor that is not owned in this session, refuses the edit with `[E_RANGE_STALE]` or `[E_STALE_ANCHOR]` and returns the current range with fresh anchors, so the retry needs no `read`. An owned anchor enters the served record when its row is shown (after a restart, restored ownership counts as shown), so a file with no owned anchors cannot be edited by anchor at all; call `read` first. An owned line that was never shown — for example beyond an auto-read preview's truncation cap — is refused with `[E_RANGE_STALE]` and returns the current range, so the retry still needs no `read`.
 
@@ -164,7 +165,7 @@ All five tools return machine-readable metadata in `details` alongside the model
 | Tool | `details` |
 | --- | --- |
 | `read` | `truncation` (set when output was truncated), `snapshotId` (a `v2\|path\|ino\|mtime\|ctime\|size` fingerprint), `nextOffset` (use as the next `offset`), and `metrics` with `truncated` and `next_offset`. |
-| `replace`, `insert` | `diff` (post-edit diff, capped, with current anchors on `+HASH│` and ` HASH│` rows; a same-turn batch reports the combined diff on its last call and an empty diff on earlier calls), `patch` (a standard unified patch for external tools, capped like the diff), `patchTruncated` (true when the patch was cut and can no longer be applied as-is), `firstChangedLine`, `snapshotId`, `classification` (`"noop"` when nothing changed), `batch` (`{ id, size, last, total }` marking same-turn batch membership), and `metrics`: `edits_attempted`, `edits_noop`, `warnings`, `classification` (`"applied"` or `"noop"`), `changed_lines` (`{ first, last }`), `added_lines`, `removed_lines`. |
+| `replace`, `insert` | `diff` (post-edit diff, capped, with current anchors on `+HASH│` and ` HASH│` rows; a same-turn batch reports the combined diff on its last call and an empty diff on earlier calls), `patch` (a standard unified patch for external tools, capped like the diff), `patchTruncated` (true when the patch was cut or skipped for a pair over 1MB and can no longer be applied as-is), `firstChangedLine`, `snapshotId`, `classification` (`"noop"` when nothing changed), `batch` (`{ id, size, last, total }` marking same-turn batch membership), and `metrics`: `edits_attempted`, `edits_noop`, `warnings`, `classification` (`"applied"` or `"noop"`), `changed_lines` (`{ first, last }`), `added_lines`, `removed_lines`. |
 | `undo_last_change` | `diff` (the undo diff with restored anchors), `patch`, `patchTruncated`, and `metrics` in the same shape as `replace`. |
 | `anchor_grep` | `metrics` with `matches` (capped at `limit`), `files`, and `truncated`; `truncation` (the standard pi truncation report) when output was cut; and `linesTruncated` (true when long lines were shown as fragments). |
 
@@ -198,7 +199,7 @@ The table is curated for tokenizers, not for humans. Every anchor is the concate
 
 Each line also carries a content checksum. The line is canonicalized (carriage returns stripped, trailing whitespace trimmed) and hashed with [xxhash-wasm](https://github.com/jungomi/xxhash-wasm). The canonicalization keeps the checksum stable across editor-save cycles that add or remove trailing whitespace. A line over 500 bytes is hashed from its first 500 bytes.
 
-Allocated anchors live in a persistent per-file snapshot (`~/.config/pi-hashline-edit-pro/hash-store.sqlite`) keyed by content checksum, so resume-after-restart and cross-session edits reuse ownership instead of minting duplicates. Each session also appends an ownership log (`allocate`/`free`/`clear` events) to a sidecar file under `~/.config/pi-hashline-edit-pro/sessions/`; the fold of that log is the session's source of truth, and sidecars whose session file is gone are garbage-collected at startup.
+Allocated anchors live in a persistent per-file snapshot (`~/.config/pi-hashline-edit-pro/hash-store.sqlite`) keyed by content checksum, so resume-after-restart and cross-session edits reuse ownership instead of minting duplicates. Each session also appends an ownership log (`allocate`/`free`/`clear` events) to a sidecar file under `~/.config/pi-hashline-edit-pro/sessions/`; the fold of that log is the session's source of truth, sidecars whose session file is gone are garbage-collected at startup, and the in-memory ownership of a session is released when that session shuts down and rebuilt from its sidecar on next use.
 
 When a range is edited, the mapping between old and new content is computed per span: lines whose content is unchanged keep their allocated anchors, anchors of removed lines are freed, and every genuinely new line is minted a fresh anchor. Anchors are never assigned by matching content; only positional survival across an edit preserves one.
 
@@ -217,7 +218,7 @@ Codes starting with `E_` are errors: nothing was written — except `File was wr
 
 | Code | Meaning |
 | --- | --- |
-| `[E_BAD_SHAPE]` | Request envelope or edit item has unknown, missing, or wrongly-typed fields (for example `replacement_lines` must be an array of strings, one element per line). |
+| `[E_BAD_SHAPE]` | Request envelope or edit item has unknown, missing, or wrongly-typed fields (for example `replacement_lines` must be an array of strings, one element per line), or content contains a NUL byte (`U+0000`), which would make the file binary. |
 | `[W_BAD_SHAPE]` | Auto-corrected request slip reported as a warning (for example unwrapped JSON array syntax, embedded newlines split into lines, or stringified array text that could not be parsed and was kept as one literal line). |
 | `[E_BAD_REF]` | An anchor in `remove_from`/`remove_to` is not a bare 4-char anchor. |
 | `[W_BAD_REF]` | A pasted `anchor│` or diff-preview marker was stripped from an anchor field with a warning. |
@@ -247,6 +248,7 @@ Codes starting with `E_` are errors: nothing was written — except `File was wr
 
 - Stale anchors. `[E_STALE_ANCHOR]` means an anchor is not owned in this session: it was never shown to you, or its line was edited or the file was rewritten since. Call `read` for fresh anchors and retry.
 - Range changed on disk. `[E_RANGE_STALE]` means a line inside the replaced range changed after it was last shown to you (or was never shown). Nothing was modified; the error carries the current range with fresh anchors, so retry with those without a `read`.
+- Multi-conversation hosts. Anchors, served records, and ownership logs are resolved per calling session, so a tool call in one conversation is never answered by another conversation's registry; a foreign anchor fails with `[E_STALE_ANCHOR]`. Interactive previews are the one exception: pi does not pass the session into render callbacks, so when one process serves several conversations at once a preview can fall back to the most recently active session and show a stale or wrong-file diff. Previews never write files or claim anchors; run the call for the authoritative result.
 - Reset the anchor state. Anchors live in `~/.config/pi-hashline-edit-pro/hash-store.sqlite` (with `-wal`/`-shm` sidecars) and in per-session ownership logs under `~/.config/pi-hashline-edit-pro/sessions/`. Quit pi, delete those files, and everything is rebuilt on the next session. Anchor history is lost, but no project files are touched.
 - Corrupt store. If the store fails its health check it is renamed to `hash-store.sqlite.corrupt-<timestamp>` and rebuilt automatically.
 - Config directory moved. If `XDG_CONFIG_HOME` is set on a non-Windows platform, the config directory (and the anchor state inside it) lives at `$XDG_CONFIG_HOME/pi-hashline-edit-pro` instead of `~/.config/pi-hashline-edit-pro`. An existing store is not migrated automatically. To keep anchor and undo history, move the old `hash-store.sqlite` files (plus `-wal`/`-shm` sidecars) into the new directory before the first run.

package/index.ts

@@ -20,7 +20,7 @@ import {
   adjustDiffContextLines,
 } from "./src/config";
 import { loadHashStore, persistSnapshot, pruneMissing } from "./src/hash-store";
-import { initRegistry, gcRegistrySidecars, clearRegistry, freeAnchors, markServed as markServedScoped } from "./src/anchor-registry";
+import { initRegistry, gcRegistrySidecars, clearRegistry, freeAnchors, markServed as markServedScoped, sessionKeyFor, withAnchorSession, releaseRegistrySession } from "./src/anchor-registry";
 import { buildServedMap } from "./src/served";
 import { clearBoundaryBypass } from "./src/boundary-bypass";
 import { finalizeTurn, planAssistantMessage } from "./src/batch";
@@ -58,7 +58,7 @@ export default function (pi: ExtensionAPI): void {
     }
   }
 
-  pi.on("session_start", async (_event, ctx) => {
+  pi.on("session_start", async (_event, ctx) => withAnchorSession(ctx, async () => {
     const active = pi.getActiveTools();
     grepWasActive = active.includes("grep");
     pi.setActiveTools(active.filter((t) => t !== "edit"));
@@ -73,7 +73,7 @@ export default function (pi: ExtensionAPI): void {
       });
     const sessionManager = (ctx as { sessionManager?: { getSessionFile?: () => string | undefined } }).sessionManager;
     const sessionFile = sessionManager?.getSessionFile?.();
-    await initRegistry(sessionFile);
+    if (sessionKeyFor(ctx) === undefined) await initRegistry(sessionFile);
     await gcRegistrySidecars();
     const { config, corrupted } = await readConfigWithStatus();
     if (corrupted && (ctx as { hasUI?: boolean }).hasUI) ctx.ui.notify("Hashline config was corrupt and was reset to defaults", "warning");
@@ -88,6 +88,15 @@ export default function (pi: ExtensionAPI): void {
     if (debugValue === "1" || debugValue === "true") {
       ctx.ui.notify(`Hashline Edit mode active`, "info");
     }
+  }));
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    try {
+      const key = sessionKeyFor(ctx);
+      if (key !== undefined) releaseRegistrySession(key);
+    } catch (error) {
+      console.error("Failed to release anchor registry session:", error);
+    }
   });
 
   pi.registerCommand("hashline-config", {
@@ -127,18 +136,18 @@ export default function (pi: ExtensionAPI): void {
 
   pi.registerCommand("clear-anchors", {
     description: "Clear the session's anchor claims (path-free resolution state); anchors are re-claimed on the next read",
-    handler: async (_args, ctx) => {
+    handler: async (_args, ctx) => withAnchorSession(ctx, async () => {
       clearRegistry();
       ctx.ui.notify(`Anchor claims cleared for this session`, "info");
-    },
+    }),
   });
-  pi.on("message_end", async (event, ctx) => {
+  pi.on("message_end", async (event, ctx) => withAnchorSession(ctx, async () => {
     try {
       await planAssistantMessage(event.message, ctx.cwd);
     } catch (error) {
       console.error("Failed to plan edit batch:", error);
     }
-  });
+  }));
   pi.on("turn_end", async (event) => {
     try {
       const ids = (event.toolResults ?? []).map((result) => (result as { toolCallId?: unknown }).toolCallId).filter((id): id is string => typeof id === "string");
@@ -147,7 +156,7 @@ export default function (pi: ExtensionAPI): void {
       console.error("Failed to finalize edit batch:", error);
     }
   });
-  pi.on("tool_result", async (event, ctx) => {
+  pi.on("tool_result", async (event, ctx) => withAnchorSession(ctx, async () => {
     if (event.isError) return;
 
     if (event.toolName === "write") {
@@ -237,5 +246,5 @@ export default function (pi: ExtensionAPI): void {
         },
       ],
     };
-  });
+  }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "4.2.6",
+  "version": "4.2.7",
   "type": "module",
   "description": "Hash-anchored read/replace/insert/grep tools for pi-coding-agent. Every line gets a unique 4-char tokenizer-friendly anchor that stays stable across edits; stale or ambiguous anchors are rejected, never fuzzy-matched. Undo persists across restarts.",
   "main": "index.ts",

package/src/anchor-registry.ts

@@ -1,7 +1,8 @@
-import { chmod, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { chmod, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { appendFileSync, chmodSync } from "node:fs";
 import { join } from "node:path";
 import { createHash } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { sessionClaimsDir } from "./paths";
 import { contentChecksum } from "./hashline/hasher";
 import { ANCHOR_COUNT, anchorAt } from "./hashline/alphabet";
@@ -24,10 +25,132 @@ export interface OwnedAnchor {
   checksum: string;
 }
 
+export interface AnchorSessionContext {
+  sessionManager?: {
+    getSessionFile?: () => string | undefined;
+    getSessionId?: () => string;
+  };
+}
+
+interface OwnedAnchorMap {
+  readonly size: number;
+  has(anchor: string): boolean;
+  get(anchor: string): OwnedAnchor | undefined;
+  set(anchor: string, entry: OwnedAnchor): unknown;
+  delete(anchor: string): boolean;
+  clear(): void;
+  keys(): Iterable<string>;
+  values(): Iterable<OwnedAnchor>;
+  entries(): Iterable<[string, OwnedAnchor]>;
+  [Symbol.iterator](): IterableIterator<[string, OwnedAnchor]>;
+}
+
+interface AnchorMintedSet {
+  has(anchor: string): boolean;
+  add(anchor: string): unknown;
+  [Symbol.iterator](): IterableIterator<string>;
+}
+
+class ShadowOwnedMap implements OwnedAnchorMap {
+  private readonly parent: OwnedAnchorMap;
+  private readonly overrides = new Map<string, OwnedAnchor | undefined>();
+
+  constructor(parent: OwnedAnchorMap) {
+    this.parent = parent;
+  }
+
+  has(anchor: string): boolean {
+    return this.overrides.has(anchor) ? this.overrides.get(anchor) !== undefined : this.parent.has(anchor);
+  }
+
+  get(anchor: string): OwnedAnchor | undefined {
+    return this.overrides.has(anchor) ? this.overrides.get(anchor) : this.parent.get(anchor);
+  }
+
+  set(anchor: string, entry: OwnedAnchor): this {
+    this.overrides.set(anchor, entry);
+    return this;
+  }
+
+  delete(anchor: string): boolean {
+    const owned = this.has(anchor);
+    this.overrides.set(anchor, undefined);
+    return owned;
+  }
+
+  clear(): void {
+    for (const anchor of this.parent.keys()) this.overrides.set(anchor, undefined);
+    for (const [anchor, entry] of this.overrides) {
+      if (entry !== undefined && !this.parent.has(anchor)) this.overrides.delete(anchor);
+    }
+  }
+
+  get size(): number {
+    let count = 0;
+    for (const _entry of this) count += 1;
+    return count;
+  }
+
+  *keys(): IterableIterator<string> {
+    for (const [anchor] of this.merged()) yield anchor;
+  }
+
+  *values(): IterableIterator<OwnedAnchor> {
+    for (const [, entry] of this.merged()) yield entry;
+  }
+
+  *entries(): IterableIterator<[string, OwnedAnchor]> {
+    yield* this.merged();
+  }
+
+  *[Symbol.iterator](): IterableIterator<[string, OwnedAnchor]> {
+    yield* this.merged();
+  }
+
+  private *merged(): IterableIterator<[string, OwnedAnchor]> {
+    for (const [anchor, entry] of this.parent) {
+      if (this.overrides.has(anchor)) {
+        const override = this.overrides.get(anchor);
+        if (override !== undefined) yield [anchor, override];
+      } else {
+        yield [anchor, entry];
+      }
+    }
+    for (const [anchor, entry] of this.overrides) {
+      if (entry !== undefined && !this.parent.has(anchor)) yield [anchor, entry];
+    }
+  }
+}
+
+class ShadowMintedSet implements AnchorMintedSet {
+  private readonly parent: AnchorMintedSet;
+  private readonly added = new Set<string>();
+
+  constructor(parent: AnchorMintedSet) {
+    this.parent = parent;
+  }
+
+  has(anchor: string): boolean {
+    return this.added.has(anchor) || this.parent.has(anchor);
+  }
+
+  add(anchor: string): this {
+    this.added.add(anchor);
+    return this;
+  }
+
+  *[Symbol.iterator](): IterableIterator<string> {
+    yield* this.parent;
+    for (const anchor of this.added) {
+      if (!this.parent.has(anchor)) yield anchor;
+    }
+  }
+}
+
 interface SessionState {
-	owned: Map<string, OwnedAnchor>;
+	owned: OwnedAnchorMap;
 	served: Map<string, Map<string, string>>;
-	everMinted: Set<string>;
+	everMinted: AnchorMintedSet;
 	probe: number;
 }
 
@@ -35,9 +158,14 @@ const SIDECAR_SUFFIX = ".registry.jsonl";
 const SIDECAR_COMPACT_LINES = 5000;
 const SIDECAR_COMPACT_BYTES = 1024 * 1024;
 const SIDECAR_COMPACT_CHUNK = 5000;
+const SIDECAR_HEADER_BYTES = 64 * 1024;
+const SIDECAR_HEADER_CHUNK = 4096;
 let currentKey: string | undefined;
-let currentSidecar: string | undefined;
+const sidecarByKey = new Map<string, string>();
+const pendingInits = new Map<string, Promise<void>>();
+const loadTokens = new Map<string, object>();
 const registries = new Map<string, SessionState>();
+const sessionScope = new AsyncLocalStorage<string>();
 
 function newSessionState(seed?: string): SessionState {
 	let probe = 0;
@@ -153,20 +281,12 @@ async function compactSidecarIfNeeded(sidecar: string, raw: string, sessionFile:
   }
 }
 
-export async function initRegistry(sessionFile: string | undefined): Promise<void> {
-  if (!sessionFile) {
-    currentKey = `__ephemeral__-${Date.now()}-${Math.random().toString(36).slice(2)}`;
-    currentSidecar = undefined;
-    registries.set(currentKey, newSessionState(currentKey));
-    return;
-  }
-  const key = sidecarKeyFor(sessionFile);
-  currentKey = key;
-  currentSidecar = sidecarPath(key);
+async function loadRegistryState(key: string, sessionFile: string, token: object): Promise<void> {
+  const sidecar = sidecarPath(key);
   let events: RegistryEvent[] = [];
   let rawLog = "";
   try {
-    rawLog = await readFile(currentSidecar, "utf-8");
+    rawLog = await readFile(sidecar, "utf-8");
     events = parseRegistryLog(rawLog);
   } catch (error) {
     if (errCode(error) !== "ENOENT") {
@@ -174,16 +294,18 @@ export async function initRegistry(sessionFile: string | undefined): Promise<voi
     }
   }
   const folded = foldRegistryEvents(events, `${key}:${process.pid}`);
+  if (loadTokens.get(key) !== token) return;
   seedServedFromOwned(folded);
   registries.set(key, folded);
+  sidecarByKey.set(key, sidecar);
   if (rawLog.length > 0) {
-    await compactSidecarIfNeeded(currentSidecar, rawLog, sessionFile, folded);
+    await compactSidecarIfNeeded(sidecar, rawLog, sessionFile, folded);
   }
   try {
     await mkdir(sessionClaimsDir(), { recursive: true, mode: 0o700 });
     if (process.platform !== "win32") {
       try { await chmod(sessionClaimsDir(), 0o700); } catch (error) { if (errCode(error) !== "ENOENT") console.error("Failed to secure anchor registry directory:", error); }
-      try { await chmod(currentSidecar, 0o600); } catch (error) { if (errCode(error) !== "ENOENT") console.error("Failed to secure anchor registry sidecar:", error); }
+      try { await chmod(sidecar, 0o600); } catch (error) { if (errCode(error) !== "ENOENT") console.error("Failed to secure anchor registry sidecar:", error); }
     }
     appendEvent({ kind: "session", sessionFile } satisfies RegistryEvent);
   } catch (error) {
@@ -191,17 +313,85 @@ export async function initRegistry(sessionFile: string | undefined): Promise<voi
   }
 }
 
+async function ensureRegistryForKey(key: string, sessionFile: string | undefined): Promise<void> {
+  currentKey = key;
+  if (registries.has(key)) return;
+  const pending = pendingInits.get(key);
+  if (pending) {
+    await pending;
+    return;
+  }
+  const token: object = {};
+  loadTokens.set(key, token);
+  const promise = (async () => {
+    if (sessionFile === undefined) {
+      registries.set(key, newSessionState(key));
+      return;
+    }
+    await loadRegistryState(key, sessionFile, token);
+  })();
+  pendingInits.set(key, promise);
+  try {
+    await promise;
+  } finally {
+    pendingInits.delete(key);
+  }
+}
+
+export async function initRegistry(sessionFile: string | undefined): Promise<string> {
+  if (sessionFile === undefined) {
+    const key = `__ephemeral__-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    currentKey = key;
+    registries.set(key, newSessionState(key));
+    return key;
+  }
+  const key = sidecarKeyFor(sessionFile);
+  await ensureRegistryForKey(key, sessionFile);
+  return key;
+}
+
+export function sessionKeyFor(ctx: AnchorSessionContext | undefined): string | undefined {
+  const sessionFile = sessionFileFor(ctx);
+  if (sessionFile !== undefined) return sidecarKeyFor(sessionFile);
+  const sessionId = ctx?.sessionManager?.getSessionId?.();
+  if (typeof sessionId === "string" && sessionId.length > 0) return `ephemeral:${sessionId}`;
+  return undefined;
+}
+
+function sessionFileFor(ctx: AnchorSessionContext | undefined): string | undefined {
+  const sessionFile = ctx?.sessionManager?.getSessionFile?.();
+  return typeof sessionFile === "string" && sessionFile.length > 0 ? sessionFile : undefined;
+}
+
+export async function withAnchorSession<T>(ctx: AnchorSessionContext | undefined, fn: () => Promise<T> | T): Promise<T> {
+  const key = sessionKeyFor(ctx);
+  if (key === undefined) return fn();
+  const sessionFile = sessionFileFor(ctx);
+  return sessionScope.run(key, async () => {
+    await ensureRegistryForKey(key, sessionFile);
+    return fn();
+  });
+}
+
+function activeKey(): string | undefined {
+  return sessionScope.getStore() ?? currentKey;
+}
+
 function current(): SessionState | undefined {
-  if (!currentKey) return undefined;
-  return registries.get(currentKey);
+  const key = activeKey();
+  if (!key) return undefined;
+  return registries.get(key);
 }
 
 function appendEvent(event: RegistryEvent): void {
-  if (!currentSidecar) return;
+  const key = activeKey();
+  if (!key) return;
+  const sidecar = sidecarByKey.get(key);
+  if (!sidecar) return;
   try {
-    appendFileSync(currentSidecar, JSON.stringify(event) + "\n", "utf-8");
+    appendFileSync(sidecar, JSON.stringify(event) + "\n", "utf-8");
     if (process.platform !== "win32") {
-      try { chmodSync(currentSidecar, 0o600); } catch (error) { if (errCode(error) !== "ENOENT") console.error("Failed to secure anchor registry sidecar:", error); }
+      try { chmodSync(sidecar, 0o600); } catch (error) { if (errCode(error) !== "ENOENT") console.error("Failed to secure anchor registry sidecar:", error); }
     }
   } catch (error) {
     console.error("Failed to append registry event:", error);
@@ -331,15 +521,16 @@ export function ownersForPath(path: string): Map<string, string> {
 }
 
 export function ensureRegistry(): void {
-  if (currentKey && registries.has(currentKey)) return;
+  const key = activeKey();
+  if (key && registries.has(key)) return;
   initRegistry(undefined).catch(() => undefined);
 }
 
-function cloneState(state: SessionState): SessionState {
+export function shadowStateFrom(state: SessionState): SessionState {
 	return {
-		owned: new Map(state.owned),
-		served: new Map([...state.served].map(([path, served]) => [path, new Map(served)])),
-		everMinted: new Set(state.everMinted),
+		owned: new ShadowOwnedMap(state.owned),
+		served: new Map(),
+		everMinted: new ShadowMintedSet(state.everMinted),
 		probe: state.probe,
 	};
 }
@@ -416,7 +607,7 @@ export function alignOwnershipWithSpans(
   spans: { start: number; end: number; replacementCount: number }[],
   options?: { shadow?: boolean },
 ): Aligned {
-  const state = options?.shadow ? cloneState(current()!) : current()!;
+  const state = options?.shadow ? shadowStateFrom(current()!) : current()!;
   const freed: { anchor: string; checksum: string }[] = [];
   const minted: MintedAt[] = [];
   const log = (event: RegistryEvent): void => {
@@ -485,10 +676,11 @@ export function alignOwnership(
   newChecksums: string[],
   options?: { shadow?: boolean },
 ): Aligned {
-  const state = options?.shadow ? cloneState(current()!) : current()!;
+  const state = options?.shadow ? shadowStateFrom(current()!) : current()!;
   const anchors: string[] = new Array(newChecksums.length);
   const freed: { anchor: string; checksum: string }[] = [];
   const minted: MintedAt[] = [];
+  const adopted: string[] = [];
   const log = (event: RegistryEvent): void => {
     if (!options?.shadow) appendEvent(event);
   };
@@ -531,6 +723,7 @@ export function alignOwnership(
           state.owned.set(fresh, { path, checksum });
           anchors[newIdx + k] = fresh;
         } else {
+          if (!entry) adopted.push(anchor);
           state.owned.set(anchor, { path, checksum });
           anchors[newIdx + k] = anchor;
         }
@@ -544,7 +737,8 @@ export function alignOwnership(
   for (let i = 0; i < anchors.length; i++) {
     rows.push([anchors[i]!, newChecksums[i]!]);
   }
-  if (minted.length > 0) log({ kind: "allocate", path, rows: rows.filter(([anchor]) => minted.some((m) => m.anchor === anchor)) });
+  const logged = new Set<string>([...minted.map((m) => m.anchor), ...adopted]);
+  if (logged.size > 0) log({ kind: "allocate", path, rows: rows.filter(([anchor]) => logged.has(anchor)) });
   if (freed.length > 0) log({ kind: "free", path, anchors: freed.map((f) => f.anchor) });
   return { anchors, freed: freed.map((f) => f.anchor), minted: minted.map((m) => m.anchor) };
 }
@@ -589,7 +783,7 @@ export async function allocateFileAnchors(
   const aligned: Aligned = prevAnchors
     ? alignOwnership(path, prevAnchors, prevChecksums, checksums, { shadow })
     : (() => {
-        const state = shadow ? cloneState(current()!) : current()!;
+        const state = shadow ? shadowStateFrom(current()!) : current()!;
         const reuseIndex = fingerprintIndex(state, path);
         const reuseTaken = new Map<string, number>();
         const anchors: string[] = checksums.map((checksum) => {
@@ -620,21 +814,54 @@ export function adoptAnchors(path: string, entries: Map<string, string>): void {
 		served = new Map();
 		state.served.set(path, served);
 	}
+	const adopted: Array<[string, string]> = [];
 	for (const [anchor, checksum] of entries) {
+		const existing = state.owned.get(anchor);
+		if (existing && existing.path !== path) continue;
 		state.owned.set(anchor, { path, checksum });
 		served.set(anchor, checksum);
+		adopted.push([anchor, checksum]);
 	}
-	if (entries.size > 0) {
-		appendEvent({ kind: "allocate", path, rows: [...entries] });
+	if (adopted.length > 0) {
+		appendEvent({ kind: "allocate", path, rows: adopted });
 	}
 }
 
 export function resetRegistryForTests(): void {
   currentKey = undefined;
-  currentSidecar = undefined;
+  sidecarByKey.clear();
+  pendingInits.clear();
+  loadTokens.clear();
   registries.clear();
 }
 
+export async function readSidecarHeader(sidecar: string): Promise<string> {
+  const handle = await open(sidecar, "r");
+  const buffer = Buffer.alloc(SIDECAR_HEADER_BYTES);
+  try {
+    let readBytes = 0;
+    while (readBytes < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, readBytes, Math.min(SIDECAR_HEADER_CHUNK, buffer.length - readBytes), readBytes);
+      if (bytesRead === 0) break;
+      readBytes += bytesRead;
+      const text = buffer.subarray(0, readBytes).toString("utf-8");
+      const newline = text.indexOf("\n");
+      if (newline >= 0) return text.slice(0, newline);
+    }
+    return buffer.subarray(0, readBytes).toString("utf-8");
+  } finally {
+    await handle.close();
+  }
+}
+
+export function releaseRegistrySession(key: string): void {
+  loadTokens.delete(key);
+  if (currentKey === key) currentKey = undefined;
+  pendingInits.delete(key);
+  sidecarByKey.delete(key);
+  registries.delete(key);
+}
+
 export async function gcRegistrySidecars(): Promise<void> {
   let names: string[];
   try {
@@ -657,8 +884,7 @@ export async function gcRegistrySidecars(): Promise<void> {
     if (!name.endsWith(SIDECAR_SUFFIX)) continue;
     const sidecar = join(sessionClaimsDir(), name);
     try {
-      const raw = await readFile(sidecar, "utf-8");
-      const header = JSON.parse(raw.split("\n")[0] ?? "{}") as { kind?: string; sessionFile?: string };
+      const header = JSON.parse(await readSidecarHeader(sidecar) || "{}") as { kind?: string; sessionFile?: string };
       if (header.kind !== "session" || !header.sessionFile) continue;
       await stat(header.sessionFile);
     } catch (error) {

package/src/constants.ts

@@ -13,6 +13,9 @@ export const HASH_STORE_VERSION = 8;
 export const NEW_CONTENT_NOT_ARRAY_MSG =
   `[E_BAD_SHAPE] "replacement_lines" must be an array of strings, one per line (use [] to delete).`;
 
+export const NUL_CONTENT_MSG =
+  `[E_BAD_SHAPE] Content contains a NUL byte (U+0000); a text file cannot contain NUL, and writing it would break further reads and edits. Remove the NUL byte and retry. An empty replacement ([]) deletes a range or inserts nothing.`;
+
 export const ANCHOR_POOL_EXHAUSTED_PREFIX =
   "[E_FILE_TOO_LARGE] The session's anchor pool is exhausted";