@zhin.js/gateway 1.1.2 → 1.3.0

package/lib/iam/rpc.js

@@ -18,7 +18,7 @@ export async function dispatchIamRpc(message, service, principal) {
     const ok = (data) => ({ status: 200, body: { success: true, data, type, requestId } });
     try {
         if (!service?.ready)
-            throw new IamError('unavailable', '当前数据库不能存储账号，或尚未就绪');
+            throw new IamError('unavailable', service?.publicUnavailable()?.message ?? 'Console 访问控制尚未就绪');
         const id = (key = 'id') => {
             const value = payload[key];
             if (typeof value !== 'string' || !value)

package/lib/iam/service.d.ts

@@ -83,7 +83,24 @@ export interface ConsoleIamServiceOptions {
      * Without it, levels are inferred from the permission suffix.
      */
     readonly pluginPermissions?: () => readonly ConsolePluginPermissionInfo[];
+    /**
+     * Why access control is closed right now (gateway.db not open, the import of the old project
+     * database tables not finished, ADR 0059 §3), or undefined. While closed the service fails
+     * closed: {@link ConsoleIamService.initialized} is true (the bootstrap token is refused),
+     * nothing authenticates and `/auth/*` answers 503 — an empty store never reads as "no owner".
+     */
+    readonly unavailable?: () => string | undefined;
+    /**
+     * Category of `unavailable` (`starting`, `store`, `migration`, `store_lost`, …). Anonymous HTTP
+     * callers only ever see this code and a generic message; the detail (paths, driver messages)
+     * goes to the logs and to the local owner (`zhin doctor`, `zhin console migrate`).
+     */
+    readonly unavailableCode?: () => string | undefined;
+    /** Called after the first owner was created (the gateway then makes sure its store marker exists). */
+    readonly onOwnerCreated?: () => void;
 }
+/** What anonymous callers learn while access control is closed (no paths or driver messages). */
+export declare const IAM_UNAVAILABLE_PUBLIC_MESSAGE = "Console \u8BBF\u95EE\u63A7\u5236\u6682\u4E0D\u53EF\u7528\uFF1A\u8BF7\u5728\u670D\u52A1\u5668\u4E0A\u8FD0\u884C zhin doctor \u67E5\u770B\u539F\u56E0";
 /**
  * What is wrong with a new account's username / password, or null — the rules
  * {@link ConsoleIamService.createUser} / `createOwner` enforce, for callers that must check before
@@ -104,6 +121,13 @@ export declare class ConsoleIamService implements ConsoleAccessProvider {
     #private;
     constructor(options: ConsoleIamServiceOptions);
     get ready(): boolean;
+    /** See {@link ConsoleIamServiceOptions.unavailable} (detail: logs and the local owner only). */
+    unavailableReason(): string | undefined;
+    /** `{ code, message }` safe for any HTTP caller while closed, or undefined. */
+    publicUnavailable(): {
+        readonly code: string;
+        readonly message: string;
+    } | undefined;
     /** Seeds built-in roles and loads the owner state; call after the database started. */
     start(options?: Readonly<{
         timers?: boolean;
@@ -201,3 +225,10 @@ export declare class ConsoleIamService implements ConsoleAccessProvider {
     /** Daily: audit older than the retention window and expired sessions. */
     cleanup(): Promise<void>;
 }
+/** Longest stored audit `detail` (characters of JSON). */
+export declare const AUDIT_DETAIL_MAX_LENGTH = 4096;
+/**
+ * Audit detail as JSON that always parses back: a detail longer than the column budget is
+ * replaced by `{ truncated, length, preview }` instead of being cut mid-string.
+ */
+export declare function auditDetailJson(detail: unknown): string;

package/lib/iam/service.js

@@ -21,6 +21,8 @@ export class IamError extends Error {
         this.status = STATUS[code];
     }
 }
+/** What anonymous callers learn while access control is closed (no paths or driver messages). */
+export const IAM_UNAVAILABLE_PUBLIC_MESSAGE = 'Console 访问控制暂不可用：请在服务器上运行 zhin doctor 查看原因';
 const USERNAME = /^[a-z0-9][a-z0-9._-]{1,63}$/u;
 /**
  * What is wrong with a new account's username / password, or null — the rules
@@ -48,6 +50,9 @@ export class ConsoleIamService {
     #limiter;
     #onError;
     #pluginPermissions;
+    #unavailable;
+    #unavailableCode;
+    #onOwnerCreated;
     #ready = false;
     #initialized;
     #cleanupTimer;
@@ -64,9 +69,22 @@ export class ConsoleIamService {
         this.#limiter = options.rateLimiter ?? new LoginRateLimiter({ now: this.#now });
         this.#onError = options.onError ?? (() => undefined);
         this.#pluginPermissions = options.pluginPermissions ?? (() => []);
+        this.#unavailable = options.unavailable ?? (() => undefined);
+        this.#unavailableCode = options.unavailableCode ?? (() => undefined);
+        this.#onOwnerCreated = options.onOwnerCreated;
     }
     get ready() {
-        return this.#ready;
+        return this.#ready && this.#unavailable() === undefined;
+    }
+    /** See {@link ConsoleIamServiceOptions.unavailable} (detail: logs and the local owner only). */
+    unavailableReason() {
+        return this.#unavailable();
+    }
+    /** `{ code, message }` safe for any HTTP caller while closed, or undefined. */
+    publicUnavailable() {
+        if (this.#unavailable() === undefined)
+            return undefined;
+        return Object.freeze({ code: this.#unavailableCode() ?? 'unavailable', message: IAM_UNAVAILABLE_PUBLIC_MESSAGE });
     }
     /** Seeds built-in roles and loads the owner state; call after the database started. */
     async start(options = {}) {
@@ -115,6 +133,8 @@ export class ConsoleIamService {
         clearInterval(this.#refreshTimer);
     }
     initialized() {
+        if (this.#unavailable() !== undefined)
+            return true;
         if (this.#initialized === true)
             return true;
         // Database not up yet, or another process (`zhin console init` beside a running gateway)
@@ -156,7 +176,7 @@ export class ConsoleIamService {
     }
     // ------------------------------------------------------------------ authentication
     async authenticate(token, meta = {}) {
-        if (!this.#ready || !token || token.length > 256)
+        if (!this.ready || !token || token.length > 256)
             return null;
         const hash = sha256(token);
         const now = this.#now();
@@ -199,7 +219,7 @@ export class ConsoleIamService {
             action: entry.action.slice(0, 256),
             target: entry.target?.slice(0, 256) ?? null,
             outcome: entry.outcome,
-            detail: entry.detail ? JSON.stringify(entry.detail).slice(0, 4096) : null,
+            detail: entry.detail ? auditDetailJson(entry.detail) : null,
             ip: entry.ip?.slice(0, 64) ?? null,
         }).catch(this.#onError);
     }
@@ -312,7 +332,14 @@ export class ConsoleIamService {
             this.#requireReady();
             if ((await this.#activeOwnerIds()).size > 0)
                 throw new IamError('conflict', '已初始化：所有者已存在');
-            return this.#createUser({ ...input, bindings: [{ role: 'owner', scopeKind: 'global' }] });
+            const owner = await this.#createUser({ ...input, bindings: [{ role: 'owner', scopeKind: 'global' }] });
+            try {
+                this.#onOwnerCreated?.();
+            }
+            catch (error) {
+                this.#onError(error);
+            }
+            return owner;
         });
     }
     /** Issues a session for a user (setup returns one for the new owner). */
@@ -782,3 +809,21 @@ function auditView(row) {
         ip: row.ip === null || row.ip === undefined ? null : String(row.ip),
     });
 }
+/** Longest stored audit `detail` (characters of JSON). */
+export const AUDIT_DETAIL_MAX_LENGTH = 4096;
+/**
+ * Audit detail as JSON that always parses back: a detail longer than the column budget is
+ * replaced by `{ truncated, length, preview }` instead of being cut mid-string.
+ */
+export function auditDetailJson(detail) {
+    const json = JSON.stringify(detail) ?? 'null';
+    if (json.length <= AUDIT_DETAIL_MAX_LENGTH)
+        return json;
+    let keep = AUDIT_DETAIL_MAX_LENGTH - 64;
+    for (;;) {
+        const replacement = JSON.stringify({ truncated: true, length: json.length, preview: json.slice(0, Math.max(0, keep)) });
+        if (replacement.length <= AUDIT_DETAIL_MAX_LENGTH || keep <= 0)
+            return replacement;
+        keep -= replacement.length - AUDIT_DETAIL_MAX_LENGTH;
+    }
+}

package/lib/iam/setup-service.d.ts

@@ -55,6 +55,8 @@ export interface ConsoleSetupServiceOptions {
     readonly driverAvailable?: (dialect: SetupDialect) => Promise<boolean>;
 }
 export declare const SETUP_NO_MIGRATION_NOTICE = "\u5207\u6362\u6570\u636E\u5E93\u4E0D\u4F1A\u8FC1\u79FB\u65E7\u5E93\u6570\u636E\uFF1A\u63D2\u4EF6\u6570\u636E\u4ECD\u7559\u5728\u539F\u6570\u636E\u5E93\u3002";
+/** PostgreSQL / MySQL: raw Console SQL needs the restricted account (ADR 0059 §4). */
+export declare const SETUP_CONSOLE_ROLE_NOTICE = "PostgreSQL / MySQL \u4E0A Console \u7684\u539F\u59CB SQL \u53EA\u7528\u53D7\u9650\u8D26\u53F7\u6267\u884C\uFF1A\u8FD0\u884C zhin db console-role \u521B\u5EFA\uFF08\u65E0\u5EFA\u53F7\u6743\u9650\u65F6\u52A0 --print-sql \u4EA4\u7ED9 DBA\uFF09\u3002";
 /**
  * The one setup flow (ADR 0049 §7): `/auth/setup*` and `zhin console init` are thin wrappers.
  * Database changes are written to the config file / `.env`; restarting is the caller's job.

package/lib/iam/setup-service.js

@@ -3,7 +3,6 @@ import { isDatabaseDriverAvailable, probeDatabaseConnection, } from '@zhin.js/da
 import { expandEnvironmentValue } from '@zhin.js/plugin-runtime';
 import { DATABASE_DIALECT_DEFINITIONS, validateDatabaseConfig, } from '@zhin.js/scaffold-wizard';
 import { IamError } from './service.js';
-import { IAM_DIALECTS } from './tables.js';
 const DEFAULT_SQLITE_FILE = '.zhin/data.sqlite';
 const SECRET_FIELDS = new Set(['password']);
 const ENV_REFERENCE = /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/u;
@@ -34,7 +33,14 @@ function fieldsOf(definition) {
             })];
     }));
 }
-const SETUP_DEFINITIONS = DATABASE_DIALECT_DEFINITIONS.filter(definition => IAM_DIALECTS.has(definition.dialect));
+/**
+ * Dialects the wizard can test a connection for. Console accounts no longer depend on it: they
+ * live in `.zhin/gateway.db` (ADR 0059); a redis / memory project keeps its database block.
+ */
+const SETUP_DIALECTS = new Set(['sqlite', 'mysql', 'pg', 'mongodb']);
+const SETUP_DEFINITIONS = DATABASE_DIALECT_DEFINITIONS.filter(definition => SETUP_DIALECTS.has(definition.dialect));
+/** PostgreSQL / MySQL: raw Console SQL needs the restricted account (ADR 0059 §4). */
+export const SETUP_CONSOLE_ROLE_NOTICE = 'PostgreSQL / MySQL 上 Console 的原始 SQL 只用受限账号执行：运行 zhin db console-role 创建（无建号权限时加 --print-sql 交给 DBA）。';
 /**
  * The one setup flow (ADR 0049 §7): `/auth/setup*` and `zhin console init` are thin wrappers.
  * Database changes are written to the config file / `.env`; restarting is the caller's job.
@@ -96,12 +102,13 @@ export class ConsoleSetupService {
             await this.#options.envFile.write(upsertDotenv(await this.#options.envFile.read(), envUpdates));
         }
         await this.#options.config.setKey('database', block);
-        return Object.freeze({ restartRequired: true, notice: SETUP_NO_MIGRATION_NOTICE });
+        const notice = prepared.dialect === 'pg' || prepared.dialect === 'mysql' ? `${SETUP_NO_MIGRATION_NOTICE}${SETUP_CONSOLE_ROLE_NOTICE}` : SETUP_NO_MIGRATION_NOTICE;
+        return Object.freeze({ restartRequired: true, notice });
     }
     async createOwner(input) {
         const iam = this.#options.iam();
         if (!iam?.ready)
-            throw new IamError('unavailable', '当前数据库不能存储账号，或尚未就绪');
+            throw new IamError('unavailable', iam?.publicUnavailable()?.message ?? 'Console 访问控制尚未就绪');
         if (iam.initialized())
             throw new IamError('conflict', '已初始化：请改用 zhin console user 管理用户');
         return { user: await iam.createOwner(input) };

package/lib/iam/tables.d.ts

@@ -1,4 +1,7 @@
-/** Console access-control tables (ADR 0049 §2). Defined by the composition root before DB start. */
+/**
+ * Console access-control tables (ADR 0049 §2). Since ADR 0059 they live in the gateway's own store
+ * `.zhin/gateway.db` (SQLite), whatever the project database is.
+ */
 export declare const IAM_TABLES: Readonly<{
     readonly users: "console_users";
     readonly roles: "console_roles";
@@ -8,13 +11,10 @@ export declare const IAM_TABLES: Readonly<{
     readonly audit: "console_audit_log";
 }>;
 export declare const IAM_TABLE_DEFINITIONS: Readonly<Record<string, Record<string, unknown>>>;
-/** Dialects that can hold accounts (redis / memory cannot, ADR 0049 §8). */
-export declare const IAM_DIALECTS: ReadonlySet<string>;
 export interface IamTableHost {
-    readonly dialect: string;
     readonly started: boolean;
     define(name: string, definition: Record<string, unknown>): void;
     tables(): readonly string[];
 }
-/** Idempotent; must run before the database starts. Returns false for unsupported dialects. */
-export declare function defineConsoleIamTables(host: IamTableHost): boolean;
+/** Idempotent; must run before the database starts. */
+export declare function defineConsoleIamTables(host: IamTableHost): void;

package/lib/iam/tables.js

@@ -1,4 +1,7 @@
-/** Console access-control tables (ADR 0049 §2). Defined by the composition root before DB start. */
+/**
+ * Console access-control tables (ADR 0049 §2). Since ADR 0059 they live in the gateway's own store
+ * `.zhin/gateway.db` (SQLite), whatever the project database is.
+ */
 export const IAM_TABLES = Object.freeze({
     users: 'console_users',
     roles: 'console_roles',
@@ -65,18 +68,13 @@ export const IAM_TABLE_DEFINITIONS = Object.freeze({
         ip: text(true),
     },
 });
-/** Dialects that can hold accounts (redis / memory cannot, ADR 0049 §8). */
-export const IAM_DIALECTS = new Set(['sqlite', 'mysql', 'pg', 'mongodb']);
-/** Idempotent; must run before the database starts. Returns false for unsupported dialects. */
+/** Idempotent; must run before the database starts. */
 export function defineConsoleIamTables(host) {
-    if (!IAM_DIALECTS.has(host.dialect))
-        return false;
     if (host.started)
-        return true;
+        return;
     const existing = new Set(host.tables());
     for (const [name, definition] of Object.entries(IAM_TABLE_DEFINITIONS)) {
         if (!existing.has(name))
             host.define(name, definition);
     }
-    return true;
 }

package/lib/local/protocol.d.ts

@@ -33,6 +33,12 @@ export declare const LOCAL_GATEWAY_RPC: Readonly<{
     readonly CONSOLE_USER_PASSWD: "gateway.console.user.passwd";
     /** `{ username, disabled }`. */
     readonly CONSOLE_USER_DISABLE: "gateway.console.user.disable";
+    /**
+     * `zhin console migrate` / `zhin doctor` beside a running gateway (ADR 0059 §3): the state of the
+     * import of the old `console_*` tables (`{ record, pending?, reappeared?, problem? }`), read by
+     * the gateway, the only process that opens `.zhin/gateway.db` while it runs.
+     */
+    readonly CONSOLE_MIGRATION_STATUS: "gateway.console.migration.status";
     /**
      * `{base}/…` request on behalf of the local owner ({@link LocalGatewayHttpRequest}): what
      * `zhin config` / `schedule` / `send` / `watch` use while a gateway runs, so they need no

package/lib/local/protocol.js

@@ -39,6 +39,12 @@ export const LOCAL_GATEWAY_RPC = Object.freeze({
     CONSOLE_USER_PASSWD: 'gateway.console.user.passwd',
     /** `{ username, disabled }`. */
     CONSOLE_USER_DISABLE: 'gateway.console.user.disable',
+    /**
+     * `zhin console migrate` / `zhin doctor` beside a running gateway (ADR 0059 §3): the state of the
+     * import of the old `console_*` tables (`{ record, pending?, reappeared?, problem? }`), read by
+     * the gateway, the only process that opens `.zhin/gateway.db` while it runs.
+     */
+    CONSOLE_MIGRATION_STATUS: 'gateway.console.migration.status',
     /**
      * `{base}/…` request on behalf of the local owner ({@link LocalGatewayHttpRequest}): what
      * `zhin config` / `schedule` / `send` / `watch` use while a gateway runs, so they need no

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;