@nanhara/hara 0.121.0 → 0.121.1

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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/

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/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/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,

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,4 +1,6 @@
 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";
@@ -12,6 +14,35 @@ 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. */
@@ -150,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/web.js

@@ -7,6 +7,8 @@ import { lookup } from "node:dns/promises";
 import { isIP } from "node:net";
 import { wrapUntrusted } from "../security/external-content.js";
 const MAX = 60_000;
+const SEARCH_ATTEMPT_MS = 8_000;
+const SEARCH_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 Chrome/124.0 Safari/537.36";
 /** True for loopback / private / link-local / ULA / CGNAT addresses we must not let web_fetch reach. */
 export function isPrivateIp(ip) {
     const host = ip.replace(/^\[|\]$/g, "");
@@ -115,6 +117,146 @@ export function parseSearchResults(html, limit) {
     }
     return out;
 }
+/** Parse Baidu's server-rendered result headings. Baidu result links are redirects, which is fine:
+ *  web_fetch follows redirects while re-running its SSRF check on every hop. This gives mainland users a
+ *  keyless search path that does not depend on an overseas API being reachable. */
+export function parseBaiduSearchResults(html, limit) {
+    const strip = (s) => s
+        .replace(/<script[\s\S]*?<\/script>/gi, " ")
+        .replace(/<style[\s\S]*?<\/style>/gi, " ")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&nbsp;|&#160;/gi, " ")
+        .replace(/&amp;/gi, "&")
+        .replace(/&lt;/gi, "<")
+        .replace(/&gt;/gi, ">")
+        .replace(/&quot;/gi, '"')
+        .replace(/&#39;|&#x27;/gi, "'")
+        .replace(/\s+/g, " ")
+        .trim();
+    const headings = [];
+    const re = /<h3\b[^>]*>[\s\S]*?<a\b[^>]*href=(?:"([^"]+)"|'([^']+)')[^>]*>([\s\S]*?)<\/a>[\s\S]*?<\/h3>/gi;
+    let m;
+    while ((m = re.exec(html)) && headings.length < limit) {
+        const title = strip(m[3]);
+        const url = (m[1] ?? m[2] ?? "").replace(/&amp;/g, "&");
+        if (title && /^https?:\/\//i.test(url))
+            headings.push({ at: m.index, end: re.lastIndex, title, url });
+    }
+    return headings.map((h, i) => {
+        // The abstract normally sits between this heading and the next result heading. Strip that bounded
+        // slice and cap it; if Baidu changes class names the title/link still survive.
+        const boundary = headings[i + 1]?.at ?? Math.min(html.length, h.end + 1800);
+        const snippet = strip(html.slice(h.end, boundary)).slice(0, 240);
+        return { title: h.title, url: h.url, snippet };
+    });
+}
+/** Parse Bing's stable server-rendered result list (`cn.bing.com` is reachable in the mainland network
+ *  where overseas agent-search APIs commonly fail). */
+export function parseBingSearchResults(html, limit) {
+    const strip = (s) => s
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&nbsp;|&#160;/gi, " ")
+        .replace(/&ensp;|&#8194;/gi, " ")
+        .replace(/&emsp;|&#8195;/gi, " ")
+        .replace(/&amp;/gi, "&")
+        .replace(/&lt;/gi, "<")
+        .replace(/&gt;/gi, ">")
+        .replace(/&quot;/gi, '"')
+        .replace(/&#39;|&#x27;/gi, "'")
+        .replace(/\s+/g, " ")
+        .trim();
+    const out = [];
+    const blockRe = /<li\b[^>]*class=(?:"[^"]*\bb_algo\b[^"]*"|'[^']*\bb_algo\b[^']*')[^>]*>([\s\S]*?)<\/li>/gi;
+    let block;
+    while ((block = blockRe.exec(html)) && out.length < limit) {
+        const link = /<h2\b[^>]*>[\s\S]*?<a\b[^>]*href=(?:"([^"]+)"|'([^']+)')[^>]*>([\s\S]*?)<\/a>[\s\S]*?<\/h2>/i.exec(block[1]);
+        if (!link)
+            continue;
+        const url = (link[1] ?? link[2] ?? "").replace(/&amp;/g, "&");
+        const title = strip(link[3]);
+        if (!title || !/^https?:\/\//i.test(url))
+            continue;
+        const paragraph = /<p\b[^>]*>([\s\S]*?)<\/p>/i.exec(block[1]);
+        out.push({ title, url, snippet: strip(paragraph?.[1] ?? "").slice(0, 240) });
+    }
+    return out;
+}
+/** Best-effort parser for Google's classic HTML result shape. Google often serves a redirect/challenge
+ *  shell in mainland environments, so this is a fallback, not the sole search path. */
+export function parseGoogleSearchResults(html, limit) {
+    const strip = (s) => s
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&amp;/gi, "&")
+        .replace(/&lt;/gi, "<")
+        .replace(/&gt;/gi, ">")
+        .replace(/&quot;/gi, '"')
+        .replace(/&#39;|&#x27;/gi, "'")
+        .replace(/\s+/g, " ")
+        .trim();
+    const out = [];
+    const linkRe = /<a\b[^>]*href=(?:"([^"]+)"|'([^']+)')[^>]*>[\s\S]{0,1600}?<h3\b[^>]*>([\s\S]*?)<\/h3>[\s\S]*?<\/a>/gi;
+    let m;
+    while ((m = linkRe.exec(html)) && out.length < limit) {
+        let url = (m[1] ?? m[2] ?? "").replace(/&amp;/g, "&");
+        if (url.startsWith("/url?")) {
+            try {
+                url = new URL(url, "https://www.google.com").searchParams.get("q") ?? "";
+            }
+            catch {
+                url = "";
+            }
+        }
+        const title = strip(m[3]);
+        if (!title || !/^https?:\/\//i.test(url) || /(?:^|\.)google\.[^/]+\//i.test(url))
+            continue;
+        out.push({ title, url, snippet: "" });
+    }
+    return out;
+}
+/** Detect the common HTML shell returned by SPAs (root element + scripts/loading text, no readable body).
+ *  web_fetch intentionally does not execute arbitrary page JavaScript, so surfacing the limitation is
+ *  better than returning a misleading successful "(empty body)". */
+export function looksLikeJsRenderedShell(html, readable) {
+    if (readable.trim().length >= 180)
+        return false;
+    const hasRoot = /<(?:div|main)\b[^>]*(?:id=["'](?:root|app|__next)["']|data-reactroot)/i.test(html);
+    const scripts = (html.match(/<script\b/gi) ?? []).length;
+    const shellText = /(?:enable javascript|javascript is required|loading[.…]*|正在加载|请启用\s*javascript)/i.test(readable || html);
+    return (hasRoot && scripts > 0) || (scripts >= 2 && readable.trim().length < 40) || shellText;
+}
+async function searchFetch(url, init) {
+    return fetch(url, { ...init, signal: AbortSignal.timeout(SEARCH_ATTEMPT_MS) });
+}
+async function firstSuccessfulSearch(attempts, failures) {
+    if (!attempts.length)
+        return null;
+    return new Promise((resolve) => {
+        let remaining = attempts.length;
+        let settled = false;
+        for (const attempt of attempts) {
+            void attempt
+                .run()
+                .then((results) => {
+                if (results.length && !settled) {
+                    settled = true;
+                    resolve(results);
+                }
+                else if (!results.length) {
+                    failures.push(`${attempt.name} no results`);
+                }
+            })
+                .catch((e) => {
+                const reason = e?.name === "TimeoutError" || e?.name === "AbortError" ? "timeout" : (e?.message ?? String(e));
+                failures.push(`${attempt.name} ${reason}`);
+            })
+                .finally(() => {
+                remaining--;
+                if (remaining === 0 && !settled)
+                    resolve(null);
+            });
+        }
+    });
+}
 registerTool({
     name: "web_search",
     description: "Search the web and return the top results (title, URL, snippet). Use it to FIND information or pages you " +
@@ -135,51 +277,90 @@ registerTool({
             return "(empty query)";
         const limit = Math.min(Math.max(1, Number(input.limit) || 6), 10);
         const fmt = (rs) => rs.map((r, n) => `${n + 1}. ${r.title}\n   ${r.url}${r.snippet ? `\n   ${r.snippet}` : ""}`).join("\n\n");
-        const ctrl = new AbortController();
-        const timer = setTimeout(() => ctrl.abort(), 20_000);
-        try {
-            // Reliable path: Tavily (designed for agents, free tier) when a key is configured.
-            const key = process.env.HARA_SEARCH_API_KEY || process.env.TAVILY_API_KEY;
-            if (key) {
-                const res = await fetch("https://api.tavily.com/search", {
-                    method: "POST",
-                    signal: ctrl.signal,
-                    headers: { "content-type": "application/json" },
-                    body: JSON.stringify({ api_key: key, query: q, max_results: limit }),
-                });
-                if (res.ok) {
+        const failures = [];
+        // Race the configured agent-search API against a mainland-accessible HTML source. A blocked Tavily
+        // endpoint no longer adds an 8-second penalty before Hara starts the domestic fallback.
+        const key = process.env.HARA_SEARCH_API_KEY || process.env.TAVILY_API_KEY;
+        const primaryAttempts = [];
+        if (key) {
+            primaryAttempts.push({
+                name: "Tavily",
+                run: async () => {
+                    const res = await searchFetch("https://api.tavily.com/search", {
+                        method: "POST",
+                        headers: { "content-type": "application/json" },
+                        body: JSON.stringify({ api_key: key, query: q, max_results: limit }),
+                    });
+                    if (!res.ok)
+                        throw new Error(`HTTP ${res.status}`);
                     const j = (await res.json());
-                    const rs = (j.results ?? []).map((x) => ({ title: String(x.title ?? x.url ?? ""), url: String(x.url ?? ""), snippet: String(x.content ?? "").slice(0, 200) }));
-                    if (rs.length)
-                        return wrapUntrusted(fmt(rs), `web_search: ${q}`);
-                }
-                // Tavily failed → fall through to the keyless best-effort path.
-            }
-            // Keyless fallback: DuckDuckGo HTML (POST — GET returns a 202 challenge). May be rate-limited.
-            const res = await fetch("https://html.duckduckgo.com/html/", {
-                method: "POST",
-                signal: ctrl.signal,
-                redirect: "follow",
-                headers: {
-                    "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36",
-                    "content-type": "application/x-www-form-urlencoded",
-                    accept: "text/html",
+                    return (j.results ?? []).map((x) => ({ title: String(x.title ?? x.url ?? ""), url: String(x.url ?? ""), snippet: String(x.content ?? "").slice(0, 200) }));
                 },
-                body: `q=${encodeURIComponent(q)}`,
             });
-            if (!res.ok)
-                return `Search failed: HTTP ${res.status}. Keyless search is rate-limited — set HARA_SEARCH_API_KEY (Tavily) for reliable search, or web_fetch a known URL.`;
-            const results = parseSearchResults(await res.text(), limit);
-            if (!results.length)
-                return "(no results — the keyless endpoint is rate-limited or changed. Set HARA_SEARCH_API_KEY (Tavily) for reliable search, or web_fetch a known URL.)";
-            return wrapUntrusted(fmt(results), `web_search: ${q}`);
-        }
-        catch (e) {
-            return `Search failed: ${e?.name === "AbortError" ? "timed out (20s)" : (e?.message ?? e)}`;
-        }
-        finally {
-            clearTimeout(timer);
         }
+        primaryAttempts.push({
+            name: "Bing CN",
+            run: async () => {
+                const res = await searchFetch(`https://cn.bing.com/search?q=${encodeURIComponent(q)}&count=${limit}&setlang=zh-Hans`, {
+                    method: "GET",
+                    redirect: "follow",
+                    headers: { "user-agent": SEARCH_UA, accept: "text/html" },
+                });
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                return parseBingSearchResults(await res.text(), limit);
+            },
+        });
+        const primary = await firstSuccessfulSearch(primaryAttempts, failures);
+        if (primary)
+            return wrapUntrusted(fmt(primary), `web_search: ${q}`);
+        // Secondary sources run concurrently, keeping total failure latency bounded. Google is included as a
+        // user-friendly fallback where it is reachable, but is never the sole path (mainland often gets a shell).
+        const secondary = await firstSuccessfulSearch([
+            {
+                name: "Baidu",
+                run: async () => {
+                    const res = await searchFetch(`https://www.baidu.com/s?wd=${encodeURIComponent(q)}&rn=${limit}`, {
+                        method: "GET",
+                        redirect: "follow",
+                        headers: { "user-agent": SEARCH_UA, accept: "text/html" },
+                    });
+                    if (!res.ok)
+                        throw new Error(`HTTP ${res.status}`);
+                    return parseBaiduSearchResults(await res.text(), limit);
+                },
+            },
+            {
+                name: "Google",
+                run: async () => {
+                    const res = await searchFetch(`https://www.google.com/search?q=${encodeURIComponent(q)}&num=${limit}&hl=zh-CN`, {
+                        method: "GET",
+                        redirect: "follow",
+                        headers: { "user-agent": SEARCH_UA, accept: "text/html" },
+                    });
+                    if (!res.ok)
+                        throw new Error(`HTTP ${res.status}`);
+                    return parseGoogleSearchResults(await res.text(), limit);
+                },
+            },
+            {
+                name: "DuckDuckGo",
+                run: async () => {
+                    const res = await searchFetch("https://html.duckduckgo.com/html/", {
+                        method: "POST",
+                        redirect: "follow",
+                        headers: { "user-agent": SEARCH_UA, "content-type": "application/x-www-form-urlencoded", accept: "text/html" },
+                        body: `q=${encodeURIComponent(q)}`,
+                    });
+                    if (!res.ok)
+                        throw new Error(`HTTP ${res.status}`);
+                    return parseSearchResults(await res.text(), limit);
+                },
+            },
+        ], failures);
+        if (secondary)
+            return wrapUntrusted(fmt(secondary), `web_search: ${q}`);
+        return `Search failed across available providers (${failures.join("; ")}). Check connectivity/proxy, configure HARA_SEARCH_API_KEY, or web_fetch a known URL.`;
     },
 });
 registerTool({
@@ -232,6 +413,11 @@ registerTool({
             let text = /html/i.test(ct) ? htmlToText(raw) : raw;
             if (text.length > cap)
                 text = text.slice(0, cap) + `\n…[truncated ${text.length - cap} chars]`;
+            if (/html/i.test(ct) && looksLikeJsRenderedShell(raw, text)) {
+                const hint = "This page appears to be JavaScript-rendered; web_fetch received only the SPA shell and does not execute page scripts. " +
+                    "Use an available browser/web skill for the rendered page, or the site's authenticated API/connector (for example the Feishu Docs API).";
+                return `# ${current.href} (HTTP ${res.status})\n\n${wrapUntrusted(`${text || "(empty shell)"}\n\n${hint}`, current.href)}`;
+            }
             return `# ${current.href} (HTTP ${res.status})\n\n${wrapUntrusted(text || "(empty body)", current.href)}`;
         }
         catch (e) {

package/dist/tui/run.js

@@ -4,36 +4,39 @@
 import { render, Box, Text, useApp, useInput } from "ink";
 import { createElement } from "react";
 import { App } from "./App.js";
-export async function runTui(props) {
-    const instance = render(createElement(App, props));
-    // Resize repaint fix. ink 6.8's own resize handler only clears the screen when the terminal gets
-    // NARROWER; on a WIDEN (or a resize it doesn't classify as narrowing) it just re-renders, so the old
-    // frame — reflowed at the new width — is never erased, and the ~125ms spinner tick stacks a fresh copy
-    // each time (the "moved the window and the UI stacked up" garble). We complement it: on ANY resize,
-    // clear ink's tracked output so the next render starts clean. Debounced by a microtask so a burst of
-    // resize events during a window drag collapses to one clear.
-    const out = process.stdout;
-    let pending = false;
+/** Ink 6.8 clears before repainting when a terminal gets narrower, but not when it gets wider. Install a
+ *  complementary WIDTH-only clear ahead of Ink's own resize listener so Ink's normal layout pass redraws
+ *  the frame immediately afterwards. Never clear on a rows-only resize: `instance.clear()` erases the
+ *  dynamic region without scheduling a React render, which made an idle input box disappear when a user
+ *  dragged only the top/bottom edge of the terminal window. Exported for a small ordering regression test. */
+export function installResizeRepaint(out, instance) {
+    let lastColumns = out.columns;
     const onResize = () => {
-        if (pending)
+        const columns = out.columns;
+        if (!columns || columns === lastColumns)
             return;
-        pending = true;
-        queueMicrotask(() => {
-            pending = false;
-            try {
-                instance.clear();
-            }
-            catch {
-                /* best-effort — never let a repaint fix crash the session */
-            }
-        });
+        lastColumns = columns;
+        try {
+            instance.clear();
+        }
+        catch {
+            /* best-effort — never let a repaint fix crash the session */
+        }
     };
-    out.on("resize", onResize);
+    // Ink registered its listener inside render() already. Prepending is essential: clearing AFTER Ink's
+    // repaint is precisely what leaves the prompt blank until some unrelated state update happens.
+    out.prependListener("resize", onResize);
+    return () => out.off("resize", onResize);
+}
+export async function runTui(props) {
+    const instance = render(createElement(App, props));
+    const out = process.stdout;
+    const removeResizeRepaint = installResizeRepaint(out, instance);
     try {
         await instance.waitUntilExit();
     }
     finally {
-        out.off("resize", onResize);
+        removeResizeRepaint();
     }
 }
 // A tiny ink yes/no prompt for pre-TUI confirms (e.g. the first-run "create AGENTS.md?" offer).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanhara/hara",
-  "version": "0.121.0",
+  "version": "0.121.1",
   "description": "hara — a coding agent CLI that runs like an engineering org.",
   "bin": {
     "hara": "dist/index.js"