@nanhara/hara 0.123.1 → 0.124.1

package/dist/plugins/plugins.js

@@ -2,11 +2,11 @@
 // runtime. The existing loaders pick the contents up (skillsDirs/loadRoles append the resolvers below;
 // index.ts merges pluginMcpServers into the MCP set). Manifest is Claude-Code-compatible: we read
 // .claude-plugin/plugin.json, .hara-plugin/plugin.json, or a bare plugin.json at the plugin root.
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, rmSync, cpSync, symlinkSync, chmodSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync, readdirSync, rmSync, cpSync, symlinkSync, chmodSync } from "node:fs";
 import { join, resolve, isAbsolute } from "node:path";
 import { homedir } from "node:os";
 import { execFileSync } from "node:child_process";
-import { readRawConfig } from "../config.js";
+import { readRawConfig, updateRawConfig } from "../config.js";
 export function pluginsDir() {
     return join(homedir(), ".hara", "plugins");
 }
@@ -193,11 +193,9 @@ export function panelsForProject(cwd) {
 }
 /** Persist a plugin's enabled flag in ~/.hara/config.json (`plugins.enabled[name]`). */
 export function setPluginEnabled(name, on) {
-    const p = join(homedir(), ".hara", "config.json");
-    const cfg = readRawConfig();
-    const plugins = (cfg.plugins && typeof cfg.plugins === "object" ? cfg.plugins : {});
-    plugins.enabled = { ...(plugins.enabled ?? {}), [name]: on };
-    cfg.plugins = plugins;
-    mkdirSync(join(homedir(), ".hara"), { recursive: true });
-    writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+    updateRawConfig((config) => {
+        const plugins = (config.plugins && typeof config.plugins === "object" ? config.plugins : {});
+        plugins.enabled = { ...(plugins.enabled ?? {}), [name]: on };
+        config.plugins = plugins;
+    });
 }

package/dist/profile/profile.js

@@ -32,29 +32,22 @@
 import { homedir } from "node:os";
 import { spawnSync } from "node:child_process";
 import { join, dirname, parse as parsePath, resolve as resolvePath } from "node:path";
-import { readFileSync, writeFileSync, existsSync, lstatSync, mkdirSync, chmodSync, realpathSync, renameSync } from "node:fs";
+import { lstatSync, realpathSync } from "node:fs";
+import { readRawConfig, updateRawConfig } from "../config.js";
 import { readVerifiedRegularFileSnapshotSync } from "../fs-read.js";
 import { atomicWriteText, bindProfilePinWritePath, discardClaimedPath, verifyAtomicWriteBoundary, } from "../fs-write.js";
 import { projectRepositoryTrustedAtStartup } from "../security/project-trust.js";
+import { bindPrivateHaraStateFile, readPrivateStateFileSnapshotSync, removePrivateStateFile, writePrivateStateFileSync, } from "../security/private-state.js";
 const PERSONAL_ID = "personal";
 const DEFAULT_ORG_ID = "default-org";
-function haraDir() {
-    return join(homedir(), ".hara");
-}
-function profilesPath() {
-    return join(haraDir(), "profiles.json");
-}
-function configPath() {
-    return join(haraDir(), "config.json");
-}
-function orgPath() {
-    return join(haraDir(), "org.json");
-}
-function readJSON(p) {
-    if (!existsSync(p))
-        return null;
+const MAX_PROFILE_STATE_BYTES = 4 * 1024 * 1024;
+function readPrivateJSON(filename) {
     try {
-        return JSON.parse(readFileSync(p, "utf8"));
+        const binding = bindPrivateHaraStateFile(homedir(), [], filename);
+        const snapshot = readPrivateStateFileSnapshotSync(binding.path, MAX_PROFILE_STATE_BYTES);
+        if (!snapshot)
+            return null;
+        return { binding, snapshot, value: JSON.parse(snapshot.text) };
     }
     catch {
         return null;
@@ -62,20 +55,13 @@ function readJSON(p) {
 }
 /** Write the profiles file 0600 (it can hold device tokens / api keys). */
 function persistProfilesFile(f) {
-    const p = profilesPath();
-    mkdirSync(dirname(p), { recursive: true });
-    writeFileSync(p, JSON.stringify(f, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
-    try {
-        chmodSync(p, 0o600);
-    }
-    catch {
-        /* best-effort */
-    }
+    const binding = bindPrivateHaraStateFile(homedir(), [], "profiles.json");
+    writePrivateStateFileSync(binding, JSON.stringify(f, null, 2) + "\n");
 }
 /** Synthesize the "personal" profile view from the legacy config.json. The config.json itself
  *  stays the *storage* — this just presents it as a Profile object. */
 function readPersonalFromConfig() {
-    const cfg = readJSON(configPath()) ?? {};
+    const cfg = readRawConfig();
     // A legacy user that ran `hara enroll` had their provider written as "hara-gateway" in config.json.
     // After migration that case is handled separately (default-org profile), so when synthesizing the
     // personal profile we coerce a stray "hara-gateway" provider to anthropic (the BYOK default) — the
@@ -97,8 +83,7 @@ function readPersonalFromConfig() {
     };
 }
 /** Synthesize a `default-org` profile from the legacy org.json (Enrollment). */
-function readDefaultOrgFromOrgJson() {
-    const e = readJSON(orgPath());
+function readDefaultOrgFromOrgJson(e) {
     if (!e || !e.gatewayUrl || !e.deviceToken)
         return null;
     const defaultModel = e.model || "";
@@ -117,11 +102,12 @@ function readDefaultOrgFromOrgJson() {
 }
 /** First-time migration. Idempotent — running again is a no-op (profiles.json already present). */
 function maybeMigrate() {
-    const existing = readJSON(profilesPath());
+    const existing = readPrivateJSON("profiles.json")?.value;
     if (existing && Array.isArray(existing.profiles) && existing.profiles.length > 0)
         return existing;
     const personal = readPersonalFromConfig();
-    const org = readDefaultOrgFromOrgJson();
+    const legacyOrg = readPrivateJSON("org.json");
+    const org = readDefaultOrgFromOrgJson(legacyOrg?.value ?? null);
     const profiles = [personal];
     let active = PERSONAL_ID;
     if (org) {
@@ -130,10 +116,13 @@ function maybeMigrate() {
     }
     const f = { active, profiles };
     persistProfilesFile(f);
-    // Park org.json so we never re-migrate. We keep the file (don't delete data), just rename.
-    if (org && existsSync(orgPath())) {
+    // Park the exact verified legacy bytes without ever following/replacing an alias. If archival races or
+    // fails, leave org.json untouched; profiles.json already makes the migration idempotent.
+    if (org && legacyOrg) {
         try {
-            renameSync(orgPath(), orgPath() + ".legacy");
+            const archive = bindPrivateHaraStateFile(homedir(), [], "org.json.legacy");
+            writePrivateStateFileSync(archive, legacyOrg.snapshot.text);
+            removePrivateStateFile(legacyOrg.binding.path, legacyOrg.snapshot, legacyOrg.binding.directory);
         }
         catch {
             /* best-effort */
@@ -531,31 +520,15 @@ export function routeHost(p) {
 // config.ts without circular imports. Implemented inline to avoid pulling config.ts.
 // ────────────────────────────────────────────────────────────────────────────────
 function setModelOnPersonal(model) {
-    const p = configPath();
-    const cfg = readJSON(p) ?? {};
-    cfg.model = model;
-    mkdirSync(dirname(p), { recursive: true });
-    writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
-    try {
-        chmodSync(p, 0o600);
-    }
-    catch {
-        /* best-effort */
-    }
+    updateRawConfig((config) => {
+        config.model = model;
+    });
     return { ok: true };
 }
 function clearModelOnPersonal() {
-    const p = configPath();
-    const cfg = readJSON(p) ?? {};
-    delete cfg.model;
-    mkdirSync(dirname(p), { recursive: true });
-    writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
-    try {
-        chmodSync(p, 0o600);
-    }
-    catch {
-        /* best-effort */
-    }
+    updateRawConfig((config) => {
+        delete config.model;
+    });
     return { ok: true };
 }
 export { PERSONAL_ID, DEFAULT_ORG_ID };

package/dist/providers/qwen-oauth.js

@@ -2,8 +2,7 @@
 // Token (access/refresh/resource_url) is stored in ~/.hara/qwen-oauth.json and auto-refreshed.
 import { createHash, randomBytes } from "node:crypto";
 import { homedir } from "node:os";
-import { join } from "node:path";
-import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from "node:fs";
+import { bindPrivateHaraStateFile, readPrivateStateFileSnapshotSync, writePrivateStateFileSync, } from "../security/private-state.js";
 const BASE = "https://chat.qwen.ai";
 const DEVICE_CODE_URL = `${BASE}/api/v1/oauth2/device/code`;
 const TOKEN_URL = `${BASE}/api/v1/oauth2/token`;
@@ -11,31 +10,19 @@ const CLIENT_ID = "f0304373b74a44d2b584a3fb70ca9e56";
 const SCOPE = "openid profile email model.completion";
 const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
 const DEFAULT_BASE_URL = "https://portal.qwen.ai/v1";
-function tokenPath() {
-    return join(homedir(), ".hara", "qwen-oauth.json");
-}
 export function loadQwenToken() {
-    const p = tokenPath();
-    if (!existsSync(p))
-        return null;
     try {
-        return JSON.parse(readFileSync(p, "utf8"));
+        const binding = bindPrivateHaraStateFile(homedir(), [], "qwen-oauth.json");
+        const snapshot = readPrivateStateFileSnapshotSync(binding.path, 1024 * 1024);
+        return snapshot ? JSON.parse(snapshot.text) : null;
     }
     catch {
         return null;
     }
 }
 function saveQwenToken(t) {
-    const p = tokenPath();
-    mkdirSync(join(homedir(), ".hara"), { recursive: true });
-    // 0600 — the file holds long-lived access + refresh tokens; don't leave it world-readable on shared boxes.
-    writeFileSync(p, JSON.stringify(t, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
-    try {
-        chmodSync(p, 0o600); // tighten an existing file that predated the mode
-    }
-    catch {
-        /* best-effort */
-    }
+    const binding = bindPrivateHaraStateFile(homedir(), [], "qwen-oauth.json");
+    writePrivateStateFileSync(binding, JSON.stringify(t, null, 2) + "\n");
 }
 const b64url = (b) => b.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 function pkce() {

package/dist/security/permissions.js

@@ -16,6 +16,7 @@ import { psArgumentsExposeEnvironment } from "./sensitive-files.js";
 import { projectRepositoryTrustedAtStartup } from "./project-trust.js";
 import { readVerifiedRegularFileSnapshotSync } from "../fs-read.js";
 import { homeWorkspaceActionError, isHomeWorkspace } from "../context/workspace-scope.js";
+import { sameOpenedFileIdentity } from "../fs-identity.js";
 const PROJECT_ROOT_MARKERS = [".git", "package.json", "Cargo.toml", "go.mod", "pyproject.toml", ".hg"];
 const MAX_PROJECT_PERMISSIONS_BYTES = 64 * 1024;
 const projectPermissionWarnings = new Set();
@@ -472,7 +473,7 @@ function scaffoldProjectPermissions(cwd) {
         fd = undefined;
         verifiedDirectory(parent, parentIdentity);
         const staged = lstatSync(temp);
-        if (!staged.isFile() || staged.isSymbolicLink() || staged.dev !== tempIdentity.dev || staged.ino !== tempIdentity.ino) {
+        if (!staged.isFile() || staged.isSymbolicLink() || !sameOpenedFileIdentity(staged, tempIdentity)) {
             throw new Error("refusing project permissions write: staging file identity changed");
         }
         verifiedDirectory(parent, parentIdentity);
@@ -490,7 +491,7 @@ function scaffoldProjectPermissions(cwd) {
         }
         verifiedDirectory(parent, parentIdentity);
         const written = lstatSync(target);
-        if (!written.isFile() || written.isSymbolicLink() || written.dev !== tempIdentity.dev || written.ino !== tempIdentity.ino) {
+        if (!written.isFile() || written.isSymbolicLink() || !sameOpenedFileIdentity(written, tempIdentity)) {
             throw new Error("refusing project permissions write: committed file identity changed");
         }
         unlinkSync(temp);
@@ -507,7 +508,7 @@ function scaffoldProjectPermissions(cwd) {
             try {
                 verifiedDirectory(parent, parentIdentity);
                 const current = lstatSync(temp);
-                if (current.isFile() && current.dev === tempIdentity.dev && current.ino === tempIdentity.ino)
+                if (current.isFile() && sameOpenedFileIdentity(current, tempIdentity))
                     unlinkSync(temp);
             }
             catch {

package/dist/security/private-state.js

@@ -1,10 +1,13 @@
 // Owner-only migration for Hara's local control plane. New writers should still create private files
 // directly, but this repairs installations created by older releases and makes ~/.hara non-traversable by
 // other local users before credentials/session state are read.
-import { closeSync, chmodSync, constants, fchmodSync, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, realpathSync, unlinkSync, } from "node:fs";
+import { closeSync, chmodSync, constants, fchmodSync, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readSync, readdirSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
-import { basename, join, resolve, sep } from "node:path";
-import { FileReadLimitError, MAX_EDIT_READ_BYTES, openVerifiedRegularFileNoFollow, verifyOpenedRegularFileSync, } from "../fs-read.js";
+import { basename, dirname, join, resolve } from "node:path";
+import { FileReadLimitError, MAX_EDIT_READ_BYTES, decodeUtf8Strict, openVerifiedRegularFileNoFollow, verifyOpenedRegularFileSync, } from "../fs-read.js";
+import { optionalPosixOpenFlag } from "../fs-open-flags.js";
+import { sameOpenedFileIdentity } from "../fs-identity.js";
 const PRIVATE_TREES = new Set(["sessions", "checkpoints", "index", "gateway", "cron", "weixin"]);
 const tightenedHomes = new Set();
 const DEFAULT_MIGRATION_CAP = 50_000;
@@ -23,7 +26,12 @@ function chmodPrivate(path, mode) {
     }
 }
 function checkedPrivateComponent(component) {
-    if (!component || component === "." || component === ".." || basename(component) !== component || component.includes(sep) || component.includes("\0")) {
+    if (!component
+        || component === "."
+        || component === ".."
+        || basename(component) !== component
+        || /[\\/]/.test(component)
+        || component.includes("\0")) {
         throw new Error(`invalid private Hara state path component '${component}'`);
     }
     return component;
@@ -58,9 +66,10 @@ function verifyAndTightenPrivateDirectory(path) {
         // no POSIX ownership mode to repair
     }
     else {
-        const noFollow = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
-        const directoryOnly = typeof constants.O_DIRECTORY === "number" ? constants.O_DIRECTORY : 0;
-        const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK | noFollow | directoryOnly);
+        const fd = openSync(path, constants.O_RDONLY
+            | optionalPosixOpenFlag("O_NONBLOCK")
+            | optionalPosixOpenFlag("O_NOFOLLOW")
+            | optionalPosixOpenFlag("O_DIRECTORY"));
         try {
             const opened = fstatSync(fd);
             if (!opened.isDirectory() || opened.dev !== inspected.dev || opened.ino !== inspected.ino) {
@@ -128,6 +137,311 @@ export function ensurePrivateStateSubdirectory(base, components, tightenExisting
     }
     return parent;
 }
+/** Bind one immediate file below a symlink-free, owner-only Hara state directory. */
+export function bindPrivateHaraStateFile(home, subdirectories, filename) {
+    const directory = ensurePrivateStateSubdirectory(home, [".hara", ...subdirectories]);
+    const name = checkedPrivateComponent(filename);
+    const path = join(directory.path, name);
+    if (dirname(path) !== directory.path)
+        throw new Error(`private Hara state file is outside '${directory.path}'`);
+    verifyPrivateDirectory(directory);
+    return { directory, path };
+}
+function privateReadLimit(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 readFdBytes(fd, count) {
+    const out = Buffer.allocUnsafe(count);
+    let offset = 0;
+    while (offset < count) {
+        const read = readSync(fd, out, offset, count - offset, offset);
+        if (!read)
+            break;
+        offset += read;
+    }
+    return out.subarray(0, offset);
+}
+/** Synchronous private-state reader for startup/auth APIs that cannot make their public contract async. */
+export function readPrivateStateFileSnapshotSync(path, maxBytes = MAX_EDIT_READ_BYTES) {
+    const limit = privateReadLimit(maxBytes);
+    let before;
+    try {
+        before = lstatSync(path);
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    if (before.isSymbolicLink())
+        throw new Error(`refusing private Hara state file: '${path}' is a symbolic link`);
+    const fd = openSync(path, constants.O_RDONLY | optionalPosixOpenFlag("O_NONBLOCK") | optionalPosixOpenFlag("O_NOFOLLOW"));
+    try {
+        let info = fstatSync(fd);
+        verifyOpenedRegularFileSync(path, info, {
+            action: "read private Hara state",
+            rejectHardLinks: true,
+            protectSensitive: false,
+        });
+        try {
+            fchmodSync(fd, 0o600);
+        }
+        catch (error) {
+            if (process.platform !== "win32")
+                throw error;
+        }
+        // chmod may update ctime; capture the authoritative baseline afterwards.
+        info = fstatSync(fd);
+        if (info.size > limit)
+            throw new FileReadLimitError(path, limit);
+        const bytes = readFdBytes(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: "read private Hara state",
+            rejectHardLinks: true,
+            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(`private Hara state file changed while reading: '${path}'`);
+        return {
+            text: decodeUtf8Strict(bytes, path),
+            dev: latest.dev,
+            ino: latest.ino,
+            mode: latest.mode & 0o777,
+            nlink: latest.nlink,
+            size: latest.size,
+            mtimeMs: latest.mtimeMs,
+            ctimeMs: latest.ctimeMs,
+        };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function samePrivateFile(path, expected) {
+    const info = lstatSync(path);
+    return (info.isFile()
+        && !info.isSymbolicLink()
+        && privateStateFileIdentityMatches({
+            dev: info.dev,
+            ino: info.ino,
+            mode: info.mode & 0o777,
+            nlink: info.nlink,
+        }, expected));
+}
+/**
+ * Compare the fields Node can use as a stable file identity on the current platform. Windows only exposes
+ * owner read/write permission semantics, so its synthetic POSIX mode can differ between descriptor- and
+ * path-based stats without identifying a different file. File type, dev/ino and hard-link count remain
+ * mandatory there; POSIX additionally requires the exact owner-only mode.
+ */
+export function privateStateFileIdentityMatches(actual, expected, platform = process.platform) {
+    return (sameOpenedFileIdentity(actual, expected, platform)
+        && actual.nlink === expected.nlink
+        && (platform === "win32" || actual.mode === expected.mode));
+}
+function privateFileIdentitySummary(path) {
+    try {
+        const info = lstatSync(path);
+        return JSON.stringify({
+            file: info.isFile(),
+            symlink: info.isSymbolicLink(),
+            dev: info.dev,
+            ino: info.ino,
+            mode: info.mode & 0o777,
+            nlink: info.nlink,
+        });
+    }
+    catch (error) {
+        return JSON.stringify({ error: error?.code ?? error?.message ?? String(error) });
+    }
+}
+function restorePrivateClaim(claimed, target, expected) {
+    if (!samePrivateFile(claimed, expected)) {
+        throw new Error(`private Hara state claim changed; original entry is preserved at '${claimed}'`);
+    }
+    try {
+        linkSync(claimed, target);
+    }
+    catch (error) {
+        if (error?.code === "EEXIST") {
+            throw new Error(`another entry appeared at '${target}'; original entry is preserved at '${claimed}'`);
+        }
+        throw error;
+    }
+    const linked = { ...expected, nlink: expected.nlink + 1 };
+    if (!samePrivateFile(claimed, linked) || !samePrivateFile(target, linked)) {
+        throw new Error(`private Hara state restore changed; original entry is preserved at '${claimed}'`);
+    }
+    unlinkSync(claimed);
+}
+function syncPrivateDirectory(path) {
+    try {
+        const fd = openSync(path, constants.O_RDONLY
+            | optionalPosixOpenFlag("O_NONBLOCK")
+            | optionalPosixOpenFlag("O_NOFOLLOW")
+            | optionalPosixOpenFlag("O_DIRECTORY"));
+        try {
+            if (fstatSync(fd).isDirectory())
+                fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        /* Directory fsync is not portable; the staged file itself is always fsynced. */
+    }
+}
+/**
+ * Crash-safe, no-follow, compare-and-swap replacement for one bound private state file. Existing entries
+ * are move-claimed before verification so a concurrent alias/replacement is never overwritten silently.
+ */
+export function writePrivateStateFileSync(binding, text) {
+    const { directory, path } = binding;
+    verifyPrivateDirectory(directory);
+    if (resolve(path) !== join(directory.path, checkedPrivateComponent(basename(path)))) {
+        throw new Error(`private Hara state file is outside '${directory.path}'`);
+    }
+    const existing = readPrivateStateFileSnapshotSync(path);
+    verifyPrivateDirectory(directory);
+    const temp = join(directory.path, `.hara-private-${process.pid}-${randomUUID()}.tmp`);
+    let fd;
+    let staged;
+    try {
+        // `wx` maps to O_WRONLY|O_CREAT|O_EXCL/CREATE_NEW and refuses an already-present symlink or file.
+        // Bun's Windows numeric-open compatibility can otherwise turn this valid create into a false ENOENT.
+        fd = openSync(temp, "wx", 0o600);
+        writeFileSync(fd, text, "utf8");
+        try {
+            fchmodSync(fd, 0o600);
+        }
+        catch (error) {
+            if (process.platform !== "win32")
+                throw error;
+        }
+        fsyncSync(fd);
+        const stagedInfo = fstatSync(fd);
+        if (!stagedInfo.isFile() || stagedInfo.nlink !== 1)
+            throw new Error("unsafe private Hara state staging inode");
+        staged = {
+            dev: stagedInfo.dev,
+            ino: stagedInfo.ino,
+            mode: stagedInfo.mode & 0o777,
+            nlink: stagedInfo.nlink,
+        };
+        closeSync(fd);
+        fd = undefined;
+        if (!existing) {
+            try {
+                verifyPrivateDirectory(directory);
+                linkSync(temp, path);
+            }
+            catch (error) {
+                if (error?.code === "EEXIST")
+                    throw new Error(`private Hara state file changed before create: '${path}'`);
+                throw error;
+            }
+        }
+        else {
+            const claimed = join(directory.path, `.hara-claim-${process.pid}-${randomUUID()}.tmp`);
+            try {
+                verifyPrivateDirectory(directory);
+                renameSync(path, claimed);
+            }
+            catch (error) {
+                if (error?.code === "ENOENT")
+                    throw new Error(`private Hara state file changed before replace: '${path}'`);
+                throw error;
+            }
+            let verifiedClaim = false;
+            try {
+                const claimedSnapshot = readPrivateStateFileSnapshotSync(claimed);
+                verifiedClaim = Boolean(claimedSnapshot
+                    && sameOpenedFileIdentity(claimedSnapshot, existing)
+                    && claimedSnapshot.mode === existing.mode
+                    && claimedSnapshot.nlink === existing.nlink
+                    && claimedSnapshot.text === existing.text);
+                if (!verifiedClaim)
+                    throw new Error(`private Hara state file changed before replace: '${path}'`);
+            }
+            catch (error) {
+                try {
+                    restorePrivateClaim(claimed, path, existing);
+                }
+                catch (restoreError) {
+                    throw new Error(`${error instanceof Error ? error.message : String(error)}; safe restore was incomplete: ${restoreError?.message ?? String(restoreError)}`, { cause: error });
+                }
+                throw error;
+            }
+            try {
+                verifyPrivateDirectory(directory);
+                linkSync(temp, path);
+            }
+            catch (error) {
+                let recovery = "";
+                try {
+                    restorePrivateClaim(claimed, path, existing);
+                }
+                catch (restoreError) {
+                    recovery = `; original entry is retained: ${restoreError?.message ?? String(restoreError)}`;
+                }
+                throw new Error(`${error?.message ?? String(error)}${recovery}`, { cause: error });
+            }
+            if (verifiedClaim) {
+                try {
+                    if (samePrivateFile(claimed, existing))
+                        unlinkSync(claimed);
+                }
+                catch {
+                    // The new entry is already committed. Retain a changed/unremovable unpredictable claim instead of
+                    // risking deletion of a concurrently supplied path; it contains only the previous private state.
+                }
+            }
+        }
+        const linkedStaged = { ...staged, nlink: staged.nlink + 1 };
+        if (!samePrivateFile(temp, linkedStaged) || !samePrivateFile(path, linkedStaged)) {
+            throw new Error(`private Hara state staging identity changed during commit: '${path}'`
+                + `; expected=${JSON.stringify(linkedStaged)}`
+                + `; staging=${privateFileIdentitySummary(temp)}`
+                + `; target=${privateFileIdentitySummary(path)}`);
+        }
+        unlinkSync(temp);
+        const committed = lstatSync(path);
+        if (!staged
+            || !committed.isFile()
+            || committed.isSymbolicLink()
+            || !sameOpenedFileIdentity(committed, staged)
+            || committed.nlink !== 1
+            || (process.platform !== "win32" && (committed.mode & 0o777) !== 0o600))
+            throw new Error(`private Hara state file changed during commit: '${path}'`);
+        verifyPrivateDirectory(directory);
+        syncPrivateDirectory(directory.path);
+    }
+    finally {
+        if (fd !== undefined)
+            try {
+                closeSync(fd);
+            }
+            catch { /* preserve original error */ }
+        if (staged) {
+            try {
+                if (samePrivateFile(temp, staged))
+                    unlinkSync(temp);
+            }
+            catch {
+                /* A changed entry is retained rather than unlinking an attacker-supplied replacement. */
+            }
+        }
+    }
+}
 /** Open/read one internal state file without following aliases, reject hard links, and repair mode by fd. */
 export async function readPrivateStateFileSnapshot(path, maxBytes = MAX_EDIT_READ_BYTES) {
     const requested = Number.isFinite(maxBytes) ? Math.floor(maxBytes) : MAX_EDIT_READ_BYTES;
@@ -185,7 +499,7 @@ export async function readPrivateStateFileSnapshot(path, maxBytes = MAX_EDIT_REA
             || after.ctimeMs !== before.ctimeMs)
             throw new Error(`private Hara state file changed while reading: '${path}'`);
         return {
-            text: Buffer.concat(chunks, total).toString("utf8"),
+            text: decodeUtf8Strict(Buffer.concat(chunks, total), path),
             dev: after.dev,
             ino: after.ino,
             mode: after.mode & 0o777,
@@ -209,9 +523,8 @@ export function removePrivateStateFile(path, expected, directory) {
     if (!current.isFile()
         || current.isSymbolicLink()
         || current.nlink !== 1
-        || current.dev !== expected.dev
-        || current.ino !== expected.ino
-        || (current.mode & 0o777) !== expected.mode
+        || !sameOpenedFileIdentity(current, expected)
+        || (process.platform !== "win32" && (current.mode & 0o777) !== expected.mode)
         || current.size !== expected.size
         || current.mtimeMs !== expected.mtimeMs
         || current.ctimeMs !== expected.ctimeMs)