@nanhara/hara 0.121.0 → 0.122.0

package/dist/session/store.js

@@ -1,8 +1,9 @@
 // Session persistence — conversations saved as JSON under ~/.hara/sessions, resumable.
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { randomUUID } from "node:crypto";
+import { redactSensitiveValue } from "../security/secrets.js";
 /** Derive the session source from the spawn environment — the gateway subprocess runs with
  *  HARA_GATEWAY=<platform>, the cron runner with HARA_CRON=1 (+ HARA_CRON_NAME=<job name>). */
 export function sessionSourceFromEnv() {
@@ -20,11 +21,92 @@ export function automatedTitle(source, sourceName, at = new Date()) {
 }
 function sessionsDir() {
     const d = join(homedir(), ".hara", "sessions");
-    mkdirSync(d, { recursive: true });
+    mkdirSync(d, { recursive: true, mode: 0o700 });
+    // `mode` is ignored when the directory already exists. Tighten legacy installs too: a session holds
+    // private conversation history, so inheriting a permissive umask (typically 0755) is not acceptable.
+    chmodSync(d, 0o700);
     return d;
 }
-const sessionFile = (id) => join(sessionsDir(), `${id}.json`);
-const lockFile = (id) => join(sessionsDir(), `${id}.lock`);
+/** Session ids become filenames. Gateway/platform ids are not always UUIDs, so allow printable filename
+ * characters broadly while rejecting separators, traversal sentinels, NULs, and unbounded names. */
+export function validSessionId(id) {
+    return typeof id === "string" && id.length > 0 && id.length <= 220 && id !== "." && id !== ".." && !/[\\/\0]/.test(id);
+}
+function checkedSessionId(id) {
+    if (!validSessionId(id))
+        throw new Error("invalid session id");
+    return id;
+}
+const sessionFile = (id) => join(sessionsDir(), `${checkedSessionId(id)}.json`);
+const lockFile = (id) => join(sessionsDir(), `${checkedSessionId(id)}.lock`);
+const reclaimFile = (id) => join(sessionsDir(), `${checkedSessionId(id)}.lock.reclaim`);
+/** Distinguish a missing session from an existing but unreadable/corrupt one without exposing its path. */
+export function sessionFileExists(id) {
+    if (!validSessionId(id))
+        return false;
+    return existsSync(sessionFile(id));
+}
+// A pid alone is not ownership: pids are reused, and another writer could replace a lock between read and
+// release. Keep the random token for every lock this module actually created and require both on release.
+const ownedLocks = new Map();
+function readLockRecord(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (!Number.isInteger(parsed.pid) ||
+            Number(parsed.pid) <= 0 ||
+            typeof parsed.startedAt !== "number" ||
+            (parsed.token !== undefined && (typeof parsed.token !== "string" || !parsed.token))) {
+            return null;
+        }
+        return { pid: Number(parsed.pid), startedAt: parsed.startedAt, ...(parsed.token ? { token: parsed.token } : {}) };
+    }
+    catch {
+        return null;
+    }
+}
+/** Create one private file without ever replacing an existing path. On a partial write, remove only the
+ *  inode we just created. Callers use this for both the primary lock and the stale-lock reclaimer. */
+function writeExclusive(path, record) {
+    let fd;
+    try {
+        fd = openSync(path, "wx", 0o600);
+        writeFileSync(fd, JSON.stringify(record), "utf8");
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = undefined;
+    }
+    catch (error) {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+                fd = undefined;
+            }
+            catch {
+                /* continue with best-effort removal */
+            }
+            try {
+                rmSync(path, { force: true });
+            }
+            catch {
+                /* the original error is more useful */
+            }
+        }
+        throw error;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                /* the acquisition will fail closed */
+            }
+        }
+    }
+}
+function newLockRecord() {
+    return { pid: process.pid, startedAt: Date.now(), token: randomUUID() };
+}
 /** Is a process with this pid alive? `process.kill(pid, 0)` sends no signal — it just probes: throws
  *  ESRCH if dead, EPERM if alive-but-not-ours (still alive). Best-effort across platforms. */
 function pidAlive(pid) {
@@ -36,60 +118,145 @@ function pidAlive(pid) {
         return e?.code === "EPERM";
     }
 }
-/** Take an exclusive lock on a session so two hara processes can't resume the SAME session and corrupt
- *  its append-only history by racing writes. Returns `{ ok: true }` if acquired (or the previous holder
- *  is dead → we take over), or `{ ok: false, pid }` if a LIVE process already holds it. Best-effort: any
- *  filesystem hiccup resolves to `ok:true` so a lock problem never blocks the user. Pair with
- *  `releaseSessionLock` on exit. */
+/** Take an O_EXCL lock on a session so two hara processes cannot both pass a check-then-write race.
+ *  Filesystem/malformed-lock errors fail CLOSED. A well-formed dead holder can be reclaimed under a second
+ *  O_EXCL guard; a corrupt lock is deliberately left for explicit operator inspection/removal. */
 export function acquireSessionLock(id) {
-    const f = lockFile(id);
+    let f;
+    let reclaim;
     try {
-        if (existsSync(f)) {
-            const held = JSON.parse(readFileSync(f, "utf8"));
-            if (typeof held.pid === "number" && held.pid !== process.pid && pidAlive(held.pid)) {
-                return { ok: false, pid: held.pid };
-            }
-            // stale (dead pid) or already ours → fall through and (re)claim it
+        f = lockFile(id);
+        reclaim = reclaimFile(id);
+    }
+    catch {
+        return { ok: false };
+    }
+    // A stale-lock recovery is changing the primary lock. New contenders wait/fail instead of creating a
+    // primary lock in the short remove→create window.
+    if (existsSync(reclaim)) {
+        const stale = readLockRecord(reclaim);
+        if (!stale?.token || !Number.isFinite(stale.startedAt) || stale.startedAt <= 0 || pidAlive(stale.pid)) {
+            return { ok: false, pid: readLockRecord(f)?.pid };
+        }
+        const current = readLockRecord(reclaim);
+        if (!current?.token ||
+            current.pid !== stale.pid ||
+            current.token !== stale.token ||
+            current.startedAt !== stale.startedAt ||
+            pidAlive(current.pid)) {
+            return { ok: false, pid: readLockRecord(f)?.pid };
+        }
+        try {
+            rmSync(reclaim);
+        }
+        catch {
+            return { ok: false, pid: readLockRecord(f)?.pid };
         }
-        writeFileSync(f, JSON.stringify({ pid: process.pid, startedAt: Date.now() }));
+    }
+    const claim = newLockRecord();
+    try {
+        writeExclusive(f, claim);
+        ownedLocks.set(id, claim.token);
         return { ok: true };
     }
+    catch (error) {
+        if (error?.code !== "EEXIST")
+            return { ok: false };
+    }
+    const held = readLockRecord(f);
+    if (!held)
+        return { ok: false }; // malformed/unreadable is not proof that the owner is dead
+    if (held.pid === process.pid && !!held.token && ownedLocks.get(id) === held.token)
+        return { ok: true }; // re-entrant
+    if (pidAlive(held.pid))
+        return { ok: false, pid: held.pid };
+    // Serialize stale takeover. All participants check this guard before attempting the primary O_EXCL create,
+    // so no second contender can steal the freshly-created primary lock during reclamation.
+    const reclaimClaim = newLockRecord();
+    try {
+        writeExclusive(reclaim, reclaimClaim);
+    }
     catch {
+        return { ok: false, pid: held.pid };
+    }
+    try {
+        const current = readLockRecord(f);
+        if (!current)
+            return { ok: false }; // disappeared/corrupted unexpectedly: fail closed
+        if (current.pid === process.pid && !!current.token && ownedLocks.get(id) === current.token)
+            return { ok: true };
+        if (pidAlive(current.pid))
+            return { ok: false, pid: current.pid };
+        rmSync(f); // known-dead, well-formed owner; protected by the reclaim guard
+        const replacement = newLockRecord();
+        writeExclusive(f, replacement);
+        ownedLocks.set(id, replacement.token);
         return { ok: true };
     }
+    catch {
+        return { ok: false };
+    }
+    finally {
+        // Only remove our own reclaimer. A replacement would indicate outside interference and must survive.
+        const currentReclaim = readLockRecord(reclaim);
+        if (currentReclaim?.pid === process.pid && currentReclaim.token === reclaimClaim.token) {
+            try {
+                rmSync(reclaim);
+            }
+            catch {
+                /* fail closed on the next acquisition until this guard can be inspected/removed */
+            }
+        }
+    }
 }
 /** Release a session lock we hold (only removes it if the pid matches ours — never steals another's). */
 export function releaseSessionLock(id) {
+    const token = ownedLocks.get(id);
+    if (!token)
+        return;
     try {
         const f = lockFile(id);
-        if (!existsSync(f))
-            return;
-        const held = JSON.parse(readFileSync(f, "utf8"));
-        if (held?.pid === process.pid)
+        const held = readLockRecord(f);
+        if (held?.pid === process.pid && held.token === token)
             rmSync(f);
+        ownedLocks.delete(id);
     }
     catch {
-        /* best-effort */
+        // Keep the ownership token so a later cleanup attempt can still prove ownership. Never unlink blindly.
     }
 }
 /** Permanently delete a session from disk (codex thread/delete — unlike archive, irreversible).
  *  Refuses when a LIVE other process holds the lock; removes the session file and any lock we may hold.
  *  Returns false when the session doesn't exist or is held elsewhere. */
 export function deleteSession(id) {
-    const f = sessionFile(id);
+    let f;
+    try {
+        f = sessionFile(id);
+    }
+    catch {
+        return false;
+    }
     if (!existsSync(f))
         return false;
+    const ownedBefore = ownedLocks.has(id);
     const lock = acquireSessionLock(id);
     if (!lock.ok)
         return false;
+    let deleted = false;
     try {
         rmSync(f);
-        rmSync(lockFile(id), { force: true });
+        deleted = true;
         return true;
     }
     catch {
         return false;
     }
+    finally {
+        // A successful delete ends the session. On failure, release only a lock acquired by this call; a live
+        // SessionHub that already owned the lock must retain it and remain protected.
+        if (deleted || !ownedBefore)
+            releaseSessionLock(id);
+    }
 }
 /** A full UUID per session (the stable identity). */
 export const newSessionId = () => randomUUID();
@@ -97,10 +264,12 @@ export const newSessionId = () => randomUUID();
 export const shortId = (id) => id.slice(0, 8);
 /** Resolve a full id OR a unique prefix (e.g. the short id) to a session id, for `--resume`. */
 export function resolveSessionId(idOrPrefix) {
+    if (!validSessionId(idOrPrefix))
+        return null;
     if (existsSync(sessionFile(idOrPrefix)))
         return idOrPrefix;
-    const hit = listSessions().find((m) => m.id.startsWith(idOrPrefix));
-    return hit ? hit.id : null;
+    const hits = listSessions().filter((m) => m.id.startsWith(idOrPrefix));
+    return hits.length === 1 ? hits[0].id : null;
 }
 const STOP = new Set("the a an to of for and or with in on at my our your this that it is please can could you help me we add fix make do run create update change implement".split(" "));
 const WORDS = "amber basalt cedar delta ember flint grove harbor indigo jade kelp larch maple onyx quartz river slate terra umber vale willow zephyr".split(" ");
@@ -154,46 +323,170 @@ export function slugify(text, max = 40) {
         .slice(0, max)
         .replace(/-+$/, "");
 }
+/** Redact a deep in-memory copy while retaining fields that define session identity/routing. */
+function redactedSessionCopy(data) {
+    // Redact a deep COPY: the live turn may still need a credential the user supplied, but the durable
+    // transcript never should. Tool inputs/results are included, not just user message content.
+    const safe = redactSensitiveValue(data).value;
+    // Structural routing/identity fields must remain byte-for-byte stable even if a path happens to contain
+    // credential-looking text. Free-form meta (title, workingSet, todos, sourceName) and ALL history remain
+    // deeply redacted. The live objects are not modified by the redaction walk.
+    safe.meta.id = data.meta.id;
+    safe.meta.cwd = data.meta.cwd;
+    safe.meta.provider = data.meta.provider;
+    safe.meta.model = data.meta.model;
+    safe.meta.createdAt = data.meta.createdAt;
+    safe.meta.updatedAt = data.meta.updatedAt;
+    if (data.meta.source !== undefined)
+        safe.meta.source = data.meta.source;
+    if (data.meta.effort !== undefined)
+        safe.meta.effort = data.meta.effort;
+    if (data.meta.archived !== undefined)
+        safe.meta.archived = data.meta.archived;
+    if (data.meta.gatewayOwner !== undefined)
+        safe.meta.gatewayOwner = data.meta.gatewayOwner;
+    return safe;
+}
 export function saveSession(meta, history) {
+    checkedSessionId(meta.id);
     meta.updatedAt = new Date().toISOString();
-    const data = { meta, history };
-    writeFileSync(sessionFile(meta.id), JSON.stringify(data, null, 2), "utf8");
+    const safe = redactedSessionCopy({ meta, history });
+    const target = sessionFile(meta.id);
+    const tmp = `${target}.${process.pid}.${randomUUID()}.tmp`;
+    let fd;
+    try {
+        fd = openSync(tmp, "wx", 0o600);
+        writeFileSync(fd, JSON.stringify(safe, null, 2), "utf8");
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = undefined;
+        // Same directory/filesystem: readers observe the complete old JSON or complete new JSON, never a prefix.
+        renameSync(tmp, target);
+        chmodSync(target, 0o600);
+    }
+    catch (error) {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                /* preserve the original error */
+            }
+        }
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            /* preserve the original error */
+        }
+        throw error;
+    }
+}
+function isTimestamp(value) {
+    return typeof value === "string" && value.length > 0 && Number.isFinite(Date.parse(value));
 }
-/** True if a parsed object has the SessionData shape we can safely use (meta object + history array). */
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function isPersistedTodo(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const todo = value;
+    return (typeof todo.text === "string" &&
+        (todo.status === "pending" || todo.status === "in_progress" || todo.status === "done") &&
+        (todo.activeForm === undefined || typeof todo.activeForm === "string") &&
+        (todo.blockedBy === undefined || isStringArray(todo.blockedBy)) &&
+        (todo.owner === undefined || typeof todo.owner === "string"));
+}
+function isNeutralMessage(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const message = value;
+    if (message.role === "user") {
+        return typeof message.content === "string" && (message.images === undefined || (Array.isArray(message.images) && message.images.every((image) => {
+            if (!image || typeof image !== "object" || Array.isArray(image))
+                return false;
+            const attachment = image;
+            return typeof attachment.path === "string" && typeof attachment.mediaType === "string";
+        })));
+    }
+    if (message.role === "assistant") {
+        return typeof message.text === "string" && Array.isArray(message.toolUses) && message.toolUses.every((use) => {
+            if (!use || typeof use !== "object" || Array.isArray(use))
+                return false;
+            const tool = use;
+            return typeof tool.id === "string" && typeof tool.name === "string" && Object.hasOwn(tool, "input");
+        });
+    }
+    if (message.role === "tool") {
+        return Array.isArray(message.results) && message.results.every((result) => {
+            if (!result || typeof result !== "object" || Array.isArray(result))
+                return false;
+            const tool = result;
+            return typeof tool.id === "string" && typeof tool.name === "string" && typeof tool.content === "string" &&
+                (tool.isError === undefined || typeof tool.isError === "boolean");
+        });
+    }
+    return false;
+}
+function isSessionMeta(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const meta = value;
+    return (validSessionId(meta.id) &&
+        typeof meta.cwd === "string" &&
+        typeof meta.provider === "string" &&
+        typeof meta.model === "string" &&
+        typeof meta.title === "string" &&
+        isTimestamp(meta.createdAt) &&
+        isTimestamp(meta.updatedAt) &&
+        (meta.workingSet === undefined || isStringArray(meta.workingSet)) &&
+        (meta.todos === undefined || (Array.isArray(meta.todos) && meta.todos.every(isPersistedTodo))) &&
+        (meta.source === undefined || meta.source === "interactive" || meta.source === "gateway" || meta.source === "cron") &&
+        (meta.sourceName === undefined || typeof meta.sourceName === "string") &&
+        (meta.effort === undefined || typeof meta.effort === "string") &&
+        (meta.archived === undefined || typeof meta.archived === "boolean") &&
+        (meta.gatewayOwner === undefined || typeof meta.gatewayOwner === "string"));
+}
+/** True if a parsed object has the SessionData shape we can safely use. */
 function isSessionData(d) {
     const o = d;
-    return !!o && typeof o === "object" && !!o.meta && typeof o.meta === "object" && Array.isArray(o.history);
+    return !!o && typeof o === "object" && !Array.isArray(o) && isSessionMeta(o.meta) &&
+        Array.isArray(o.history) && o.history.every(isNeutralMessage);
 }
-export function loadSession(id) {
-    const p = sessionFile(id);
-    if (!existsSync(p))
-        return null;
+/** Read only. Legacy plaintext is redacted in the returned in-memory copy but intentionally not migrated
+ *  here: listing/resuming must not perform an unlocked write. The next explicit save atomically migrates it. */
+function readSessionFile(p) {
     try {
         const d = JSON.parse(readFileSync(p, "utf8"));
-        return isSessionData(d) ? d : null; // a corrupt / hand-edited file resumes as "no session" instead of crashing
+        return isSessionData(d) ? redactedSessionCopy(d) : null;
     }
     catch {
         return null;
     }
 }
+export function loadSession(id) {
+    if (!validSessionId(id))
+        return null;
+    const p = sessionFile(id);
+    if (!existsSync(p))
+        return null;
+    const data = readSessionFile(p);
+    return data?.meta.id === id ? data : null; // a corrupt, spoofed, or hand-edited file resumes as "no session"
+}
 /** Session metas, newest first; optionally filtered to a cwd. */
 export function listSessions(cwd) {
     let metas = [];
     for (const f of readdirSync(sessionsDir())) {
         if (!f.endsWith(".json"))
             continue;
-        try {
-            const d = JSON.parse(readFileSync(join(sessionsDir(), f), "utf8"));
-            if (d?.meta && typeof d.meta === "object" && d.meta.id && d.meta.updatedAt)
-                metas.push(d.meta); // skip metaless/corrupt
-        }
-        catch {
-            /* skip corrupt */
-        }
+        const d = readSessionFile(join(sessionsDir(), f));
+        if (d?.meta.id && validSessionId(d.meta.id) && f === `${d.meta.id}.json` && d.meta.updatedAt)
+            metas.push(d.meta); // skip spoofed/metalless/corrupt; never mutate while listing
     }
     if (cwd)
         metas = metas.filter((m) => m.cwd === cwd);
-    return metas.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    return metas.sort((a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt));
 }
 export function latestForCwd(cwd) {
     const [m] = listSessions(cwd);

package/dist/tools/all.js

@@ -12,6 +12,7 @@ import "./memory.js"; // memory_search/get/write/forget + skill_create
 import "./skill.js"; // skill loader
 import "./codebase.js"; // codebase_search
 import "./todo.js"; // todo_write
+import "./task.js"; // task (project-level persistent task pool)
 import "./send.js"; // send_file (self-gates on HARA_GATEWAY)
 import "./external_agent.js"; // external_agent (claude-code / codex delegation)
 import "./ask_user.js"; // ask_user

package/dist/tools/builtin.js

@@ -1,17 +1,53 @@
-import { readFile, stat } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { resolve, isAbsolute } from "node:path";
 import { stdout as procOut } from "node:process";
 import { registerTool } from "./registry.js";
 import { runShell } from "../sandbox.js";
-import { isProbablyBinary, nearestPaths } from "../fs-walk.js";
+import { nearestPaths } from "../fs-walk.js";
 import { emitDiff } from "../diff.js";
 import { recordEdit } from "../undo.js";
 import { atomicWriteText } from "../fs-write.js";
 import { invalidateFileCandidates } from "../context/mentions.js";
-import { BinaryFileError, streamFileSlice } from "../fs-read.js";
+import { BinaryFileError, readRegularFileSnapshot, streamFileSlice } from "../fs-read.js";
 import { startJob, listJobs, tailJob, killJob } from "../exec/jobs.js";
 import { hostsInCommand, isNetworkGitOp, hostFromConnectError, isConnectFailure, markHostUnreachable, isHostUnreachable, unreachableHostsSnapshot, } from "./net-reachability.js";
 const MAX = 100_000;
+/** Package installs are network-bound and routinely exceed the ordinary foreground cap. */
+export function isPackageInstallCommand(command) {
+    return /(?:^|[;&|]\s*)(?:npm\s+(?:i|install|ci)\b|pnpm\s+(?:i|install|add)\b|yarn(?:\s+(?:install|add))?(?:\s|$)|bun\s+(?:i|install|add)\b)/i.test(command.trim());
+}
+/** Resolve a bounded foreground timeout. Installs get a longer default, but remain attached so a headless
+ * run cannot exit, kill its background child, and leave node_modules half-written. */
+export function shellTimeoutMs(command, requested) {
+    if (Number.isFinite(requested) && requested > 0) {
+        return Math.min(Math.max(Math.trunc(requested), 1_000), 3_600_000);
+    }
+    return isPackageInstallCommand(command) ? 900_000 : 300_000;
+}
+export function isNgrokTunnelCommand(command) {
+    return /(?:^|[;&|]\s*)ngrok\s+(?:http|tcp|tls|start)\b/i.test(command.trim());
+}
+/** Read only the presence of ngrok auth — never return or print its value. */
+export function ngrokAuthConfigured(env = process.env, home = homedir()) {
+    if (env.NGROK_AUTHTOKEN || env.NGROK_API_KEY)
+        return true;
+    const files = [
+        resolve(home, ".config/ngrok/ngrok.yml"),
+        resolve(home, "Library/Application Support/ngrok/ngrok.yml"),
+        resolve(home, ".ngrok2/ngrok.yml"),
+    ];
+    for (const file of files) {
+        try {
+            if (existsSync(file) && /^\s*(?:authtoken|api_key)\s*:\s*\S+/im.test(readFileSync(file, "utf8")))
+                return true;
+        }
+        catch {
+            /* unreadable config counts as unconfigured */
+        }
+    }
+    return false;
+}
 /** Resolve the remote HOST a bare `git pull/fetch/push` targets (no URL in the command → host lives in the
  *  repo's remote config). Local + fast (no network); best-effort — returns "" on any hiccup. Only ever
  *  called after a host has already been marked unreachable, so it adds zero overhead on the happy path. */
@@ -48,7 +84,6 @@ export function capHeadTail(s, max = MAX) {
 }
 const READ_LINES = 300; // sized to stay useful under the global 24k-char tool-result context boundary
 const LINE_CAP = 2000; // chars per line before truncation (minified bundles / data lines)
-const BUFFERED_READ_BYTES = 4 * 1024 * 1024;
 /** Render a line slice of a file, cat -n style. The old read_file dumped the WHOLE file (100K-char cap,
  *  tail simply lost) — on long files that both flooded the context (~25k tokens per read, again on every
  *  re-read) and made everything past the cap unreachable. Now: line numbers (anchor for edits and for
@@ -89,19 +124,15 @@ registerTool({
     async run(input, ctx) {
         const p = abs(input.path, ctx.cwd);
         try {
-            const info = await stat(p);
-            if (info.size > BUFFERED_READ_BYTES)
-                return cap(await streamFileSlice(p, input.offset, input.limit ?? READ_LINES, { lineCap: LINE_CAP }));
-            const buf = await readFile(p);
-            if (isProbablyBinary(buf))
-                throw new BinaryFileError(p);
-            return cap(renderFileSlice(buf.toString("utf8"), input.offset, input.limit));
+            // streamFileSlice opens O_NONBLOCK, validates the same fd as a regular file, and stops after the
+            // requested window. Using it for every size removes the path-level stat→read race entirely.
+            return cap(await streamFileSlice(p, input.offset, input.limit ?? READ_LINES, { lineCap: LINE_CAP }));
         }
         catch (e) {
             if (e instanceof BinaryFileError)
                 return `Error: cannot read ${input.path}: file appears binary; use an image/media-specific tool or inspect it with \`file\`.`;
             const near = nearestPaths(ctx.cwd, input.path);
-            return `Error: cannot read ${input.path}: ${e.code ?? e.message}.` + (near.length ? ` Did you mean: ${near.join(", ")}?` : "");
+            return `Error: cannot read ${input.path}: ${e.message ?? e.code}.` + (near.length ? ` Did you mean: ${near.join(", ")}?` : "");
         }
     },
 });
@@ -121,26 +152,28 @@ registerTool({
         const p = abs(input.path, ctx.cwd);
         if (typeof input.content !== "string")
             return "Error: write_file `content` must be a string. No changes written.";
-        let prev = null;
+        let prevSnapshot = null;
         try {
-            prev = await readFile(p, "utf8");
+            prevSnapshot = await readRegularFileSnapshot(p);
         }
         catch (error) {
             if (error?.code !== "ENOENT")
-                return `Error: cannot inspect ${input.path}: ${error?.code ?? error?.message}. No changes written.`;
+                return `Error: cannot inspect ${input.path}: ${error?.message ?? error?.code}. No changes written.`;
         }
+        const prev = prevSnapshot?.text ?? null;
         if (prev === input.content)
             return `Unchanged ${p} (${input.content.length} chars already match).`;
+        let committed;
         try {
-            await atomicWriteText(p, input.content, { expected: prev });
+            committed = await atomicWriteText(p, input.content, { expected: prev, expectedIdentity: prevSnapshot ?? undefined });
         }
         catch (error) {
             return `Error: cannot write ${input.path}: ${error?.message ?? String(error)} No changes written.`;
         }
         emitDiff(input.path, prev ?? "", input.content, ctx.ui);
-        recordEdit([{ path: input.path, absPath: p, before: prev }]);
+        recordEdit([{ path: input.path, absPath: p, before: prev, beforeMode: prevSnapshot?.mode, committed, after: input.content }]);
         invalidateFileCandidates(ctx.cwd);
-        return `Wrote ${String(input.content).length} chars to ${p}`;
+        return `Wrote ${String(input.content).length} chars to ${p}` + (committed.warnings?.length ? ` Warning: ${committed.warnings.join("; ")}` : "");
     },
 });
 registerTool({
@@ -150,16 +183,20 @@ registerTool({
         type: "object",
         properties: {
             command: { type: "string" },
-            timeout_ms: { type: "number", description: "default 300000 (5 min); raise for a long build/transform, or use background:true for a server" },
-            background: { type: "boolean", description: "run as a background job (dev server, watcher, long task); returns a job id immediately — tail/kill it with the `job` tool" },
+            timeout_ms: { type: "number", description: "default 300000 (5 min), or 900000 (15 min) for package installs; bounded to 1s..1h" },
+            background: { type: "boolean", description: "run as a background job (dev server, watcher, long task); package installs stay foreground unless explicitly requested" },
         },
         required: ["command"],
     },
     kind: "exec",
     async run(input, ctx) {
+        if (isNgrokTunnelCommand(input.command) && !ngrokAuthConfigured()) {
+            return ("Skipped ngrok tunnel: no authentication was found in NGROK_AUTHTOKEN/NGROK_API_KEY or the standard ngrok config files. " +
+                "Configure ngrok authentication first, then retry. Do not rotate through other tunnel providers blindly; ask the user which authenticated provider to use.");
+        }
         if (input.background) {
             const id = startJob(input.command, ctx.cwd, ctx.sandbox ?? "off");
-            return `Started background job ${id}: \`${input.command}\`. Manage with the \`job\` tool — {action:"tail",id:"${id}"} for output, {action:"kill",id:"${id}"} to stop, {action:"list"} for all.`;
+            return `Started background job ${id}: \`${input.command}\`. Manage with the \`job\` tool — {action:"tail",id:"${id}"} for output, {action:"kill",id:"${id}"} to stop, {action:"list"} for all. Poll until it exits before running steps that depend on it.`;
         }
         // Network fault tolerance — short-circuit if this command targets a host already found unreachable this
         // session, so a repeat doesn't burn another ~75s OS connect timeout. Only pays the git-remote lookup
@@ -190,9 +227,10 @@ registerTool({
             : procOut.isTTY
                 ? (s) => procOut.write(s) // stream output in a plain terminal
                 : undefined;
+        const timeout = shellTimeoutMs(input.command, input.timeout_ms);
         try {
             const { stdout, stderr } = await runShell(input.command, ctx.cwd, ctx.sandbox ?? "off", {
-                timeout: input.timeout_ms ?? 300_000, // was 120s — a long file transform/build legitimately runs longer
+                timeout,
                 maxBuffer: 10 * 1024 * 1024,
                 onData: live,
             });
@@ -207,7 +245,7 @@ registerTool({
             // lane instead of blind-retrying into the same wall.
             if (/timed out after \d+ms/.test(String(e.message))) {
                 base +=
-                    `\n⏱ hara: the command hit its ${input.timeout_ms ?? 300_000}ms cap and was killed. Pick ONE: ` +
+                    `\n⏱ hara: the command hit its ${timeout}ms cap and was killed. Pick ONE: ` +
                         `a long build/transform → re-run with a larger timeout_ms; a server/watcher → background:true; ` +
                         `a network op (git/curl/npm) → do NOT just retry — check connectivity/proxy or skip this step and tell the user.`;
             }

package/dist/tools/codebase.js

@@ -72,7 +72,9 @@ registerTool({
         // to pure lexical when no index/embedder — zero behaviour change for the default install.
         const out = [];
         const seen = new Set();
-        const cfg = loadConfig();
+        // Tool execution can be dispatched to a registered agent home without changing process.cwd(). Its
+        // semantic-search provider/index settings belong to the tool context, not to the launcher directory.
+        const cfg = loadConfig({ cwd: ctx.cwd });
         const embed = getEmbedder(cfg);
         if (embed && indexExists("repo", ctx.cwd)) {
             try {