@nanhara/hara 0.120.0 → 0.121.1

package/dist/index.js

@@ -1574,9 +1574,21 @@ program
         version: pkg.version,
         providerId: cfg.provider,
         model: cfg.model,
-        buildSessionProvider: async () => withRouting(await buildProvider(cfg), cfg),
-        buildProviderFor: async (model, effort) => withRouting(await buildProvider({ ...cfg, model, reasoningEffort: effort ?? cfg.reasoningEffort }), cfg),
-        listModels: () => listModels(cfg.baseURL ?? providerDefaultBaseURL(cfg.provider), cfg.apiKey ?? ""),
+        // `hara serve` is persistent, but config.json is user-editable at any time. Re-read it for every
+        // new/resumed session and model operation so a repaired/rotated key takes effect without restarting
+        // the desktop server (and, critically, never ask for a key that is already on disk).
+        buildSessionProvider: async () => {
+            const live = loadConfig();
+            return withRouting(await buildProvider(live), live);
+        },
+        buildProviderFor: async (model, effort) => {
+            const live = loadConfig();
+            return withRouting(await buildProvider({ ...live, model, reasoningEffort: effort ?? live.reasoningEffort }), live);
+        },
+        listModels: () => {
+            const live = loadConfig();
+            return listModels(live.baseURL ?? providerDefaultBaseURL(live.provider), live.apiKey ?? "");
+        },
         effortLevels: levelsFor(resolvePlatform(cfg.provider, cfg.baseURL ?? providerDefaultBaseURL(cfg.provider)).reasoning).filter((e) => !!e),
         spawnSubagent: (provider, scwd, projectContext, stats, task, role) => runSubagent(cfg, provider, scwd, sandbox, projectContext, stats, task, role),
         guardian: guardianOpt,
@@ -2036,6 +2048,94 @@ program
         out(`\n(gh CLI unavailable or filing failed — copy everything below into ${NEW_ISSUE_URL})\n\n# ${issueTitle(desc)}\n\n${body}\n`);
     }
 });
+// `hara desk` — connect to a hara-desk coordination server (identity registry + task board).
+// The desk is the closed-source enterprise piece; this is the open-source client side.
+const deskCmd = program.command("desk").description("coordinate with a hara-desk server (register · post · board · claim · complete)");
+deskCmd
+    .command("register")
+    .description("register this agent with a desk and save credentials to ~/.hara/desk.json")
+    .requiredOption("--url <url>", "desk base URL (e.g. http://127.0.0.1:4200)")
+    .requiredOption("--key <enrollKey>", "the desk's enroll key")
+    .option("--name <name>", "agent name shown in the registry", "hara-cli")
+    .option("--owner <owner>", "the human this agent belongs to", "me")
+    .action(async (o) => {
+    const { registerAgent } = await import("./desk.js");
+    try {
+        const creds = await registerAgent(o.url, o.key, o.name, o.owner);
+        out(c.green("✓ registered ") + `${creds.agentId} (owner ${creds.owner}) → ${creds.url}\n`);
+    }
+    catch (e) {
+        out(c.red(`register failed: ${e.message}\n`));
+    }
+});
+deskCmd
+    .command("post [title...]")
+    .description("post a task or feedback report to the board")
+    .option("--dispatch", "a dispatch task (someone does work) instead of a feedback report")
+    .option("--high", "high-risk dispatch (needs an owner ack before it can complete)")
+    .option("--body <text>", "task body / details", "")
+    .action(async (parts, o) => {
+    const { loadCreds, deskCall } = await import("./desk.js");
+    const creds = loadCreds();
+    if (!creds)
+        return void out(c.red("not registered — run `hara desk register --url … --key …` first\n"));
+    const title = (parts ?? []).join(" ").trim();
+    if (!title)
+        return void out("Usage: hara desk post <title> [--dispatch] [--high] [--body …]\n");
+    try {
+        const r = await deskCall(creds.url, "POST", "/tasks", { token: creds.token, body: { kind: o.dispatch ? "dispatch" : "feedback", risk: o.high ? "high" : "low", title, body: o.body } });
+        out(c.green("✓ posted ") + `${r.task.id} (${r.task.kind}/${r.task.state})\n`);
+    }
+    catch (e) {
+        out(c.red(`post failed: ${e.message}\n`));
+    }
+});
+deskCmd
+    .command("board")
+    .description("list the board (default: open tasks)")
+    .option("--state <state>", "open | claimed | done | cancelled", "open")
+    .option("--kind <kind>", "feedback | dispatch")
+    .action(async (o) => {
+    const { loadCreds, deskCall } = await import("./desk.js");
+    const creds = loadCreds();
+    if (!creds)
+        return void out(c.red("not registered — run `hara desk register` first\n"));
+    try {
+        const q = `/tasks?state=${encodeURIComponent(o.state)}${o.kind ? `&kind=${encodeURIComponent(o.kind)}` : ""}`;
+        const r = await deskCall(creds.url, "GET", q, { token: creds.token });
+        if (!r.tasks.length)
+            return void out(c.dim("(board empty)\n"));
+        for (const t of r.tasks)
+            out(`${t.id}  ${c.bold(t.kind)}${t.risk === "high" ? c.red("!") : " "} ${t.state.padEnd(8)} ${t.title}\n`);
+    }
+    catch (e) {
+        out(c.red(`board failed: ${e.message}\n`));
+    }
+});
+for (const [verb, path, ok] of [
+    ["claim", "claim", "claimed"],
+    ["complete", "complete", "completed"],
+    ["ack", "ack", "acked"],
+    ["cancel", "cancel", "cancelled"],
+]) {
+    deskCmd
+        .command(`${verb} <taskId>`)
+        .description(`${verb} a task`)
+        .option("--detail <text>", "note (complete)", "")
+        .action(async (taskId, o) => {
+        const { loadCreds, deskCall } = await import("./desk.js");
+        const creds = loadCreds();
+        if (!creds)
+            return void out(c.red("not registered — run `hara desk register` first\n"));
+        try {
+            const r = await deskCall(creds.url, "POST", `/tasks/${taskId}/${path}`, { token: creds.token, body: verb === "complete" ? { detail: o.detail } : {} });
+            out(c.green(`✓ ${ok} `) + `${r.task?.id ?? taskId}${r.task ? ` (${r.task.state})` : ""}\n`);
+        }
+        catch (e) {
+            out(c.red(`${verb} failed: ${e.message}\n`));
+        }
+    });
+}
 const skillsCmd = program.command("skills").description("manage skills (.hara/skills/<name>/SKILL.md)");
 skillsCmd
     .command("init")

package/dist/security/secrets.js

@@ -0,0 +1,75 @@
+/** Shared secret redaction for anything that may leave the live model context (session JSON, public
+ *  feedback, logs). Deliberately conservative: a false positive hides a value in a local transcript;
+ *  a false negative leaves a credential on disk. */
+const PATTERNS = [
+    {
+        label: "private-key",
+        re: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+        replace: "<REDACTED:private-key>",
+    },
+    { label: "sk-key", re: /\bsk-[A-Za-z0-9_-]{8,}\b/g, replace: "sk-***" },
+    { label: "github-token", re: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, replace: "gh*_***" },
+    { label: "aws-key", re: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, replace: "AWS-KEY-***" },
+    { label: "jwt", re: /\beyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, replace: "JWT-***" },
+    {
+        label: "bearer-token",
+        re: /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/gi,
+        replace: "Bearer ***",
+    },
+    {
+        // Generic all-caps environment variables such as OPENAI_KEY / SOME_SERVICE_PRIVATE_KEY. Keep this
+        // case-sensitive so ordinary prose/code identifiers ending in "key" are not over-redacted.
+        label: "environment-credential",
+        re: /(\b[A-Z][A-Z0-9_]*(?:_KEY|_SECRET|_TOKEN|_PASSWORD|_PASSWD)\b\s*=\s*)(["']?)([^\s"',;}\]]{6,})(["']?)/g,
+        replace: (_match, prefix, open, _value, close) => `${prefix}${open}***${close}`,
+    },
+    {
+        // FEISHU_APP_SECRET=… · apiKey: "…" · "access_token": "…". The optional quote immediately
+        // after the key handles JSON without consuming the opening quote of the value.
+        label: "credential-assignment",
+        re: /(\b(?:[A-Za-z][A-Za-z0-9_.-]*(?:api[_-]?key|apikey|secret|token|password|passwd)[A-Za-z0-9_.-]*|(?:api[_-]?key|apikey|secret|token|password|passwd)[A-Za-z0-9_.-]*)\b["']?\s*[:=]\s*)(["']?)([^\s"',;}\]]{6,})(["']?)/gi,
+        replace: (_match, prefix, open, _value, close) => `${prefix}${open}***${close}`,
+    },
+    {
+        label: "authorization",
+        re: /(\bAuthorization\s*[:=]\s*)(?!Bearer\s+)(["']?)([^\s"',;}\]]{6,})(["']?)/gi,
+        replace: (_match, prefix, open, _value, close) => `${prefix}${open}***${close}`,
+    },
+    {
+        label: "credential-flag",
+        re: /(--?(?:api[-_]?key|token|secret|password|passwd)(?:\s+|=))(["']?)([^\s"']{6,})(["']?)/gi,
+        replace: (_match, prefix, open, _value, close) => `${prefix}${open}***${close}`,
+    },
+];
+export function redactSensitiveText(text) {
+    let out = text;
+    const redactions = [];
+    for (const pattern of PATTERNS) {
+        pattern.re.lastIndex = 0;
+        out = out.replace(pattern.re, (...args) => {
+            redactions.push(pattern.label);
+            return typeof pattern.replace === "string" ? pattern.replace : pattern.replace(...args);
+        });
+    }
+    return { text: out, redactions };
+}
+/** Deep-copy a JSON-shaped value while redacting every string. Session history contains secrets not only
+ *  in user text but also in assistant tool inputs and tool results, so a top-level content-only pass is
+ *  insufficient. The live value is never mutated. */
+export function redactSensitiveValue(value) {
+    const hits = [];
+    const walk = (v) => {
+        if (typeof v === "string") {
+            const r = redactSensitiveText(v);
+            hits.push(...r.redactions);
+            return r.text;
+        }
+        if (Array.isArray(v))
+            return v.map(walk);
+        if (v && typeof v === "object") {
+            return Object.fromEntries(Object.entries(v).map(([k, child]) => [k, walk(child)]));
+        }
+        return v;
+    };
+    return { value: walk(value), redactions: hits };
+}

package/dist/serve/server.js

@@ -223,10 +223,10 @@ export async function startServe(opts, deps) {
                     case "session.create": {
                         const provider = await deps.buildSessionProvider();
                         if (!provider)
-                            return reply(rpcError(id, ERR.INTERNAL, "provider not authenticated — run `hara setup`"));
+                            return reply(rpcError(id, ERR.INTERNAL, "provider not authenticated — check the active profile and ~/.hara/config.json"));
                         const cwd = typeof p.cwd === "string" && p.cwd ? p.cwd : opts.cwd;
                         const approval = ["suggest", "auto-edit", "full-auto"].includes(p.approval) ? p.approval : deps.approval;
-                        const s = hub.create({ cwd, provider, providerId: deps.providerId, model: deps.model, approval, projectContext: loadAgentsMd(cwd) || undefined });
+                        const s = hub.create({ cwd, provider, providerId: provider.id, model: provider.model, approval, projectContext: loadAgentsMd(cwd) || undefined });
                         return reply(rpcResult(id, { sessionId: s.meta.id, model: s.meta.model }));
                     }
                     case "session.resume": {
@@ -234,7 +234,7 @@ export async function startServe(opts, deps) {
                             return reply(rpcError(id, ERR.PARAMS, "sessionId required"));
                         const provider = await deps.buildSessionProvider();
                         if (!provider)
-                            return reply(rpcError(id, ERR.INTERNAL, "provider not authenticated — run `hara setup`"));
+                            return reply(rpcError(id, ERR.INTERNAL, "provider not authenticated — check the active profile and ~/.hara/config.json"));
                         const r = hub.resume(p.sessionId, { provider, approval: deps.approval, projectContext: undefined });
                         if ("missing" in r)
                             return reply(rpcError(id, ERR.NO_SESSION, `no session ${p.sessionId}`));
@@ -305,8 +305,8 @@ export async function startServe(opts, deps) {
                             return reply(rpcError(id, ERR.PARAMS, "sessionId required"));
                         const provider = await deps.buildSessionProvider();
                         if (!provider)
-                            return reply(rpcError(id, ERR.INTERNAL, "provider not authenticated — run `hara setup`"));
-                        const r = hub.fork(p.sessionId, { provider, providerId: deps.providerId, approval: deps.approval, projectContext: undefined });
+                            return reply(rpcError(id, ERR.INTERNAL, "provider not authenticated — check the active profile and ~/.hara/config.json"));
+                        const r = hub.fork(p.sessionId, { provider, providerId: provider.id, approval: deps.approval, projectContext: undefined });
                         if ("missing" in r)
                             return reply(rpcError(id, ERR.NO_SESSION, `no session ${p.sessionId}`));
                         r.session.projectContext = loadAgentsMd(r.session.meta.cwd) || undefined;

package/dist/serve/sessions.js

@@ -42,6 +42,10 @@ export class SessionHub {
         if (!lock.ok)
             return { lockedBy: lock.pid ?? 0 };
         const s = { meta: prior.meta, history: [...prior.history], provider: o.provider, approval: o.approval, autoApprove: new Set(), stats: { input: 0, output: 0 }, projectContext: o.projectContext, busy: false, abort: null };
+        // A rotated config may change the provider/model between runs. The resumed transcript is preserved,
+        // while new turns and subsequent persistence accurately reflect the live route.
+        s.meta.provider = o.provider.id;
+        s.meta.model = o.provider.model;
         this.sessions.set(id, s);
         return { session: s };
     }
@@ -101,7 +105,7 @@ export class SessionHub {
             id: newSessionId(),
             cwd: src.meta.cwd,
             provider: o.providerId,
-            model: src.meta.model,
+            model: o.provider.model,
             title: src.meta.title ? `${src.meta.title} ⑂` : "",
             createdAt: new Date().toISOString(),
             updatedAt: "",

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,7 +21,8 @@ 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 });
+    chmodSync(d, 0o700); // tighten legacy installs too; session transcripts are private
     return d;
 }
 const sessionFile = (id) => join(sessionsDir(), `${id}.json`);
@@ -157,39 +159,79 @@ export function slugify(text, max = 40) {
 export function saveSession(meta, history) {
     meta.updatedAt = new Date().toISOString();
     const data = { meta, history };
-    writeFileSync(sessionFile(meta.id), JSON.stringify(data, null, 2), "utf8");
+    // 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;
+    // Keep structural routing/identity fields stable even if a path/model happens to resemble a secret.
+    safe.meta.id = meta.id;
+    safe.meta.cwd = meta.cwd;
+    safe.meta.provider = meta.provider;
+    safe.meta.model = meta.model;
+    safe.meta.createdAt = meta.createdAt;
+    safe.meta.updatedAt = meta.updatedAt;
+    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;
+        renameSync(tmp, target); // same filesystem: readers see the complete old or complete new JSON
+        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;
+    }
 }
 /** True if a parsed object has the SessionData shape we can safely use (meta object + history array). */
 function isSessionData(d) {
     const o = d;
     return !!o && typeof o === "object" && !!o.meta && typeof o.meta === "object" && Array.isArray(o.history);
 }
-export function loadSession(id) {
-    const p = sessionFile(id);
-    if (!existsSync(p))
-        return null;
+/** Parse a legacy session and redact the in-memory copy. Reads stay read-only (no unlocked migration race);
+ *  the next explicit save atomically replaces the old file with its private, redacted form. */
+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
+        if (!isSessionData(d))
+            return null;
+        return redactSensitiveValue(d).value;
     }
     catch {
         return null;
     }
 }
+export function loadSession(id) {
+    const p = sessionFile(id);
+    if (!existsSync(p))
+        return null;
+    return readSessionFile(p); // a corrupt / hand-edited file resumes as "no session" instead of crashing
+}
 /** 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 && d.meta.updatedAt)
+            metas.push(d.meta); // skip metaless/corrupt; never mutate while listing
     }
     if (cwd)
         metas = metas.filter((m) => m.cwd === cwd);

package/dist/tools/builtin.js

@@ -1,14 +1,48 @@
-import { readFile, writeFile, mkdir } from "node:fs/promises";
-import { dirname, resolve, isAbsolute } from "node:path";
+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 { nearestPaths } from "../fs-walk.js";
+import { isProbablyBinary, 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 { 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 foreground cap. When the model omits an
+ *  explicit foreground/background choice, detach these commands into the existing job system so the UI
+ *  remains responsive and the agent can poll output instead of waiting five minutes for a hard kill. */
+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());
+}
+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. */
@@ -43,8 +77,9 @@ export function capHeadTail(s, max = MAX) {
     const head = Math.floor(max * 0.6);
     return s.slice(0, head) + `\n…[${s.length - max} chars truncated]…\n` + s.slice(s.length - (max - head));
 }
-const READ_LINES = 2000; // default lines per read_file call (a long file is read in slices, not dumped whole)
+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
@@ -71,22 +106,31 @@ export function renderFileSlice(text, offset, limit) {
 }
 registerTool({
     name: "read_file",
-    description: "Read a UTF-8 text file; returns cat -n style numbered lines. Reads up to 2000 lines by default — for a longer file pass offset/limit to read the next slice (the output header tells you the total and where to continue). Prefer grep to locate, then read just that region.",
+    description: "Read a UTF-8 text file; returns cat -n style numbered lines. Reads up to 300 lines by default — for a longer file pass offset/limit to read the next slice (the header tells you where to continue). Large files are streamed instead of loaded whole. Prefer grep to locate, then read just that region.",
     input_schema: {
         type: "object",
         properties: {
             path: { type: "string", description: "File path, relative to cwd or absolute" },
             offset: { type: "number", description: "1-based line number to start from (for long files)" },
-            limit: { type: "number", description: "max lines to return (default 2000)" },
+            limit: { type: "number", description: "max lines to return (default 300)" },
         },
         required: ["path"],
     },
     kind: "read",
     async run(input, ctx) {
+        const p = abs(input.path, ctx.cwd);
         try {
-            return cap(renderFileSlice(await readFile(abs(input.path, ctx.cwd), "utf8"), input.offset, input.limit));
+            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));
         }
         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(", ")}?` : "");
         }
@@ -106,17 +150,27 @@ registerTool({
     kind: "edit",
     async run(input, ctx) {
         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;
         try {
             prev = await readFile(p, "utf8");
         }
-        catch {
-            /* new file */
+        catch (error) {
+            if (error?.code !== "ENOENT")
+                return `Error: cannot inspect ${input.path}: ${error?.code ?? error?.message}. No changes written.`;
+        }
+        if (prev === input.content)
+            return `Unchanged ${p} (${input.content.length} chars already match).`;
+        try {
+            await atomicWriteText(p, input.content, { expected: prev });
+        }
+        catch (error) {
+            return `Error: cannot write ${input.path}: ${error?.message ?? String(error)} No changes written.`;
         }
-        await mkdir(dirname(p), { recursive: true });
-        await writeFile(p, input.content, "utf8");
         emitDiff(input.path, prev ?? "", input.content, ctx.ui);
         recordEdit([{ path: input.path, absPath: p, before: prev }]);
+        invalidateFileCandidates(ctx.cwd);
         return `Wrote ${String(input.content).length} chars to ${p}`;
     },
 });
@@ -127,16 +181,21 @@ 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); set explicitly for a foreground long build/transform" },
+            background: { type: "boolean", description: "run as a background job (dev server, watcher, long task). Package installs auto-background when this field and timeout_ms are omitted. Poll with the `job` tool before depending on completion." },
         },
         required: ["command"],
     },
     kind: "exec",
     async run(input, ctx) {
-        if (input.background) {
+        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.");
+        }
+        const autoPackageJob = input.background === undefined && input.timeout_ms === undefined && isPackageInstallCommand(input.command);
+        if (input.background || autoPackageJob) {
             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 `${autoPackageJob ? "Package install auto-started" : "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 installed packages.`;
         }
         // 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

package/dist/tools/edit.js

@@ -1,10 +1,12 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import { isAbsolute, resolve } from "node:path";
 import { registerTool } from "./registry.js";
 import { nearestPaths } from "../fs-walk.js";
 import { emitDiff } from "../diff.js";
 import { applyEdits } from "./apply-core.js";
 import { recordEdit } from "../undo.js";
+import { atomicWriteText } from "../fs-write.js";
+import { invalidateFileCandidates } from "../context/mentions.js";
 registerTool({
     name: "edit_file",
     description: "Edit an existing file by replacing exact strings. Provide a single `old_string`/`new_string`, " +
@@ -53,9 +55,15 @@ registerTool({
         const res = applyEdits(text, edits);
         if ("error" in res)
             return `Error: ${res.error} in ${input.path}. No changes written.`;
-        await writeFile(p, res.text, "utf8");
+        try {
+            await atomicWriteText(p, res.text, { expected: text });
+        }
+        catch (error) {
+            return `Error: cannot edit ${input.path}: ${error?.message ?? String(error)} No changes written.`;
+        }
         emitDiff(input.path, text, res.text, ctx.ui);
         recordEdit([{ path: input.path, absPath: p, before: text }]);
+        invalidateFileCandidates(ctx.cwd);
         const note = res.fuzzy ? " (quote-normalized)" : "";
         const plural = (n, w) => `${n} ${w}${n === 1 ? "" : "s"}`;
         return `Edited ${input.path}: ${plural(edits.length, "edit")}, ${plural(res.total, "replacement")}${note}.`;