@nanhara/hara 0.67.0 → 0.89.0

package/dist/index.js

@@ -3,7 +3,7 @@ import { Command } from "commander";
 import { createInterface } from "node:readline/promises";
 import { emitKeypressEvents } from "node:readline";
 import { runTui } from "./tui/run.js";
-import { readClipboardImage } from "./images.js";
+import { readClipboardImage, mediaTypeFor } from "./images.js";
 import { describeImages, locateImage, classifyVision, SCREENSHOT_SYSTEM } from "./vision.js";
 import { setTheme } from "./tui/theme.js";
 import { memoryDigest, memoryDir, readRecentLogs, scaffoldMemory } from "./memory/store.js";
@@ -19,7 +19,13 @@ import { notifyDone } from "./notify.js";
 import { startMcpServer, mcpServeToolNames } from "./mcp/server.js";
 import { completionScript } from "./completions.js";
 import { renderSessionMarkdown } from "./export.js";
-import { loadEnrollment, clearEnrollment, enrollDevice, heartbeat, gatewayBaseURL } from "./org-fleet/enroll.js";
+import { loadEnrollment, clearEnrollment, enrollDevice, heartbeat, gatewayBaseURL, syncOrgRoles } from "./org-fleet/enroll.js";
+import { loadPermissionRules, scaffoldPermissions, globalPermissionsPath, projectPermissionsPath } from "./security/permissions.js";
+import { routingProvider } from "./agent/route.js";
+import { shouldAutoCompact } from "./agent/compact.js";
+import { formatContextReport } from "./agent/context-report.js";
+import { userTurnPreviews, rewindTo } from "./agent/rewind.js";
+import { checkpoint, listCheckpoints, restoreCheckpoint } from "./checkpoints.js";
 import { mapLimit, maxParallel } from "./concurrency.js";
 import { parseVerdict, captureChanges, reviewPrompt, fixPrompt, REVIEWER_SYSTEM, isTreeClean, stripCommitFence } from "./org/review-chain.js";
 import { parseSchedule, describeSchedule, nextRun } from "./cron/schedule.js";
@@ -58,6 +64,7 @@ import "./tools/memory.js"; // register memory_search/get/write/forget/skill_cre
 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 "./tools/send.js"; // register send_file (self-gates on HARA_GATEWAY — pushes a file to the chat)
 import { computerBackends } from "./tools/computer.js"; // register the computer tool + expose the backend probe
 const here = dirname(fileURLToPath(import.meta.url));
 // Version: from a build-time define in the compiled single-binary (no package.json on its virtual FS),
@@ -94,6 +101,15 @@ async function buildProvider(cfg) {
     }
     return createOpenAIProvider({ apiKey: cfg.apiKey, model: cfg.model, baseURL: cfg.baseURL, label: cfg.provider });
 }
+/** Wrap the main provider with per-turn model routing when `routeModel` is configured: trivial/non-coding
+ *  turns go to the alternate (cheap/general) model, real coding/action work stays on the primary. No-op when
+ *  routeModel is unset or equals the primary model. routeBaseURL/routeApiKey default to the primary's. */
+async function withRouting(primary, cfg) {
+    if (!primary || !cfg.routeModel || cfg.routeModel === cfg.model)
+        return primary;
+    const alt = await buildProvider({ ...cfg, model: cfg.routeModel, baseURL: cfg.routeBaseURL ?? cfg.baseURL, apiKey: cfg.routeApiKey ?? cfg.apiKey });
+    return alt ? routingProvider(primary, alt) : primary;
+}
 function authHint(cfg) {
     if (cfg.provider === "qwen-oauth")
         return `Run ${c.bold("hara login qwen")} to authenticate.`;
@@ -486,15 +502,59 @@ const MEMORY_DISTILL_SYSTEM = "You consolidate an agent's short-term daily memor
     "conventions / user preferences from the logs that are NOT already captured, and persist each with " +
     "memory_write (target=memory, or target=user for preferences; pick the right scope=project|global). " +
     "Skip the ephemeral, the one-off, and anything already known. Be terse and de-duplicated. Then reply DONE.";
-const COMPACT_SYSTEM = "Summarize the conversation so far into a concise but complete brief so the assistant can " +
-    "continue seamlessly: the user's goal, key decisions, files changed, current state, and open next steps. " +
-    "Be specific. Output only the summary.";
+const COMPACT_SYSTEM = "Summarize the conversation so far into a structured, complete brief so the assistant can continue with NO " +
+    "loss of context. First think privately in a brief <analysis> scratchpad (what matters, what's in flight), " +
+    "then output ONLY the summary under these exact headings:\n" +
+    "1. Goal — the user's overall intent, in their own framing.\n" +
+    "2. Key decisions — choices made and why (so they aren't relitigated).\n" +
+    "3. Files & code — files created/changed and the important snippets, with why each matters.\n" +
+    "4. Errors & fixes — failures hit, how they were resolved, and any correction the user gave (quote pointed feedback verbatim).\n" +
+    "5. Current state — what works now / what is verified.\n" +
+    "6. Next step — the immediate next action, INCLUDING a direct verbatim quote of the user's most recent request so there is no drift.\n" +
+    "Be specific and concrete. Drop the <analysis>; output only the headed summary.";
 const workingSetFromSummary = (s) => s
     .split("\n")
     .map((l) => l.replace(/^[-*\d.\s]+/, "").trim())
     .filter((l) => l.length > 3)
     .slice(0, 12)
     .map((l) => l.slice(0, 140));
+/** Summarize the conversation and replace history with the summary (keeping working-memory notes). Shared by
+ *  /compact (manual) and auto-compaction. Returns the summary, or null on failure / nothing to do. */
+async function compactConversation(provider, history, meta, stats) {
+    if (history.length < 2)
+        return null;
+    const r = await provider.turn({
+        system: COMPACT_SYSTEM,
+        history: [...history, { role: "user", content: "Summarize our conversation so far per the instructions." }],
+        tools: [],
+        onText: () => { },
+    });
+    if (r.stop === "error")
+        return null;
+    const summary = r.text.trim();
+    if (!summary)
+        return null;
+    meta.workingSet = workingSetFromSummary(summary); // survives the history wipe + injects into the next turns
+    history.length = 0;
+    history.push({ role: "user", content: `Summary of our conversation so far (continue from here):\n\n${summary}` });
+    stats.input += r.usage?.input ?? 0;
+    stats.output += r.usage?.output ?? 0;
+    stats.lastInput = r.usage?.input ?? 0; // ctx% now reflects the (small) summary, not the old full turn
+    saveSession(meta, history);
+    return summary;
+}
+/** Auto-compact (à la Claude Code) when the last turn filled the context past the threshold, so the NEXT turn
+ *  doesn't overflow. Opt-out via `autoCompact: false` / `HARA_AUTO_COMPACT=0`. Best-effort; `notify` surfaces
+ *  a one-line status. Returns true if it compacted. */
+async function maybeAutoCompact(provider, history, meta, stats, cfg, notify) {
+    const pct = bar.ctxPctFor(cfg.model, stats.lastInput ?? 0);
+    if (!shouldAutoCompact(pct, history.length, cfg.autoCompact))
+        return false;
+    notify(`✻ Auto-compacting conversation (context ${pct}% full)…`);
+    const summary = await compactConversation(provider, history, meta, stats);
+    notify(summary ? `(auto-compacted — context replaced with a summary; ${meta.workingSet?.length ?? 0} notes kept)` : "(auto-compact failed — use /compact or /clear)");
+    return !!summary;
+}
 /** Run a (read-only by default) sub-agent to completion, quietly, and return its final text. */
 async function runSubagent(cfg, baseProvider, cwd, sandbox, projectContext, stats, task, roleId) {
     const roles = loadRoles(cwd);
@@ -763,11 +823,50 @@ program
         if (e.model)
             writeConfigValue("model", e.model);
         out(c.green(`✓ enrolled with ${e.gatewayUrl}`) + c.dim(` · device ${e.deviceId || "?"} · model ${e.model || "(gateway default)"}\n`) + c.dim("hara routes through the gateway now — the real provider key stays server-side.\n"));
+        const nRoles = await syncOrgRoles(); // pull this device's governed digital-employee bundle (B3)
+        if (nRoles > 0)
+            out(c.dim(`  ↳ synced ${nRoles} org role${nRoles === 1 ? "" : "s"} → ~/.hara/org-roles/\n`));
     }
     catch (err) {
         out(c.red(`Enroll failed: ${err instanceof Error ? err.message : String(err)}\n`));
     }
 });
+program
+    .command("permissions")
+    .description("show or scaffold command permission rules (bash allow/ask/deny + read-only autorun)")
+    .option("--init", "write a starter permissions.json")
+    .option("--project", "with --init, write it in this project (.hara/permissions.json) instead of globally")
+    .action((opts) => {
+    if (opts.init) {
+        const p = scaffoldPermissions(process.cwd(), opts.project ? "project" : "global");
+        return void out(p ? c.green(`✓ wrote ${p}\n`) : c.dim("(permissions file already exists — edit it directly)\n"));
+    }
+    const r = loadPermissionRules(process.cwd());
+    const pp = projectPermissionsPath(process.cwd());
+    out(c.bold("Command permissions") +
+        c.dim(" (bash) — deny blocks even in full-auto; allow / read-only auto-runs even in suggest\n") +
+        `  ${c.dim("global: ")} ${globalPermissionsPath()}\n` +
+        `  ${c.dim("project:")} ${pp ?? "(none)"}\n` +
+        `  ${c.dim("read-only autorun:")} ${r.readonlyAutorun ? c.green("on") : "off"}\n` +
+        `  ${c.green("allow")}: ${r.allow.length ? r.allow.join(", ") : c.dim("(none)")}\n` +
+        `  ${c.red("deny")} : ${r.deny.length ? r.deny.join(", ") : c.dim("(none)")}\n` +
+        c.dim("  edit the JSON to customize, or `hara permissions --init` for a starter.\n"));
+});
+program
+    .command("gateway")
+    .description("run a chat gateway (Telegram or WeChat) so you can drive your local hara from your phone — opt-in daemon")
+    .option("--platform <name>", "chat platform: telegram | weixin | discord | feishu | slack | mattermost | matrix | dingtalk", "telegram")
+    .option("--login", "(weixin) scan a QR to log in and save credentials, then exit")
+    .option("--cwd <dir>", "directory hara operates in per message (default: ~/.hara/workspace)")
+    .action(async (opts) => {
+    const mod = await import("./gateway/serve.js");
+    if (opts.platform === "weixin" && opts.login) {
+        await mod.weixinLogin();
+        return;
+    }
+    const cwd = opts.cwd ? (await import("node:path")).resolve(opts.cwd) : undefined; // undefined → ~/.hara/workspace
+    await mod.runGateway({ cwd, platform: opts.platform });
+});
 program
     .command("export [session]")
     .description("export a session to a Markdown transcript (default: the latest in this directory)")
@@ -1220,7 +1319,9 @@ program.action(async (opts) => {
     const cfg = loadConfig({ profile: opts.profile });
     if (opts.model)
         cfg.model = opts.model;
-    const provider0 = await buildProvider(cfg);
+    const provider0 = await withRouting(await buildProvider(cfg), cfg);
+    const fallbackProvider = provider0 && cfg.fallbackModel && cfg.fallbackModel !== cfg.model ? await buildProvider({ ...cfg, model: cfg.fallbackModel, baseURL: cfg.fallbackBaseURL ?? cfg.baseURL, apiKey: cfg.fallbackApiKey ?? cfg.apiKey }) : null;
+    const fbOpt = fallbackProvider ? { provider: fallbackProvider } : undefined; // app-failover for the main chat turns
     if (!provider0) {
         // First-run friendliness: offer the setup wizard instead of just erroring (interactive TTY only).
         if (stdin.isTTY && !opts.print) {
@@ -1237,8 +1338,10 @@ program.action(async (opts) => {
         process.exit(1);
     }
     let provider = provider0;
-    if (cfg.provider === "hara-gateway")
+    if (cfg.provider === "hara-gateway") {
         void heartbeat(); // fleet visibility — fire-and-forget, never blocks startup
+        void syncOrgRoles(); // refresh governed org-role bundle (B3) in the background; best-effort, never blocks
+    }
     const cwd = cfg.cwd;
     let approval = opts.yes ? "full-auto" : (opts.approval || cfg.approval);
     let currentTurn = null; // set during a running turn so Esc can abort it
@@ -1256,16 +1359,83 @@ program.action(async (opts) => {
     // one-shot
     if (opts.print) {
         const projectContext = loadAgentsMd(cwd) || undefined;
-        const history = [{ role: "user", content: expandMentions(String(opts.print), cwd) }];
+        // Vision sidecar for headless runs (gateway/cron): without it the computer tool's screenshots come back
+        // "configure a vision model" even when one is set, leaving a headless agent blind. Mirrors the interactive
+        // describeScreenshot — a configured visionModel, else the main model if it's vision-capable.
+        const describeImage = async (path, hint) => {
+            const cap = classifyVision(cfg.provider, cfg.model, cfg.modelVision);
+            const vp = cfg.visionModel
+                ? ((await buildProvider({ ...cfg, model: cfg.visionModel, baseURL: cfg.visionBaseURL ?? cfg.baseURL, apiKey: cfg.visionApiKey ?? cfg.apiKey })) ?? null)
+                : cap === "vision"
+                    ? provider
+                    : null;
+            if (!vp)
+                return "";
+            try {
+                return await describeImages(vp, [{ path, mediaType: "image/png" }], { system: SCREENSHOT_SYSTEM, hint });
+            }
+            catch {
+                return "";
+            }
+        };
+        // Headless session continuity: --resume <id> / --continue loads the session, appends this prompt, and
+        // saves it back — so `hara -p … --resume <id>` continues a thread (used by cron, scripts, the chat gateway).
+        // Plain `hara -p` stays stateless. A --resume id with no match is created WITH that id (stable per caller).
+        let meta = null;
+        const history = [];
+        if (opts.resume || opts.continue) {
+            const rid = opts.resume ? (resolveSessionId(opts.resume) ?? opts.resume) : latestForCwd(cwd)?.meta.id;
+            const prior = rid ? loadSession(rid) : null;
+            if (prior?.history)
+                history.push(...prior.history);
+            meta = prior?.meta ?? { id: rid ?? newSessionId(), cwd, provider: cfg.provider, model: cfg.model, title: "", createdAt: new Date().toISOString(), updatedAt: "" };
+        }
+        // Inbound images (gateway): the platform downloaded the user's photo(s) and passed their paths via env.
+        // Let the agent actually SEE them — attached inline for a vision-capable main model, else described via the
+        // visionModel sidecar and folded into the message (text-only models can't take image blocks).
+        const userText = expandMentions(String(opts.print), cwd);
+        const inboundImgs = (process.env.HARA_GATEWAY_IMAGES ?? "")
+            .split("\n")
+            .map((s) => s.trim())
+            .filter((p) => p && existsSync(p))
+            .map((p) => ({ path: p, mediaType: mediaTypeFor(p) ?? "image/jpeg" }));
+        if (inboundImgs.length && classifyVision(cfg.provider, cfg.model, cfg.modelVision) === "vision") {
+            history.push({ role: "user", content: userText, images: inboundImgs }); // native vision → inline
+        }
+        else if (inboundImgs.length && cfg.visionModel) {
+            let desc = "";
+            try {
+                const vp = await buildProvider({ ...cfg, model: cfg.visionModel, baseURL: cfg.visionBaseURL ?? cfg.baseURL, apiKey: cfg.visionApiKey ?? cfg.apiKey });
+                if (vp)
+                    desc = await describeImages(vp, inboundImgs);
+            }
+            catch {
+                /* describe is best-effort — fall back to the marker-only text */
+            }
+            const n = inboundImgs.length;
+            history.push({
+                role: "user",
+                content: desc ? `${userText}\n\n[${n} image${n > 1 ? "s" : ""} the user sent — described by ${cfg.visionModel}]\n${desc}` : userText,
+            });
+        }
+        else {
+            history.push({ role: "user", content: userText });
+        }
         await runAgent(history, {
             provider,
-            ctx: { cwd, sandbox, spawn: (t, role) => runSubagent(cfg, provider, cwd, sandbox, projectContext, stats, t, role) },
+            ctx: { cwd, sandbox, spawn: (t, role) => runSubagent(cfg, provider, cwd, sandbox, projectContext, stats, t, role), describeImage },
             approval: "full-auto",
             confirm: async () => true,
             projectContext,
             memory: memoryDigest(cwd),
             stats,
         });
+        if (meta) {
+            // Long-session safety: auto-compact before saving so a long chat/cron thread never overflows context.
+            // Silent (no-op notify) in headless mode so nothing leaks into a captured -p reply. Opt-out via config.
+            await maybeAutoCompact(provider, history, meta, stats, cfg, () => { });
+            saveSession(meta, history); // persist when resuming/continuing; plain -p stays stateless
+        }
         if (stats.input || stats.output)
             out(statusLine(cfg.model, stats.input, stats.output) + "\n");
         await closeMcp();
@@ -1533,31 +1703,52 @@ program.action(async (opts) => {
                 out(c.green(`↩ reverted: ${r.files.join(", ")}\n`));
             },
         },
+        {
+            name: "context",
+            desc: "show what's filling the context window (token breakdown by category)",
+            run: () => void out(formatContextReport(history, cfg.model) + "\n"),
+        },
+        {
+            name: "rewind",
+            desc: "fork the conversation back to an earlier turn: /rewind (list) · /rewind <n> (files unchanged)",
+            run: (a) => {
+                const arg = (a ?? "").trim();
+                if (!arg) {
+                    const turns = userTurnPreviews(history);
+                    return void out(turns.length ? "Recent turns (newest first) — `/rewind <n>` forks from before it (files unchanged):\n" + turns.map((t) => `  ${t.n}. ${t.preview}`).join("\n") + "\n" : c.dim("(nothing to rewind)\n"));
+                }
+                const nh = rewindTo(history, Number(arg));
+                if (!nh)
+                    return void out(c.dim(`(no such turn: ${arg})\n`));
+                history.length = 0;
+                history.push(...nh);
+                saveSession(meta, history);
+                out(c.green(`(rewound — dropped the last ${arg} turn(s); ${history.length} messages kept. Files are unchanged. Type your next message.)\n`));
+            },
+        },
+        {
+            name: "checkpoint",
+            desc: "file-state checkpoints: /checkpoint (list) · /checkpoint restore <n> (revert files to a checkpoint)",
+            run: (a) => {
+                const parts = (a ?? "").trim().split(/\s+/);
+                const cps = listCheckpoints(cwd);
+                if (parts[0] !== "restore") {
+                    return void out(cps.length ? "File checkpoints (newest first) — `/checkpoint restore <n>` reverts files to it:\n" + cps.map((cp, i) => `  ${i + 1}. ${cp.sha}  ${cp.label}`).join("\n") + "\n" : c.dim("(no checkpoints yet — taken before each turn when fileCheckpoints is on)\n"));
+                }
+                const cp = cps[Number(parts[1]) - 1];
+                if (!cp)
+                    return void out(c.dim(`(no checkpoint ${parts[1] ?? ""})\n`));
+                const k = restoreCheckpoint(cwd, cp.sha);
+                out(k == null ? c.red("(restore failed)\n") : c.green(`(restored ${k} file(s) to ${cp.sha} — '${cp.label}'; prior state snapshotted too)\n`));
+            },
+        },
         {
             name: "compact",
             desc: "summarize the conversation so far to free up context",
             run: async () => {
-                if (history.length < 2)
-                    return void out(c.dim("(nothing to compact)\n"));
                 out(c.dim("Compacting…\n"));
-                const r = await provider.turn({
-                    system: COMPACT_SYSTEM,
-                    history: [...history, { role: "user", content: "Summarize our conversation so far per the instructions." }],
-                    tools: [],
-                    onText: () => { },
-                });
-                if (r.stop === "error")
-                    return void out(c.red(`(compact failed: ${r.errorMsg})\n`));
-                const summary = r.text.trim();
-                if (!summary)
-                    return void out(c.dim("(compact produced nothing)\n"));
-                meta.workingSet = workingSetFromSummary(summary); // survives the history wipe + injects next turns
-                history.length = 0;
-                history.push({ role: "user", content: `Summary of our conversation so far (continue from here):\n\n${summary}` });
-                stats.input += r.usage?.input ?? 0;
-                stats.output += r.usage?.output ?? 0;
-                saveSession(meta, history);
-                out(c.green(`(compacted — ${summary.length} chars; context replaced with the summary)\n`));
+                const summary = await compactConversation(provider, history, meta, stats);
+                out(summary ? c.green(`(compacted — ${summary.length} chars; context replaced with the summary)\n`) : c.dim("(nothing to compact / compact failed)\n"));
             },
         },
         {
@@ -1771,6 +1962,33 @@ program.action(async (opts) => {
                         saveSession(meta, history);
                         return void h.sink.notice(`(renamed → ${meta.title})`);
                     }
+                    if (nm === "context")
+                        return void h.sink.notice(formatContextReport(history, cfg.model));
+                    if (nm === "rewind") {
+                        if (!arg) {
+                            const turns = userTurnPreviews(history);
+                            return void h.sink.notice(turns.length ? "Recent turns (newest first) — /rewind <n> (files unchanged):\n" + turns.map((t) => `  ${t.n}. ${t.preview}`).join("\n") : "(nothing to rewind)");
+                        }
+                        const nh = rewindTo(history, Number(arg));
+                        if (!nh)
+                            return void h.sink.notice(`(no such turn: ${arg})`);
+                        history.length = 0;
+                        history.push(...nh);
+                        saveSession(meta, history);
+                        return void h.sink.notice(`(rewound — kept ${history.length} messages; files unchanged. Type your next message.)`);
+                    }
+                    if (nm === "checkpoint") {
+                        const parts = arg.split(/\s+/);
+                        const cps = listCheckpoints(cwd);
+                        if (parts[0] !== "restore") {
+                            return void h.sink.notice(cps.length ? "File checkpoints (newest first) — /checkpoint restore <n>:\n" + cps.map((cp, i) => `  ${i + 1}. ${cp.sha}  ${cp.label}`).join("\n") : "(no checkpoints yet)");
+                        }
+                        const cp = cps[Number(parts[1]) - 1];
+                        if (!cp)
+                            return void h.sink.notice(`(no checkpoint ${parts[1] ?? ""})`);
+                        const k = restoreCheckpoint(cwd, cp.sha);
+                        return void h.sink.notice(k == null ? "(restore failed)" : `(restored ${k} file(s) to ${cp.sha} — '${cp.label}')`);
+                    }
                     if (nm === "compact") {
                         if (history.length < 2)
                             return void h.sink.notice("(nothing to compact)");
@@ -1794,25 +2012,8 @@ program.action(async (opts) => {
                                 /* flush is best-effort */
                             }
                         }
-                        const cr = await provider.turn({
-                            system: COMPACT_SYSTEM,
-                            history: [...history, { role: "user", content: "Summarize our conversation so far per the instructions." }],
-                            tools: [],
-                            onText: () => { },
-                        });
-                        if (cr.stop === "error")
-                            return void h.sink.notice(`(compact failed: ${cr.errorMsg})`);
-                        const summary = cr.text.trim();
-                        if (!summary)
-                            return void h.sink.notice("(compact produced nothing)");
-                        meta.workingSet = workingSetFromSummary(summary);
-                        history.length = 0;
-                        history.push({ role: "user", content: `Summary of our conversation so far (continue from here):\n\n${summary}` });
-                        stats.input += cr.usage?.input ?? 0;
-                        stats.output += cr.usage?.output ?? 0;
-                        h.sink.usage(cr.usage?.input ?? 0, cr.usage?.output ?? 0);
-                        saveSession(meta, history);
-                        return void h.sink.notice(`(compacted — kept ${meta.workingSet.length} working-memory notes)`);
+                        const summary = await compactConversation(provider, history, meta, stats);
+                        return void h.sink.notice(summary ? `(compacted — kept ${meta.workingSet?.length ?? 0} working-memory notes)` : "(nothing to compact / compact failed)");
                     }
                     if (nm === "sessions") {
                         const ms = listSessions();
@@ -1977,6 +2178,8 @@ program.action(async (opts) => {
                 const userContent = (recalledContext ? `${recalledContext}\n\n---\n\n` : "") + expandMentions(line, cwd) + (ri.extraText ?? "");
                 recalledContext = "";
                 history.push({ role: "user", content: userContent, ...(ri.attach?.length ? { images: ri.attach } : {}) });
+                if (cfg.fileCheckpoints)
+                    checkpoint(cwd, line.slice(0, 80)); // shadow-git snapshot before the turn mutates
                 const beforeIn = stats.input;
                 const beforeOut = stats.output;
                 await runAgent(history, {
@@ -1990,6 +2193,7 @@ program.action(async (opts) => {
                     stats,
                     signal: h.signal,
                     pendingInput,
+                    fallback: fbOpt,
                 });
                 if (!meta.title) {
                     meta.title = await nameSession(provider, history);
@@ -1998,6 +2202,7 @@ program.action(async (opts) => {
                 h.sink.usage(stats.input - beforeIn, stats.output - beforeOut);
                 notifyDone(cfg.notify, { message: meta.title || "turn complete", elapsedMs: Date.now() - turnStart });
                 saveSession(meta, history);
+                await maybeAutoCompact(provider, history, meta, stats, cfg, (m) => h.sink.notice(m));
             },
         });
         await closeMcp();
@@ -2042,10 +2247,12 @@ program.action(async (opts) => {
         const userContent = (recalledContext ? `${recalledContext}\n\n---\n\n` : "") + expandMentions(line, cwd);
         recalledContext = "";
         history.push({ role: "user", content: userContent });
+        if (cfg.fileCheckpoints)
+            checkpoint(cwd, userContent.slice(0, 80)); // shadow-git snapshot before the turn mutates
         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 });
+            await runAgent(history, { provider, ctx: { cwd, sandbox, spawn }, approval, confirm, autoApprove, projectContext, memory: buildMemory(), stats, signal: currentTurn.signal, fallback: fbOpt });
         }
         catch (e) {
             out(c.red(`\n[error] ${e.message}\n`));
@@ -2068,9 +2275,11 @@ program.action(async (opts) => {
             out(statusLine(cfg.model, stats.input, stats.output) + "\n\n");
         }
         saveSession(meta, history);
-        const ctxPct = bar.ctxPctFor(cfg.model, stats.lastInput ?? 0);
-        if (ctxPct >= 80)
-            out(c.yellow(`  ⚠ context ${ctxPct}% full — /compact to summarize, or /reset to clear\n`));
+        if (!(await maybeAutoCompact(provider, history, meta, stats, cfg, (m) => out(c.dim(`${m}\n`))))) {
+            const ctxPct = bar.ctxPctFor(cfg.model, stats.lastInput ?? 0);
+            if (ctxPct >= 80)
+                out(c.yellow(`  ⚠ context ${ctxPct}% full — /compact to summarize, or /clear to reset\n`));
+        }
     }
     bar.uninstall();
     rl.close();

package/dist/org/roles.js

@@ -12,6 +12,12 @@ export function rolesDir(cwd) {
 export function globalRolesDir() {
     return join(homedir(), ".hara", "roles");
 }
+/** Org-pushed roles (B-end): the digital-employee bundle synced from hara-control's `/v1/roles` into
+ *  `~/.hara/org-roles/*.md` (see org-fleet/enroll.ts syncOrgRoles). A managed baseline — above
+ *  third-party plugins, but a dev's own global/project roles still win. */
+export function orgRolesDir() {
+    return join(homedir(), ".hara", "org-roles");
+}
 /** Claude-Code subagents (`.claude/agents/*.md`) — consumed for ecosystem interop (project scope). */
 export function claudeAgentsDir(cwd) {
     return join(findProjectRoot(cwd), ".claude", "agents");
@@ -62,8 +68,8 @@ export function subagentToolFilter(role, isReadonly) {
 }
 export function loadRoles(cwd) {
     const byId = new Map();
-    // lowest→highest precedence: plugins < global < .claude/agents < .hara/roles (project wins, same as memory/config)
-    for (const dir of [...pluginRoleDirs(), globalRolesDir(), claudeAgentsDir(cwd), rolesDir(cwd)]) {
+    // lowest→highest precedence: plugins < org(B-end push) < global < .claude/agents < .hara/roles (project wins)
+    for (const dir of [...pluginRoleDirs(), orgRolesDir(), globalRolesDir(), claudeAgentsDir(cwd), rolesDir(cwd)]) {
         if (!existsSync(dir))
             continue;
         for (const f of readdirSync(dir)) {

package/dist/org-fleet/enroll.js

@@ -7,10 +7,12 @@
 // Protocol (what `hara-control` implements on the other end):
 //   POST {gateway}/v1/enroll      {code, device:{name,os,hara_version}} -> {device_token, device_id, model, base_url?}
 //   POST {gateway}/v1/heartbeat   Bearer <device_token> {device_id, name, os, hara_version} -> 200/204
+//   GET  {gateway}/v1/roles       Bearer <device_token> -> {version, org_policy, roles:[…]}  (B3 digital-employee push-down)
 //   POST {gateway}/v1/chat/completions  (OpenAI-compatible; the normal agent traffic, Bearer <device_token>)
 import { homedir, hostname, platform } from "node:os";
 import { join } from "node:path";
 import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync, rmSync } from "node:fs";
+import { orgRolesDir } from "../org/roles.js";
 const orgPath = () => join(homedir(), ".hara", "org.json");
 const deviceInfo = () => ({ name: hostname(), os: platform(), hara_version: process.env.HARA_BUILD_VERSION ?? "dev" });
 /** The effective OpenAI-compatible base URL for an enrollment (explicit, else <gatewayUrl>/v1). */
@@ -92,3 +94,50 @@ export async function heartbeat(signal) {
         return false;
     }
 }
+/** Render one bundle role into the markdown frontmatter the CLI role loader expects
+ *  (src/org/roles.ts parseFrontmatter): name/description/owns/rejects/model/allowTools/denyTools, body=system. */
+function renderRoleMd(r) {
+    const fm = ["---", `name: ${r.name}`];
+    if (r.description)
+        fm.push(`description: ${r.description}`);
+    if (r.owns?.length)
+        fm.push(`owns: [${r.owns.join(", ")}]`);
+    if (r.rejects?.length)
+        fm.push(`rejects: [${r.rejects.join(", ")}]`);
+    if (r.model)
+        fm.push(`model: ${r.model}`);
+    if (r.allow_tools?.length)
+        fm.push(`allowTools: [${r.allow_tools.join(", ")}]`); // snake_case wire → camelCase fm
+    if (r.deny_tools?.length)
+        fm.push(`denyTools: [${r.deny_tools.join(", ")}]`);
+    fm.push("---", "", (r.system || "").trim(), "");
+    return fm.join("\n");
+}
+/** Pull this device's governed role bundle from the control plane and materialize it into
+ *  `~/.hara/org-roles/*.md` — a managed precedence layer below the dev's own global/project roles
+ *  (see src/org/roles.ts loadRoles). The org bundle is AUTHORITATIVE: the dir is wiped and rewritten on
+ *  every sync, so a server-side revoke/rename actually removes the local role. Best-effort: never throws;
+ *  returns the count of roles written (0 on any failure / not enrolled / empty bundle). */
+export async function syncOrgRoles(signal) {
+    const e = loadEnrollment();
+    if (!e)
+        return 0;
+    try {
+        const res = await fetch(`${e.gatewayUrl}/v1/roles`, { signal, headers: { authorization: `Bearer ${e.deviceToken}` } });
+        if (!res.ok)
+            return 0;
+        const bundle = (await res.json());
+        const roles = Array.isArray(bundle.roles) ? bundle.roles.filter((r) => r && r.name && r.system) : [];
+        const dir = orgRolesDir();
+        rmSync(dir, { recursive: true, force: true }); // authoritative replace
+        mkdirSync(dir, { recursive: true });
+        for (const r of roles)
+            writeFileSync(join(dir, `${r.name}.md`), renderRoleMd(r), "utf8");
+        // org policy sidecar (model/tool/approval floors the CLI enforces; skipped by the .md-only role loader)
+        writeFileSync(join(dir, "_policy.json"), JSON.stringify({ version: bundle.version ?? 0, org_policy: bundle.org_policy ?? {} }, null, 2) + "\n", "utf8");
+        return roles.length;
+    }
+    catch {
+        return 0;
+    }
+}

package/dist/sandbox.js

@@ -33,24 +33,27 @@ let warnedUnsandboxed = false; // emit the "macOS-only" notice at most once per
  * Streams output via `opts.onData` while capturing it for the resolved value.
  * Resolves on exit 0; rejects (with `.stdout`/`.stderr`/`.code`) on nonzero exit or timeout.
  */
-export function runShell(command, cwd, mode, opts) {
-    let cmd;
-    let args;
+/** Build the (sandboxed, when supported) argv for a shell command — shared by runShell + background jobs
+ *  so the seatbelt write-confinement is identical for both. */
+export function shellCommand(command, cwd, mode) {
     if (mode !== "off" && platform() === "darwin") {
         const dir = mkdtempSync(join(tmpdir(), "hara-sb-"));
         const profileFile = join(dir, "policy.sb");
         writeFileSync(profileFile, seatbeltProfile(cwd, mode));
-        cmd = "sandbox-exec";
-        args = ["-f", profileFile, "/bin/bash", "-lc", command];
+        return { cmd: "sandbox-exec", args: ["-f", profileFile, "/bin/bash", "-lc", command] };
     }
-    else {
-        if (mode !== "off" && !warnedUnsandboxed) {
-            warnedUnsandboxed = true;
-            process.stderr.write(`hara: --sandbox ${mode} is macOS-only — the shell runs UNSANDBOXED on ${platform()}.\n`);
-        }
-        cmd = "/bin/sh";
-        args = ["-c", command];
+    maybeWarnUnsandboxed(mode);
+    return { cmd: "/bin/sh", args: ["-c", command] };
+}
+/** One-time-per-process notice that --sandbox is a no-op off macOS (covers every entry point). */
+export function maybeWarnUnsandboxed(mode) {
+    if (mode !== "off" && !warnedUnsandboxed) {
+        warnedUnsandboxed = true;
+        process.stderr.write(`hara: --sandbox ${mode} is macOS-only — the shell runs UNSANDBOXED on ${platform()}.\n`);
     }
+}
+export function runShell(command, cwd, mode, opts) {
+    const { cmd, args } = shellCommand(command, cwd, mode);
     return new Promise((resolve, reject) => {
         const child = spawn(cmd, args, { cwd });
         let stdout = "";

package/dist/search/semindex.js

@@ -7,6 +7,7 @@ import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { findProjectRoot } from "../context/agents-md.js";
 import { listProjectFiles, walkFiles, isProbablyBinary, fileSize } from "../fs-walk.js";
+import { zvecBuild, zvecQueryIds } from "./zvec-store.js";
 // Same code/text extensions codebase_search ranks lexically — keep the two walks in sync.
 const CODE_RE = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|c|h|cc|cpp|hpp|cs|swift|scala|sh|bash|sql|md|mdx|json|ya?ml|toml|html|css|scss|less|vue|svelte|astro|tf|proto|graphql|gql|gradle|txt)$/i;
 /** Index location — repo index lives in the project (gitignore it); the rest are global. Derived/rebuildable. */
@@ -116,6 +117,8 @@ export async function buildIndex(name, chunks, embed, cwd, model = "embed") {
     if (!existsSync(join(dir, ".gitignore")))
         writeFileSync(join(dir, ".gitignore"), "*\n", "utf8");
     writeFileSync(p, JSON.stringify({ model, items }), "utf8");
+    // Build a zvec ANN index alongside the JSON cache (best-effort; queryIndex prefers it for retrieval).
+    await zvecBuild(name, items.map((it) => ({ id: it.id, vec: it.vec })), cwd);
     return { total: items.length, embedded: toEmbed.length, reused };
 }
 export function indexExists(name, cwd) {
@@ -192,6 +195,21 @@ export async function queryIndex(name, query, embed, cwd, k = 6) {
     const [qv] = await embed([query]);
     if (!qv)
         return [];
+    // Prefer the zvec ANN index for candidate retrieval; re-rank candidates by EXACT cosine from the JSON
+    // store (identical score semantics to the brute-force path). Fall back to full brute-force if zvec is
+    // unavailable / has no index / errors.
+    const ids = await zvecQueryIds(name, qv, cwd, k);
+    if (ids?.length) {
+        const byId = new Map(idx.items.map((it) => [it.id, it]));
+        const hits = ids
+            .map((id) => byId.get(id))
+            .filter((it) => Boolean(it))
+            .map((it) => ({ file: it.file, source: it.source, text: it.text, score: cosine(qv, it.vec) }))
+            .sort((a, b) => b.score - a.score)
+            .slice(0, k);
+        if (hits.length)
+            return hits;
+    }
     return idx.items
         .map((it) => ({ file: it.file, source: it.source, text: it.text, score: cosine(qv, it.vec) }))
         .sort((a, b) => b.score - a.score)