@nanhara/hara 0.33.0 → 0.53.0

package/dist/index.js

@@ -4,17 +4,18 @@ import { createInterface } from "node:readline/promises";
 import { emitKeypressEvents } from "node:readline";
 import { runTui } from "./tui/run.js";
 import { readClipboardImage } from "./images.js";
-import { describeImages, classifyVision } from "./vision.js";
+import { describeImages, locateImage, classifyVision, SCREENSHOT_SYSTEM } from "./vision.js";
 import { setTheme } from "./tui/theme.js";
 import { memoryDigest, memoryDir } from "./memory/store.js";
 import { nextMode as cycleMode } from "./tui/InputBox.js";
 import { stdin, stdout } from "node:process";
-import { readFileSync, existsSync } from "node:fs";
-import { homedir } from "node:os";
+import { readFileSync, existsSync, writeFileSync, rmSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { loadConfig, configPath, readRawConfig, writeConfigValue, setModelVisionOverride, providerEnvKey, CONFIG_KEYS, APPROVAL_MODES, SANDBOX_MODES, } from "./config.js";
 import { runAgent } from "./agent/loop.js";
+import { notifyDone } from "./notify.js";
 import { getTools } from "./tools/registry.js";
 import { createAnthropicProvider } from "./providers/anthropic.js";
 import { createOpenAIProvider } from "./providers/openai.js";
@@ -24,14 +25,14 @@ import { getEmbedder } from "./search/embed.js";
 import { collectRepoChunks, collectDirChunks, buildIndex, indexPath, indexExists } from "./search/semindex.js";
 import { searchHybrid } from "./search/hybrid.js";
 import { expandMentions, fileCandidates } from "./context/mentions.js";
-import { newSessionId, shortId, resolveSessionId, saveSession, loadSession, listSessions, latestForCwd, titleFrom, } from "./session/store.js";
+import { newSessionId, shortId, resolveSessionId, saveSession, loadSession, listSessions, latestForCwd, titleFrom, slugify, } from "./session/store.js";
 import { loadRoles, scaffoldRoles } from "./org/roles.js";
 import { loadSkillIndex, loadSkillBody, scaffoldSkills, globalSkillsDir } from "./skills/skills.js";
-import { installPlugin, uninstallPlugin, listInstalled, enabledPlugins, setPluginEnabled, pluginMcpServers } from "./plugins/plugins.js";
+import { installPlugin, uninstallPlugin, listInstalled, enabledPlugins, setPluginEnabled, pluginMcpServers, pluginHooks } from "./plugins/plugins.js";
 import { routeByKeywords, buildDispatchPrompt, parseRoleId } from "./org/router.js";
-import { decompose, topoOrder, savePlan, atomPrompt, verify, runCheck } from "./org/planner.js";
+import { decompose, topoOrder, topoWaves, savePlan, loadPlan, atomPrompt, verify, runCheck } from "./org/planner.js";
 import { connectMcpServers, closeMcp } from "./mcp/client.js";
-import { sandboxSupported } from "./sandbox.js";
+import { sandboxSupported, runShell } from "./sandbox.js";
 import { undoLast } from "./undo.js";
 import { scaffoldAssets, assetsDir, assetSearchRoots } from "./recall.js";
 import { c, out, statusLine } from "./ui.js";
@@ -46,6 +47,7 @@ import "./tools/agent.js"; // register agent (subagent spawn)
 import "./tools/memory.js"; // register memory_search/get/write/forget/skill_create
 import "./tools/skill.js"; // register the skill loader tool
 import "./tools/codebase.js"; // register codebase_search (repo as a knowledge base)
+import "./tools/todo.js"; // register todo_write (inline task checklist)
 import { computerBackends } from "./tools/computer.js"; // register the computer tool + expose the backend probe
 const here = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
@@ -133,7 +135,96 @@ function lastAssistantText(history) {
     }
     return "";
 }
-/** Decompose a task into atoms, sequence them (DAG), and execute each with a verify gate. */
+/** Run one atom (routed to its role if any), then gate it (its `check` command, else an LLM verify). */
+async function executeAtom(atom, plan, done, roles, o) {
+    atom.status = "running";
+    savePlan(o.cwd, plan);
+    const role = atom.role ? roles.find((r) => r.id === atom.role) : undefined;
+    const roleProvider = role?.model && role.model !== o.cfg.model ? ((await buildProvider({ ...o.cfg, model: role.model })) ?? o.baseProvider) : o.baseProvider;
+    const toolFilter = role?.allowTools
+        ? (n) => role.allowTools.includes(n)
+        : role?.denyTools
+            ? (n) => !role.denyTools.includes(n)
+            : undefined;
+    const history = [{ role: "user", content: atomPrompt(atom, plan, done) }];
+    try {
+        await runAgent(history, {
+            provider: roleProvider,
+            ctx: { cwd: o.cwd, sandbox: o.sandbox },
+            approval: o.approval,
+            confirm: o.confirm,
+            projectContext: o.projectContext,
+            memory: memoryDigest(o.cwd),
+            stats: o.stats,
+            systemOverride: role?.system,
+            toolFilter,
+            quiet: o.parallel, // concurrent atoms would otherwise interleave their streamed output
+        });
+    }
+    catch (e) {
+        atom.status = "failed";
+        atom.note = e.message;
+        savePlan(o.cwd, plan);
+        out(c.red(`  ✗ ${atom.id} errored: ${e.message}\n`));
+        return false;
+    }
+    const v = atom.check ? await runCheck(atom.check, o.cwd, o.sandbox) : await verify(o.baseProvider, atom, lastAssistantText(history));
+    atom.status = v.ok ? "done" : "failed";
+    atom.note = v.reason;
+    savePlan(o.cwd, plan);
+    out(v.ok ? c.green(`  ✓ ${atom.id} verified\n`) : c.yellow(`  ⚠ ${atom.id}: ${v.reason}\n`));
+    return v.ok;
+}
+/** Execute a plan's atoms (sequential, or parallel waves with --parallel). Atoms already marked `done`
+ *  are skipped — so this doubles as the resume engine. Stops on the first failure. */
+async function executePlan(plan, roles, o) {
+    const done = plan.atoms.filter((a) => a.status === "done");
+    const doneIds = new Set(done.map((a) => a.id));
+    if (o.parallel) {
+        const waved = topoWaves(plan.atoms);
+        if ("error" in waved)
+            return void out(c.red(`${waved.error}\n`));
+        out(c.dim(`Parallel mode — ${waved.ok.length} wave(s).\n`));
+        for (const wave of waved.ok) {
+            const todo = wave.filter((a) => !doneIds.has(a.id));
+            if (!todo.length)
+                continue; // whole wave already complete (resume)
+            out(c.cyan(`\n▶ wave [${todo.map((a) => a.id).join(", ")}] — ${todo.length} in parallel\n`));
+            const results = await Promise.all(todo.map((atom) => executeAtom(atom, plan, done, roles, o)));
+            todo.forEach((atom, i) => {
+                if (results[i]) {
+                    done.push(atom);
+                    doneIds.add(atom.id);
+                }
+            });
+            if (results.some((r) => !r)) {
+                out(c.dim("Stopping — a wave atom failed. Inspect .hara/org/plan.json, then fix & `hara plan resume`.\n"));
+                break;
+            }
+        }
+    }
+    else {
+        const ord = topoOrder(plan.atoms);
+        if ("error" in ord)
+            return void out(c.red(`${ord.error}\n`));
+        for (const atom of ord.ok) {
+            if (doneIds.has(atom.id))
+                continue; // resume: skip completed atoms
+            out(c.cyan(`\n▶ ${atom.id} ${atom.title}\n`));
+            if (await executeAtom(atom, plan, done, roles, o)) {
+                done.push(atom);
+                doneIds.add(atom.id);
+            }
+            else {
+                out(c.dim("Stopping — inspect .hara/org/plan.json, then fix & `hara plan resume`.\n"));
+                break;
+            }
+        }
+    }
+    out(c.bold(`\nPlan: ${plan.atoms.filter((a) => a.status === "done").length}/${plan.atoms.length} atoms done.\n`));
+}
+/** Decompose a task into atoms, sequence them (DAG), and execute each with a verify gate.
+ *  With `parallel`, independent atoms (the same dependency wave) run concurrently. */
 async function runPlan(task, o) {
     const roles = loadRoles(o.cwd);
     out(c.dim("Planning…\n"));
@@ -147,68 +238,75 @@ async function runPlan(task, o) {
         out(c.red(`${ord.error}\n`));
         return;
     }
-    const ordered = ord.ok;
-    out(c.bold(`\nPlan (${ordered.length} atoms):\n`));
-    for (const a of ordered) {
+    out(c.bold(`\nPlan (${ord.ok.length} atoms):\n`));
+    for (const a of ord.ok) {
         out(`  ${c.cyan(a.id)} ${a.title}${a.deps.length ? c.dim(" ←" + a.deps.join(",")) : ""}${a.role ? c.dim(" @" + a.role) : ""}${a.check ? c.dim(" ✓" + a.check) : ""}\n`);
     }
     if (o.approval !== "full-auto") {
-        const ok = await o.confirm(`${c.yellow("▶")} Execute this ${ordered.length}-atom plan?`);
+        const ok = await o.confirm(`${c.yellow("▶")} Execute this ${ord.ok.length}-atom plan?`);
         if (!ok)
             return void out(c.dim("(cancelled)\n"));
     }
     savePlan(o.cwd, plan);
-    const done = [];
-    for (const atom of ordered) {
-        atom.status = "running";
-        savePlan(o.cwd, plan);
-        out(c.cyan(`\n▶ ${atom.id} ${atom.title}\n`));
-        const role = atom.role ? roles.find((r) => r.id === atom.role) : undefined;
-        const roleProvider = role?.model && role.model !== o.cfg.model ? ((await buildProvider({ ...o.cfg, model: role.model })) ?? o.baseProvider) : o.baseProvider;
-        const toolFilter = role?.allowTools
-            ? (n) => role.allowTools.includes(n)
-            : role?.denyTools
-                ? (n) => !role.denyTools.includes(n)
-                : undefined;
-        const history = [{ role: "user", content: atomPrompt(atom, plan, done) }];
-        try {
-            await runAgent(history, {
-                provider: roleProvider,
-                ctx: { cwd: o.cwd, sandbox: o.sandbox },
-                approval: o.approval,
-                confirm: o.confirm,
-                projectContext: o.projectContext,
-                memory: memoryDigest(o.cwd),
-                stats: o.stats,
-                systemOverride: role?.system,
-                toolFilter,
-            });
-        }
-        catch (e) {
-            atom.status = "failed";
-            atom.note = e.message;
-            savePlan(o.cwd, plan);
-            out(c.red(`  ✗ ${atom.id} errored: ${e.message}\n`));
-            break;
-        }
-        if (atom.check)
-            out(c.dim(`  check: ${atom.check}\n`));
-        const v = atom.check ? await runCheck(atom.check, o.cwd, o.sandbox) : await verify(o.baseProvider, atom, lastAssistantText(history));
-        atom.status = v.ok ? "done" : "failed";
-        atom.note = v.reason;
-        savePlan(o.cwd, plan);
-        if (v.ok) {
-            out(c.green(`  ✓ ${atom.id} verified\n`));
-            done.push(atom);
-        }
-        else {
-            out(c.yellow(`  ⚠ ${atom.id}: ${v.reason}\n`) + c.dim("Stopping — inspect .hara/org/plan.json, then refine & re-run.\n"));
-            break;
-        }
+    await executePlan(plan, roles, o);
+}
+/** Resume the saved plan (.hara/org/plan.json): re-run atoms that aren't done; completed atoms are skipped. */
+async function runResume(o) {
+    const roles = loadRoles(o.cwd);
+    const plan = loadPlan(o.cwd);
+    if (!plan)
+        return void out(c.red('No saved plan at .hara/org/plan.json — run `hara plan "<task>"` first.\n'));
+    const remaining = plan.atoms.filter((a) => a.status !== "done");
+    if (!remaining.length)
+        return void out(c.green(`Plan already complete — ${plan.atoms.length}/${plan.atoms.length} done.\n`));
+    out(c.bold(`Resuming: ${plan.task}\n`) + c.dim(`${plan.atoms.length - remaining.length}/${plan.atoms.length} done · ${remaining.length} to go\n`));
+    for (const a of remaining)
+        out(`  ${c.cyan(a.id)} ${a.title} ${c.dim("(" + a.status + ")")}\n`);
+    if (o.approval !== "full-auto") {
+        const ok = await o.confirm(`${c.yellow("▶")} Resume the ${remaining.length} remaining atom(s)?`);
+        if (!ok)
+            return void out(c.dim("(cancelled)\n"));
+    }
+    for (const a of plan.atoms)
+        if (a.status === "failed" || a.status === "running")
+            a.status = "pending"; // retry interrupted
+    savePlan(o.cwd, plan);
+    await executePlan(plan, roles, o);
+}
+const READONLY_TOOLS = new Set(["read_file", "grep", "glob", "ls", "web_fetch", "web_search", "codebase_search", "todo_write"]);
+const REVIEW_SYSTEM = "You are a senior code reviewer. Review the git diff the user provides for: correctness bugs, security " +
+    "issues, missing error handling, unclear naming, and missing/weak tests. You may read files (read-only) " +
+    "for context. Be concise and specific — cite file:line and the concrete fix. Group findings by severity: " +
+    "**Blocker**, **Should-fix**, **Nit**. If nothing material is wrong, say the diff looks good. Never edit files.";
+const COMMIT_SYSTEM = "Write a git commit message for the staged diff. A concise imperative subject (≤72 chars; an optional " +
+    "conventional-commits prefix like feat:/fix:/refactor:/docs:/test:/chore: is welcome). If the change is " +
+    "non-trivial, add a blank line then a short body (a few bullets or sentences) on what changed and why. " +
+    "Output ONLY the commit message — no code fences, no preamble, no surrounding quotes.";
+const SESSION_NAME_SYSTEM = "Name this coding session as a SHORT slug: 2–4 English words, lowercase, hyphen-separated, ASCII only " +
+    "(e.g. add-semantic-search, fix-login-redirect). If the conversation is in another language, translate the " +
+    "gist to English (use pinyin only if a term is untranslatable). Output ONLY the slug.";
+/** One short model call → a 2–4 word English kebab-case session name summarizing the work.
+ *  Always ASCII (translates non-English gist). Falls back to the lexical title on any failure. */
+async function nameSession(provider, history) {
+    const text = (m) => {
+        if (!m)
+            return "";
+        if (m.role === "assistant")
+            return typeof m.text === "string" ? m.text : "";
+        if (m.role === "user")
+            return typeof m.content === "string" ? m.content : "";
+        return "";
+    };
+    const basis = `User: ${text(history.find((m) => m.role === "user")).slice(0, 800)}\n` +
+        `Assistant: ${text(history.find((m) => m.role === "assistant")).slice(0, 800)}`;
+    try {
+        const r = await provider.turn({ system: SESSION_NAME_SYSTEM, history: [{ role: "user", content: basis }], tools: [], onText: () => { } });
+        return slugify(r.text) || titleFrom(history);
+    }
+    catch {
+        return titleFrom(history);
     }
-    out(c.bold(`\nPlan: ${plan.atoms.filter((a) => a.status === "done").length}/${plan.atoms.length} atoms done.\n`));
 }
-const READONLY_TOOLS = new Set(["read_file", "grep", "glob", "ls", "web_fetch"]);
 const PLAN_SYSTEM = "You are in PLAN MODE. Investigate read-only (read_file / grep / glob / ls / web_fetch) and think, " +
     "then propose a concise step-by-step plan for the task. Do NOT edit files or run commands yet — only plan. " +
     "End your message with the plan as a short numbered list.";
@@ -280,6 +378,8 @@ function runDoctor(cfg) {
         `${dot} screen ${cfg.computerUse === "off" ? c.dim("off (hara config set computerUse read|click|full)") : c.bold(cfg.computerUse) + c.dim(` · ${computerBackends()}${cfg.computerApps.length ? " · apps: " + cfg.computerApps.join(", ") : " · no app allowlist"}`)}`,
         `${dot} plugins ${(() => { const inst = listInstalled(); const on = enabledPlugins().length; return inst.length ? c.dim(`${on}/${inst.length} enabled: ${inst.map((p) => p.name).slice(0, 6).join(", ")}`) : c.dim("none — hara plugin add <source>"); })()}`,
         `${dot} mcp servers ${c.dim(String(Object.keys({ ...pluginMcpServers(), ...cfg.mcpServers }).length))}`,
+        `${dot} hooks ${(() => { const ph = pluginHooks(); const pre = (cfg.hooks.PreToolUse ?? []).length + (ph.PreToolUse ?? []).length; const post = (cfg.hooks.PostToolUse ?? []).length + (ph.PostToolUse ?? []).length; return pre + post ? c.dim(`${pre} pre · ${post} post`) : c.dim("none — config.json \"hooks\""); })()}`,
+        `${dot} notify ${cfg.notify === "off" ? c.dim("off — hara config set notify bell|system") : c.bold(cfg.notify)}`,
     ];
     return lines.join("\n");
 }
@@ -359,9 +459,10 @@ program
         out(statusLine(cfg.model, stats.input, stats.output) + "\n");
 });
 program
-    .command("plan <task...>")
+    .command("plan [task...]")
     .description("decompose a task into atoms, sequence them (DAG), and execute each with a verify gate")
-    .action(async (taskParts) => {
+    .option("--parallel", "run independent atoms (same dependency wave) concurrently")
+    .action(async (taskParts, opts) => {
     const cfg = loadConfig();
     const provider = await buildProvider(cfg);
     if (!provider) {
@@ -369,7 +470,7 @@ program
         process.exit(1);
     }
     const stats = { input: 0, output: 0, lastInput: 0 };
-    await runPlan(taskParts.join(" "), {
+    const o = {
         cfg,
         baseProvider: provider,
         cwd: cfg.cwd,
@@ -378,7 +479,15 @@ program
         confirm: async () => true,
         projectContext: loadAgentsMd(cfg.cwd) || undefined,
         stats,
-    });
+        parallel: opts.parallel,
+    };
+    const task = (taskParts ?? []).join(" ").trim();
+    if (task === "resume")
+        await runResume(o);
+    else if (!task)
+        out(c.dim('usage: hara plan "<task>"   (or: hara plan resume)\n'));
+    else
+        await runPlan(task, o);
     if (stats.input || stats.output)
         out(statusLine(cfg.model, stats.input, stats.output) + "\n");
 });
@@ -424,10 +533,11 @@ program
     const build = async (name, chunks, blurb) => {
         if (!chunks.length)
             return void out(c.dim(`Nothing to index for ${name}.\n`));
-        out(c.dim(`Embedding ${chunks.length} ${name} chunks with ${cfg.embedProvider}…\n`));
+        out(c.dim(`Indexing ${chunks.length} ${name} chunks with ${cfg.embedProvider}…\n`));
         try {
-            const n = await buildIndex(name, chunks, embed, cwd, model);
-            out(c.green(`Indexed ${n} chunks → ${indexPath(name, cwd)}`) + c.dim(` (${blurb})`) + "\n");
+            const r = await buildIndex(name, chunks, embed, cwd, model);
+            const detail = r.reused ? `${r.embedded} embedded, ${r.reused} reused` : `${r.embedded} embedded`;
+            out(c.green(`Indexed ${r.total} chunks`) + c.dim(` (${detail}) → ${indexPath(name, cwd)} · ${blurb}`) + "\n");
         }
         catch (e) {
             out(c.red(`Indexing ${name} failed: ${e.message}\n`));
@@ -445,6 +555,111 @@ program
     .command("doctor")
     .description("check your hara setup (provider / auth / model / node / assets / roles)")
     .action(() => out(runDoctor(loadConfig()) + "\n"));
+program
+    .command("review")
+    .description("review your uncommitted changes (git diff) for bugs, security, and missing tests")
+    .option("--staged", "review only staged changes")
+    .option("--base <ref>", "review against a base ref (e.g. main) instead of just the working tree")
+    .action(async (opts) => {
+    const cfg = loadConfig();
+    const provider = await buildProvider(cfg);
+    if (!provider) {
+        out(c.red(`Not authenticated for provider '${cfg.provider}'.\n`) + authHint(cfg) + "\n");
+        process.exit(1);
+    }
+    const cmd = opts.base ? `git diff ${opts.base}` : opts.staged ? "git diff --staged" : "git diff HEAD";
+    let diff = "";
+    try {
+        diff = (await runShell(cmd, cfg.cwd, "off", { timeout: 30_000, maxBuffer: 8_000_000 })).stdout;
+    }
+    catch (e) {
+        return void out(c.red(`\`${cmd}\` failed: ${e instanceof Error ? e.message : String(e)}\n`) + c.dim("(is this a git repo?)\n"));
+    }
+    if (!diff.trim())
+        return void out(c.dim(`No changes to review (${cmd}).\n`));
+    out(c.dim(`Reviewing \`${cmd}\` (${diff.split("\n").length} diff lines)…\n\n`));
+    const stats = { input: 0, output: 0, lastInput: 0 };
+    await runAgent([{ role: "user", content: `Review this diff:\n\n\`\`\`diff\n${diff.slice(0, 120_000)}\n\`\`\`` }], {
+        provider,
+        ctx: { cwd: cfg.cwd, sandbox: cfg.sandbox },
+        approval: "full-auto",
+        confirm: async () => true,
+        systemOverride: REVIEW_SYSTEM,
+        toolFilter: (n) => READONLY_TOOLS.has(n), // read-only: the reviewer can inspect, never edit
+        projectContext: loadAgentsMd(cfg.cwd) || undefined,
+        memory: memoryDigest(cfg.cwd),
+        stats,
+    });
+    if (stats.input || stats.output)
+        out("\n" + statusLine(cfg.model, stats.input, stats.output) + "\n");
+});
+program
+    .command("commit")
+    .description("generate a commit message from staged changes and commit (-y to skip the confirm)")
+    .option("-a, --all", "stage all tracked changes first (git add -u)")
+    .action(async (opts) => {
+    const skipConfirm = !!program.opts().yes; // reuse the global -y/--yes (auto-approve)
+    const cfg = loadConfig();
+    const provider = await buildProvider(cfg);
+    if (!provider) {
+        out(c.red(`Not authenticated for provider '${cfg.provider}'.\n`) + authHint(cfg) + "\n");
+        process.exit(1);
+    }
+    if (opts.all) {
+        try {
+            await runShell("git add -u", cfg.cwd, "off", { timeout: 30_000, maxBuffer: 1_000_000 });
+        }
+        catch {
+            /* report below if nothing is staged */
+        }
+    }
+    let diff = "";
+    try {
+        diff = (await runShell("git diff --staged", cfg.cwd, "off", { timeout: 30_000, maxBuffer: 8_000_000 })).stdout;
+    }
+    catch (e) {
+        return void out(c.red(`git diff failed: ${e instanceof Error ? e.message : String(e)}\n`) + c.dim("(is this a git repo?)\n"));
+    }
+    if (!diff.trim())
+        return void out(c.dim("Nothing staged. Stage changes with `git add`, or use `hara commit -a`.\n"));
+    out(c.dim("Writing a commit message…\n"));
+    const r = await provider.turn({
+        system: COMMIT_SYSTEM,
+        history: [{ role: "user", content: `Write a commit message for these staged changes:\n\n\`\`\`diff\n${diff.slice(0, 120_000)}\n\`\`\`` }],
+        tools: [],
+        onText: () => { },
+    });
+    if (r.stop === "error")
+        return void out(c.red(`message generation failed: ${r.errorMsg ?? "provider error"}\n`));
+    const msg = r.text.trim().replace(/^```[a-z]*\n?/i, "").replace(/\n?```$/i, "").trim();
+    if (!msg)
+        return void out(c.red("No commit message produced — commit manually or retry.\n"));
+    out("\n" + c.bold("Proposed commit message:\n") + c.dim("─".repeat(48) + "\n") + msg + "\n" + c.dim("─".repeat(48)) + "\n\n");
+    if (!skipConfirm) {
+        const rl = createInterface({ input: stdin, output: stdout });
+        const ans = (await rl.question(`Commit with this message? ${c.dim("[Y/n]")} `)).trim().toLowerCase();
+        rl.close();
+        if (ans === "n" || ans === "no")
+            return void out(c.dim("(cancelled — nothing committed)\n"));
+    }
+    const tmp = join(tmpdir(), `hara-commit-${process.pid}.txt`);
+    writeFileSync(tmp, msg + "\n", "utf8");
+    try {
+        const res = await runShell(`git commit -F ${JSON.stringify(tmp)}`, cfg.cwd, "off", { timeout: 30_000, maxBuffer: 1_000_000 });
+        out(c.green("✓ committed ") + c.dim(((res.stdout || "").trim().split("\n")[0] || "").slice(0, 100)) + "\n");
+    }
+    catch (e) {
+        out(c.red(`git commit failed: ${e instanceof Error ? e.message : String(e)}\n`));
+    }
+    finally {
+        try {
+            rmSync(tmp);
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+    }
+});
 const rolesCmd = program.command("roles").description("manage org roles (.hara/roles)");
 rolesCmd
     .command("init")
@@ -965,19 +1180,35 @@ program.action(async (opts) => {
             visionProvider = await buildProvider({ ...cfg, model: cfg.visionModel, baseURL: cfg.visionBaseURL ?? cfg.baseURL, apiKey: cfg.visionApiKey ?? cfg.apiKey });
             return visionProvider;
         };
-        // lets the computer tool return a screenshot as text (describe via the vision sidecar / a vision main model)
-        const describeScreenshot = async (path) => {
+        // lets the computer tool return a screenshot as text (describe via the vision sidecar / a vision main model).
+        // Uses the screenshot-tuned prompt (actionable UI elements + positions) + an optional focus hint, so a
+        // text-only main model gets something it can click on rather than a generic transcription.
+        const describeScreenshot = async (path, hint) => {
             const cap = classifyVision(cfg.provider, cfg.model, cfg.modelVision);
             const vp = cfg.visionModel ? await getVisionProvider() : cap === "vision" ? provider : null;
             if (!vp)
                 return "";
             try {
-                return await describeImages(vp, [{ path, mediaType: "image/png" }]);
+                return await describeImages(vp, [{ path, mediaType: "image/png" }], { system: SCREENSHOT_SYSTEM, hint });
             }
             catch {
                 return "";
             }
         };
+        // grounding for accurate RPA: ask the vision model WHERE an element is (0..1 fractions) so the computer
+        // tool can click it precisely instead of guessing pixels from a text description.
+        const locateScreenshot = async (path, target) => {
+            const cap = classifyVision(cfg.provider, cfg.model, cfg.modelVision);
+            const vp = cfg.visionModel ? await getVisionProvider() : cap === "vision" ? provider : null;
+            if (!vp)
+                return null;
+            try {
+                return await locateImage(vp, { path, mediaType: "image/png" }, target);
+            }
+            catch {
+                return null;
+            }
+        };
         const remindVision = (sink) => {
             if (remindedVision)
                 return void sink.notice(`⚠ image skipped — ${cfg.model} is text-only. Add a vision model: /vision <model>`);
@@ -1196,6 +1427,22 @@ program.action(async (opts) => {
                 }
                 const ui = { text: h.sink.assistantDelta, reasoning: h.sink.reasoningDelta, tool: h.sink.tool, diff: h.sink.diff, notice: h.sink.notice };
                 const appr = h.approval;
+                // Type-ahead steering: fold messages typed mid-turn into the next model call (codex-style) so a
+                // clarification/addition course-corrects the live task, rather than waiting for a fresh turn.
+                // Shared by every turn below (plan investigate, plan execute, and the regular turn).
+                const pendingInput = async () => {
+                    const out = [];
+                    for (const it of h.drainQueue()) {
+                        const r2 = await resolveImages(it.images, h);
+                        const body = expandMentions(it.line, cwd) + (r2.skip ? "" : (r2.extraText ?? ""));
+                        const attach = !r2.skip && r2.attach?.length ? r2.attach : undefined;
+                        if (!body.trim() && !attach)
+                            continue; // image-only message whose image was skipped → nothing to add
+                        out.push({ role: "user", content: `[I sent this while you were working on the above]\n\n${body}`, ...(attach ? { images: attach } : {}) });
+                    }
+                    return out;
+                };
+                const turnStart = Date.now(); // for the task-done notification (gated on elapsed)
                 if (appr === "plan") {
                     // PLAN MODE: read-only investigate → propose a plan → selectable proceed → execute.
                     const planImg = await resolveImages(images, h);
@@ -1207,7 +1454,7 @@ program.action(async (opts) => {
                     const pout = stats.output;
                     await runAgent(history, {
                         provider,
-                        ctx: { cwd, sandbox, spawn, ui, describeImage: describeScreenshot },
+                        ctx: { cwd, sandbox, spawn, ui, describeImage: describeScreenshot, locate: locateScreenshot },
                         approval: "suggest",
                         confirm: h.confirm,
                         toolFilter: (n) => READONLY_TOOLS.has(n),
@@ -1216,9 +1463,10 @@ program.action(async (opts) => {
                         projectContext,
                         stats,
                         signal: h.signal,
+                        pendingInput,
                     });
                     if (!meta.title) {
-                        meta.title = titleFrom(history);
+                        meta.title = await nameSession(provider, history);
                         h.sink.session(meta.title);
                     }
                     h.sink.usage(stats.input - pin, stats.output - pout);
@@ -1235,7 +1483,7 @@ program.action(async (opts) => {
                         const xout = stats.output;
                         await runAgent(history, {
                             provider,
-                            ctx: { cwd, sandbox, spawn, ui, describeImage: describeScreenshot },
+                            ctx: { cwd, sandbox, spawn, ui, describeImage: describeScreenshot, locate: locateScreenshot },
                             approval: choice,
                             memory: buildMemory(),
                             confirm: h.confirm,
@@ -1243,10 +1491,12 @@ program.action(async (opts) => {
                             projectContext,
                             stats,
                             signal: h.signal,
+                            pendingInput,
                         });
                         h.sink.usage(stats.input - xin, stats.output - xout);
                         saveSession(meta, history);
                     }
+                    notifyDone(cfg.notify, { message: meta.title || "plan turn complete", elapsedMs: Date.now() - turnStart });
                     return;
                 }
                 const ri = await resolveImages(images, h);
@@ -1259,7 +1509,7 @@ program.action(async (opts) => {
                 const beforeOut = stats.output;
                 await runAgent(history, {
                     provider,
-                    ctx: { cwd, sandbox, spawn, ui, describeImage: describeScreenshot },
+                    ctx: { cwd, sandbox, spawn, ui, describeImage: describeScreenshot, locate: locateScreenshot },
                     approval: appr,
                     memory: buildMemory(),
                     confirm: h.confirm,
@@ -1267,12 +1517,14 @@ program.action(async (opts) => {
                     projectContext,
                     stats,
                     signal: h.signal,
+                    pendingInput,
                 });
                 if (!meta.title) {
-                    meta.title = titleFrom(history);
+                    meta.title = await nameSession(provider, history);
                     h.sink.session(meta.title);
                 }
                 h.sink.usage(stats.input - beforeIn, stats.output - beforeOut);
+                notifyDone(cfg.notify, { message: meta.title || "turn complete", elapsedMs: Date.now() - turnStart });
                 saveSession(meta, history);
             },
         });
@@ -1319,6 +1571,7 @@ program.action(async (opts) => {
         recalledContext = "";
         history.push({ role: "user", content: userContent });
         currentTurn = new AbortController();
+        const t0 = Date.now();
         try {
             await runAgent(history, { provider, ctx: { cwd, sandbox, spawn }, approval, confirm, autoApprove, projectContext, memory: buildMemory(), stats, signal: currentTurn.signal });
         }
@@ -1328,8 +1581,9 @@ program.action(async (opts) => {
         finally {
             currentTurn = null;
         }
+        notifyDone(cfg.notify, { message: meta.title || "turn complete", elapsedMs: Date.now() - t0 });
         if (!meta.title)
-            meta.title = titleFrom(history);
+            meta.title = await nameSession(provider, history);
         if (bar.isActive()) {
             bar.update({
                 sessionName: meta.title,

package/dist/notify.js

@@ -0,0 +1,42 @@
+// Task-done notifications — ping the user when a turn finishes (or needs them) so they can walk away
+// during a long run (codex/Claude-Code parity). off = nothing; bell = terminal BEL; system = an OS
+// notification (best-effort, fire-and-forget) + bell. Gated on elapsed so quick turns you watched stay quiet.
+import { spawn } from "node:child_process";
+import { platform } from "node:os";
+export const NOTIFY_MODES = ["off", "bell", "system"];
+/** AppleScript double-quoted string (escape " and \). */
+const osaStr = (s) => '"' + s.replace(/[\\"]/g, "\\$&") + '"';
+/** Fire a notification for a finished/awaiting turn. No-op under `off` or when the turn was quicker than
+ *  `minMs` (default 8s) — you were watching those. `system` shells out without blocking and also rings the bell. */
+export function notifyDone(mode, opts) {
+    if (mode === "off")
+        return;
+    if (opts.elapsedMs < (opts.minMs ?? 8000))
+        return;
+    const bell = () => {
+        try {
+            process.stderr.write("\x07");
+        }
+        catch {
+            /* no tty */
+        }
+    };
+    if (mode === "bell")
+        return bell();
+    const title = (opts.title ?? "hara").slice(0, 80);
+    const msg = opts.message.slice(0, 200).replace(/\s*\n+\s*/g, " ").trim() || "done";
+    try {
+        const os = platform();
+        if (os === "darwin") {
+            spawn("osascript", ["-e", `display notification ${osaStr(msg)} with title ${osaStr(title)}`], { stdio: "ignore", detached: true }).unref();
+        }
+        else if (os === "linux") {
+            spawn("notify-send", ["-a", "hara", title, msg], { stdio: "ignore", detached: true }).unref();
+        }
+        // Windows (and any platform): the bell is the reliable cross-terminal signal; toast needs extra modules.
+    }
+    catch {
+        /* best-effort — a notification must never break the turn */
+    }
+    bell();
+}