@nanhara/hara 0.99.3 → 0.101.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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.101.0 — startup update check
+
+- **`hara` tells you when it's out of date.** On launch (interactive TTY only), a one-line notice —
+  `⬆ Update available 0.100.0 → 0.101.0 · npm i -g @nanhara/hara` — driven by a daily background
+  probe with a 3s timeout that NEVER delays startup (the notice always comes from the previous
+  probe's cache, npm update-notifier style). npmjs first, npmmirror fallback for CN networks;
+  offline machines fail silent and back off to daily retries. Disable with
+  `hara config set updateCheck false` or `HARA_UPDATE_CHECK=0`.
+
+## 0.100.0 — the agent keeps its own attention: system-reminders + anti-drift compaction
+
+Distilled from a source-level study of Claude Code v1.0.33's agent internals (the Ie1/WD5 reminder
+layer and the AU2 compaction template).
+
+- **system-reminder injection layer.** An event queue (`agent/reminders.ts`) that lands queued context
+  as ONE `<system-reminder>`-wrapped message before the next model call — visible to the model, never
+  rendered in the transcript, and always carrying the "ignore unless relevant" disclaimer so a nudge
+  can't derail unrelated work. Quiet (sub-agent) runs neither drain nor push, so parallel fan-outs
+  can't steal the main conversation's reminders. First wired event:
+- **Todo attention-refresh.** When a checklist has unfinished items and goes 5 tool-rounds untouched,
+  the model gets a reminder re-showing the authoritative list and asking for a status pass — so long
+  tasks stop silently abandoning their own plan. Any `todo_write` resets the clock; after firing it
+  re-arms (at most one nag per 5 rounds).
+- **Compaction brief: 6 → 8 sections (anti-drift).** `/compact` and auto-compaction now also preserve
+  **All user messages** — your own words survive verbatim, in order, however hard the history is
+  squeezed — and **Key technical concepts**, so the next turn doesn't re-derive the stack.
+  (`COMPACT_SYSTEM` moved to `agent/compact.ts` where tests pin the structure.)
+
 ## 0.99.3 — TUI: rock-steady input box (constant-height chrome) + plan mode grows a real handshake
 
 Built from a source-level study of codex-rs (bottom-anchored viewport, plan cells) and Claude Code

package/README.md

@@ -13,7 +13,7 @@
 **Highlights**
 - **An org, not just an agent** — `hara org "<task>"` routes work to the role that *owns* it; `hara plan "<task>"` decomposes a task into a verified DAG of atoms (frame → atomize → sequence → execute → **verify gate**), and `hara plan --parallel` runs independent atoms concurrently.
 - **Drive it from chat** — `hara gateway` runs your local hara from **Telegram · WeChat · Discord · Feishu/Lark · Slack · Mattermost · Matrix · DingTalk · WeCom · Signal** (10 platforms), with **two-way images** (send a photo → it sees it; ask for a file → it sends one), per-chat resumable sessions, and project roaming. Connects out — no public webhook. See **[docs/gateway.md](docs/gateway.md)**.
-- **Real terminal UX** — an **ink TUI**: bottom-pinned input box, **plan mode** (read-only → propose a plan → approve → execute), selectable approvals with "don't ask again", windowed reasoning, **paste images** (Ctrl+V) for vision models, light/dark theme.
+- **Real terminal UX** — an **ink TUI**: bottom-pinned input box, **plan mode** (read-only investigation → the model submits its plan via `exit_plan` → approve → execute), selectable approvals with "don't ask again", windowed reasoning, **paste images** (Ctrl+V) for vision models, light/dark theme.
 - **Persistent memory + self-evolution** — `memory_*` tools over global/project `MEMORY.md`; the agent recalls before acting, **proactively saves** durable facts, and grows its own playbooks (a lexical guard screens what it writes). Inspect/consolidate it with **`hara memory show`** and **`hara memory distill`** (promote recent daily logs → durable memory). Lexical-first by design — semantic search is opt-in, never required.
 - **Multi-provider, all streamed** — Anthropic (Claude) or any OpenAI-compatible endpoint (Qwen/DashScope, GLM, Kimi, OpenAI) with live Markdown + visible reasoning.
 - **Delegate to other agents** — the **`external_agent`** tool hands a self-contained task to **Claude Code** or **Codex** running headless, and returns the result — so you pick the best engine per task. Gated by approval, trust-tiered, and never exposed to read-only sub-agents.

package/dist/agent/compact.js

@@ -3,6 +3,23 @@
 // which reuses the manual /compact path; this just decides *when* to fire.
 /** Auto-compact once the last turn used ≥ this % of the model's context window. */
 export const AUTO_COMPACT_PCT = 85;
+/** The compaction brief (shared by /compact and auto-compaction). Eight sections, mirroring Claude
+ *  Code's AU2 template — the two that matter most beyond the obvious: **All user messages** (the
+ *  user's own words survive verbatim, so however hard the history is squeezed, intent never drifts)
+ *  and **Key technical concepts** (the frameworks/APIs in play, so the next turn doesn't re-derive
+ *  the stack). Lives here (not index.ts) so tests can pin the structure. */
+export 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 technical concepts — the frameworks, tools, APIs, and domain ideas central to the work.\n" +
+    "3. Key decisions — choices made and why (so they aren't relitigated).\n" +
+    "4. Files & code — files created/changed and the important snippets, with why each matters.\n" +
+    "5. Errors & fixes — failures hit, how they were resolved, and any correction the user gave (quote pointed feedback verbatim).\n" +
+    "6. Current state — what works now / what is verified.\n" +
+    "7. All user messages — EVERY user message so far (excluding tool results), verbatim and in order; abbreviate only huge pasted blobs with […]. These are the ground truth of intent.\n" +
+    "8. 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.";
 /** Whether to auto-compact now: enabled, the history is substantial enough to be worth summarizing, and the
  *  last turn filled the context past the threshold (so the NEXT turn would risk overflow). */
 export function shouldAutoCompact(ctxPct, historyLen, autoCompact, threshold = AUTO_COMPACT_PCT) {

package/dist/agent/loop.js

@@ -10,7 +10,8 @@ import { decideCommand, loadPermissionRules } from "../security/permissions.js";
 import { classifyRisk, guardianVeto, guardianEnabled, newBreaker, recordBlock } from "../security/guardian.js";
 import { subdirHint } from "../context/subdir-hints.js";
 import { classifyError, failoverAction, errorHint } from "./failover.js";
-import { currentTodos } from "../tools/todo.js";
+import { currentTodos, renderTodos } from "../tools/todo.js";
+import { drainReminders, wrapReminders, pushReminder, todoStaleReminder, TODO_STALE_ROUNDS } from "./reminders.js";
 /** Spinner verb (terminal mode + reused by TUI tests): when the agent has an in_progress todo,
  *  surface its activeForm/text so the bottom-of-screen line reads concretely ("▶ updating tests… 3s")
  *  instead of "working 3s". Pure: takes a snapshot + elapsed seconds. */
@@ -86,6 +87,9 @@ export async function runAgent(history, opts) {
     const guardianOn = !!opts.guardian && (opts.guardian.enabled ?? true) && guardianEnabled();
     const breaker = newBreaker();
     let breakerHalt = false; // set when a tripped breaker aborts this run
+    // Todo attention-refresh (à la Claude Code): tool rounds since the checklist was last touched while
+    // unfinished items exist. Main loop only — quiet (sub-agent) runs share the global list and must not nag.
+    let todoIdleRounds = 0;
     for (;;) {
         // Type-ahead steering: fold in anything the user submitted while the previous step ran, so it
         // reaches the model on this next call (drained after the last tool round; empty on the 1st pass).
@@ -93,6 +97,14 @@ export async function runAgent(history, opts) {
             for (const m of await opts.pendingInput())
                 history.push(m);
         }
+        // system-reminder injection: event-driven context queued since the last call (todo staleness today)
+        // lands as ONE wrapped user message the UI never renders. Quiet runs don't drain — a parallel
+        // sub-agent must not steal the main conversation's reminders.
+        if (!opts.quiet) {
+            const reminders = drainReminders();
+            if (reminders.length)
+                history.push({ role: "user", content: wrapReminders(reminders) });
+        }
         const baseSpecs = opts.toolFilter ? toolSpecs().filter((t) => opts.toolFilter(t.name)) : toolSpecs();
         const specs = opts.extraTools?.length
             ? [...baseSpecs, ...opts.extraTools.map((t) => ({ name: t.name, description: t.description, input_schema: t.input_schema }))]
@@ -349,6 +361,21 @@ export async function runAgent(history, opts) {
         }
         await flush();
         history.push({ role: "tool", results });
+        // Todo attention-refresh: a round that touched the checklist resets the clock; rounds that leave
+        // unfinished items untouched accumulate, and at TODO_STALE_ROUNDS the model gets a system-reminder
+        // re-showing the authoritative list (then the counter re-arms — at most one nag per N rounds).
+        if (!opts.quiet) {
+            if (r.toolUses.some((tu) => tu.name === "todo_write")) {
+                todoIdleRounds = 0;
+            }
+            else if (currentTodos().some((t) => t.status !== "done")) {
+                todoIdleRounds++;
+                if (todoIdleRounds >= TODO_STALE_ROUNDS) {
+                    pushReminder(todoStaleReminder(renderTodos(currentTodos())));
+                    todoIdleRounds = 0;
+                }
+            }
+        }
         if (breakerHalt) {
             // A tripped-and-declined circuit-breaker is a hard stop: end the run cleanly (the denial messages are
             // already in `results` so the model/user see why). Never spin further.

package/dist/agent/reminders.js

@@ -0,0 +1,38 @@
+// system-reminder injection (à la Claude Code's Ie1/WD5 event layer): event-driven context the model
+// should see on its NEXT call, injected as ONE `<system-reminder>`-wrapped user message. It rides the
+// provider history only — the UI transcript never renders it, so the user isn't bothered while the
+// model stays synchronized with system state (todo staleness today; file-change/diagnostic events can
+// plug in later via pushReminder).
+//
+// Claude Code's disclaimer is preserved: the model is told the context may be irrelevant, so an
+// injected nudge never derails an unrelated task.
+const queue = [];
+/** Queue a reminder for injection before the next model call (main loop only — quiet/sub-agent runs
+ *  neither push nor drain, so a parallel fan-out can't steal the main conversation's reminders). */
+export function pushReminder(text) {
+    const t = text.trim();
+    if (t)
+        queue.push(t);
+}
+/** Take everything queued (FIFO), clearing the queue. */
+export function drainReminders() {
+    if (!queue.length)
+        return [];
+    return queue.splice(0, queue.length);
+}
+/** Merge queued reminders into the single injected message. */
+export function wrapReminders(items) {
+    return ("<system-reminder>\n" +
+        items.join("\n\n") +
+        "\n\nThis context may or may not be relevant to your task — do not respond to it directly; ignore it unless it is relevant.\n" +
+        "</system-reminder>");
+}
+/** How many tool rounds a checklist may sit untouched (with unfinished items) before the model gets an
+ *  attention refresh. Reset on every todo_write; re-arms after firing so it nags at most once per N. */
+export const TODO_STALE_ROUNDS = 5;
+/** The staleness nudge: re-show the authoritative list + ask for a status pass. */
+export function todoStaleReminder(renderedTodos) {
+    return (`Your todo list has not been updated in a while. Current state:\n\n${renderedTodos}\n\n` +
+        "If you have completed or started items, update them with todo_write now (statuses drive the user's progress view). " +
+        "If the list no longer matches the work, rewrite it.");
+}

package/dist/config.js

@@ -30,7 +30,7 @@ const PROVIDER_DEFAULTS = {
     },
     "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", "routeModel", "routeBaseURL", "routeApiKey", "guardian", "notify", "vimMode", "autoCompact", "fileCheckpoints", "fallbackModel", "fallbackBaseURL", "fallbackApiKey", "reasoningEffort"];
+export const CONFIG_KEYS = ["provider", "apiKey", "model", "baseURL", "approval", "sandbox", "theme", "evolve", "assetCapture", "computerUse", "computerApps", "visionModel", "visionBaseURL", "visionApiKey", "embedProvider", "embedModel", "embedBaseURL", "embedApiKey", "routeModel", "routeBaseURL", "routeApiKey", "guardian", "notify", "vimMode", "autoCompact", "fileCheckpoints", "updateCheck", "fallbackModel", "fallbackBaseURL", "fallbackApiKey", "reasoningEffort"];
 export const REASONING_EFFORTS = ["off", "low", "medium", "high"];
 export const APPROVAL_MODES = ["suggest", "auto-edit", "full-auto"];
 export const SANDBOX_MODES = ["off", "workspace-write", "read-only"];
@@ -158,6 +158,7 @@ export function loadConfig(opts = {}) {
     const vimMode = process.env.HARA_VIM === "1" || merged.vimMode === true || merged.vimMode === "true";
     const autoCompact = !(process.env.HARA_AUTO_COMPACT === "0" || merged.autoCompact === false || merged.autoCompact === "false"); // default ON
     const fileCheckpoints = !(process.env.HARA_CHECKPOINTS === "0" || merged.fileCheckpoints === false || merged.fileCheckpoints === "false"); // default ON
+    const updateCheck = !(process.env.HARA_UPDATE_CHECK === "0" || merged.updateCheck === false || merged.updateCheck === "false"); // default ON
     const fallbackModel = process.env.HARA_FALLBACK_MODEL ?? merged.fallbackModel;
     const fallbackBaseURL = process.env.HARA_FALLBACK_BASE_URL ?? merged.fallbackBaseURL;
     const fallbackApiKey = process.env.HARA_FALLBACK_API_KEY ?? merged.fallbackApiKey;
@@ -165,7 +166,7 @@ export function loadConfig(opts = {}) {
     const reasoningEffort = reasoningRaw && ["off", "low", "medium", "high"].includes(reasoningRaw)
         ? reasoningRaw
         : undefined;
-    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, routeModel, routeBaseURL, routeApiKey, guardian, hooks, notify, vimMode, autoCompact, fileCheckpoints, fallbackModel, fallbackBaseURL, fallbackApiKey, reasoningEffort, mcpServers, cwd: process.cwd() };
+    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, routeModel, routeBaseURL, routeApiKey, guardian, hooks, notify, vimMode, autoCompact, fileCheckpoints, updateCheck, fallbackModel, fallbackBaseURL, fallbackApiKey, reasoningEffort, mcpServers, cwd: process.cwd() };
 }
 export function providerEnvKey(provider) {
     return (PROVIDER_DEFAULTS[provider] ?? PROVIDER_DEFAULTS.anthropic).envKey;

package/dist/index.js

@@ -24,7 +24,8 @@ import { clearEnrollment, enrollDevice, heartbeat, syncOrgRoles } from "./org-fl
 import { loadActiveProfile, listProfiles, useProfile, addProfile, upsertProfile, removeProfile, setModel as setProfileModel, resetModel as resetProfileModel, getProfile, effectiveModel, routingLabel, routeHost, activeId, resolveActive, setFlagOverride, writePin, removePin, pinFilePath, DEFAULT_ORG_ID, PERSONAL_ID, } from "./profile/profile.js";
 import { loadPermissionRules, scaffoldPermissions, globalPermissionsPath, projectPermissionsPath } from "./security/permissions.js";
 import { routingProvider } from "./agent/route.js";
-import { shouldAutoCompact } from "./agent/compact.js";
+import { shouldAutoCompact, COMPACT_SYSTEM } from "./agent/compact.js";
+import { checkForUpdate } from "./update-check.js";
 import { formatContextReport } from "./agent/context-report.js";
 import { userTurnPreviews, rewindTo } from "./agent/rewind.js";
 import { checkpoint, listCheckpoints, restoreCheckpoint } from "./checkpoints.js";
@@ -716,16 +717,7 @@ 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 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.";
+// COMPACT_SYSTEM (the 8-section brief) lives in agent/compact.ts so tests can pin its structure.
 const workingSetFromSummary = (s) => s
     .split("\n")
     .map((l) => l.replace(/^[-*\d.\s]+/, "").trim())
@@ -2196,6 +2188,13 @@ program.action(async (opts) => {
     // interactive REPL — ink TUI by default on a real terminal; HARA_TUI=0 forces the classic readline path
     const useTui = stdin.isTTY && stdout.isTTY && process.env.HARA_TUI !== "0";
     out(c.bold(`hara ${pkg.version}`) + c.dim(`  ·  ${cfg.provider}:${cfg.model}  ·  ${approval}${sandbox !== "off" ? `  ·  sandbox:${sandbox}` : ""}  ·  ${cwd}\n`));
+    // Startup update notice — cache-driven (a previous session's background probe), so it costs zero
+    // latency; today's probe (if due) fires in the background for the NEXT launch. TTY sessions only.
+    if (cfg.updateCheck && stdout.isTTY) {
+        const upd = checkForUpdate(pkg.version);
+        if (upd)
+            out(c.yellow(`⬆ ${upd}`) + "\n");
+    }
     const rl = createInterface({
         input: stdin,
         output: stdout,

package/dist/org/roles.js

@@ -22,13 +22,37 @@ export function orgRolesDir() {
 export function claudeAgentsDir(cwd) {
     return join(findProjectRoot(cwd), ".claude", "agents");
 }
-/** Accept Claude-Code `tools:` (comma string or list) as an alias for hara's allowTools. */
-function claudeTools(v) {
-    if (Array.isArray(v))
-        return v;
-    if (typeof v === "string" && v.trim())
-        return v.split(",").map((s) => s.trim()).filter(Boolean);
-    return undefined;
+/** Claude-Code tool names → hara tool names, for `.claude/agents` interop. Without this, a CC agent
+ *  with `tools: Read, Edit, Bash` produced allowTools that matched ZERO hara tools — the role spawned
+ *  with an empty toolbox. Unknown names pass through verbatim (they may be hara names already). */
+const CLAUDE_TOOL_MAP = {
+    read: "read_file",
+    edit: "edit_file",
+    write: "write_file",
+    bash: "bash",
+    grep: "grep",
+    glob: "glob",
+    ls: "ls",
+    webfetch: "web_fetch",
+    websearch: "web_search",
+    agent: "agent",
+    task: "agent",
+    todowrite: "todo_write",
+    notebookedit: "edit_file",
+};
+/** Accept Claude-Code `tools:` (comma string or list) as an alias for hara's allowTools —
+ *  translating CC tool names to hara's. "All tools" / "*" means unrestricted → undefined. */
+export function claudeTools(v) {
+    const raw = Array.isArray(v)
+        ? v
+        : typeof v === "string" && v.trim()
+            ? v.split(",").map((s) => s.trim()).filter(Boolean)
+            : null;
+    if (!raw || !raw.length)
+        return undefined;
+    if (raw.some((t) => /^(\*|all tools?)$/i.test(t)))
+        return undefined; // unrestricted
+    return raw.map((t) => CLAUDE_TOOL_MAP[t.toLowerCase().replace(/[^a-z]/g, "")] ?? t);
 }
 function parseFrontmatter(text) {
     const m = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(text);
@@ -83,7 +107,9 @@ export function loadRoles(cwd) {
                     description: fm.description || "",
                     owns: Array.isArray(fm.owns) ? fm.owns : [],
                     rejects: Array.isArray(fm.rejects) ? fm.rejects : [],
-                    model: fm.model || undefined,
+                    // Claude-Code model ALIASES (sonnet/opus/haiku/inherit) aren't hara model ids — treat as
+                    // "inherit the session model" rather than passing a string no provider resolves.
+                    model: fm.model && !/^(sonnet|opus|haiku|inherit)$/i.test(String(fm.model)) ? fm.model : undefined,
                     allowTools: Array.isArray(fm.allowTools) ? fm.allowTools : claudeTools(fm.tools),
                     denyTools: Array.isArray(fm.denyTools) ? fm.denyTools : undefined,
                     system: body,

package/dist/update-check.js

@@ -0,0 +1,83 @@
+// Startup update check (npm's update-notifier pattern): NEVER blocks or delays startup. The notice
+// shown at launch comes from a CACHE written by a previous session's background probe; if the cache
+// is stale (> a day) a fresh probe fires in the background with a hard timeout — its result shows on
+// the NEXT launch. Offline / blocked registries fail silently. Interactive TTY sessions only (the
+// caller gates); disable with `hara config set updateCheck false` or HARA_UPDATE_CHECK=0.
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+const cacheFile = () => join(homedir(), ".hara", "update-check.json");
+/** Probe at most once a day — the check is a courtesy, not a heartbeat. */
+export const CHECK_EVERY_MS = 24 * 60 * 60 * 1000;
+/** npmjs first; the npmmirror fallback keeps the check working on CN networks where npmjs stalls. */
+const REGISTRIES = ["https://registry.npmjs.org/@nanhara/hara/latest", "https://registry.npmmirror.com/@nanhara/hara/latest"];
+/** Strict-ish semver compare on the numeric triple: is `latest` newer than `current`?
+ *  Anything unparsable (tags, garbage, empty) → false — never nag on bad data. */
+export function isNewer(latest, current) {
+    const parse = (v) => {
+        const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
+        return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+    };
+    const a = parse(latest);
+    const b = parse(current);
+    if (!a || !b)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] > b[i];
+    }
+    return false;
+}
+export function readCache(file = cacheFile()) {
+    try {
+        const j = JSON.parse(readFileSync(file, "utf8"));
+        return typeof j?.checkedAt === "number" && typeof j?.latest === "string" ? j : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeCache(c, file = cacheFile()) {
+    try {
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, JSON.stringify(c));
+    }
+    catch {
+        /* a failed cache write must never surface */
+    }
+}
+/** The startup notice, decided purely from cache state (testable without I/O). */
+export function updateNotice(current, cache) {
+    if (!cache || !isNewer(cache.latest, current))
+        return null;
+    return `Update available ${current} → ${cache.latest} · npm i -g @nanhara/hara`;
+}
+/** Background probe: first registry that answers wins; 3s hard timeout each; silent on total failure
+ *  (checkedAt still stamps so an offline machine backs off to daily retries, not every launch). */
+export async function refreshLatest(file = cacheFile(), fetchFn = fetch) {
+    for (const url of REGISTRIES) {
+        try {
+            const r = await fetchFn(url, { signal: AbortSignal.timeout(3000) });
+            if (!r.ok)
+                continue;
+            const j = (await r.json());
+            if (j?.version) {
+                writeCache({ checkedAt: Date.now(), latest: j.version }, file);
+                return;
+            }
+        }
+        catch {
+            /* offline / blocked / slow → try the next registry, then give up quietly */
+        }
+    }
+    const prev = readCache(file);
+    writeCache({ checkedAt: Date.now(), latest: prev?.latest ?? "" }, file);
+}
+/** Startup entry: return the notice to print (or null), and — when the cache is stale — fire the
+ *  daily background probe (fire-and-forget; the caller never awaits it). */
+export function checkForUpdate(current, file = cacheFile(), now = Date.now()) {
+    const cache = readCache(file);
+    if (!cache || now - cache.checkedAt > CHECK_EVERY_MS)
+        void refreshLatest(file).catch(() => { });
+    return updateNotice(current, cache);
+}

package/package.json

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