@nanhara/hara 0.123.1 → 0.124.1

package/CHANGELOG.md

@@ -5,6 +5,55 @@ 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.124.1 — 2026-07-16 — Windows native private-state and file-identity portability
+
+- **Windows private state works in both Node and the native Bun executable.** Exclusive staging creation now
+  uses the portable `wx`/`CREATE_NEW` contract instead of passing Bun numeric flags that could surface a false
+  `ENOENT`. Config, credentials, gateway state, discovery records, and other private atomic writers retain
+  create-if-absent publication, hard-link fencing, fsync, and fail-closed alias checks.
+- **Descriptor-to-path identity checks follow the host's real guarantees.** Windows Node may report a
+  volume-derived `dev` from `fstat` but `dev=0` from `lstat` for the exact same NTFS file. Hara now correlates
+  an already-open descriptor with its already-bounded path using the stable file id and link count, while
+  POSIX still requires device, inode, and owner-only mode. Arbitrary path-to-path protected-file detection
+  continues to require device + inode, so the portability fix does not weaken hard-link protection.
+- **The release gate now exercises the reported failure on a real Windows runtime.** CI installs the pinned
+  Bun 1.3.9 x64-baseline runtime, runs portable file-state contracts, compiles `hara.exe`, and executes the
+  hostile-cwd standalone smoke including an isolated `hara doctor`. Bounded failure annotations keep future
+  Windows-only regressions diagnosable without exposing credentials. Production dependency audits retry a
+  transient registry failure only within a fixed bound and still require a real successful audit result.
+- Windows users on 0.124.0 should upgrade with `npm i -g @nanhara/hara@0.124.1`; Desktop releases that bundle
+  a sidecar should pin this patch or newer.
+
+## 0.124.0 — 2026-07-16 — task-safe interaction, bounded context, and private-state hardening
+
+- **Idle conversation no longer hijacks an unfinished task.** Ordinary input starts a new execution while
+  keeping the conversation thread; explicit `继续` / `continue` / `resume` / `go on` resumes the paused task,
+  and `/new` creates a visible task boundary. While a turn is live, Enter still steers it; `/next <message>`
+  queues a separate next task.
+- **Accepted Desktop steering is crash-safe and exactly-once.** `session.steer` persists a bounded pending
+  inbox entry before ACK, writes the projected transcript before delivery, then marks it consumed. Legacy
+  audit entries are never replayed, a full pending inbox applies backpressure, and secrets remain redacted.
+- **Every model request has a total context boundary.** Oversized historical user/assistant/tool payloads,
+  tool-call arguments, and old images are normalized in a provider-only snapshot without rewriting durable
+  history. A context-overflow response gets one tighter same-model retry before configured fallback.
+- **Compaction is now a bounded execution checkpoint.** The summarizer receives a guarded source snapshot,
+  emits structured goals/constraints/decisions/verification/files/errors/checkpoint/blockers/next action,
+  and keeps the last three user-turn groups as an anti-drift anchor instead of copying every user message
+  into the summary. CLI and Serve use the same contract and restore current touched files.
+- **Self-evolution is explicit and auditable.** `/evolve status|now` exposes the mode and manual curation;
+  classic and TUI exits share proactive reflection. Candidate observations go to logs, only stable evidence-
+  backed facts/preferences enter memory, verified repeatable procedures may become skills, and autonomous
+  code/config/permission/system-prompt mutation is explicitly outside the feature.
+- **Credential files share one no-alias storage boundary.** Desk registration, identity profiles, Qwen OAuth,
+  Weixin credentials/cursors/context tokens, legacy org enrollment, and global config mutations now use
+  symlink-free 0700 directories, bounded no-follow reads, hard-link rejection, 0600 fsynced staging, and
+  identity-checked compare-and-swap publication. Preseeded aliases fail closed without changing external file
+  bytes or permissions; legacy `org.json` archival/removal is bound to the exact verified inode.
+- **Text tools no longer rewrite undecodable bytes.** Existing-file preflight for `edit_file`, `write_file`,
+  and single/multi-file `apply_patch` uses fatal UTF-8 decoding and keeps the NUL/binary refusal. Invalid input
+  fails before the first commit with its original bytes intact, while a valid UTF-8 BOM is preserved across an
+  edit instead of being silently stripped.
+
 ## 0.123.1 — 2026-07-15 — restore default TUI keyboard input
 
 - **The bracketed-paste proxy now resumes the real terminal stream.** The main TUI closes its temporary

package/README.md

@@ -14,7 +14,7 @@
 - **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 where the platform has a byte-upload API**, resumable per-chat sessions, project/agent roaming, bounded per-thread queues, and approval-gated group automations. 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 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.
+- **Persistent memory + auditable self-evolution** — `memory_*` tools over global/project `MEMORY.md`; the agent recalls before acting and can curate evidence-backed facts/preferences plus verified reusable skills. `/evolve status|now` shows or runs the bounded curation policy; it never grants permission to rewrite product code, permissions, config, or system prompts. Inspect/consolidate with **`hara memory show`** and **`hara memory distill`**. 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. It is a trusted extension outside Hara's protected-file boundary: every interactive call requires confirmation, and non-interactive use is disabled by default.
 - **Honest under a slow network** — a live "waiting for the model… Ns" status, a stall watchdog that
@@ -195,9 +195,10 @@ stderr and missing/invalid output exits non-zero. `--role reviewer` resolves loc
 uses the portable global persona in the current project, and `--role shop:reviewer` runs at that registered
 project home. Each form enforces the role's persona, model, `allowTools`/`denyTools`, and `readOnly` policy.
 
-Inside the REPL: `/help` `/init` `/tools` `/model` `/approval` `/org` `/plan` `/roles` `/task` `/usage`
+Inside the REPL: `/help` `/init` `/tools` `/model` `/approval` `/org` `/plan` `/roles` `/task` `/continue` `/new` `/evolve` `/usage`
 `/doctor` `/sessions` `/undo` `/compact` `/recall` `/reset` `/exit` (type `/`+Tab to complete). `/task`
-shows the active execution record; `/task clear` drops it without deleting the conversation. Type `@` + Tab
+shows the active execution record; `/task clear` drops it without deleting the conversation, and `/new` starts
+a new task while retaining useful thread context. Type `@` + Tab
 to attach a file (fuzzy, walks subdirectories).
 
 The interactive REPL is an **ink TUI**: a bordered **input box pinned at the bottom** — session name in
@@ -257,11 +258,12 @@ by the tier, the frontmost-app allowlist, a dangerous-key blocklist, and a once-
 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 and task execution**: conversations are saved automatically — `-c` / `--resume <id>` or
 `hara resume <id>` to continue, `hara sessions` to list, `hara export [id] [--out file]` to render one as a
-Markdown transcript. The current task is persisted separately with stable task/turn identity and resumes as
-paused rather than being inferred from chat text; `/task` inspects it and `/task clear` leaves the transcript
-intact. Type-ahead input steers the exact live turn. Desktop/serve clients can use `session.steer` with
-`expectedTurnId`, and may pass `newTask: true` to `session.send` when an unfinished resumed task should be
-replaced explicitly. The `hara resume` launcher preserves terminal input in both npm/Node and standalone-binary
+Markdown transcript. The current task is persisted separately with stable task/turn identity and recovers as
+paused rather than being inferred from chat text. At idle, ordinary input starts a new task; an explicit
+`继续` / `continue` / `resume` / `go on` resumes the paused objective, while `/new` forces a clean task boundary.
+Type-ahead Enter steers the exact live turn; `/next <message>` queues a separate task after it. Desktop/serve
+clients use `session.steer` with `expectedTurnId` (durable before ACK) and may pass `newTask: true` to force a
+new execution. The `hara resume` launcher preserves terminal input in both npm/Node and standalone-binary
 installs.
 **MCP**: add an `mcpServers` map to global config (a reviewed project config additionally needs `HARA_TRUST_PROJECT_CONFIG=1` at launch); their tools appear to the agent as `mcp__<server>__<tool>`. Configured MCP servers, like `external_agent`, are trusted host extensions outside Hara's protected-file boundary. Every interactive tool call requires confirmation (even in `full-auto`), and non-interactive runs disable them by default; reviewed automation can explicitly opt in before launch with `HARA_ALLOW_TRUSTED_EXTENSIONS=1`. 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.
@@ -334,7 +336,8 @@ read-only **`grep`** / **`glob`** / **`ls`** / **`web_fetch`** — behind a huma
 dangerous ones unless `-y`. Read-only tools run in parallel within a turn, and edits print a
 **colored diff** of what changed. Shell output streams live; press **Esc** to interrupt a running
 turn, or **`/undo`** to revert the last edit. In-session **`/diff`**, **`/review`**, and **`/commit`** close the change → review → commit loop without leaving the prompt.
-- **Type-ahead steering**: keep typing while hara works — your message is held, then **folded into the next model call** (not deferred to a new turn), so a clarification or "also do X" course-corrects the task already in flight (codex-style). Messages typed after the final step start a fresh turn; **Esc** drops the queue and stops.
+- **Explicit live steering vs next-task queue**: keep typing while hara works and press Enter to fold a clarification into the next model call; use `/next <message>` to queue a separate task behind the live one. Accepted Desktop steering is persisted before ACK; **Esc** drops the local queue and stops.
+- **Bounded context + checkpoint compaction**: each provider call receives a non-destructive budgeted snapshot (old tool payloads/images cannot monopolize context). Overflow retries once with a tighter snapshot; `/compact` creates a structured execution checkpoint and retains the latest three user-turn groups plus current touched-file content.
 - **Project context**: auto-loads `AGENTS.md` (the cross-tool standard) walking up to the repo root; `hara init` writes one by analyzing the repo.
 - **`@file` mentions**: attach file contents to a message (`@path`); Tab-completes with a **fuzzy** matcher over the project (subdirs, git-tracked + untracked) — `@idx` → `src/index.ts`. `@<dir>` loads a directory listing, `@src/`+Tab drills into a folder, and mistyped tool/file paths get a "did you mean" suggestion.
 - **Explicit workspace boundary**: launching at Home does not inventory its directories or permit coding mutations. Start Hara from a concrete project, or pass `hara --cwd /path/to/project`, to enable search, `@` completion, shell/external agents, and file edits; explicitly named single-file reads remain available at Home.

package/dist/agent/compact.js

@@ -8,31 +8,111 @@ export const AUTO_COMPACT_PCT = 85;
  *  re-sends a bloated prompt. This cap makes auto-compaction actually engage at a snappy working size
  *  regardless of how large the window is. Overridable via `HARA_AUTO_COMPACT_TOKENS`. */
 export const AUTO_COMPACT_TOKEN_CAP = 200_000;
-/** 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.";
+import { historyChars, prepareHistoryForModel } from "./context-budget.js";
+export const COMPACTION_SOURCE_CHARS = 220_000;
+export const COMPACTION_RECENT_CHARS = 72_000;
+export const COMPACTION_SUMMARY_CHARS = 40_000;
+export const COMPACTION_RECENT_USER_TURNS = 3;
+export const COMPACTION_HEADINGS = [
+    "Goal and latest request",
+    "Constraints and preferences",
+    "Decisions and exact identifiers",
+    "Completed and verified",
+    "Files and artifacts",
+    "Failures and corrections",
+    "Current execution checkpoint",
+    "Pending work and blockers",
+    "Next concrete action",
+];
+/** The compaction brief is bounded and checkpoint-oriented. Recent turns are preserved separately, so asking
+ *  the model to repeat every user message would waste the very context compaction is meant to recover. */
+export const COMPACT_SYSTEM = "Create a bounded execution checkpoint for another coding agent. Recent turns will be retained separately, so DO NOT copy the full transcript or list every user message. " +
+    "Preserve exact file paths, commands, versions, task/turn IDs, error strings, API names, and numeric values when they matter. Distinguish verified facts from assumptions. " +
+    "Quote only short, pointed user corrections or the latest ask when necessary. Output ONLY these exact Markdown headings, each concise and concrete:\n" +
+    COMPACTION_HEADINGS.map((heading) => `## ${heading}`).join("\n") + "\n" +
+    "Under Current execution checkpoint include the active plan/status and the last safely completed action. Under Pending work and blockers include accepted steering or unanswered questions. " +
+    "Under Next concrete action give exactly one immediate action. Never include secrets or credentials.";
+function clipSummary(value) {
+    const normalized = value.replace(/\r\n?/g, "\n").trim();
+    if (normalized.length <= COMPACTION_SUMMARY_CHARS)
+        return normalized;
+    const marker = "\n…[hara: compaction summary truncated at its hard boundary]";
+    return normalized.slice(0, COMPACTION_SUMMARY_CHARS - marker.length) + marker;
+}
+function clipSection(value, max = 3_800) {
+    const normalized = value.trim();
+    if (normalized.length <= max)
+        return normalized;
+    const marker = "\n…[section truncated]";
+    return normalized.slice(0, max - marker.length) + marker;
+}
+/** Ensure even a weak/non-compliant summarizer leaves a predictable checkpoint shape. */
+export function normalizeCompactionSummary(raw) {
+    const normalized = raw.replace(/\r\n?/g, "\n").trim();
+    const complete = COMPACTION_HEADINGS.every((heading) => normalized.includes(`## ${heading}`));
+    if (complete) {
+        const sections = COMPACTION_HEADINGS.map((heading, index) => {
+            const start = normalized.indexOf(`## ${heading}`) + `## ${heading}`.length;
+            const nextHeading = COMPACTION_HEADINGS.slice(index + 1)
+                .map((candidate) => normalized.indexOf(`## ${candidate}`, start))
+                .find((position) => position >= 0) ?? normalized.length;
+            return `## ${heading}\n${clipSection(normalized.slice(start, nextHeading))}`;
+        });
+        return clipSummary(sections.join("\n\n"));
+    }
+    const summary = clipSection(normalized, 8_000);
+    const sections = COMPACTION_HEADINGS.map((heading, index) => {
+        if (index === 0)
+            return `## ${heading}\n${summary || "No usable model summary was returned."}`;
+        if (heading === "Current execution checkpoint")
+            return `## ${heading}\nConsult the durable task state and recent preserved turns.`;
+        if (heading === "Next concrete action")
+            return `## ${heading}\nRe-read the latest preserved user request and take its next verifiable step.`;
+        return `## ${heading}\nNot captured by the summarizer; verify from recent preserved turns or the workspace.`;
+    });
+    return clipSummary(sections.join("\n\n"));
+}
+/** Bounded source snapshot for the summarizer itself; direct compaction calls bypass runAgent's guard. */
+export function compactionSourceHistory(history) {
+    return prepareHistoryForModel(history, { model: "compaction", maxChars: COMPACTION_SOURCE_CHARS }).history;
+}
+/** Preserve the last few user-turn groups after the summary, with the same hard payload/image boundaries as
+ *  ordinary model requests. This is the anti-drift anchor used by Codex/OpenClaw-style compaction. */
+export function recentHistoryForCompaction(history, userTurns = COMPACTION_RECENT_USER_TURNS) {
+    const users = history.flatMap((message, index) => message.role === "user" ? [index] : []);
+    if (!users.length)
+        return [];
+    const start = users[Math.max(0, users.length - Math.max(1, userTurns))];
+    return prepareHistoryForModel(history.slice(start), { model: "compaction", maxChars: COMPACTION_RECENT_CHARS }).history;
+}
+export function compactedConversationHistory(summary, recent, restore) {
+    const out = [
+        { role: "user", content: `Execution checkpoint from older conversation (continue from current task and recent turns):\n\n${normalizeCompactionSummary(summary)}` },
+        ...recent,
+    ];
+    if (restore)
+        out.push({ role: "user", content: restore });
+    return out;
+}
+export function compactedHistoryTokenEstimate(history) {
+    return Math.ceil(historyChars(history) / 4);
+}
 /** Working-memory notes distilled from a compaction summary — short lines that survive the history wipe
  *  (stored on SessionMeta.workingSet, injected into subsequent turns). Shared by the CLI /compact path
  *  and serve's session.compact. */
 export function workingSetFromSummary(s) {
+    const seen = new Set();
     return s
         .split("\n")
         .map((l) => l.replace(/^[-*\d.\s]+/, "").trim())
-        .filter((l) => l.length > 3)
+        .filter((l) => l.length > 3 && !/^#{1,6}\s/.test(l) && !/^not captured/i.test(l) && !/^consult the durable/i.test(l))
+        .filter((l) => {
+        const key = l.toLocaleLowerCase();
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    })
         .slice(0, 12)
         .map((l) => l.slice(0, 140));
 }

package/dist/agent/context-budget.js

@@ -0,0 +1,180 @@
+import { contextWindow } from "../statusbar.js";
+export const MAX_MODEL_HISTORY_CHARS = 600_000;
+export const MIN_MODEL_HISTORY_CHARS = 48_000;
+export const MAX_USER_ITEM_CHARS = 64_000;
+export const MAX_ASSISTANT_ITEM_CHARS = 24_000;
+export const MAX_TOOL_INPUT_STRING_CHARS = 12_000;
+export const RECENT_IMAGE_TURNS = 2;
+const GUARD_NOTE = "[Hara context guard: older/oversized context was bounded for this model request. The durable transcript is unchanged. " +
+    "Prefer current task state and recent messages; re-read files or ask the user before relying on an omitted exact value.]";
+function jsonChars(value) {
+    try {
+        return JSON.stringify(value).length;
+    }
+    catch {
+        return 1_000;
+    }
+}
+export function historyChars(history) {
+    let total = 0;
+    for (const message of history) {
+        if (message.role === "user") {
+            total += message.content.length + (message.images?.reduce((sum, image) => sum + image.path.length + image.mediaType.length + 64, 0) ?? 0);
+        }
+        else if (message.role === "assistant") {
+            total += message.text.length + jsonChars(message.toolUses);
+        }
+        else {
+            total += message.results.reduce((sum, result) => sum + result.content.length + result.id.length + result.name.length + 32, 0);
+        }
+    }
+    return total;
+}
+export function modelHistoryBudget(options) {
+    if (options.maxChars !== undefined)
+        return Math.max(2_000, Math.floor(options.maxChars));
+    // Use a conservative blended chars/token allowance: English commonly has more, while CJK/code can have
+    // fewer. Reserve system/tool schema room and cap giant-window models at a responsive working set.
+    const gross = Math.min(MAX_MODEL_HISTORY_CHARS, Math.floor(contextWindow(options.model) * 1.5));
+    const overhead = (options.system?.length ?? 0) + jsonChars(options.tools ?? []);
+    const scale = Math.max(0.2, Math.min(1, options.budgetScale ?? 1));
+    return Math.max(MIN_MODEL_HISTORY_CHARS, Math.floor((gross - overhead) * scale));
+}
+function safeSliceEnd(value, end) {
+    let at = Math.max(0, Math.min(value.length, end));
+    if (at > 0 && /[\uD800-\uDBFF]/.test(value[at - 1] ?? ""))
+        at--;
+    return value.slice(0, at);
+}
+function safeSliceStart(value, start) {
+    let at = Math.max(0, Math.min(value.length, start));
+    if (at < value.length && /[\uDC00-\uDFFF]/.test(value[at] ?? ""))
+        at++;
+    return value.slice(at);
+}
+function clip(value, max, label) {
+    const cap = Math.max(0, Math.floor(max));
+    if (value.length <= cap)
+        return value;
+    const marker = `\n…[hara: ${value.length - cap} chars omitted from ${label}]…\n`;
+    if (marker.length >= cap)
+        return marker.slice(0, cap);
+    const room = cap - marker.length;
+    const head = Math.floor(room * 0.6);
+    const tail = room - head;
+    return safeSliceEnd(value, head) + marker + safeSliceStart(value, value.length - tail);
+}
+function boundValue(value, stringCap, depth = 0) {
+    if (typeof value === "string")
+        return clip(value, stringCap, "historical tool input");
+    if (value === null || typeof value !== "object")
+        return value;
+    if (depth >= 8)
+        return "[hara: nested historical tool input omitted]";
+    if (Array.isArray(value)) {
+        const kept = value.slice(0, 80).map((item) => boundValue(item, stringCap, depth + 1));
+        if (value.length > kept.length)
+            kept.push(`[hara: ${value.length - kept.length} array items omitted]`);
+        return kept;
+    }
+    const entries = Object.entries(value);
+    const out = {};
+    for (const [key, item] of entries.slice(0, 80))
+        out[key] = boundValue(item, stringCap, depth + 1);
+    if (entries.length > 80)
+        out._hara_omitted_keys = entries.length - 80;
+    return out;
+}
+function boundToolUses(toolUses, stringCap) {
+    // Never cap the call ARRAY independently: provider protocols require every following tool_result id to
+    // have a matching tool_use. Payloads may shrink, or an entire old exchange may fall out of the suffix,
+    // but identities within a retained exchange stay one-to-one.
+    return toolUses.map((use) => ({ ...use, input: boundValue(use.input, stringCap) }));
+}
+function addGuard(history) {
+    return [{ role: "user", content: GUARD_NOTE }, ...history];
+}
+/** Create a bounded provider snapshot without mutating or deleting the durable transcript. Tool call/result
+ *  identities and ordering remain intact; only model-visible payload text is clipped. */
+export function prepareHistoryForModel(history, options) {
+    const originalChars = historyChars(history);
+    const budgetChars = modelHistoryBudget(options);
+    const userIndices = history.flatMap((message, index) => message.role === "user" ? [index] : []);
+    const latestUser = userIndices.at(-1) ?? -1;
+    const recentUsers = new Set(userIndices.slice(-3));
+    const imageUsers = new Set(userIndices.slice(-RECENT_IMAGE_TURNS));
+    let changed = false;
+    let omittedImages = 0;
+    let snapshot = history.map((message, index) => {
+        if (message.role === "user") {
+            const cap = index === latestUser ? MAX_USER_ITEM_CHARS : recentUsers.has(index) ? 40_000 : 20_000;
+            let content = clip(message.content, cap, "user message");
+            if (content !== message.content)
+                changed = true;
+            let images = message.images?.map((image) => ({ ...image }));
+            if (images?.length && !imageUsers.has(index)) {
+                omittedImages += images.length;
+                content += `\n\n[hara: ${images.length} older image attachment(s) omitted from this model round; reattach if needed]`;
+                images = undefined;
+                changed = true;
+            }
+            return { role: "user", content, ...(images?.length ? { images } : {}) };
+        }
+        if (message.role === "assistant") {
+            const text = clip(message.text, MAX_ASSISTANT_ITEM_CHARS, "assistant message");
+            const toolUses = boundToolUses(message.toolUses, MAX_TOOL_INPUT_STRING_CHARS);
+            if (text !== message.text || jsonChars(toolUses) !== jsonChars(message.toolUses))
+                changed = true;
+            return { role: "assistant", text, toolUses };
+        }
+        const results = message.results.map((result) => {
+            const content = clip(result.content, 24_000, `tool result ${result.name}`);
+            if (content !== result.content)
+                changed = true;
+            return { ...result, content };
+        });
+        return { role: "tool", results };
+    });
+    const reduce = (toolCap, assistantCap, oldUserCap, recentUserCap, inputCap) => {
+        snapshot = snapshot.map((message, index) => {
+            if (message.role === "tool") {
+                return { role: "tool", results: message.results.map((result) => ({ ...result, content: clip(result.content, toolCap, `tool result ${result.name}`) })) };
+            }
+            if (message.role === "assistant") {
+                return { role: "assistant", text: clip(message.text, assistantCap, "assistant message"), toolUses: boundToolUses(message.toolUses, inputCap) };
+            }
+            const cap = index === latestUser ? Math.max(recentUserCap, 24_000) : recentUsers.has(index) ? recentUserCap : oldUserCap;
+            return { ...message, content: clip(message.content, cap, "user message") };
+        });
+        changed = true;
+    };
+    if (historyChars(snapshot) + GUARD_NOTE.length > budgetChars)
+        reduce(2_000, 4_000, 6_000, 16_000, 2_000);
+    if (historyChars(snapshot) + GUARD_NOTE.length > budgetChars)
+        reduce(512, 1_500, 1_500, 8_000, 768);
+    if (historyChars(snapshot) + GUARD_NOTE.length > budgetChars)
+        reduce(128, 512, 512, 4_000, 256);
+    if (changed)
+        snapshot = addGuard(snapshot);
+    // Extremely long threads can exceed the ceiling through message structure alone. Retain the largest suffix
+    // beginning at a user boundary. The durable thread remains available for explicit compaction/export.
+    if (historyChars(snapshot) > budgetChars) {
+        const starts = snapshot.flatMap((message, index) => message.role === "user" ? [index] : []).reverse();
+        let suffix = null;
+        for (const start of starts) {
+            const candidate = snapshot.slice(start);
+            if (historyChars(candidate) + GUARD_NOTE.length <= budgetChars)
+                suffix = candidate;
+            else if (suffix)
+                break;
+        }
+        if (suffix)
+            snapshot = addGuard(suffix[0]?.role === "user" && suffix[0].content === GUARD_NOTE ? suffix.slice(1) : suffix);
+        else {
+            const latest = [...snapshot].reverse().find((message) => message.role === "user");
+            snapshot = [{ role: "user", content: `${GUARD_NOTE}\n\n${latest?.role === "user" ? clip(latest.content, Math.max(1_000, budgetChars - GUARD_NOTE.length - 8), "latest user message") : "Continue the active task from durable task state."}` }];
+        }
+        changed = true;
+    }
+    return { history: snapshot, changed, originalChars, preparedChars: historyChars(snapshot), budgetChars, omittedImages };
+}

package/dist/agent/evolution.js

@@ -0,0 +1,37 @@
+const EVOLUTION_READ_TOOLS = new Set([
+    "memory_search",
+    "memory_get",
+    "read_file",
+    "grep",
+    "glob",
+    "ls",
+    "codebase_search",
+]);
+/** Self-evolution is an auditable memory/skill curation pass, never autonomous product mutation. */
+export const EVOLUTION_SYSTEM = "Review this session for durable, reusable learning. This is an AUDITABLE CURATION pass, not permission to rewrite yourself. " +
+    "Use memory_write only for evidence-backed facts, decisions, project conventions, or explicit user preferences. Put tentative or one-off observations in target=log; " +
+    "promote directly to memory/user only when stable and clearly supported by the conversation or verified workspace state. Include a short source/evidence phrase and avoid duplicates. " +
+    "Use skill_create only for a repeatable procedure that was actually exercised or verified; do not turn a single guess into a playbook. " +
+    "Never store secrets, credentials, raw private content, large transcripts, or stale task state. Never edit product code, AGENTS.md, permissions, configuration, or system prompts as 'self-evolution'; " +
+    "those require a separate normal task and human-reviewed change. If nothing qualifies, write nothing. Reply only DONE with a short count of memories/skills saved.";
+export function evolutionStatus(config) {
+    const mode = config.evolve === "off"
+        ? "off — no reflection/distillation runs"
+        : config.evolve === "light"
+            ? "light — memory tools are available; curation runs on /evolve now or manual /compact"
+            : "proactive — eligible session exits reflect automatically; /evolve now is also available";
+    const capture = config.assetCapture === "off"
+        ? "skill capture off"
+        : config.assetCapture === "auto"
+            ? "memory/skill writes auto-approved during a curation pass"
+            : "memory/skill writes require confirmation during a curation pass";
+    return `self-evolution: ${mode}\npolicy: evidence-backed memory + verified reusable skills only; never autonomous code/system-prompt changes\ncapture: ${capture}`;
+}
+export function shouldAutoEvolve(mode, historyLength) {
+    return mode === "proactive" && historyLength >= 4;
+}
+/** Runtime capability boundary for curation. In particular, todo_write is not "read-only" here: it would
+ * mutate the active execution checkpoint. Network tools are also unnecessary for distilling local evidence. */
+export function allowsEvolutionTool(name, assetCapture) {
+    return name === "memory_write" || (assetCapture !== "off" && name === "skill_create") || EVOLUTION_READ_TOOLS.has(name);
+}

package/dist/agent/failover.js

@@ -1,7 +1,6 @@
 // App-level failover — what to do when a provider turn ENDS in an error (the SDK already retried transient
-// 429/5xx via maxRetries; this handles what's left). Two recoveries: a context-overflow → compact + retry,
-// and a persistent/overloaded error → retry once on a configured FALLBACK model. The decision is pure +
-// tested here; runAgent just executes it (and guards each recovery to once, so no retry loops).
+// 429/5xx via maxRetries; this handles what's left). runAgent first retries context overflow once with a
+// tighter bounded snapshot; this module then decides whether a remaining error gets one fallback-model try.
 /** Classify a provider error from its message (+ HTTP status if known). Message patterns include the
  *  Chinese strings DashScope/GLM/Qwen return, since hara targets those endpoints. */
 export function classifyError(msg, status) {
@@ -44,7 +43,7 @@ export function errorHint(kind) {
         case "overloaded":
             return " — provider overloaded; set `fallbackModel` to auto-switch on errors";
         case "context_overflow":
-            return " — context too long; `/compact` (or enable `autoCompact`)";
+            return " — context still too long after bounded retry; use `/compact` or `/new`";
         case "timeout":
             return " — network timeout; check connectivity";
         default:

package/dist/agent/loop.js

@@ -19,6 +19,7 @@ import { recordTouch } from "./touched.js";
 import { resolve as resolvePath } from "node:path";
 import { redactSensitiveText } from "../security/secrets.js";
 import { redactToolSubprocessOutput } from "../security/subprocess-env.js";
+import { prepareHistoryForModel } from "./context-budget.js";
 /** File tools whose `path` input marks the file as "recently worked with" (post-compaction restore). */
 const FILE_TOUCH_TOOLS = new Set(["read_file", "edit_file", "write_file"]);
 /** Stall watchdog ceiling: a model attempt that streams NOTHING for this long is treated as a dead /
@@ -91,8 +92,11 @@ independent questions (role "explore") — each returns conclusions, not dumps.
 mid-task arrive marked as interjections — triage them (refine current / queue as todo / urgent-switch)
 instead of blindly folding everything into the current task; the todo list is your task queue. For a multi-step task, call \`todo_write\` to plan a short checklist and keep it updated as
 you go (one item in_progress at a time) — skip it for trivial one-step tasks. You have a persistent
-memory: use memory_search before answering about prior decisions,
-conventions, or the user's preferences, and memory_write to proactively save durable facts you learn.
+memory: use memory_search before answering about prior decisions, conventions, or the user's preferences.
+Only save evidence-backed learning: tentative/one-off observations go to memory_write target=log; stable
+verified project conventions/decisions may go to project memory, and explicit user preferences to user memory.
+Include a short source/evidence phrase, avoid duplicates, and never treat memory as permission to change code,
+configuration, permissions, AGENTS.md, or your system instructions.
 When a task matches one of the Skills listed below, call the \`skill\` tool to load its full instructions
 before acting; save a reusable how-to as a new skill with skill_create. If you discover a durable project
 convention, you may propose an edit to AGENTS.md via edit_file (the user reviews the diff).
@@ -254,6 +258,9 @@ async function runAgentInner(history, opts, life) {
     const permRules = loadPermissionRules(ctx.cwd); // command-level allow/ask/deny policy for the bash tool
     let activeProvider = provider; // may switch to a fallback model on a recoverable error (app-failover)
     let triedFallback = false;
+    let contextOverflowRetried = false;
+    let contextBudgetScale = 1;
+    let contextGuardNotified = false;
     let emptyRetried = false; // one-shot: a genuinely empty model turn gets a single nudge before we give up
     const interruptedOutcome = () => {
         const msg = "(interrupted)";
@@ -348,6 +355,21 @@ async function runAgentInner(history, opts, life) {
             ? [...baseSpecs, ...opts.extraTools.map((t) => ({ name: t.name, description: t.description, input_schema: t.input_schema }))]
             : baseSpecs;
         const sink = ctx.ui; // TUI mode: route output to ink instead of stdout
+        const system = composeSystem(ctx.cwd, opts.projectContext, opts.systemOverride, opts.memory, opts.continuationSession, opts.executionContext);
+        const prepared = prepareHistoryForModel(history, {
+            model: activeProvider.model,
+            system,
+            tools: specs,
+            budgetScale: contextBudgetScale,
+        });
+        if (prepared.changed && !contextGuardNotified && !opts.quiet) {
+            contextGuardNotified = true;
+            const note = `✻ context guard bounded this model request (${Math.round(prepared.originalChars / 1000)}k → ${Math.round(prepared.preparedChars / 1000)}k chars); durable history is unchanged`;
+            if (sink)
+                sink.notice(note);
+            else
+                out(c.dim(`${note}\n`));
+        }
         const tty = stdout.isTTY && !opts.quiet && !sink;
         const md = tty && process.env.HARA_MD !== "0" ? makeRenderer(out) : null;
         // Reasoning rendering in plain-terminal mode: we put reasoning on its OWN dim lines (prefixed
@@ -428,8 +450,8 @@ async function runAgentInner(history, opts, life) {
                     return { text: "", toolUses: [], stop: "error", errorMsg: "interrupted" };
                 }
                 return activeProvider.turn({
-                    system: composeSystem(ctx.cwd, opts.projectContext, opts.systemOverride, opts.memory, opts.continuationSession, opts.executionContext),
-                    history,
+                    system,
+                    history: prepared.history,
                     tools: specs,
                     // Any stream chunk keeps the connection considered alive — even suppressed reasoning_content, so a
                     // reasoning model thinking for a long while before its first `content` token can't be false-timed-out.
@@ -535,6 +557,19 @@ async function runAgentInner(history, opts, life) {
         history.push({ role: "assistant", text: r.text, toolUses: r.toolUses });
         if (r.stop === "error") {
             const kind = classifyError(r.errorMsg ?? "");
+            if (kind === "context_overflow" && !contextOverflowRetried) {
+                contextOverflowRetried = true;
+                contextBudgetScale = 0.5;
+                history.pop(); // drop the errored (partial/empty) assistant turn before a tighter normalized retry
+                if (!opts.quiet) {
+                    const note = "✻ context overflow → retrying once with a tighter bounded history snapshot…";
+                    if (sink)
+                        sink.notice(note);
+                    else
+                        out(c.dim(`${note}\n`));
+                }
+                continue;
+            }
             if (failoverAction(kind, { hasFallback: !!opts.fallback?.provider, triedFallback }) === "fallback") {
                 triedFallback = true;
                 history.pop(); // drop the errored (partial/empty) assistant turn before retrying