@nanhara/hara 0.67.0 → 0.89.0

package/dist/agent/loop.js

@@ -6,6 +6,9 @@ import { makeRenderer } from "../md.js";
 import { skillsDigest } from "../skills/skills.js";
 import { runHooks } from "../hooks.js";
 import { mapLimit, maxParallel } from "../concurrency.js";
+import { decideCommand, loadPermissionRules } from "../security/permissions.js";
+import { subdirHint } from "../context/subdir-hints.js";
+import { classifyError, failoverAction, errorHint } from "./failover.js";
 /** Whether a tool call needs user confirmation under the given approval mode. */
 export function needsConfirm(kind, mode) {
     if (kind === "read")
@@ -30,10 +33,24 @@ When a task matches one of the Skills listed below, call the \`skill\` tool to l
 before acting; save a reusable how-to as a new skill with skill_create. If you discover a durable project
 convention, you may propose an edit to AGENTS.md via edit_file (the user reviews the diff). 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() {
+    const plat = process.env.HARA_GATEWAY;
+    if (!plat)
+        return "";
+    return (`\n\n# You are in a chat gateway (${plat})\n` +
+        `You are talking to the user through the ${plat} chat — not a terminal, and NOT the desktop ${plat} app. ` +
+        `To send a file or image to them, call the \`send_file\` tool with an absolute path; that is the ONLY channel ` +
+        `that reaches this chat. Do NOT use the \`computer\` tool, AppleScript, or any desktop/${plat}-client automation ` +
+        `to deliver files — that drives a different window and silently fails to reach the user. Never tell the user a ` +
+        `file was sent unless \`send_file\` returned success. Keep replies short and chat-friendly.`);
+}
 function composeSystem(cwd, projectContext, override, memory) {
     const head = override ? `${override}\n\nWorking directory: ${cwd}` : HARA_SYSTEM(cwd);
     const skills = skillsDigest(cwd);
     return (head +
+        gatewayNote() +
         (projectContext ? `\n\n# Project context (AGENTS.md)\n${projectContext}` : "") +
         (memory ? `\n\n# Memory (durable — facts/decisions/prefs you've saved; use memory_search/get for more)\n${memory}` : "") +
         (skills ? `\n\n# Skills (capabilities you can load — call the \`skill\` tool with the id for full instructions before using one)\n${skills}` : ""));
@@ -41,6 +58,16 @@ function composeSystem(cwd, projectContext, override, memory) {
 /** Provider-agnostic agentic loop. Mutates `history` in place. */
 export async function runAgent(history, opts) {
     const { provider, ctx } = opts;
+    const permRules = loadPermissionRules(ctx.cwd); // command-level allow/ask/deny policy for the bash tool
+    let activeProvider = provider; // may switch to a fallback model on a recoverable error (app-failover)
+    let triedFallback = false;
+    // 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.
+    const guard = !!process.env.HARA_GATEWAY;
+    const toolCounts = new Map();
+    let blindShots = 0;
+    let nudged = false;
     for (;;) {
         // Type-ahead steering: fold in anything the user submitted while the previous step ran, so it
         // reaches the model on this next call (drained after the last tool round; empty on the 1st pass).
@@ -68,7 +95,7 @@ export async function runAgent(history, opts) {
             let fi = 0;
             spin = setInterval(() => out(`\r${c.dim(`${frames[fi++ % frames.length]} working ${Math.floor((Date.now() - t0) / 1000)}s`)}`), 100);
         }
-        const r = await provider.turn({
+        const r = await activeProvider.turn({
             system: composeSystem(ctx.cwd, opts.projectContext, opts.systemOverride, opts.memory),
             history,
             tools: specs,
@@ -115,12 +142,26 @@ export async function runAgent(history, opts) {
         }
         history.push({ role: "assistant", text: r.text, toolUses: r.toolUses });
         if (r.stop === "error") {
-            const msg = r.errorMsg === "interrupted" ? "(interrupted)" : `[${provider.id} error] ${r.errorMsg ?? "unknown"}`;
+            const kind = classifyError(r.errorMsg ?? "");
+            if (failoverAction(kind, { hasFallback: !!opts.fallback?.provider, triedFallback }) === "fallback") {
+                triedFallback = true;
+                history.pop(); // drop the errored (partial/empty) assistant turn before retrying
+                activeProvider = opts.fallback.provider;
+                if (!opts.quiet) {
+                    const note = `✻ ${kind} → falling back to ${activeProvider.model}…`;
+                    if (sink)
+                        sink.notice(note);
+                    else
+                        out(c.dim(`${note}\n`));
+                }
+                continue; // retry once on the fallback model (guarded by triedFallback)
+            }
+            const msg = kind === "interrupted" ? "(interrupted)" : `[${activeProvider.id} error] ${r.errorMsg ?? "unknown"}${errorHint(kind)}`;
             if (!opts.quiet) {
                 if (sink)
                     sink.notice(msg);
                 else
-                    out(r.errorMsg === "interrupted" ? c.dim(`\n${msg}\n`) : c.red(`${msg}\n`));
+                    out(kind === "interrupted" ? c.dim(`\n${msg}\n`) : c.red(`${msg}\n`));
             }
             return;
         }
@@ -139,7 +180,14 @@ export async function runAgent(history, opts) {
                 .trim();
             // Screen control is gated on EVERY action — a prior "don't ask again" must never satisfy it.
             const alwaysGate = tool.kind === "computer";
-            if (needsConfirm(tool.kind, opts.approval) && (alwaysGate || !opts.autoApprove?.has(tu.name))) {
+            // Command-level policy for shell commands: a deny rule blocks even in full-auto; an allow rule (or a
+            // read-only command) auto-runs even in suggest mode. Composes with, doesn't replace, the approval mode.
+            const cmdDecision = tool.kind === "exec" && typeof input.command === "string" ? decideCommand(input.command, permRules) : null;
+            if (cmdDecision === "deny") {
+                plans.push({ tu, tool, denied: "Denied by a permission rule (~/.hara/permissions.json). Loosen the rule or run it yourself." });
+                continue;
+            }
+            if (cmdDecision !== "allow" && needsConfirm(tool.kind, opts.approval) && (alwaysGate || !opts.autoApprove?.has(tu.name))) {
                 const reply = await opts.confirm(`${c.yellow("⚠")}  ${c.bold(tu.name)} ${c.dim(preview)} — run?`);
                 if (reply === false) {
                     plans.push({ tu, tool, denied: "User denied this action." });
@@ -172,7 +220,8 @@ export async function runAgent(history, opts) {
                     return;
                 }
                 const res = await p.tool.run(p.tu.input, ctx);
-                results[idx] = { id: p.tu.id, name: p.tu.name, content: res };
+                // append any not-yet-seen subdirectory AGENTS.md/CLAUDE.md this call touched (monorepo-local conventions)
+                results[idx] = { id: p.tu.id, name: p.tu.name, content: res + subdirHint(p.tu.input, ctx.cwd) };
                 runHooks("PostToolUse", p.tu.name, { input: p.tu.input, result: res }, ctx.cwd); // observe-only
             }
             catch (e) {
@@ -202,5 +251,26 @@ export async function runAgent(history, opts) {
         }
         await flush();
         history.push({ role: "tool", results });
+        if (guard && !nudged) {
+            for (const p of plans)
+                if (p.tool && p.tool.kind !== "read")
+                    toolCounts.set(p.tu.name, (toolCounts.get(p.tu.name) ?? 0) + 1);
+            for (const res of results)
+                if (typeof res.content === "string" && /Configure a vision model/.test(res.content))
+                    blindShots++;
+            const maxRepeat = Math.max(0, ...toolCounts.values());
+            const blind = blindShots >= 2;
+            if (blind || maxRepeat >= 5) {
+                nudged = true;
+                history.push({
+                    role: "user",
+                    content: blind
+                        ? "⚠ Self-check: your screenshots come back unreadable (no vision model) — you are acting blind, so this approach cannot work. Stop using the computer tool. Reach the user through a non-visual path instead (a CLI, an API, or the send_file tool). State the new plan in one line, then do it."
+                        : "⚠ Self-check: you've repeated the same action several times without resolving the task. Stop and reconsider — is there a more direct tool or channel (e.g. send_file to deliver a file)? Don't keep retrying the same thing. State your revised plan in one line, then act.",
+                });
+                if (!opts.quiet && !ctx.ui)
+                    out(c.dim("  ⟲ stuck-guard: nudging a rethink\n"));
+            }
+        }
     }
 }

package/dist/agent/rewind.js

@@ -0,0 +1,20 @@
+/** Recent user turns, newest first (n=1 = most recent), each with a short preview — for `/rewind` to list. */
+export function userTurnPreviews(history, max = 10) {
+    const idxs = [];
+    history.forEach((m, i) => m.role === "user" && idxs.push(i));
+    const out = [];
+    for (let k = idxs.length - 1, n = 1; k >= 0 && n <= max; k--, n++) {
+        const m = history[idxs[k]];
+        out.push({ n, preview: (m.role === "user" ? m.content : "").replace(/\s+/g, " ").slice(0, 70) });
+    }
+    return out;
+}
+/** Truncate history to just BEFORE the n-th-most-recent user turn (n=1 drops the last exchange), forking the
+ *  conversation from that point. Returns the new history array, or null if n is out of range. */
+export function rewindTo(history, n) {
+    const idxs = [];
+    history.forEach((m, i) => m.role === "user" && idxs.push(i));
+    if (!Number.isInteger(n) || n < 1 || n > idxs.length)
+        return null;
+    return history.slice(0, idxs[idxs.length - n]); // cut at the n-th-from-last user message
+}

package/dist/agent/route.js

@@ -0,0 +1,47 @@
+// Words that signal real coding/action work → keep the primary (strong) model. Broad on purpose: routing
+// should fire only on clearly trivial, non-actionable turns (questions, lookups, chit-chat).
+const COMPLEX = /\b(debug|refactor|implement|fix(es|ed|ing)?|build|test|deploy|migrat\w*|optimi[sz]e|architect|design|review|trace|profile|benchmark|docker|kubernetes|compile|exception|error|bug|patch|diff|commit|merge|rebase|rename|add|remove|delete|update|change|write|create|edit|run|install|generate|convert|parse|format|lint|setup|configure|wire|hook|render|fetch|query|schema|class|function|async|await|import|export)\b/i;
+/** The text of the most recent genuine user message (tool results are role:"tool", so this is stable
+ *  across a turn's tool rounds). */
+export function lastUserText(history) {
+    for (let i = history.length - 1; i >= 0; i--) {
+        const m = history[i];
+        if (m.role === "user")
+            return typeof m.content === "string" ? m.content : "";
+    }
+    return "";
+}
+/** True if a turn is trivial enough to hand to the cheap/general model: short, single-line, no code,
+ *  no URL, and no coding/action keyword. Defaults to FALSE (stay on the strong model) when unsure. */
+export function isTrivialTurn(text) {
+    const t = (text ?? "").trim();
+    if (!t)
+        return false;
+    if (t.length > 160)
+        return false; // long → probably substantive
+    if (t.split(/\s+/).length > 28)
+        return false;
+    if (t.includes("\n"))
+        return false; // multi-line / paste
+    if (t.includes("`"))
+        return false; // inline code / fences
+    if (/https?:\/\//i.test(t))
+        return false; // a URL to act on
+    if (/[{}();=]|=>|::|\/|\\/.test(t))
+        return false; // code-ish / a path
+    if (COMPLEX.test(t))
+        return false; // an action/coding verb
+    return true;
+}
+/** Wrap a primary + alternate provider so each turn routes to the alternate when the latest user message is
+ *  trivial, else the primary. Decided per turn from history (stable across tool rounds). */
+export function routingProvider(primary, alt) {
+    return {
+        id: primary.id,
+        model: primary.model, // reported model = primary; routing is transparent
+        turn(args) {
+            const useAlt = isTrivialTurn(lastUserText(args.history));
+            return (useAlt ? alt : primary).turn(args);
+        },
+    };
+}

package/dist/checkpoints.js

@@ -0,0 +1,91 @@
+// File-state checkpoints via a SHADOW git repo — durable "undo the agent's file changes" beyond the
+// edit-only in-memory undo (which misses bash-made changes). The shadow repo lives OUTSIDE the project
+// (~/.hara/checkpoints/<hash>/git) with GIT_DIR there + GIT_WORK_TREE = the project root, so it captures the
+// WHOLE tree, NEVER touches the user's real .git/index, and the model never sees it. Restore is
+// snapshot-then-checkout: SAFE — it reverts changed/deleted files to the checkpoint and never deletes files
+// created since (so a stray restore can't nuke new work; it's also itself undoable via the auto-snapshot).
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+import { findProjectRoot } from "./context/agents-md.js";
+// Heavy/derived dirs the shadow repo must never snapshot (in addition to the project's own .gitignore).
+const EXCLUDES = ["node_modules/", ".git/", "dist/", "build/", "out/", ".next/", "target/", ".venv/", "venv/", "__pycache__/", ".hara/", ".cache/", ".turbo/", "coverage/", "*.log", ".DS_Store"];
+function shadowGitDir(root) {
+    return join(homedir(), ".hara", "checkpoints", createHash("sha256").update(root).digest("hex").slice(0, 16), "git");
+}
+function git(root, gitDir, args) {
+    return execFileSync("git", args, {
+        cwd: root,
+        env: { ...process.env, GIT_DIR: gitDir, GIT_WORK_TREE: root, GIT_AUTHOR_NAME: "hara", GIT_AUTHOR_EMAIL: "hara@local", GIT_COMMITTER_NAME: "hara", GIT_COMMITTER_EMAIL: "hara@local" },
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        maxBuffer: 64 * 1024 * 1024,
+    }).toString();
+}
+function ensureRepo(root, gitDir) {
+    try {
+        if (!existsSync(join(gitDir, "HEAD"))) {
+            mkdirSync(gitDir, { recursive: true });
+            git(root, gitDir, ["init", "-q"]);
+            mkdirSync(join(gitDir, "info"), { recursive: true });
+            writeFileSync(join(gitDir, "info", "exclude"), EXCLUDES.join("\n") + "\n");
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Snapshot the current working tree into the shadow repo. Returns the short sha, or null on failure. */
+export function checkpoint(cwd, label) {
+    const root = findProjectRoot(cwd);
+    const gitDir = shadowGitDir(root);
+    if (!ensureRepo(root, gitDir))
+        return null;
+    try {
+        git(root, gitDir, ["add", "-A"]);
+        git(root, gitDir, ["commit", "-q", "--allow-empty", "--no-gpg-sign", "-m", (label || "checkpoint").slice(0, 120)]);
+        return git(root, gitDir, ["rev-parse", "--short", "HEAD"]).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/** Recent checkpoints, newest first. */
+export function listCheckpoints(cwd, n = 15) {
+    const gitDir = shadowGitDir(findProjectRoot(cwd));
+    if (!existsSync(join(gitDir, "HEAD")))
+        return [];
+    try {
+        const out = git(findProjectRoot(cwd), gitDir, ["log", `-n${n}`, "--format=%h\x1f%ct\x1f%s"]).trim();
+        if (!out)
+            return [];
+        return out.split("\n").map((l) => {
+            const [sha, ct, ...rest] = l.split("\x1f");
+            return { sha, when: Number(ct) * 1000, label: rest.join("\x1f") };
+        });
+    }
+    catch {
+        return [];
+    }
+}
+/** Restore the working tree's changed/deleted files to a checkpoint (snapshots current first, so it's
+ *  undoable). Files created AFTER the checkpoint are left in place — nothing is deleted. Returns the count of
+ *  files restored, or null on failure. */
+export function restoreCheckpoint(cwd, ref) {
+    const root = findProjectRoot(cwd);
+    const gitDir = shadowGitDir(root);
+    if (!existsSync(join(gitDir, "HEAD")))
+        return null;
+    try {
+        checkpoint(cwd, `before restore to ${ref}`); // make the restore itself undoable
+        const changed = git(root, gitDir, ["diff", "--name-only", ref, "--"]).trim(); // files differing now vs ref
+        git(root, gitDir, ["checkout", ref, "--", "."]);
+        return changed ? changed.split("\n").length : 0;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/config.js

@@ -12,7 +12,7 @@ const PROVIDER_DEFAULTS = {
     openai: { model: "gpt-4o-mini", envKey: "OPENAI_API_KEY" },
     "hara-gateway": { model: "", envKey: "HARA_GATEWAY_TOKEN" }, // B-end: enrolled device → token in ~/.hara/org.json, routed by the gateway
 };
-export const CONFIG_KEYS = ["provider", "apiKey", "model", "baseURL", "approval", "sandbox", "theme", "evolve", "assetCapture", "computerUse", "computerApps", "visionModel", "visionBaseURL", "visionApiKey", "embedProvider", "embedModel", "embedBaseURL", "embedApiKey", "notify", "vimMode"];
+export const CONFIG_KEYS = ["provider", "apiKey", "model", "baseURL", "approval", "sandbox", "theme", "evolve", "assetCapture", "computerUse", "computerApps", "visionModel", "visionBaseURL", "visionApiKey", "embedProvider", "embedModel", "embedBaseURL", "embedApiKey", "routeModel", "routeBaseURL", "routeApiKey", "notify", "vimMode", "autoCompact", "fileCheckpoints", "fallbackModel", "fallbackBaseURL", "fallbackApiKey"];
 export const APPROVAL_MODES = ["suggest", "auto-edit", "full-auto"];
 export const SANDBOX_MODES = ["off", "workspace-write", "read-only"];
 const PROJECT_ROOT_MARKERS = [".git", "package.json", "Cargo.toml", "go.mod", "pyproject.toml", ".hg"];
@@ -112,6 +112,9 @@ export function loadConfig(opts = {}) {
     const embedModel = process.env.HARA_EMBED_MODEL ?? merged.embedModel;
     const embedBaseURL = process.env.HARA_EMBED_BASE_URL ?? merged.embedBaseURL;
     const embedApiKey = process.env.HARA_EMBED_API_KEY ?? merged.embedApiKey;
+    const routeModel = process.env.HARA_ROUTE_MODEL ?? merged.routeModel;
+    const routeBaseURL = process.env.HARA_ROUTE_BASE_URL ?? merged.routeBaseURL;
+    const routeApiKey = process.env.HARA_ROUTE_API_KEY ?? merged.routeApiKey;
     const mcpServers = {
         ...(globalBase.mcpServers ?? {}),
         ...(project.mcpServers ?? {}),
@@ -120,7 +123,12 @@ export function loadConfig(opts = {}) {
     const hooks = (merged.hooks && typeof merged.hooks === "object" ? merged.hooks : {});
     const notify = (process.env.HARA_NOTIFY ?? merged.notify ?? "off");
     const vimMode = process.env.HARA_VIM === "1" || merged.vimMode === true || merged.vimMode === "true";
-    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, hooks, notify, vimMode, mcpServers, cwd: process.cwd() };
+    const autoCompact = !(process.env.HARA_AUTO_COMPACT === "0" || merged.autoCompact === false || merged.autoCompact === "false"); // default ON
+    const fileCheckpoints = !(process.env.HARA_CHECKPOINTS === "0" || merged.fileCheckpoints === false || merged.fileCheckpoints === "false"); // default ON
+    const fallbackModel = process.env.HARA_FALLBACK_MODEL ?? merged.fallbackModel;
+    const fallbackBaseURL = process.env.HARA_FALLBACK_BASE_URL ?? merged.fallbackBaseURL;
+    const fallbackApiKey = process.env.HARA_FALLBACK_API_KEY ?? merged.fallbackApiKey;
+    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, routeModel, routeBaseURL, routeApiKey, hooks, notify, vimMode, autoCompact, fileCheckpoints, fallbackModel, fallbackBaseURL, fallbackApiKey, mcpServers, cwd: process.cwd() };
 }
 export function providerEnvKey(provider) {
     return (PROVIDER_DEFAULTS[provider] ?? PROVIDER_DEFAULTS.anthropic).envKey;

package/dist/context/mentions.js

@@ -8,45 +8,49 @@ import { mediaTypeFor } from "../images.js";
 const MAX_FILE = 50_000;
 // @ at start-of-string or after whitespace; capture a path with no spaces/@ (avoids emails like a@b.com)
 const MENTION_RE = /(?:^|\s)@([^\s@]+)/g;
-/** Append the contents of any @mentioned files to the input as fenced blocks. */
+/** Expand `@path` references **in place** — the file/dir content lands where it's referenced, not
+ *  dumped at the bottom (so "compare @a.ts with @b.ts" reads in context). A repeated mention keeps
+ *  the bare `@path` the second time (no double-inlining), and a non-readable ref is left untouched. */
 export function expandMentions(input, cwd) {
     const seen = new Set();
-    const blocks = [];
-    let m;
     MENTION_RE.lastIndex = 0;
-    while ((m = MENTION_RE.exec(input)) !== null) {
-        const ref = m[1];
+    return input.replace(MENTION_RE, (whole, ref) => {
+        const prefix = whole.slice(0, whole.length - ref.length - 1); // BOL "" or the captured leading whitespace
         if (seen.has(ref))
-            continue;
+            return whole; // already inlined above → leave this occurrence as the bare @ref
+        const block = expandRef(ref, cwd);
+        if (block === null)
+            return whole; // not a readable file/dir → leave the token as typed
         seen.add(ref);
-        const abs = isAbsolute(ref) ? ref : resolve(cwd, ref);
-        try {
-            if (existsSync(abs)) {
-                const st = statSync(abs);
-                if (st.isFile()) {
-                    if (mediaTypeFor(abs)) {
-                        // don't inline binary image bytes as text — paste it with Ctrl+V (or drag the file in) to attach visually
-                        blocks.push(`Referenced \`${ref}\` is an image — paste it with Ctrl+V to attach it visually.`);
-                    }
-                    else {
-                        let txt = readFileSync(abs, "utf8");
-                        if (txt.length > MAX_FILE)
-                            txt = txt.slice(0, MAX_FILE) + "\n…[truncated]";
-                        blocks.push(`Referenced file \`${ref}\`:\n\`\`\`\n${txt}\n\`\`\``);
-                    }
-                }
-                else if (st.isDirectory()) {
-                    // `@dir` loads a listing of the directory's files (the agent can then read specific ones)
-                    const files = walkFiles(abs, 300);
-                    blocks.push(`Referenced directory \`${ref}\` (${files.length} files):\n\`\`\`\n${files.join("\n") || "(empty)"}\n\`\`\``);
-                }
-            }
+        return `${prefix}${block}`;
+    });
+}
+/** Render one mention as an inline block, or null if it isn't a readable file/dir. */
+function expandRef(ref, cwd) {
+    const abs = isAbsolute(ref) ? ref : resolve(cwd, ref);
+    try {
+        if (!existsSync(abs))
+            return null;
+        const st = statSync(abs);
+        if (st.isFile()) {
+            // don't inline binary image bytes as text — paste with Ctrl+V (or drag the file in) to attach visually
+            if (mediaTypeFor(abs))
+                return `Referenced \`${ref}\` is an image — paste it with Ctrl+V to attach it visually.`;
+            let txt = readFileSync(abs, "utf8");
+            if (txt.length > MAX_FILE)
+                txt = txt.slice(0, MAX_FILE) + "\n…[truncated]";
+            return `\nReferenced file \`${ref}\`:\n\`\`\`\n${txt}\n\`\`\`\n`;
         }
-        catch {
-            /* ignore unreadable mention */
+        if (st.isDirectory()) {
+            // `@dir` loads a listing of the directory's files (the agent can then read specific ones)
+            const files = walkFiles(abs, 300);
+            return `\nReferenced directory \`${ref}\` (${files.length} files):\n\`\`\`\n${files.join("\n") || "(empty)"}\n\`\`\`\n`;
         }
     }
-    return blocks.length ? `${input}\n\n${blocks.join("\n\n")}` : input;
+    catch {
+        /* ignore unreadable mention */
+    }
+    return null;
 }
 // Short-lived per-cwd cache so Tab completion stays snappy without re-scanning every press.
 const cache = new Map();

package/dist/context/subdir-hints.js

@@ -0,0 +1,76 @@
+// Lazy per-directory project docs — when a tool touches a directory we haven't seen yet, surface that dir's
+// AGENTS.md / CLAUDE.md (the local conventions for that package) by appending it to the tool result, so a
+// monorepo's per-package rules reach the model exactly when work moves into that package. Startup already
+// loads root→cwd (agents-md.ts); this covers the subdirs the agent navigates INTO. Each dir loaded once.
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { join, dirname, resolve, relative, isAbsolute } from "node:path";
+import { findProjectRoot } from "./agents-md.js";
+const FILENAMES = ["AGENTS.override.md", "AGENTS.md", "CLAUDE.md"];
+const MAX = 8 * 1024;
+const loaded = new Set(); // dirs whose local doc we've already injected (per process / session)
+function isDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Candidate file/dir paths referenced by a tool call (its `path`, or path-like tokens in a shell command). */
+function pathsFrom(input) {
+    const out = [];
+    if (typeof input?.path === "string")
+        out.push(input.path);
+    if (typeof input?.command === "string")
+        for (const m of input.command.matchAll(/[\w.@~+-]*\/[\w./@+-]+/g))
+            out.push(m[0]);
+    return out;
+}
+/** Project docs for any NEW directory (strictly under cwd) this tool call touches — appendable to the tool
+ *  result. Returns "" when nothing new. Each directory is checked/loaded at most once per session. */
+export function subdirHint(input, cwd) {
+    const base = resolve(cwd);
+    const root = findProjectRoot(cwd);
+    const parts = [];
+    for (const raw of pathsFrom(input)) {
+        const absPath = isAbsolute(raw) ? resolve(raw) : resolve(cwd, raw);
+        const startDir = isDir(absPath) ? absPath : dirname(absPath);
+        const rel = relative(base, startDir);
+        if (!rel || rel.startsWith("..") || isAbsolute(rel))
+            continue; // not strictly under cwd → startup already covered it
+        // collect unseen dirs from startDir up to (but excluding) cwd
+        const chain = [];
+        let d = startDir;
+        while (d.startsWith(base) && d !== base) {
+            if (!loaded.has(d))
+                chain.unshift(d);
+            if (d === root)
+                break;
+            const parent = dirname(d);
+            if (parent === d)
+                break;
+            d = parent;
+        }
+        for (const cd of chain) {
+            loaded.add(cd); // mark checked even if no doc here, so we don't re-scan it
+            for (const name of FILENAMES) {
+                const fp = join(cd, name);
+                if (!existsSync(fp))
+                    continue;
+                try {
+                    let txt = readFileSync(fp, "utf8").trim();
+                    if (!txt)
+                        break;
+                    if (Buffer.byteLength(txt, "utf8") > MAX)
+                        txt = txt.slice(0, MAX) + "\n…[truncated]";
+                    parts.push(`<!-- ${name} @ ${cd} — local conventions for this directory -->\n${txt}`);
+                }
+                catch {
+                    /* ignore unreadable */
+                }
+                break; // first filename match per dir
+            }
+        }
+    }
+    return parts.length ? "\n\n" + parts.join("\n\n") : "";
+}

package/dist/cron/runner.js

@@ -10,11 +10,14 @@ import { isDue } from "./schedule.js";
 export function dueJobs(jobs, nowMs) {
     return jobs.filter((j) => j.enabled && isDue(j, nowMs));
 }
-/** How to invoke hara again — handles both `node dist/index.js` (argv[1] is a script) and the compiled
- *  single-binary (argv[1] is a user arg, so re-invoke the binary directly). Used by the tick + by install. */
+/** How to invoke hara again. Under node, argv[1] is the entry to hand back to node — either `dist/index.js`
+ *  OR the installed `hara` bin symlink (node runs both); as a compiled single-binary, execPath itself IS hara
+ *  (argv[1] is a user arg), so re-invoke the binary directly. Used by the cron tick + the chat gateway.
+ *  Discriminator is whether execPath is node — NOT argv[1]'s extension (the bin symlink has no `.js`). */
 export function selfArgv() {
-    const a1 = process.argv[1];
-    return a1 && /\.[cm]?js$|\.ts$/.test(a1) ? [process.execPath, a1] : [process.execPath];
+    const exec = process.execPath;
+    const underNode = /(^|[\\/])node(\.exe)?$/i.test(exec);
+    return underNode && process.argv[1] ? [exec, process.argv[1]] : [exec];
 }
 const lockPath = () => join(cronDir(), ".tick.lock");
 // Generous: a live-PID owner is respected this long (so a genuinely long job isn't double-fired); past it

package/dist/exec/jobs.js

@@ -0,0 +1,82 @@
+// Background shell jobs — run long-lived commands (dev servers, `tsc --watch`, long builds) WITHOUT blocking
+// the agent, then tail/kill them. Pipe-based (no PTY yet; a true interactive PTY can come later behind an
+// optional dep). Same sandbox write-confinement as runShell (shared `shellCommand`). Jobs are the agent's
+// own child processes and are terminated when hara exits.
+import { spawn } from "node:child_process";
+import { shellCommand } from "../sandbox.js";
+const MAX_BUF = 64 * 1024; // retain only the tail of each job's combined output
+const jobs = new Map();
+let seq = 0;
+let hooked = false;
+function ensureExitCleanup() {
+    if (hooked)
+        return;
+    hooked = true;
+    process.on("exit", killAllJobs); // sync; runs on normal quit so background jobs don't orphan
+}
+/** Start a background shell job; returns its id immediately. Output is captured to a capped tail buffer. */
+export function startJob(command, cwd, mode) {
+    ensureExitCleanup();
+    const { cmd, args } = shellCommand(command, cwd, mode);
+    const child = spawn(cmd, args, { cwd });
+    const job = { id: "j" + ++seq, command, child, status: "running", code: null, startedAt: Date.now(), buf: "" };
+    const onData = (d) => {
+        job.buf = (job.buf + d.toString()).slice(-MAX_BUF);
+    };
+    child.stdout?.on("data", onData);
+    child.stderr?.on("data", onData);
+    child.on("close", (code) => {
+        if (job.status === "running") {
+            job.status = "exited";
+            job.code = code;
+        }
+    });
+    child.on("error", (e) => {
+        if (job.status === "running") {
+            job.status = "exited";
+            job.code = -1;
+            job.buf = (job.buf + `\n[spawn error] ${e.message}`).slice(-MAX_BUF);
+        }
+    });
+    jobs.set(job.id, job);
+    return job.id;
+}
+export function listJobs() {
+    const now = Date.now();
+    return [...jobs.values()].map((j) => ({ id: j.id, command: j.command, status: j.status, code: j.code, ageMs: now - j.startedAt }));
+}
+/** Last `lines` lines of a job's output buffer, or null if there is no such job. */
+export function tailJob(id, lines = 40) {
+    const j = jobs.get(id);
+    if (!j)
+        return null;
+    return j.buf.split("\n").slice(-lines).join("\n");
+}
+/** Terminate a running job (SIGTERM). Returns true only if it was running. */
+export function killJob(id) {
+    const j = jobs.get(id);
+    if (!j || j.status !== "running")
+        return false;
+    try {
+        j.child.kill("SIGTERM");
+    }
+    catch {
+        /* already gone */
+    }
+    j.status = "killed";
+    return true;
+}
+/** Terminate every running job — registered on process exit so dev servers don't outlive hara. */
+export function killAllJobs() {
+    for (const j of jobs.values()) {
+        if (j.status === "running") {
+            try {
+                j.child.kill("SIGTERM");
+            }
+            catch {
+                /* ignore */
+            }
+            j.status = "killed";
+        }
+    }
+}