@nanhara/hara 0.131.1 → 0.132.1

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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.132.1 — 2026-07-22 — stable native release gates
+
+- Native release tests now wait for observable child-process and terminal-render handshakes within explicit
+  upper bounds instead of assuming fixed startup delays. This removes an Intel macOS runner race that could
+  read fixture state before Node or Ink had started while preserving the timeout, process-tree cleanup, MCP
+  diagnostic-boundary, and command-history assertions.
+- This patch carries the observable gateway status, scoped web proxy, full config redaction, and
+  user-managed organization connection features introduced in 0.132.0 into the verified standalone and
+  Desktop release train. Upgrade with `npm i -g @nanhara/hara@0.132.1`.
+
+## 0.132.0 — 2026-07-22 — observable chat gateways and scoped web proxies
+
+- `hara gateway status --platform <name>` now reports redacted credential readability, the live
+  credential-scoped lease/PID, transport state, start time, last connection/poll/message, bounded error code,
+  and one focused action. The same read-only data is available to Desktop through
+  `settings.gateways.list`; no model call, chat content, credential id, token, URL, or raw transport error is
+  stored or returned. WeChat status distinguishes missing, malformed, and readable QR login state, while
+  Feishu lifecycle comes from the SDK's actual connect/reconnect/error callbacks.
+- `web_fetch` and `web_search` now honor `HTTPS_PROXY`, `HTTP_PROXY`, lowercase equivalents, `NO_PROXY`,
+  `HARA_WEB_PROXY`, or global `~/.hara/config.json` key `proxy`. Proxy dispatch is scoped to those two web
+  tools: model/provider, Control enrollment, and chat gateway traffic are unchanged. `web_fetch` still
+  resolves and rejects internal targets before every redirect and sends the approved public IP in the
+  CONNECT tunnel, preserving its DNS-rebinding/SSRF boundary even when a proxy is used.
+- Proxy URLs and every `*ApiKey` config value are masked by `hara config get`; invalid proxy errors do not
+  echo the supplied value. The proxy transport uses patched Undici 7.28.0, and Hono/node-server/fast-uri
+  transitive dependencies are pinned to their current security fixes.
+- Desktop can now list, add, re-enroll, switch, check, and locally remove user-provided organization
+  connections through authenticated `settings.organizations.*` Serve methods. Enrollment rejects redirects,
+  embedded URL credentials, and non-HTTPS remote endpoints; one-time codes are never persisted or returned,
+  while scoped device tokens remain only in the private `profiles.json` store. No enterprise endpoint is
+  preconfigured by Hara.
+- Upgrade with `npm i -g @nanhara/hara@0.132.0`.
+
 ## 0.131.1 — 2026-07-21 — authenticated macOS standalone assets
 
 - Darwin arm64 and Intel standalone binaries are now built on their matching native macOS runners,

package/README.md

@@ -127,6 +127,17 @@ hara config set apiKey   ...
 hara config set model    ...
 ```
 
+**Proxy for web tools in mainland/restricted networks** — only `web_fetch` and `web_search` use it:
+```bash
+export HTTPS_PROXY=http://127.0.0.1:7890
+# or persist the same endpoint privately:
+hara config set proxy http://127.0.0.1:7890
+```
+`HTTP_PROXY`, lowercase variants, `NO_PROXY`, and `HARA_WEB_PROXY` are supported. Model/provider calls,
+organization enrollment, and chat gateways are not silently redirected. Even through a proxy, `web_fetch`
+pins each DNS-approved public IP and rechecks redirects; authenticated proxy URLs are masked by
+`hara config get`.
+
 **Vision** — hara **auto-detects** whether your main model can see images. A vision model (Claude, gpt-4o,
 qwen-vl, glm-4v…) gets pasted images **inline**. For a **text-only** model (DeepSeek, coding models), set a
 describer — the "eyes" — and hara OCRs/describes each pasted image into text first:
@@ -183,6 +194,7 @@ hara --sandbox workspace-write   # confine shell writes to the project (macOS Se
 hara --cwd /path/to/project      # explicitly select a workspace without changing your shell directory
 hara -c                    # resume the most recent session in this directory
 hara --profile work        # use a named profile from ~/.hara/config.json
+hara profile add work --gateway https://control.example.com --code <one-time-code>  # user-added org route
 hara -m glm-5              # pick a model
 ```
 
@@ -331,6 +343,9 @@ start an external tool server.
 **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.
+Organization connections are never prefilled: add one with `hara profile add <id> --gateway <https-url>
+--code <one-time-code>` or in Desktop's AI & models settings. The registration code is exchanged once and
+discarded; only the scoped, revocable device credential is retained in the private `~/.hara/profiles.json`.
 `.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

package/dist/config.js

@@ -76,7 +76,7 @@ export function providerCatalog() {
         ...(PROVIDER_DEFAULTS[id].baseURL ? { defaultBaseURL: PROVIDER_DEFAULTS[id].baseURL } : {}),
     }));
 }
-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", "guardian", "notify", "runTimeoutMs", "maxAgentRounds", "vimMode", "autoCompact", "fileCheckpoints", "updateCheck", "fallbackModel", "fallbackProvider", "fallbackBaseURL", "fallbackApiKey", "reasoningEffort"];
+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", "guardian", "notify", "runTimeoutMs", "maxAgentRounds", "vimMode", "autoCompact", "fileCheckpoints", "updateCheck", "proxy", "fallbackModel", "fallbackProvider", "fallbackBaseURL", "fallbackApiKey", "reasoningEffort"];
 export const REASONING_EFFORTS = ["off", "low", "medium", "high", "max"];
 export const APPROVAL_MODES = ["suggest", "auto-edit", "full-auto"];
 export const SANDBOX_MODES = ["off", "workspace-write", "read-only"];
@@ -492,6 +492,7 @@ export function loadConfig(opts = {}) {
     const autoCompact = !(process.env.HARA_AUTO_COMPACT === "0" || merged.autoCompact === false || merged.autoCompact === "false"); // default ON
     const fileCheckpoints = !(process.env.HARA_CHECKPOINTS === "0" || merged.fileCheckpoints === false || merged.fileCheckpoints === "false"); // default ON
     const updateCheck = !(process.env.HARA_UPDATE_CHECK === "0" || merged.updateCheck === false || merged.updateCheck === "false"); // default ON
+    const proxy = typeof merged.proxy === "string" && merged.proxy.trim() ? merged.proxy.trim() : undefined;
     const fallbackModel = nonBlankEnv(process.env.HARA_FALLBACK_MODEL) ?? merged.fallbackModel;
     const requestedFallbackProvider = nonBlankEnv(process.env.HARA_FALLBACK_PROVIDER) ?? merged.fallbackProvider;
     const fallbackProvider = isProviderId(requestedFallbackProvider) ? requestedFallbackProvider : undefined;
@@ -501,7 +502,7 @@ export function loadConfig(opts = {}) {
     const reasoningEffort = reasoningRaw && ["off", "low", "medium", "high", "max"].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, guardian, hooks, notify, runTimeoutMs, maxAgentRounds, vimMode, autoCompact, fileCheckpoints, updateCheck, fallbackModel, fallbackProvider, fallbackBaseURL, fallbackApiKey, reasoningEffort, mcpServers, cwd: effectiveCwd };
+    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, routeModel, routeBaseURL, routeApiKey, guardian, hooks, notify, runTimeoutMs, maxAgentRounds, vimMode, autoCompact, fileCheckpoints, updateCheck, proxy, fallbackModel, fallbackProvider, fallbackBaseURL, fallbackApiKey, reasoningEffort, mcpServers, cwd: effectiveCwd };
 }
 export function providerEnvKey(provider) {
     return (PROVIDER_DEFAULTS[provider] ?? PROVIDER_DEFAULTS.anthropic).envKey;

package/dist/gateway/feishu.js

@@ -234,6 +234,7 @@ export function feishuAdapter(appId, appSecret) {
     // visibility so a reconnect is observable instead of a mystery silence.
     const wsHealth = new FeishuWsHealthMonitor();
     let failActiveStart;
+    let runtimeObserver;
     const wsClient = new lark.WSClient({
         appId,
         appSecret,
@@ -243,10 +244,12 @@ export function feishuAdapter(appId, appSecret) {
         handshakeTimeoutMs: 15_000,
         onReady: () => {
             wsHealth.ready();
+            runtimeObserver?.connected();
             console.error("hara feishu: ✓ ws connected");
         },
         onReconnecting: () => {
             const health = wsHealth.disconnect();
+            runtimeObserver?.error("reconnecting");
             console.error(`hara feishu: ws disconnected #${health.total} · ${health.hourCount}/1h · ${health.dayCount}/24h · ` +
                 `previous connection ${wsDuration(health.connectedForMs)} · auto-reconnecting (SDK does not expose close code/reason)`);
             if (health.alert) {
@@ -255,9 +258,11 @@ export function feishuAdapter(appId, appSecret) {
             }
         },
         onReconnected: () => {
+            runtimeObserver?.connected();
             console.error(`hara feishu: ✓ ws reconnected after ${wsDuration(wsHealth.reconnected())}`);
         },
         onError: (err) => {
+            runtimeObserver?.error("transport-terminal");
             const safe = redactKnownSecrets(String(err?.message ?? err), [appId, appSecret]).text
                 .replace(/\s+/gu, " ")
                 .slice(0, 300);
@@ -460,7 +465,8 @@ export function feishuAdapter(appId, appSecret) {
                 });
             });
         },
-        async start(onMessage, signal, shouldDownload) {
+        async start(onMessage, signal, shouldDownload, runtime) {
+            runtimeObserver = runtime;
             const runAbort = new AbortController();
             const relayAbort = () => {
                 runAbort.abort(signal.reason instanceof Error ? signal.reason : new Error("Feishu gateway cancelled"));
@@ -615,6 +621,8 @@ export function feishuAdapter(appId, appSecret) {
             }
             finally {
                 failActiveStart = undefined;
+                if (runtimeObserver === runtime)
+                    runtimeObserver = undefined;
                 runAbort.abort(new Error("Feishu gateway stopped"));
                 signal.removeEventListener("abort", relayAbort);
                 try {

package/dist/gateway/runtime-state.js

@@ -18,6 +18,8 @@ import { sameOpenedFileIdentity } from "../fs-identity.js";
 const PLATFORM = /^[a-z0-9][a-z0-9_-]{0,63}$/;
 const LOCK_BYTES = 4 * 1024;
 const LOCK_WAIT_MS = 5_000;
+const RUNTIME_STATUS_BYTES = 32 * 1024;
+const RUNTIME_STATUS_FILE = /^status-([a-z0-9][a-z0-9_-]{0,63})\.json$/;
 const STORE_BYTES = 256 * 1024;
 const DEFAULT_TTL_MS = 60 * 60_000;
 const DEFAULT_CAPACITY = 2_048;
@@ -341,6 +343,251 @@ export function acquireGatewayInstance(platformValue, options = {}) {
             throw new Error(`gateway '${displayPlatform}' stale instance could not be reclaimed`);
     }
 }
+const GATEWAY_RUNTIME_ERROR_CODES = new Set([
+    "network",
+    "platform-error",
+    "reconnecting",
+    "session-expired",
+    "transport-exited",
+    "transport-terminal",
+]);
+function optionalRuntimeTimestamp(value) {
+    return Number.isFinite(value) && value > 0 ? Math.trunc(value) : undefined;
+}
+function parseGatewayRuntimeStatus(snapshot, path) {
+    if (!snapshot)
+        return null;
+    let value;
+    try {
+        value = JSON.parse(snapshot.text);
+    }
+    catch {
+        throw new Error(`invalid gateway runtime status: ${path}`);
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`invalid gateway runtime status: ${path}`);
+    }
+    const record = value;
+    const state = record.state;
+    const error = record.lastErrorCode;
+    if (record.version !== 1
+        || typeof record.platform !== "string"
+        || checkedPlatform(record.platform) !== record.platform
+        || !Number.isSafeInteger(record.pid)
+        || record.pid <= 0
+        || !optionalRuntimeTimestamp(record.startedAt)
+        || !optionalRuntimeTimestamp(record.updatedAt)
+        || !["starting", "connected", "degraded", "stopped", "failed"].includes(state)
+        || (error !== undefined && !GATEWAY_RUNTIME_ERROR_CODES.has(error))) {
+        throw new Error(`invalid gateway runtime status: ${path}`);
+    }
+    for (const timestamp of [
+        record.lastConnectedAt,
+        record.lastPollAt,
+        record.lastMessageAt,
+        record.lastErrorAt,
+    ]) {
+        if (timestamp !== undefined && !optionalRuntimeTimestamp(timestamp)) {
+            throw new Error(`invalid gateway runtime status: ${path}`);
+        }
+    }
+    return record;
+}
+function gatewayRuntimeStatusPath(directory, runtimeScope) {
+    return join(directory, `status-${checkedPlatform(runtimeScope)}.json`);
+}
+/**
+ * Credential-scoped, redacted health writer for one live gateway. It stores only lifecycle timestamps and
+ * bounded error codes: never tokens, app ids, URLs, chat ids, message text, or raw transport errors.
+ */
+export class GatewayRuntimeReporter {
+    dir;
+    path;
+    now;
+    record;
+    tail = Promise.resolve();
+    writeWarningShown = false;
+    constructor(dir, path, now, record) {
+        this.dir = dir;
+        this.path = path;
+        this.now = now;
+        this.record = record;
+    }
+    static async open(runtimeScopeValue, platformValue, options = {}) {
+        const runtimeScope = checkedPlatform(runtimeScopeValue);
+        const platform = checkedPlatform(platformValue);
+        const dir = stateDirectory(options.home ?? homedir());
+        const path = gatewayRuntimeStatusPath(dir, runtimeScope);
+        const previous = parseGatewayRuntimeStatus(await readPrivateStateFileSnapshot(path, RUNTIME_STATUS_BYTES), path);
+        if (previous && previous.platform !== platform) {
+            throw new Error("gateway runtime status belongs to a different platform");
+        }
+        const now = options.now ?? Date.now;
+        const startedAt = now();
+        const reporter = new GatewayRuntimeReporter(dir, path, now, {
+            version: 1,
+            platform,
+            pid: process.pid,
+            startedAt,
+            updatedAt: startedAt,
+            state: "starting",
+            ...(previous?.lastConnectedAt ? { lastConnectedAt: previous.lastConnectedAt } : {}),
+            ...(previous?.lastPollAt ? { lastPollAt: previous.lastPollAt } : {}),
+            ...(previous?.lastMessageAt ? { lastMessageAt: previous.lastMessageAt } : {}),
+            ...(previous?.lastErrorAt ? { lastErrorAt: previous.lastErrorAt } : {}),
+            ...(previous?.lastErrorCode ? { lastErrorCode: previous.lastErrorCode } : {}),
+        });
+        reporter.scheduleWrite();
+        await reporter.flush();
+        return reporter;
+    }
+    scheduleWrite() {
+        this.record.updatedAt = this.now();
+        const payload = JSON.stringify({ ...this.record }, null, 2) + "\n";
+        this.tail = this.tail
+            .then(async () => {
+            const snapshot = await readPrivateStateFileSnapshot(this.path, RUNTIME_STATUS_BYTES);
+            const boundary = bindHaraPrivateStateWritePath(this.path, this.dir, "write gateway runtime status");
+            await atomicWriteText(this.path, payload, {
+                expected: snapshot?.text ?? null,
+                expectedIdentity: snapshot
+                    ? { dev: snapshot.dev, ino: snapshot.ino, mode: snapshot.mode, nlink: snapshot.nlink }
+                    : undefined,
+                mode: 0o600,
+                boundary,
+            });
+        })
+            .catch(() => {
+            if (!this.writeWarningShown) {
+                this.writeWarningShown = true;
+                console.error("hara gateway: runtime status could not be persisted; gateway operation continues");
+            }
+        });
+    }
+    connected() {
+        const now = this.now();
+        this.record.state = "connected";
+        this.record.lastConnectedAt = now;
+        this.scheduleWrite();
+    }
+    poll() {
+        const now = this.now();
+        this.record.state = "connected";
+        this.record.lastConnectedAt = now;
+        this.record.lastPollAt = now;
+        this.scheduleWrite();
+    }
+    message() {
+        const now = this.now();
+        this.record.state = "connected";
+        this.record.lastConnectedAt = now;
+        this.record.lastMessageAt = now;
+        this.scheduleWrite();
+    }
+    error(code) {
+        if (!GATEWAY_RUNTIME_ERROR_CODES.has(code))
+            return;
+        this.record.state = code === "transport-terminal" || code === "transport-exited" ? "failed" : "degraded";
+        this.record.lastErrorAt = this.now();
+        this.record.lastErrorCode = code;
+        this.scheduleWrite();
+    }
+    stopped(failed = false) {
+        this.record.state = failed ? "failed" : "stopped";
+        this.scheduleWrite();
+    }
+    async flush() {
+        await this.tail;
+    }
+}
+/** Aggregate all credential-scoped instances of one platform without exposing their scope hashes or ids. */
+export async function inspectGatewayRuntime(platformValue, runtimeScopes = [], options = {}) {
+    const platform = checkedPlatform(platformValue);
+    const dir = stateDirectory(options.home ?? homedir());
+    const scopes = new Set(runtimeScopes.map(checkedPlatform));
+    let unreadable = false;
+    for (const name of readdirSync(dir)) {
+        const match = RUNTIME_STATUS_FILE.exec(name);
+        if (!match)
+            continue;
+        const scope = match[1];
+        try {
+            const record = parseGatewayRuntimeStatus(await readPrivateStateFileSnapshot(join(dir, name), RUNTIME_STATUS_BYTES), join(dir, name));
+            if (record?.platform === platform)
+                scopes.add(scope);
+        }
+        catch {
+            if (scope === platform || scope.startsWith(`${platform}-`))
+                unreadable = true;
+        }
+    }
+    const pidAlive = options.pidAlive ?? defaultPidAlive;
+    const processIdentity = options.processIdentity ?? defaultProcessIdentity;
+    const candidates = [];
+    for (const scope of scopes) {
+        let record = null;
+        let lease = null;
+        try {
+            record = parseGatewayRuntimeStatus(await readPrivateStateFileSnapshot(gatewayRuntimeStatusPath(dir, scope), RUNTIME_STATUS_BYTES), gatewayRuntimeStatusPath(dir, scope));
+            if (record && record.platform !== platform)
+                continue;
+            lease = readLease(join(dir, `instance-${scope}.lock`), scope);
+        }
+        catch {
+            unreadable = true;
+        }
+        candidates.push({
+            scope,
+            record,
+            lease,
+            live: Boolean(lease && leaseOwnerAlive(lease.record, pidAlive, processIdentity)),
+        });
+    }
+    const live = candidates
+        .filter((candidate) => candidate.live && candidate.lease)
+        .sort((left, right) => (right.lease?.record.startedAt ?? 0) - (left.lease?.record.startedAt ?? 0));
+    const selected = live[0]
+        ?? candidates
+            .filter((candidate) => candidate.record)
+            .sort((left, right) => (right.record?.updatedAt ?? 0) - (left.record?.updatedAt ?? 0))[0];
+    const matchingRecord = selected?.record
+        && (!selected.lease || selected.record.pid === selected.lease.record.pid)
+        ? selected.record
+        : null;
+    const history = matchingRecord
+        ? {
+            ...(matchingRecord.lastConnectedAt ? { lastConnectedAt: matchingRecord.lastConnectedAt } : {}),
+            ...(matchingRecord.lastPollAt ? { lastPollAt: matchingRecord.lastPollAt } : {}),
+            ...(matchingRecord.lastMessageAt ? { lastMessageAt: matchingRecord.lastMessageAt } : {}),
+            ...(matchingRecord.lastErrorAt ? { lastErrorAt: matchingRecord.lastErrorAt } : {}),
+            ...(matchingRecord.lastErrorCode ? { lastErrorCode: matchingRecord.lastErrorCode } : {}),
+        }
+        : {};
+    if (live.length && selected?.lease) {
+        return {
+            running: true,
+            runningInstances: live.length,
+            state: matchingRecord?.state ?? "unknown",
+            pid: selected.lease.record.pid,
+            startedAt: selected.lease.record.startedAt,
+            ...history,
+        };
+    }
+    if (selected?.record) {
+        return {
+            running: false,
+            runningInstances: 0,
+            state: selected.record.state === "failed" ? "failed" : "stopped",
+            startedAt: selected.record.startedAt,
+            ...history,
+        };
+    }
+    return {
+        running: false,
+        runningInstances: 0,
+        state: unreadable ? "unreadable" : "unknown",
+    };
+}
 function parseProcessedStore(snapshot, path) {
     if (!snapshot)
         return [];

package/dist/gateway/serve.js

@@ -19,7 +19,7 @@ import { join, resolve } from "node:path";
 import { chmodSync, mkdirSync, writeFileSync, readFileSync, existsSync, statSync, rmSync } from "node:fs";
 import { redactToolSubprocessOutput, terminateSubprocessTree } from "../security/subprocess-env.js";
 import { cleanupOutboundSnapshot, cleanupOutboundSnapshots, consumeOutboundSnapshots, queueOutboundSnapshot, } from "./outbound-files.js";
-import { acquireGatewayInstance, gatewayRuntimeScope, GatewayFlowRunStore, GatewayInboundTracker, GatewayMessageDeduper, GatewayRunOutcomeStore, } from "./runtime-state.js";
+import { acquireGatewayInstance, gatewayRuntimeScope, GatewayFlowRunStore, GatewayInboundTracker, GatewayMessageDeduper, GatewayRuntimeReporter, GatewayRunOutcomeStore, inspectGatewayRuntime, } from "./runtime-state.js";
 /** Parse a leading slash-command from a chat message (pure). null if it isn't one. */
 export function parseCommand(text) {
     const m = /^\/([a-z]+)\b\s*([\s\S]*)$/i.exec(text.trim());
@@ -485,6 +485,154 @@ function runFlowAgent(prompt, _cwd, schema, signal) {
 }
 /** Re-exported so `hara gateway --platform weixin --login` can run the QR flow. */
 export { weixinLogin } from "./weixin.js";
+export const GATEWAY_PLATFORMS = [
+    "telegram",
+    "weixin",
+    "discord",
+    "feishu",
+    "slack",
+    "mattermost",
+    "matrix",
+    "dingtalk",
+    "wecom",
+    "signal",
+];
+const GATEWAY_LABELS = {
+    telegram: "Telegram",
+    weixin: "WeChat",
+    discord: "Discord",
+    feishu: "Feishu",
+    slack: "Slack",
+    mattermost: "Mattermost",
+    matrix: "Matrix",
+    dingtalk: "DingTalk",
+    wecom: "WeCom",
+    signal: "Signal",
+};
+function gatewayPlatform(value) {
+    const platform = canonicalGatewayPlatform(value);
+    if (!GATEWAY_PLATFORMS.includes(platform)) {
+        throw new Error(`unsupported gateway platform '${value}'`);
+    }
+    return platform;
+}
+function environmentConfiguration(values, runtimeScope, missingHint) {
+    const present = values.filter((value) => Boolean(value?.trim())).length;
+    return present === values.length
+        ? { state: "ready", runtimeScope: runtimeScope(), missingHint }
+        : { state: present === 0 ? "missing" : "incomplete", missingHint };
+}
+async function inspectGatewayConfiguration(platform) {
+    if (platform === "weixin") {
+        const { inspectWeixinCredentials } = await import("./weixin.js");
+        const inspected = inspectWeixinCredentials();
+        if (inspected.state === "ready") {
+            return {
+                state: "ready",
+                runtimeScope: gatewayRuntimeScope("weixin", inspected.credentials.user_id),
+                missingHint: "run `hara gateway --platform weixin --login`",
+            };
+        }
+        return {
+            state: inspected.state,
+            missingHint: inspected.state === "unreadable"
+                ? "repair the private WeChat login state, then log in again"
+                : "run `hara gateway --platform weixin --login`",
+        };
+    }
+    if (platform === "telegram") {
+        const token = process.env.HARA_TELEGRAM_TOKEN;
+        return environmentConfiguration([token], () => gatewayRuntimeScope("telegram", token), "set HARA_TELEGRAM_TOKEN");
+    }
+    if (platform === "discord") {
+        const token = process.env.HARA_DISCORD_TOKEN;
+        return environmentConfiguration([token], () => gatewayRuntimeScope("discord", token), "set HARA_DISCORD_TOKEN");
+    }
+    if (platform === "feishu") {
+        const appId = process.env.HARA_FEISHU_APP_ID;
+        const secret = process.env.HARA_FEISHU_APP_SECRET;
+        return environmentConfiguration([appId, secret], () => gatewayRuntimeScope("feishu", appId), "set HARA_FEISHU_APP_ID and HARA_FEISHU_APP_SECRET");
+    }
+    if (platform === "slack") {
+        const appToken = process.env.HARA_SLACK_APP_TOKEN;
+        const botToken = process.env.HARA_SLACK_BOT_TOKEN;
+        return environmentConfiguration([appToken, botToken], () => gatewayRuntimeScope("slack", appToken), "set HARA_SLACK_APP_TOKEN and HARA_SLACK_BOT_TOKEN");
+    }
+    if (platform === "mattermost") {
+        const url = process.env.HARA_MATTERMOST_URL;
+        const token = process.env.HARA_MATTERMOST_TOKEN;
+        return environmentConfiguration([url, token], () => gatewayRuntimeScope("mattermost", `${url}\0${token}`), "set HARA_MATTERMOST_URL and HARA_MATTERMOST_TOKEN");
+    }
+    if (platform === "matrix") {
+        const homeserver = process.env.HARA_MATRIX_HOMESERVER;
+        const token = process.env.HARA_MATRIX_TOKEN;
+        const userId = process.env.HARA_MATRIX_USER_ID;
+        return environmentConfiguration([homeserver, token, userId], () => gatewayRuntimeScope("matrix", `${homeserver}\0${userId}`), "set HARA_MATRIX_HOMESERVER, HARA_MATRIX_TOKEN, and HARA_MATRIX_USER_ID");
+    }
+    if (platform === "dingtalk") {
+        const clientId = process.env.HARA_DINGTALK_CLIENT_ID;
+        const secret = process.env.HARA_DINGTALK_CLIENT_SECRET;
+        return environmentConfiguration([clientId, secret], () => gatewayRuntimeScope("dingtalk", clientId), "set HARA_DINGTALK_CLIENT_ID and HARA_DINGTALK_CLIENT_SECRET");
+    }
+    if (platform === "wecom") {
+        const botId = process.env.HARA_WECOM_BOT_ID;
+        const secret = process.env.HARA_WECOM_SECRET;
+        return environmentConfiguration([botId, secret], () => gatewayRuntimeScope("wecom", botId), "set HARA_WECOM_BOT_ID and HARA_WECOM_SECRET");
+    }
+    const rpcUrl = process.env.HARA_SIGNAL_RPC_URL;
+    const number = process.env.HARA_SIGNAL_NUMBER;
+    return environmentConfiguration([rpcUrl, number], () => gatewayRuntimeScope("signal", `${rpcUrl}\0${number}`), "set HARA_SIGNAL_RPC_URL and HARA_SIGNAL_NUMBER");
+}
+function gatewayRecommendation(platform, configuration, runtime) {
+    const unresolvedError = runtime.lastErrorAt !== undefined
+        && runtime.state !== "connected"
+        && (runtime.lastConnectedAt === undefined || runtime.lastErrorAt >= runtime.lastConnectedAt);
+    if (unresolvedError && runtime.lastErrorCode === "session-expired" && platform === "weixin") {
+        return "re-login with `hara gateway --platform weixin --login`, then restart the gateway";
+    }
+    if (runtime.state === "degraded" || runtime.state === "failed" || runtime.state === "unreadable") {
+        return "inspect the redacted gateway log and restart the gateway if the error persists";
+    }
+    if (runtime.running)
+        return "none";
+    if (configuration.state !== "ready")
+        return configuration.missingHint;
+    return `run \`hara gateway --platform ${platform}\``;
+}
+/** Read-only, redacted gateway diagnosis shared by the CLI and Desktop serve protocol. */
+export async function gatewayStatus(platformValue) {
+    const platform = gatewayPlatform(platformValue);
+    const configuration = await inspectGatewayConfiguration(platform);
+    const runtime = await inspectGatewayRuntime(platform, configuration.runtimeScope ? [configuration.runtimeScope] : []);
+    // A long-running gateway can own environment-only credentials that are intentionally unavailable to the
+    // Desktop/CLI status process. Report that boundary explicitly instead of contradicting a live connection
+    // with "missing credentials". WeChat uses a shared private state file, so unreadability there stays visible.
+    const exposedConfiguration = platform !== "weixin"
+        && runtime.running
+        && configuration.state !== "ready"
+        ? "process-only"
+        : configuration.state;
+    return {
+        platform,
+        label: GATEWAY_LABELS[platform],
+        configuration: exposedConfiguration,
+        configured: exposedConfiguration === "ready" || exposedConfiguration === "process-only" || runtime.running,
+        running: runtime.running,
+        runningInstances: runtime.runningInstances,
+        runtimeState: runtime.state,
+        ...(runtime.pid ? { pid: runtime.pid } : {}),
+        ...(runtime.startedAt ? { startedAt: runtime.startedAt } : {}),
+        ...(runtime.lastConnectedAt ? { lastConnectedAt: runtime.lastConnectedAt } : {}),
+        ...(runtime.lastPollAt ? { lastPollAt: runtime.lastPollAt } : {}),
+        ...(runtime.lastMessageAt ? { lastMessageAt: runtime.lastMessageAt } : {}),
+        ...(runtime.lastErrorAt ? { lastErrorAt: runtime.lastErrorAt } : {}),
+        ...(runtime.lastErrorCode ? { lastErrorCode: runtime.lastErrorCode } : {}),
+        recommendation: gatewayRecommendation(platform, configuration, runtime),
+    };
+}
+export async function listGatewayStatuses(platforms = GATEWAY_PLATFORMS) {
+    return Promise.all(platforms.map((platform) => gatewayStatus(platform)));
+}
 async function buildAdapter(platform) {
     if (platform === "weixin") {
         const { loadWeixinCreds, weixinAdapter } = await import("./weixin.js");
@@ -694,6 +842,13 @@ export async function runGateway(opts) {
     // requested spelling only for startup/config hints; all persisted/routable identities are canonical.
     const platform = adapter.name || canonicalGatewayPlatform(requestedPlatform);
     const releaseInstance = acquireGatewayInstance(runtimeScope, { displayPlatform: platform });
+    let runtimeReporter;
+    try {
+        runtimeReporter = await GatewayRuntimeReporter.open(runtimeScope, platform);
+    }
+    catch {
+        console.error("hara gateway: runtime status is unavailable; gateway operation continues");
+    }
     let messageDeduper;
     let flowEffectReceipts;
     let flowRuns;
@@ -709,6 +864,9 @@ export async function runGateway(opts) {
         runOutcomes = await GatewayRunOutcomeStore.open(gatewayRuntimeScope("run-cache", runtimeScope));
     }
     catch (error) {
+        runtimeReporter?.error("transport-exited");
+        runtimeReporter?.stopped(true);
+        await runtimeReporter?.flush();
         releaseInstance();
         throw error;
     }
@@ -745,6 +903,7 @@ export async function runGateway(opts) {
     process.once("SIGTERM", stop);
     ac.signal.addEventListener("abort", closeQueue, { once: true });
     console.error(`hara gateway: ${adapter.name} up · cwd=${cwd} · ${allowlist.size} allowed user(s) · Ctrl-C to stop`);
+    let transportFailed = false;
     try {
         await pruneStaleMedia(platform).catch((error) => {
             console.error(`hara gateway: media cleanup failed — ${error instanceof Error ? error.message : String(error)}`);
@@ -753,6 +912,7 @@ export async function runGateway(opts) {
             try {
                 if (ac.signal.aborted)
                     return;
+                runtimeReporter?.message();
                 let existingRunOutcome = null;
                 let outcomeLoadError;
                 try {
@@ -1174,7 +1334,12 @@ export async function runGateway(opts) {
                     console.error(`hara gateway: inbound media cleanup failed — ${error instanceof Error ? error.message : String(error)}`);
                 });
             }
-        })()), ac.signal, (m) => shouldDownloadInboundMedia(m, allowlist));
+        })()), ac.signal, (m) => shouldDownloadInboundMedia(m, allowlist), runtimeReporter);
+    }
+    catch (error) {
+        transportFailed = true;
+        runtimeReporter?.error("transport-exited");
+        throw error;
     }
     finally {
         stop();
@@ -1184,11 +1349,18 @@ export async function runGateway(opts) {
         ac.signal.removeEventListener("abort", closeQueue);
         process.off("SIGINT", stop);
         process.off("SIGTERM", stop);
-        if (handlersDrained)
+        if (handlersDrained) {
             releaseInstance();
+            runtimeReporter?.stopped(transportFailed);
+            await runtimeReporter?.flush();
+        }
         else {
             console.error("hara gateway: shutdown timed out with inbound work still active; instance lease retained until callbacks finish.");
-            void inboundHandlers.waitForIdle().then(() => releaseInstance(), (error) => console.error(`hara gateway: could not release the deferred instance lease — ${error instanceof Error ? error.message : String(error)}`));
+            void inboundHandlers.waitForIdle().then(async () => {
+                releaseInstance();
+                runtimeReporter?.stopped(transportFailed);
+                await runtimeReporter?.flush();
+            }, (error) => console.error(`hara gateway: could not release the deferred instance lease — ${error instanceof Error ? error.message : String(error)}`));
         }
     }
 }