@nanhara/hara 0.89.0 → 0.95.2

package/CHANGELOG.md

@@ -5,6 +5,80 @@ 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.94.1 — unreleased (gateway: relay is on-inbound, not a noisy push)
+
+- **Fix the bind output relay to be quiet + platform-correct.** 0.94.0's continuous 3s timer-push flooded chat
+  (a message every few seconds) and hit iLink's `ret=-2` (its bot model is passive-reply, no continuous push).
+  Replaced with **on-inbound relay**: when you message a bound/registered pane, the daemon captures the pane,
+  injects your text, waits ~3s, and replies **once** with the session's NEW output (`🖥 <pane>\n<delta>`). One
+  reply per message — no spam, and it fits iLink's "one inbound → one reply" model. Send `?` to peek again.
+  - `tmux-routes.ts`: `pickPaneForReply()` (pick+consume, no inject); the timer loop is gone.
+  - `serve.ts` onMessage: capture-before → inject → settle → reply with `outputDelta`.
+
+## 0.94.0 — unreleased (gateway: bind output relay — two-way remote terminal)
+
+- **Output relay for `hara remote bind`** — the daemon now polls each bound tmux pane and pushes its NEW output
+  back to chat once it settles, so a session you drive from your phone is **two-way**: your replies inject in
+  (existing), and you SEE the session's output come back (`🖥 <pane>\n<delta>`). Only bound (`bind`) panes; the
+  first sighting is baselined (no dump of the pre-existing screen); best-effort send (iLink cold-push may drop a
+  message when the chat is cold). Pure `outputDelta` (append / unchanged / scroll-anchor / tail) unit-tested.
+  - `src/gateway/tmux-routes.ts`: `boundRoutes`, `capturePane`, `outputDelta`.
+  - `src/gateway/serve.ts`: a 3s relay loop in `runGateway` (capture → settle → send delta), cleared on abort.
+  - Caveat: a full-screen TUI session (e.g. Claude Code's ink UI) relays the rendered frame; a non-TUI /
+    `HARA_TUI=0` / `-p`-style session relays cleaner. 285 tests.
+## 0.93.0 — unreleased (hara remote — universal chat-driven HITL for any tmux session)
+
+- **`hara remote`** — a first-class, agent-agnostic command so ANY terminal session in tmux (Claude Code, codex,
+  hara, a plain REPL) can be driven from chat, not just via the Claude-Code wechat-send skill:
+  - `hara remote ask "<q>"` — register this pane (one-shot) + push the question to WeChat; your reply injects back.
+  - `hara remote bind` — **persistent bind**: every WeChat reply injects into this pane until `unbind` / `/detach`
+    (drive a whole session from your phone while you're out, many messages, not just one).
+  - `hara remote unbind` · `hara remote status`.
+- Route store gains `mode: "once" | "bind"`; the daemon consumes "once" routes but keeps "bind" ones
+  (`pickRoute`/`deliverToTmux`). New `/detach` chat command unbinds all persistent panes from your phone.
+- Generic by design: the injection is just `tmux send-keys`, so it works for any program reading stdin in the
+  pane — the agent only needs to call `hara remote ask` when it wants your input (the confirm-loop pattern).
+- 284 tests (+ bind-mode `pickRoute`); persistent-bind verified live (two replies → same pane, route persists).
+
+## 0.92.0 — unreleased (gateway: reply-into-tmux — two-way HITL for any running session)
+
+- **Reply routing into an already-running tmux session** — a session you started yourself (Claude Code / codex /
+  hara, in tmux) can ping you on WeChat and, while you're away, your reply gets **injected back into that exact
+  session** so it continues. No need to launch it under a supervisor or use a blocking tool — borrows the ccgram
+  keystroke-injection pattern (the only way to retrofit a session the daemon doesn't own).
+  - `src/gateway/tmux-routes.ts`: a route store (`~/.hara/gateway/tmux-routes.json`) + `tmux send-keys` injection.
+    The gateway daemon, on an owner reply, injects it into the **oldest live registered pane** (`deliverToTmux`),
+    one-shot per ask, dead panes pruned. Pure `pickRoute` + `paneAlive` (list-panes membership) unit-tested.
+  - `serve.ts` `onMessage`: a non-slash reply is routed to a waiting pane (and the task isn't re-run) — owner-gated
+    by the existing allowlist; only panes that **opted in** are ever touched.
+  - The `wechat-send` skill gains `--ask`: send a question + register this tmux pane for the reply.
+- Live-verified the injection path (send-keys → pane received the line); fixed `paneAlive` (display-message was
+  too lenient → use `list-panes -a` membership). 283 tests.
+
+## 0.91.0 — unreleased (external_agent: delegate to Claude Code / Codex)
+
+- **`external_agent` tool** — hand a self-contained task to an EXTERNAL coding agent (**`claude`** / **`codex`**)
+  running headless in the current dir, and get its result back. Zero new deps — drives each agent's native
+  headless flag (`claude -p … --output-format text --permission-mode …`, `codex exec … --cd … --sandbox …`)
+  over `node:child_process`, not openclaw's heavier ACP/acpx stack. Pick the best engine per task.
+  - **Gated**: `kind:"exec"` → inherits the approval flow; and because read-only fan-out sub-agents only get the
+    `READONLY_TOOLS` allow-list, this privileged tool is **never** exposed to them.
+  - **Trust tiers** `externalAgentTrust` / `HARA_EXTERNAL_AGENT_TRUST` = `off | gated (default) | full`. `gated`
+    runs the external agent in its safe sub-mode (`claude --permission-mode plan/acceptEdits`,
+    `codex --sandbox read-only/workspace-write`); the dangerous bypass/full-access sub-modes are only reachable at
+    `full`. Backend allow-list (claude/codex), timeout + output cap. Pure `buildExternalArgv` unit-tested.
+
+## 0.90.0 — unreleased (gateway: WeCom + Signal → 10 platforms)
+
+- **WeCom (企业微信)** — connects out to WeCom's AI-Bot WebSocket gateway (no public webhook). `HARA_WECOM_BOT_ID`
+  + `HARA_WECOM_SECRET`. Two-way: inbound text + images (incl. AES-decrypted attachments → `~/.hara/wecom/media`),
+  outbound text/image/file. Zero new deps (native WebSocket + node:crypto).
+- **Signal** — talks to a local **signal-cli** daemon (JSON-RPC). `HARA_SIGNAL_RPC_URL` + `HARA_SIGNAL_NUMBER`.
+  Inbound text + image attachments, outbound text/file; phone numbers redacted in logs. signal-cli is an external
+  daemon the user runs (documented). Zero new npm deps.
+- Pure parsers `parseWecomMessage` / `parseSignalMessage` unit-tested. docs/gateway.md + README updated to 10
+  platforms. Ported from the openclaw + hermes adapters.
+
 ## 0.89.0 — unreleased (gateway: Slack · Mattermost · Matrix · DingTalk + docs)
 
 - **Four more platforms**, all zero-new-dep (native WebSocket / `fetch`), same `ChatAdapter` seam:

package/README.md

@@ -2,6 +2,8 @@
 
 **A coding agent CLI that runs like an engineering org.**
 
+![hara — your coding agent, driven from 10 chat platforms](docs/assets/hara-gateway-hero.png)
+
 > Think "Claude Code, but it operates as a configurable, governed *organization* of role-agents" —
 > with routing boundaries, a dispatcher, a single source-of-truth data layer, human-in-the-loop
 > approvals, and cron autonomy.
@@ -10,10 +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** (8 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** (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)**.
 - **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). 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.
 - **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.
 
 Track it: https://github.com/hara-cli/hara · https://hara.run

package/dist/agent/loop.js

@@ -9,6 +9,18 @@ import { mapLimit, maxParallel } from "../concurrency.js";
 import { decideCommand, loadPermissionRules } from "../security/permissions.js";
 import { subdirHint } from "../context/subdir-hints.js";
 import { classifyError, failoverAction, errorHint } from "./failover.js";
+import { currentTodos } from "../tools/todo.js";
+/** Spinner verb (terminal mode + reused by TUI tests): when the agent has an in_progress todo,
+ *  surface its activeForm/text so the bottom-of-screen line reads concretely ("▶ updating tests… 3s")
+ *  instead of "working 3s". Pure: takes a snapshot + elapsed seconds. */
+export function spinnerVerb(list, elapsedSec) {
+    const active = list.find((t) => t.status === "in_progress");
+    if (active) {
+        const phrase = active.activeForm?.trim() || active.text;
+        return `${phrase}… ${elapsedSec}s`;
+    }
+    return `working ${elapsedSec}s`;
+}
 /** Whether a tool call needs user confirmation under the given approval mode. */
 export function needsConfirm(kind, mode) {
     if (kind === "read")
@@ -79,7 +91,17 @@ export async function runAgent(history, opts) {
         const sink = ctx.ui; // TUI mode: route output to ink instead of stdout
         const tty = stdout.isTTY && !opts.quiet && !sink;
         const md = tty && process.env.HARA_MD !== "0" ? makeRenderer(out) : null;
-        let sawReasoning = false;
+        // Reasoning rendering in plain-terminal mode: we put reasoning on its OWN dim lines (prefixed
+        // "│ ") instead of sharing a line with the spinner — that's what was eating DeepSeek's
+        // reasoning_content in non-TUI mode (each spinner tick `\r`-overwrote it). The TUI keeps its
+        // existing 5-line scroll window via the ink Block; this is the terminal equivalent.
+        let reasoningOpen = false;
+        const flushReasoningTail = () => {
+            if (reasoningOpen) {
+                out("\n");
+                reasoningOpen = false;
+            }
+        };
         // "working Ns" spinner until the first output arrives (cleared on text/reasoning or turn end)
         let spin = null;
         const stopSpin = () => {
@@ -93,7 +115,10 @@ export async function runAgent(history, opts) {
             const frames = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏";
             const t0 = Date.now();
             let fi = 0;
-            spin = setInterval(() => out(`\r${c.dim(`${frames[fi++ % frames.length]} working ${Math.floor((Date.now() - t0) / 1000)}s`)}`), 100);
+            spin = setInterval(() => {
+                const verb = spinnerVerb(currentTodos(), Math.floor((Date.now() - t0) / 1000));
+                out(`\r\x1b[K${c.dim(`${frames[fi++ % frames.length]} ${verb}`)}`);
+            }, 100);
         }
         const r = await activeProvider.turn({
             system: composeSystem(ctx.cwd, opts.projectContext, opts.systemOverride, opts.memory),
@@ -107,10 +132,7 @@ export async function runAgent(history, opts) {
                     return;
                 }
                 stopSpin();
-                if (sawReasoning) {
-                    out("\n");
-                    sawReasoning = false;
-                }
+                flushReasoningTail();
                 if (md)
                     md.push(d);
                 else
@@ -124,14 +146,29 @@ export async function runAgent(history, opts) {
                         sink.reasoning(d);
                         return;
                     }
+                    // Terminal mode: render reasoning on its own dim lines (prefix `│ ` per line). Each
+                    // line is committed once and never overwritten — so a subsequent spinner tick can't
+                    // clobber it (the old `out(c.dim(d))` bug). Multi-line deltas split cleanly; the
+                    // current line resumes mid-output when the next delta arrives.
                     stopSpin();
-                    sawReasoning = true;
-                    out(c.dim(d));
+                    const lines = d.split("\n");
+                    for (let i = 0; i < lines.length; i++) {
+                        if (!reasoningOpen) {
+                            out(c.dim("│ "));
+                            reasoningOpen = true;
+                        }
+                        out(c.dim(lines[i]));
+                        if (i < lines.length - 1) {
+                            out("\n");
+                            reasoningOpen = false;
+                        }
+                    }
                 }
                 : undefined,
             signal: opts.signal,
         });
         stopSpin();
+        flushReasoningTail();
         md?.end();
         if (!opts.quiet && !sink)
             out("\n");

package/dist/config.js

@@ -12,7 +12,8 @@ const PROVIDER_DEFAULTS = {
     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", "routeModel", "routeBaseURL", "routeApiKey", "notify", "vimMode", "autoCompact", "fileCheckpoints", "fallbackModel", "fallbackBaseURL", "fallbackApiKey"];
+export const CONFIG_KEYS = ["provider", "apiKey", "model", "baseURL", "approval", "sandbox", "theme", "evolve", "assetCapture", "computerUse", "computerApps", "visionModel", "visionBaseURL", "visionApiKey", "embedProvider", "embedModel", "embedBaseURL", "embedApiKey", "routeModel", "routeBaseURL", "routeApiKey", "notify", "vimMode", "autoCompact", "fileCheckpoints", "fallbackModel", "fallbackBaseURL", "fallbackApiKey", "reasoningEffort"];
+export const REASONING_EFFORTS = ["off", "low", "medium", "high"];
 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"];
@@ -82,16 +83,27 @@ export function setModelVisionOverride(model, cap) {
     persistConfig(p, cfg);
 }
 /**
- * Effective config. Precedence (high→low): env vars > selected profile >
- * project `.hara/config.json` > global `~/.hara/config.json` > provider defaults.
+ * Effective config. Precedence (high→low): env vars > project `.hara/config.json` >
+ * named overlay (`overlays.<name>` in global config) > global `~/.hara/config.json`
+ * > provider defaults.
+ *
+ * NOTE: `--profile` / `HARA_PROFILE` is the IDENTITY-profile selector (personal ↔ org A
+ * ↔ org B) — see src/profile/profile.ts. The legacy `profiles:{name:partial}` overlay
+ * mechanism (a tiny in-config preset / overlay) has been renamed to `overlays:{...}`
+ * to free the "profile" word for identity. We still read the legacy `profiles:{...}`
+ * key for one release for back-compat. Overlays are addressed by env var
+ * `HARA_OVERLAY=<name>` (or `opts.overlay`).
  */
 export function loadConfig(opts = {}) {
     const global = readRawConfig();
-    const { profiles, ...globalBase } = global;
+    // Strip both the new (`overlays`) and legacy (`profiles`) overlay containers from the base merge.
+    // The legacy `profiles` key is kept readable for back-compat with users who already have it.
+    const { overlays, profiles, ...globalBase } = global;
     const project = readProjectConfig(process.cwd());
-    const profileName = process.env.HARA_PROFILE ?? opts.profile;
-    const profile = profileName && profiles && profiles[profileName] ? profiles[profileName] : {};
-    const merged = { ...globalBase, ...project, ...profile };
+    const overlayName = process.env.HARA_OVERLAY ?? opts.overlay;
+    const overlayMap = overlays && typeof overlays === "object" ? overlays : profiles && typeof profiles === "object" ? profiles : null;
+    const overlay = overlayName && overlayMap && overlayMap[overlayName] ? overlayMap[overlayName] : {};
+    const merged = { ...globalBase, ...project, ...overlay };
     const provider = (process.env.HARA_PROVIDER ?? merged.provider ?? "anthropic");
     const d = PROVIDER_DEFAULTS[provider] ?? PROVIDER_DEFAULTS.anthropic;
     const model = process.env.HARA_MODEL ?? merged.model ?? d.model;
@@ -118,7 +130,7 @@ export function loadConfig(opts = {}) {
     const mcpServers = {
         ...(globalBase.mcpServers ?? {}),
         ...(project.mcpServers ?? {}),
-        ...(profile.mcpServers ?? {}),
+        ...(overlay.mcpServers ?? {}),
     };
     const hooks = (merged.hooks && typeof merged.hooks === "object" ? merged.hooks : {});
     const notify = (process.env.HARA_NOTIFY ?? merged.notify ?? "off");
@@ -128,7 +140,11 @@ export function loadConfig(opts = {}) {
     const fallbackModel = process.env.HARA_FALLBACK_MODEL ?? merged.fallbackModel;
     const fallbackBaseURL = process.env.HARA_FALLBACK_BASE_URL ?? merged.fallbackBaseURL;
     const fallbackApiKey = process.env.HARA_FALLBACK_API_KEY ?? merged.fallbackApiKey;
-    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, routeModel, routeBaseURL, routeApiKey, hooks, notify, vimMode, autoCompact, fileCheckpoints, fallbackModel, fallbackBaseURL, fallbackApiKey, mcpServers, cwd: process.cwd() };
+    const reasoningRaw = process.env.HARA_REASONING_EFFORT ?? merged.reasoningEffort;
+    const reasoningEffort = reasoningRaw && ["off", "low", "medium", "high"].includes(reasoningRaw)
+        ? reasoningRaw
+        : undefined;
+    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, routeModel, routeBaseURL, routeApiKey, hooks, notify, vimMode, autoCompact, fileCheckpoints, fallbackModel, fallbackBaseURL, fallbackApiKey, reasoningEffort, mcpServers, cwd: process.cwd() };
 }
 export function providerEnvKey(provider) {
     return (PROVIDER_DEFAULTS[provider] ?? PROVIDER_DEFAULTS.anthropic).envKey;

package/dist/gateway/serve.js

@@ -5,6 +5,7 @@
 import { spawn } from "node:child_process";
 import { telegramAdapter } from "./telegram.js";
 import { chatContext, chatCd, newChatSession, setChatSession, toggleVoice } from "./sessions.js";
+import { pickPaneForReply, capturePane, injectTmux, outputDelta } from "./tmux-routes.js";
 import { synthesize } from "./tts.js";
 import { selfArgv } from "../cron/runner.js";
 import { listSessions, resolveSessionId, loadSession } from "../session/store.js";
@@ -142,6 +143,26 @@ async function buildAdapter(platform) {
         const { dingtalkAdapter } = await import("./dingtalk.js");
         return { adapter: dingtalkAdapter(clientId, clientSecret) };
     }
+    if (platform === "wecom" || platform === "wework") {
+        const botId = process.env.HARA_WECOM_BOT_ID;
+        const secret = process.env.HARA_WECOM_SECRET;
+        if (!botId || !secret) {
+            console.error("hara gateway: set HARA_WECOM_BOT_ID + HARA_WECOM_SECRET (企业微信 admin console → AI Bot credentials) and HARA_GATEWAY_ALLOWED=<your wecom userid>. (HARA_WECOM_WS_URL overrides the gateway URL.)");
+            return null;
+        }
+        const { wecomAdapter } = await import("./wecom.js");
+        return { adapter: wecomAdapter(botId, secret, process.env.HARA_WECOM_WS_URL) };
+    }
+    if (platform === "signal") {
+        const rpcUrl = process.env.HARA_SIGNAL_RPC_URL;
+        const number = process.env.HARA_SIGNAL_NUMBER;
+        if (!rpcUrl || !number) {
+            console.error("hara gateway: set HARA_SIGNAL_RPC_URL (e.g. http://localhost:8080) + HARA_SIGNAL_NUMBER (the bot's registered phone, E.164) and HARA_GATEWAY_ALLOWED=<your signal number/uuid>. Requires a local signal-cli daemon: `signal-cli -a <number> daemon --http localhost:8080`.");
+            return null;
+        }
+        const { signalAdapter } = await import("./signal.js");
+        return { adapter: signalAdapter(rpcUrl, number), ownerId: number };
+    }
     const token = process.env.HARA_TELEGRAM_TOKEN;
     if (!token) {
         console.error("hara gateway: set HARA_TELEGRAM_TOKEN (from @BotFather) and HARA_GATEWAY_ALLOWED=<your telegram user id>.");
@@ -192,11 +213,47 @@ export async function runGateway(opts) {
             await adapter.send(m.chatId, "⛔ not authorized.");
             return;
         }
+        // If a tmux session opted in (via `hara remote ask/bind`), this reply is its input → inject it into that
+        // pane, let it react, and reply with the session's NEW output (on-inbound relay — quiet + iLink-friendly:
+        // one reply per message, no continuous push). Owner-gated by the allowlist check above.
+        if (!parseCommand(m.text)) {
+            const pane = pickPaneForReply();
+            if (pane) {
+                console.error(`hara gateway: routed reply → tmux pane ${pane}`);
+                const before = capturePane(pane) ?? "";
+                injectTmux(pane, m.text);
+                // wait for the session's output to SETTLE (poll every 800ms; stable for ~1.6s → done; cap ~10s) so a
+                // slow response isn't missed and we don't capture mid-stream.
+                let after = "";
+                let stable = 0;
+                for (let i = 0; i < 12; i++) {
+                    await new Promise((r) => setTimeout(r, 800));
+                    const cur = capturePane(pane) ?? "";
+                    if (cur === after) {
+                        if (++stable >= 2)
+                            break;
+                    }
+                    else {
+                        stable = 0;
+                        after = cur;
+                    }
+                }
+                const delta = outputDelta(before, after).trim();
+                const body = delta ? (delta.length > 1500 ? "…\n" + delta.slice(-1500) : delta) : "(已注入,暂无新输出 — 发 ? 再看)";
+                await adapter.send(m.chatId, `🖥 ${pane}\n${body}`);
+                return;
+            }
+        }
         const ctx = chatContext(adapter.name, m.chatId, cwd); // this chat's current { cwd, sessionId }
         const cmd = parseCommand(m.text);
         if (cmd) {
             if (cmd.cmd === "help")
-                return adapter.send(m.chatId, "commands:\n/pwd · /cd <dir> — project\n/sessions · /new · /resume <id> — threads\n/voice · /say <text> — speech · /send <path> — send a file\n/help\nanything else = run hara here");
+                return adapter.send(m.chatId, "commands:\n/pwd · /cd <dir> — project\n/sessions · /new · /resume <id> — threads\n/voice · /say <text> — speech · /send <path> — send a file\n/detach — stop injecting replies into bound tmux panes\n/help\nanything else = run hara here");
+            if (cmd.cmd === "detach") {
+                const { unbindBinds } = await import("./tmux-routes.js");
+                const n = unbindBinds();
+                return adapter.send(m.chatId, n ? `🔓 detached ${n} bound tmux pane(s) — replies go to hara again.` : "(no tmux panes were bound)");
+            }
             if (cmd.cmd === "pwd")
                 return adapter.send(m.chatId, `📂 ${ctx.cwd}\n🧵 ${ctx.sessionId.slice(-18)}`);
             if (cmd.cmd === "cd" || cmd.cmd === "project") {

package/dist/gateway/signal.js

@@ -0,0 +1,220 @@
+// Signal adapter for `hara gateway` — talks to a LOCAL signal-cli daemon running in HTTP/JSON-RPC mode
+// (built-in fetch, zero new dep; no WebSocket, no cloud API). The user installs signal-cli, registers/links the
+// bot's phone number, and runs `signal-cli -a <number> daemon --http localhost:8080`. Inbound is drained via the
+// JSON-RPC `receive` method on a long-poll loop (the robust zero-dep path — no SSE line-buffering quirks);
+// outbound + attachment fetch go through JSON-RPC `send`/`getAttachment`. Creds from HARA_SIGNAL_RPC_URL
+// (e.g. http://localhost:8080) + HARA_SIGNAL_NUMBER (the bot's registered phone, E.164). Same ChatAdapter shape
+// as the others, so all cross-platform gateway plumbing (send_file, system context, stuck-guard, image
+// attach/describe) works unchanged. Mirrors the Matrix long-poll model + the Discord download-media/sendFile
+// patterns, and the hermes signal.py protocol/redaction behavior.
+//
+// EXTERNAL DEPENDENCY: signal-cli is NOT bundled — it's a separate program the user installs and runs (it is the
+// only way to speak Signal's protocol; there is no official cloud API). The adapter just speaks HTTP/JSON-RPC to
+// the daemon the user has running. See setup notes at the bottom of this file.
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, basename } from "node:path";
+import { homedir } from "node:os";
+import { chunkText } from "./telegram.js";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// E.164 phone numbers (+15551234567) anywhere in a string → +155****4567 (mirrors hermes' _redact_phone).
+const PHONE_RE = /\+[1-9]\d{6,14}/g;
+/** Redact phone numbers for logging. Keeps a 4/4 head+tail window; never logs the full E.164. (pure) */
+export function redactPhone(s) {
+    if (!s)
+        return "<none>";
+    return s.replace(PHONE_RE, (p) => (p.length <= 8 ? "****" : `${p.slice(0, 4)}****${p.slice(-4)}`));
+}
+const isImageExt = (ext) => /^\.(png|jpe?g|gif|webp)$/i.test(ext);
+/** Guess a file extension from an attachment's contentType / filename (signal-cli gives us both as hints). (pure) */
+export function attachmentExt(contentType, filename) {
+    const ct = (contentType ?? "").toLowerCase();
+    if (ct.startsWith("image/")) {
+        if (ct.includes("png"))
+            return ".png";
+        if (ct.includes("jpeg") || ct.includes("jpg"))
+            return ".jpg";
+        if (ct.includes("gif"))
+            return ".gif";
+        if (ct.includes("webp"))
+            return ".webp";
+    }
+    const fromName = (filename ?? "").toLowerCase().match(/\.(png|jpe?g|gif|webp|mp4|mp3|ogg|m4a|pdf|txt)$/);
+    if (fromName)
+        return fromName[0];
+    if (ct.startsWith("audio/"))
+        return ".ogg";
+    if (ct.startsWith("video/"))
+        return ".mp4";
+    return ".bin";
+}
+/** Sniff a file extension from magic bytes — fallback when signal-cli's base64 attachment lacks a contentType. (pure) */
+export function extFromBytes(data) {
+    if (data.length >= 4 && data[0] === 0x89 && data[1] === 0x50 && data[2] === 0x4e && data[3] === 0x47)
+        return ".png";
+    if (data.length >= 2 && data[0] === 0xff && data[1] === 0xd8)
+        return ".jpg";
+    if (data.length >= 4 && data[0] === 0x47 && data[1] === 0x49 && data[2] === 0x46 && data[3] === 0x38)
+        return ".gif";
+    if (data.length >= 12 && data[0] === 0x52 && data[1] === 0x49 && data[2] === 0x46 && data[3] === 0x46 && data[8] === 0x57 && data[9] === 0x45 && data[10] === 0x42 && data[11] === 0x50)
+        return ".webp";
+    return ".bin";
+}
+/** Parse one signal-cli envelope → InboundMsg + the image attachments to fetch (pure; the fetch/download happens in
+ *  start()). Mirrors hermes' _handle_envelope: unwraps the {envelope:{...}} shape, handles plain dataMessage + edits,
+ *  filters our own outbound + stories. Filtering of OUR OWN number is done here via `selfNumber`. Returns the msg +
+ *  the image attachment refs (only images — other media is ignored, like Telegram/Matrix). null = skip. */
+export function parseSignalMessage(raw, selfNumber) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const env = raw.envelope ?? raw; // signal-cli wraps payloads as { envelope: {...} }
+    // Stories / typing / receipts / sync echoes carry no inbound dataMessage → skip. Also skip our own outbound
+    // (syncMessage is the echo of what WE sent from another linked device — never treat it as user input).
+    if (env.syncMessage)
+        return null;
+    if (env.storyMessage)
+        return null;
+    if (env.typingMessage || env.receiptMessage)
+        return null;
+    const sender = env.sourceNumber || env.sourceUuid || env.source;
+    if (!sender)
+        return null;
+    if (selfNumber && (env.sourceNumber === selfNumber || env.source === selfNumber))
+        return null; // our own message
+    // editMessage carries its updated dataMessage nested inside (mirrors hermes).
+    const data = env.dataMessage ?? env.editMessage?.dataMessage;
+    if (!data || typeof data !== "object")
+        return null;
+    const group = data.groupInfo;
+    const groupId = group?.groupId;
+    const chatId = groupId ? `group:${groupId}` : String(sender);
+    const atts = Array.isArray(data.attachments) ? data.attachments : [];
+    const images = atts
+        .filter((a) => a?.id && (String(a.contentType ?? "").startsWith("image/") || isImageExt(attachmentExt(a?.contentType, a?.filename))))
+        .map((a) => ({ id: String(a.id), contentType: a?.contentType, filename: a?.filename }));
+    const text = typeof data.message === "string" ? data.message : "";
+    if (!text && images.length === 0)
+        return null; // no text + no image (reaction/sticker/other media) → skip
+    return {
+        msg: {
+            chatId,
+            userId: String(sender),
+            userName: env.sourceName || String(sender),
+            text: text || "[图片]",
+        },
+        images,
+    };
+}
+export function signalAdapter(rpcUrl, selfNumber) {
+    const base = rpcUrl.replace(/\/+$/, ""); // trim trailing slashes
+    let rpcSeq = 0;
+    /** One JSON-RPC 2.0 call to the signal-cli daemon. Returns `result` (any) or null on error. */
+    async function rpc(method, params, signal) {
+        const id = `${method}_${++rpcSeq}`;
+        try {
+            const res = await fetch(`${base}/api/v1/rpc`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ jsonrpc: "2.0", method, params, id }),
+                signal,
+            });
+            if (!res.ok)
+                return null;
+            const j = (await res.json());
+            if (j.error) {
+                console.error(`hara gateway[signal]: RPC ${method} error:`, redactPhone(JSON.stringify(j.error)));
+                return null;
+            }
+            return j.result ?? null;
+        }
+        catch (e) {
+            if (signal?.aborted)
+                return null;
+            return null;
+        }
+    }
+    /** Recipient/group routing shared by send + sendFile (mirrors hermes). */
+    const target = (chatId) => {
+        const id = String(chatId);
+        return id.startsWith("group:") ? { groupId: id.slice(6) } : { recipient: [id] };
+    };
+    /** Fetch a signal-cli attachment by id (base64 over JSON-RPC) → a local path under ~/.hara/signal/media. */
+    async function downloadAttachment(ref) {
+        try {
+            const result = await rpc("getAttachment", { account: selfNumber, id: ref.id });
+            // signal-cli returns either a raw base64 string or { data: "base64..." }
+            const b64 = typeof result === "string" ? result : result && typeof result === "object" ? result.data : null;
+            if (!b64 || typeof b64 !== "string")
+                return null;
+            const bytes = Buffer.from(b64, "base64");
+            let ext = attachmentExt(ref.contentType, ref.filename);
+            if (ext === ".bin")
+                ext = extFromBytes(bytes); // last-resort magic-byte sniff
+            const dir = join(homedir(), ".hara", "signal", "media");
+            mkdirSync(dir, { recursive: true });
+            const path = join(dir, `sig_${Date.now()}_${ref.id.slice(-12)}${ext}`);
+            writeFileSync(path, bytes);
+            return path;
+        }
+        catch {
+            return null;
+        }
+    }
+    return {
+        name: "signal",
+        async send(chatId, text) {
+            for (const part of chunkText(text || "(empty)", 4000)) {
+                await rpc("send", { account: selfNumber, message: part, ...target(chatId) });
+            }
+        },
+        async sendFile(chatId, filePath) {
+            // Signal has no separate photo/document endpoints — everything is an `attachments` path on `send`.
+            // signal-cli reads the file off the local disk by path, so we just hand it the path (no upload step).
+            await rpc("send", { account: selfNumber, message: "", attachments: [filePath], ...target(chatId) }).catch(() => { });
+            // (readFileSync/basename imported for parity with the other adapters' file plumbing; signal-cli reads by path.)
+            void readFileSync;
+            void basename;
+        },
+        async start(onMessage, signal) {
+            console.error(`hara gateway[signal]: polling signal-cli daemon at ${base} as ${redactPhone(selfNumber)} (ensure \`signal-cli -a <number> daemon --http\` is running).`);
+            while (!signal.aborted) {
+                try {
+                    // JSON-RPC `receive` drains all envelopes queued since the last call. timeout is the long-poll seconds
+                    // the daemon will hold the request open waiting for new messages (server-side block → low-latency, low-spin).
+                    const result = await rpc("receive", { account: selfNumber, timeout: 30 }, signal);
+                    const envelopes = Array.isArray(result) ? result : result ? [result] : [];
+                    for (const raw of envelopes) {
+                        const parsed = parseSignalMessage(raw, selfNumber);
+                        if (!parsed)
+                            continue;
+                        for (const ref of parsed.images) {
+                            const path = await downloadAttachment(ref);
+                            if (path)
+                                (parsed.msg.images ??= []).push(path);
+                        }
+                        await onMessage(parsed.msg).catch(() => { });
+                    }
+                    if (envelopes.length === 0)
+                        await sleep(500); // daemon returned immediately (no long-poll support) → gentle spin
+                }
+                catch {
+                    if (signal.aborted)
+                        break;
+                    await sleep(2000); // daemon down / network blip → back off + retry (reconnect on drop)
+                }
+            }
+        },
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// signal-cli setup (the user does this once, OUTSIDE hara):
+//
+//   1. Install signal-cli           brew install signal-cli   (or download a release; needs a JRE)
+//   2. Register OR link the number  (a) register a NEW number:
+//                                       signal-cli -a +1555… register        # solve the captcha it prompts for
+//                                       signal-cli -a +1555… verify 123456    # the SMS code
+//                                   (b) OR link to an EXISTING phone as a secondary device:
+//                                       signal-cli link -n "hara"             # scan the QR from Signal app → Linked devices
+//   3. Run the HTTP/JSON-RPC daemon signal-cli -a +1555… daemon --http localhost:8080
+//   4. Point hara at it             HARA_SIGNAL_RPC_URL=http://localhost:8080  HARA_SIGNAL_NUMBER=+1555…
+//                                   hara gateway --platform signal
+// ─────────────────────────────────────────────────────────────────────────────