@nanhara/hara 0.120.0 → 0.121.1

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to `@nanhara/hara`.
 > Versioning (pre-1.0, SemVer-style): the **minor** (middle) number bumps for a **new feature**; the
 > **patch** (last) number bumps for **optimizations/fixes of existing features**.
 
+## 0.121.1 — field-feedback reliability & credential safety
+
+- **Terminal resize no longer erases the composer.** Hara clears stale Ink output only before a real
+  width change; height-only window drags keep the input box visible and width changes repaint immediately.
+- **Credentials stay out of durable transcripts and generated code.** Session writes deeply redact likely
+  keys/tokens/passwords (including tool inputs/results); legacy content is redacted when loaded and migrated
+  on its next atomic, private save. Interactive pastes get a warning without echoing the value. The agent must use environment references,
+  never literal secrets in code/commands, and may only populate a real-secret `.env` when explicitly asked.
+- **`web_search` has a verified mainland path.** A configured Tavily request races the keyless Bing China
+  HTML path; Baidu, Google, and DuckDuckGo remain concurrent secondary fallbacks. Provider timeouts are
+  isolated, and JavaScript-only `web_fetch` pages now explain that a browser/API/connector is required
+  instead of returning a misleading empty body.
+- **Long setup commands fail usefully.** Package installs automatically become background jobs unless the
+  caller explicitly sets timeout/background, while ngrok tunnels preflight local authentication once and
+  stop with a focused fix instead of cycling through unrelated tunnel tools.
+- **Persistent desktop sessions re-read configuration.** New/resumed `hara serve` sessions pick up rotated
+  `apiKey`/model/baseURL values without a restart; empty env/project values no longer mask valid global
+  config, and a 401 says the configured credential expired rather than asking users to paste it into chat.
+
+## 0.121.0 — `hara desk` · crash-safe coding/files · bounded interactive I/O
+
+- **`hara desk` connects the CLI to the shared coordination desk.** Register an agent, post/list/
+  claim/complete/ack/cancel tasks, and persist the desk token with owner-only file permissions. The
+  client identifies itself as `hara-cli`, so mixed Codex/Claude Code/hara fleets remain legible.
+- **Coding edits are transaction-safe.** `write_file` uses same-directory atomic replacement;
+  multi-file patches validate every destination before writing and roll back already-committed
+  files if a later commit fails. Undo snapshots are captured before mutation, failed writes do not
+  create false undo history, and symlink/non-regular destinations are rejected consistently.
+- **Large files stay useful without flooding memory or context.** Slice reads stream only the
+  requested line window, `@file` mentions have explicit byte/line caps, and tool results are
+  bounded centrally (including plugin/MCP results) with clear truncation metadata.
+- **Interactive input is friendlier and bounded.** The TUI composer has shell-style up/down history
+  with draft restoration, duplicate suppression, navigation reset after edits, and a fixed maximum
+  history size. The ask-mode sentinel is also source-safe on every supported Node runtime.
+- **Faster cold start.** Unicode-width data and the write/edit tool graph are loaded only when the
+  active command needs them, reducing startup work for lightweight commands such as `--version`.
+- **Production dependency hardening.** The Lark SDK's Axios transport is pinned to a patched 1.x
+  release instead of its vulnerable `~1.13.3` range; the production npm audit is clean at release.
+
 ## 0.120.0 — `hara feedback`: one door for humans and agents
 
 - **`hara feedback "what happened"`** files a structured GitHub issue (repo hara-cli/hara,

package/dist/agent/failover.js

@@ -38,7 +38,7 @@ export function failoverAction(kind, s) {
 export function errorHint(kind) {
     switch (kind) {
         case "auth":
-            return " — check your API key / auth (try `hara setup`)";
+            return " — the configured credential was rejected or expired; update ~/.hara/config.json, the active profile, or its environment variable, then retry. Do not paste the key into chat";
         case "rate_limit":
             return " — rate-limited; wait a moment, or set `fallbackModel` to auto-switch";
         case "overloaded":

package/dist/agent/loop.js

@@ -16,6 +16,7 @@ import { drainReminders, wrapReminders, pushReminder, todoStaleReminder, TODO_ST
 import { setTurnPhase } from "./phase.js";
 import { recordTouch } from "./touched.js";
 import { resolve as resolvePath } from "node:path";
+import { redactSensitiveText } from "../security/secrets.js";
 /** File tools whose `path` input marks the file as "recently worked with" (post-compaction restore). */
 const FILE_TOUCH_TOOLS = new Set(["read_file", "edit_file", "write_file"]);
 /** Stall watchdog ceiling: a model attempt that streams NOTHING for this long is treated as a dead /
@@ -65,7 +66,14 @@ re-reading a big file after every edit is the slowest habit an agent can have.
 When an attempt FAILS, never repeat it unchanged — read the error, form a hypothesis about the cause, and
 change something (arguments / approach / tool) before trying again. After two failed variants of the same
 approach, stop: re-plan from what you learned, or ask the user, stating concisely what you tried and what
-the errors said. Repeating a failed action hoping for a different result is how sessions die. For broad,
+the errors said. Repeating a failed action hoping for a different result is how sessions die.
+Never put a literal password, API key, token, App Secret, Authorization header, or other credential in a
+source file or shell command. Reference an environment variable instead (for example process.env.API_KEY or
+$API_KEY). Keep real values in the user's environment or an approved secret store; do not create/populate a
+.env file with a real secret unless the user explicitly asks and it is excluded from version control. Never
+echo credentials back. Session persistence redacts likely secrets as a last line of defense, but that does
+not make embedding credentials acceptable.
+For broad,
 open-ended exploration (more than ~3 searches), spawn \`agent\` sub-agents — several in one response for
 independent questions (role "explore") — each returns conclusions, not dumps. Messages the user sends
 mid-task arrive marked as interjections — triage them (refine current / queue as todo / urgent-switch)
@@ -88,7 +96,10 @@ site, build output), check they are newer than their sources (compare mtimes or
 the sources changed since the artifacts were built, run the project's documented build/render steps FIRST.
 When AGENTS.md / README / package.json document a command sequence (e.g. pull → render → build → preview),
 that ordering is authoritative — never skip the middle steps, or you serve stale output and the user sees
-two-day-old work. After completing a task, give a one-line summary.`;
+two-day-old work. Package-manager installs auto-start as background jobs when you omit background/timeout;
+poll the returned job until it exits before depending on its packages. Before opening a public tunnel,
+verify that provider's authentication/config once; if it is missing, stop and ask instead of trying a chain
+of unrelated tunnel tools. After completing a task, give a one-line summary.`;
 /** When running inside `hara gateway`, tell the agent it's in a chat — so it delivers files via send_file
  *  (the only channel that reaches the peer) and never reaches for the desktop client / computer tool. */
 function gatewayNote() {
@@ -118,6 +129,17 @@ export async function runAgent(history, opts) {
     let activeProvider = provider; // may switch to a fallback model on a recoverable error (app-failover)
     let triedFallback = false;
     let emptyRetried = false; // one-shot: a genuinely empty model turn gets a single nudge before we give up
+    // Warn at the interaction boundary without echoing the value. Headless/gateway stdout is the response
+    // transport, so keep the banner to interactive surfaces; persistence is still redacted everywhere.
+    const latestUser = [...history].reverse().find((m) => m.role === "user");
+    const sensitive = latestUser?.role === "user" ? redactSensitiveText(latestUser.content).redactions : [];
+    if (sensitive.length && !opts.quiet) {
+        const note = "⚠ possible credential detected — the saved session copy will be redacted; prefer passing secrets through environment variables.";
+        if (ctx.ui)
+            ctx.ui.notice(note);
+        else if (stdout.isTTY)
+            out(c.yellow(note + "\n"));
+    }
     // Stuck/loop guard — only in headless chat (`hara gateway`), where a wrong approach can grind forever with
     // nobody to hit Esc (e.g. screenshots it can't read). Once per run, when the agent keeps repeating one
     // non-read tool or acting blind, we inject a reflection nudge so it steps back instead of spinning.

package/dist/config.js

@@ -49,6 +49,28 @@ export function readRawConfig() {
         return {};
     }
 }
+const ROUTING_CONFIG_KEYS = new Set(["provider", "apiKey", "model", "baseURL"]);
+/** Empty routing values are not meaningful credentials/endpoints. Ignore them at each precedence layer so
+ *  an empty project override (or launcher-exported empty env var) cannot hide a valid global config value. */
+function withoutBlankRoutingValues(input) {
+    const out = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (ROUTING_CONFIG_KEYS.has(key) && typeof value === "string") {
+            const trimmed = value.trim();
+            if (!trimmed)
+                continue;
+            out[key] = trimmed;
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+function nonBlankEnv(value) {
+    const trimmed = value?.trim();
+    return trimmed || undefined;
+}
 /** Nearest project override `.hara/config.json`, searching cwd up to the repo root. */
 function readProjectConfig(cwd) {
     let dir = resolve(cwd);
@@ -121,12 +143,16 @@ export function loadConfig(opts = {}) {
     const overlayName = process.env.HARA_OVERLAY ?? opts.overlay;
     const overlayMap = overlays && typeof overlays === "object" ? overlays : profiles && typeof profiles === "object" ? profiles : null;
     const overlay = overlayName && overlayMap && overlayMap[overlayName] ? overlayMap[overlayName] : {};
-    const merged = { ...globalBase, ...project, ...overlay };
-    const provider = (process.env.HARA_PROVIDER ?? merged.provider ?? "anthropic");
+    const merged = {
+        ...withoutBlankRoutingValues(globalBase),
+        ...withoutBlankRoutingValues(project),
+        ...withoutBlankRoutingValues(overlay),
+    };
+    const provider = (nonBlankEnv(process.env.HARA_PROVIDER) ?? merged.provider ?? "anthropic");
     const d = PROVIDER_DEFAULTS[provider] ?? PROVIDER_DEFAULTS.anthropic;
-    const model = process.env.HARA_MODEL ?? merged.model ?? d.model;
-    const baseURL = process.env.HARA_BASE_URL ?? merged.baseURL ?? d.baseURL;
-    const apiKey = process.env.HARA_API_KEY ?? process.env[d.envKey] ?? merged.apiKey;
+    const model = nonBlankEnv(process.env.HARA_MODEL) ?? merged.model ?? d.model;
+    const baseURL = nonBlankEnv(process.env.HARA_BASE_URL) ?? merged.baseURL ?? d.baseURL;
+    const apiKey = nonBlankEnv(process.env.HARA_API_KEY) ?? nonBlankEnv(process.env[d.envKey]) ?? merged.apiKey;
     const approval = (process.env.HARA_APPROVAL ?? merged.approval ?? "suggest");
     const sandbox = (process.env.HARA_SANDBOX ?? merged.sandbox ?? "off");
     const theme = (process.env.HARA_THEME ?? merged.theme ?? "dark");

package/dist/context/mentions.js

@@ -1,10 +1,11 @@
 // @file mentions — expand `@path` references in user input into appended file contents,
 // and provide fuzzy file candidates for REPL tab-completion.
-import { readFileSync, existsSync, statSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
 import { listProjectFiles, dirPrefixes, walkFiles } from "../fs-walk.js";
 import { fuzzyRank } from "../fuzzy.js";
 import { mediaTypeFor } from "../images.js";
+import { readTextPrefixSync } from "../fs-read.js";
 const MAX_FILE = 50_000;
 // @ at start-of-string or after whitespace; capture a path with no spaces/@ (avoids emails like a@b.com)
 const MENTION_RE = /(?:^|\s)@([^\s@]+)/g;
@@ -53,9 +54,10 @@ function expandRef(ref, cwd) {
             // don't inline binary image bytes as text — paste with Ctrl+V (or drag the file in) to attach visually
             if (mediaTypeFor(abs))
                 return `Referenced \`${ref}\` is an image — paste it with Ctrl+V to attach it visually.`;
-            let txt = readFileSync(abs, "utf8");
-            if (txt.length > MAX_FILE)
-                txt = txt.slice(0, MAX_FILE) + "\n…[truncated]";
+            const prefix = readTextPrefixSync(abs, MAX_FILE);
+            if (prefix.binary)
+                return `Referenced \`${ref}\` appears to be binary — it was not inserted into the model context.`;
+            const txt = prefix.text + (prefix.truncated ? "\n…[truncated]" : "");
             return `\nReferenced file \`${ref}\`:\n\`\`\`\n${txt}\n\`\`\`\n`;
         }
         if (st.isDirectory()) {
@@ -73,16 +75,24 @@ function expandRef(ref, cwd) {
 const cache = new Map();
 const CACHE_MS = 5000;
 function projectEntries(cwd) {
-    const hit = cache.get(cwd);
+    const key = resolve(cwd);
+    const hit = cache.get(key);
     const now = Date.now();
     if (hit && now - hit.at < CACHE_MS)
         return hit.entries;
-    const files = listProjectFiles(cwd);
+    const files = listProjectFiles(key);
     // files + their directory prefixes (so `@src/` drills into the subtree)
     const entries = [...dirPrefixes(files), ...files];
-    cache.set(cwd, { at: now, entries });
+    cache.set(key, { at: now, entries });
     return entries;
 }
+/** Invalidate the derived @path inventory after a coding tool creates/deletes a file. */
+export function invalidateFileCandidates(cwd) {
+    if (cwd)
+        cache.delete(resolve(cwd));
+    else
+        cache.clear();
+}
 /**
  * File/dir candidates whose path matches `query`, for @ autocomplete.
  * Recurses subdirectories (git-tracked + untracked, or a filesystem walk outside git),

package/dist/desk.js

@@ -0,0 +1,64 @@
+// `hara desk` client — how a hara agent connects to the hara-desk coordination server (the closed-
+// source identity registry + task board). This is the OPEN-SOURCE side of the wire: a thin HTTP
+// client + local credential storage. The desk itself (auth, board, L2 ack) lives in hara-desk.
+//
+// Credentials live in ~/.hara/desk.json (0600): the desk URL + this agent's token, written once at
+// `hara desk register`. Every later call reads them back. The token is a bearer secret — never logged.
+import { readFileSync, writeFileSync, mkdirSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const credsPath = () => join(homedir(), ".hara", "desk.json");
+export function loadCreds() {
+    try {
+        const c = JSON.parse(readFileSync(credsPath(), "utf8"));
+        return c.url && c.token ? c : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveCreds(c) {
+    const dir = join(homedir(), ".hara");
+    mkdirSync(dir, { recursive: true });
+    const p = credsPath();
+    writeFileSync(p, JSON.stringify(c, null, 2));
+    try {
+        chmodSync(p, 0o600);
+    }
+    catch {
+        /* best-effort on non-posix */
+    }
+}
+/** One HTTP call to the desk. Auth via bearer token when creds are present. Throws on non-2xx with
+ *  the server's error message (so the CLI can surface a real reason, not "request failed"). */
+export async function deskCall(url, method, path, opts = {}) {
+    const r = await fetch(url.replace(/\/$/, "") + path, {
+        method,
+        headers: {
+            "content-type": "application/json",
+            ...(opts.token ? { authorization: `Bearer ${opts.token}` } : {}),
+        },
+        ...(opts.body !== undefined ? { body: JSON.stringify(opts.body) } : {}),
+        signal: AbortSignal.timeout(opts.timeoutMs ?? 10000),
+    });
+    const text = await r.text();
+    let data = {};
+    try {
+        data = text ? JSON.parse(text) : {};
+    }
+    catch {
+        data = { raw: text };
+    }
+    if (!r.ok)
+        throw new Error(data?.error || `desk ${r.status}: ${text.slice(0, 200)}`);
+    return data;
+}
+/** Register this machine's agent with a desk and persist the returned credentials. `client`
+ *  identifies the kind of client (defaults "hara-cli"); the desk is client-agnostic, so any agent
+ *  may pass its own label. */
+export async function registerAgent(url, enrollKey, name, owner, client = "hara-cli") {
+    const r = await deskCall(url, "POST", "/register", { body: { enrollKey, name, owner, client } });
+    const creds = { url, agentId: r.agentId, owner: r.owner, token: r.token };
+    saveCreds(creds);
+    return creds;
+}

package/dist/feedback.js

@@ -3,6 +3,7 @@
 // humans and agents file through the same door (gh CLI when present, copy-paste text otherwise).
 // The session tail is OFF by default and explicitly opt-in (--session) because issues are public.
 import { platform, release, arch } from "node:os";
+import { redactSensitiveText } from "./security/secrets.js";
 export function collectEnv(version, model) {
     return {
         version,
@@ -14,13 +15,7 @@ export function collectEnv(version, model) {
 /** Strip credential-looking material from text that is about to become a PUBLIC issue.
  *  Deliberately aggressive: false positives cost a little readability, false negatives leak keys. */
 export function redact(text) {
-    return text
-        .replace(/\bsk-[A-Za-z0-9_-]{8,}/g, "sk-***")
-        .replace(/\bgh[pousr]_[A-Za-z0-9]{20,}/g, "gh*_***")
-        .replace(/\b(AKIA|ASIA)[A-Z0-9]{16}\b/g, "AWS-KEY-***")
-        .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]{16,}/gi, "Bearer ***")
-        .replace(/\b(api[_-]?key|apikey|token|secret|password|passwd|authorization)(["']?\s*[:=]\s*["']?)[^\s"',;]{6,}/gi, "$1$2***")
-        .replace(/\beyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, "JWT-***");
+    return redactSensitiveText(text).text;
 }
 /** The structured issue body — same shape as .github/ISSUE_TEMPLATE/bug_report.yml so hand-filed
  *  and command-filed issues read identically to the triage side. */

package/dist/fs-read.js

@@ -0,0 +1,157 @@
+// 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, createReadStream, fstatSync, openSync, readSync } from "node:fs";
+export class BinaryFileError extends Error {
+    constructor(path) {
+        super(`${path} appears to be binary (NUL byte detected)`);
+        this.name = "BinaryFileError";
+    }
+}
+const DEFAULT_LINE_CAP = 2000;
+const DEFAULT_MAX_SCAN = 64 * 1024 * 1024;
+/** Read only enough bytes to produce a bounded UTF-8 prefix (used by synchronous @file expansion). */
+export function readTextPrefixSync(path, maxChars) {
+    const chars = Math.max(0, Math.floor(maxChars));
+    const fd = openSync(path, "r");
+    try {
+        const size = fstatSync(fd).size;
+        // Four bytes per Unicode scalar plus a small boundary cushion guarantees enough decoded input for
+        // `chars` without allocating the entire file. readSync can short-read, so fill in a loop.
+        const byteLimit = Math.min(size, chars * 4 + 4);
+        const buffer = Buffer.allocUnsafe(byteLimit);
+        let read = 0;
+        while (read < byteLimit) {
+            const n = readSync(fd, buffer, read, byteLimit - read, read);
+            if (n === 0)
+                break;
+            read += n;
+        }
+        const bytes = buffer.subarray(0, read);
+        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 > read || decoded.length > chars,
+            binary,
+        };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Render a line slice without retaining the entire file. Total line count is shown only when EOF is reached. */
+export async function streamFileSlice(path, offset = 1, limit = 300, options = {}) {
+    const start = Math.max(1, Math.floor(offset));
+    const want = Math.max(1, Math.floor(limit));
+    const requestedEnd = start + want - 1;
+    const lineCap = Math.max(1, Math.floor(options.lineCap ?? DEFAULT_LINE_CAP));
+    const maxScan = Math.max(lineCap, Math.floor(options.maxScanChars ?? DEFAULT_MAX_SCAN));
+    const rendered = [];
+    let lineNo = 1;
+    let linePrefix = "";
+    let lineChars = 0;
+    let lineEndsWithCr = false;
+    let sawData = false;
+    let endedWithNewline = false;
+    let scanned = 0;
+    let hasMore = false;
+    let scanLimited = false;
+    let stoppedEarly = false;
+    const append = (part) => {
+        if (!part.length)
+            return;
+        sawData = true;
+        endedWithNewline = false;
+        if (lineNo > requestedEnd) {
+            hasMore = true;
+            return;
+        }
+        if (lineNo >= start) {
+            lineChars += part.length;
+            if (linePrefix.length < lineCap)
+                linePrefix += part.slice(0, lineCap - linePrefix.length);
+            lineEndsWithCr = part.endsWith("\r");
+        }
+    };
+    const finishLine = (partial = false) => {
+        const current = lineNo;
+        if (current >= start && current <= requestedEnd) {
+            let chars = lineChars;
+            let prefix = linePrefix;
+            if (!partial && lineEndsWithCr) {
+                chars = Math.max(0, chars - 1);
+                if (prefix.endsWith("\r"))
+                    prefix = prefix.slice(0, -1);
+            }
+            const omitted = Math.max(0, chars - prefix.length);
+            const tail = partial
+                ? `…[line continues; scan stopped after ${scanned} chars]`
+                : omitted
+                    ? `…[+${omitted} chars]`
+                    : "";
+            rendered.push(`${String(current).padStart(6)}\t${prefix}${tail}`);
+        }
+        lineNo++;
+        linePrefix = "";
+        lineChars = 0;
+        lineEndsWithCr = false;
+        if (current > requestedEnd)
+            hasMore = true;
+    };
+    const stream = createReadStream(path, { encoding: "utf8", highWaterMark: 64 * 1024 });
+    try {
+        for await (const raw of stream) {
+            const chunk = String(raw);
+            if (chunk.length)
+                sawData = true;
+            if (scanned < 4096 && chunk.slice(0, 4096 - scanned).includes("\0"))
+                throw new BinaryFileError(path);
+            scanned += chunk.length;
+            let at = 0;
+            while (at < chunk.length) {
+                const newline = chunk.indexOf("\n", at);
+                if (newline < 0) {
+                    append(chunk.slice(at));
+                    break;
+                }
+                append(chunk.slice(at, newline));
+                finishLine();
+                endedWithNewline = true;
+                at = newline + 1;
+                if (hasMore)
+                    break;
+            }
+            if (hasMore) {
+                stoppedEarly = true;
+                break;
+            }
+            if (scanned >= maxScan) {
+                scanLimited = true;
+                stoppedEarly = true;
+                if (lineNo >= start && lineNo <= requestedEnd)
+                    finishLine(true);
+                break;
+            }
+        }
+    }
+    finally {
+        stream.destroy();
+    }
+    if (!stoppedEarly) {
+        // A trailing newline creates no phantom line, matching String#split + trailing-empty removal.
+        if (!endedWithNewline || !sawData)
+            finishLine();
+        const total = lineNo - 1;
+        if (start > total)
+            return `(file has ${total} lines — offset ${start} is past the end)`;
+        const end = start + rendered.length - 1;
+        const sliced = start > 1 || end < total;
+        const head = sliced ? `(lines ${start}–${end} of ${total}${end < total ? ` — continue with offset:${end + 1}` : ""})\n` : "";
+        return head + rendered.join("\n");
+    }
+    const end = start + Math.max(0, rendered.length - 1);
+    if (scanLimited) {
+        return `(large file scan stopped after ${scanned} chars — use grep or bash byte-range tools for a narrower target)\n${rendered.join("\n")}`;
+    }
+    return `(lines ${start}–${end}; more lines follow — continue with offset:${end + 1})\n${rendered.join("\n")}`;
+}

package/dist/fs-write.js

@@ -0,0 +1,105 @@
+// 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 { dirname, join } from "node:path";
+import { link, lstat, mkdir, open, readFile, realpath, rename, stat, unlink } from "node:fs/promises";
+export class FileChangedError extends Error {
+    code = "HARA_FILE_CHANGED";
+    constructor(path) {
+        super(`File changed while the edit was being prepared: ${path}. Re-read it and retry the edit.`);
+        this.name = "FileChangedError";
+    }
+}
+let tempSequence = 0;
+async function writeTarget(path) {
+    try {
+        const info = await lstat(path);
+        // Replacing a symlink would silently break it. Stage beside the real target instead so edits retain
+        // the link (common in dotfile repos and generated workspace layouts).
+        if (info.isSymbolicLink())
+            return await realpath(path);
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT")
+            throw error;
+    }
+    return path;
+}
+async function syncDirectory(path) {
+    // Directory fsync makes the rename durable across a power loss on POSIX. Some filesystems/platforms
+    // reject opening directories, so durability degrades gracefully after the file itself was synced.
+    try {
+        const handle = await open(path, "r");
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        /* best effort */
+    }
+}
+/** Atomically replace/create a UTF-8 file, optionally refusing to overwrite a newer disk version. */
+export async function atomicWriteText(path, content, options = {}) {
+    const target = await writeTarget(path);
+    const dir = dirname(target);
+    await mkdir(dir, { recursive: true });
+    let mode = 0o666;
+    try {
+        mode = (await stat(target)).mode & 0o777;
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT")
+            throw error;
+    }
+    // Keep the staging basename fixed-size: prefixing the destination's full basename would make a
+    // perfectly valid near-NAME_MAX file impossible to edit because the temporary name becomes longer.
+    const temp = join(dir, `.hara-${process.pid}-${Date.now().toString(36)}-${tempSequence++}.tmp`);
+    let staged = false;
+    try {
+        const handle = await open(temp, "wx", mode);
+        staged = true;
+        try {
+            await handle.writeFile(content, "utf8");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        if (options.expected === null) {
+            // 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);
+            }
+            catch (error) {
+                if (error?.code === "EEXIST")
+                    throw new FileChangedError(path);
+                throw error;
+            }
+            await unlink(temp);
+            staged = false;
+        }
+        else {
+            if (typeof options.expected === "string") {
+                let current;
+                try {
+                    current = await readFile(target, "utf8");
+                }
+                catch {
+                    throw new FileChangedError(path);
+                }
+                if (current !== options.expected)
+                    throw new FileChangedError(path);
+            }
+            await rename(temp, target);
+            staged = false;
+        }
+        await syncDirectory(dir);
+    }
+    finally {
+        if (staged)
+            await unlink(temp).catch(() => { });
+    }
+}