@nanhara/hara 0.62.0 → 0.67.0

package/CHANGELOG.md

@@ -5,6 +5,49 @@ 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.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

@@ -59,7 +59,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 +187,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 +207,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

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/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 } 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,55 @@ 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"));
+    }
+    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 +1222,23 @@ 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
     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-fleet/enroll.js

@@ -0,0 +1,94 @@
+// 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
+//   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";
+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;
+    }
+}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanhara/hara",
-  "version": "0.62.0",
+  "version": "0.67.0",
   "description": "hara — a coding agent CLI that runs like an engineering org.",
   "bin": {
     "hara": "dist/index.js"