@zhin.js/gateway 1.2.0 → 1.4.0

package/lib/onboarding/ignored-builds.js

@@ -0,0 +1,63 @@
+/**
+ * pnpm 10+ skips dependency build scripts that the project did not allow; pnpm 11 (and pnpm 10
+ * with `strictDepBuilds`) then exits 1 with `ERR_PNPM_IGNORED_BUILDS` although every dependency
+ * was resolved, fetched and linked. That exit is not a failed install: the packages are in place,
+ * only their build scripts did not run (#1250). These helpers tell the two apart.
+ */
+import { access } from 'node:fs/promises';
+import { join } from 'node:path';
+export const PNPM_IGNORED_BUILDS_CODE = 'ERR_PNPM_IGNORED_BUILDS';
+/** Cap on the package-manager output kept to recognise the error (its summary comes last). */
+export const IGNORED_BUILDS_OUTPUT_LIMIT = 64 * 1024;
+/**
+ * The packages pnpm reports in `Ignored build scripts: a@1.0.0, @scope/b@2.0.0.`; `undefined` when
+ * the output does not carry `ERR_PNPM_IGNORED_BUILDS` (an empty list when the list is unreadable).
+ */
+export function parseIgnoredBuilds(output) {
+    if (!output.includes(PNPM_IGNORED_BUILDS_CODE))
+        return undefined;
+    const names = new Set();
+    for (const match of output.matchAll(/Ignored build scripts:\s*([^\n]*)/gu)) {
+        for (const raw of match[1].split(',')) {
+            const item = raw.replace(/[│|]/gu, '').trim().replace(/\.$/u, '').trim();
+            const at = item.lastIndexOf('@');
+            const name = at > 0 ? item.slice(0, at) : item;
+            if (/^(?:@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*$/iu.test(name))
+                names.add(name);
+        }
+    }
+    return Object.freeze([...names]);
+}
+/** Package names named by an `add` invocation (`add [-w] [-D] <spec>…`); empty for other commands. */
+export function addedPackageNames(args) {
+    if (args[0] !== 'add')
+        return [];
+    return args.slice(1).filter(arg => !arg.startsWith('-')).map((spec) => {
+        const bare = spec.replace(/^npm:/u, '');
+        const at = bare.indexOf('@', 1);
+        return at > 0 ? bare.slice(0, at) : bare;
+    });
+}
+const exists = (path) => access(path).then(() => true, () => false);
+/**
+ * Whether the dependencies of `args` are in place after pnpm reported ignored builds: pnpm wrote
+ * `node_modules/.modules.yaml` (it does so after linking) and every package an `add` named is in
+ * `node_modules`. Only then is the exit treated as a warning.
+ */
+export async function dependenciesInPlace(projectRoot, args) {
+    if (!await exists(join(projectRoot, 'node_modules', '.modules.yaml')))
+        return false;
+    for (const name of addedPackageNames(args)) {
+        if (!await exists(join(projectRoot, 'node_modules', ...name.split('/'), 'package.json')))
+            return false;
+    }
+    return true;
+}
+/** The hint printed for ignored builds: same allowance the scaffold writes for native packages. */
+export function ignoredBuildsHint(names) {
+    const list = names.length ? names.join('、') : '部分依赖';
+    const example = names[0] ?? '<包名>';
+    return `pnpm 跳过了 ${list} 的构建脚本（${PNPM_IGNORED_BUILDS_CODE}），依赖本身已安装。`
+        + `如需运行它们的构建脚本：在 pnpm-workspace.yaml 写 allowBuilds:\n  ${example}: true\n`
+        + `（pnpm < 10.26 改为 onlyBuiltDependencies 列表），再运行 pnpm rebuild ${names.join(' ') || example}；不需要构建产物的包可以不处理。`;
+}

package/lib/onboarding/index.d.ts

@@ -2,5 +2,6 @@ export * from './errors.js';
 export * from './allowlist.js';
 export * from './state-store.js';
 export * from './package-manager.js';
+export * from './ignored-builds.js';
 export * from './install.js';
 export * from './service.js';

package/lib/onboarding/index.js

@@ -2,5 +2,6 @@ export * from './errors.js';
 export * from './allowlist.js';
 export * from './state-store.js';
 export * from './package-manager.js';
+export * from './ignored-builds.js';
 export * from './install.js';
 export * from './service.js';

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

@@ -10,6 +10,7 @@ import { CONSOLE_PERMISSIONS } from '@zhin.js/console-protocol';
 import { createInstallAllowlist } from '../onboarding/allowlist.js';
 import { InstallOutputRelay, streamEvents } from '../onboarding/install.js';
 import { createStreamingPackageManager, detectPackageManager } from '../onboarding/package-manager.js';
+import { dependenciesInPlace, IGNORED_BUILDS_OUTPUT_LIMIT, parseIgnoredBuilds } from '../onboarding/ignored-builds.js';
 import { PluginDeclarationError, PluginEnablementError, PluginManagementOperationError, PluginManagementWorkflow } from '../plugin-management/workflow.js';
 import { InstanceStartError } from '../supervisor/instance-supervisor.js';
 import { authorizePackages, gatewayPrincipalAllows } from './authorization.js';
@@ -39,16 +40,46 @@ export class GatewayPackageService {
     #packageManager;
     #workflow;
     #active;
+    /** Packages whose build scripts pnpm skipped during the running transaction (#1250). */
+    #ignoredBuilds;
     constructor(options) {
         this.#root = resolve(options.projectRoot);
         this.#options = options;
         const streaming = createStreamingPackageManager(this.#relay.output);
-        this.#packageManager = options.packageManager ?? ((args, root) => streaming(args, root));
+        this.#packageManager = this.#tolerateIgnoredBuilds(options.packageManager ?? ((args, root) => streaming(args, root)));
         this.#workflow = options.workflow ?? new PluginManagementWorkflow(this.#root, {
             ...options.workflowOptions,
             installDependencies: (args, root) => this.#packageManager(args, root, this.#relay.output),
         });
     }
+    /**
+     * pnpm 11 exits 1 with `ERR_PNPM_IGNORED_BUILDS` after a complete install whose dependency build
+     * scripts were not allowed. With the dependencies in place that exit is recorded (reported as
+     * `ignoredBuilds` with an allowBuilds hint) instead of failing — and rolling back — the transaction.
+     */
+    #tolerateIgnoredBuilds(manager) {
+        return async (args, root, output) => {
+            let captured = '';
+            const tee = (stream, chunk) => {
+                captured = (captured + chunk).slice(-IGNORED_BUILDS_OUTPUT_LIMIT);
+                output(stream, chunk);
+            };
+            try {
+                await manager(args, root, tee);
+            }
+            catch (error) {
+                const detail = error && typeof error === 'object'
+                    ? ['message', 'stdout', 'stderr'].map(key => Reflect.get(error, key)).filter((value) => typeof value === 'string').join('\n')
+                    : String(error);
+                const ignored = parseIgnoredBuilds(`${captured}\n${detail}`);
+                if (!ignored || !await dependenciesInPlace(root, args))
+                    throw error;
+                this.#ignoredBuilds ??= new Set();
+                for (const name of ignored)
+                    this.#ignoredBuilds.add(name);
+            }
+        };
+    }
     /** Id of the running transaction, if any. */
     get activeTransaction() { return this.#active; }
     /** Progress of every transaction (for `gateway.packages.progress`); returns an unsubscribe function. */
@@ -90,7 +121,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));
@@ -293,7 +329,9 @@ export class GatewayPackageService {
         let failedPhase;
         let failure;
         let rollbackFailure;
+        let restartFailure;
         let logTail;
+        this.#ignoredBuilds = undefined;
         emit({ type: 'start', id, operation, packages: authorized });
         try {
             try {
@@ -330,17 +368,29 @@ export class GatewayPackageService {
                             await run(snapshot.hasLockfile ? ['install', '--frozen-lockfile'] : ['install']);
                         }
                     }
-                    if (wasRunning) {
-                        enter('restart-instance');
-                        await this.#startInstance(instance, logMark);
-                    }
                 }
                 catch (error) {
                     status = 'rollbackFailed';
                     rollbackFailure = error;
                 }
+                // A running instance is brought back even when restoring the files or dependencies failed
+                // (#1250): leaving the bot stopped is worse than starting it on what is on disk. A failed
+                // start is reported on its own.
+                if (wasRunning) {
+                    enter('restart-instance');
+                    try {
+                        await this.#startInstance(instance, logMark);
+                    }
+                    catch (error) {
+                        status = 'rollbackFailed';
+                        restartFailure = error;
+                        if (error instanceof InstanceStartFailure && !logTail?.length)
+                            logTail = error.logTail;
+                    }
+                }
             }
             enter('done');
+            const ignoredBuilds = this.#ignoredBuilds ? Object.freeze([...this.#ignoredBuilds]) : undefined;
             const result = Object.freeze({
                 id,
                 operation,
@@ -350,6 +400,8 @@ export class GatewayPackageService {
                 ...(failedPhase ? { failedPhase } : {}),
                 ...(failure === undefined ? {} : { error: failureMessage(failure), ...declarationDetails(failure) }),
                 ...(rollbackFailure === undefined ? {} : { rollbackError: failureMessage(rollbackFailure) }),
+                ...(restartFailure === undefined ? {} : { restartError: failureMessage(restartFailure) }),
+                ...(ignoredBuilds ? { ignoredBuilds } : {}),
                 ...(logTail?.length ? { logTail } : {}),
                 ...(status === 'succeeded' && extras?.needsConfiguration?.length ? { needsConfiguration: extras.needsConfiguration } : {}),
                 ...(status === 'succeeded' && extras?.plugin ? { plugin: extras.plugin } : {}),
@@ -416,13 +468,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 +560,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/plugin-candidates.d.ts

@@ -0,0 +1,9 @@
+/** The offline official catalog: catalog adapters, use-case plugins and Market entries. */
+export declare function officialPluginCatalog(): readonly string[];
+/**
+ * Official package names matching `request` (same name once the `@zhin.js/` scope and the
+ * `plugin-` / `adapter-` / `service-` / `game-` prefix are dropped). Empty when nothing matches.
+ */
+export declare function officialPluginCandidates(request: string, projectRoot?: string): Promise<readonly string[]>;
+/** The message for an instance that is not declared: install hints only for official candidates. */
+export declare function undeclaredPluginMessage(request: string, candidates: readonly string[]): string;

package/lib/plugin-management/plugin-candidates.js

@@ -0,0 +1,55 @@
+/**
+ * Official packages a user probably meant by a short or misspelled plugin name (#1250). `zhin enable
+ * reminder` must never suggest `zhin install reminder`: that is an unrelated third-party package on
+ * npm. Suggestions only come from the official catalog and the project's installed `@zhin.js/*`
+ * packages — never from the request itself.
+ */
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createInstallAllowlist } from '../onboarding/allowlist.js';
+import { pluginUseCases } from './use-cases.js';
+const OFFICIAL_SCOPE = '@zhin.js/';
+const KIND_PREFIXES = ['plugin-', 'adapter-', 'service-', 'game-'];
+/** `@zhin.js/plugin-reminder`, `plugin-reminder` and `reminder` all reduce to `reminder`. */
+function baseName(name) {
+    let base = name.trim().toLowerCase();
+    if (base.startsWith(OFFICIAL_SCOPE))
+        base = base.slice(OFFICIAL_SCOPE.length);
+    for (const prefix of KIND_PREFIXES)
+        if (base.startsWith(prefix))
+            return base.slice(prefix.length);
+    return base;
+}
+/** The offline official catalog: catalog adapters, use-case plugins and Market entries. */
+export function officialPluginCatalog() {
+    const names = new Set();
+    for (const entry of createInstallAllowlist().entries()) {
+        if (entry.kind === 'adapter' && entry.name.startsWith(OFFICIAL_SCOPE))
+            names.add(entry.name);
+    }
+    for (const useCase of pluginUseCases)
+        names.add(useCase.packageName);
+    return Object.freeze([...names].sort());
+}
+async function installedOfficialPackages(projectRoot) {
+    const entries = await readdir(join(projectRoot, 'node_modules', '@zhin.js')).catch(() => []);
+    return entries.filter(name => !name.startsWith('.')).map(name => `${OFFICIAL_SCOPE}${name}`);
+}
+/**
+ * Official package names matching `request` (same name once the `@zhin.js/` scope and the
+ * `plugin-` / `adapter-` / `service-` / `game-` prefix are dropped). Empty when nothing matches.
+ */
+export async function officialPluginCandidates(request, projectRoot) {
+    const wanted = baseName(request);
+    if (!wanted)
+        return [];
+    const pool = new Set([...officialPluginCatalog(), ...(projectRoot ? await installedOfficialPackages(projectRoot) : [])]);
+    return Object.freeze([...pool].filter(name => baseName(name) === wanted).sort());
+}
+/** The message for an instance that is not declared: install hints only for official candidates. */
+export function undeclaredPluginMessage(request, candidates) {
+    const head = `找不到插件实例 ${request}（配置中没有声明）`;
+    if (!candidates.length)
+        return head;
+    return `${head}。官方插件中名称相近的有：${candidates.join('、')}；如果要用它，运行 ${candidates.map(name => `zhin install ${name}`).join(' 或 ')}`;
+}

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 {
@@ -8,6 +8,11 @@ export interface PluginManagementOptions {
     readonly requestRestart?: () => void | Promise<void>;
     /** Real package-manager boundary; tests use independent on-disk packages. */
     readonly installDependencies?: (args: readonly string[], projectRoot: string) => Promise<void>;
+    /**
+     * Default package-manager boundary only: pnpm exited with `ERR_PNPM_IGNORED_BUILDS` but the
+     * dependencies are in place. Without this callback that exit still fails the operation.
+     */
+    readonly onIgnoredBuilds?: (packages: readonly string[]) => void;
     readonly lifecycleFile?: string;
 }
 export interface PluginInstallOptions {
@@ -67,7 +72,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

@@ -9,6 +9,8 @@ import { featureId, pluginVerificationToken, rootPluginId, readPluginConfigurati
 import { ConsoleConfigurationStore } from '../config/configuration.js';
 import { explainConfigFields } from './config-explanation.js';
 import { resolveCommand } from '../onboarding/package-manager.js';
+import { dependenciesInPlace, parseIgnoredBuilds } from '../onboarding/ignored-builds.js';
+import { officialPluginCandidates, undeclaredPluginMessage } from './plugin-candidates.js';
 import { inferConventionFeatureReferences, readPluginLifecycleState, resolvePluginLifecycleFile } from '@zhin.js/runtime';
 const execute = promisify(execFile);
 // Narrow local view of the `@zhin.js/adapter` index projection: the gateway must not import IM layers (ADR 0054 §0).
@@ -209,16 +211,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 +254,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);
         }
@@ -433,8 +453,20 @@ export class PluginManagementWorkflow {
         else {
             // No shell: on Windows `pnpm.cmd` is resolved and run through `cmd.exe /d /s /c` with quoted arguments.
             const resolved = resolveCommand('pnpm', invocation);
-            await execute(resolved.command, [...resolved.args], { cwd: this.#root, maxBuffer: 10 * 1024 * 1024, windowsHide: true,
-                ...(resolved.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}) });
+            try {
+                await execute(resolved.command, [...resolved.args], { cwd: this.#root, maxBuffer: 10 * 1024 * 1024, windowsHide: true,
+                    ...(resolved.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}) });
+            }
+            catch (error) {
+                // pnpm 11: builds the project did not allow are skipped and pnpm exits 1 after a complete install (#1250).
+                const report = this.#options.onIgnoredBuilds;
+                const output = ['stdout', 'stderr'].map(key => (error && typeof error === 'object' ? Reflect.get(error, key) : undefined))
+                    .filter((value) => typeof value === 'string').join('\n');
+                const ignored = parseIgnoredBuilds(output);
+                if (!report || !ignored || !await dependenciesInPlace(this.#root, invocation))
+                    throw error;
+                report(ignored);
+            }
         }
     }
     async install(request, expectedRevision, expectedProjectRevision, options = {}) {
@@ -607,8 +639,9 @@ export class PluginManagementWorkflow {
         catch (error) {
             throw new PluginEnablementError('invalid-request', errorMessage(error), [], []);
         }
+        // The fallback target is derived from the request itself: never suggest installing it (#1250).
         if (!declared)
-            throw new PluginEnablementError('not-declared', `插件实例 ${target.instanceKey}（${target.packageName}）未在配置中声明；先运行 zhin install ${target.packageName}`);
+            throw new PluginEnablementError('not-declared', undeclaredPluginMessage(key, await officialPluginCandidates(key, this.#root)));
         const state = await this.inspect(target.instanceKey);
         if (enabled && (!state.installed || !state.plugin)) {
             throw new PluginEnablementError('not-installed', `${state.packageName} ${state.installed ? `不是可加载的 Plugin 包${state.issues[0] ? `：${state.issues[0]}` : ''}` : '未安装'}；先运行 zhin install ${state.packageName}`);

package/lib/plugin-management.d.ts

@@ -3,3 +3,4 @@ export * from './plugin-management/activity.js';
 export * from './plugin-management/config-explanation.js';
 export * from './plugin-management/use-cases.js';
 export * from './plugin-management/workflow.js';
+export * from './plugin-management/plugin-candidates.js';

package/lib/plugin-management.js

@@ -3,3 +3,4 @@ export * from './plugin-management/activity.js';
 export * from './plugin-management/config-explanation.js';
 export * from './plugin-management/use-cases.js';
 export * from './plugin-management/workflow.js';
+export * from './plugin-management/plugin-candidates.js';

package/lib/project/identity.d.ts

@@ -0,0 +1,2 @@
+/** 32 hex characters of SHA-256 over the canonical project root path. */
+export declare function projectIdentity(projectRoot: string): string;

package/lib/project/identity.js

@@ -0,0 +1,21 @@
+/**
+ * A stable, non-reversible identifier of a project checkout (#1250). The gateway reports it on
+ * `GET /pub/health`; the CLI compares it with the project it runs in before it sends a request —
+ * and a Console token — to a gateway on this machine, so a command run in project B never lands
+ * on project A's gateway that happens to listen on the same port.
+ */
+import { createHash } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+/** 32 hex characters of SHA-256 over the canonical project root path. */
+export function projectIdentity(projectRoot) {
+    let root = resolve(projectRoot);
+    try {
+        root = realpathSync.native(root);
+    }
+    catch { /* keep the resolved path */ }
+    // Windows paths are case-insensitive.
+    if (process.platform === 'win32')
+        root = root.toLowerCase();
+    return createHash('sha256').update(`zhin-project:${root}`).digest('hex').slice(0, 32);
+}

package/lib/project.d.ts

@@ -5,3 +5,4 @@ export * from './project/instance-declarations.js';
 export * from './project/legacy-config.js';
 export * from './project/node-requirements.js';
 export * from './project/tsx-module-loader.js';
+export * from './project/identity.js';

package/lib/project.js

@@ -5,3 +5,4 @@ export * from './project/instance-declarations.js';
 export * from './project/legacy-config.js';
 export * from './project/node-requirements.js';
 export * from './project/tsx-module-loader.js';
+export * from './project/identity.js';