@zhin.js/gateway 1.3.0 → 1.4.0

package/lib/http/gateway-console.js

@@ -86,13 +86,38 @@ export async function startGatewayConsole(options) {
         iam,
         logger: { warn: (message) => logger.warn(message), info: (message) => logger.info(message) },
     });
+    // ADR 0060 §2.4: a deleted / disabled Console user's chat person link is removed by the
+    // instance on `principal-revoked`. Those two reasons are kept while no instance is attached
+    // and sent once one reports ready, so a link never outlives its user because the instance was
+    // down (bounded; in memory only: a gateway restart forgets them).
+    const undelivered = new Map();
     const revoke = (userId, reason) => {
         terminal.terminatePrincipal(`user:${userId}`, 'revoked');
+        const ending = reason === 'deleted' || reason === 'disabled';
+        if (ending && options.instance?.ready === false) {
+            undelivered.delete(userId);
+            undelivered.set(userId, reason);
+            if (undelivered.size > 1024)
+                undelivered.delete(undelivered.keys().next().value);
+        }
         try {
             options.instance?.revokePrincipal?.(userId, reason);
         }
         catch { /* bridge gone */ }
     };
+    const stopUndelivered = options.instance?.onRoutes?.(() => {
+        if (options.instance?.ready !== true)
+            return;
+        for (const [userId, reason] of [...undelivered]) {
+            undelivered.delete(userId);
+            try {
+                options.instance?.revokePrincipal?.(userId, reason);
+            }
+            catch { /* bridge gone */ }
+        }
+    });
+    if (stopUndelivered)
+        disposers.push(stopUndelivered);
     const projectDatabase = async () => options.database
         ?? resolveProjectDatabaseConfig(projectRoot, await loadExpandedProjectConfig(projectRoot, environment));
     async function connect() {

package/lib/http/gateway-http-server.d.ts

@@ -43,6 +43,8 @@ export interface GatewayHttpServerOptions {
      * RPC type on that route is forwarded to the instance unchanged.
      */
     readonly consoleRpc?: GatewayConsoleRpc;
+    /** Reported on `/pub/health` as `project.id` (`projectIdentity(projectRoot)`). */
+    readonly projectId?: string;
 }
 /** One router, many listeners: every listener serves the same surface. */
 export declare class GatewayHttpServer {

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

@@ -58,6 +58,7 @@ export class GatewayHttpServer {
     #consoleRpc;
     /** The instance connection (and route table) that has no capability route: asked once. */
     #capabilitiesMissing;
+    #projectId;
     #rpcHandlers = new Set();
     #closed = false;
     #closeResult;
@@ -68,6 +69,7 @@ export class GatewayHttpServer {
         this.#retryAfter = String(Math.max(1, Math.round(options.retryAfterSeconds ?? DEFAULT_GATEWAY_RETRY_AFTER_SECONDS)));
         this.#maxBody = options.maxRequestBodyBytes ?? DEFAULT_GATEWAY_MAX_REQUEST_BODY_BYTES;
         this.#consoleRpc = options.consoleRpc;
+        this.#projectId = options.projectId;
         this.tokenRegistry = options.tokenRegistry ?? new TokenRegistry({ primaryToken: primary.token });
         this.apiBase = normalizePath(primary.apiBase ?? '/api');
         const routerOptions = {
@@ -185,6 +187,7 @@ export class GatewayHttpServer {
             status: 'ok',
             timestamp: new Date().toISOString(),
             instance: { state: this.#instance.state(), ready: this.#readyTransport() !== undefined },
+            ...(this.#projectId ? { project: { id: this.#projectId } } : {}),
         };
         // Polled by the Console's instance banner: never cached.
         return jsonResponse(200, body, { 'cache-control': 'no-store' });

package/lib/http/local-principal.d.ts

@@ -1,2 +1,2 @@
-import type { ConsoleUserPrincipal } from '@zhin.js/host-http';
+import { type ConsoleUserPrincipal } from '@zhin.js/host-http';
 export declare const LOCAL_OWNER_PRINCIPAL: ConsoleUserPrincipal;

package/lib/http/local-principal.js

@@ -5,12 +5,13 @@
  * entries name it `user:local`.
  */
 import { CONSOLE_PERMISSION_LIST } from '@zhin.js/console-protocol';
+import { LOCAL_SOCKET_CREDENTIAL_ID, LOCAL_SOCKET_USER_ID } from '@zhin.js/host-http';
 export const LOCAL_OWNER_PRINCIPAL = Object.freeze({
     kind: 'user',
-    userId: 'local',
+    userId: LOCAL_SOCKET_USER_ID,
     username: 'local',
     displayName: '本机 CLI（网关控制套接字）',
-    credentialId: 'local-socket',
+    credentialId: LOCAL_SOCKET_CREDENTIAL_ID,
     grants: Object.freeze([Object.freeze({ role: 'owner', scope: Object.freeze({ kind: 'global' }), permissions: CONSOLE_PERMISSION_LIST })]),
     roles: Object.freeze(['owner']),
 });

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

@@ -177,7 +177,7 @@ async function runSwitch(plugin, enabled, principal, options, type) {
         return { result };
     const action = enabled ? '启用' : '停用';
     const text = result.status === 'rollbackFailed'
-        ? `${action} ${plugin} 失败，且回滚未完成：${result.rollbackError ?? '未知错误'}（原因：${result.error ?? '未知错误'}）`
+        ? `${action} ${plugin} 失败，且回滚未完成：${[result.rollbackError, result.restartError ? `重新启动实例失败：${result.restartError}` : undefined].filter(Boolean).join('；') || '未知错误'}（原因：${result.error ?? '未知错误'}）`
         : `${action} ${plugin} 失败，已回滚：${result.error ?? '未知错误'}`;
     return {
         reply: error(500, result.status === 'rollbackFailed' ? 'rollback_failed' : 'transaction_failed', text, type, {

package/lib/http/start-gateway.d.ts

@@ -14,7 +14,7 @@ import { GatewayHttpServer } from './gateway-http-server.js';
  * optional {@link GatewayConsoleInstancePort} methods (plugin catalog, instance audit,
  * `principal-revoked`) when the transport has them (`IpcInstanceTransport` does).
  */
-export interface GatewayInstanceTransport extends InstanceTransport, GatewayConsoleInstancePort {
+export interface GatewayInstanceTransport extends InstanceTransport, Omit<GatewayConsoleInstancePort, 'ready' | 'onRoutes'> {
     dispose?(): void | Promise<void>;
     /** Told the bound listener addresses after listen (the instance's `HttpHost.address`). */
     setAddresses?(addresses: readonly import('@zhin.js/host-http').HttpHostAddress[]): void;

package/lib/http/start-gateway.js

@@ -7,6 +7,7 @@ import { join } from 'node:path';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { createConfigDocument } from '@zhin.js/runtime';
 import { findConfigFile } from '../project/config-file.js';
+import { projectIdentity } from '../project/identity.js';
 import { loadRuntimeEnvironmentLayers } from '../project/environment.js';
 import { InstanceSupervisor } from '../supervisor/instance-supervisor.js';
 import { GatewayPackageService } from '../packages/service.js';
@@ -113,6 +114,7 @@ export async function startGateway(options) {
         ...(options.retryAfterSeconds !== undefined ? { retryAfterSeconds: options.retryAfterSeconds } : {}),
         ...(options.maxRequestBodyBytes !== undefined ? { maxRequestBodyBytes: options.maxRequestBodyBytes } : {}),
         consoleRpc: createGatewayConsoleRpc(rpc),
+        projectId: projectIdentity(options.projectRoot),
     });
     registry = server.tokenRegistry;
     // The Console's global plugin switch is a gateway transaction (stop → write → start, rollback);

package/lib/iam/service.js

@@ -460,9 +460,18 @@ export class ConsoleIamService {
                 row.permissions = JSON.stringify(permissionList(patch.permissions));
             if (Object.keys(row).length)
                 await this.#model('roles').update(row).where({ id });
+            // Grants of every holder may have shrunk: their long-lived connections and anything the
+            // instance derived from their grants (open chat bind codes) re-authorize from scratch.
+            if (patch.permissions !== undefined)
+                for (const userId of await this.#usersBoundTo(id))
+                    this.#emitRevocation(userId, 'bindings');
             return withPluginPermissions((await this.#role(id)), this.pluginPermissionCatalog());
         });
     }
+    async #usersBoundTo(roleId) {
+        const rows = await this.#model('bindings').select('user_id').where({ role_id: roleId });
+        return [...new Set(rows.map(row => String(row.user_id)))];
+    }
     deleteRole(id) {
         return this.#serialize(async () => {
             const role = await this.#role(id);
@@ -470,8 +479,11 @@ export class ConsoleIamService {
                 throw new IamError('not_found', '角色不存在');
             if (role.builtin)
                 throw new IamError('forbidden', '内置角色不可删除');
+            const holders = await this.#usersBoundTo(id);
             await this.#model('bindings').delete().where({ role_id: id });
             await this.#model('roles').delete().where({ id });
+            for (const userId of holders)
+                this.#emitRevocation(userId, 'bindings');
         });
     }
     /** Replaces all bindings of a user. */

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

@@ -37,7 +37,9 @@ export interface SetupDatabaseInput {
 /** Config-file and dotenv access the setup flow needs (ConsoleConfigurationStore satisfies `config`). */
 export interface SetupConfigPort {
     readDocument(): Promise<Record<string, unknown>>;
-    setKey(key: string, value: unknown): Promise<unknown>;
+    setKey(key: string, value: unknown, options?: {
+        readonly environmentWrite?: boolean;
+    }): Promise<unknown>;
 }
 export interface SetupEnvFilePort {
     read(): Promise<string>;

package/lib/iam/setup-service.js

@@ -101,7 +101,8 @@ export class ConsoleSetupService {
         if (Object.keys(envUpdates).length) {
             await this.#options.envFile.write(upsertDotenv(await this.#options.envFile.read(), envUpdates));
         }
-        await this.#options.config.setKey('database', block);
+        // The setup flow writes `.env` itself (bootstrap / owner): secret literals may go there too.
+        await this.#options.config.setKey('database', block, { environmentWrite: true });
         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 });
     }

package/lib/onboarding/ignored-builds.d.ts

@@ -0,0 +1,18 @@
+export declare 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 declare const IGNORED_BUILDS_OUTPUT_LIMIT: number;
+/**
+ * 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 declare function parseIgnoredBuilds(output: string): readonly string[] | undefined;
+/** Package names named by an `add` invocation (`add [-w] [-D] <spec>…`); empty for other commands. */
+export declare function addedPackageNames(args: readonly string[]): readonly string[];
+/**
+ * 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 declare function dependenciesInPlace(projectRoot: string, args: readonly string[]): Promise<boolean>;
+/** The hint printed for ignored builds: same allowance the scaffold writes for native packages. */
+export declare function ignoredBuildsHint(names: readonly string[]): string;

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/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. */
@@ -298,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 {
@@ -335,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,
@@ -355,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 } : {}),

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/workflow.d.ts

@@ -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 {

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).
@@ -451,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 = {}) {
@@ -625,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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/gateway",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Zhin.js management gateway: Console access control, terminal, project configuration and instance supervision (ADR 0054)",
   "type": "module",
   "main": "./lib/index.js",
@@ -72,13 +72,13 @@
     "fs-extra": "^11.4.0",
     "tsx": "^4.23.1",
     "yaml": "^2.9.0",
-    "@zhin.js/console-protocol": "1.3.0",
-    "@zhin.js/database": "1.2.0",
-    "@zhin.js/host-http": "1.3.0",
-    "@zhin.js/logger": "1.1.3",
+    "@zhin.js/console-protocol": "1.4.0",
+    "@zhin.js/database": "1.2.1",
+    "@zhin.js/host-http": "1.4.0",
+    "@zhin.js/logger": "1.2.0",
     "@zhin.js/plugin-runtime": "1.3.0",
-    "@zhin.js/runtime": "1.3.0",
-    "@zhin.js/scaffold-wizard": "1.2.0"
+    "@zhin.js/runtime": "1.4.0",
+    "@zhin.js/scaffold-wizard": "1.3.0"
   },
   "optionalDependencies": {
     "node-pty": "^1.0.0",