@nanhara/hara 0.62.0 → 0.70.0

package/CHANGELOG.md

@@ -5,6 +5,100 @@ All notable changes to `@nanhara/hara`.
 > Versioning (pre-1.0, SemVer-style): the **minor** (middle) number bumps for a **new feature**; the
 > **patch** (last) number bumps for **optimizations/fixes of existing features**.
 
+## 0.70.0 — unreleased (B-end: devices pull their governed org-role bundle)
+
+- An enrolled device now **syncs its digital-employee roles from hara-control** — `GET {gateway}/v1/roles`
+  (Bearer device token) returns the governed bundle the control plane resolved for this device's
+  person/team, and hara materializes it into `~/.hara/org-roles/*.md`. This closes the B3 gap where the
+  server could resolve+govern roles but the CLI never consumed them (it only read local `.hara/roles/`).
+- **Precedence layer** (in `loadRoles`): `plugins < org(B-end push) < global < .claude/agents < project`
+  — the org baseline sits above third-party plugins, but a dev's own global/project roles still win, so
+  pushed roles are a managed default, not a lock. (Org policy can tighten this later.)
+- **Authoritative replace**: the org bundle owns `~/.hara/org-roles/` — each sync wipes and rewrites it,
+  so a server-side role revoke/rename actually removes the local file. A `_policy.json` sidecar carries
+  the org governance floor (model/tool/approval) for later enforcement.
+- Wired on `hara enroll` (reports the count) and best-effort in the background on startup when
+  `provider=hara-gateway` (alongside the heartbeat). Never throws / never blocks — returns 0 on any
+  failure or when not enrolled. snake_case wire fields (`allow_tools`/`deny_tools`) map to the CLI's
+  `allowTools`/`denyTools` frontmatter. New `syncOrgRoles()` in `src/org-fleet/enroll.ts` + test.
+
+## 0.69.1 — unreleased (@file expands inline, not appended at the bottom)
+
+- `@path` mentions now expand **in place** — the referenced file/dir content lands exactly where it's
+  written, so "compare `@a.ts` with `@b.ts`" reads in context instead of keeping the bare `@a.ts`
+  tokens and dumping both files in a block at the very end. A repeated mention keeps the bare `@path`
+  the second time (no double-inlining); a non-readable ref is left as typed. Labels ("Referenced file
+  `x`:") and the image/dir handling are unchanged — only the position moved.
+
+## 0.69.0 — unreleased (real local vector store via zvec)
+
+- Local semantic search now uses **zvec** (`@zvec/zvec`, an in-process native vector DB) for ANN
+  retrieval, replacing the brute-force-cosine scan as the query path. zvec was previously referenced
+  only in comments as the "scale-up path"; it's now actually wired (it ships a darwin-arm64/linux
+  prebuilt, added as an **optionalDependency**).
+- Design keeps the JSON store as the durable embedding cache + SSOT for hit text, and recomputes the
+  cosine **score from the JSON vectors** after zvec returns candidate ids — so ranking/threshold
+  semantics are byte-identical to before (no change to `hybrid.ts`), zvec just does fast candidate
+  retrieval. Build writes the zvec index alongside the JSON cache (`~/.hara/index/<name>.zvec`).
+- **Graceful fallback preserved**: if `@zvec/zvec` is absent or its native binding fails to load (a
+  platform with no prebuilt), `queryIndex` falls back to the JSON brute-force — so installs without
+  the binding keep working. Lexical remains the zero-dep floor when no embedder is configured at all.
+- New `src/search/zvec-store.ts` (lazy load · read-only open for queries · best-effort build) + test.
+
+## 0.68.0 — unreleased (run hara in Docker)
+
+- **Dockerfile** — run hara in a container against any mounted repo, no Node install needed, and as an
+  isolated/ephemeral environment (handy for CI). Multi-stage build → a slim runtime that still ships a
+  shell + `git` + `ripgrep` (the bash/search tools need them; a distroless image would break them).
+  `docker run --rm -v "$PWD:/workspace" -e HARA_API_KEY=… ghcr.io/hara-cli/hara -p "…"`.
+- **Release pipeline** now also builds + pushes a multi-arch (amd64/arm64) image to
+  `ghcr.io/hara-cli/hara` on a version tag, alongside the existing standalone binaries — so the Docker
+  and binary distributions stay in lockstep. (Single-binary distribution shipped in 0.60.0; this
+  rounds out "install hara any way you like": npm · binary · Docker.)
+
+## 0.67.0 — unreleased (bounded parallel concurrency)
+
+- hara already runs work in parallel — fan-out **`agent`** sub-agents, concurrent read-kind tools in a turn,
+  and `hara plan --parallel` waves — but with **no cap**: the model spawning 20 `agent` calls in one turn
+  started 20 LLM loops at once (provider rate-limits / resource thrash). Now a **bounded pool** (`mapLimit`)
+  caps in-flight parallelism to **8** by default (tunable via `HARA_MAX_CONCURRENCY`), matching cc-haha's
+  safeguard (it caps at 10). Excess work queues and runs as slots free; ordering + behavior otherwise
+  unchanged. Applied to the loop's read/agent batch and the parallel-plan wave.
+
+## 0.66.0 — unreleased (B-end: device enrollment + `hara-gateway` provider)
+
+- First slice of the **B-end** (fleets / control plane): `hara enroll <gateway-url> --code <code>` trades a
+  one-time code for a scoped, revocable **device token** (stored `0600` in `~/.hara/org.json`) and switches
+  hara to the new **`hara-gateway`** provider — an OpenAI-compatible client pointed at your org's gateway.
+  **The real provider key never touches the device** (it stays at the gateway). A heartbeat fires on start
+  for fleet visibility; `--status` / `--clear` manage it. The device↔gateway protocol (enroll / heartbeat /
+  OpenAI-compatible proxy) is documented in `docs/b-end.md` and **verified end-to-end against a stub control
+  plane**. The control-plane server (`hara-control`) + the LiteLLM data-plane are the next, separate increment.
+
+## 0.65.0 — unreleased (frontmatter-aware asset recall)
+
+- Asset/skill recall (`searchAssets`, behind `hara recall` / `/recall` / skill dedup) now **ranks by the
+  asset's declared dimensions** — a query word in the `title` or the frontmatter `tags`/`lang` counts more
+  than one buried in the body. The asset format already declared these (the scaffold seeds `tags`/`lang`);
+  retrieval now actually uses them. The base relevance score (distinct query words present) is unchanged,
+  so the dedup-before-save threshold is unaffected — this only improves *ordering*. (Studied codex + cc-haha:
+  both stay lexical + manual-file curation with no semantic search or auto-capture; hara's hybrid lexical+
+  opt-in-semantic recall over a unified skills/code-assets/memory corpus is already ahead.)
+
+## 0.64.0 — unreleased (session export)
+
+- **`hara export [session] [--out file]`** renders a saved session to a Markdown transcript — the header
+  (title/model/cwd/date), each turn (you / hara), tool calls inline, and tool results in collapsible
+  `<details>` blocks (capped). Default is the latest session in the current directory. For sharing a
+  decision, pasting into a PR, or archiving. Pure renderer (`src/export.ts`), unit-tested.
+
+## 0.63.0 — unreleased (first-run setup wizard)
+
+- **`hara setup`** — an interactive wizard (provider → optional base URL → API key → model) that writes
+  `~/.hara/config.json` (0600), so a new user doesn't have to know the individual `hara config set` keys.
+  It's also **auto-offered** when you start `hara` unconfigured ("Not authenticated — run setup now?")
+  instead of just erroring. TTY-only (scripts get a clear pointer to `hara config set`).
+
 ## 0.62.0 — unreleased (shell completions)
 
 - **`hara completions bash|zsh|fish`** prints a completion script (eval it in your shell rc) that

package/README.md

@@ -31,6 +31,16 @@ curl -fsSL https://raw.githubusercontent.com/hara-cli/hara/main/install.sh | sh
 
 Tab completion (optional): `eval "$(hara completions zsh)"` in your `~/.zshrc` (or `bash`/`fish`).
 
+Or in **Docker** — run hara against any repo without installing Node, and as an isolated/ephemeral
+environment (handy for CI):
+
+```bash
+docker run --rm -v "$PWD:/workspace" -e HARA_API_KEY=sk-... ghcr.io/hara-cli/hara -p "summarize this repo"
+# interactive TUI:
+docker run --rm -it -v "$PWD:/workspace" -e HARA_API_KEY=sk-... ghcr.io/hara-cli/hara
+# or build it yourself: docker build -t hara . && docker run --rm -v "$PWD:/workspace" -e HARA_API_KEY=sk-... hara
+```
+
 Or from source:
 
 ```bash
@@ -59,7 +69,9 @@ hara -p "summarize @README.md and list any TODOs"
 
 ## Setup
 
-hara is **multi-provider** — pick a provider + key.
+The fastest path is **`hara setup`** — an interactive wizard for provider + key + model (it also runs
+automatically the first time you start `hara` unconfigured). Or configure it yourself — hara is
+**multi-provider**:
 
 **Anthropic (default)**
 ```bash
@@ -185,7 +197,7 @@ only changed files re-embed (a full repo rebuild that takes ~a minute re-runs in
 `hara config set computerUse read|click|full` and allowlist apps with `hara config set computerApps "App, …"`. Guarded
 by the tier, the frontmost-app allowlist, a dangerous-key blocklist, and a once-per-session grant. Screenshots are read via your
 vision model into **actionable** output — interactive elements + positions (pass `focus` to target what you're after) — so even a text-only main model can click.
-**Sessions**: conversations are saved automatically — `-c` / `--resume <id>` to continue, `hara sessions` to list.
+**Sessions**: conversations are saved automatically — `-c` / `--resume <id>` to continue, `hara sessions` to list, `hara export [id] [--out file]` to render one as a Markdown transcript.
 **MCP**: add an `mcpServers` map to config (global or project `.hara/config.json`); their tools appear to the agent as `mcp__<server>__<tool>`. hara can also **be** an MCP server — `hara mcp` exposes its read/search tools (esp. **`codebase_search`**) over stdio so other clients (Claude Desktop, Cursor, another hara) can use them; read-only by default (`HARA_MCP_TOOLS` to override).
 **Vim mode**: `hara config set vimMode true` makes the prompt modal — Esc → normal, `i/a/A/I` insert, `h l 0 $ w b e` motions, `x D C dd cw p` edits. Off by default.
 **Scheduled tasks**: `hara cron add "0 9 * * 1-5" "<task>"` (or `"every 30m"`, `"in 2h"`) runs a task on a schedule — each run is a fresh hara session. `hara cron install` wires a per-minute tick into launchd/crontab (no daemon); `--org` routes through the role org. Manage with `hara cron list/run/enable/disable/remove/logs`.
@@ -205,7 +217,7 @@ the diff and either approves or sends it back with fixes — looping implement
 (or `--rounds N`). Add **`--commit`** and it commits the approved result with an AI-written message (guarded
 to a clean start tree; a review that doesn't pass leaves the work uncommitted). The
 **`agent`** tool spawns **parallel read-only sub-agents** for fan-out — analyze / review / search
-several things at once (each can take a `role`).
+several things at once (each can take a `role`), bounded to 8 concurrent (`HARA_MAX_CONCURRENCY`).
 
 Beyond routing, **`hara plan "<task>"`** makes the org *plan*: it decomposes the task into atoms,
 sequences them as a DAG, and executes each step (optionally routed to a role) behind a per-step
@@ -231,7 +243,7 @@ turn, or **`/undo`** to revert the last edit. In-session **`/diff`**, **`/review
 
 ### Roadmap
 
-**Shipped:** ink TUI · plan mode · persistent memory + self-evolution · atomization planner · parallel plan atoms · **multi-role review chains** · parallel sub-agents · MCP client *and* server · **scheduled tasks (`hara cron`)** · **single-binary distribution** · `/compact` context management.
+**Shipped:** ink TUI · plan mode · persistent memory + self-evolution · atomization planner · parallel plan atoms · **multi-role review chains** · parallel sub-agents · MCP client *and* server · **scheduled tasks (`hara cron`)** · **single-binary distribution** · **Docker image** · `/compact` context management.
 **Next:** SSOT data authority · an enterprise control-plane (fleet + central token management).
 
 ## Security

package/dist/agent/loop.js

@@ -5,6 +5,7 @@ import { activity } from "../activity.js";
 import { makeRenderer } from "../md.js";
 import { skillsDigest } from "../skills/skills.js";
 import { runHooks } from "../hooks.js";
+import { mapLimit, maxParallel } from "../concurrency.js";
 /** Whether a tool call needs user confirmation under the given approval mode. */
 export function needsConfirm(kind, mode) {
     if (kind === "read")
@@ -181,21 +182,25 @@ export async function runAgent(history, opts) {
                 activity.dec();
             }
         };
-        let batch = [];
+        let batch = []; // indices of pending read-kind tools (run concurrently, capped)
+        const flush = async () => {
+            if (!batch.length)
+                return;
+            const idx = batch;
+            batch = [];
+            await mapLimit(idx, maxParallel(), (i) => runOne(i, plans[i])); // bounded fan-out (e.g. 20 parallel agents → 8 at a time)
+        };
         for (let i = 0; i < plans.length; i++) {
             const p = plans[i];
             if (p.denied === undefined && p.tool?.kind === "read") {
-                batch.push(runOne(i, p)); // safe → accumulate to run concurrently
+                batch.push(i); // safe → accumulate to run concurrently
             }
             else {
-                if (batch.length) {
-                    await Promise.all(batch); // flush pending reads before an edit/exec
-                    batch = [];
-                }
+                await flush(); // flush pending reads before an edit/exec
                 await runOne(i, p);
             }
         }
-        await Promise.all(batch);
+        await flush();
         history.push({ role: "tool", results });
     }
 }

package/dist/concurrency.js

@@ -0,0 +1,22 @@
+// Bounded-concurrency map: run `fn` over `items` with at most `limit` in flight at once, preserving input
+// order in the results. Used to cap parallel sub-agents / read-tools / plan atoms so a wide fan-out (the
+// model spawning 20 `agent` calls in one turn) doesn't hammer the provider's rate limits or thrash the box.
+// cc-haha caps tool concurrency at 10; hara defaults to 8, tunable via HARA_MAX_CONCURRENCY.
+export function maxParallel() {
+    const n = Number(process.env.HARA_MAX_CONCURRENCY);
+    return Number.isInteger(n) && n >= 1 ? n : 8;
+}
+export async function mapLimit(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        for (;;) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            results[i] = await fn(items[i], i);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(Math.max(1, limit), items.length) }, worker));
+    return results;
+}

package/dist/config.js

@@ -10,6 +10,7 @@ const PROVIDER_DEFAULTS = {
     },
     "qwen-oauth": { model: "coder-model", envKey: "QWEN_OAUTH_TOKEN" },
     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 APPROVAL_MODES = ["suggest", "auto-edit", "full-auto"];

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/export.js

@@ -0,0 +1,43 @@
+const CAP = 4000; // per tool-result body, so a giant log doesn't bloat the transcript
+/** A session → Markdown: a header (title/model/cwd/date) then each turn (you / hara / tool results). */
+export function renderSessionMarkdown(data) {
+    const { meta, history } = data;
+    const out = [
+        `# ${meta.title || meta.id}`,
+        "",
+        `- **session** \`${meta.id}\``,
+        `- **model** ${meta.provider}:${meta.model}`,
+        `- **cwd** ${meta.cwd}`,
+        `- **created** ${meta.createdAt}`,
+        "",
+        "---",
+        "",
+    ];
+    for (const m of history) {
+        if (m.role === "user") {
+            const text = (m.content ?? "").trim();
+            if (text)
+                out.push("## 🧑 You", "", text, "");
+        }
+        else if (m.role === "assistant") {
+            const parts = [];
+            if (m.text?.trim())
+                parts.push(m.text.trim());
+            for (const tu of m.toolUses ?? []) {
+                const input = JSON.stringify(tu.input ?? {});
+                parts.push(`> 🔧 \`${tu.name}\`${input && input !== "{}" ? ` \`${input.length > 200 ? input.slice(0, 200) + "…" : input}\`` : ""}`);
+            }
+            if (parts.length)
+                out.push("## 🤖 hara", "", parts.join("\n\n"), "");
+        }
+        else {
+            for (const r of m.results ?? []) {
+                const body = String(r.content ?? "").trim();
+                if (!body)
+                    continue;
+                out.push(`<details><summary>↳ ${r.name}${r.isError ? " (error)" : ""}</summary>`, "", "```", body.length > CAP ? body.slice(0, CAP) + `\n…[${body.length - CAP} more chars]` : body, "```", "", "</details>", "");
+            }
+        }
+    }
+    return out.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+}

package/dist/index.js

@@ -18,6 +18,9 @@ import { runAgent } from "./agent/loop.js";
 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, syncOrgRoles } from "./org-fleet/enroll.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";
 import { addJob, removeJob, setEnabled, resolveJob, loadJobs, recordRun, logPath } from "./cron/store.js";
@@ -78,6 +81,12 @@ async function buildProvider(cfg) {
             return null;
         return createOpenAIProvider({ apiKey: auth.accessToken, baseURL: auth.baseURL, model: cfg.model, label: "qwen-oauth" });
     }
+    if (cfg.provider === "hara-gateway") {
+        const e = loadEnrollment();
+        if (!e)
+            return null; // not enrolled → `hara enroll`
+        return createOpenAIProvider({ apiKey: e.deviceToken, baseURL: gatewayBaseURL(e), model: cfg.model || e.model, label: "hara-gateway" });
+    }
     if (!cfg.apiKey)
         return null;
     if (cfg.provider === "anthropic") {
@@ -88,7 +97,38 @@ async function buildProvider(cfg) {
 function authHint(cfg) {
     if (cfg.provider === "qwen-oauth")
         return `Run ${c.bold("hara login qwen")} to authenticate.`;
-    return `Set ${c.bold(providerEnvKey(cfg.provider))} (or ${c.bold("HARA_API_KEY")}), or run ${c.bold("hara config set apiKey <key>")}.`;
+    return `Set ${c.bold(providerEnvKey(cfg.provider))} (or ${c.bold("HARA_API_KEY")}), or run ${c.bold("hara setup")}.`;
+}
+const SETUP_DEFAULT_MODEL = { anthropic: "claude-opus-4-8", qwen: "qwen-plus", openai: "gpt-4o-mini", "qwen-oauth": "coder-model" };
+/** Interactive first-run setup: pick a provider, (optional) base URL, API key, and model → ~/.hara/config.json. */
+async function runSetup() {
+    if (!stdin.isTTY) {
+        out(c.yellow("`hara setup` is interactive — run it in a terminal, or use `hara config set <key> <value>` in scripts.\n"));
+        return;
+    }
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        out(c.bold("hara setup") + c.dim(" — configure a provider, key, and model (Ctrl-C to cancel)\n\n"));
+        const provider = ((await rl.question(`Provider ${c.dim("anthropic / qwen / openai")} [anthropic]: `)).trim() || "anthropic").toLowerCase();
+        let baseURL = "";
+        if (provider === "qwen" || provider === "openai") {
+            baseURL = (await rl.question(`Base URL ${c.dim("(blank = default; set for an OpenAI-compatible endpoint, e.g. GLM/Kimi/DashScope)")}: `)).trim();
+        }
+        const envKey = providerEnvKey(provider);
+        const apiKey = (await rl.question(`API key ${c.dim(`(blank = use the ${envKey} env var)`)}: `)).trim();
+        const model = (await rl.question(`Model [${SETUP_DEFAULT_MODEL[provider] ?? "?"}]: `)).trim() || SETUP_DEFAULT_MODEL[provider] || "";
+        writeConfigValue("provider", provider);
+        if (baseURL)
+            writeConfigValue("baseURL", baseURL);
+        if (apiKey)
+            writeConfigValue("apiKey", apiKey);
+        if (model)
+            writeConfigValue("model", model);
+        out(c.green(`\n✓ saved to ${configPath()}\n`) + c.dim(`Check it with ${c.bold("hara doctor")}, then just run ${c.bold("hara")}.\n`));
+    }
+    finally {
+        rl.close();
+    }
 }
 async function runInit(provider, cwd, sandbox = "off") {
     const history = [{ role: "user", content: INIT_PROMPT }];
@@ -319,7 +359,7 @@ async function executePlan(plan, roles, o) {
             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)));
+            const results = await mapLimit(todo, maxParallel(), (atom) => executeAtom(atom, plan, done, roles, o)); // bounded
             todo.forEach((atom, i) => {
                 if (results[i]) {
                     done.push(atom);
@@ -696,6 +736,58 @@ program
     .command("doctor")
     .description("check your hara setup (provider / auth / model / node / assets / roles)")
     .action(() => out(runDoctor(loadConfig()) + "\n"));
+program
+    .command("setup")
+    .description("interactive first-run setup — pick a provider, API key, and model")
+    .action(runSetup);
+program
+    .command("enroll [gateway-url]")
+    .description("B-end: join a fleet — trade a one-time code for a device token (routes hara through your org's gateway; no provider key on this device)")
+    .option("--code <code>", "enrollment code from your hara-control admin")
+    .option("--status", "show the current enrollment")
+    .option("--clear", "remove the enrollment (revert to your own provider config)")
+    .action(async (gatewayUrl, opts) => {
+    if (opts.status) {
+        const e = loadEnrollment();
+        return void out(e ? c.green("enrolled") + c.dim(` · ${e.gatewayUrl} · device ${e.deviceId || "?"} · model ${e.model || "(gateway default)"} · since ${e.enrolledAt}\n`) : c.dim("Not enrolled — `hara enroll <gateway-url> --code <code>`.\n"));
+    }
+    if (opts.clear)
+        return void out(clearEnrollment() ? c.green("✓ enrollment cleared — set your own provider with `hara setup`.\n") : c.dim("(not enrolled)\n"));
+    if (!gatewayUrl)
+        return void out(c.red("usage: hara enroll <gateway-url> --code <code>   (or --status / --clear)\n"));
+    if (!opts.code)
+        return void out(c.red("Need --code <code> — ask your hara-control admin to issue an enrollment code.\n"));
+    try {
+        const e = await enrollDevice(gatewayUrl, opts.code);
+        writeConfigValue("provider", "hara-gateway");
+        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("export [session]")
+    .description("export a session to a Markdown transcript (default: the latest in this directory)")
+    .option("--out <file>", "write to a file instead of stdout")
+    .action((sessionArg, opts) => {
+    const data = sessionArg ? (() => { const id = resolveSessionId(sessionArg); return id ? loadSession(id) : null; })() : latestForCwd(process.cwd());
+    if (!data)
+        return void out(c.red(sessionArg ? `No session matching '${sessionArg}'.\n` : "No session for this directory — pass an id (see `hara sessions`).\n"));
+    const md = renderSessionMarkdown(data);
+    if (opts.out) {
+        writeFileSync(opts.out, md, "utf8");
+        out(c.green(`✓ wrote ${opts.out}`) + c.dim(` (${md.length} chars)\n`));
+    }
+    else {
+        out(md);
+    }
+});
 program
     .command("completions <shell>")
     .description("print a shell completion script: bash | zsh | fish (eval it in your shell rc)")
@@ -1133,10 +1225,25 @@ program.action(async (opts) => {
         cfg.model = opts.model;
     const provider0 = await buildProvider(cfg);
     if (!provider0) {
+        // First-run friendliness: offer the setup wizard instead of just erroring (interactive TTY only).
+        if (stdin.isTTY && !opts.print) {
+            const rl = createInterface({ input: stdin, output: stdout });
+            const ans = (await rl.question(c.yellow(`Not authenticated for '${cfg.provider}'. Run setup now? `) + c.dim("[Y/n] "))).trim().toLowerCase();
+            rl.close();
+            if (ans === "" || ans === "y" || ans === "yes") {
+                await runSetup();
+                out(c.dim(`\nThen run ${c.bold("hara")} to start.\n`));
+                process.exit(0);
+            }
+        }
         out(c.red(`Not authenticated for provider '${cfg.provider}'.\n`) + authHint(cfg) + "\n");
         process.exit(1);
     }
     let provider = provider0;
+    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

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

@@ -0,0 +1,143 @@
+// B-end device enrollment (the OSS client side of the fleet/control-plane story). A hara device joins a
+// fleet by exchanging a one-time enrollment code for a scoped, revocable DEVICE TOKEN — it never holds the
+// real provider key (that stays at the gateway). hara then points its OpenAI-compatible calls at the
+// gateway, which validates the token, maps it to an upstream key, and proxies. Heartbeats give the control
+// plane fleet visibility. Token + endpoint live in ~/.hara/org.json (0600).
+//
+// 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). */
+export function gatewayBaseURL(e) {
+    return e.baseURL || `${e.gatewayUrl.replace(/\/$/, "")}/v1`;
+}
+export function loadEnrollment() {
+    const p = orgPath();
+    if (!existsSync(p))
+        return null;
+    try {
+        const e = JSON.parse(readFileSync(p, "utf8"));
+        return e && typeof e === "object" && e.gatewayUrl && e.deviceToken ? e : null;
+    }
+    catch {
+        return null;
+    }
+}
+function saveEnrollment(e) {
+    mkdirSync(join(homedir(), ".hara"), { recursive: true });
+    writeFileSync(orgPath(), JSON.stringify(e, null, 2) + "\n", { encoding: "utf8", mode: 0o600 }); // holds a device token → 0600
+    try {
+        chmodSync(orgPath(), 0o600);
+    }
+    catch {
+        /* best-effort */
+    }
+}
+export function clearEnrollment() {
+    if (!existsSync(orgPath()))
+        return false;
+    rmSync(orgPath());
+    return true;
+}
+/** Parse a control-plane enroll response (tolerant of snake_case / camelCase) into an Enrollment. */
+export function parseEnrollResponse(gatewayUrl, j, now) {
+    const deviceToken = (j.device_token ?? j.deviceToken);
+    if (!deviceToken)
+        throw new Error("enroll response missing device_token");
+    return {
+        gatewayUrl: gatewayUrl.replace(/\/$/, ""),
+        deviceToken,
+        deviceId: String(j.device_id ?? j.deviceId ?? ""),
+        model: String(j.model ?? ""),
+        baseURL: (j.base_url ?? j.baseURL),
+        enrolledAt: now,
+    };
+}
+/** Exchange a one-time code for a device token at the gateway, persist it, and return the Enrollment. */
+export async function enrollDevice(gatewayUrl, code, signal) {
+    const base = gatewayUrl.replace(/\/$/, "");
+    const res = await fetch(`${base}/v1/enroll`, {
+        method: "POST",
+        signal,
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ code, device: deviceInfo() }),
+    });
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status}${res.status === 401 || res.status === 403 ? " — bad or expired code" : ""}: ${(await res.text()).slice(0, 200)}`);
+    const e = parseEnrollResponse(base, (await res.json()), new Date().toISOString());
+    saveEnrollment(e);
+    return e;
+}
+/** Best-effort heartbeat so the control plane shows this device online. Never throws. */
+export async function heartbeat(signal) {
+    const e = loadEnrollment();
+    if (!e)
+        return false;
+    try {
+        const res = await fetch(`${e.gatewayUrl}/v1/heartbeat`, {
+            method: "POST",
+            signal,
+            headers: { "content-type": "application/json", authorization: `Bearer ${e.deviceToken}` },
+            body: JSON.stringify({ device_id: e.deviceId, ...deviceInfo() }),
+        });
+        return res.ok;
+    }
+    catch {
+        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/recall.js

@@ -24,6 +24,20 @@ export function titleOf(text, path) {
     const h = /^#\s+(.+)$/m.exec(text);
     return h ? h[1].trim() : (path.split("/").pop() ?? path);
 }
+/** A ranking boost from the asset's declared dimensions: a query word in the title or the frontmatter
+ *  tags/lang matters more than one buried in the body. Used to order results, NOT the base relevance
+ *  score (which the dedup threshold relies on). */
+export function metaBoost(text, title, words) {
+    const titleL = title.toLowerCase();
+    let b = words.filter((w) => titleL.includes(w)).length * 3;
+    const fm = /^---\n([\s\S]*?)\n---/.exec(text);
+    if (fm) {
+        const tags = (/(?:^|\n)tags:\s*(.+)/i.exec(fm[1])?.[1] ?? "").toLowerCase();
+        const lang = (/(?:^|\n)lang:\s*(.+)/i.exec(fm[1])?.[1] ?? "").toLowerCase();
+        b += words.filter((w) => `${tags} ${lang}`.includes(w)).length * 2;
+    }
+    return b;
+}
 /**
  * Lexical search: rank .md files by how many query words appear in path+content.
  * Default searches the code-asset library (relative paths). Pass `roots` to search other dirs
@@ -48,14 +62,16 @@ export function searchAssets(query, limit = 5, roots) {
                 continue;
             }
             const hay = (rel + "\n" + text).toLowerCase();
-            const score = words.filter((w) => hay.includes(w)).length;
+            const score = words.filter((w) => hay.includes(w)).length; // distinct query words present (dedup threshold uses this)
             if (!score)
                 continue;
-            hits.push({ path: abs ? join(dir, rel) : rel, title: titleOf(text, rel), snippet: text.slice(0, 800), score });
+            const title = titleOf(text, rel);
+            hits.push({ path: abs ? join(dir, rel) : rel, title, snippet: text.slice(0, 800), score, boost: metaBoost(text, title, words) });
         }
     }
-    hits.sort((a, b) => b.score - a.score || a.path.length - b.path.length);
-    return hits.slice(0, limit);
+    // rank by relevance, then by the declared-dimension boost (title/tags/lang), then prefer the shorter path
+    hits.sort((a, b) => b.score - a.score || b.boost - a.boost || a.path.length - b.path.length);
+    return hits.slice(0, limit).map(({ boost, ...r }) => r);
 }
 /** Create the assets dir with an example snippet + README. Returns files written. */
 export function scaffoldAssets() {

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)

package/dist/search/zvec-store.js

@@ -0,0 +1,77 @@
+// zvec-backed ANN index for local semantic search. zvec (@zvec/zvec) is an OPTIONAL native dependency:
+// if it's absent or fails to load (no prebuilt for the platform), every function here returns
+// null/false and the caller falls back to the JSON brute-force store in semindex.ts — so installs
+// without the native binding keep working (lexical/JSON floor preserved).
+//
+// Design: zvec stores only vector→id (a pure ANN index). The JSON store stays the durable embedding
+// cache + SSOT for hit text/score. So zvec is used for fast candidate retrieval, but the SCORE is
+// recomputed from the JSON vectors (in semindex.queryIndex) — identical score semantics, zero risk
+// to hybrid.ts's thresholds.
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { rmSync, existsSync } from "node:fs";
+import { findProjectRoot } from "../context/agents-md.js";
+/* eslint-disable @typescript-eslint/no-explicit-any */
+let cached = null;
+let attempted = false;
+async function zvec() {
+    if (attempted)
+        return cached;
+    attempted = true;
+    try {
+        cached = await import("@zvec/zvec");
+    }
+    catch {
+        cached = null; // optional dep / no native prebuilt → callers fall back to brute-force
+    }
+    return cached;
+}
+export async function zvecAvailable() {
+    return (await zvec()) !== null;
+}
+function zvecDir(name, cwd) {
+    if (name === "repo")
+        return join(findProjectRoot(cwd), ".hara", "index", "repo.zvec");
+    return join(homedir(), ".hara", "index", `${name}.zvec`);
+}
+const VEC = "v";
+/** (Re)build a fresh zvec collection from already-embedded items. Best-effort — false on any failure. */
+export async function zvecBuild(name, items, cwd) {
+    const z = await zvec();
+    if (!z || items.length === 0)
+        return false;
+    try {
+        const dim = items[0].vec.length;
+        const path = zvecDir(name, cwd);
+        rmSync(path, { recursive: true, force: true }); // rebuild from the JSON cache (vectors already computed)
+        const schema = new z.ZVecCollectionSchema({
+            name,
+            vectors: [{ name: VEC, dataType: z.ZVecDataType.VECTOR_FP32, dimension: dim, indexParams: { indexType: z.ZVecIndexType.FLAT, metricType: z.ZVecMetricType.COSINE } }],
+        });
+        const col = z.ZVecCreateAndOpen(path, schema);
+        col.insertSync(items.map((it) => ({ id: it.id, vectors: { [VEC]: it.vec } })));
+        col.closeSync?.(); // closeSync flushes + releases the LOCK so a later (read-only) open succeeds
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** ANN candidate ids (best first) from the zvec index. null if unavailable/error → caller brute-forces. */
+export async function zvecQueryIds(name, qv, cwd, k) {
+    const z = await zvec();
+    if (!z)
+        return null;
+    if (!existsSync(zvecDir(name, cwd)))
+        return null;
+    try {
+        const col = z.ZVecOpen(zvecDir(name, cwd), { readOnly: true }); // read-only → no write-lock contention
+        // over-fetch, then semindex re-ranks the candidates by exact cosine from the JSON store
+        const docs = await col.query({ fieldName: VEC, vector: qv, topk: Math.max(k * 4, 24) });
+        col.closeSync?.();
+        return docs.map((d) => d.id);
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanhara/hara",
-  "version": "0.62.0",
+  "version": "0.70.0",
   "description": "hara — a coding agent CLI that runs like an engineering org.",
   "bin": {
     "hara": "dist/index.js"
@@ -63,5 +63,8 @@
     "ink-testing-library": "^4.0.0",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3"
+  },
+  "optionalDependencies": {
+    "@zvec/zvec": "^0.5.0"
   }
 }