@nanhara/hara 0.122.2 → 0.122.4

package/CHANGELOG.md

@@ -5,6 +5,114 @@ 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.122.4 — 2026-07-14 — bounded agent lifecycle and chat delivery hardening
+
+- **An active agent can no longer renew itself forever.** Every CLI, headless, org, and Desktop/serve turn
+  now has a 30-minute total wall-clock deadline and a 64 model/tool-round ceiling, independent of streaming
+  activity and per-tool timeouts. A visible warning fires after five minutes or at 75% of the round budget;
+  reaching either hard boundary returns an actionable `halted` outcome to the terminal, Desktop protocol, or
+  gateway reply. `runTimeoutMs` (friendly `30m`/`90s` values; hard max 2h) and `maxAgentRounds` (hard max 256)
+  can raise/lower the bounds but cannot disable them.
+- **Repeated failures now trip a real circuit-breaker.** The third identical failing tool call closes its
+  protocol round and stops the run instead of merely asking the model not to repeat itself. A final round cap
+  still catches alternating or superficially changing loops.
+- **Cancellation reaches owned work.** Tools receive the combined user/deadline signal; foreground shell and
+  external-agent process trees terminate on it, and read-only sub-agents inherit the parent's cancellation
+  with tighter 8-minute/24-round limits. Providers/tools that ignore `AbortSignal` are raced at the core, so
+  Hara itself still settles on time and never executes a late next tool call. File, memory, skill, and gateway
+  outbox writes re-check cancellation immediately before commit, while session ownership remains held until an
+  uncooperative tool physically settles, preventing a timed-out write from racing the next turn.
+- **One-shot model helpers are hard-bounded too.** Setup checks, role routing, plan decomposition and
+  verification, commit-message generation, session naming, conversation compaction, vision analysis, and the
+  security guardian now combine cooperative abort with a hard Promise deadline. A custom provider that ignores
+  cancellation can no longer strand the CLI before or after the main agent loop.
+- **Cron can no longer hold its global tick lock forever.** Scheduled jobs keep their 30-minute per-job
+  deadline and the whole tick now has a non-renewable 60-minute wall-clock watchdog. Timeout cancellation
+  force-stops the owned process tree, always releases the tick lock, records `running`/`timed_out`, duration and
+  last error durably, counts timeouts toward `alertAfter`, and lets later due jobs run after an individual job
+  timeout (a total-tick timeout stops the remainder). `HARA_CRON_JOB_TIMEOUT_MS` and
+  `HARA_CRON_TICK_TIMEOUT_MS` tune the millisecond bounds, with hard maxima of 24 hours and 5 hours; a scheduled
+  job is additionally capped by its tick. `hara cron list` now makes active and timed-out work explicit.
+- **Cron timeout notifications survive transport outages and restarts.** Each outcome/threshold alarm is
+  committed with terminal state before delivery, keeps one stable idempotency key across bounded per-tick
+  retries, and is removed (with alert cooldown recorded) only after confirmed transport success. Each job's
+  queue is capped at 64: launches reserve room for outcome + alert, disable before overflow, and recovery may
+  compact only an old outcome while marking that loss explicitly; jobs.json also has schema/count/byte limits.
+  Configure the failure threshold with `--alert-after 1..1000` or the cron tool's `alertAfter` field.
+- **Cron recovery no longer mistakes PID reuse for a live owner forever.** The tick and synchronous jobs-store
+  locks use Linux/macOS process-birth identity; store commits additionally use a conservative renewable lease,
+  snapshot CAS, and a token fence.
+  Unknown identity formats and live legacy identity-less commit guards fail closed instead of being age-stolen.
+  A `running` record beyond the 24-hour hard job maximum plus grace is marked interrupted and disabled even if
+  its PID is alive. Recovery never kills or replays the possibly orphaned task; it persists the failure
+  notification for operator verification. Manual runs also refuse every unresolved `running` marker; if its
+  parent is dead, Hara records an interrupted/disabled state and requires operator inspection before retrying.
+- **Creation-minute cron jobs now use an explicit one-shot due marker.** A job added just after that minute's
+  OS tick runs once on the next tick, while disabling it clears the marker so a later enable cannot replay a
+  days- or months-old occurrence. Absolute one-shot schedules already in the past are rejected instead of being
+  displayed forever as a misleading next run.
+- **`hara resume <id>` now re-enters the correct runtime without blocking terminal input.** The launcher uses
+  the same runtime-aware self command as cron/gateway and waits asynchronously with inherited stdio: npm/Node
+  keeps its script entry, while a Bun-compiled standalone re-executes only the binary instead of treating its
+  virtual/user `argv[1]` as JavaScript. This removes the standalone resume hang/high-CPU/dead-input failure.
+- **The home directory is no longer an implicit repository.** Canonical/real-path checks suppress first-run
+  AGENTS generation and reject `hara init`, repo indexing, codebase search, and recursive grep/glob/inventory at
+  the Home root (including symlink aliases). Hara shows a `cd /path/to/project` hint; non-recursive `ls`, explicit
+  file reads, and explicitly selected child directories remain usable.
+- **Recursive project discovery is streaming and interruptible.** Glob/grep fallback, codebase search, semantic
+  indexing, recall, Desktop file lookup, did-you-mean, and `@dir` expansion share file, directory, Dirent, and
+  wall-clock bounds from the start of discovery. Cached empty-directory forests and a single extremely wide
+  directory can no longer block the event loop past the agent deadline; truncated indexes are never published.
+- **Windows shell and portable-home discovery are deterministic.** Hara probes the conventional Git Bash
+  installation paths before falling back to `cmd.exe`, understands MSYS drive paths and UNC paths, and honors an
+  explicit `HOME` ahead of `USERPROFILE` so portable/Git-Bash sessions do not silently load another profile.
+
+- **Long chat replies now split on natural line/word boundaries without tearing Unicode.** Feishu and
+  Telegram bubbles preserve the exact reply while keeping emoji ZWJ sequences, flags, combining marks, CRLF,
+  and surrogate pairs intact whenever the platform limit permits.
+- **Only one Hara gateway process may own a configured bot connection at a time.** A credential-scoped,
+  crash-safe private lease refuses a second live Feishu/Telegram/etc. connection and reclaims only a
+  proven-dead owner, preventing multiple WebSockets from replying to the same event.
+- **Stable inbound message ids are deduplicated across restarts.** Successfully handled Feishu and Telegram
+  ids are persisted for one hour in a byte- and count-bounded owner-only store; failures remain retryable,
+  concurrent duplicates and startup replays older than 30 seconds are ignored, and different bot credentials
+  use isolated stores. State contains ids/timestamps and a one-way connection namespace only—never message
+  text, user data, or credentials.
+- **Outbound chat transport is bounded and ordered across adapter instances.** Telegram and Feishu text/file
+  requests use real `AbortSignal` cancellation plus a hard 30s/120s ceiling; a credential-scoped, process-wide
+  per-chat lane prevents long multipart replies from interleaving with one-shot or flow delivery. A failed or
+  timed-out call settles for its caller without freezing shutdown or the inbound retry claim; an ambiguous
+  underlying transfer remains quarantined in that live process's lane until it actually settles.
+- **Flow side effects resume from durable receipts.** Each reply, notification target, and pending approval has
+  a stable, credential-scoped receipt. Redelivery skips locally completed receipts, pending actions reuse their
+  stable opaque id, and idempotency keys are forwarded where supported. A crash after remote acceptance but
+  before the local receipt commit can still cause at-least-once delivery on transports without server-side
+  deduplication. No-tool model decisions, bounded failure attempts, and partial target/chunk progress also
+  survive restarts, so a retry cannot mix a newly generated answer into an older partially delivered flow.
+- **Stable-id gateway events do not re-execute coding or stateful commands on delivery retry.** A private
+  started marker is durable before coding, tmux injection, `/new`, `/voice`, `/say`, or `/send`; completed
+  reply/file/default-voice bytes are durable before transport. Default voice retries therefore reuse the same
+  synthesized bytes instead of rerunning coding or TTS. Speech now has a 60-second default/120-second hard
+  deadline, propagates shutdown cancellation to remote requests, and terminates the full local
+  `say`/custom-command process tree.
+- **Interrupted gateway outcome markers have an explicit fail-closed recovery path.** A credential-scoped,
+  single-instance `hara gateway --recover-outcome ... --confirm-recovery terminalize:<id>` command releases one
+  abandoned active slot without rerunning its side effect; a separate exact confirmation can later delete only
+  an already-terminal tombstone. Running or unacknowledged completed records cannot be silently erased.
+- Feishu outbound REST now uses native abortable requests with an in-memory, early-refresh tenant-token cache;
+  the official SDK remains responsible for the inbound WebSocket/resource surface. Hara resolves mentions
+  from event metadata and drains tracked callbacks before releasing the single-instance lease on shutdown.
+
+## 0.122.3 — 2026-07-14 — standalone runtime recovery
+
+- **Bun-compiled standalone binaries no longer assume `SharedArrayBuffer` exists at module startup.**
+  The short synchronous waits used by cross-process stores now prefer `Bun.sleepSync`, lazily use
+  `Atomics.wait` only on Node when its primitives exist, and retain a bounded last-resort delay. This
+  fixes the macOS arm64 `ReferenceError` that could make the 0.122.2 standalone binary exit before
+  even printing `--version`; npm/Node and GHCR users were unaffected. CI now compiles and executes a
+  native standalone binary on Linux and macOS, and the release job executes its native Linux asset
+  before publishing, so a merely successful cross-compile is no longer accepted as runtime proof.
+
 ## 0.122.2 — 2026-07-14 — reproducible container release
 
 - **The Docker build now includes the guarded runtime entry before normalizing package modes.** This fixes the

package/README.md

@@ -175,6 +175,11 @@ hara --profile work        # use a named profile from ~/.hara/config.json
 hara -m glm-5              # pick a model
 ```
 
+Run Hara from a project directory. When the current directory resolves to your Home root, Hara does not treat
+the whole Home tree as a repository: project init/index and default recursive grep/glob/codebase inventory are
+disabled with a `cd /path/to/project` hint. Non-recursive `ls`, explicitly named files, and explicitly selected
+child directories still work.
+
 For automation, `--schema` accepts inline JSON Schema or a schema file. The model must return through the
 validated `structured_output` tool; on success stdout contains only the JSON value, while diagnostics go to
 stderr and missing/invalid output exits non-zero. `--role reviewer` resolves locally, `--role global:reviewer`
@@ -234,16 +239,24 @@ 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, `hara export [id] [--out file]` to render one as a Markdown transcript.
+**Sessions**: 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 `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.
-**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`.
+**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/webhook) for outcomes and `--alert-after N` for the consecutive-failure 🚨 threshold (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.
 **Work coordination**: `todo_write` is the agent's short, session-scoped checklist; it persists with that
 session and is isolated between simultaneous sub-agents and serve sessions. `task` is the durable project pool
 for work that outlives a conversation: add/update/list/remove items with `pending|in_progress|done`, an optional
 owner, and `blockedBy` dependencies. The private, atomic store is shared by concurrent hara processes for the
 same project and rejects missing/self/cyclic dependencies.
 **Notifications**: `hara config set notify bell` (terminal bell) or `notify system` (OS notification) pings you when a turn finishes — handy for long runs you've stepped away from. Gated on elapsed time so quick turns stay quiet; off by default.
+**Run limits and loop alarms**: every agent turn has a non-renewable 30-minute total deadline and a 64-round
+model/tool cap. Hara warns after five minutes or at 75% of the round budget, stops the third identical failing
+tool call, and surfaces the final reason in CLI, Desktop, or gateway output. Tune intentional long work with
+`hara config set runTimeoutMs 45m` (1s..2h) and `hara config set maxAgentRounds 96` (1..256), or
+`HARA_RUN_TIMEOUT_MS` / `HARA_MAX_AGENT_ROUNDS`; neither boundary can be disabled. Sub-agents are capped at
+8 minutes/24 rounds and inherit the parent's cancellation. Auxiliary model work (planning, verification,
+compaction, naming, commit messages, the guardian, and vision) has its own short hard deadline as well, so a
+provider that ignores cancellation cannot strand the CLI outside the main loop.
 **Hooks**: run your own shell commands around tool calls via a `"hooks"` map in global config; hooks from a reviewed project config require the launch-time `HARA_TRUST_PROJECT_CONFIG=1` opt-in. A **`PreToolUse`** hook can **veto** a call (non-zero exit blocks it; its output becomes the reason the model sees) — gate `bash`, forbid edits outside a path, require a clean tree. A **`PostToolUse`** hook observes (format/lint a file the agent just wrote, log, notify). Each has a `matcher` (regex/literal on the tool name, `*` = all) and gets `{tool, payload}` on stdin + `HARA_TOOL_NAME` in env. Plugins can contribute hooks too.
 Reviewer/read-only/plan runs and parallel read-only sub-agents suppress both hook phases: PreToolUse and
 PostToolUse commands are arbitrary shell, so either could otherwise bypass their read-only contract indirectly.

package/dist/agent/limits.js

@@ -0,0 +1,51 @@
+/** Hard lifecycle bounds for one agent run. These are deliberately independent of the provider's
+ * stream-idle watchdog and each tool's own timeout: activity must not be able to renew a run forever. */
+export const DEFAULT_AGENT_RUN_TIMEOUT_MS = 30 * 60_000;
+export const MAX_AGENT_RUN_TIMEOUT_MS = 2 * 60 * 60_000;
+export const MIN_AGENT_RUN_TIMEOUT_MS = 1_000;
+export const DEFAULT_AGENT_MAX_ROUNDS = 64;
+export const MAX_AGENT_MAX_ROUNDS = 256;
+export function parseAgentRunTimeoutMs(value) {
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : undefined;
+    if (typeof value !== "string")
+        return undefined;
+    const match = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m|h)?\s*$/i.exec(value);
+    if (!match)
+        return undefined;
+    const amount = Number(match[1]);
+    const unit = (match[2] ?? "ms").toLowerCase();
+    const multiplier = unit === "h" ? 3_600_000 : unit === "m" ? 60_000 : unit === "s" ? 1_000 : 1;
+    const parsed = amount * multiplier;
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+/** Parse a total run deadline. Invalid/zero values cannot disable the safety boundary. Human values such
+ * as `30m`, `90s`, and `1h` are accepted in config; HARA_RUN_TIMEOUT_MS also accepts plain milliseconds. */
+export function agentRunTimeoutMs(value = process.env.HARA_RUN_TIMEOUT_MS) {
+    const parsed = parseAgentRunTimeoutMs(value);
+    if (parsed === undefined || parsed <= 0)
+        return DEFAULT_AGENT_RUN_TIMEOUT_MS;
+    return Math.max(MIN_AGENT_RUN_TIMEOUT_MS, Math.min(MAX_AGENT_RUN_TIMEOUT_MS, Math.trunc(parsed)));
+}
+/** Maximum provider/tool rounds in one run. This catches active loops that never go silent. */
+export function agentMaxRounds(value = process.env.HARA_MAX_AGENT_ROUNDS) {
+    const parsed = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return DEFAULT_AGENT_MAX_ROUNDS;
+    return Math.max(1, Math.min(MAX_AGENT_MAX_ROUNDS, Math.trunc(parsed)));
+}
+export function formatAgentDuration(ms) {
+    if (ms >= 3_600_000 && ms % 3_600_000 === 0)
+        return `${ms / 3_600_000}h`;
+    if (ms >= 3_600_000)
+        return `${Math.round(ms / 360_000) / 10}h`;
+    if (ms >= 60_000 && ms % 60_000 === 0)
+        return `${ms / 60_000}m`;
+    if (ms >= 60_000)
+        return `${Math.round(ms / 6_000) / 10}m`;
+    if (ms >= 1_000 && ms % 1_000 === 0)
+        return `${ms / 1_000}s`;
+    if (ms >= 1_000)
+        return `${Math.round(ms / 1_000)}s`;
+    return `${ms}ms`;
+}