@zhin.js/gateway 1.2.0 → 1.3.0

package/lib/http/console-rpc.js

@@ -5,31 +5,58 @@
  * error, requestId, errors?, missingEnv? }`, see `GatewayRpcHttpErrorReply`), every other
  * type is forwarded to the instance by the HTTP server.
  */
-import { auditActor, jsonResponse, } from '@zhin.js/host-http';
-import { GATEWAY_RPC } from '@zhin.js/console-protocol';
+import { auditActor, jsonResponse, unknownRpcLog, } from '@zhin.js/host-http';
+import { CONSOLE_DENIAL_REASONS, GATEWAY_RPC, GATEWAY_RPC_PERMISSIONS, } from '@zhin.js/console-protocol';
+import { isGatewayRpcType } from '../packages/rpc.js';
+import { gatewayPrincipalAllows } from '../packages/authorization.js';
+import { LOCAL_GATEWAY_RPC } from '../local/protocol.js';
 /** RPC types with this prefix belong to the gateway (unknown ones are refused as unmapped). */
 export const GATEWAY_RPC_PREFIX = 'gateway.';
+/**
+ * Socket-only RPC types ({@link LOCAL_GATEWAY_RPC}): they exist, but never over HTTP. Refused
+ * with 403 (`forbidden`, audit reason `socket_only`) rather than `unknown_rpc`, so an attempt to
+ * reach Console administration over HTTP stays visible in the audit log.
+ */
+const SOCKET_ONLY_TYPES = new Set(Object.values(LOCAL_GATEWAY_RPC));
 const READ_ONLY_TYPES = new Set([
     GATEWAY_RPC.LIST,
     GATEWAY_RPC.PLAN,
     GATEWAY_RPC.STATUS,
     GATEWAY_RPC.LOGS,
 ]);
+/** Why the gateway dispatcher refused `type` (`forbidden`). */
+function gatewayDenialReason(type, principal) {
+    if (!principal)
+        return CONSOLE_DENIAL_REASONS.NOT_AUTHENTICATED;
+    if (isGatewayRpcType(type) && !gatewayPrincipalAllows(principal, GATEWAY_RPC_PERMISSIONS[type])) {
+        return principal.kind === 'bootstrap' ? CONSOLE_DENIAL_REASONS.SETUP_REQUIRED : CONSOLE_DENIAL_REASONS.INSUFFICIENT_PERMISSION;
+    }
+    // The permission map admitted it; the service's own rule refused (e.g. bootstrap package limits).
+    return CONSOLE_DENIAL_REASONS.HANDLER_DENIED;
+}
 export function createGatewayConsoleRpc(dispatch) {
     return Object.freeze({
         async handle(message, context, tokenRegistry) {
             const type = typeof message.type === 'string' ? message.type : '';
             const requestId = message.requestId;
             const principal = context.principal;
-            const result = await dispatch({ type, data: message.data }, principal);
+            const socketOnly = SOCKET_ONLY_TYPES.has(type);
+            const result = socketOnly
+                ? { ok: false, error: { code: 'forbidden', status: 403, message: `RPC "${type.slice(0, 64)}" 只能通过本机网关套接字调用（zhin console …）` } }
+                : await dispatch({ type, data: message.data }, principal);
             const write = !READ_ONLY_TYPES.has(type);
+            const unknown = !result.ok && result.error.code === 'unknown_rpc';
             const outcome = result.ok ? 'ok' : result.error.code === 'forbidden' ? 'denied' : 'error';
-            if (write || outcome === 'denied') {
+            // zhinjs/zhin#1250: an unknown `gateway.*` type ran nothing and is not a refusal: not audited.
+            if (unknown)
+                unknownRpcLog.note(type);
+            else if (write || outcome === 'denied') {
                 try {
                     tokenRegistry.accessProvider?.audit?.({
                         actor: auditActor(principal),
                         action: `rpc:${type}`.slice(0, 256),
                         outcome,
+                        ...(outcome === 'denied' ? { detail: { type: type.slice(0, 256), reason: socketOnly ? CONSOLE_DENIAL_REASONS.SOCKET_ONLY : gatewayDenialReason(type, principal) } } : {}),
                         ...(context.remoteAddress ? { ip: context.remoteAddress } : {}),
                     });
                 }

package/lib/http/gateway-console.js

@@ -12,7 +12,7 @@
  */
 import { join } from 'node:path';
 import { auditActor, authorizeConsoleRpc, jsonResponse, rpcAuditDetail, rpcAuditTarget, } from '@zhin.js/host-http';
-import { ONBOARDING_RPC } from '@zhin.js/console-protocol';
+import { CONSOLE_DENIAL_REASONS, IAM_RPC, ONBOARDING_RPC } from '@zhin.js/console-protocol';
 import { DEFAULT_ROOT_CONFIG_FILE_NAME } from '@zhin.js/plugin-runtime';
 import { createConfigDocument } from '@zhin.js/runtime';
 import { formatCompact, getLogger } from '@zhin.js/logger';
@@ -330,6 +330,7 @@ const ONBOARDING_STEPS = new Set(['ai', 'adapters', 'finish']);
 export function createGatewayAccountRpc(options) {
     return Object.freeze({
         owns: (type) => isIamRpc(type) || type === ONBOARDING_RPC.UPDATE,
+        types: () => [...Object.values(IAM_RPC), ONBOARDING_RPC.UPDATE],
         async handle(message, context, registry) {
             const noStore = { 'cache-control': 'no-store' };
             const requestId = message.requestId;
@@ -338,21 +339,21 @@ export function createGatewayAccountRpc(options) {
                 return jsonResponse(401, { success: false, code: 'unauthorized', error: 'Invalid or missing token', requestId }, noStore);
             }
             const decision = authorizeConsoleRpc(principal, message);
-            const audit = (outcome) => {
+            const audit = (outcome, reason) => {
                 try {
                     registry.accessProvider?.audit?.({
                         actor: auditActor(principal),
                         action: `rpc:${String(message.type ?? '')}`.slice(0, 256),
                         ...(decision.allowed && rpcAuditTarget(decision.rule) ? { target: rpcAuditTarget(decision.rule) } : {}),
                         outcome,
-                        detail: rpcAuditDetail(message),
+                        detail: reason ? { ...rpcAuditDetail(message), reason } : rpcAuditDetail(message),
                         ...(context.remoteAddress ? { ip: context.remoteAddress } : {}),
                     });
                 }
                 catch { /* audit never breaks a request */ }
             };
             if (!decision.allowed) {
-                audit('denied');
+                audit('denied', decision.reason);
                 return jsonResponse(403, { success: false, code: decision.code, error: decision.error, requestId }, noStore);
             }
             const result = isIamRpc(message.type)
@@ -361,7 +362,7 @@ export function createGatewayAccountRpc(options) {
             if (decision.write)
                 audit(result.status < 400 && result.body.success !== false ? 'ok' : 'error');
             else if (result.status === 403)
-                audit('denied');
+                audit('denied', CONSOLE_DENIAL_REASONS.HANDLER_DENIED);
             return jsonResponse(result.status, result.body, { ...noStore, ...result.headers });
         },
     });

package/lib/http/gateway-http-server.js

@@ -14,9 +14,10 @@
  * answer in time gives `504 { code: 'instance_timeout' }`, any other bridge failure
  * `502 { code: 'instance_error' }` (mapped from {@link InstanceTransportError}).
  */
-import { authorizeConsoleWebSocket, auditActor, createHttpRouter, extractBearerToken, jsonResponse, normalizePath, requestMeta, TokenRegistry, } from '@zhin.js/host-http';
+import { authorizeConsoleWebSocket, auditActor, createHttpRouter, extractBearerToken, jsonResponse, normalizePath, requestMeta, TokenRegistry, webSocketDenialReason, } from '@zhin.js/host-http';
 import { InstanceTransportError, } from '@zhin.js/host-http/bridge';
 import { createNodeHttpListener } from '@zhin.js/host-http/node';
+import { CONSOLE_CAPABILITIES_PATH, CONSOLE_FEATURES, GATEWAY_RPC, createConsoleCapabilities, mergeConsoleCapabilities, parseConsoleCapabilities, } from '@zhin.js/console-protocol';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { databaseBusyResponse, isDatabaseBusyError } from '../database/project-database.js';
 import { GATEWAY_RPC_PREFIX } from './console-rpc.js';
@@ -55,6 +56,8 @@ export class GatewayHttpServer {
     #retryAfter;
     #maxBody;
     #consoleRpc;
+    /** The instance connection (and route table) that has no capability route: asked once. */
+    #capabilitiesMissing;
     #rpcHandlers = new Set();
     #closed = false;
     #closeResult;
@@ -84,6 +87,10 @@ export class GatewayHttpServer {
                 summary: 'Console RPC (gateway-owned types answered by the gateway, the rest forwarded)',
                 tags: ['console'],
             });
+            router.route('GET', `${this.apiBase}${CONSOLE_CAPABILITIES_PATH}`, (request, context) => this.#capabilities(request, context), {
+                summary: 'Console capabilities (gateway-owned RPC types merged with the instance\'s)',
+                tags: ['console'],
+            });
             // Lowest precedence: every path no gateway route claims goes to the instance.
             router.route('ALL', '/*', (request, context) => this.#forward(request, context));
         }
@@ -243,6 +250,36 @@ export class GatewayHttpServer {
         }));
         return this.#instanceError(502, 'instance_error', 'unknown', 'The instance failed to answer', false);
     }
+    /**
+     * `GET {base}/console/capabilities` (zhinjs/zhin#1250): the RPC types the gateway answers itself,
+     * merged with the instance's reply. While the instance is not answering (or predates the route)
+     * the reply says `complete: false`, so the Console reads it again later.
+     */
+    async #capabilities(request, context) {
+        const own = [...this.#rpcHandlers].flatMap(handler => handler.types?.() ?? []);
+        const gateway = createConsoleCapabilities({
+            rpc: [...(this.#consoleRpc ? Object.values(GATEWAY_RPC) : []), ...own],
+            features: [CONSOLE_FEATURES.UNKNOWN_RPC_CODE, CONSOLE_FEATURES.DENIAL_REASONS, CONSOLE_FEATURES.GATEWAY],
+        });
+        let instance = createConsoleCapabilities({ rpc: [], complete: false });
+        const transport = this.#readyTransport();
+        // An instance that predates the route refuses it (and audits that): ask it once per route table.
+        const revision = transport?.routes().revision;
+        const missing = this.#capabilitiesMissing;
+        if (transport && !(missing?.transport === transport && missing.revision === revision)) {
+            try {
+                const response = await this.#forward(request, context);
+                const body = response.ok ? await response.json().catch(() => null) : null;
+                const parsed = parseConsoleCapabilities(body?.data);
+                if (parsed)
+                    instance = parsed;
+                else if (response.status === 403 || response.status === 404)
+                    this.#capabilitiesMissing = { transport, revision };
+            }
+            catch { /* the instance part stays unknown */ }
+        }
+        return jsonResponse(200, { success: true, data: mergeConsoleCapabilities(gateway, instance) }, { 'cache-control': 'no-store' });
+    }
     /**
      * `POST {base}/console/request`: the router authenticated and authorized the route; `gateway.*`
      * types are dispatched here (the dispatcher checks the per-RPC permission), the rest are
@@ -392,6 +429,7 @@ export class GatewayHttpServer {
                     actor: auditActor(principal),
                     action: `ws:${pathname}`,
                     outcome: 'denied',
+                    detail: { reason: webSocketDenialReason(principal, pathname) },
                     ...(request.remoteAddress ? { ip: request.remoteAddress } : {}),
                 });
             }

package/lib/http/plugin-switch-rpc.js

@@ -17,7 +17,7 @@
  */
 import { join } from 'node:path';
 import { auditActor, authorizeConsoleRpc, jsonResponse, rpcAuditDetail, rpcAuditTarget, } from '@zhin.js/host-http';
-import { FEATURE_RPC, PLUGIN_RPC, isGlobalFeatureSwitch, } from '@zhin.js/console-protocol';
+import { CONSOLE_DENIAL_REASONS, FEATURE_RPC, PLUGIN_RPC, isGlobalFeatureSwitch, } from '@zhin.js/console-protocol';
 import { DEFAULT_ROOT_CONFIG_FILE_NAME, FEATURE_OVERRIDES_KEY } from '@zhin.js/plugin-runtime';
 import { collectFeatureOverrideWarnings, createConfigDocument } from '@zhin.js/runtime';
 import { formatCompact, getLogger } from '@zhin.js/logger';
@@ -39,6 +39,7 @@ export function createGatewayPluginSwitchRpc(options) {
     return Object.freeze({
         owns: (type) => type === PLUGIN_RPC.SET_ENABLED || type === FEATURE_RPC.SET_ENABLED,
         claims: isGatewayPluginSwitch,
+        types: () => [PLUGIN_RPC.SET_ENABLED, FEATURE_RPC.SET_ENABLED],
         async handle(message, context, registry) {
             const noStore = { 'cache-control': 'no-store' };
             const type = String(message.type ?? '');
@@ -49,27 +50,27 @@ export function createGatewayPluginSwitchRpc(options) {
             }
             // plugin.manage: `plugin:set-enabled` is mapped to it, `feature.set-enabled` is refined by level.
             const decision = authorizeConsoleRpc(principal, message);
-            const audit = (outcome) => {
+            const audit = (outcome, reason) => {
                 try {
                     registry.accessProvider?.audit?.({
                         actor: auditActor(principal),
                         action: `rpc:${type}`.slice(0, 256),
                         ...(decision.allowed && rpcAuditTarget(decision.rule) ? { target: rpcAuditTarget(decision.rule) } : {}),
                         outcome,
-                        detail: rpcAuditDetail(message),
+                        detail: reason ? { ...rpcAuditDetail(message), reason } : rpcAuditDetail(message),
                         ...(context.remoteAddress ? { ip: context.remoteAddress } : {}),
                     });
                 }
                 catch { /* audit never breaks a request */ }
             };
             if (!decision.allowed) {
-                audit('denied');
+                audit('denied', decision.reason);
                 return jsonResponse(403, { success: false, code: decision.code, error: decision.error, requestId }, noStore);
             }
             const reply = type === PLUGIN_RPC.SET_ENABLED
                 ? await setPluginEnabled(message, principal, options, readConfig)
                 : await setFeatureGlobal(message, principal, options, readConfig);
-            audit(reply.status < 400 && reply.body.success !== false ? 'ok' : reply.status === 403 ? 'denied' : 'error');
+            audit(reply.status < 400 && reply.body.success !== false ? 'ok' : reply.status === 403 ? 'denied' : 'error', reply.status === 403 ? CONSOLE_DENIAL_REASONS.HANDLER_DENIED : undefined);
             return jsonResponse(reply.status, { ...reply.body, requestId }, noStore);
         },
     });

package/lib/packages/errors.js

@@ -2,6 +2,7 @@ const STATUS = {
     invalid_input: 400,
     forbidden: 403,
     unmapped: 403,
+    unknown_rpc: 404,
     conflict: 409,
     unavailable: 503,
     internal: 500,

package/lib/packages/rpc.d.ts

@@ -3,7 +3,7 @@
  * `gateway.instance.*`, ADR 0054 §4 / §5). The HTTP server maps envelopes onto it; the permission
  * map in `@zhin.js/console-protocol` is checked here, then each service applies its own rules.
  */
-import { type GatewayInstanceStatus, type GatewayRpcRequest, type GatewayRpcResponse, type GatewayRpcType } from '@zhin.js/console-protocol';
+import { type GatewayInstanceStatus, type GatewayRpcRequest, type GatewayRpcResponse, type GatewayRpcType, type ConsoleProcessSample } from '@zhin.js/console-protocol';
 import type { InstanceStatus, InstanceStopOptions } from '../supervisor/instance-supervisor.js';
 import type { InstanceLogLine } from '../supervisor/instance-logs.js';
 import { type GatewayPrincipal } from './authorization.js';
@@ -28,3 +28,8 @@ export declare function createGatewayRpcDispatcher(dependencies: GatewayRpcDepen
 /** Dispatches one gateway RPC; never throws (errors become `{ ok: false }`). */
 export declare function dispatchGatewayRpc(request: GatewayRpcRequest, principal: GatewayPrincipal | undefined, dependencies: GatewayRpcDependencies): Promise<GatewayRpcResponse>;
 export declare function instanceStatus(status: InstanceStatus): GatewayInstanceStatus;
+/**
+ * The gateway's own process sample (#1250): one `process.memoryUsage()` call, labeled
+ * `role: 'gateway'`, so the Console never mixes it with the instance's numbers.
+ */
+export declare function sampleGatewayProcess(): ConsoleProcessSample | undefined;

package/lib/packages/rpc.js

@@ -20,8 +20,9 @@ export function createGatewayRpcDispatcher(dependencies) {
 export async function dispatchGatewayRpc(request, principal, dependencies) {
     try {
         const type = request?.type;
+        // zhinjs/zhin#1250: a `gateway.*` type this gateway does not have is not a refusal (not audited).
         if (!isGatewayRpcType(type))
-            throw new GatewayError('unmapped', `RPC "${String(type ?? '').slice(0, 64)}" 未登记权限`);
+            throw new GatewayError('unknown_rpc', `RPC "${String(type ?? '').slice(0, 64)}" 不存在`);
         if (!principal)
             throw new GatewayError('forbidden', '未登录');
         const packageMutation = type === GATEWAY_RPC.PLAN || type === GATEWAY_RPC.INSTALL;
@@ -69,7 +70,10 @@ async function handle(type, data, principal, deps) {
             return packagesOf(deps).setEnabled({ plugin: data.plugin }, type === 'gateway.plugins.enable', {
                 principal, ...optionalBoolean(data, 'startInstance'),
             });
-        case 'gateway.instance.status': return instanceStatus(instanceOf(deps).status());
+        case 'gateway.instance.status': {
+            const gateway = sampleGatewayProcess();
+            return Object.freeze({ ...instanceStatus(instanceOf(deps).status()), ...(gateway ? { gateway } : {}) });
+        }
         case 'gateway.instance.logs': {
             const lines = data.lines === undefined ? DEFAULT_LOG_LINES : data.lines;
             if (typeof lines !== 'number' || !Number.isInteger(lines) || lines < 1 || lines > MAX_LOG_LINES) {
@@ -126,6 +130,28 @@ export function instanceStatus(status) {
         recentRestarts: status.recentRestarts,
     });
 }
+/**
+ * The gateway's own process sample (#1250): one `process.memoryUsage()` call, labeled
+ * `role: 'gateway'`, so the Console never mixes it with the instance's numbers.
+ */
+export function sampleGatewayProcess() {
+    try {
+        const memory = process.memoryUsage();
+        return Object.freeze({
+            role: 'gateway',
+            pid: process.pid,
+            uptime: process.uptime(),
+            memory: Object.freeze({
+                rss: memory.rss, heapUsed: memory.heapUsed, heapTotal: memory.heapTotal,
+                external: memory.external, arrayBuffers: memory.arrayBuffers,
+            }),
+            sampledAt: Date.now(),
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
 function record(value) {
     if (value === undefined || value === null)
         return {};

package/lib/packages/service.d.ts

@@ -1,4 +1,4 @@
-import type { GatewayAuthorizedPackage, GatewayPackageEvent, GatewayPackageList, GatewayPackageOperation, GatewayPackagePlan, GatewayPackageTransactionResult } from '@zhin.js/console-protocol';
+import type { GatewayAuthorizedPackage, GatewayInstalledPackageKind, GatewayPackageEvent, GatewayPackageList, GatewayPackageOperation, GatewayPackagePlan, GatewayPackageTransactionResult } from '@zhin.js/console-protocol';
 import { type InstallAllowlist, type MarketCatalogEntry } from '../onboarding/allowlist.js';
 import { type PackageManagerOutput } from '../onboarding/package-manager.js';
 import { type PluginManagementOptions } from '../plugin-management/workflow.js';
@@ -137,3 +137,5 @@ export declare class GatewayPackageService {
         readonly result: Promise<GatewayPackageTransactionResult>;
     };
 }
+/** `package.json#zhin` → what the dependency is to Zhin; anything without a Zhin manifest is a library. */
+export declare function installedPackageKind(zhin: unknown): GatewayInstalledPackageKind;

package/lib/packages/service.js

@@ -90,7 +90,12 @@ export class GatewayPackageService {
                 if (typeof range !== 'string')
                     continue;
                 const catalog = allowlist.get(name)?.kind;
-                packages.push(Object.freeze({ name, range, dependencyType, installedVersion: await this.#installedVersion(name), ...(catalog ? { catalog } : {}) }));
+                const installed = await this.#installedManifest(name);
+                packages.push(Object.freeze({
+                    name, range, dependencyType, installedVersion: installed?.version ?? null,
+                    ...(installed ? { kind: installed.kind } : {}),
+                    ...(catalog ? { catalog } : {}),
+                }));
             }
         }
         packages.sort((a, b) => a.name.localeCompare(b.name));
@@ -416,13 +421,19 @@ export class GatewayPackageService {
     #instanceState() {
         return this.#options.instance?.state ?? 'unmanaged';
     }
-    async #installedVersion(name) {
+    /**
+     * Installed version plus what the package is to Zhin (#1250): `package.json#zhin.type` `plugin`
+     * → `plugin`, `feature` → `feature`, no `zhin` manifest → `library`. Undefined when not installed.
+     */
+    async #installedManifest(name) {
         try {
             const manifest = JSON.parse(await readFile(join(this.#root, 'node_modules', ...name.split('/'), 'package.json'), 'utf8'));
-            return manifest.name === name && typeof manifest.version === 'string' ? manifest.version : null;
+            if (manifest.name !== name || typeof manifest.version !== 'string')
+                return undefined;
+            return { version: manifest.version, kind: installedPackageKind(manifest.zhin) };
         }
         catch {
-            return null;
+            return undefined;
         }
     }
     /** Cross-process exclusion (CLI and gateway); separate from the workflow's own lock file. */
@@ -502,3 +513,10 @@ function failureMessage(error) {
     const cause = error instanceof PluginManagementOperationError ? error.cause : error;
     return cause instanceof Error ? cause.message : String(cause);
 }
+/** `package.json#zhin` → what the dependency is to Zhin; anything without a Zhin manifest is a library. */
+export function installedPackageKind(zhin) {
+    if (!zhin || typeof zhin !== 'object' || Array.isArray(zhin))
+        return 'library';
+    const type = zhin.type;
+    return type === 'plugin' ? 'plugin' : type === 'feature' ? 'feature' : 'library';
+}

package/lib/plugin-management/use-cases.js

@@ -1,11 +1,11 @@
 export const pluginUseCases = Object.freeze([
     {
-        id: 'rss-subscription', title: '订阅 RSS 新文章', summary: '在任务中心选择精确目标，创建独立管理员 RSS 订阅。',
+        id: 'rss-subscription', title: '订阅 RSS 新文章', summary: '在 Console「运维 → 定时任务 → 管理员任务」选择精确目标，创建独立管理员 RSS 订阅。',
         packageName: '@zhin.js/plugin-rss', mode: 'administrator-task',
         steps: ['通过现有安装计划安装 RSS 插件，配置持久 Database Host、Schedule Host 与支持精确目标的 Outbound Host，保存并应用。',
-            '在 Console 任务中心选择当前已加载的 RSS 实例，核对账号、会话、父容器和线程。',
+            '在 Console「运维 → 定时任务」的「管理员任务」页签选择当前已加载的 RSS 实例，核对账号、会话、父容器和线程。',
             '填写 HTTP(S) RSS / Atom 地址，阅读抓取和发送影响后创建；保存不会抓取源站或发送测试消息。',
-            '等待实例轮询首次成功抓取建立基线；后续新文章才推送，可在任务中心暂停、编辑、恢复或取消。'],
+            '等待实例轮询首次成功抓取建立基线；后续新文章才推送，可在「运维 → 定时任务 → 管理员任务」暂停、编辑、恢复或取消。'],
         limitations: ['首次和暂停恢复后的首次成功抓取只建基线，不补发历史；每轮只检查源前 20 条，最多展示 maxItems 条，其余提示查看源站，不续轮补发。',
             '管理员订阅与聊天订阅独立；聊天 rss-list、rss-remove 和 rss-check 不管理或触发管理员任务。',
             '投递未确认时不自动重试或恢复，只能取消；先核实目标会话，确需继续时再新建。'],
@@ -14,7 +14,7 @@ export const pluginUseCases = Object.freeze([
         id: 'reminder', title: '创建定时提醒', summary: '指定账号、会话与时间，创建可查看、暂停和取消的管理员提醒。',
         packageName: '@zhin.js/plugin-reminder', mode: 'administrator-task',
         steps: ['通过现有安装计划安装持久提醒插件，配置 Database Host 并应用。',
-            '在 Console 任务中心选择当前已加载的提醒实例，检查当前版本与可用表单。',
+            '在 Console「运维 → 定时任务」的「管理员任务」页签选择当前已加载的提醒实例，检查当前版本与可用表单。',
             '选择精确投递账号及会话，填写含时区的时间和内容，确认未来发送的效果后创建。',
             '查看下次执行时间与实际结果；投递不确定时先核对目标会话，不盲目重建。'],
         limitations: ['Console 只管理管理员任务；聊天创建的提醒仍归原发送者。',
@@ -54,11 +54,11 @@ export const pluginUseCases = Object.freeze([
 ].map(item => Object.freeze({ ...item, steps: Object.freeze(item.steps), limitations: Object.freeze(item.limitations) })));
 const englishUseCases = {
     'rss-subscription': {
-        title: 'Subscribe to RSS updates', summary: 'Choose an exact delivery target and create a separate administrator RSS subscription.',
+        title: 'Subscribe to RSS updates', summary: 'In Operations → Scheduled tasks → Administrator tasks, choose an exact delivery target and create a separate administrator RSS subscription.',
         steps: ['Install the RSS plugin through the existing installation plan. Configure persistent Database, Schedule and Outbound Hosts with exact-target support, then save and apply.',
-            'Select a loaded RSS instance in Console Tasks. Check its account, conversation, parent container and thread.',
+            'In Console, open Operations → Scheduled tasks → Administrator tasks and select a loaded RSS instance. Check its account, conversation, parent container and thread.',
             'Enter an HTTP(S) RSS or Atom URL, review fetching and delivery effects, then create. Saving does not fetch the feed or send a test message.',
-            'Wait for the first successful poll to establish a baseline. Only later articles are delivered. Use Tasks to pause, edit, resume or cancel.'],
+            'Wait for the first successful poll to establish a baseline. Only later articles are delivered. Pause, edit, resume or cancel it under Operations → Scheduled tasks → Administrator tasks.'],
         limitations: ['The first successful fetch after creation or resuming only establishes a baseline; it does not replay history. Each poll examines the first 20 feed entries and displays at most maxItems, with a link to the feed for the remainder; there is no later catch-up.',
             'Administrator subscriptions and chat subscriptions are separate. Chat rss-list, rss-remove and rss-check do not manage or trigger administrator tasks.',
             'An unconfirmed delivery is not automatically retried or resumed. Cancel it, check the destination, and create a new task only if needed.'],
@@ -66,7 +66,7 @@ const englishUseCases = {
     reminder: {
         title: 'Create a scheduled reminder', summary: 'Choose an account, conversation and time, then manage an administrator reminder.',
         steps: ['Install the persistent reminder plugin, configure a Database Host and apply.',
-            'Select a loaded reminder instance in Console Tasks and check its current version and form.',
+            'In Console, open Operations → Scheduled tasks → Administrator tasks, select a loaded reminder instance and check its current version and form.',
             'Choose the exact account and conversation, enter a time with an offset and the content, and confirm the future delivery effect.',
             'Check the next execution time and actual result. If delivery is uncertain, inspect the destination before creating another task.'],
         limitations: ['Console manages administrator tasks only. Chat reminders still belong to the actual sender.',

package/lib/plugin-management/workflow.d.ts

@@ -1,5 +1,5 @@
 import { type SnapshotReader } from '@zhin.js/plugin-runtime';
-import type { PluginInstallPlan, PluginManagementPort, PluginManagementState, PluginUninstallPlan, PluginUpdatePlan, PluginVerificationResult, PluginVerificationPlan } from '@zhin.js/host-http';
+import type { PluginDependencyCheck, PluginInspectOptions, PluginInstallPlan, PluginManagementPort, PluginManagementState, PluginUninstallPlan, PluginUpdatePlan, PluginVerificationResult, PluginVerificationPlan } from '@zhin.js/host-http';
 import type { ConsoleConfigExplanation, GatewayPluginConfigurationNeed } from '@zhin.js/console-protocol';
 import type { PluginManagementActivity } from './activity.js';
 export interface PluginManagementOptions {
@@ -67,7 +67,13 @@ export interface PluginEnablementPlan {
 export declare class PluginManagementWorkflow implements PluginManagementPort {
     #private;
     constructor(projectRoot: string, options?: PluginManagementOptions);
-    inspect(request: string): Promise<PluginManagementState>;
+    inspect(request: string, options?: PluginInspectOptions): Promise<PluginManagementState>;
+    /**
+     * The project-wide dependency graph check `inspect` runs for every declared, enabled plugin.
+     * Callers inspecting many plugins (Console attention) run it once here and pass
+     * `{ dependencies: 'skip' }` to `inspect`.
+     */
+    checkDependencies(): Promise<PluginDependencyCheck>;
     /** Full-scope, metadata-only projection over the same file and generation observation as inspect. */
     explainConfiguration(instanceKey: string, expectedRevision: string): Promise<ConsoleConfigExplanation>;
     planInstall(request: string, options?: Pick<PluginInstallOptions, 'enable'>): Promise<PluginInstallPlan>;

package/lib/plugin-management/workflow.js

@@ -209,16 +209,32 @@ export class PluginManagementWorkflow {
         const revision = config ? (await config.document.read()).revision : null;
         return { revision, projectRevision: createHash('sha256').update(JSON.stringify([source.revision, revision])).digest('hex') };
     }
-    async inspect(request) {
+    async inspect(request, options = {}) {
         const lease = this.#options.snapshots?.acquire();
         try {
-            return await this.#inspect(request, lease?.value);
+            return await this.#inspect(request, lease?.value, options);
         }
         finally {
             lease?.release();
         }
     }
-    async #inspect(request, snapshot) {
+    /**
+     * The project-wide dependency graph check `inspect` runs for every declared, enabled plugin.
+     * Callers inspecting many plugins (Console attention) run it once here and pass
+     * `{ dependencies: 'skip' }` to `inspect`.
+     */
+    async checkDependencies() {
+        const configuration = this.#configuration();
+        const document = configuration ? (await configuration.document.read()).document : {};
+        try {
+            await this.#checkDependencies(undefined, document);
+            return Object.freeze({ status: 'passed' });
+        }
+        catch (error) {
+            return Object.freeze({ status: 'failed', error: errorMessage(error) });
+        }
+    }
+    async #inspect(request, snapshot, options = {}) {
         const { configuration, source, document, declaration, projectRevision } = await this.#configurationObservation(snapshot);
         const entries = declaration.instances;
         const target = await this.#resolveTarget(request, entries);
@@ -236,13 +252,15 @@ export class PluginManagementWorkflow {
             throw new Error('Legacy plugin lifecycle state detected; run zhin migrate instances');
         const disabled = declaration.disabled.includes(target.instanceKey);
         if (installed.plugin && declared && !disabled) {
-            try {
-                await this.#checkDependencies(undefined, document);
-                dependencies = 'passed';
-            }
-            catch (error) {
-                dependencies = 'failed';
-                issues.push(errorMessage(error));
+            if (options.dependencies !== 'skip') {
+                try {
+                    await this.#checkDependencies(undefined, document);
+                    dependencies = 'passed';
+                }
+                catch (error) {
+                    dependencies = 'failed';
+                    issues.push(errorMessage(error));
+                }
             }
             validation = await configuration.store.validatePluginConfig(target.instanceKey, config[target.instanceKey] ?? {}, document);
         }

package/lib/supervisor/instance-supervisor.d.ts

@@ -17,7 +17,10 @@ export interface InstanceStatus {
     readonly pid?: number;
     /** Epoch ms of the current child's `ready`. */
     readonly startedAt?: number;
-    /** Runtime generation reported by the instance in `ready`. */
+    /**
+     * Committed Runtime generation of the current instance: reported in `ready`, then advanced by
+     * every route table the instance publishes after a hot reload commits (#1250).
+     */
     readonly generation?: number;
     /** Protocol version reported by the instance in `ready`. */
     readonly protocolVersion?: number;

package/lib/supervisor/instance-supervisor.js

@@ -55,6 +55,8 @@ export class InstanceSupervisor extends EventEmitter {
     #backoffTimer;
     #restartTimes = [];
     #ready;
+    /** Latest committed generation of the current child (`ready`, then each route table). */
+    #generation;
     #startedAt;
     #lastExit;
     #lastFailure;
@@ -76,7 +78,7 @@ export class InstanceSupervisor extends EventEmitter {
             state: this.#state,
             ...(child?.process.pid !== undefined ? { pid: child.process.pid } : {}),
             ...(this.#startedAt !== undefined && this.#state === 'running' ? { startedAt: this.#startedAt } : {}),
-            ...(this.#ready?.generation !== undefined ? { generation: this.#ready.generation } : {}),
+            ...(this.#generation !== undefined ? { generation: this.#generation } : {}),
             ...(this.#ready ? { protocolVersion: this.#ready.version } : {}),
             lastExitCode: this.#lastExit?.code ?? null,
             lastExitSignal: this.#lastExit?.signal ?? null,
@@ -153,6 +155,7 @@ export class InstanceSupervisor extends EventEmitter {
         const { spawn: spec } = this.#options;
         const output = this.#options.output ?? 'pipe';
         this.#ready = undefined;
+        this.#generation = undefined;
         this.#startedAt = undefined;
         this.#setState('starting');
         let processHandle;
@@ -250,12 +253,19 @@ export class InstanceSupervisor extends EventEmitter {
             }
             child.ready = true;
             this.#ready = message.payload;
+            this.#noteGeneration(message.payload.generation);
             this.#startedAt = Date.now();
             this.#setState('running');
             this.emit('ready', message.payload);
             child.settleStart?.();
             return;
         }
+        if (message.type === 'routes') {
+            // The instance republishes its route table on every generation commit (hot reload,
+            // configuration apply); the table carries that generation (#1250).
+            this.#noteGeneration(message.payload.table.generation);
+            return;
+        }
         if (message.type !== 'restart-request')
             return;
         this.emit('restart-request', message.payload);
@@ -273,6 +283,13 @@ export class InstanceSupervisor extends EventEmitter {
         this.#setState('stopping');
         void this.#terminate(child, `restart:${message.payload.reason}`);
     }
+    /** Generations only move forward; a late table of an older generation never rolls status back. */
+    #noteGeneration(generation) {
+        if (generation === undefined)
+            return;
+        if (this.#generation === undefined || generation > this.#generation)
+            this.#generation = generation;
+    }
     #onExit(child, code, signal) {
         if (this.#child !== child)
             return;

package/lib/terminal/modules.d.ts

@@ -85,3 +85,15 @@ export declare function createModuleCache(loaders?: TerminalModuleLoaders): {
     pty(): Promise<ModuleLoadResult<PtyModule>>;
     ssh(): Promise<ModuleLoadResult<SshModule>>;
 };
+/**
+ * Whether `error` says the package itself cannot be resolved (not installed), as opposed to the
+ * package loading but failing inside (e.g. node-pty's `pty.node` missing because pnpm skipped its
+ * build script, or an addon built for another Node.js ABI).
+ */
+export declare function isPackageNotInstalledError(name: string, error: unknown): boolean;
+/**
+ * Operator hint for an optional terminal module that failed to load (#1250). Distinguishes "not
+ * installed" from "installed but its native addon was not built" — the usual cause with pnpm, which
+ * skips dependency build scripts unless `allowBuilds` lets them run. Matches `zhin doctor`'s fix text.
+ */
+export declare function moduleLoadFailureHint(name: string, error: unknown): string;