@nanhara/hara 0.121.1 → 0.122.1

package/CHANGELOG.md

@@ -5,6 +5,126 @@ 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.1 — 2026-07-14 — protected files and explicit extension trust
+
+- **The npm CLI now requires Node.js 22.12+.** Node 20 is end-of-life, so Hara no longer makes a security or
+  compatibility promise for it. npm metadata, `hara doctor`, and startup diagnostics now agree; an older
+  runtime exits with a direct `nvm install 22 && nvm use 22` upgrade hint. Standalone binaries and Desktop
+  sidecars remain self-contained and do not require a host Node installation.
+- **Built-in file access fails closed before ordinary approval/dispatch.** Canonical and real-path checks
+  reject `.env`/`.env.*`, credential stores, private keys, and private Hara runtime state in file reads,
+  edit/patch pre-reads, grep/glob/ls, `@file`/completion, codebase and stale semantic indexes, checkpoints,
+  gateway file delivery, and cron command admission. Safe templates such as `.env.example`, `.env.sample`,
+  and `.env.template` remain readable. `HARA_ALLOW_SENSITIVE_FILES=1` is an explicit launch-time exposure
+  switch for one process; it removes both these built-in denies and that process's shell protected-read mask.
+- **Shell protection now reflects the host's guarantees.** Tool subprocesses receive a scrubbed environment;
+  inherited variables can be explicitly retained with the launch-time `HARA_SUBPROCESS_ENV_ALLOW` list, and
+  output is redacted by secret pattern and exact inherited value. Under the default protected-file policy,
+  shell admission blocks literal protected paths and environment dump commands on every platform. macOS
+  additionally applies a Seatbelt read mask to existing protected
+  files/directories, even when the general write sandbox is off. Linux and Windows do not have that kernel
+  read mask: their arbitrary shell code is not a security sandbox and static preflight can be bypassed.
+- **MCP servers and external coding agents are explicit trusted extensions.** They execute outside Hara's
+  protected-file boundary, require confirmation on every interactive tool call (including `full-auto`), and
+  are disabled in non-interactive runs by default. Reviewed automation may opt in before launch with
+  `HARA_ALLOW_TRUSTED_EXTENSIONS=1`; inherited credentials are still scrubbed.
+- **Repositories no longer silently control Hara's privileged configuration.** Project config is limited by
+  default to validated presentation/model preferences; provider routes, credentials, hooks, MCP, sandbox,
+  guardian, approval, and automation settings require the launch-time `HARA_TRUST_PROJECT_CONFIG=1` opt-in.
+  Project permissions may tighten global policy but cannot grant new access, and Git-tracked `.hara-profile`
+  pins are ignored unless that same trust decision was made before startup. Symlink, hard-link, size, identity,
+  and concurrent-change checks protect each of these inputs, while diagnostics reveal key names but no values.
+- **Coding and project-state writes are transactional.** Edit, patch, undo, memory, skills, plans, profiles,
+  indexes, and gateway state use no-follow descriptors, inode checks, bounded reads, atomic replace or
+  compare-and-swap semantics, and private modes where appropriate. Protected search uses the same verified
+  descriptor path instead of handing sensitive-path decisions to `rg`, closing replacement and hard-link
+  races. `AGENTS.md`, subdirectory hints, mentions, and touched-file recall are bounded and reject protected
+  aliases before adding repository content to model context.
+- **Semantic search and review automation distrust stale or historical content.** Semantic indexes carry a
+  versioned manifest with content hashes and are rebuilt when source identity or bytes change. Review-chain
+  prompts receive bounded status/path metadata rather than Git patches; an auto-commit proceeds only when the
+  staged blob still matches the verified worktree descriptor, including deletion and SHA-256 repository edge
+  cases. Read-only auto-run Git policy excludes commands that can expose historical blobs, credentials, remote
+  URLs, or patch bodies.
+- **Old private state is tightened and stale checkpoint history is rotated.** Startup repairs `~/.hara` and
+  sensitive runtime trees to owner-only modes on POSIX systems. The protected checkpoint format rebuilds old
+  derived shadow repositories, filters protected paths independently of the launch-time exposure switch, and
+  purges a checkpoint repository if a protected blob ever reaches its index.
+- **Long-running work has bounded ownership and shutdown.** Shell jobs, external agents, gateway children,
+  approved organization flows, and cron commands terminate the whole process tree with TERM-to-KILL escalation
+  and stop accepting output after cancellation. Background job counts, cron run time/log size, lock takeover,
+  and context fan-out are capped; Windows shell aliases and environment-dump variants are denied consistently.
+- **Gateway outbound files are immutable after admission.** Telegram, Feishu, Slack, Discord, Mattermost,
+  Matrix, WeCom, and Weixin upload verified in-memory bytes plus a safe filename, so a queued path cannot be
+  swapped for a secret before delivery. Counts and bytes are bounded at queue and consume time, cleanup checks
+  inode identity, and Signal outbound files fail closed because its RPC accepts only reopenable filesystem paths.
+
+## 0.122.0 — 2026-07-13 — structured runs, durable work, and a fail-closed gateway
+
+- **Machine-safe headless runs.** `hara -p … --schema <json|file>` installs a run-scoped
+  `structured_output` contract, validates the value against JSON Schema, and writes exactly one JSON value to
+  stdout. Prose, auth notices, retries, and provider/schema failures cannot masquerade as machine output:
+  diagnostics go to stderr and failures exit non-zero. `hara -p … --role <id>` now applies the role's persona,
+  model, and allow/deny tool policy instead of changing the prompt alone.
+- **Agents have stable homes.** `hara projects add/list/remove` maintains a private, atomic registry of project
+  homes; `hara agents` builds one address book from global and registered-project roles.
+  `hara org --role project:agent …` resolves unambiguously and executes at that home with its project context/config. Concurrent
+  CLIs safely share the registry, and dead lock owners can be reclaimed without stealing a live lock.
+- **Two levels of work state.** `todo_write` is now isolated per interactive/headless/sub-agent/serve session
+  and persists with the session, so concurrent agents cannot overwrite each other's checklist. The new `task`
+  tool is a durable cross-session project pool with owners, statuses, `blockedBy` dependencies, cycle checks,
+  and private atomic cross-process persistence. `hara serve` exposes the pool through `tasks.list`.
+- **10-platform gateway, with project-agent roaming.** Telegram, WeChat, Discord, Feishu/Lark, Slack,
+  Mattermost, Matrix, DingTalk, WeCom, and Signal adapters now classify direct vs multi-party chats
+  conservatively. The full coding agent accepts only verified private messages; unknown channel shapes fail
+  closed. `/agent <name|project:name>` pins a thread to an indexed agent and its home, while `/agent main`
+  restores the prior project thread. Chat/session preferences survive project round-trips and group-member
+  state is isolated.
+- **Untrusted group flows cannot reach coding tools.** Opt-in `~/.hara/flows.json` rules are hot-reloaded and
+  evaluated through a bounded, stateless provider call with `tools: []` — no shell, files, MCP, session, or
+  project context. Rules support trigger filters, JSON Schema, disposition-based notification/auto-reply,
+  redacted rotating logs, and rate/concurrency caps. Proposed sends and agent dispatches are parked unless an
+  explicitly configured safe `replyOn` disposition applies.
+- **Single-owner, idempotent approvals.** Consequential flow actions require a unique allowlisted owner and a
+  verified private channel. Deterministic `/approve <id>`, `/edit <id> <content>`, and `/reject <id>` commands
+  avoid “latest draft” ambiguity; blank edits fail closed. Pending actions use private atomic storage and a
+  compare-and-set execution claim, shared by chat and the new serve `approvals.list/resolve` inbox, so two
+  approval surfaces cannot double-send. Deferred actions are parked only for one-shot delivery targets
+  (Telegram, Feishu/Lark, or WeChat); other adapters fail closed instead of presenting an unusable approval.
+- **Bounded gateway execution and media.** Turns are FIFO per session (depth 8), with four active children,
+  bounded global/session-key backlogs, a 15-minute default/30-minute hard timeout, and TERM-to-KILL shutdown;
+  non-zero or signalled children fail visibly. Inbound attachments are authorized before download, limited to
+  four files and 20 MiB each, streamed into private random paths with time/concurrency/retention quotas, and
+  expired after 24 hours. Progress markers are recalled in `finally`, gateway chat/session files are `0600`
+  with lock-before-load persistence, and ambiguous/stale locks are never reclaimed merely by age.
+- **Layered flow admission.** Group classifiers are capped globally (20/minute, 120/hour), per rule/platform/chat
+  (10/minute, 60/hour), per sender (5/minute), and at four active runs. Rate maps and key sizes are bounded and
+  saturation fails closed, so rotating identities cannot grow memory or bypass the host-wide ceiling.
+- **Live config for persistent clients.** `hara serve` rebuilds cwd-specific provider routes, credentials, and
+  guardian settings on sessions/turns; `initialize`, `models.list`, and new sessions reflect current defaults.
+  Resumed sessions retain their explicit model pin while using the live provider route, so credential rotation
+  and project config edits no longer require a server restart.
+- **Coding-path robustness.** File reads/search/edit/patch now reject FIFOs/devices and symlink races, cap reads,
+  use bounded subprocess search with a linear glob matcher, preserve exact file modes, and roll back multi-file
+  patches without overwriting concurrent replacements; writes move-claim the expected inode and commit with
+  create-if-absent semantics, while `/undo` applies the same identity checks. Blank
+  project/env routing values no longer mask valid global config; precedence is environment > project > overlay
+  > global. Web fetch/search blocks IPv4-mapped and full link-local IPv6 SSRF forms and tries regional providers
+  sequentially instead of broadcasting a successful query. Package installs stay attached with bounded
+  long-operation timeouts, tunnel commands preflight their binaries, TUI resize repaints reliably, persisted/
+  public text redacts secrets, and session writes are private, atomic, and cross-process safe.
+- **Interrupts and non-interactive outcomes are honest.** Cancelling a parallel tool round records matching
+  interrupted results while preserving completed side effects; serve approvals settle immediately on interrupt.
+  The stream-stall watchdog is a hard Promise boundary even when a provider ignores its abort signal.
+  Headless and org runs now exit non-zero on provider errors, empty/halted turns, schema failures, and rejected
+  reviews; plan atoms stop on the same outcomes instead of being verified as done, and failed implementers are
+  never committed. Read-only roles are resolved before startup and launch neither hooks nor configured/plugin
+  MCP subprocesses.
+- **Private serve lifecycle.** `~/.hara`/`serve.json` are tightened to `0700`/`0600` and discovery is fsynced,
+  atomically replaced without following symlinks, and removed only by its owning instance. Discovery failures
+  close the listening socket. Serve-side compaction is mutually exclusive with turns/config changes, carries an
+  abort signal, releases locks on interrupt/shutdown, and has a 60-second hard deadline.
+
 ## 0.121.1 — field-feedback reliability & credential safety
 
 - **Terminal resize no longer erases the composer.** Hara clears stale Ink output only before a real

package/README.md

@@ -12,11 +12,11 @@
 
 **Highlights**
 - **An org, not just an agent** — `hara org "<task>"` routes work to the role that *owns* it; `hara plan "<task>"` decomposes a task into a verified DAG of atoms (frame → atomize → sequence → execute → **verify gate**), and `hara plan --parallel` runs independent atoms concurrently.
-- **Drive it from chat** — `hara gateway` runs your local hara from **Telegram · WeChat · Discord · Feishu/Lark · Slack · Mattermost · Matrix · DingTalk · WeCom · Signal** (10 platforms), with **two-way images** (send a photo → it sees it; ask for a file → it sends one), per-chat resumable sessions, and project roaming. Connects out — no public webhook. See **[docs/gateway.md](docs/gateway.md)**.
+- **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.
 - **Multi-provider, all streamed** — Anthropic (Claude) or any OpenAI-compatible endpoint (Qwen/DashScope, GLM, Kimi, OpenAI) with live Markdown + visible reasoning.
-- **Delegate to other agents** — the **`external_agent`** tool hands a self-contained task to **Claude Code** or **Codex** running headless, and returns the result — so you pick the best engine per task. Gated by approval, trust-tiered, and never exposed to read-only sub-agents.
+- **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
   auto-fails-over instead of hanging, big pastes folding to a token, and a startup update notice — the
   terminal never feels dead.
@@ -26,6 +26,9 @@ Track it: https://github.com/hara-cli/hara · https://hara.run
 
 ## Install
 
+The npm package requires **Node.js 22.12 or newer**. If needed, upgrade first with
+`nvm install 22 && nvm use 22`. Node.js 20 is end-of-life and is not a supported Hara runtime.
+
 ```bash
 npm i -g @nanhara/hara
 ```
@@ -135,8 +138,16 @@ hara expresses it the way each endpoint wants (OpenAI `reasoning_effort`, Anthro
 DashScope `enable_thinking`, **DeepSeek** V4 `thinking` + `reasoning_effort` where `max` genuinely raises the
 effort). In the TUI, bare `/model` opens a picker — ↑↓ pick a model, **←→ set the thinking level**.
 
-Config lives in `~/.hara/config.json`. Env vars override it: `HARA_PROVIDER`, `HARA_MODEL`,
-`HARA_BASE_URL`, `HARA_API_KEY`, or the provider key (`ANTHROPIC_API_KEY` / `DASHSCOPE_API_KEY`).
+Config lives in `~/.hara/config.json`; the nearest project `.hara/config.json` may set the explicitly safe
+project preferences `model`, `theme`, `vimMode`, `autoCompact`, and `reasoningEffort`. Repository config is
+untrusted by default: routing/credential, hook/MCP, approval/sandbox, computer-control, and other privileged
+keys are ignored with a key-name-only warning. For a repository you have reviewed, launch with
+`HARA_TRUST_PROJECT_CONFIG=1` to enable all of its project keys for that process. The opt-in is captured at
+startup, and project config itself must be a bounded regular file under a real (non-symlink) `.hara` directory.
+Effective precedence for enabled keys is **environment > project > selected overlay > global**. Empty routing
+values are ignored, so an empty project/env value cannot hide a working global credential or endpoint. Env overrides include
+`HARA_PROVIDER`, `HARA_MODEL`, `HARA_BASE_URL`, `HARA_API_KEY`, and the provider key
+(`ANTHROPIC_API_KEY` / `DASHSCOPE_API_KEY`).
 
 ## Use
 
@@ -146,12 +157,17 @@ hara init                  # analyze the project & (re)generate AGENTS.md
 hara doctor                # check your setup (auth / model / node / assets / roles)
 hara roles init            # scaffold role-agents (implementer / reviewer / docs)
 hara org "review src/ for bugs"   # dispatch a task to the role that owns it (or --role <id>)
+hara projects add shop /absolute/path/to/shop   # register an agent home
+hara agents                # list global + registered project agents
+hara org --role shop:reviewer "audit auth"     # run that agent at its own home
 hara plan "add a /health endpoint with a test"   # decompose → sequence (DAG) → run each step + verify
 hara plan --parallel "..."  # run independent atoms concurrently  ·  hara plan resume  # continue a stopped plan
 hara review                 # review uncommitted changes for bugs/security/missing tests (--staged · --base main)
 hara commit                 # AI commit message from staged changes, then commit (-a to stage all · -y to skip confirm)
 hara index                 # build the semantic search index (after: hara config set embedProvider ollama|qwen)
 hara -p "summarize @README.md and fix the lint errors in src/"   # one-shot; @path attaches a file
+hara -p "extract package metadata" --schema ./schema.json         # stdout is exactly schema-valid JSON
+hara -p "review the current diff" --role reviewer                 # persona + model + tool policy from the role
 hara --approval auto-edit  # suggest (default) | auto-edit | full-auto   (-y = full-auto)
 hara --sandbox workspace-write   # confine shell writes to the project (macOS Seatbelt)
 hara -c                    # resume the most recent session in this directory
@@ -159,6 +175,12 @@ hara --profile work        # use a named profile from ~/.hara/config.json
 hara -m glm-5              # pick a model
 ```
 
+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`
+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` `/usage` `/doctor` `/sessions` `/undo` `/compact` `/recall` `/reset` `/exit` (type `/`+Tab to complete). 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
@@ -206,19 +228,37 @@ 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 — **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).
+**Protected files and shell sandboxing**: built-in file, search, and context paths hard-reject `.env`/credential/private-key/private-Hara-state files before the ordinary approval/dispatch path can authorize them. Safe templates (`.env.example`, `.env.sample`, `.env.template`) remain readable. `HARA_ALLOW_SENSITIVE_FILES=1` is an explicit one-process exposure switch: it removes these built-in denies and that process's shell protected-read mask. Shell subprocesses receive a scrubbed environment; explicitly retain a named inherited variable with `HARA_SUBPROCESS_ENV_ALLOW=NAME[,NAME]` (output is still redacted). With the protected-file policy enabled, shell preflight rejects literal protected paths and environment-dump commands on every OS. On macOS, Seatbelt also masks existing protected files/directories from the shell and `--sandbox workspace-write|read-only` provides **file-write confinement**. Linux/Windows have no equivalent kernel read mask: static shell preflight is a useful guardrail, not a security sandbox, and arbitrary code can bypass it.
 **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, `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).
+**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`.
+**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.
-**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.
+**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.
+They also skip configured and plugin-provided MCP server processes, so starting an external tool server cannot
+bypass the same contract before the first model turn.
+**Profiles and live config**: select an identity with `--profile <name>`; use `overlays` in
+`~/.hara/config.json` for named config overlays. Project `.hara/config.json` files get the safe preference
+allowlist above; project-specific routing requires `HARA_TRUST_PROJECT_CONFIG=1` before launch.
+`.hara-profile` identity pins are read no-follow with size, single-inode, and hard-link checks; pin updates use
+an atomic compare-and-swap, and invalid-pin warnings never echo file contents or paths. A Git-tracked pin is
+repository-controlled and ignored by default; local untracked pins created with `hara profile pin` work
+normally. The same launch-time `HARA_TRUST_PROJECT_CONFIG=1` opt-in enables a reviewed tracked pin.
+Long-lived `hara serve` processes reload provider credentials/routes and guardian settings for the target cwd on
+new sessions and turns. `models.list` and new sessions see current defaults; a resumed session keeps its explicit
+model pin while using the live provider route. No server restart is required after a credential rotation.
 
 ### The org — what makes hara different
 
@@ -234,6 +274,13 @@ to a clean start tree; a review that doesn't pass leaves the work uncommitted).
 **`agent`** tool spawns **parallel read-only sub-agents** for fan-out — analyze / review / search
 several things at once (each can take a `role`), bounded to 8 concurrent (`HARA_MAX_CONCURRENCY`).
 
+Register project homes with `hara projects add <name> <absolute-path>`, then `hara agents` becomes a global
+address book across `~/.hara/roles` and each registered project's roles. A qualified address such as
+`shop:reviewer` is unambiguous; both `hara org --role shop:reviewer "<task>"` and one-shot `hara -p "<task>"
+--role shop:reviewer` execute at that agent's home, with its own `AGENTS.md`, live project config, role model,
+and allow/deny/read-only tool policy. `global:<name>` is portable and runs in the current project. A bare name
+uses the local role first and otherwise must resolve unambiguously.
+
 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
 **verify gate** — frame → atomize → sequence → execute → verify. Each atom may carry a `check` shell
@@ -255,11 +302,11 @@ turn, or **`/undo`** to revert the last edit. In-session **`/diff`**, **`/review
 - **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.
 - **Multi-provider**: Anthropic (Claude) or any OpenAI-compatible endpoint (Qwen/DashScope, GLM, Kimi, OpenAI) — **all streamed live**.
-- **Chat gateway**: drive your local hara from a chat app — **Telegram · WeChat · Discord · Feishu/Lark · Slack · Mattermost · Matrix · DingTalk**. The daemon connects out (no public webhook), with per-chat sessions, project roaming (`/cd`), and **two-way images** (send a photo → it sees it; ask for a file → it sends one). Setup per platform: **[docs/gateway.md](docs/gateway.md)**.
+- **Chat gateway**: drive your local hara from **Telegram · WeChat · Discord · Feishu/Lark · Slack · Mattermost · Matrix · DingTalk · WeCom · Signal**. The daemon connects out (no public webhook), with per-chat sessions, project roaming (`/cd`), agent switching (`/agent`), and **two-way images on byte-upload-capable platforms**. Setup, platform capability details, and the group-flow security model: **[docs/gateway.md](docs/gateway.md)**.
 
 ### Roadmap
 
-**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`)** · **chat gateway (8 platforms, two-way images)** · **single-binary distribution** · **Docker image** · `/compact` context management.
+**Shipped:** ink TUI · plan mode · persistent memory + self-evolution · atomization planner · parallel plan atoms · **multi-role review chains** · global project-agent index · durable project tasks · parallel sub-agents · MCP client *and* server · **scheduled tasks (`hara cron`)** · **chat gateway (10 platforms, capability-aware media)** · **single-binary distribution** · **Docker image** · `/compact` context management.
 **Next:** SSOT data authority · an enterprise control-plane (fleet + central token management).
 
 ## Security

package/SECURITY.md

@@ -29,9 +29,45 @@ local user (who already has your shell).
 - **`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.
+- **Protected reads in built-in paths.** `.env`, `.env.*` (except explicit templates such as
+  `.env.example`), credential stores, private keys, and private Hara state are rejected before the ordinary
+  approval/dispatch path can authorize them. The same canonical/real-path check covers built-in file reads,
+  edit/patch pre-reads, grep/glob/ls, `@file`, completion, semantic/lexical indexes, checkpoints, gateway file
+  delivery, cron command admission, and symlink aliases. Headless, gateway, sub-agent, cron, and `full-auto`
+  execution cannot approve those built-in paths past the check. `HARA_ALLOW_SENSITIVE_FILES=1` is an explicit
+  launch-time exposure switch for one process: it removes the built-in denies and that process's shell
+  protected-read preflight/Seatbelt mask.
+- **Shell guardrails differ by platform.** With the protected-file policy enabled, shell admission statically
+  rejects literal protected paths and environment-dump commands on every OS. On macOS, Hara additionally
+  applies a Seatbelt read mask to existing
+  protected files/directories even when the general write sandbox is off. Linux and Windows have no equivalent
+  kernel-enforced read mask: their arbitrary shell code is outside the protected-file boundary, and static
+  preflight can be bypassed by indirection or generated code.
+- **Subprocess credentials.** Model-controlled Bash/background jobs, hooks, external agents, and MCP servers
+  inherit an environment with secret-shaped and code-injection variables removed. MCP `env` entries are an
+  explicit per-server grant; other commands can receive named variables only when the user launches Hara with
+  `HARA_SUBPROCESS_ENV_ALLOW=NAME,OTHER`. Tool output is pattern- and exact-value-redacted. Hara's own provider
+  process retains its keys.
+- **Secrets at rest.** `~/.hara/config.json` (API keys) and `~/.hara/qwen-oauth.json` (tokens) are written
+  `0600`. The optional semantic index skips secret-named files and filters old indexes at query time, so keys
+  aren't embedded or sent to an embedding provider. The memory guard screens secret-shaped strings out of
+  what the agent saves.
+- **Repository config is untrusted by default.** A project `.hara/config.json` can set only `model`, `theme`,
+  `vimMode`, `autoCompact`, and `reasoningEffort`. Endpoint/credential routing, hooks/MCP commands, approval,
+  sandbox, guardian, computer control, and all other keys remain global unless the user launches Hara with
+  `HARA_TRUST_PROJECT_CONFIG=1` after reviewing that repository. Warnings name ignored/enabled keys but never
+  their values. Project config reads reject a symlink `.hara`, final symlinks, hard links, oversized files,
+  and files/directories that change identity during the read.
+- **Identity pins are bound, not followed.** `.hara-profile` reads reject symlink/hard-link aliases and
+  oversized or changing files. Writes use a canonical-parent, no-follow snapshot plus atomic compare-and-swap;
+  invalid pin warnings never include the pin's raw content or untrusted path. Git-tracked pins are ignored by
+  default so a cloned repository cannot silently switch to an existing personal/org identity; untracked local
+  pins remain usable, and the reviewed-repository `HARA_TRUST_PROJECT_CONFIG=1` launch opt-in enables tracked pins.
+- **MCP/external agents are trusted extensions.** They execute outside Hara's protected-file boundary. Every
+  interactive tool call requires confirmation, including in `full-auto`; non-interactive runs disable them by
+  default. Reviewed automation can explicitly enable them before launch with
+  `HARA_ALLOW_TRUSTED_EXTENSIONS=1`. Their inherited environment is still scrubbed, but the extension may use
+  its own credentials or access anything its host process permits.
 - **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>`.
@@ -39,13 +75,16 @@ local user (who already has your shell).
 
 ## 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.
+- **The general sandbox confines file writes only** — not arbitrary reads, network, or process exec;
+  `/private/tmp` stays writable. The protected-file policy is a narrow boundary for Hara's built-in paths,
+  plus an OS-enforced shell read mask on macOS only; it is not a complete hostile-code jail. On Linux and
+  Windows, treat any allowed network-capable shell as able to read and send anything the Hara process account
+  can access. On macOS, the protected-path mask still does not confine ordinary files, network, or process exec.
+- **`@file` mentions** can read ordinary files *you* name (including outside the project), but protected
+  files are refused unless you made the launch-time opt-in. Mentions are expanded on user input only.
 - **`full-auto` / `-y`** removes the human gate by your explicit choice. Use it on code and in directories
-  you trust.
+  you trust. It does not remove built-in protected-path checks or subprocess environment scrubbing, but it
+  does not turn Linux/Windows shell preflight into a security boundary.
 
 ## Reporting a vulnerability