@nanhara/hara 0.122.2 → 0.122.4

package/dist/tools/skill.js

@@ -27,7 +27,7 @@ registerTool({
         const located = `Skill directory (absolute): ${dirname(sk.file)}\nRead any sibling files this skill mentions (e.g. references/…, assets/…) from under that directory.\n\n${body}`;
         if (sk.context === "fork" && ctx.spawn) {
             // fork: run the skill as a delegated sub-agent rather than inlining it into this turn
-            return await ctx.spawn(`Follow this skill to complete the current task:\n\n${located}`);
+            return await ctx.spawn(`Follow this skill to complete the current task:\n\n${located}`, undefined, ctx.signal);
         }
         return located; // inline (default): the body enters the conversation as this tool's result
     },

package/dist/tools/task.js

@@ -6,9 +6,9 @@ import { basename, join, resolve } from "node:path";
 import { homedir } from "node:os";
 import { createHash, randomUUID } from "node:crypto";
 import { registerTool } from "./registry.js";
+import { sleepSync } from "../sync-sleep.js";
 const TASK_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const TASK_STATUSES = new Set(["pending", "in_progress", "done"]);
-const sleepCell = new Int32Array(new SharedArrayBuffer(4));
 const LOCK_ATTEMPTS = 500;
 const LOCK_WAIT_MS = 10;
 /** Resolve aliases/symlinks before deriving the key. A missing path still gets a stable absolute key so
@@ -113,7 +113,7 @@ function withTaskLock(cwd, fn) {
                     continue;
                 }
             }
-            Atomics.wait(sleepCell, 0, 0, LOCK_WAIT_MS);
+            sleepSync(LOCK_WAIT_MS);
             continue;
         }
         const candidate = { pid: process.pid, token: randomUUID() };
@@ -144,7 +144,7 @@ function withTaskLock(cwd, fn) {
                     rmSync(reclaim, { force: true });
             }
         }
-        Atomics.wait(sleepCell, 0, 0, LOCK_WAIT_MS);
+        sleepSync(LOCK_WAIT_MS);
     }
     if (!claim)
         throw new Error("task store is busy; retry the operation");

package/dist/tools/web.js

@@ -349,21 +349,36 @@ export function looksLikeJsRenderedShell(html, readable) {
     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) });
+function interrupted(label) {
+    const error = new Error(`${label} interrupted by agent run deadline or cancellation`);
+    error.name = "AbortError";
+    return error;
 }
-async function firstSuccessfulSearch(attempts, failures) {
+async function searchFetch(url, init, parentSignal) {
+    if (parentSignal?.aborted)
+        throw interrupted("web search");
+    const attemptSignal = AbortSignal.timeout(SEARCH_ATTEMPT_MS);
+    const signal = parentSignal ? AbortSignal.any([parentSignal, attemptSignal]) : attemptSignal;
+    return fetch(url, { ...init, signal });
+}
+async function firstSuccessfulSearch(attempts, failures, signal) {
     // Try one provider at a time. Search terms can be sensitive; a successful request must not be mirrored
     // to unrelated providers merely to save a few seconds, and sequential fallback also avoids leaving
     // losing requests running after the tool has already returned.
     for (const attempt of attempts) {
+        if (signal?.aborted)
+            throw interrupted("web search");
         try {
             const results = await attempt.run();
+            if (signal?.aborted)
+                throw interrupted("web search");
             if (results.length)
                 return results;
             failures.push(`${attempt.name} no results`);
         }
         catch (e) {
+            if (signal?.aborted)
+                throw interrupted("web search");
             const reason = e?.name === "TimeoutError" || e?.name === "AbortError" ? "timeout" : (e?.message ?? String(e));
             failures.push(`${attempt.name} ${reason}`);
         }
@@ -384,7 +399,9 @@ registerTool({
         required: ["query"],
     },
     kind: "read",
-    async run(input) {
+    async run(input, ctx) {
+        if (ctx.signal?.aborted)
+            throw interrupted("web search");
         const q = String(input.query ?? "").trim();
         if (!q)
             return "(empty query)";
@@ -403,7 +420,7 @@ registerTool({
                         method: "POST",
                         headers: { "content-type": "application/json" },
                         body: JSON.stringify({ api_key: key, query: q, max_results: limit }),
-                    });
+                    }, ctx.signal);
                     if (!res.ok)
                         throw new Error(`HTTP ${res.status}`);
                     const j = (await res.json());
@@ -418,13 +435,13 @@ registerTool({
                     method: "GET",
                     redirect: "follow",
                     headers: { "user-agent": SEARCH_UA, accept: "text/html" },
-                });
+                }, ctx.signal);
                 if (!res.ok)
                     throw new Error(`HTTP ${res.status}`);
                 return parseBingSearchResults(await res.text(), limit);
             },
         });
-        const primary = await firstSuccessfulSearch(primaryAttempts, failures);
+        const primary = await firstSuccessfulSearch(primaryAttempts, failures, ctx.signal);
         if (primary)
             return wrapUntrusted(fmt(primary), `web_search: ${q}`);
         // Secondary sources are ordered fallbacks. Google is included where reachable, but is never the sole
@@ -437,7 +454,7 @@ registerTool({
                         method: "GET",
                         redirect: "follow",
                         headers: { "user-agent": SEARCH_UA, accept: "text/html" },
-                    });
+                    }, ctx.signal);
                     if (!res.ok)
                         throw new Error(`HTTP ${res.status}`);
                     return parseBaiduSearchResults(await res.text(), limit);
@@ -450,7 +467,7 @@ registerTool({
                         method: "GET",
                         redirect: "follow",
                         headers: { "user-agent": SEARCH_UA, accept: "text/html" },
-                    });
+                    }, ctx.signal);
                     if (!res.ok)
                         throw new Error(`HTTP ${res.status}`);
                     return parseGoogleSearchResults(await res.text(), limit);
@@ -464,13 +481,13 @@ registerTool({
                         redirect: "follow",
                         headers: { "user-agent": SEARCH_UA, "content-type": "application/x-www-form-urlencoded", accept: "text/html" },
                         body: `q=${encodeURIComponent(q)}`,
-                    });
+                    }, ctx.signal);
                     if (!res.ok)
                         throw new Error(`HTTP ${res.status}`);
                     return parseSearchResults(await res.text(), limit);
                 },
             },
-        ], failures);
+        ], failures, ctx.signal);
         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.`;
@@ -489,7 +506,9 @@ registerTool({
         required: ["url"],
     },
     kind: "read",
-    async run(input) {
+    async run(input, ctx) {
+        if (ctx.signal?.aborted)
+            throw interrupted("web fetch");
         let url;
         try {
             url = new URL(input.url);
@@ -502,13 +521,18 @@ registerTool({
         const cap = Math.min(Math.max(1000, input.max_chars ?? MAX), 200_000);
         const ctrl = new AbortController();
         const timer = setTimeout(() => ctrl.abort(), 30_000);
+        const signal = ctx.signal ? AbortSignal.any([ctx.signal, ctrl.signal]) : ctrl.signal;
         try {
             // Follow redirects manually so the SSRF guard runs on EVERY hop (a public URL can 30x to 169.254…).
             let current = url;
             let res;
             for (let hop = 0;; hop++) {
+                if (ctx.signal?.aborted)
+                    throw interrupted("web fetch");
                 const pinned = await resolvePublicHost(current.hostname);
-                res = await requestPinned(current, pinned, ctrl.signal);
+                if (ctx.signal?.aborted)
+                    throw interrupted("web fetch");
+                res = await requestPinned(current, pinned, signal);
                 const loc = res.status >= 300 && res.status < 400 ? res.headers.get("location") : null;
                 if (!loc || hop >= 5)
                     break;
@@ -520,10 +544,14 @@ registerTool({
                 // We never consume redirect bodies. Destroy the socket before following the next pinned hop so a
                 // server cannot accumulate idle response streams across a redirect chain.
                 res.body.destroy();
+                if (ctx.signal?.aborted)
+                    throw interrupted("web fetch");
                 current = next;
             }
             const ct = res.headers.get("content-type") ?? "";
             const raw = await readPinnedCapped(res.body, cap * 4); // byte ceiling (HTML→text shrinks; cap*4 leaves headroom)
+            if (ctx.signal?.aborted)
+                throw interrupted("web fetch");
             let text = /html/i.test(ct) ? htmlToText(raw) : raw;
             if (text.length > cap)
                 text = text.slice(0, cap) + `\n…[truncated ${text.length - cap} chars]`;
@@ -535,6 +563,8 @@ registerTool({
             return `# ${current.href} (HTTP ${res.status})\n\n${wrapUntrusted(text || "(empty body)", current.href)}`;
         }
         catch (e) {
+            if (ctx.signal?.aborted)
+                throw interrupted("web fetch");
             return `Error fetching ${url.href}: ${e?.name === "AbortError" ? "timed out (30s)" : (e?.message ?? e)}`;
         }
         finally {

package/dist/tui/App.js

@@ -23,6 +23,13 @@ import { ModelPicker } from "./model-picker.js";
 let _id = 0;
 const nid = () => ++_id;
 const stripAnsi = (s) => s.replace(/\x1b\[[0-9;]*m/g, "");
+function promptAbortReason(signal) {
+    if (signal.reason instanceof Error)
+        return signal.reason;
+    const error = new Error("interactive prompt cancelled");
+    error.name = "AbortError";
+    return error;
+}
 /** Prepare a finalized turn item for the append-only `<Static>` scrollback. A completed reasoning
  *  block collapses to a single-line "✻ thought · N lines" notice (its full text preserved in `full`
  *  for the Ctrl+T overlay) — mirroring codex writing finalized rows to scrollback ONCE. Every other
@@ -231,7 +238,7 @@ function HeaderCard(props) {
         : row("profile", _jsx(Text, { children: props.profileId ? `personal:${props.profileId}` : "personal" }));
     return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "gray", borderDimColor: true, paddingX: 1, alignSelf: "flex-start", marginBottom: 1, children: [_jsxs(Text, { children: [_jsx(Text, { color: accent(), bold: true, children: "◆ hara" }), _jsx(Text, { dimColor: true, children: `   v${version} · the agent that runs like an org` })] }), _jsx(Text, { children: " " }), identityRow, row("model", (_jsxs(Text, { children: [_jsx(Text, { children: modelLabel }), isOrg
                                 ? props.modelSource ? _jsx(Text, { dimColor: true, children: ` · from ${props.modelSource}` }) : null
-                                : props.visionModel ? _jsx(Text, { dimColor: true, children: modelLineSuffix(props.visionModel) }) : null, _jsx(Text, { children: "   " }), _jsx(Text, { color: "green", children: "/model ↹" })] }))), row("cwd", (_jsxs(Text, { children: [_jsx(Text, { children: cwdShort }), agentsMdLoaded ? _jsx(Text, { dimColor: true, children: " · AGENTS.md" }) : null] }))), sessionShort ? row("session", _jsx(Text, { children: sessionShort })) : null] }), _jsx(Text, { dimColor: true, children: "  Tip: @ attach file · ctrl+t transcript · ctrl+r reasoning · shift+tab approval · esc interrupt" }), props.updateNotice ? _jsx(Text, { color: "yellow", children: `  ⬆ ${props.updateNotice}` }) : null] }));
+                                : props.visionModel ? _jsx(Text, { dimColor: true, children: modelLineSuffix(props.visionModel) }) : null, _jsx(Text, { children: "   " }), _jsx(Text, { color: "green", children: "/model ↹" })] }))), row("cwd", (_jsxs(Text, { children: [_jsx(Text, { children: cwdShort }), agentsMdLoaded ? _jsx(Text, { dimColor: true, children: " · AGENTS.md" }) : null] }))), sessionShort ? row("session", _jsx(Text, { children: sessionShort })) : null] }), _jsx(Text, { dimColor: true, children: "  Tip: @ attach file · ctrl+t transcript · ctrl+r reasoning · shift+tab approval · esc interrupt" }), props.workspaceNotice ? _jsx(Text, { color: "yellow", children: `  ⚠ ${props.workspaceNotice}` }) : null, props.updateNotice ? _jsx(Text, { color: "yellow", children: `  ⬆ ${props.updateNotice}` }) : null] }));
 }
 // Spinner verb: while a turn is running, prefer the in_progress todo's activeForm (or its text),
 // so the bottom line reads "▶ updating tests…" instead of an abstract "working". Falls back to
@@ -381,6 +388,8 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
             clearTimeout(flushTimerRef.current);
         if (modeSelectorTimerRef.current)
             clearTimeout(modeSelectorTimerRef.current);
+        queueRef.current = [];
+        ctrlRef.current?.abort();
     }, []);
     // Subscribe to todo_write updates so the panel re-renders when the agent edits the checklist.
     useEffect(() => {
@@ -460,12 +469,20 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
             pushCurrent("user", b.line.trim() || "🖼 (image)");
         return batch;
     }, [pushCurrent, noteVisionIfNeeded]);
+    // One stop primitive for every live-turn surface. A queued type-ahead belongs to the turn being stopped;
+    // retaining it while Esc dismisses an approval/ask prompt would auto-submit it as a surprise second turn.
+    const abortCurrentTurn = useCallback(() => {
+        if (queueRef.current.length) {
+            queueRef.current = [];
+            setPool([]);
+        }
+        ctrlRef.current?.abort();
+    }, []);
     const handleSubmit = useCallback(async (line, images) => {
         const t = line.trim();
         // A free-text question (ask_user) is awaiting an answer: this submission IS the answer, not a new turn.
         if (askText) {
             const r = askText.resolve;
-            setAskText(null);
             setHistory((h) => [...h, { id: nid(), kind: "user", text: t }]);
             r(t);
             return;
@@ -502,31 +519,87 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
             usage: (input, output) => setStatus((s) => ({ ...s, input: s.input + input, output: s.output + output, ctxPct: ctxPctFor(model, input) })),
             session: (name) => setStatus((s) => ({ ...s, sessionName: name })),
         };
-        const openPrompt = (title, options) => new Promise((resolve) => {
+        const openPrompt = (title, options, signal = ctrl.signal, abortTurnOnEscape = false) => new Promise((resolve, reject) => {
+            if (signal.aborted) {
+                reject(promptAbortReason(signal));
+                return;
+            }
+            const token = Symbol("prompt");
+            let settled = false;
+            const cleanup = () => signal.removeEventListener("abort", onAbort);
+            const finish = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                setPrompt((current) => current?.token === token ? null : current);
+                resolve(value);
+            };
+            const onAbort = () => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                setPrompt((current) => current?.token === token ? null : current);
+                reject(promptAbortReason(signal));
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
             setPromptSel(0);
-            setPrompt({ title, options: options, resolve: resolve });
+            setPrompt({
+                token,
+                title,
+                options: options,
+                resolve: finish,
+                abortTurnOnEscape,
+            });
         });
-        const confirmFn = (q) => openPrompt(q, [
+        const confirmFn = (q, signal = ctrl.signal) => openPrompt(q, [
             { label: "Yes", value: true, key: "y" },
             { label: "Yes, and don't ask again this session", value: "always", key: "a" },
             { label: "No  (esc)", value: false, key: "n" },
-        ]);
+        ], signal, true);
         const selectFn = (title, options) => openPrompt(title, options);
         // Free-text question: re-enable the InputBox to read one line (resolves via handleSubmit's askText branch).
-        const askTextFn = (title) => new Promise((resolve) => setAskText({ title, resolve }));
+        const askTextFn = (title, signal = ctrl.signal) => new Promise((resolve, reject) => {
+            if (signal.aborted) {
+                reject(promptAbortReason(signal));
+                return;
+            }
+            const token = Symbol("ask-text");
+            let settled = false;
+            const cleanup = () => signal.removeEventListener("abort", onAbort);
+            const finish = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                setAskText((current) => current?.token === token ? null : current);
+                resolve(value);
+            };
+            const onAbort = () => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                setAskText((current) => current?.token === token ? null : current);
+                reject(promptAbortReason(signal));
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+            setAskText({ token, title, resolve: finish });
+        });
         // ask_user: when options are given, offer them as a select + a "type my own" escape hatch; otherwise (or
         // when the user chooses to type their own) capture a free-text line. Returns the chosen/typed answer.
         const OTHER = "\\0__ask_other__"; // escaped sentinel keeps this TypeScript file text-only
-        const askFn = async (question, options) => {
+        const askFn = async (question, options, signal = ctrl.signal) => {
             if (options && options.length) {
                 const choice = await openPrompt(question, [
                     ...options.map((o) => ({ label: o, value: o })),
                     { label: "✎ Type my own answer", value: OTHER },
-                ]);
+                ], signal, true);
                 if (choice !== OTHER)
                     return choice;
             }
-            return askTextFn(question);
+            return askTextFn(question, signal);
         };
         const setApprovalFn = (m) => setStatus((s) => ({ ...s, approval: m }));
         const pickModelFn = (o) => new Promise((resolve) => setPicker({ ...o, resolve }));
@@ -580,12 +653,13 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
             return; // while open, the overlay's own useInput owns every key (scroll / esc)
         if (picker)
             return; // the /model picker overlay owns input (↑↓ model, ←→ thinking, ⏎, esc) while open
-        // Free-text question awaiting an answer: Esc cancels (empty answer); all other keys belong to the InputBox.
+        // Free-text question awaiting an answer: Esc aborts the owning turn; all other keys belong to InputBox.
         if (askText) {
             if (key.escape) {
-                const r = askText.resolve;
-                setAskText(null);
-                r("");
+                if (working && ctrlRef.current)
+                    abortCurrentTurn();
+                else
+                    askText.resolve("");
             }
             return;
         }
@@ -597,21 +671,20 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
                 setPromptSel((s) => (s + 1) % opts.length);
             else if (key.return) {
                 prompt.resolve(opts[Math.min(promptSel, opts.length - 1)].value);
-                setPrompt(null);
             }
             else if (key.escape) {
-                prompt.resolve(opts[opts.length - 1].value); // last option = cancel/no
-                setPrompt(null);
+                if (prompt.abortTurnOnEscape && working && ctrlRef.current)
+                    abortCurrentTurn();
+                else
+                    prompt.resolve(opts[opts.length - 1].value); // select-only prompt: last option = cancel/no
             }
             else if (/^[1-9]$/.test(input) && Number(input) <= opts.length) {
                 prompt.resolve(opts[Number(input) - 1].value); // type a number to pick directly
-                setPrompt(null);
             }
             else if (input) {
                 const hit = opts.find((o) => o.key && o.key === input.toLowerCase());
                 if (hit) {
                     prompt.resolve(hit.value);
-                    setPrompt(null);
                 }
             }
             return;
@@ -619,12 +692,7 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
         if (key.ctrl && input === "r")
             return setReasoningOpen((x) => !x);
         if (key.escape && working) {
-            // Esc = stop everything: abort the turn AND drop any type-ahead (a stopped turn shouldn't fire queued msgs)
-            if (queueRef.current.length) {
-                queueRef.current = [];
-                setPool([]);
-            }
-            ctrlRef.current?.abort();
+            abortCurrentTurn();
         }
         else if (key.tab && key.shift && cycleApproval) {
             setStatus((s) => ({ ...s, approval: cycleApproval(s.approval) }));

package/dist/vision.js

@@ -1,3 +1,4 @@
+import { boundedProviderTurn } from "./providers/bounded-turn.js";
 // Built-in capability map for the major model families. First matching rule wins, so each family's
 // vision pattern is listed BEFORE its text catch-all. Anything that matches nothing → "unknown"
 // (we ask the user once and remember). Easy to extend — add a rule near the right family.
@@ -101,13 +102,12 @@ export function parseLocate(text) {
 }
 /** Send a screenshot to a (grounding-capable) vision model and get the target's center as 0..1 fractions. */
 export async function locateImage(provider, image, target, opts = {}) {
-    const r = await provider.turn({
+    const r = await boundedProviderTurn(provider, {
         system: LOCATE_SYSTEM,
         history: [{ role: "user", content: `Locate this element: ${target}`, images: [image] }],
         tools: [],
         onText: () => { },
-        signal: opts.signal,
-    });
+    }, { timeoutMs: opts.timeoutMs ?? 30_000, signal: opts.signal, label: "image element location" });
     if (r.stop === "error")
         return null;
     return parseLocate(r.text);
@@ -117,13 +117,12 @@ const PROMPT = "Describe the attached image(s) per your instructions.";
  *  `system` overrides the default prompt (e.g. SCREENSHOT_SYSTEM); `hint` focuses it on a specific goal. */
 export async function describeImages(provider, images, opts = {}) {
     const content = opts.hint ? `${PROMPT}\nFocus especially on: ${opts.hint}` : PROMPT;
-    const r = await provider.turn({
+    const r = await boundedProviderTurn(provider, {
         system: opts.system ?? DESCRIBE_SYSTEM,
         history: [{ role: "user", content, images }],
         tools: [],
         onText: () => { },
-        signal: opts.signal,
-    });
+    }, { timeoutMs: opts.timeoutMs ?? 90_000, signal: opts.signal, label: "image description" });
     if (r.stop === "error")
         throw new Error(r.errorMsg || "vision provider error");
     return r.text.trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanhara/hara",
-  "version": "0.122.2",
+  "version": "0.122.4",
   "description": "hara — a coding agent CLI that runs like an engineering org.",
   "bin": {
     "hara": "runtime-bootstrap.cjs"
@@ -43,7 +43,7 @@
     "prepare": "npm run build",
     "dev": "tsx src/cli.ts",
     "start": "node runtime-bootstrap.cjs",
-    "test": "npm run build && node --test test/*.test.mjs",
+    "test": "npm run build && node --test --test-timeout=120000 test/*.test.mjs",
     "build:binary": "npm run build && bun scripts/build-binary.ts dist/bin/hara",
     "build:binaries": "npm run build && bun scripts/build-binary.ts dist/bin/hara-darwin-arm64 bun-darwin-arm64 && bun scripts/build-binary.ts dist/bin/hara-darwin-x64 bun-darwin-x64 && bun scripts/build-binary.ts dist/bin/hara-linux-x64 bun-linux-x64 && bun scripts/build-binary.ts dist/bin/hara-linux-arm64 bun-linux-arm64"
   },

package/runtime-bootstrap.cjs

@@ -37,6 +37,25 @@ function unsupportedNodeMessage(versions) {
   ].join("\n");
 }
 
+function normalizePortableWindowsHome(value) {
+  var home = String(value || "").trim();
+  var drive = /^\/([a-zA-Z])(?:\/(.*))?$/.exec(home);
+  if (drive) return drive[1].toUpperCase() + ":\\" + String(drive[2] || "").replace(/\//g, "\\");
+  if (/^\/\/[^/]/.test(home)) return "\\\\" + home.slice(2).replace(/\//g, "\\");
+  if (/^[a-zA-Z]:[\\/]/.test(home)) return home.charAt(0).toUpperCase() + home.slice(1).replace(/\//g, "\\");
+  return home;
+}
+
+function applyPortableHomeEnv(env, runtimePlatform) {
+  env = env || process.env;
+  runtimePlatform = runtimePlatform || process.platform;
+  if (runtimePlatform !== "win32") return false;
+  var home = normalizePortableWindowsHome(env.HOME || "");
+  if (!home || env.USERPROFILE === home) return false;
+  env.USERPROFILE = home;
+  return true;
+}
+
 function failStart(error) {
   var message = error && error.message ? error.message : String(error);
   process.stderr.write("hara: failed to start: " + message + "\n");
@@ -52,6 +71,7 @@ function main() {
   }
 
   try {
+    applyPortableHomeEnv(process.env, process.platform);
     // Keeping import() inside a string prevents legacy parsers from seeing unsupported ESM syntax. This
     // branch is reached only on the supported Node floor (or Bun when used as a script runtime).
     var load = Function("specifier", "return import(specifier)");
@@ -67,6 +87,8 @@ module.exports = {
   MIN_NODE_VERSION: MIN_NODE_VERSION,
   supportedNodeVersion: supportedNodeVersion,
   unsupportedNodeMessage: unsupportedNodeMessage,
+  applyPortableHomeEnv: applyPortableHomeEnv,
+  normalizePortableWindowsHome: normalizePortableWindowsHome,
 };
 
 if (require.main === module) main();