@nanhara/hara 0.53.0 → 0.67.0

package/CHANGELOG.md

@@ -5,6 +5,230 @@ All notable changes to `@nanhara/hara`.
 > Versioning (pre-1.0, SemVer-style): the **minor** (middle) number bumps for a **new feature**; the
 > **patch** (last) number bumps for **optimizations/fixes of existing features**.
 
+## 0.67.0 — unreleased (bounded parallel concurrency)
+
+- hara already runs work in parallel — fan-out **`agent`** sub-agents, concurrent read-kind tools in a turn,
+  and `hara plan --parallel` waves — but with **no cap**: the model spawning 20 `agent` calls in one turn
+  started 20 LLM loops at once (provider rate-limits / resource thrash). Now a **bounded pool** (`mapLimit`)
+  caps in-flight parallelism to **8** by default (tunable via `HARA_MAX_CONCURRENCY`), matching cc-haha's
+  safeguard (it caps at 10). Excess work queues and runs as slots free; ordering + behavior otherwise
+  unchanged. Applied to the loop's read/agent batch and the parallel-plan wave.
+
+## 0.66.0 — unreleased (B-end: device enrollment + `hara-gateway` provider)
+
+- First slice of the **B-end** (fleets / control plane): `hara enroll <gateway-url> --code <code>` trades a
+  one-time code for a scoped, revocable **device token** (stored `0600` in `~/.hara/org.json`) and switches
+  hara to the new **`hara-gateway`** provider — an OpenAI-compatible client pointed at your org's gateway.
+  **The real provider key never touches the device** (it stays at the gateway). A heartbeat fires on start
+  for fleet visibility; `--status` / `--clear` manage it. The device↔gateway protocol (enroll / heartbeat /
+  OpenAI-compatible proxy) is documented in `docs/b-end.md` and **verified end-to-end against a stub control
+  plane**. The control-plane server (`hara-control`) + the LiteLLM data-plane are the next, separate increment.
+
+## 0.65.0 — unreleased (frontmatter-aware asset recall)
+
+- Asset/skill recall (`searchAssets`, behind `hara recall` / `/recall` / skill dedup) now **ranks by the
+  asset's declared dimensions** — a query word in the `title` or the frontmatter `tags`/`lang` counts more
+  than one buried in the body. The asset format already declared these (the scaffold seeds `tags`/`lang`);
+  retrieval now actually uses them. The base relevance score (distinct query words present) is unchanged,
+  so the dedup-before-save threshold is unaffected — this only improves *ordering*. (Studied codex + cc-haha:
+  both stay lexical + manual-file curation with no semantic search or auto-capture; hara's hybrid lexical+
+  opt-in-semantic recall over a unified skills/code-assets/memory corpus is already ahead.)
+
+## 0.64.0 — unreleased (session export)
+
+- **`hara export [session] [--out file]`** renders a saved session to a Markdown transcript — the header
+  (title/model/cwd/date), each turn (you / hara), tool calls inline, and tool results in collapsible
+  `<details>` blocks (capped). Default is the latest session in the current directory. For sharing a
+  decision, pasting into a PR, or archiving. Pure renderer (`src/export.ts`), unit-tested.
+
+## 0.63.0 — unreleased (first-run setup wizard)
+
+- **`hara setup`** — an interactive wizard (provider → optional base URL → API key → model) that writes
+  `~/.hara/config.json` (0600), so a new user doesn't have to know the individual `hara config set` keys.
+  It's also **auto-offered** when you start `hara` unconfigured ("Not authenticated — run setup now?")
+  instead of just erroring. TTY-only (scripts get a clear pointer to `hara config set`).
+
+## 0.62.0 — unreleased (shell completions)
+
+- **`hara completions bash|zsh|fish`** prints a completion script (eval it in your shell rc) that
+  tab-completes the top-level subcommands and the subcommands of each group (`cron`, `memory`, `plugin`,
+  `roles`, `skills`, `config`), falling back to file completion. Generated from the live command tree so it
+  never drifts; hand-rolled (no new dependency).
+
+## 0.61.3 — unreleased (audit follow-through: session robustness + SECURITY.md)
+
+- **Corrupt/hand-edited session files no longer crash** `--resume` or `/sessions` (audit M4): `loadSession`
+  validates the shape (meta object + history array), `deriveTitle` tolerates a non-string, and `listSessions`
+  skips metaless files instead of throwing.
+- New **`SECURITY.md`** — the threat model, the controls (approval gate, read-only sub-agents, write-confinement
+  sandbox, `web_fetch` SSRF guard, 0600 secrets, plugin trust), what is deliberately *not* a security boundary,
+  and how to report a vulnerability. Captures the posture from the two audit passes.
+
+## 0.61.2 — unreleased (security hardening — second audit: SSRF, RPA, secrets)
+
+A second audit (RPA / network / auth / search) found more real issues; fixed:
+- **`web_fetch` SSRF (critical).** It would fetch any host — incl. `169.254.169.254` (cloud metadata),
+  `localhost`/`127.0.0.1` internal services, and private ranges — and followed redirects blindly. Now it
+  **refuses private/loopback/link-local/CGNAT targets** (resolving the hostname first), **re-checks on every
+  redirect hop** (manual redirects), and reads the body under a **byte ceiling** (no multi-GB / bomb body).
+- **`computer` "don't ask again" defeated the per-action grant (high).** Screen control is supposed to
+  confirm every action; the shared "always" approval silently auto-approved all future clicks/types. Now
+  `computer` is **never** satisfied by a prior "always" — it always prompts.
+- **Key blocklist bypassable (high).** It only caught spelled-out combos, so Windows SendKeys `%{F4}`/`^w`
+  and Linux `XF86LogOff`/`XF86PowerOff` slipped through. Now caught on all three platforms (bare editing
+  keys like Delete stay allowed).
+- **Secrets could be embedded into the semantic index (medium).** The asset/skill/memory dirs aren't
+  `.gitignore`-filtered, so a stray `credentials.json`/`secrets.yaml` there could be POSTed to the embedding
+  provider + persisted. Now secret-named files are skipped in both index collectors.
+- **Token/config files were world-readable (medium).** `~/.hara/qwen-oauth.json` (access+refresh tokens)
+  and `~/.hara/config.json` (`apiKey`) are now written **0600** (and tightened on save).
+- **RPA app allowlist was substring-matched (low).** `"Notes"` matched `"Notes - Evil"`; now an exact
+  (case-insensitive) frontmost-app match.
+
+The RPA + clipboard shell-outs were confirmed injection-safe (argv arrays, JSON-quoted scripts). 198 tests
+(2 new: the SSRF private-IP guard + the widened key blocklist).
+
+## 0.61.1 — unreleased (security + correctness hardening — core audit)
+
+A security/correctness audit of the core (sandbox, confirmation gate, file tools, MCP client) found real
+issues; fixed:
+- **Confirmation-gate bypass via sub-agents (critical).** The read-kind `agent` tool never prompts, yet
+  spawned sub-agents ran **full-auto, unconfirmed** — so a role granting `edit_file`/`bash` let a fan-out
+  sub-agent mutate files / run shell with no approval, even in `suggest` mode. Sub-agents are now **always
+  read-only** (a role may narrow further but can never grant write/exec — `subagentToolFilter`). Write-capable
+  roles run in the main loop via `hara org`, behind the gate.
+- **`apply_patch` wasn't actually atomic (critical / data-loss).** It claimed all-or-nothing but Phase 2 wrote
+  files sequentially — a mid-way failure left a half-patched tree with no undo. Now it **rolls back** every
+  applied write on any failure (restores updated/deleted, removes created), so it's truly all-or-nothing.
+- **Sandbox honesty.** It's **file-write confinement only** (not reads/network/exec; `/private/tmp` stays
+  writable) — clarified in the header, `--sandbox` docs, and label so it no longer oversells containment.
+- The non-macOS "runs unsandboxed" warning now fires from `runShell` (every entry point: `-p`, org, cron),
+  not just the REPL; a runaway `bash` whose output exceeds `maxBuffer` is now **killed** (not streamed to
+  the timeout); and `hara plugin add` now **shows the commands a plugin will run** on every launch (its MCP
+  servers + hooks are arbitrary code — surface the trust surface).
+
+196 tests (2 new: the sub-agent read-only guard + the apply_patch rollback). The edit tools, hooks matcher,
+and sandbox profile-injection safety were audited and confirmed solid.
+
+## 0.61.0 — unreleased (`hara memory` — inspect + distill durable memory)
+
+- New **`hara memory`** command group, giving memory a CLI surface it lacked:
+  - **`hara memory show`** — print the digest injected at session start (what the agent actually sees).
+  - **`hara memory init`** — scaffold the global + project memory dirs/seed files.
+  - **`hara memory distill [--days N] [--scope global|project|all]`** — **promote short-term → long-term**:
+    consolidate recent daily logs (`log/YYYY-MM-DD.md`) into durable `MEMORY.md`/`USER.md`, deduped against
+    what's already there, skipping the ephemeral. This closes the one tiering gap the PAI/hermes study
+    surfaced (the daily-log tier was previously write-only). The agent routes each fact to the right
+    target/scope (user pref → `USER.md`, project fact → project memory). Verified live with glm-5.
+- `.hara/` is now gitignored in this repo so dogfooding doesn't leave runtime state (memory/roles/plans).
+
+## 0.60.2 — unreleased (memory digest: per-source budgets)
+
+- After studying the PAI and hermes memory systems (both lexical-first; both treat vectors as an *optional*
+  optimization, not a requirement — which validates hara's design), tightened the frozen-snapshot digest:
+  the old `slice(0, 4000)` on the **concatenated** sources could cut an entry mid-line and let a large
+  project `MEMORY.md` **crowd `USER.md` out entirely**. Each source (project MEMORY / global MEMORY / USER)
+  now gets its **own** budget and is truncated at a **line boundary**, so high-value user prefs are always
+  injected and no entry is split. The rest stays reachable via `memory_search` (which is already hybrid
+  lexical + opt-in semantic). No behavior change when memory is small.
+
+## 0.60.1 — unreleased (cron hardening — from a code-review pass)
+
+A review of the fast-built `hara cron` module surfaced real bugs; fixed:
+- **Malformed cron expressions were silently accepted** (`Number("")===0` etc.) — `"0 9 * * 1,"`, `"/5 * * * *"`, `"5/"` parsed as valid jobs that fire at the wrong time. Now strictly validated and rejected; `N/step` correctly extends to max (Vixie semantics).
+- **`hara cron install` could emit a broken plist/crontab** when a path contained `&`/`<`/`>` (launchd XML) or a space/metacharacter (crontab shell line). Now XML-escaped / shell-quoted, and an install is refused if a path contains a newline.
+- **Per-job logs grew unbounded** — capped to the last ~256KB once over ~1MB.
+- **The tick lock could poison the scheduler for 30 min after a crash, or double-fire a long job** — now keyed on PID liveness (a dead owner is taken over within one tick; a live owner is respected for long runs).
+- **An ambiguous id-prefix silently deleted/toggled the *first* match** — `cron remove/enable/disable/run/logs` now error on an ambiguous prefix instead of guessing.
+
+The vim reducer, type-ahead steering, Anthropic message coalescing, the MCP allowlist, and the binary build were reviewed and confirmed clean. 192 tests (4 new hardening cases).
+
+## 0.60.0 — unreleased (single-binary distribution)
+
+- **Standalone binaries** — hara can now be a single self-contained executable (no Node required):
+  `curl -fsSL .../install.sh | sh`. Built with `bun build --compile` (`npm run build:binary`, or
+  `build:binaries` to cross-compile darwin-arm64/x64 + linux-x64/arm64 from one machine). A tagged
+  release (`.github/workflows/release.yml`) builds + attaches them; `install.sh` grabs the right one.
+- Build fixes for the bundled binary: a Bun plugin **stubs ink's dev-only `react-devtools-core`** (lazy-
+  imported under `DEV`, never in production) so it bundles clean; the version is **baked in via a build
+  define** (a compiled binary has no `package.json` to read at runtime); and cron's self-reinvoke now
+  detects script-vs-binary mode (`selfArgv`) so `hara cron` works from the binary too. The 60 MB binaries
+  are kept out of the npm tarball (`!dist/bin`), which stays ~140 kB.
+
+## 0.59.0 — unreleased (vim keybindings in the input box)
+
+- **Vim mode** (opt-in: `hara config set vimMode true`, or `HARA_VIM=1`). The TUI prompt becomes modal —
+  **Esc** → normal, **i/a/I/A/o** → insert. Normal-mode motions `h l 0 $ w b e` (+ `gg`/`G`), edits
+  `x D C dd cc dw cw`, and paste `p`/`P` with a delete/yank register. A distinct prompt marker (`◆` yellow)
+  + a `-- NORMAL -- / -- INSERT --` hint show the mode. Off by default (normal typing is unchanged). The
+  editing logic is a pure reducer (`src/tui/vim.ts`), fully unit-tested; `hara doctor` shows the input mode.
+
+## 0.58.0 — unreleased (`hara cron` — scheduled tasks)
+
+- **Scheduled tasks.** `hara cron add "<schedule>" "<task>"` runs a task on a schedule — the fired job is a
+  fresh `hara` session (the run *is* the agent, like openclaw/hermes). Schedules: a 5-field **cron expr**
+  (`"0 9 * * 1-5"`), an **interval** (`"every 30m"`), or a **one-shot** (`"in 2h"` / an ISO timestamp).
+  `--org` routes it through the role org instead of a plain prompt.
+- **Fires via your OS, no daemon to babysit.** `hara cron install` registers a per-minute `hara cron tick`
+  with **launchd** (macOS) or **crontab** (Linux); `tick` runs whatever's due (lock-guarded so a slow job
+  doesn't double-fire) and logs each run. Manage with `hara cron list / run <id> / enable / disable /
+  remove / logs / uninstall`. Jobs persist atomically in `~/.hara/cron/jobs.json`; `hara doctor` shows the
+  count + scheduler status. Cron matching is hand-rolled (no new dependency), minute-granular, local-time.
+
+## 0.57.0 — unreleased (in-session `/diff`, `/review`, `/commit` in the TUI)
+
+- The default TUI now wires three more slash commands so the **change → review → commit** loop happens
+  in-session instead of dropping to a subcommand (they used to print "isn't wired into the TUI yet"):
+  - **`/diff`** — show the working-tree diff vs HEAD (`/diff staged` for the index), rendered as a colored diff block. No model call.
+  - **`/review`** — a senior-reviewer pass over `git diff HEAD` (read-only), streamed inline.
+  - **`/commit`** — stage everything and commit with an AI-written message (reuses the review→commit machinery).
+  Reuses existing, already-verified pieces (`autoCommit`, `REVIEW_SYSTEM`, `runShell`). Other subcommands
+  (`init`/`index`/`plan`/`org`/…) still point you to `hara <cmd>` or `HARA_TUI=0`.
+
+## 0.56.0 — unreleased (review → commit capstone + robust verdict parsing)
+
+- **`hara org --review --commit`** closes the loop: once the reviewer approves, hara stages the work and
+  commits it with an AI-written message (reusing `hara commit`'s generation). **Guarded** — it only
+  auto-commits when the working tree was **clean before the run** (so it captures this run's work, never
+  pre-existing WIP), and with `--review` only **after approval** (a review that doesn't pass leaves the
+  changes in your tree, uncommitted). `--commit` works without `--review` too (commit the implementer's
+  result). Verified live end-to-end: implement → review → approve → `✓ committed`.
+- **Robust verdict parsing** (hardening v0.55, found via live smokes). Real models don't emit the literal
+  `VERDICT: APPROVED` token — across runs glm-5 wrote `**VERDICT**: No issues found`, `**VERDICT**: PASS`,
+  and `VERDICT: LGTM`. The parser now anchors on a markdown-tolerant `VERDICT` marker and **classifies the
+  phrase after it** (approve vs changes synonyms), with a changes-signal veto and an ambiguous-→-not-approved
+  safe default (worst case is one extra review round, never a bad auto-commit). `not approved` correctly
+  vetoes despite containing "approv". Unit tests now cover the exact shapes seen in live runs.
+
+## 0.55.0 — unreleased (multi-role review chain — `hara org --review`)
+
+- **Review chains** — `hara org --review "<task>"` runs the org like an actual engineering team: the owning
+  role implements, then a **reviewer** role inspects the diff and either **approves** or sends it back with
+  concrete fixes, looping implement → review → fix until approved or a round cap (`--rounds`, default 3).
+  This is hara's differentiation — not "one agent + temp sub-agents" but roles that hold each other to a
+  bar. The reviewer is read-only (uses your `reviewer` role if defined, else a built-in persona) and ends
+  with a machine-parseable `VERDICT: APPROVED | CHANGES_REQUESTED`; on changes-requested the issues feed
+  back into the implementer's own conversation so it keeps context. New `src/org/review-chain.ts` (verdict
+  parsing, non-destructive `git diff HEAD` capture, prompts) — all unit-tested. **Verified live end-to-end**
+  (implementer edits a file → reviewer approves → loop exits).
+
+## 0.54.0 — unreleased (`hara mcp` — run hara as an MCP server)
+
+- **MCP server mode** — `hara mcp` runs hara as an MCP server over stdio, so other MCP clients (Claude
+  Desktop, Cursor, another hara…) can call its tools. hara was already an MCP *client*; this completes
+  the loop. The high-value one is **`codebase_search`** — point any MCP client at a repo and it gets
+  hara's semantic/lexical code search, plus `read_file`/`grep`/`glob`/`ls`/`web_fetch`/`web_search`.
+  **Read-only by default** — no `edit_file`/`bash`/`computer`, so an external client can't mutate your
+  machine through hara; override the exposed set with `HARA_MCP_TOOLS=a,b,c` at your own risk. Reuses
+  hara's tool registry (`src/mcp/server.ts`, built on `@modelcontextprotocol/sdk` — already a dep).
+  Verified end-to-end (a real MCP client lists the tools + calls `ls`/`codebase_search`). `hara doctor`
+  now shows both the client (servers connected) and serve (tools exposed) sides.
+
+  ```jsonc
+  // e.g. in a client's mcpServers config:
+  "hara": { "command": "hara", "args": ["mcp"] }   // run from the repo you want searchable
+  ```
+
 ## 0.53.0 — unreleased (task-done notifications + steering in plan mode)
 
 - **Notifications** — get pinged when a turn finishes so you can walk away during a long run

package/README.md

@@ -11,7 +11,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.
 - **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.
-- **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).
+- **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.
 - **Solid coding core** — `edit_file` / `apply_patch` (atomic multi-file) with colored diffs · `grep`/`glob`/`ls`/`codebase_search` (lexical + optional semantic search over the repo) /`web_fetch` · fuzzy `@file` · `/undo` · `/compact` · **Esc-to-interrupt** · parallel sub-agents · MCP client · macOS sandbox.
 
@@ -23,6 +23,14 @@ Track it: https://github.com/hara-cli/hara · https://hara.run
 npm i -g @nanhara/hara
 ```
 
+Or a **standalone binary** (no Node required):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/hara-cli/hara/main/install.sh | sh
+```
+
+Tab completion (optional): `eval "$(hara completions zsh)"` in your `~/.zshrc` (or `bash`/`fish`).
+
 Or from source:
 
 ```bash
@@ -51,7 +59,9 @@ hara -p "summarize @README.md and list any TODOs"
 
 ## Setup
 
-hara is **multi-provider** — pick a provider + key.
+The fastest path is **`hara setup`** — an interactive wizard for provider + key + model (it also runs
+automatically the first time you start `hara` unconfigured). Or configure it yourself — hara is
+**multi-provider**:
 
 **Anthropic (default)**
 ```bash
@@ -171,14 +181,16 @@ vector DB needed, and lexical still works when there's no index. Re-running `har
 only changed files re-embed (a full repo rebuild that takes ~a minute re-runs in well under a second).
 
 **Approval modes**: `suggest` confirms edits & shell · `auto-edit` auto-applies file edits but confirms shell · `full-auto` runs everything.
-**Sandbox** (macOS): `--sandbox workspace-write|read-only` runs the `bash` tool under Seatbelt (writes confined to the project / blocked).
+**Sandbox** (macOS): `--sandbox workspace-write|read-only` runs the `bash` tool under Seatbelt — **file-write confinement** (writes confined to the project / blocked). It does not restrict reads, network, or process exec; on non-macOS the shell runs unsandboxed (with a warning).
 **Screen control** (opt-in): the `computer` tool drives desktop software (screenshot → click/type), native per OS
 (mac `screencapture`+`cliclick` · Windows PowerShell · Linux `scrot`+`xdotool`). Off by default — enable a tier with
 `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.
-**MCP**: add an `mcpServers` map to config (global or project `.hara/config.json`); their tools appear to the agent as `mcp__<server>__<tool>`.
+**Sessions**: conversations are saved automatically — `-c` / `--resume <id>` to continue, `hara sessions` to list, `hara export [id] [--out file]` to render one as a Markdown transcript.
+**MCP**: add an `mcpServers` map to config (global or project `.hara/config.json`); their tools appear to the agent as `mcp__<server>__<tool>`. hara can also **be** an MCP server — `hara mcp` exposes its read/search tools (esp. **`codebase_search`**) over stdio so other clients (Claude Desktop, Cursor, another hara) can use them; read-only by default (`HARA_MCP_TOOLS` to override).
+**Vim mode**: `hara config set vimMode true` makes the prompt modal — Esc → normal, `i/a/A/I` insert, `h l 0 $ w b e` motions, `x D C dd cw p` edits. Off by default.
+**Scheduled tasks**: `hara cron add "0 9 * * 1-5" "<task>"` (or `"every 30m"`, `"in 2h"`) runs a task on a schedule — each run is a fresh hara session. `hara cron install` wires a per-minute tick into launchd/crontab (no daemon); `--org` routes through the role org. Manage with `hara cron list/run/enable/disable/remove/logs`.
 **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.
 **Hooks**: run your own shell commands around tool calls via a `"hooks"` map in config. 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.
 **Profiles**: add a `profiles` map to `~/.hara/config.json` (`--profile <name>`), or drop a project-level `.hara/config.json` that overrides the global config.
@@ -189,9 +201,13 @@ Define role-agents in `.hara/roles/*.md` — each is a persona (the file body) p
 (keywords that route a task here), optional `rejects`, `model`, and `allowTools`/`denyTools`. `hara org
 "<task>"` routes the task to the role that **owns** it (keyword match, LLM fallback) and runs that role's
 agent — e.g. a read-only `reviewer` that reports issues vs an `implementer` that edits code. `hara roles`
-lists them, `hara roles init` scaffolds a starter set, and `--role <id>` forces a specific role. The
+lists them, `hara roles init` scaffolds a starter set, and `--role <id>` forces a specific role. Add
+**`--review`** and the org works like a team: the owning role implements, then a **reviewer** role inspects
+the diff and either approves or sends it back with fixes — looping implement → review → fix until approved
+(or `--rounds N`). Add **`--commit`** and it commits the approved result with an AI-written message (guarded
+to a clean start tree; a review that doesn't pass leaves the work uncommitted). The
 **`agent`** tool spawns **parallel read-only sub-agents** for fan-out — analyze / review / search
-several things at once (each can take a `role`).
+several things at once (each can take a `role`), bounded to 8 concurrent (`HARA_MAX_CONCURRENCY`).
 
 Beyond routing, **`hara plan "<task>"`** makes the org *plan*: it decomposes the task into atoms,
 sequences them as a DAG, and executes each step (optionally routed to a role) behind a per-step
@@ -209,7 +225,7 @@ A streaming agentic loop with built-in tools — `read_file`, `write_file`, **`e
 read-only **`grep`** / **`glob`** / **`ls`** / **`web_fetch`** — behind a human-in-the-loop confirmation gate on the
 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.
+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.
 - **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.
@@ -217,8 +233,12 @@ turn, or **`/undo`** to revert the last edit.
 
 ### Roadmap
 
-**Shipped:** ink TUI · plan mode · persistent memory + self-evolution · atomization planner · parallel sub-agents · `/compact` context management.
-**Next:** parallel plan atoms · multi-role review chains · cron autonomy for the org · single-binary distribution · an enterprise control-plane (fleet + central token management).
+**Shipped:** ink TUI · plan mode · persistent memory + self-evolution · atomization planner · parallel plan atoms · **multi-role review chains** · parallel sub-agents · MCP client *and* server · **scheduled tasks (`hara cron`)** · **single-binary distribution** · `/compact` context management.
+**Next:** SSOT data authority · an enterprise control-plane (fleet + central token management).
+
+## Security
+
+Human-in-the-loop by default, with a layered model (approval gate · read-only sub-agents · write-confinement sandbox · `web_fetch` SSRF guard · `0600` secrets · reviewed plugin trust). Threat model, controls, and how to report a vulnerability: **[SECURITY.md](SECURITY.md)**.
 
 ## License
 

package/SECURITY.md

@@ -0,0 +1,54 @@
+# Security
+
+hara is a coding agent that reads/writes files, runs shell commands, drives a browser/desktop, and calls
+LLMs — so it takes a layered, **human-in-the-loop-by-default** stance. This documents the threat model, the
+controls, what is deliberately *not* a security boundary, and how to report a vulnerability.
+
+## Threat model
+
+hara runs on **your** machine under **your** account, on code **you** point it at. It is not a multi-tenant
+sandbox. The adversary we defend against is primarily **the model going wrong** — a bad suggestion, a
+prompt-injected web page or file steering it toward a destructive or exfiltrating action — not a malicious
+local user (who already has your shell).
+
+## Controls
+
+- **Approval gate.** Every file edit, shell command, and screen action is classified (`read` / `edit` /
+  `exec` / `computer`) and gated by an approval mode: `suggest` (confirm edits & commands), `auto-edit`
+  (auto-apply edits, confirm commands), `full-auto` (no prompts — opt-in). Read-only tools never prompt.
+- **Screen control is gated on *every* action.** The `computer` tool always asks before each click/type,
+  even in `full-auto`, and "don't ask again" never applies to it. Guarded further by a frontmost-app
+  **allowlist** (exact match), a dangerous-key **blocklist** (quit/close/logout across macOS/Windows/Linux
+  syntaxes), and a per-session grant. Off by default.
+- **Sub-agents are read-only.** The parallel `agent` fan-out tool runs sub-agents that can never edit or run
+  shell — a role may *narrow* their tools but never *grant* write/exec. Write-capable roles run in the main
+  loop (`hara org`), behind the gate.
+- **Shell sandbox (macOS).** `--sandbox workspace-write|read-only` runs the `bash` tool under Seatbelt —
+  **file-write confinement** (see the non-boundary note below). Commands/paths are passed as argv / a profile
+  file, not interpolated into a shell string.
+- **`web_fetch` SSRF guard.** Refuses to fetch private / loopback / link-local / CGNAT addresses (resolving
+  the hostname first), re-checks on every redirect hop, and reads the body under a byte ceiling — so the
+  model can't reach cloud-metadata endpoints or internal services.
+- **Secrets.** `~/.hara/config.json` (API keys) and `~/.hara/qwen-oauth.json` (tokens) are written `0600`.
+  The optional semantic index respects `.gitignore` and skips secret-named files, so keys aren't embedded or
+  sent to an embedding provider. The memory guard screens secret-shaped strings out of what the agent saves.
+- **Plugins are code you trust.** Installing a plugin (`hara plugin add`) grants its author code execution:
+  its MCP servers and hooks run shell commands on launch. `hara plugin add` **prints the exact commands** a
+  plugin will run so you can review them; disable with `hara plugin disable <name>`.
+- **Coding-plan keys.** Provider keys you configure are used only to call the model endpoint you set.
+
+## What is *not* a security boundary
+
+- **The sandbox confines file writes only** — not reads, not network, not process exec; `/private/tmp`
+  stays writable. It stops a stray `rm`/overwrite escaping the project, not a determined exfiltration. Treat
+  a `full-auto` + network-capable shell as able to read and send anything your account can.
+- **`@file` mentions** read any file *you* name (including outside the project) — that's you attaching
+  context, not the model exfiltrating; mentions are expanded on your typed input only, never on model output.
+- **`full-auto` / `-y`** removes the human gate by your explicit choice. Use it on code and in directories
+  you trust.
+
+## Reporting a vulnerability
+
+Please report security issues privately — open a GitHub **security advisory** on `hara-cli/hara`, or email
+the maintainers — rather than a public issue. Include a minimal reproduction and the impact. We'll
+acknowledge, fix, and credit you.

package/dist/agent/loop.js

@@ -5,6 +5,7 @@ import { activity } from "../activity.js";
 import { makeRenderer } from "../md.js";
 import { skillsDigest } from "../skills/skills.js";
 import { runHooks } from "../hooks.js";
+import { mapLimit, maxParallel } from "../concurrency.js";
 /** Whether a tool call needs user confirmation under the given approval mode. */
 export function needsConfirm(kind, mode) {
     if (kind === "read")
@@ -136,14 +137,16 @@ export async function runAgent(history, opts) {
             const preview = String(input.path ?? input.command ?? input.pattern ?? input.url ?? input.task ?? "")
                 .replace(/\s+/g, " ")
                 .trim();
-            if (needsConfirm(tool.kind, opts.approval) && !opts.autoApprove?.has(tu.name)) {
+            // Screen control is gated on EVERY action — a prior "don't ask again" must never satisfy it.
+            const alwaysGate = tool.kind === "computer";
+            if (needsConfirm(tool.kind, opts.approval) && (alwaysGate || !opts.autoApprove?.has(tu.name))) {
                 const reply = await opts.confirm(`${c.yellow("⚠")}  ${c.bold(tu.name)} ${c.dim(preview)} — run?`);
                 if (reply === false) {
                     plans.push({ tu, tool, denied: "User denied this action." });
                     continue;
                 }
-                if (reply === "always")
-                    opts.autoApprove?.add(tu.name);
+                if (reply === "always" && !alwaysGate)
+                    opts.autoApprove?.add(tu.name); // computer: treat "always" as one-time yes
             }
             plans.push({ tu, tool });
             if (!opts.quiet) {
@@ -179,21 +182,25 @@ export async function runAgent(history, opts) {
                 activity.dec();
             }
         };
-        let batch = [];
+        let batch = []; // indices of pending read-kind tools (run concurrently, capped)
+        const flush = async () => {
+            if (!batch.length)
+                return;
+            const idx = batch;
+            batch = [];
+            await mapLimit(idx, maxParallel(), (i) => runOne(i, plans[i])); // bounded fan-out (e.g. 20 parallel agents → 8 at a time)
+        };
         for (let i = 0; i < plans.length; i++) {
             const p = plans[i];
             if (p.denied === undefined && p.tool?.kind === "read") {
-                batch.push(runOne(i, p)); // safe → accumulate to run concurrently
+                batch.push(i); // safe → accumulate to run concurrently
             }
             else {
-                if (batch.length) {
-                    await Promise.all(batch); // flush pending reads before an edit/exec
-                    batch = [];
-                }
+                await flush(); // flush pending reads before an edit/exec
                 await runOne(i, p);
             }
         }
-        await Promise.all(batch);
+        await flush();
         history.push({ role: "tool", results });
     }
 }

package/dist/completions.js

@@ -0,0 +1,49 @@
+// Shell completion scripts (bash / zsh / fish), generated from the command tree so they never drift.
+// `hara completions <shell>` prints one; the user evals it in their shell rc. Completes the top-level
+// subcommands, the subcommands of each group (cron/memory/plugin/roles/skills/config), and falls back to
+// file completion otherwise. Hand-rolled (no dependency) — same minimal-deps philosophy as the rest.
+const bash = ({ top, subs }) => {
+    const cases = Object.entries(subs)
+        .map(([cmd, sub]) => `    ${cmd}) COMPREPLY=( $(compgen -W "${sub.join(" ")}" -- "$cur") ); return;;`)
+        .join("\n");
+    return `# hara bash completion — add to ~/.bashrc:  eval "$(hara completions bash)"
+_hara() {
+  local cur prev; cur="\${COMP_WORDS[COMP_CWORD]}"; prev="\${COMP_WORDS[1]}"
+  if [ "$COMP_CWORD" -eq 1 ]; then COMPREPLY=( $(compgen -W "${top.join(" ")}" -- "$cur") ); return; fi
+  case "$prev" in
+${cases}
+    *) COMPREPLY=( $(compgen -f -- "$cur") );;
+  esac
+}
+complete -F _hara hara
+`;
+};
+const zsh = ({ top, subs }) => {
+    const cases = Object.entries(subs)
+        .map(([cmd, sub]) => `    ${cmd}) compadd -- ${sub.join(" ")} ;;`)
+        .join("\n");
+    return `# hara zsh completion — add to ~/.zshrc:  eval "$(hara completions zsh)"
+_hara() {
+  if (( CURRENT == 2 )); then compadd -- ${top.join(" ")}; return; fi
+  case "\${words[2]}" in
+${cases}
+    *) _files ;;
+  esac
+}
+compdef _hara hara
+`;
+};
+const fish = ({ top, subs }) => {
+    const lines = [
+        "# hara fish completion — save to ~/.config/fish/completions/hara.fish:  hara completions fish > ~/.config/fish/completions/hara.fish",
+        "complete -c hara -f",
+        `complete -c hara -n __fish_use_subcommand -a "${top.join(" ")}"`,
+        ...Object.entries(subs).map(([cmd, sub]) => `complete -c hara -n "__fish_seen_subcommand_from ${cmd}" -a "${sub.join(" ")}"`),
+    ];
+    return lines.join("\n") + "\n";
+};
+/** Render the completion script for a shell, or null if the shell isn't supported. */
+export function completionScript(shell, tree) {
+    const gen = { bash, zsh, fish };
+    return gen[shell] ? gen[shell](tree) : null;
+}

package/dist/concurrency.js

@@ -0,0 +1,22 @@
+// Bounded-concurrency map: run `fn` over `items` with at most `limit` in flight at once, preserving input
+// order in the results. Used to cap parallel sub-agents / read-tools / plan atoms so a wide fan-out (the
+// model spawning 20 `agent` calls in one turn) doesn't hammer the provider's rate limits or thrash the box.
+// cc-haha caps tool concurrency at 10; hara defaults to 8, tunable via HARA_MAX_CONCURRENCY.
+export function maxParallel() {
+    const n = Number(process.env.HARA_MAX_CONCURRENCY);
+    return Number.isInteger(n) && n >= 1 ? n : 8;
+}
+export async function mapLimit(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        for (;;) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            results[i] = await fn(items[i], i);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(Math.max(1, limit), items.length) }, worker));
+    return results;
+}

package/dist/config.js

@@ -1,6 +1,6 @@
 import { homedir } from "node:os";
 import { join, dirname, resolve } from "node:path";
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from "node:fs";
 const PROVIDER_DEFAULTS = {
     anthropic: { model: "claude-opus-4-8", envKey: "ANTHROPIC_API_KEY" },
     qwen: {
@@ -10,8 +10,9 @@ const PROVIDER_DEFAULTS = {
     },
     "qwen-oauth": { model: "coder-model", envKey: "QWEN_OAUTH_TOKEN" },
     openai: { model: "gpt-4o-mini", envKey: "OPENAI_API_KEY" },
+    "hara-gateway": { model: "", envKey: "HARA_GATEWAY_TOKEN" }, // B-end: enrolled device → token in ~/.hara/org.json, routed by the gateway
 };
-export const CONFIG_KEYS = ["provider", "apiKey", "model", "baseURL", "approval", "sandbox", "theme", "evolve", "assetCapture", "computerUse", "computerApps", "visionModel", "visionBaseURL", "visionApiKey", "embedProvider", "embedModel", "embedBaseURL", "embedApiKey", "notify"];
+export const CONFIG_KEYS = ["provider", "apiKey", "model", "baseURL", "approval", "sandbox", "theme", "evolve", "assetCapture", "computerUse", "computerApps", "visionModel", "visionBaseURL", "visionApiKey", "embedProvider", "embedModel", "embedBaseURL", "embedApiKey", "notify", "vimMode"];
 export const APPROVAL_MODES = ["suggest", "auto-edit", "full-auto"];
 export const SANDBOX_MODES = ["off", "workspace-write", "read-only"];
 const PROJECT_ROOT_MARKERS = [".git", "package.json", "Cargo.toml", "go.mod", "pyproject.toml", ".hg"];
@@ -51,12 +52,22 @@ function readProjectConfig(cwd) {
     }
     return {};
 }
+/** Write the config 0600 (it can hold `apiKey`) + tighten an existing file. */
+function persistConfig(p, cfg) {
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+    try {
+        chmodSync(p, 0o600);
+    }
+    catch {
+        /* best-effort */
+    }
+}
 export function writeConfigValue(key, value) {
     const p = configPath();
     const cfg = readRawConfig();
     cfg[key] = value;
-    mkdirSync(dirname(p), { recursive: true });
-    writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+    persistConfig(p, cfg);
 }
 /** Record (or clear, with cap=null) a confirmed per-model vision capability in `modelVision`. */
 export function setModelVisionOverride(model, cap) {
@@ -68,8 +79,7 @@ export function setModelVisionOverride(model, cap) {
     else
         map[model] = cap;
     cfg.modelVision = map;
-    mkdirSync(dirname(p), { recursive: true });
-    writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+    persistConfig(p, cfg);
 }
 /**
  * Effective config. Precedence (high→low): env vars > selected profile >
@@ -109,7 +119,8 @@ export function loadConfig(opts = {}) {
     };
     const hooks = (merged.hooks && typeof merged.hooks === "object" ? merged.hooks : {});
     const notify = (process.env.HARA_NOTIFY ?? merged.notify ?? "off");
-    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, hooks, notify, mcpServers, cwd: process.cwd() };
+    const vimMode = process.env.HARA_VIM === "1" || merged.vimMode === true || merged.vimMode === "true";
+    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, hooks, notify, vimMode, mcpServers, cwd: process.cwd() };
 }
 export function providerEnvKey(provider) {
     return (PROVIDER_DEFAULTS[provider] ?? PROVIDER_DEFAULTS.anthropic).envKey;