@nanhara/hara 0.127.2 → 0.129.0

package/CHANGELOG.md

@@ -5,6 +5,47 @@ 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.129.0 — 2026-07-20 — durable revisions and workspace recovery
+
+- Authenticated Serve clients can commit a user-selected file as a new immutable Artifact revision with
+  `artifact.commit`. Every write carries `baseRevisionId`; a stale editor receives the dedicated protocol
+  conflict code and cannot replace the current revision.
+- `artifact.revert` restores an earlier ancestor by creating another immutable revision rather than moving
+  the pointer backward or mutating history. The imported original and every prior revision remain unchanged.
+- Revision pointer updates now use a private-state compare-and-swap guard that also closes a cross-process
+  race. The authenticated host assigns the user actor, so a Desktop client cannot forge an Agent/migration
+  audit identity.
+- This slice does not yet export files or claim Office fidelity. ExportReceipt, validation reports, worker
+  identity, format-specific editing, and Panel v2 remain separate release gates.
+- Interactive launches from the home directory now offer an explicit, one-step switch to a recent or
+  registered project before provider and MCP startup. Hara never enumerates the home directory and never
+  changes workspace scope without confirmation.
+- Repeated protected-home failures are now grouped by semantic root cause across `ls`, `grep`, `glob`, and
+  other filesystem tools. A run stops after the bounded retry threshold with a focused recovery instruction
+  instead of trying different tools against the same boundary indefinitely.
+- Git plugin installation now rejects credential-bearing source URLs, bounds clone time, and safely
+  distinguishes missing Git, network, authentication/access, and private/not-found repository failures
+  without echoing URLs, tokens, or Git stderr.
+- Feishu WebSocket gateways now report connected, disconnected, and reconnected lifecycle events with
+  one-hour and 24-hour counters. Repeated disconnects raise rate-limited alerts, while terminal SDK recovery
+  failures stop the adapter after a safe drain so a process supervisor can restart it.
+- Upgrade with `npm i -g @nanhara/hara@0.129.0`.
+
+## 0.128.0 — 2026-07-20 — local deliverable foundation
+
+- Hara Serve now provides the first `artifact/1` local runtime through authenticated
+  `artifact.import`, `artifact.list`, `artifact.get`, and `artifact.revisions` methods. Presentations,
+  spreadsheets, and documents receive opaque Artifact/revision identities and a stable content receipt.
+- Import is copy-on-write and leaves the selected file untouched. The private store rejects relative paths,
+  symbolic links, hard links, protected credential/configuration files, macro-enabled Office extensions,
+  type-confused Office packages, empty files, and files over 64 MiB; activation and immutable binary writes
+  are crash-safe, owner-only, and digest-verified.
+- Local metadata never retains the selected absolute path. Corrupt entries remain hidden without hiding
+  healthy work, and unexpected filesystem failures cross the Desktop RPC boundary as path-free errors.
+- This release intentionally stores and verifies deliverables but does not render, edit, export, or execute
+  them. Those actions remain gated on a matching reviewed Office capability in the next vertical slices.
+- Upgrade with `npm i -g @nanhara/hara@0.128.0`.
+
 ## 0.127.2 — 2026-07-20 — quiet scheduled monitoring
 
 - Cron delivery now supports `--deliver-mode always|on-output|on-error`. Existing jobs retain the

package/README.md

@@ -272,6 +272,15 @@ Type-ahead Enter steers the exact live turn; `/next <message>` queues a separate
 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.
+**Local deliverables**: Hara Serve 0.128 adds the first local `artifact/1` foundation for presentations,
+spreadsheets, and documents. An authenticated Desktop client can import, list, integrity-check, and inspect
+version history through `artifact.import|list|get|revisions`. The next revision transaction slice also
+advertises `artifact.commit|revert`: every edit supplies the version it started from, a stale edit fails with
+an explicit conflict, and reverting creates a new immutable revision instead of rewriting history. Import and
+commit make owner-only copies under `~/.hara/artifacts`, never change the selected source file, and never store
+its absolute path. Relative, linked, protected, macro-enabled, type-confused, empty, and oversized inputs fail
+closed. The runtime does **not** yet render, format-edit, export, or execute imported content; those operations
+require matching reviewed Office capabilities and validation/export receipts.
 **MCP**: add an `mcpServers` map to global config (a reviewed project config additionally needs `HARA_TRUST_PROJECT_CONFIG=1` at launch). Hara starts with every configured server stopped and exposes only `mcp_connect`; when the current task first needs one server, the agent requests permission to connect that server and its tools appear on the next round as `mcp__<server>__<tool>`. Unrelated servers remain stopped. Configured MCP servers, like `external_agent`, are trusted host extensions outside Hara's protected-file boundary. Every interactive external-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.
 **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`. Every job has a 30-minute deadline and the whole sequential tick has a non-renewable 60-minute watchdog: a job timeout kills its process tree, records `timed out` + duration/error, then continues with the next due job; a tick timeout stops the remainder and releases the global lock. Add `--deliver feishu:<chatId>` (or Telegram/WeChat/webhook) for outcomes. `--deliver-mode always` preserves the existing every-run heartbeat, `on-output` sends only when redacted stdout is non-empty, and `on-error` sends only failed runs; `--alert-after N` remains independent and still raises the consecutive-failure 🚨 threshold alarm (default 3). Delivery intent is durable before transport, uses a stable idempotency key, and retries with bounded backoff on later ticks until confirmed. A failed channel cannot grow `jobs.json` forever: each job keeps at most 64 pending effects, reserves outcome/alert room before launch, and disables itself with a visible backlog error when full; restore delivery, let the queue drain, then re-enable it. Tune milliseconds with `HARA_CRON_JOB_TIMEOUT_MS` (hard max 24h) and `HARA_CRON_TICK_TIMEOUT_MS` (hard max 5h); scheduled jobs are also capped by the tick. After upgrading from a version whose tick is already stuck, terminate that specific legacy `hara cron tick` process tree once (or reboot); the next scheduler minute marks over-age state interrupted/disabled and recovers the lock without replaying a possibly orphaned task.

package/dist/agent/loop.js

@@ -9,7 +9,7 @@ import { runHooks } from "../hooks.js";
 import { mapLimit, maxParallel } from "../concurrency.js";
 import { decideCommand, isReadOnlyCommand, loadPermissionRules, splitCompound, } from "../security/permissions.js";
 import { classifyRisk, guardianVeto, guardianEnabled, newBreaker, recordBlock } from "../security/guardian.js";
-import { keyOf, looksFailed, recordCall } from "./repeat-guard.js";
+import { failureIdentity, looksFailed, recordCall } from "./repeat-guard.js";
 import { agentMaxRounds, agentRunTimeoutMs, formatAgentDuration } from "./limits.js";
 import { subdirHint } from "../context/subdir-hints.js";
 import { classifyError, failoverAction, errorHint } from "./failover.js";
@@ -405,7 +405,7 @@ function hardStop(opts, life, kind, detail) {
         ? `⏸ agent run paused: active-execution deadline ${formatAgentDuration(life.timeoutMs)} reached after ${life.rounds} round(s). Waiting for your answers did not consume this budget. No further model or tool calls will start in this turn. Session-backed work keeps its task and checklist checkpoint; type \`/continue\` to resume in a fresh bounded turn. Only for intentionally long single turns, use \`hara config set runTimeoutMs 45m\` (maximum 2h).`
         : kind === "max_rounds"
             ? `⛔ agent run stopped: ${life.maxRounds}-round safety limit reached after ${formatAgentDuration(elapsedMs)}. This usually means the model is looping. Increase it with \`hara config set maxAgentRounds <n>\` (maximum 256) only if the extra rounds are intentional.`
-            : `⛔ agent run stopped: the same failing ${detail?.tool ?? "tool"} call repeated ${detail?.count ?? REPEATED_FAILURE_LIMIT} times. Change the approach or fix the reported cause before retrying.`;
+            : `⛔ agent run stopped: the same failing ${detail?.label ?? "tool call"} repeated ${detail?.count ?? REPEATED_FAILURE_LIMIT} times. Change the approach or fix the reported cause before retrying.`;
     const event = { kind, message, elapsedMs, rounds: life.rounds, timeoutMs: life.timeoutMs, maxRounds: life.maxRounds };
     if (!life.limitAnnounced) {
         life.limitAnnounced = true;
@@ -944,16 +944,16 @@ async function runAgentInner(history, opts, life) {
         let repeatHalt = null;
         const noteCall = (name, input, content, isError = false) => {
             const note = recordCall(name, input, content, isError, ctx.todoScope);
-            const key = keyOf(name, input);
+            const identity = failureIdentity(name, input, content, isError);
             if (isError || looksFailed(content, name)) {
-                const count = (life.failedCalls.get(key) ?? 0) + 1;
+                const count = (life.failedCalls.get(identity.key) ?? 0) + 1;
                 // This is a *consecutive no-progress* streak, not a lifetime counter for the call. A different
                 // failure is a changed attempt; keep only that new streak instead of letting an old failure
                 // silently accumulate across intervening work.
                 life.failedCalls.clear();
-                life.failedCalls.set(key, count);
+                life.failedCalls.set(identity.key, count);
                 if (count >= REPEATED_FAILURE_LIMIT && !repeatHalt)
-                    repeatHalt = { tool: name, count };
+                    repeatHalt = { label: identity.label, count };
             }
             else {
                 // Any successful action is progress (in particular edit/exec calls that may have fixed the

package/dist/agent/repeat-guard.js

@@ -8,6 +8,7 @@
 // sessions in one process, so streaks are keyed by the same run scope as todo/reminder state.
 const DEFAULT_SCOPE = "default";
 const seenByScope = new Map();
+const HOME_WORKSPACE_BOUNDARY_KEY = "root-cause:home-workspace-boundary";
 function scopedSeen(scope) {
     const key = scope?.trim() || DEFAULT_SCOPE;
     const seen = seenByScope.get(key) ?? new Map();
@@ -68,23 +69,52 @@ export function looksFailed(content, name) {
     }
     return false;
 }
+/** Several different filesystem tools can hit the same protected Home-workspace boundary. Treating each
+ * tool name/argument tuple as a fresh idea lets a model spin through grep → glob → ls even though the
+ * root cause cannot change inside that run. Only Hara's own stable boundary diagnostics are coalesced. */
+function isHomeWorkspaceBoundaryFailure(content) {
+    return (/will not recursively scan the home directory\b/i.test(content)
+        || /will not enumerate or recursively scan directories while Hara is rooted at the home directory\b/i.test(content)
+        || /workspace that is the home directory or contains it\b/i.test(content));
+}
+/** Stable identity used by both the warning note and the run-level hard breaker. */
+export function failureIdentity(name, input, content, isError = false) {
+    const failed = isError || looksFailed(content, name);
+    if (failed && isHomeWorkspaceBoundaryFailure(content)) {
+        return {
+            key: HOME_WORKSPACE_BOUNDARY_KEY,
+            label: "Home workspace boundary",
+            semantic: true,
+        };
+    }
+    return {
+        key: keyOf(name, input),
+        label: `${name} call`,
+        semantic: false,
+    };
+}
 /** Record a completed call; returns a warning to APPEND to the tool result when the same call has now
  *  failed >=2x in a row (empty string otherwise). Pure aside from the session-scoped map. */
 export function recordCall(name, input, content, isError = false, scope) {
-    const k = keyOf(name, input);
     const failed = isError || looksFailed(content, name);
+    const identity = failureIdentity(name, input, content, isError);
     const seen = scopedSeen(scope);
     if (!failed) {
         seen.clear(); // any success is progress; a later failure starts a fresh no-progress streak
         return "";
     }
-    const s = seen.get(k) ?? { fails: 0 };
+    const s = seen.get(identity.key) ?? { fails: 0 };
     s.fails++;
     // "In a row" is literal: a different failed call is a changed attempt and breaks the old streak.
     seen.clear();
-    seen.set(k, s);
+    seen.set(identity.key, s);
     if (s.fails < 2)
         return "";
+    if (identity.semantic) {
+        return (`\n\n⟳ hara: the same ${identity.label} has now blocked ${s.fails} consecutive tool calls — ` +
+            "another filesystem/search tool cannot bypass it. Ask the user to switch with `/cd <project>` " +
+            "or stop this run; do not probe another directory tool from Home.");
+    }
     return (`\n\n⟳ hara: this exact ${name} call has now FAILED ${s.fails}× with identical arguments — ` +
         `repeating it unchanged will fail again. Read the error above, change something (arguments / approach / tool), ` +
         `or step back and re-plan; if you're out of ideas, ask the user and say what you tried.`);