@nanhara/hara 0.122.0 → 0.122.1

package/dist/fs-read.js

@@ -1,7 +1,9 @@
 // Bounded streaming line reader for files too large to load as one string. It stores only the requested
 // window and a capped prefix of each line, so huge logs/JSONL and minified one-line files stay safe.
-import { closeSync, constants, fstatSync, openSync, readSync } from "node:fs";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync, statSync, } from "node:fs";
 import { open } from "node:fs/promises";
+import { StringDecoder } from "node:string_decoder";
+import { sensitiveFileError } from "./security/sensitive-files.js";
 export class BinaryFileError extends Error {
     constructor(path) {
         super(`${path} appears to be binary (NUL byte detected)`);
@@ -31,6 +33,306 @@ const MAX_SLICE_LINES = 2_000;
 export const MAX_EDIT_READ_BYTES = 64 * 1024 * 1024;
 const READ_CHUNK_BYTES = 64 * 1024;
 const MAX_PREFIX_CHARS = 1_000_000;
+/** A context-loader rejected a protected path before any bytes could enter a model prompt. */
+export class ProtectedContextFileError extends Error {
+    code = "HARA_PROTECTED_CONTEXT_FILE";
+    constructor(message) {
+        super(message);
+        this.name = "ProtectedContextFileError";
+    }
+}
+export class HardLinkedFileError extends Error {
+    code = "HARA_HARD_LINKED_FILE";
+    constructor(path) {
+        super(`${path} has multiple hard links; its protected identity cannot be established safely`);
+        this.name = "HardLinkedFileError";
+    }
+}
+/** Resolve a user-facing path once, checking both its lexical name and canonical target. Direct tools then
+ * open this canonical path with O_NOFOLLOW, so a safe symlink remains usable without a retarget race. */
+export function resolveVerifiedModelPath(path, action = "read") {
+    const denied = sensitiveFileError(path, action);
+    if (denied)
+        throw new ProtectedContextFileError(denied);
+    const canonical = realpathSync.native(path);
+    const targetDenied = sensitiveFileError(canonical, action);
+    if (targetDenied)
+        throw new ProtectedContextFileError(targetDenied);
+    return canonical;
+}
+/**
+ * Common post-open identity check for security-sensitive readers. `opened` MUST be the fstat result for an
+ * O_NOFOLLOW descriptor. It verifies that the current lexical/canonical name still identifies that inode,
+ * rejects hard-link aliases by default, and applies the central protected-file policy to the actual target.
+ */
+export function verifyOpenedRegularFileSync(path, opened, options = {}) {
+    if (!opened.isFile())
+        throw new NonRegularFileError(path);
+    if (options.rejectHardLinks !== false && opened.nlink > 1)
+        throw new HardLinkedFileError(path);
+    const canonical = realpathSync.native(path);
+    if (options.protectSensitive !== false) {
+        const targetDenied = sensitiveFileError(canonical, options.action ?? "read");
+        if (targetDenied)
+            throw new ProtectedContextFileError(targetDenied);
+    }
+    const currentLink = lstatSync(path);
+    const currentTarget = statSync(canonical);
+    if (currentLink.isSymbolicLink()
+        || currentLink.dev !== opened.dev
+        || currentLink.ino !== opened.ino
+        || currentTarget.dev !== opened.dev
+        || currentTarget.ino !== opened.ino) {
+        throw new Error(`refusing to access ${path}: path changed while opening it`);
+    }
+    return canonical;
+}
+/** Open + validate a regular file for direct tools that need to keep reading the verified descriptor. */
+export async function openVerifiedRegularFileNoFollow(path, options = {}) {
+    if (options.protectSensitive !== false) {
+        const denied = sensitiveFileError(path, options.action ?? "read");
+        if (denied)
+            throw new ProtectedContextFileError(denied);
+    }
+    const before = lstatSync(path);
+    if (before.isSymbolicLink())
+        throw new NonRegularFileError(path);
+    const noFollow = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
+    const handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK | noFollow);
+    try {
+        const info = await handle.stat();
+        const canonicalPath = verifyOpenedRegularFileSync(path, info, options);
+        return { handle, info, canonicalPath };
+    }
+    catch (error) {
+        await handle.close().catch(() => { });
+        throw error;
+    }
+}
+/** Materialize a direct-tool pre-read from a verified descriptor. Safe symlinks should be canonicalized by
+ * `resolveVerifiedModelPath` first; hard-linked aliases are rejected because their protected origin cannot be
+ * inferred from the opened pathname alone. */
+export async function readVerifiedRegularFileSnapshot(path, maxBytes = MAX_EDIT_READ_BYTES, action = "read") {
+    const limit = checkedContextLimit(maxBytes);
+    const verified = await openVerifiedRegularFileNoFollow(path, { action, rejectHardLinks: true, protectSensitive: true });
+    try {
+        const { handle, info } = verified;
+        if (info.size > limit)
+            throw new FileReadLimitError(path, limit);
+        const chunks = [];
+        let total = 0;
+        let position = 0;
+        while (total <= limit) {
+            const want = Math.min(READ_CHUNK_BYTES, limit + 1 - total);
+            const buffer = Buffer.allocUnsafe(want);
+            const { bytesRead } = await handle.read(buffer, 0, want, position);
+            if (!bytesRead)
+                break;
+            chunks.push(buffer.subarray(0, bytesRead));
+            total += bytesRead;
+            position += bytesRead;
+        }
+        if (total > limit)
+            throw new FileReadLimitError(path, limit);
+        const latest = await handle.stat();
+        verifyOpenedRegularFileSync(path, latest, { action, rejectHardLinks: true, protectSensitive: true });
+        if (latest.dev !== info.dev
+            || latest.ino !== info.ino
+            || latest.size !== info.size
+            || latest.mtimeMs !== info.mtimeMs
+            || latest.ctimeMs !== info.ctimeMs)
+            throw new Error(`refusing to read ${path}: file changed while reading it`);
+        return {
+            text: Buffer.concat(chunks, total).toString("utf8"),
+            dev: info.dev,
+            ino: info.ino,
+            mode: info.mode & 0o777,
+            nlink: info.nlink,
+        };
+    }
+    finally {
+        await verified.handle.close().catch(() => { });
+    }
+}
+/** Synchronous counterpart for startup/configuration paths that cannot make their public API async. It
+ * validates and reads the same O_NOFOLLOW descriptor, rejects aliases with multiple hard links, bounds the
+ * allocation, and verifies identity/metadata again after the read. Internal state readers may explicitly
+ * disable the model-facing protected-file policy while retaining every filesystem identity check. */
+export function readVerifiedRegularFileSnapshotSync(path, maxBytes = MAX_EDIT_READ_BYTES, options = {}) {
+    const action = options.action ?? "read";
+    if (options.protectSensitive !== false) {
+        const denied = sensitiveFileError(path, action);
+        if (denied)
+            throw new ProtectedContextFileError(denied);
+    }
+    const before = lstatSync(path);
+    if (before.isSymbolicLink())
+        throw new NonRegularFileError(path);
+    const noFollow = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK | noFollow);
+    try {
+        const info = fstatSync(fd);
+        verifyOpenedRegularFileSync(path, info, {
+            action,
+            rejectHardLinks: options.rejectHardLinks !== false,
+            protectSensitive: options.protectSensitive !== false,
+        });
+        const limit = checkedContextLimit(maxBytes);
+        if (info.size > limit)
+            throw new FileReadLimitError(path, limit);
+        const bytes = readFdBytesSync(fd, Math.min(limit + 1, info.size + 1));
+        if (bytes.length > limit)
+            throw new FileReadLimitError(path, limit);
+        const latest = fstatSync(fd);
+        verifyOpenedRegularFileSync(path, latest, {
+            action,
+            rejectHardLinks: options.rejectHardLinks !== false,
+            protectSensitive: options.protectSensitive !== false,
+        });
+        if (latest.dev !== info.dev
+            || latest.ino !== info.ino
+            || latest.size !== info.size
+            || latest.mtimeMs !== info.mtimeMs
+            || latest.ctimeMs !== info.ctimeMs)
+            throw new Error(`refusing to read ${path}: file changed while reading it`);
+        return {
+            text: bytes.toString("utf8"),
+            dev: info.dev,
+            ino: info.ino,
+            mode: info.mode & 0o777,
+            nlink: info.nlink,
+        };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Open a model-context source without following its final component, validate the SAME descriptor, and
+ * re-check the canonical target against the central protected-file policy. The identity comparison closes
+ * the ordinary validate-then-open race: if the pathname is exchanged while it is being inspected, callers
+ * get an error rather than bytes from an unverified inode.
+ *
+ * This is intentionally synchronous because AGENTS/skills/roles/memory are assembled synchronously before
+ * a provider turn. Keep the reader callback small and bounded.
+ */
+function withVerifiedContextFdSync(path, read) {
+    const denied = sensitiveFileError(path, "load into model context");
+    if (denied)
+        throw new ProtectedContextFileError(denied);
+    // O_NOFOLLOW is not exposed on every platform. The before/after lstat checks retain fail-closed symlink
+    // behaviour there; on POSIX O_NOFOLLOW makes the critical open itself atomic.
+    const noFollow = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
+    const before = lstatSync(path);
+    if (before.isSymbolicLink())
+        throw new NonRegularFileError(path);
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK | noFollow);
+    try {
+        const info = fstatSync(fd);
+        verifyOpenedRegularFileSync(path, info, {
+            action: "load into model context",
+            rejectHardLinks: true,
+            protectSensitive: true,
+        });
+        const result = read(fd, info.size);
+        const latest = fstatSync(fd);
+        verifyOpenedRegularFileSync(path, latest, {
+            action: "load into model context",
+            rejectHardLinks: true,
+            protectSensitive: true,
+        });
+        if (latest.dev !== info.dev
+            || latest.ino !== info.ino
+            || latest.size !== info.size
+            || latest.mtimeMs !== info.mtimeMs
+            || latest.ctimeMs !== info.ctimeMs)
+            throw new Error(`refusing to read ${path}: file changed while reading it`);
+        return result;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function checkedContextLimit(maxBytes) {
+    const requested = Number.isFinite(maxBytes) ? Math.floor(maxBytes) : MAX_EDIT_READ_BYTES;
+    return Math.min(MAX_EDIT_READ_BYTES, Math.max(1, requested));
+}
+function readFdBytesSync(fd, count) {
+    const out = Buffer.allocUnsafe(count);
+    let offset = 0;
+    while (offset < count) {
+        const n = readSync(fd, out, offset, count - offset, offset);
+        if (n === 0)
+            break;
+        offset += n;
+    }
+    return out.subarray(0, offset);
+}
+/** Safely materialize a bounded UTF-8 context file. Oversized or binary inputs fail closed. */
+export function readModelContextFileSync(path, maxBytes) {
+    const limit = checkedContextLimit(maxBytes);
+    return withVerifiedContextFdSync(path, (fd, size) => {
+        if (size > limit)
+            throw new FileReadLimitError(path, limit);
+        // Read one byte past the stated size/limit so concurrent growth is never silently included or ignored.
+        const bytes = readFdBytesSync(fd, Math.min(limit + 1, size + 1));
+        if (bytes.length > limit)
+            throw new FileReadLimitError(path, limit);
+        if (bytes.includes(0))
+            throw new BinaryFileError(path);
+        return bytes.toString("utf8");
+    });
+}
+/** Safe bounded-prefix counterpart for @file expansion; it never materializes the remainder of a huge file. */
+export function readModelContextPrefixSync(path, maxChars) {
+    const requested = Number.isFinite(maxChars) ? Math.floor(maxChars) : MAX_PREFIX_CHARS;
+    const chars = Math.min(MAX_PREFIX_CHARS, Math.max(0, requested));
+    return withVerifiedContextFdSync(path, (fd, size) => {
+        const byteLimit = Math.min(size, chars * 4 + 4);
+        const bytes = readFdBytesSync(fd, byteLimit);
+        const binary = bytes.subarray(0, Math.min(bytes.length, 4096)).includes(0);
+        const decoded = binary ? "" : bytes.toString("utf8");
+        return {
+            text: decoded.slice(0, chars),
+            truncated: size > bytes.length || decoded.length > chars,
+            binary,
+        };
+    });
+}
+function utf8BytePrefix(value, maxBytes) {
+    if (Buffer.byteLength(value, "utf8") <= maxBytes)
+        return value;
+    let used = 0;
+    let end = 0;
+    for (const char of value) {
+        const bytes = Buffer.byteLength(char, "utf8");
+        if (used + bytes > maxBytes)
+            break;
+        used += bytes;
+        end += char.length;
+    }
+    return value.slice(0, end);
+}
+/**
+ * Verified byte-budgeted prefix reader for project instructions. Unlike `readModelContextFileSync`, an
+ * oversized text file keeps its useful beginning instead of disappearing from model context. The returned
+ * text is always at most `maxBytes` UTF-8 bytes and never ends with half of a multibyte code point.
+ */
+export function readModelContextBytePrefixSync(path, maxBytes) {
+    const limit = checkedContextLimit(maxBytes);
+    return withVerifiedContextFdSync(path, (fd, size) => {
+        const bytes = readFdBytesSync(fd, Math.min(size, limit));
+        const binary = bytes.subarray(0, Math.min(bytes.length, 4096)).includes(0);
+        if (binary)
+            return { text: "", truncated: size > bytes.length, binary: true };
+        // StringDecoder buffers an incomplete UTF-8 suffix when the file continues past this prefix. This
+        // avoids injecting U+FFFD merely because the byte budget happened to split a multibyte character.
+        const decoder = new StringDecoder("utf8");
+        const decoded = size > bytes.length ? decoder.write(bytes) : decoder.end(bytes);
+        const text = utf8BytePrefix(decoded, limit);
+        return { text, truncated: size > bytes.length || text.length < decoded.length, binary: false };
+    });
+}
 /** Open without blocking on a FIFO, validate the SAME descriptor, then read at most maxBytes from it.
  * Path-level stat→readFile is unsafe because the path can be exchanged for a pipe/device between calls. */
 async function readRegularFileSnapshotWithFlags(path, maxBytes, flags) {
@@ -180,10 +482,13 @@ export async function streamFileSlice(path, offset = 1, limit = 300, options = {
     };
     // Keep validation and streaming on the same non-blocking descriptor. This closes the stat→open race
     // where an attacker/local generator exchanges a regular path for a FIFO after validation.
-    const handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    const verified = options.protectSensitive
+        ? await openVerifiedRegularFileNoFollow(path, { action: "read", rejectHardLinks: true, protectSensitive: true })
+        : null;
+    const handle = verified?.handle ?? await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
     let stream;
     try {
-        const info = await handle.stat();
+        const info = verified?.info ?? await handle.stat();
         if (!info.isFile())
             throw new NonRegularFileError(path);
         // `end` is an inclusive byte offset. It makes the scan ceiling a true fd-level byte bound (not just
@@ -226,6 +531,16 @@ export async function streamFileSlice(path, offset = 1, limit = 300, options = {
                     finishLine(true);
             }
         }
+        if (verified) {
+            const latest = await handle.stat();
+            verifyOpenedRegularFileSync(path, latest, { action: "read", rejectHardLinks: true, protectSensitive: true });
+            if (latest.dev !== info.dev
+                || latest.ino !== info.ino
+                || latest.size !== info.size
+                || latest.mtimeMs !== info.mtimeMs
+                || latest.ctimeMs !== info.ctimeMs)
+                throw new Error(`refusing to read ${path}: file changed while reading it`);
+        }
     }
     finally {
         stream?.destroy();

package/dist/fs-walk.js

@@ -4,6 +4,8 @@ import { readdirSync, statSync } from "node:fs";
 import { join, relative, sep } from "node:path";
 import { execSync } from "node:child_process";
 import { fuzzyRank } from "./fuzzy.js";
+import { isSensitiveFilePath } from "./security/sensitive-files.js";
+import { toolSubprocessEnv } from "./security/subprocess-env.js";
 export const IGNORE_DIRS = new Set([
     ".git", "node_modules", "dist", "build", "out", ".next", ".nuxt", ".cache",
     "coverage", ".venv", "venv", "__pycache__", ".mypy_cache", ".pytest_cache",
@@ -36,7 +38,10 @@ export function walkFiles(root, cap = 8000) {
                 stack.push(join(dir, e.name));
             }
             else if (e.isFile()) {
-                files.push(toPosix(relative(root, join(dir, e.name))));
+                const absolute = join(dir, e.name);
+                if (isSensitiveFilePath(absolute))
+                    continue;
+                files.push(toPosix(relative(root, absolute)));
             }
         }
     }
@@ -50,6 +55,7 @@ export function listProjectFiles(root, cap = 8000) {
     try {
         const out = execSync("git ls-files --cached --others --exclude-standard", {
             cwd: root,
+            env: toolSubprocessEnv(),
             encoding: "utf8",
             maxBuffer: 32 * 1024 * 1024,
             stdio: ["ignore", "pipe", "ignore"],
@@ -59,7 +65,7 @@ export function listProjectFiles(root, cap = 8000) {
         })
             .split("\n")
             .map((s) => s.trim())
-            .filter(Boolean);
+            .filter((path) => Boolean(path) && !isSensitiveFilePath(join(root, path)));
         if (out.length)
             return out.slice(0, cap);
     }

package/dist/fs-write.js

@@ -1,10 +1,11 @@
 // Crash-safe UTF-8 writes for coding tools. Content is staged beside the destination, fsynced, then
 // renamed into place so a killed process never leaves a half-written source file.
 import { randomUUID } from "node:crypto";
-import { basename, dirname, join } from "node:path";
-import { constants, linkSync, lstatSync, readlinkSync, renameSync, symlinkSync, unlinkSync } from "node:fs";
-import { link, lstat, mkdir, open, realpath, rename, rmdir, stat, unlink } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { constants, linkSync, lstatSync, readlinkSync, realpathSync, renameSync, symlinkSync, unlinkSync } from "node:fs";
+import { lstat, mkdir, open, realpath, rmdir, stat } from "node:fs/promises";
 import { NonRegularFileError, readRegularFileSnapshotNoFollow } from "./fs-read.js";
+import { canonicalizeProspectivePath, lexicalSensitiveFileReason, sensitiveFileError, } from "./security/sensitive-files.js";
 export class FileChangedError extends Error {
     code = "HARA_FILE_CHANGED";
     constructor(path) {
@@ -13,6 +14,145 @@ export class FileChangedError extends Error {
     }
 }
 let tempSequence = 0;
+// Internal Hara control-plane writers need the same identity/CAS guarantees as coding tools, but the
+// public protected-file policy intentionally rejects those destinations. Keep exemptions as object identity
+// rather than a forgeable boolean on AtomicWriteBoundary: only the narrow, destination-specific binders below
+// can mint one.
+const privateStateBoundaries = new WeakSet();
+function protectedWriteError(path, action) {
+    const denied = sensitiveFileError(path, action);
+    return denied ? new Error(denied) : null;
+}
+function verifyDirectoryIdentity(boundary) {
+    const current = lstatSync(boundary.ancestor.path);
+    const canonical = realpathSync.native(boundary.ancestor.path);
+    if (!current.isDirectory()
+        || current.isSymbolicLink()
+        || current.dev !== boundary.ancestor.dev
+        || current.ino !== boundary.ancestor.ino
+        || canonical !== boundary.ancestor.path)
+        throw new FileChangedError(boundary.target);
+}
+export function verifyAtomicWriteBoundary(boundary) {
+    verifyDirectoryIdentity(boundary);
+    if (!privateStateBoundaries.has(boundary)) {
+        const denied = protectedWriteError(boundary.target, boundary.action);
+        if (denied)
+            throw denied;
+    }
+}
+/**
+ * Bind one internal private-Hara-state file below a directory whose symlink-free construction and mode
+ * were already verified by the caller. The exemption cannot be used for `.env`/credential files or an
+ * arbitrary descendant: the target must be an immediate child classified specifically as Hara state.
+ */
+export function bindHaraPrivateStateWritePath(path, stateDir, action) {
+    const dir = resolve(stateDir);
+    const target = resolve(path);
+    if (dirname(target) !== dir)
+        throw new Error(`private Hara state target must be an immediate child of ${dir}`);
+    if (lexicalSensitiveFileReason(target) !== "private Hara state") {
+        throw new Error(`refusing private Hara state exemption for ${target}`);
+    }
+    const canonical = realpathSync.native(dir);
+    const info = lstatSync(dir);
+    if (!info.isDirectory() || info.isSymbolicLink() || canonical !== dir) {
+        throw new Error(`refusing private Hara state write: '${dir}' is not a canonical directory`);
+    }
+    const boundary = {
+        target,
+        action,
+        ancestor: { path: dir, dev: info.dev, ino: info.ino },
+    };
+    privateStateBoundaries.add(boundary);
+    verifyAtomicWriteBoundary(boundary);
+    return boundary;
+}
+/** Bind the personal identity pin without granting a general protected-file bypass. The final directory
+ * entry is deliberately not resolved: callers can no-follow inspect it and atomic CAS will reject any
+ * symlink or replacement that appears after preflight. */
+export function bindProfilePinWritePath(path, action = "write profile pin") {
+    const requested = resolve(path);
+    if (basename(requested) !== ".hara-profile")
+        throw new Error("profile pin target must be named .hara-profile");
+    const parent = realpathSync.native(dirname(requested));
+    const target = join(parent, basename(requested));
+    if (lexicalSensitiveFileReason(target) !== "private Hara routing state") {
+        throw new Error(`refusing profile pin exemption for ${target}`);
+    }
+    const info = lstatSync(parent);
+    if (!info.isDirectory() || info.isSymbolicLink())
+        throw new Error(`${parent} is not a canonical directory`);
+    const boundary = {
+        target,
+        action,
+        ancestor: { path: parent, dev: info.dev, ino: info.ino },
+    };
+    privateStateBoundaries.add(boundary);
+    verifyAtomicWriteBoundary(boundary);
+    return boundary;
+}
+/** Bind a directory entry while preserving its final symlink topology (used by transactional deletes). */
+export function bindAtomicParentEntryPath(path, action = "write") {
+    const lexicalDenied = protectedWriteError(path, action);
+    if (lexicalDenied)
+        throw lexicalDenied;
+    const requested = resolve(path);
+    const parent = realpathSync.native(dirname(requested));
+    const target = join(parent, basename(requested));
+    const canonicalDenied = protectedWriteError(target, action);
+    if (canonicalDenied)
+        throw canonicalDenied;
+    const info = lstatSync(parent);
+    if (!info.isDirectory() || info.isSymbolicLink())
+        throw new Error(`${parent} is not a directory`);
+    const boundary = {
+        target,
+        action,
+        ancestor: { path: parent, dev: info.dev, ino: info.ino },
+    };
+    verifyAtomicWriteBoundary(boundary);
+    return boundary;
+}
+/**
+ * Bind a direct coding-tool path to one canonical candidate and the nearest existing parent directory.
+ * Missing tail directories remain below that identity; a parent symlink retarget or directory replacement
+ * between preflight and commit therefore fails instead of silently selecting another tree.
+ */
+export function bindAtomicWritePath(path, action = "write") {
+    const lexicalDenied = protectedWriteError(path, action);
+    if (lexicalDenied)
+        throw lexicalDenied;
+    const target = canonicalizeProspectivePath(path);
+    const canonicalDenied = protectedWriteError(target, action);
+    if (canonicalDenied)
+        throw canonicalDenied;
+    let current = dirname(target);
+    for (let depth = 0; depth < 128; depth++) {
+        try {
+            const canonical = realpathSync.native(current);
+            const info = lstatSync(canonical);
+            if (!info.isDirectory() || info.isSymbolicLink())
+                throw new Error(`${canonical} is not a directory`);
+            const boundary = {
+                target,
+                action,
+                ancestor: { path: canonical, dev: info.dev, ino: info.ino },
+            };
+            verifyAtomicWriteBoundary(boundary);
+            return boundary;
+        }
+        catch (error) {
+            if (error?.code !== "ENOENT" && error?.code !== "ENOTDIR")
+                throw error;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            throw new Error(`cannot bind parent directory for ${path}`);
+        current = parent;
+    }
+    throw new Error(`write path exceeds 128 components: ${path}`);
+}
 async function writeTarget(path) {
     try {
         const info = await lstat(path);
@@ -172,6 +312,11 @@ async function syncDirectory(path) {
 }
 /** Atomically replace/create a UTF-8 file, optionally refusing to overwrite a newer disk version. */
 export async function atomicWriteText(path, content, options = {}) {
+    if (options.boundary) {
+        if (resolve(path) !== resolve(options.boundary.target))
+            throw new FileChangedError(path);
+        verifyAtomicWriteBoundary(options.boundary);
+    }
     let target = await writeTarget(path);
     let dir = dirname(target);
     const createdDirs = [];
@@ -181,6 +326,25 @@ export async function atomicWriteText(path, content, options = {}) {
     // later transaction steps to a different tree.
     dir = await realpath(dir);
     target = join(dir, basename(target));
+    if (options.boundary) {
+        if (target !== options.boundary.target)
+            throw new FileChangedError(path);
+        verifyAtomicWriteBoundary(options.boundary);
+    }
+    const parentInfo = await lstat(dir);
+    if (!parentInfo.isDirectory() || parentInfo.isSymbolicLink())
+        throw new FileChangedError(dir);
+    const parentBoundary = {
+        target,
+        action: options.boundary?.action ?? "write",
+        ancestor: { path: dir, dev: parentInfo.dev, ino: parentInfo.ino },
+    };
+    const verifyCommitParent = () => {
+        verifyDirectoryIdentity(parentBoundary);
+        if (options.boundary)
+            verifyAtomicWriteBoundary(options.boundary);
+    };
+    verifyCommitParent();
     // A caller-provided preflight identity is authoritative. Reading mode from a path before the move-claim
     // would let a temporary same-path replacement influence the mode even when the expected inode is restored
     // before claim verification.
@@ -209,6 +373,8 @@ export async function atomicWriteText(path, content, options = {}) {
         const handle = await open(temp, "wx", mode);
         staged = true;
         try {
+            const opened = await handle.stat();
+            writtenIdentity = { dev: opened.dev, ino: opened.ino, mode: opened.mode & 0o777, nlink: opened.nlink };
             await handle.writeFile(content, "utf8");
             // open(2) applies the process umask even when replacing an existing file. Restore that existing (or
             // explicit rollback) mode on the staged fd; brand-new ordinary files still honor the user's umask.
@@ -225,14 +391,17 @@ export async function atomicWriteText(path, content, options = {}) {
             // link(2) is an atomic create-if-absent operation. A plain rename would overwrite a file that
             // appeared after validation, defeating create's no-clobber contract.
             try {
-                await link(temp, target);
+                // Keep the final parent-identity check and namespace mutation in one JS turn. Node has no portable
+                // openat/linkat API; synchronous link is the narrowest available commit boundary.
+                verifyCommitParent();
+                linkSync(temp, target);
             }
             catch (error) {
                 if (error?.code === "EEXIST")
                     throw new FileChangedError(path);
                 throw error;
             }
-            await unlink(temp);
+            unlinkSync(temp);
             staged = false;
         }
         else if (typeof options.expected === "string") {
@@ -240,7 +409,8 @@ export async function atomicWriteText(path, content, options = {}) {
             // path leaves a verify→commit race; a concurrent replacement can otherwise be silently destroyed.
             const claimed = join(dir, `.hara-claim-${process.pid}-${randomUUID()}.tmp`);
             try {
-                await rename(target, claimed);
+                verifyCommitParent();
+                renameSync(target, claimed);
             }
             catch (error) {
                 if (error?.code === "ENOENT")
@@ -289,11 +459,13 @@ export async function atomicWriteText(path, content, options = {}) {
             if (!claimedIdentity)
                 throw new Error(`Failed to identify claimed file for ${path}`);
             try {
-                await link(temp, target); // atomic create-if-absent: never overwrites an entry created after claim.
+                verifyCommitParent();
+                linkSync(temp, target); // atomic create-if-absent: never overwrites an entry created after claim.
             }
             catch (error) {
                 let recovery = "";
                 try {
+                    verifyCommitParent();
                     restoreClaimedPath(claimed, target, claimedIdentity);
                 }
                 catch (restoreError) {
@@ -303,9 +475,10 @@ export async function atomicWriteText(path, content, options = {}) {
                     throw new Error(`${new FileChangedError(path).message}${recovery}`);
                 throw new Error(`${error?.message ?? String(error)}${recovery}`, { cause: error });
             }
-            await unlink(temp);
+            unlinkSync(temp);
             staged = false;
             try {
+                verifyCommitParent();
                 discardClaimedPath(claimed, claimedIdentity);
             }
             catch (error) {
@@ -313,15 +486,28 @@ export async function atomicWriteText(path, content, options = {}) {
             }
         }
         else {
-            await rename(temp, target);
+            verifyCommitParent();
+            renameSync(temp, target);
             staged = false;
         }
         await syncDirectory(dir);
         succeeded = true;
     }
     finally {
-        if (staged)
-            await unlink(temp).catch(() => { });
+        if (staged && writtenIdentity) {
+            try {
+                verifyCommitParent();
+                const current = lstatSync(temp);
+                if (current.isFile()
+                    && current.dev === writtenIdentity.dev
+                    && current.ino === writtenIdentity.ino)
+                    unlinkSync(temp);
+            }
+            catch {
+                // A changed parent makes path-based cleanup unsafe. Retaining an unpredictable private staging file
+                // is preferable to unlinking an entry supplied by a concurrent actor.
+            }
+        }
         if (!succeeded)
             await removeCreatedDirectories(createdDirs).catch(() => { });
     }