@zhin.js/host-http 1.1.2 → 1.1.4

package/README.md

@@ -12,6 +12,10 @@ only the `HttpHost` routing port: they may register HTTP/WS routes but cannot li
 shared server. Registrations are bound to generation admission, so candidate routes stay invisible
 until snapshot commit and retired routes stop matching immediately while their leases drain.
 
+`ProcessHttpHost.close()` is terminal and idempotent. It waits for a pending
+`listen()` operation to settle and releases its TCP listener. Concurrent `listen()`
+calls share one operation; calling `listen()` after close rejects.
+
 ## Capabilities (this slice)
 
 - Path-scoped WebSocket upgrades (`ws(path)`)
@@ -59,3 +63,10 @@ Extended Console RPC uses `src/console-rpc-extended/index.ts` as its module boun
 only maps protocol method names to schedule, inbox, login, Endpoint-management, and Workroom control
 handlers. Shared request parsing and generation-leased Endpoint execution live behind internal helper
 ports, so adding one RPC domain does not enlarge the central dispatcher or couple unrelated domains.
+
+Console project-file operations resolve the project root and existing filesystem targets before
+access. Internal symlinks remain usable only when their resolved target is inside an allowed project
+path; links outside the root, blocked path segments, and dangling links are denied. New files are
+checked through their nearest existing parent and checked again after parent creation. File-tree
+and environment-file inventory use the same boundary. This covers existing symlink layouts; it does
+not provide an OS sandbox against a local process concurrently replacing directories during access.

package/lib/console-rest-pages.js

@@ -54,28 +54,58 @@ function registerLogsRoutes(route, base, ctx) {
     };
     const unavailableNote = 'SystemLog 模型不可用（Database 未启动或未注册 DatabaseLogTransport）';
     route('GET', `${base}/logs`, async (_request, response, url) => {
-        const limit = Math.min(Math.max(parseInt(url.searchParams.get('limit') ?? '100', 10) || 100, 1), 1000);
-        const level = url.searchParams.get('level') ?? undefined;
+        const pageSize = clampPositiveInt(parsePositiveInt(url.searchParams.get('pageSize') ?? url.searchParams.get('limit'), 100), 100, 1000);
+        const requestedPage = clampPositiveInt(parsePositiveInt(url.searchParams.get('page'), 1), 1, Number.MAX_SAFE_INTEGER);
+        const level = url.searchParams.get('level');
+        const source = url.searchParams.get('source')?.trim();
+        const query = url.searchParams.get('q')?.trim();
+        const baseWhere = {
+            ...(level && level !== 'all' ? { level } : {}),
+        };
+        const where = { ...baseWhere, ...(source ? { source } : {}) };
         const LogModel = getModel();
         if (!LogModel) {
-            writeJson(response, 200, { success: true, data: [], total: 0, note: unavailableNote });
+            writeJson(response, 200, { success: true, data: [], total: 0, page: 1, pageSize, totalPages: 1, sources: [], note: unavailableNote });
             return;
         }
-        let selection = LogModel.select();
-        if (level && level !== 'all') {
-            selection = selection.where({ level });
+        // Database $like has no portable ESCAPE contract. Keep q literal (including
+        // %/_ and Unicode) and filter actual retained rows on the Host, not wildcard SQL.
+        const matchesQuery = (row) => !query || ['message', 'name', 'source']
+            .some(field => String(row[field] ?? '').toLowerCase().includes(query.toLowerCase()));
+        const selection = LogModel.select().where(where).orderBy('timestamp', 'DESC').orderBy('id', 'DESC');
+        const queriedRows = query ? (await selection).filter(matchesQuery) : undefined;
+        const total = queriedRows?.length ?? (typeof LogModel.count === 'function'
+            ? await LogModel.count(where)
+            : (await LogModel.select('id').where(where)).length);
+        const totalPages = Math.max(1, Math.ceil(total / pageSize));
+        const page = Math.min(requestedPage, totalPages);
+        const offset = (page - 1) * pageSize;
+        const logs = queriedRows
+            ? queriedRows.slice(offset, offset + pageSize)
+            : selection.offset
+                ? await selection.offset(offset).limit(pageSize)
+                : (await selection).slice(offset, offset + pageSize);
+        // Source counts match level/q, but exclude the selected source and page window.
+        const sourceRows = await LogModel.select('source', 'name', 'message').where(baseWhere);
+        const counts = new Map();
+        for (const row of sourceRows) {
+            const name = row.source;
+            if (!name || !matchesQuery(row))
+                continue;
+            counts.set(name, (counts.get(name) ?? 0) + 1);
         }
-        const logs = await selection.orderBy('timestamp', 'DESC').limit(limit);
         writeJson(response, 200, {
             success: true,
             data: logs.map((log) => ({
+                id: log.id,
                 level: log.level,
                 name: log.name,
                 message: log.message,
                 source: log.source,
                 timestamp: log.timestamp instanceof Date ? log.timestamp.toISOString() : log.timestamp,
             })),
-            total: logs.length,
+            total, page, pageSize, totalPages,
+            sources: [...counts].sort(([a], [b]) => a.localeCompare(b)).map(([source, count]) => ({ source, count })),
         });
     }, { summary: 'List system logs', tags: ['console', 'logs'] });
     route('DELETE', `${base}/logs`, async (_request, response, _url, authScope) => {
@@ -195,8 +225,8 @@ function registerMarketplaceRoutes(route, base, ctx, fetchFn, pluginRegistryUrl,
                 version: p.version || '',
                 description: p.description || '',
                 author: p.author || '',
-                isOfficial: !!p.isOfficial,
-                official: !!p.isOfficial,
+                isOfficial: typeof p.name === 'string' && /^@zhin\.js\/[a-z0-9][a-z0-9._-]*$/.test(p.name),
+                official: typeof p.name === 'string' && /^@zhin\.js\/[a-z0-9][a-z0-9._-]*$/.test(p.name),
                 category: p.category || 'util',
                 keywords: p.tags || [],
                 npm: p.npm || `https://www.npmjs.com/package/${p.name}`,

package/lib/console-rpc-extended/dispatcher.js

@@ -1,5 +1,5 @@
 import { assertDemoConsoleRpcAllowed } from '@zhin.js/console-protocol';
-import { addCron, listSchedule, mutateCron } from './schedule-rpc.js';
+import { addCron, listSchedule, mutateCron, validateCron } from './schedule-rpc.js';
 import { actOnRequest, listInbox, listInboxMessages, listPendingRequests, listRecentInboxMessages, mapNoticeRow, mapRequestRow, markInboxConsumed, TABLE_NOTICE, TABLE_REQUEST, } from './inbox-rpc.js';
 import { cancelLogin, listLoginPending, submitLogin } from './login-rpc.js';
 import { deleteFriend, groupWriteOp, listChannels, listFriends, listGroupMembers, listGroups, } from './endpoint-rpc.js';
@@ -15,6 +15,8 @@ export async function dispatchExtendedConsoleRpc(type, data, ctx) {
         case 'schedule:list':
         case 'cron:list':
             return listSchedule(ctx);
+        case 'cron:validate':
+            return validateCron(d);
         case 'cron:add':
             return addCron(d, ctx);
         case 'cron:remove':

package/lib/console-rpc-extended/schedule-rpc.d.ts

@@ -3,4 +3,6 @@ export declare function listSchedule(ctx: ConsoleScheduleListCtx): Promise<Exten
 type ConsoleScheduleListCtx = ConsoleRpcExtendedCtx;
 export declare function addCron(d: Record<string, unknown>, ctx: ConsoleRpcExtendedCtx): Promise<ExtendedRpcResult>;
 export declare function mutateCron(type: 'cron:remove' | 'cron:pause' | 'cron:resume', d: Record<string, unknown>, ctx: ConsoleRpcExtendedCtx): Promise<ExtendedRpcResult>;
+/** Uses the same parser as the persistent schedule engine; never creates a job. */
+export declare function validateCron(d: Record<string, unknown>): ExtendedRpcResult;
 export {};

package/lib/console-rpc-extended/schedule-rpc.js

@@ -1,3 +1,4 @@
+import { parseCron } from '@zhin.js/schedule';
 import { errorMessage } from './rpc-values.js';
 const CRON_NOT_WIRED = '持久化调度未接线：当前 Plugin Runtime ScheduleHost 仅支持插件注册的内存任务（list），' +
     '不支持 add/remove/pause/resume（需要 @zhin.js/agent 持久化调度引擎）';
@@ -23,7 +24,7 @@ export function listSchedule(ctx) {
             ...(job.nextExecution
                 ? { nextExecution: job.nextExecution } : {}),
         }));
-        return listPersistentJobs(ctx).then((persistent) => ({ data: { memory, persistent } }));
+        return listPersistentJobs(ctx).then((persistent) => ({ data: { memory, persistent, capabilities: { persistent: !!ctx.resolveScheduleEngine?.() && ctx.fullScope } } })).catch((error) => ({ error: errorMessage(error) }));
     }
     catch (error) {
         return { error: errorMessage(error) };
@@ -51,8 +52,8 @@ async function listPersistentJobs(ctx) {
             lastStatus: job.state?.lastStatus,
         }));
     }
-    catch {
-        return [];
+    catch (error) {
+        throw new Error(`读取持久化任务失败: ${errorMessage(error)}`);
     }
 }
 export async function addCron(d, ctx) {
@@ -65,6 +66,12 @@ export async function addCron(d, ctx) {
         return { error: 'cronExpression is required' };
     if (!prompt)
         return { error: 'prompt is required' };
+    try {
+        parseCron(cronExpression);
+    }
+    catch (error) {
+        return { error: `Cron 表达式无效: ${errorMessage(error)}` };
+    }
     const label = typeof d.label === 'string' && d.label.trim() ? d.label.trim() : undefined;
     const context = (d.context ?? {});
     const target = context.target ?? context.channel;
@@ -107,3 +114,13 @@ export async function mutateCron(type, d, ctx) {
     }
 }
 // ---------------------------------------------------------------- inbox
+/** Uses the same parser as the persistent schedule engine; never creates a job. */
+export function validateCron(d) {
+    try {
+        parseCron(String(d.cronExpression ?? '').trim());
+        return { data: { valid: true } };
+    }
+    catch (error) {
+        return { data: { valid: false, error: errorMessage(error) } };
+    }
+}

package/lib/console-rpc.js

@@ -652,6 +652,8 @@ export async function dispatchRuntimeConsoleRpc(message, ctx) {
                         reachable: endpoint.connected && endpoint.status === 'online',
                         connected: endpoint.connected,
                         status: endpoint.status,
+                        admitted: endpoint.admitted,
+                        transportState: endpoint.transportState,
                         phase: endpoint.phase ?? (endpoint.connected ? 'online' : 'pending'),
                         pendingLogin: endpoint.pendingLogin ?? false,
                         latencyMs: Date.now() - startedAt,

package/lib/http-host.js

@@ -30,6 +30,7 @@ export function createHttpHost(options = {}) {
     let address;
     let closed = false;
     let closeResult;
+    let listenResult;
     const secure = options.tls !== undefined;
     const handleRequest = (request, response) => {
         void dispatchHttp(request, response);
@@ -205,7 +206,10 @@ export function createHttpHost(options = {}) {
         if (!auth.ok) {
             if (corsOk && origin)
                 applyCors(response, origin, corsOrigins);
-            writeJson(response, 401, { success: false, error: 'Invalid or missing token' });
+            writeJson(response, auth.forbidden ? 403 : 401, {
+                success: false,
+                error: auth.forbidden ? 'Token scope does not allow this route' : 'Invalid or missing token',
+            });
             return;
         }
         const route = matchHttpRoute(httpRoutes, method, pathname);
@@ -280,7 +284,7 @@ export function createHttpHost(options = {}) {
         if (scope === 'demo') {
             const method = (request.method ?? 'GET').toUpperCase();
             if (!isDemoHttpAllowed(method, pathname, apiBase))
-                return { ok: false };
+                return { ok: false, forbidden: true };
         }
         const principal = tokenRegistry.resolvePrincipal(token);
         return { ok: true, scope, ...(principal ? { principal } : {}) };
@@ -365,12 +369,24 @@ export function createHttpHost(options = {}) {
             return tokenRegistry;
         },
         listen() {
+            if (closed)
+                return Promise.reject(new Error('HTTP Host is closed'));
+            if (listenResult)
+                return listenResult;
             if (address)
                 return Promise.resolve(address);
-            return new Promise((resolve, reject) => {
-                server.once('error', reject);
+            listenResult = new Promise((resolve, reject) => {
+                const onError = (error) => {
+                    listenResult = undefined;
+                    reject(error);
+                };
+                server.once('error', onError);
                 server.listen({ host, port }, () => {
-                    server.off('error', reject);
+                    server.off('error', onError);
+                    if (closed) {
+                        reject(new Error('HTTP Host closed before listen completed'));
+                        return;
+                    }
                     const bound = server.address();
                     const listenPort = typeof bound === 'object' && bound ? bound.port : port;
                     const publicHost = host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host;
@@ -390,6 +406,7 @@ export function createHttpHost(options = {}) {
                     resolve(address);
                 });
             });
+            return listenResult;
         },
         close() {
             if (closeResult)
@@ -397,37 +414,40 @@ export function createHttpHost(options = {}) {
             closed = true;
             wsRoutes.clear();
             httpRoutes.length = 0;
-            // Rollback paths dispose a host whose generation never reached listen().
-            if (!server.listening) {
-                address = undefined;
-                closeResult = Promise.resolve();
-                return closeResult;
-            }
-            closeResult = new Promise((resolve, reject) => {
-                // Long-lived connections (SSE, keep-alive, WS) never end on their own:
-                // destroy tracked sockets and terminate WS clients before close(),
-                // otherwise the close callbacks would never fire.
-                for (const socket of sockets)
-                    socket.destroy();
-                sockets.clear();
-                for (const client of wss.clients)
-                    client.terminate();
-                wss.close((wssError) => {
-                    if (wssError) {
-                        reject(wssError);
-                        return;
-                    }
-                    server.close((serverError) => {
-                        if (serverError) {
-                            reject(serverError);
+            closeResult = (async () => {
+                // A pending listen must settle before deciding whether there is a
+                // listener to close. Otherwise it can bind after close has resolved.
+                await listenResult?.catch(() => undefined);
+                if (!server.listening) {
+                    address = undefined;
+                    return;
+                }
+                await new Promise((resolve, reject) => {
+                    // Long-lived connections (SSE, keep-alive, WS) never end on their own:
+                    // destroy tracked sockets and terminate WS clients before close(),
+                    // otherwise the close callbacks would never fire.
+                    for (const socket of sockets)
+                        socket.destroy();
+                    sockets.clear();
+                    for (const client of wss.clients)
+                        client.terminate();
+                    wss.close((wssError) => {
+                        if (wssError) {
+                            reject(wssError);
                             return;
                         }
-                        logger.debug(formatCompact({ op: 'http_host_closed' }));
-                        address = undefined;
-                        resolve();
+                        server.close((serverError) => {
+                            if (serverError) {
+                                reject(serverError);
+                                return;
+                            }
+                            logger.debug(formatCompact({ op: 'http_host_closed' }));
+                            address = undefined;
+                            resolve();
+                        });
                     });
                 });
-            });
+            })();
             return closeResult;
         },
     };

package/lib/project-files.js

@@ -1,4 +1,4 @@
-import { access, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { access, lstat, mkdir, readdir, readFile, realpath, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 /** Align with Remote Console file manager (paths relative to project root). */
 export const FILE_MANAGER_ALLOWED = Object.freeze([
@@ -39,8 +39,7 @@ export function isProjectPathAllowed(relativePath) {
     if (relativePath.includes('..') || path.isAbsolute(relativePath))
         return false;
     const normalized = relativePath.replace(/\\/gu, '/').replace(/^\.\//u, '');
-    const firstSegment = normalized.split('/')[0] ?? '';
-    if (FILE_MANAGER_BLOCKED.has(firstSegment))
+    if (normalized.split('/').some((segment) => FILE_MANAGER_BLOCKED.has(segment)))
         return false;
     return FILE_MANAGER_ALLOWED.some((allowed) => normalized === allowed || normalized.startsWith(`${allowed}/`));
 }
@@ -49,7 +48,9 @@ export async function buildProjectFileTree(projectRoot) {
     for (const entry of FILE_MANAGER_ALLOWED) {
         if (entry.includes('/'))
             continue;
-        const absPath = path.resolve(projectRoot, entry);
+        const absPath = await resolveAllowedPath(projectRoot, entry);
+        if (!absPath)
+            continue;
         if (!(await pathExists(absPath)))
             continue;
         const info = await safeStat(absPath);
@@ -70,7 +71,7 @@ export async function buildProjectFileTree(projectRoot) {
     return tree.sort(compareTreeNodes);
 }
 export async function readProjectFile(projectRoot, relativePath) {
-    const absPath = resolveAllowedPath(projectRoot, relativePath);
+    const absPath = await resolveAllowedPath(projectRoot, relativePath);
     if (!absPath)
         throw new Error(`Access denied: ${relativePath}`);
     if (!(await pathExists(absPath)))
@@ -85,29 +86,69 @@ export async function readProjectFile(projectRoot, relativePath) {
     return { content, size: info.size };
 }
 export async function saveProjectFile(projectRoot, relativePath, content) {
-    const absPath = resolveAllowedPath(projectRoot, relativePath);
+    const absPath = await resolveAllowedPath(projectRoot, relativePath);
     if (!absPath)
         throw new Error(`Access denied: ${relativePath}`);
     await mkdir(path.dirname(absPath), { recursive: true });
-    await writeFile(absPath, content, 'utf8');
+    const checkedPath = await resolveAllowedPath(projectRoot, relativePath);
+    if (!checkedPath)
+        throw new Error(`Access denied: ${relativePath}`);
+    await writeFile(checkedPath, content, 'utf8');
 }
 export async function listEnvFiles(projectRoot) {
     const names = ['.env', '.env.development', '.env.production'];
-    const result = await Promise.all(names.map(async (name) => ({
-        name,
-        exists: await pathExists(path.resolve(projectRoot, name)),
-    })));
+    const result = await Promise.all(names.map(async (name) => {
+        const resolved = await resolveAllowedPath(projectRoot, name);
+        return { name, exists: resolved !== null && await pathExists(resolved) };
+    }));
     return Object.freeze(result);
 }
-function resolveAllowedPath(projectRoot, relativePath) {
+/** Resolve existing links, or the nearest existing parent for a new file. */
+async function resolveAllowedPath(projectRoot, relativePath) {
     if (!isProjectPathAllowed(relativePath))
         return null;
-    return path.resolve(projectRoot, relativePath);
+    try {
+        const root = await realpath(projectRoot);
+        let candidate = path.resolve(root, relativePath);
+        const missing = [];
+        for (;;) {
+            try {
+                // A dangling link must fail closed rather than be treated as a missing directory.
+                await lstat(candidate);
+                const resolved = path.resolve(await realpath(candidate), ...missing);
+                const relative = path.relative(root, resolved);
+                return isProjectPathAllowed(relative) ? resolved : null;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    return null;
+                // lstat succeeds for dangling symlinks even though realpath fails.
+                try {
+                    await lstat(candidate);
+                    return null;
+                }
+                catch (missingError) {
+                    if (missingError.code !== 'ENOENT')
+                        return null;
+                }
+                const parent = path.dirname(candidate);
+                if (candidate === root || parent === candidate)
+                    return null;
+                missing.unshift(path.basename(candidate));
+                candidate = parent;
+            }
+        }
+    }
+    catch {
+        return null;
+    }
 }
 async function buildDirectoryTree(projectRoot, relativePath, maxDepth) {
     if (maxDepth <= 0)
         return [];
-    const absDir = path.resolve(projectRoot, relativePath);
+    const absDir = await resolveAllowedPath(projectRoot, relativePath);
+    if (!absDir)
+        return [];
     const info = await safeStat(absDir);
     if (!info?.isDirectory())
         return [];
@@ -117,7 +158,11 @@ async function buildDirectoryTree(projectRoot, relativePath, maxDepth) {
         if (FILE_MANAGER_BLOCKED.has(entry.name) || entry.name.startsWith('.'))
             continue;
         const childRelative = relativePath ? `${relativePath}/${entry.name}` : entry.name;
-        if (entry.isDirectory()) {
+        const childPath = await resolveAllowedPath(projectRoot, childRelative);
+        if (!childPath)
+            continue;
+        const childInfo = await safeStat(childPath);
+        if (childInfo?.isDirectory()) {
             result.push({
                 name: entry.name,
                 path: childRelative,
@@ -125,7 +170,7 @@ async function buildDirectoryTree(projectRoot, relativePath, maxDepth) {
                 children: await buildDirectoryTree(projectRoot, childRelative, maxDepth - 1),
             });
         }
-        else if (entry.isFile()) {
+        else if (childInfo?.isFile()) {
             result.push({ name: entry.name, path: childRelative, type: 'file' });
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/host-http",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Minimal HTTP and WebSocket host for Plugin Runtime (no Koa)",
   "type": "module",
   "main": "./lib/index.js",
@@ -18,10 +18,11 @@
   ],
   "dependencies": {
     "ws": "^8.21.1",
-    "@zhin.js/console-protocol": "1.1.6",
+    "@zhin.js/console-protocol": "1.1.7",
     "@zhin.js/host-http-contract": "1.1.0",
     "@zhin.js/logger": "1.1.1",
-    "@zhin.js/plugin-runtime": "1.1.11"
+    "@zhin.js/schedule": "1.1.2",
+    "@zhin.js/plugin-runtime": "1.1.12"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/src/console-rest-pages.ts

@@ -108,6 +108,7 @@ type LogSelectionLike = PromiseLike<LogRow[]> & {
   where(where: Record<string, unknown>): LogSelectionLike;
   orderBy(field: string, direction: 'ASC' | 'DESC'): LogSelectionLike;
   limit(count: number): Promise<LogRow[]>;
+  offset?(count: number): LogSelectionLike;
 };
 
 type LogRow = {
@@ -187,35 +188,57 @@ function registerLogsRoutes(
   const unavailableNote = 'SystemLog 模型不可用（Database 未启动或未注册 DatabaseLogTransport）';
 
   route('GET', `${base}/logs`, async (_request, response, url) => {
-    const limit = Math.min(
-      Math.max(parseInt(url.searchParams.get('limit') ?? '100', 10) || 100, 1),
-      1000,
-    );
-    const level = url.searchParams.get('level') ?? undefined;
+    const pageSize = clampPositiveInt(parsePositiveInt(url.searchParams.get('pageSize') ?? url.searchParams.get('limit'), 100), 100, 1000);
+    const requestedPage = clampPositiveInt(parsePositiveInt(url.searchParams.get('page'), 1), 1, Number.MAX_SAFE_INTEGER);
+    const level = url.searchParams.get('level');
+    const source = url.searchParams.get('source')?.trim();
+    const query = url.searchParams.get('q')?.trim();
+    const baseWhere: Record<string, unknown> = {
+      ...(level && level !== 'all' ? { level } : {}),
+    };
+    const where = { ...baseWhere, ...(source ? { source } : {}) };
     const LogModel = getModel();
     if (!LogModel) {
-      writeJson(response, 200, { success: true, data: [], total: 0, note: unavailableNote });
+      writeJson(response, 200, { success: true, data: [], total: 0, page: 1, pageSize, totalPages: 1, sources: [], note: unavailableNote });
       return;
     }
-
-    let selection = LogModel.select();
-    if (level && level !== 'all') {
-      selection = selection.where({ level });
+    // Database $like has no portable ESCAPE contract. Keep q literal (including
+    // %/_ and Unicode) and filter actual retained rows on the Host, not wildcard SQL.
+    const matchesQuery = (row: LogRow): boolean => !query || ['message', 'name', 'source']
+      .some(field => String(row[field as keyof LogRow] ?? '').toLowerCase().includes(query.toLowerCase()));
+    const selection = LogModel.select().where(where).orderBy('timestamp', 'DESC').orderBy('id', 'DESC');
+    const queriedRows = query ? (await selection).filter(matchesQuery) : undefined;
+    const total = queriedRows?.length ?? (typeof LogModel.count === 'function'
+      ? await LogModel.count(where)
+      : (await LogModel.select('id').where(where)).length);
+    const totalPages = Math.max(1, Math.ceil(total / pageSize));
+    const page = Math.min(requestedPage, totalPages);
+    const offset = (page - 1) * pageSize;
+    const logs = queriedRows
+      ? queriedRows.slice(offset, offset + pageSize)
+      : selection.offset
+        ? await selection.offset(offset).limit(pageSize)
+        : (await selection).slice(offset, offset + pageSize);
+    // Source counts match level/q, but exclude the selected source and page window.
+    const sourceRows = await LogModel.select('source', 'name', 'message').where(baseWhere);
+    const counts = new Map<string, number>();
+    for (const row of sourceRows) {
+      const name = row.source;
+      if (!name || !matchesQuery(row)) continue;
+      counts.set(name, (counts.get(name) ?? 0) + 1);
     }
-
-    const logs = await selection.orderBy('timestamp', 'DESC').limit(limit);
-
     writeJson(response, 200, {
       success: true,
       data: logs.map((log) => ({
+        id: log.id,
         level: log.level,
         name: log.name,
         message: log.message,
         source: log.source,
-        timestamp:
-          log.timestamp instanceof Date ? log.timestamp.toISOString() : log.timestamp,
+        timestamp: log.timestamp instanceof Date ? log.timestamp.toISOString() : log.timestamp,
       })),
-      total: logs.length,
+      total, page, pageSize, totalPages,
+      sources: [...counts].sort(([a], [b]) => a.localeCompare(b)).map(([source, count]) => ({ source, count })),
     });
   }, { summary: 'List system logs', tags: ['console', 'logs'] });
 
@@ -363,8 +386,8 @@ function registerMarketplaceRoutes(
         version: p.version || '',
         description: p.description || '',
         author: p.author || '',
-        isOfficial: !!p.isOfficial,
-        official: !!p.isOfficial,
+        isOfficial: typeof p.name === 'string' && /^@zhin\.js\/[a-z0-9][a-z0-9._-]*$/.test(p.name),
+        official: typeof p.name === 'string' && /^@zhin\.js\/[a-z0-9][a-z0-9._-]*$/.test(p.name),
         category: p.category || 'util',
         keywords: (p.tags as string[]) || [],
         npm: p.npm || `https://www.npmjs.com/package/${p.name}`,

package/src/console-rpc-extended/dispatcher.ts

@@ -1,6 +1,6 @@
 import { assertDemoConsoleRpcAllowed } from '@zhin.js/console-protocol';
 import type { ConsoleRpcExtendedCtx, ExtendedRpcResult } from './contracts.js';
-import { addCron, listSchedule, mutateCron } from './schedule-rpc.js';
+import { addCron, listSchedule, mutateCron, validateCron } from './schedule-rpc.js';
 import {
   actOnRequest, listInbox, listInboxMessages, listPendingRequests, listRecentInboxMessages,
   mapNoticeRow, mapRequestRow, markInboxConsumed, TABLE_NOTICE, TABLE_REQUEST,
@@ -28,6 +28,9 @@ export async function dispatchExtendedConsoleRpc(
     case 'cron:list':
       return listSchedule(ctx);
 
+    case 'cron:validate':
+      return validateCron(d);
+
     case 'cron:add':
       return addCron(d, ctx);
     case 'cron:remove':

package/src/console-rpc-extended/schedule-rpc.ts

@@ -1,3 +1,4 @@
+import { parseCron } from '@zhin.js/schedule';
 import type { ConsoleRpcExtendedCtx, ConsoleScheduleEngine, ExtendedRpcResult, ScheduleJobRow } from './contracts.js';
 import { errorMessage, strField } from './rpc-values.js';
 
@@ -28,7 +29,7 @@ export function listSchedule(ctx: ConsoleScheduleListCtx): Promise<ExtendedRpcRe
         ...((job as { nextExecution?: number }).nextExecution
           ? { nextExecution: (job as { nextExecution?: number }).nextExecution } : {}),
       }));
-    return listPersistentJobs(ctx).then((persistent) => ({ data: { memory, persistent } }));
+    return listPersistentJobs(ctx).then((persistent) => ({ data: { memory, persistent, capabilities: { persistent: !!ctx.resolveScheduleEngine?.() && ctx.fullScope } } })).catch((error) => ({ error: errorMessage(error) }));
   } catch (error) {
     return { error: errorMessage(error) };
   }
@@ -56,8 +57,8 @@ async function listPersistentJobs(ctx: ConsoleRpcExtendedCtx): Promise<Record<st
       lastExecutedAt: (job.state as { lastExecutedAt?: number } | undefined)?.lastExecutedAt,
       lastStatus: (job.state as { lastStatus?: string } | undefined)?.lastStatus,
     }));
-  } catch {
-    return [];
+  } catch (error) {
+    throw new Error(`读取持久化任务失败: ${errorMessage(error)}`);
   }
 }
 
@@ -71,6 +72,11 @@ export async function addCron(
   const prompt = String(d.prompt ?? '').trim();
   if (!cronExpression) return { error: 'cronExpression is required' };
   if (!prompt) return { error: 'prompt is required' };
+  try {
+    parseCron(cronExpression);
+  } catch (error) {
+    return { error: `Cron 表达式无效: ${errorMessage(error)}` };
+  }
   const label = typeof d.label === 'string' && d.label.trim() ? d.label.trim() : undefined;
   const context = (d.context ?? {}) as Record<string, unknown>;
   const target = context.target ?? context.channel;
@@ -115,3 +121,13 @@ export async function mutateCron(
 }
 
 // ---------------------------------------------------------------- inbox
+
+/** Uses the same parser as the persistent schedule engine; never creates a job. */
+export function validateCron(d: Record<string, unknown>): ExtendedRpcResult {
+  try {
+    parseCron(String(d.cronExpression ?? '').trim());
+    return { data: { valid: true } };
+  } catch (error) {
+    return { data: { valid: false, error: errorMessage(error) } };
+  }
+}

package/src/console-rpc.ts

@@ -812,6 +812,8 @@ export async function dispatchRuntimeConsoleRpc(
           reachable: endpoint.connected && endpoint.status === 'online',
           connected: endpoint.connected,
           status: endpoint.status,
+          admitted: endpoint.admitted,
+          transportState: endpoint.transportState,
           phase: endpoint.phase ?? (endpoint.connected ? 'online' : 'pending'),
           pendingLogin: endpoint.pendingLogin ?? false,
           latencyMs: Date.now() - startedAt,

package/src/http-host.ts

@@ -170,6 +170,7 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
   let address: HttpHostAddress | undefined;
   let closed = false;
   let closeResult: Promise<void> | undefined;
+  let listenResult: Promise<HttpHostAddress> | undefined;
 
   const secure = options.tls !== undefined;
   const handleRequest = (request: IncomingMessage, response: ServerResponse): void => {
@@ -345,7 +346,10 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
     const auth = authenticateHttp(request, url, pathname);
     if (!auth.ok) {
       if (corsOk && origin) applyCors(response, origin, corsOrigins);
-      writeJson(response, 401, { success: false, error: 'Invalid or missing token' });
+      writeJson(response, auth.forbidden ? 403 : 401, {
+        success: false,
+        error: auth.forbidden ? 'Token scope does not allow this route' : 'Invalid or missing token',
+      });
       return;
     }
 
@@ -407,7 +411,7 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
     request: IncomingMessage,
     url: URL,
     pathname: string,
-  ): { ok: true; scope: AuthScope; principal?: AuthenticatedTokenPrincipal } | { ok: false } {
+  ): { ok: true; scope: AuthScope; principal?: AuthenticatedTokenPrincipal } | { ok: false; forbidden?: boolean } {
     if (!requiresHttpAuth(pathname, apiBase, authExempt)) {
       return { ok: true, scope: 'full' };
     }
@@ -422,7 +426,7 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
     if (!scope) return { ok: false };
     if (scope === 'demo') {
       const method = (request.method ?? 'GET').toUpperCase();
-      if (!isDemoHttpAllowed(method, pathname, apiBase)) return { ok: false };
+      if (!isDemoHttpAllowed(method, pathname, apiBase)) return { ok: false, forbidden: true };
     }
     const principal = tokenRegistry.resolvePrincipal(token);
     return { ok: true, scope, ...(principal ? { principal } : {}) };
@@ -534,11 +538,21 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
     },
 
     listen(): Promise<HttpHostAddress> {
+      if (closed) return Promise.reject(new Error('HTTP Host is closed'));
+      if (listenResult) return listenResult;
       if (address) return Promise.resolve(address);
-      return new Promise((resolve, reject) => {
-        server.once('error', reject);
+      listenResult = new Promise((resolve, reject) => {
+        const onError = (error: Error): void => {
+          listenResult = undefined;
+          reject(error);
+        };
+        server.once('error', onError);
         server.listen({ host, port }, () => {
-          server.off('error', reject);
+          server.off('error', onError);
+          if (closed) {
+            reject(new Error('HTTP Host closed before listen completed'));
+            return;
+          }
           const bound = server.address();
           const listenPort = typeof bound === 'object' && bound ? bound.port : port;
           const publicHost = host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host;
@@ -562,6 +576,7 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
           resolve(address);
         });
       });
+      return listenResult;
     },
 
     close(): Promise<void> {
@@ -569,35 +584,38 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
       closed = true;
       wsRoutes.clear();
       httpRoutes.length = 0;
-      // Rollback paths dispose a host whose generation never reached listen().
-      if (!server.listening) {
-        address = undefined;
-        closeResult = Promise.resolve();
-        return closeResult;
-      }
-      closeResult = new Promise((resolve, reject) => {
-        // Long-lived connections (SSE, keep-alive, WS) never end on their own:
-        // destroy tracked sockets and terminate WS clients before close(),
-        // otherwise the close callbacks would never fire.
-        for (const socket of sockets) socket.destroy();
-        sockets.clear();
-        for (const client of wss.clients) client.terminate();
-        wss.close((wssError) => {
-          if (wssError) {
-            reject(wssError);
-            return;
-          }
-          server.close((serverError) => {
-            if (serverError) {
-              reject(serverError);
+      closeResult = (async () => {
+        // A pending listen must settle before deciding whether there is a
+        // listener to close. Otherwise it can bind after close has resolved.
+        await listenResult?.catch(() => undefined);
+        if (!server.listening) {
+          address = undefined;
+          return;
+        }
+        await new Promise<void>((resolve, reject) => {
+          // Long-lived connections (SSE, keep-alive, WS) never end on their own:
+          // destroy tracked sockets and terminate WS clients before close(),
+          // otherwise the close callbacks would never fire.
+          for (const socket of sockets) socket.destroy();
+          sockets.clear();
+          for (const client of wss.clients) client.terminate();
+          wss.close((wssError) => {
+            if (wssError) {
+              reject(wssError);
               return;
             }
-            logger.debug(formatCompact({ op: 'http_host_closed' }));
-            address = undefined;
-            resolve();
+            server.close((serverError) => {
+              if (serverError) {
+                reject(serverError);
+                return;
+              }
+              logger.debug(formatCompact({ op: 'http_host_closed' }));
+              address = undefined;
+              resolve();
+            });
           });
         });
-      });
+      })();
       return closeResult;
     },
   };

package/src/project-files.ts

@@ -1,4 +1,4 @@
-import { access, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { access, lstat, mkdir, readdir, readFile, realpath, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
 /** Align with Remote Console file manager (paths relative to project root). */
@@ -48,8 +48,7 @@ export type FileTreeNode = {
 export function isProjectPathAllowed(relativePath: string): boolean {
   if (relativePath.includes('..') || path.isAbsolute(relativePath)) return false;
   const normalized = relativePath.replace(/\\/gu, '/').replace(/^\.\//u, '');
-  const firstSegment = normalized.split('/')[0] ?? '';
-  if (FILE_MANAGER_BLOCKED.has(firstSegment)) return false;
+  if (normalized.split('/').some((segment) => FILE_MANAGER_BLOCKED.has(segment))) return false;
   return FILE_MANAGER_ALLOWED.some(
     (allowed) => normalized === allowed || normalized.startsWith(`${allowed}/`),
   );
@@ -59,7 +58,8 @@ export async function buildProjectFileTree(projectRoot: string): Promise<FileTre
   const tree: FileTreeNode[] = [];
   for (const entry of FILE_MANAGER_ALLOWED) {
     if (entry.includes('/')) continue;
-    const absPath = path.resolve(projectRoot, entry);
+    const absPath = await resolveAllowedPath(projectRoot, entry);
+    if (!absPath) continue;
     if (!(await pathExists(absPath))) continue;
     const info = await safeStat(absPath);
     if (!info) continue;
@@ -81,7 +81,7 @@ export async function readProjectFile(
   projectRoot: string,
   relativePath: string,
 ): Promise<{ content: string; size: number }> {
-  const absPath = resolveAllowedPath(projectRoot, relativePath);
+  const absPath = await resolveAllowedPath(projectRoot, relativePath);
   if (!absPath) throw new Error(`Access denied: ${relativePath}`);
   if (!(await pathExists(absPath))) throw new Error(`File not found: ${relativePath}`);
   const info = await safeStat(absPath);
@@ -98,26 +98,54 @@ export async function saveProjectFile(
   relativePath: string,
   content: string,
 ): Promise<void> {
-  const absPath = resolveAllowedPath(projectRoot, relativePath);
+  const absPath = await resolveAllowedPath(projectRoot, relativePath);
   if (!absPath) throw new Error(`Access denied: ${relativePath}`);
   await mkdir(path.dirname(absPath), { recursive: true });
-  await writeFile(absPath, content, 'utf8');
+  const checkedPath = await resolveAllowedPath(projectRoot, relativePath);
+  if (!checkedPath) throw new Error(`Access denied: ${relativePath}`);
+  await writeFile(checkedPath, content, 'utf8');
 }
 
 export async function listEnvFiles(
   projectRoot: string,
 ): Promise<readonly { name: string; exists: boolean }[]> {
   const names = ['.env', '.env.development', '.env.production'] as const;
-  const result = await Promise.all(names.map(async (name) => ({
-    name,
-    exists: await pathExists(path.resolve(projectRoot, name)),
-  })));
+  const result = await Promise.all(names.map(async (name) => {
+    const resolved = await resolveAllowedPath(projectRoot, name);
+    return { name, exists: resolved !== null && await pathExists(resolved) };
+  }));
   return Object.freeze(result);
 }
 
-function resolveAllowedPath(projectRoot: string, relativePath: string): string | null {
+/** Resolve existing links, or the nearest existing parent for a new file. */
+async function resolveAllowedPath(projectRoot: string, relativePath: string): Promise<string | null> {
   if (!isProjectPathAllowed(relativePath)) return null;
-  return path.resolve(projectRoot, relativePath);
+  try {
+    const root = await realpath(projectRoot);
+    let candidate = path.resolve(root, relativePath);
+    const missing: string[] = [];
+    for (;;) {
+      try {
+        // A dangling link must fail closed rather than be treated as a missing directory.
+        await lstat(candidate);
+        const resolved = path.resolve(await realpath(candidate), ...missing);
+        const relative = path.relative(root, resolved);
+        return isProjectPathAllowed(relative) ? resolved : null;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') return null;
+        // lstat succeeds for dangling symlinks even though realpath fails.
+        try { await lstat(candidate); return null; } catch (missingError) {
+          if ((missingError as NodeJS.ErrnoException).code !== 'ENOENT') return null;
+        }
+        const parent = path.dirname(candidate);
+        if (candidate === root || parent === candidate) return null;
+        missing.unshift(path.basename(candidate));
+        candidate = parent;
+      }
+    }
+  } catch {
+    return null;
+  }
 }
 
 async function buildDirectoryTree(
@@ -126,7 +154,8 @@ async function buildDirectoryTree(
   maxDepth: number,
 ): Promise<FileTreeNode[]> {
   if (maxDepth <= 0) return [];
-  const absDir = path.resolve(projectRoot, relativePath);
+  const absDir = await resolveAllowedPath(projectRoot, relativePath);
+  if (!absDir) return [];
   const info = await safeStat(absDir);
   if (!info?.isDirectory()) return [];
   const entries = await readdir(absDir, { withFileTypes: true });
@@ -134,14 +163,17 @@ async function buildDirectoryTree(
   for (const entry of entries) {
     if (FILE_MANAGER_BLOCKED.has(entry.name) || entry.name.startsWith('.')) continue;
     const childRelative = relativePath ? `${relativePath}/${entry.name}` : entry.name;
-    if (entry.isDirectory()) {
+    const childPath = await resolveAllowedPath(projectRoot, childRelative);
+    if (!childPath) continue;
+    const childInfo = await safeStat(childPath);
+    if (childInfo?.isDirectory()) {
       result.push({
         name: entry.name,
         path: childRelative,
         type: 'directory',
         children: await buildDirectoryTree(projectRoot, childRelative, maxDepth - 1),
       });
-    } else if (entry.isFile()) {
+    } else if (childInfo?.isFile()) {
       result.push({ name: entry.name, path: childRelative, type: 'file' });
     }
   }