@zhin.js/runtime 1.1.3 → 1.1.5

package/lib/config-composer.d.ts

@@ -1,6 +1,637 @@
-import type { RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
-import type { PluginId } from '@zhin.js/plugin-runtime';
+import type { RuntimeConfigDocument, PluginId } from '@zhin.js/plugin-runtime';
 import type { ProjectGraph } from './project-graph.js';
+export declare const HOST_CONFIG_SCHEMA: {
+    $schema: string;
+    type: string;
+    additionalProperties: boolean;
+    properties: {
+        http: {
+            type: string;
+            additionalProperties: boolean;
+            description: string;
+            "x-descriptionZh": string;
+            properties: {
+                readiness: {
+                    type: string;
+                    additionalProperties: boolean;
+                    description: string;
+                    "x-descriptionZh": string;
+                    properties: {
+                        database: {
+                            type: string;
+                            default: boolean;
+                            description: string;
+                            "x-descriptionZh": string;
+                        };
+                        endpoints: {
+                            type: string;
+                            uniqueItems: boolean;
+                            description: string;
+                            "x-descriptionZh": string;
+                            items: {
+                                type: string;
+                                additionalProperties: boolean;
+                                required: string[];
+                                properties: {
+                                    owner: {
+                                        type: string;
+                                        pattern: string;
+                                    };
+                                    name: {
+                                        type: string;
+                                        minLength: number;
+                                        pattern: string;
+                                    };
+                                };
+                            };
+                        };
+                        agents: {
+                            type: string;
+                            uniqueItems: boolean;
+                            items: {
+                                type: string;
+                                minLength: number;
+                            };
+                            description: string;
+                            "x-descriptionZh": string;
+                        };
+                    };
+                };
+            };
+        };
+        database: {
+            type: string;
+            additionalProperties: boolean;
+            description: string;
+            "x-descriptionZh": string;
+        };
+        ai: {
+            type: string;
+            additionalProperties: boolean;
+            description: string;
+            "x-descriptionZh": string;
+            properties: {
+                decisions: {
+                    type: string;
+                    additionalProperties: boolean;
+                    required: string[];
+                    description: string;
+                    "x-descriptionZh": string;
+                    properties: {
+                        provider: {
+                            type: string;
+                            pattern: string;
+                            description: string;
+                            "x-descriptionZh": string;
+                        };
+                        skills: {
+                            $ref: string;
+                        };
+                        tools: {
+                            $ref: string;
+                        };
+                        memory: {
+                            $ref: string;
+                        };
+                        agents: {
+                            $ref: string;
+                        };
+                        approval: {
+                            $ref: string;
+                        };
+                    };
+                };
+                workroom: {
+                    type: string;
+                    additionalProperties: boolean;
+                    description: string;
+                    "x-descriptionZh": string;
+                    properties: {
+                        trustedPackPublishers: {
+                            type: string;
+                            items: {
+                                type: string;
+                                minLength: number;
+                            };
+                            uniqueItems: boolean;
+                            description: string;
+                            "x-descriptionZh": string;
+                        };
+                        disclosure: {
+                            type: string;
+                            additionalProperties: boolean;
+                            description: string;
+                            "x-descriptionZh": string;
+                            properties: {
+                                tenantId: {
+                                    type: string;
+                                    minLength: number;
+                                };
+                                modelProviders: {
+                                    type: string;
+                                    additionalProperties: {
+                                        type: string;
+                                        additionalProperties: boolean;
+                                        required: string[];
+                                        properties: {
+                                            endpoint: {
+                                                type: string;
+                                                minLength: number;
+                                            };
+                                            owner: {
+                                                type: string;
+                                                minLength: number;
+                                            };
+                                            trustDomain: {
+                                                type: string;
+                                                minLength: number;
+                                            };
+                                            processingRegions: {
+                                                type: string;
+                                                minItems: number;
+                                                uniqueItems: boolean;
+                                                items: {
+                                                    type: string;
+                                                    minLength: number;
+                                                };
+                                            };
+                                            maxConfidentiality: {
+                                                type: string;
+                                                enum: string[];
+                                            };
+                                            external: {
+                                                type: string;
+                                            };
+                                            noTraining: {
+                                                type: string;
+                                            };
+                                            loggingMode: {
+                                                type: string;
+                                                enum: string[];
+                                            };
+                                            maximumRetentionSeconds: {
+                                                type: string;
+                                                minimum: number;
+                                            };
+                                            allowsRedisclosure: {
+                                                type: string;
+                                            };
+                                            supportsDeletion: {
+                                                type: string;
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+                agent: {
+                    type: string;
+                    additionalProperties: boolean;
+                    description: string;
+                    "x-descriptionZh": string;
+                    properties: {
+                        inboundQueue: {
+                            type: string;
+                            additionalProperties: boolean;
+                            description: string;
+                            "x-descriptionZh": string;
+                            properties: {
+                                groupMode: {
+                                    type: string;
+                                    enum: string[];
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                            };
+                        };
+                        execSecurity: {
+                            type: string;
+                            enum: string[];
+                            description: string;
+                            "x-descriptionZh": string;
+                        };
+                        execPreset: {
+                            type: string;
+                            enum: string[];
+                            description: string;
+                            "x-descriptionZh": string;
+                        };
+                        execApprovalMode: {
+                            type: string;
+                            enum: string[];
+                            description: string;
+                            "x-descriptionZh": string;
+                        };
+                        subagentExecApprovalMode: {
+                            type: string;
+                            enum: string[];
+                            description: string;
+                            "x-descriptionZh": string;
+                        };
+                        workerExecApprovalMode: {
+                            type: string;
+                            enum: string[];
+                            description: string;
+                            "x-descriptionZh": string;
+                        };
+                        taskExecApprovalMode: {
+                            type: string;
+                            enum: string[];
+                            description: string;
+                            "x-descriptionZh": string;
+                        };
+                        toolExecution: {
+                            type: string;
+                            enum: string[];
+                            description: string;
+                            "x-descriptionZh": string;
+                        };
+                        modelSizeHint: {
+                            type: string;
+                            enum: string[];
+                            description: string;
+                            "x-descriptionZh": string;
+                        };
+                        promptCacheRetention: {
+                            type: string;
+                            enum: string[];
+                            description: string;
+                            "x-descriptionZh": string;
+                        };
+                        steeringMode: {
+                            type: string;
+                            enum: string[];
+                            description: string;
+                            "x-descriptionZh": string;
+                        };
+                        followUpMode: {
+                            type: string;
+                            enum: string[];
+                            description: string;
+                            "x-descriptionZh": string;
+                        };
+                        outputSchema: {
+                            anyOf: ({
+                                type: string;
+                                enum?: undefined;
+                            } | {
+                                type: string;
+                                enum: string[];
+                            })[];
+                            description: string;
+                            "x-descriptionZh": string;
+                        };
+                        schedule: {
+                            type: string;
+                            additionalProperties: boolean;
+                            description: string;
+                            "x-descriptionZh": string;
+                            properties: {
+                                security: {
+                                    type: string;
+                                    additionalProperties: boolean;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                    properties: {
+                                        execPreset: {
+                                            type: string;
+                                            enum: string[];
+                                            description: string;
+                                            "x-descriptionZh": string;
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        mcp: {
+            type: string;
+            additionalProperties: boolean;
+            description: string;
+            "x-descriptionZh": string;
+        };
+        a2a: {
+            type: string;
+            additionalProperties: boolean;
+            description: string;
+            "x-descriptionZh": string;
+        };
+        speech: {
+            type: string;
+            additionalProperties: boolean;
+            description: string;
+            "x-descriptionZh": string;
+        };
+        htmlRenderer: {
+            type: string;
+            additionalProperties: boolean;
+            description: string;
+            "x-descriptionZh": string;
+            properties: {
+                width: {
+                    type: string;
+                    minimum: number;
+                    maximum: number;
+                    description: string;
+                    "x-descriptionZh": string;
+                };
+                defaultWidth: {
+                    type: string;
+                    minimum: number;
+                    maximum: number;
+                    description: string;
+                    "x-descriptionZh": string;
+                };
+                viewport: {
+                    type: string;
+                    additionalProperties: boolean;
+                    description: string;
+                    "x-descriptionZh": string;
+                    properties: {
+                        width: {
+                            type: string;
+                            minimum: number;
+                            maximum: number;
+                            description: string;
+                            "x-descriptionZh": string;
+                        };
+                        height: {
+                            type: string;
+                            minimum: number;
+                            maximum: number;
+                            description: string;
+                            "x-descriptionZh": string;
+                        };
+                    };
+                };
+                backgroundColor: {
+                    type: string;
+                    description: string;
+                    "x-descriptionZh": string;
+                };
+                defaultBackgroundColor: {
+                    type: string;
+                    description: string;
+                    "x-descriptionZh": string;
+                };
+                scale: {
+                    type: string;
+                    minimum: number;
+                    maximum: number;
+                    description: string;
+                    "x-descriptionZh": string;
+                };
+                type: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                    "x-descriptionZh": string;
+                };
+                quality: {
+                    type: string;
+                    minimum: number;
+                    maximum: number;
+                    description: string;
+                    "x-descriptionZh": string;
+                };
+                timeout: {
+                    type: string;
+                    minimum: number;
+                    maximum: number;
+                    description: string;
+                    "x-descriptionZh": string;
+                };
+                waitUntil: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                    "x-descriptionZh": string;
+                };
+                fontFamily: {
+                    type: string;
+                    description: string;
+                    "x-descriptionZh": string;
+                };
+                maxImageHeight: {
+                    type: string;
+                    minimum: number;
+                    maximum: number;
+                    description: string;
+                    "x-descriptionZh": string;
+                };
+                sliceCompression: {
+                    type: string;
+                    minimum: number;
+                    maximum: number;
+                    description: string;
+                    "x-descriptionZh": string;
+                };
+                allowFileAccess: {
+                    type: string;
+                    description: string;
+                    "x-descriptionZh": string;
+                };
+                takeOverHtmlSegments: {
+                    type: string;
+                    description: string;
+                    "x-descriptionZh": string;
+                };
+                cacheDir: {
+                    type: string;
+                    description: string;
+                    "x-descriptionZh": string;
+                };
+                cacheMaxBytes: {
+                    type: string;
+                    minimum: number;
+                    description: string;
+                    "x-descriptionZh": string;
+                };
+                userAgent: {
+                    type: string;
+                    description: string;
+                    "x-descriptionZh": string;
+                };
+                idleTimeoutMs: {
+                    type: string;
+                    minimum: number;
+                    maximum: number;
+                    description: string;
+                    "x-descriptionZh": string;
+                };
+                logStats: {
+                    type: string;
+                    description: string;
+                    "x-descriptionZh": string;
+                };
+                mode: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                    "x-descriptionZh": string;
+                };
+                aiTextAsImage: {
+                    anyOf: ({
+                        type: string;
+                        additionalProperties?: undefined;
+                        description?: undefined;
+                        "x-descriptionZh"?: undefined;
+                        properties?: undefined;
+                    } | {
+                        type: string;
+                        additionalProperties: boolean;
+                        description: string;
+                        "x-descriptionZh": string;
+                        properties: {
+                            enabled: {
+                                type: string;
+                                description: string;
+                                "x-descriptionZh": string;
+                            };
+                            onlyAdapters: {
+                                type: string;
+                                items: {
+                                    type: string;
+                                    minLength: number;
+                                };
+                                uniqueItems: boolean;
+                                description: string;
+                                "x-descriptionZh": string;
+                            };
+                            minLength: {
+                                type: string;
+                                minimum: number;
+                                description: string;
+                                "x-descriptionZh": string;
+                            };
+                            maxLength: {
+                                type: string;
+                                minimum: number;
+                                description: string;
+                                "x-descriptionZh": string;
+                            };
+                            skipIfRich: {
+                                type: string;
+                                description: string;
+                                "x-descriptionZh": string;
+                            };
+                            width: {
+                                type: string;
+                                minimum: number;
+                                maximum: number;
+                                description: string;
+                                "x-descriptionZh": string;
+                            };
+                            height: {
+                                type: string;
+                                minimum: number;
+                                maximum: number;
+                                description: string;
+                                "x-descriptionZh": string;
+                            };
+                            backgroundColor: {
+                                type: string;
+                                description: string;
+                                "x-descriptionZh": string;
+                            };
+                            fontSize: {
+                                type: string;
+                                minimum: number;
+                                description: string;
+                                "x-descriptionZh": string;
+                            };
+                            color: {
+                                type: string;
+                                description: string;
+                                "x-descriptionZh": string;
+                            };
+                            padding: {
+                                type: string;
+                                minimum: number;
+                                description: string;
+                                "x-descriptionZh": string;
+                            };
+                            scale: {
+                                type: string;
+                                minimum: number;
+                                maximum: number;
+                                description: string;
+                                "x-descriptionZh": string;
+                            };
+                            fileName: {
+                                type: string;
+                                minLength: number;
+                                description: string;
+                                "x-descriptionZh": string;
+                            };
+                        };
+                    })[];
+                    description: string;
+                    "x-descriptionZh": string;
+                };
+            };
+        };
+        assistant: {
+            type: string;
+            additionalProperties: boolean;
+            description: string;
+            "x-descriptionZh": string;
+        };
+        log_level: {
+            type: string[];
+            description: string;
+            "x-descriptionZh": string;
+        };
+        plugin: {
+            type: string;
+            description: string;
+            "x-descriptionZh": string;
+        };
+    };
+    $defs: {
+        decisionTask: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                mode: {
+                    type: string;
+                    enum: string[];
+                };
+                timeoutMs: {
+                    type: string;
+                    minimum: number;
+                    maximum: number;
+                };
+                minConfidence: {
+                    type: string;
+                    minimum: number;
+                    maximum: number;
+                };
+                topK: {
+                    type: string;
+                    minimum: number;
+                    maximum: number;
+                };
+                maxCandidates: {
+                    type: string;
+                    minimum: number;
+                    maximum: number;
+                };
+                maxSelections: {
+                    type: string;
+                    minimum: number;
+                    maximum: number;
+                };
+            };
+        };
+    };
+};
 /** Host configuration keys consumed by Runtime composition and Host installers. */
 export declare const HOST_CONFIG_KEYS: readonly string[];
 export type JsonSchema = Readonly<Record<string, unknown>>;

package/lib/config-composer.js

@@ -10,7 +10,7 @@ function deepFreeze(value) {
     }
     return value;
 }
-const HOST_CONFIG_SCHEMA = deepFreeze(hostConfigSchema);
+export const HOST_CONFIG_SCHEMA = deepFreeze(hostConfigSchema);
 /** Host configuration keys consumed by Runtime composition and Host installers. */
 export const HOST_CONFIG_KEYS = Object.freeze(Object.keys(HOST_CONFIG_SCHEMA.properties));
 export class ConfigSchemaCollisionError extends Error {
@@ -57,6 +57,7 @@ export class ConfigComposer {
         // start-command, not Plugin ConfigViews.
         const effectiveSchema = Object.freeze({
             type: 'object',
+            $defs: HOST_CONFIG_SCHEMA.$defs,
             additionalProperties: false,
             properties: {
                 ...HOST_CONFIG_SCHEMA.properties,

package/lib/hmr-coordinator.js

@@ -1,3 +1,4 @@
+import { normalizeSourcePath } from './source-path.js';
 import { InvalidationPlanner, } from './invalidation-planner.js';
 export class HmrCoordinator {
     options;
@@ -31,11 +32,28 @@ export class HmrCoordinator {
         if (this.#stopResult)
             return this.#stopResult;
         this.#closing = true;
-        this.#unwatch?.();
+        const unwatch = this.#unwatch;
         this.#unwatch = undefined;
-        this.#stopResult = (async () => {
-            await this.#draining;
-        })();
+        this.#stopResult = Promise.resolve().then(async () => {
+            const errors = [];
+            try {
+                await unwatch?.();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+            // Watcher disposal failure must not bypass already admitted reloads.
+            try {
+                await this.#draining;
+            }
+            catch (error) {
+                errors.push(error);
+            }
+            if (errors.length === 1)
+                throw errors[0];
+            if (errors.length > 1)
+                throw new AggregateError(errors, 'HMR stop failed');
+        });
         return this.#stopResult;
     }
     enqueue(source) {
@@ -45,7 +63,7 @@ export class HmrCoordinator {
         if (this.#restartRequired) {
             return Promise.reject(new Error('HMR coordinator requires a process restart'));
         }
-        this.#pending.add(source);
+        this.#pending.add(normalizeSourcePath(source));
         const completed = new Promise((resolve, reject) => {
             this.#waiters.push({ resolve, reject });
         });

package/lib/host-config-schema.json

@@ -46,6 +46,21 @@
             "description": "Providers, Agents, sessions, memory, tools, and execution security.",
             "x-descriptionZh": "Provider、Agent、会话、记忆、工具与执行安全策略。",
             "properties": {
+                "decisions": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["provider"],
+                    "description": "Optional structured-decision service. Missing tasks are off; use shadow before active.",
+                    "x-descriptionZh": "可选的结构化决策服务。未配置的任务关闭；建议先用 shadow 验证。",
+                    "properties": {
+                        "provider": { "type": "string", "pattern": "^root(/[a-z0-9][a-z0-9-]*)+$", "description": "Exact enabled DecisionProvider Plugin owner, such as root/typesafe.", "x-descriptionZh": "提供已启用 DecisionProvider 的精确插件身份，例如 root/typesafe。" },
+                        "skills": { "$ref": "#/$defs/decisionTask" },
+                        "tools": { "$ref": "#/$defs/decisionTask" },
+                        "memory": { "$ref": "#/$defs/decisionTask" },
+                        "agents": { "$ref": "#/$defs/decisionTask" },
+                        "approval": { "$ref": "#/$defs/decisionTask" }
+                    }
+                },
                 "workroom": {
                     "type": "object",
                     "additionalProperties": true,
@@ -264,5 +279,20 @@
         "assistant": { "type": "object", "additionalProperties": true, "description": "Scheduled jobs, event ingress, and failure notifications.", "x-descriptionZh": "调度任务、事件入口和失败通知。" },
         "log_level": { "type": ["string", "number"], "description": "Runtime log level.", "x-descriptionZh": "Runtime 日志级别。" },
         "plugin": { "type": "object", "description": "Root Plugin configuration; replaced by its project schema during composition.", "x-descriptionZh": "Root Plugin 配置；组合时由项目 Schema 替换。" }
+    },
+    "$defs": {
+        "decisionTask": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["mode"],
+            "properties": {
+                "mode": { "type": "string", "enum": ["off", "shadow", "active"] },
+                "timeoutMs": { "type": "integer", "minimum": 1, "maximum": 2147483647 },
+                "minConfidence": { "type": "number", "minimum": 0, "maximum": 1 },
+                "topK": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 },
+                "maxCandidates": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 },
+                "maxSelections": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }
+            }
+        }
     }
 }

package/lib/invalidation-planner.js

@@ -1,4 +1,5 @@
-import { basename, resolve } from 'node:path';
+import { normalizeSourcePath } from './source-path.js';
+import { basename } from 'node:path';
 import { rootPluginId } from '@zhin.js/plugin-runtime';
 const processFiles = new Set([
     'pnpm-lock.yaml',
@@ -14,7 +15,7 @@ export class InvalidationPlanner {
         this.dependencies = dependencies;
     }
     plan(sources) {
-        const changed = unique(sources.map((source) => resolve(source)));
+        const changed = unique(sources.map((source) => normalizeSourcePath(source)));
         if (changed.some((source) => processFiles.has(basename(source)))) {
             return Object.freeze({
                 kind: 'process',
@@ -32,7 +33,7 @@ export class InvalidationPlanner {
             if (basename(source) === 'package.json') {
                 addManifestSource(manifestSources, reasons, source);
             }
-            const affected = unique([source, ...(this.dependencies?.affectedSources(source) ?? [])].map((item) => resolve(item)));
+            const affected = unique([source, ...(this.dependencies?.affectedSources(source) ?? [])].map((item) => normalizeSourcePath(item)));
             let matched = false;
             for (const item of affected) {
                 const records = this.ownership.recordsFor(item);
@@ -95,7 +96,7 @@ export class InvalidationPlanner {
     }
 }
 function addManifestSource(manifestSources, reasons, source) {
-    const manifest = resolve(source);
+    const manifest = normalizeSourcePath(source);
     manifestSources.add(manifest);
     reasons.add(`Manifest source changed: ${manifest}`);
 }

package/lib/module-dependency-index.js

@@ -1,3 +1,4 @@
+import { normalizeSourcePath } from './source-path.js';
 import { access, readFile } from 'node:fs/promises';
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -21,7 +22,7 @@ export class ModuleDependencyIndex {
     #commonJsByDirectory = new Map();
     #dirtyEntries = new Set();
     async analyze(entry) {
-        const normalized = resolve(entry);
+        const normalized = normalizeSourcePath(entry);
         const cached = this.#dependenciesByEntry.get(normalized);
         if (cached && !this.#dirtyEntries.has(normalized)) {
             return analysis(cached, this.#commonJsSourcesByEntry.get(normalized) ?? new Set());
@@ -34,7 +35,7 @@ export class ModuleDependencyIndex {
         return analysis(dependencies, commonJsSources);
     }
     commit(entry, result) {
-        const normalized = resolve(entry);
+        const normalized = normalizeSourcePath(entry);
         this.#remove(normalized);
         const dependencies = new Set(result.dependencies);
         const commonJsSources = new Set(result.commonJsSources);
@@ -50,7 +51,7 @@ export class ModuleDependencyIndex {
     }
     /** Marks the changed entry and every entry importing it for lazy re-analysis. */
     invalidate(source) {
-        const normalized = resolve(source);
+        const normalized = normalizeSourcePath(source);
         if (basename(normalized) === 'package.json') {
             this.#commonJsByDirectory.clear();
             const packageRoot = dirname(normalized);
@@ -69,7 +70,7 @@ export class ModuleDependencyIndex {
     }
     /** Drops entries that no longer belong to the successfully committed generation. */
     retain(entries) {
-        const active = new Set(entries.map((entry) => resolve(entry)));
+        const active = new Set(entries.map((entry) => normalizeSourcePath(entry)));
         for (const entry of this.#dependenciesByEntry.keys()) {
             if (!active.has(entry))
                 this.#remove(entry);
@@ -84,7 +85,7 @@ export class ModuleDependencyIndex {
         this.#dirtyEntries.clear();
     }
     hasCommonJsImpact(source) {
-        const normalized = resolve(source);
+        const normalized = normalizeSourcePath(source);
         if (isExplicitCommonJsSource(normalized))
             return true;
         if (this.#entriesByCommonJsSource.has(normalized))
@@ -92,7 +93,7 @@ export class ModuleDependencyIndex {
         return [...(this.#entriesByDependency.get(normalized) ?? [])].some((entry) => this.#commonJsSourcesByEntry.get(entry)?.has(entry) ?? false);
     }
     affectedSources(source) {
-        const normalized = resolve(source);
+        const normalized = normalizeSourcePath(source);
         const entries = [...(this.#entriesByDependency.get(normalized) ?? [])].sort();
         return Object.freeze([normalized, ...entries.filter((entry) => entry !== normalized)]);
     }
@@ -363,7 +364,7 @@ async function resolveLocalImport(importer, specifier) {
     }
     for (const candidate of importCandidates(requested)) {
         if (await exists(candidate))
-            return resolve(candidate);
+            return normalizeSourcePath(candidate);
     }
     return undefined;
 }

package/lib/native-development-runtime.js

@@ -1,3 +1,4 @@
+import { normalizeSourcePath } from './source-path.js';
 import { readdirSync, statSync, watch as watchDirectory, } from 'node:fs';
 import { basename, extname, isAbsolute, relative, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -29,14 +30,14 @@ export class NativeDevelopmentModuleRuntime {
     #closed = false;
     constructor(options) {
         ensureTypeScriptSpecifierRemap();
-        this.#projectRoot = resolve(options.projectRoot);
+        this.#projectRoot = normalizeSourcePath(options.projectRoot);
         this.#watchEnabled = options.watch ?? true;
         this.#tsxLoader = options.tsxLoader;
         this.#watchRoots = normalizeWatchRoots([this.#projectRoot]);
     }
     async load(source) {
         this.#assertOpen();
-        const normalized = resolve(source);
+        const normalized = normalizeSourcePath(source);
         if (isNativeTypeScriptSource(normalized))
             assertNativeTypeScriptSupport();
         const analysis = this.#pendingDependencies?.get(normalized)
@@ -67,7 +68,7 @@ export class NativeDevelopmentModuleRuntime {
         return this.#dependencies.affectedSources(source);
     }
     requiresProcessRestart(source) {
-        const normalized = resolve(source);
+        const normalized = normalizeSourcePath(source);
         const packageRoot = nearestWatchRoot(this.#watchRoots, normalized);
         // Installed packages and external paths are intentionally not watched.
         // The HMR coordinator turns this into a visible process restart reason.
@@ -353,7 +354,7 @@ function isNodeModulesSource(root, source) {
     return relative(root, source).split(sep).some((part) => part === 'node_modules');
 }
 function normalizeWatchRoots(roots) {
-    const sorted = [...new Set(roots.map((root) => resolve(root)))].sort((left, right) => left.length - right.length);
+    const sorted = [...new Set(roots.map((root) => normalizeSourcePath(root)))].sort((left, right) => left.length - right.length);
     return Object.freeze(sorted.filter((root, index) => !sorted.slice(0, index).some((parent) => isWithin(parent, root))));
 }
 function sameRoots(left, right) {

package/lib/plugin-scope-assembler.d.ts

@@ -1,4 +1,4 @@
-import { DisposeStack, Scope, type Dispose, type FeatureId, type GenerationHandoff, type GenerationAdmissionGate, type GenerationHandoffRegistry, type PluginId, type PluginNodeSnapshot, type SetupCapabilityRegistration, type TokenId } from '@zhin.js/plugin-runtime';
+import { DisposeStack, Scope, type Dispose, type FeatureId, type GenerationHandoff, type GenerationAdmissionGate, type GenerationHandoffRegistry, type RuntimeSnapshot, type PluginId, type PluginNodeSnapshot, type SetupCapabilityRegistration, type TokenId } from '@zhin.js/plugin-runtime';
 import { type RuntimeEnvironment } from './environment.js';
 import { type EnvironmentLayers } from './environment-store.js';
 import type { ModuleRuntime } from './module-runtime.js';
@@ -10,6 +10,8 @@ export type PluginConfigResolver = (node: PluginGraphNode) => unknown;
 export interface RootResourceContext {
     /** Exact shadow generation being assembled; never inferred from a latest snapshot. */
     readonly generation: number;
+    /** Exact projected candidate, available during handoff activation, never the committed previous generation. */
+    readonly readCandidateSnapshot?: () => RuntimeSnapshot;
     readonly signal: AbortSignal;
     readonly resources: Scope;
     readonly lifecycle: DisposeStack;
@@ -51,6 +53,7 @@ export declare class PluginScopeAssembler {
     setupTree(node: PluginGraphNode, signal: AbortSignal): Promise<void>;
     synchronizeTree(node: PluginGraphNode): void;
     createdScopeDisposers(): readonly (readonly [PluginId, Dispose])[];
+    bindCandidateSnapshot(snapshot: RuntimeSnapshot): void;
     generationHandoff(): GenerationHandoff | undefined;
     setupCapabilities(): readonly Readonly<SetupCapabilityRegistration>[];
     /** Root resources are process-owned; every Plugin Scope receives an owner-bound facade. */

package/lib/plugin-scope-assembler.js

@@ -21,6 +21,7 @@ export class PluginScopeAssembler {
     #handoffs = new GenerationHandoffStack();
     #admission = createGenerationAdmissionGate();
     #envStores;
+    #candidateSnapshot;
     #setupFeatureAliases = new Map();
     constructor(modules, configResolver, environment, primaryConfigDocument, generation, installResources, environmentLayers = {}, seed, isolation) {
         this.modules = modules;
@@ -71,6 +72,11 @@ export class PluginScopeAssembler {
             scope.provide(primaryConfigToken, config);
             await this.installResources?.({
                 generation: this.generation,
+                readCandidateSnapshot: () => {
+                    if (!this.#candidateSnapshot)
+                        throw new Error('Candidate snapshot is not projected yet');
+                    return this.#candidateSnapshot;
+                },
                 signal,
                 resources: scope,
                 lifecycle: scope.disposers,
@@ -206,6 +212,12 @@ export class PluginScopeAssembler {
             return [owner, () => scope.disposers.dispose()];
         });
     }
+    bindCandidateSnapshot(snapshot) {
+        if (snapshot.generation !== this.generation || this.#candidateSnapshot) {
+            throw new Error('Candidate snapshot does not match this Plugin assembly');
+        }
+        this.#candidateSnapshot = snapshot;
+    }
     generationHandoff() {
         return this.#handoffs.seal();
     }

package/lib/root-runtime.js

@@ -1,3 +1,4 @@
+import { normalizeSourcePath } from './source-path.js';
 import { resolve } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { DisposeStack, GenerationHandoffStack, RootController, ConfigDocumentDivergenceError, createSnapshotView, rootPluginId, } from '@zhin.js/plugin-runtime';
@@ -41,7 +42,7 @@ export class RootRuntime {
     #controller;
     #disabledPluginInstanceKeys;
     constructor(options) {
-        this.#projectRoot = resolve(options.projectRoot);
+        this.#projectRoot = normalizeSourcePath(options.projectRoot);
         this.#modules = options.modules;
         this.#environment = defineRuntimeEnvironment(options.environment);
         this.#environmentLayers = defineEnvironmentLayers(options.environmentVariables);
@@ -55,7 +56,7 @@ export class RootRuntime {
         this.#runtimeInputSources = new Set([
             ...(this.#configPort?.sources ?? []),
             ...(this.#environmentSource?.sources ?? []),
-        ].map((source) => resolve(source)));
+        ].map((source) => normalizeSourcePath(source)));
         this.#installResources = options.installResources;
         this.#isolation = options.isolation;
         this.#disabledPluginInstanceKeys = Object.freeze([...(options.disabledPluginInstanceKeys ?? [])]);
@@ -105,7 +106,7 @@ export class RootRuntime {
             modules: this.#modules,
             ownership: () => this.sourceOwnership,
             runtime: {
-                handlesSource: (source) => this.#runtimeInputSources.has(resolve(source)),
+                handlesSource: (source) => this.#runtimeInputSources.has(normalizeSourcePath(source)),
                 reload: async (plan) => {
                     const result = await this.#reloadPlan(plan);
                     return isProcessPlan(result) ? result : undefined;
@@ -139,7 +140,7 @@ export class RootRuntime {
             ? Object.freeze({
                 ...plan,
                 subtrees: collapseInvalidationSubtrees([...plan.subtrees, ...inputs.roots]),
-                fallbacks: Object.freeze(plan.fallbacks.filter((fallback) => !inputs.inputSources.has(resolve(fallback.source)))),
+                fallbacks: Object.freeze(plan.fallbacks.filter((fallback) => !inputs.inputSources.has(normalizeSourcePath(fallback.source)))),
             })
             : plan;
         let restart;
@@ -189,11 +190,11 @@ export class RootRuntime {
         return this.#controller.committed.state.model;
     }
     async #planRuntimeInputs(changed) {
-        const inputSources = new Set(changed.map((source) => resolve(source)).filter((source) => this.#runtimeInputSources.has(source)));
+        const inputSources = new Set(changed.map((source) => normalizeSourcePath(source)).filter((source) => this.#runtimeInputSources.has(source)));
         if (inputSources.size === 0 || !this.#model)
             return undefined;
-        const configChanged = this.#configPort?.sources?.some((source) => inputSources.has(resolve(source))) ?? false;
-        const environmentChanged = this.#environmentSource?.sources.some((source) => inputSources.has(resolve(source))) ?? false;
+        const configChanged = this.#configPort?.sources?.some((source) => inputSources.has(normalizeSourcePath(source))) ?? false;
+        const environmentChanged = this.#environmentSource?.sources.some((source) => inputSources.has(normalizeSourcePath(source))) ?? false;
         const configSnapshot = configChanged ? await this.#configPort?.read() : undefined;
         const document = configSnapshot?.document ?? requireConfigDocument(this.#configDocument);
         const environmentLayers = environmentChanged && this.#environmentSource
@@ -210,7 +211,7 @@ export class RootRuntime {
         if (inputPlan.hostKeys.length > 0) {
             return Object.freeze({
                 kind: 'process',
-                changed: Object.freeze([...changed].map((source) => resolve(source))),
+                changed: Object.freeze([...changed].map((source) => normalizeSourcePath(source))),
                 reasons: Object.freeze(inputPlan.hostKeys.map((key) => `Host configuration changed: ${key}`)),
             });
         }
@@ -263,7 +264,7 @@ export class RootRuntime {
         if (plan.subtrees.length === 0 || plan.subtrees.includes(rootPluginId()))
             return false;
         return plan.changed.every((source) => {
-            if (this.#runtimeInputSources.has(resolve(source)))
+            if (this.#runtimeInputSources.has(normalizeSourcePath(source)))
                 return true;
             const records = this.sourceOwnership.recordsFor(source);
             return records.length > 0 && records.every((record) => record.role === 'plugin' || record.role === 'schema');
@@ -519,6 +520,7 @@ class GenerationAssembler {
             }
             const state = projected.state;
             const snapshot = createSnapshotView(this.generation, state);
+            this.#plugins.bindCandidateSnapshot(snapshot);
             const ownership = SourceOwnershipIndex.fromGeneration(this.graph, snapshot, this.#featureIdsByPackageRoot);
             const assets = GenerationAssets.create(this.#plugins.createdScopeDisposers(), this.#projectionDisposers);
             return prepareRuntimeGeneration({

package/lib/source-ownership.js

@@ -1,3 +1,4 @@
+import { normalizeSourcePath } from './source-path.js';
 import { isAbsolute, relative, resolve } from 'node:path';
 export class SourceOwnershipIndex {
     #records = new Map();
@@ -102,7 +103,7 @@ export class SourceOwnershipIndex {
         return Object.freeze([...this.#watchRoots.values()]);
     }
     addWatchRoot(root) {
-        const normalized = resolve(root.root);
+        const normalized = normalizeSourcePath(root.root);
         this.#watchRoots.set(normalized, Object.freeze({ ...root, root: normalized }));
     }
 }
@@ -112,7 +113,7 @@ function visitPlugin(node, visit) {
         visitPlugin(child, visit);
 }
 function normalizeSource(source) {
-    return resolve(source);
+    return normalizeSourcePath(source);
 }
 function contains(packageRoot, source) {
     const path = relative(packageRoot, source);

package/lib/source-path.d.ts

@@ -0,0 +1,4 @@
+/** Keep file events and scanned sources in the same physical path namespace.
+ * Resolve the nearest existing parent for unlink events and newly added files.
+ */
+export declare function normalizeSourcePath(source: string): string;

package/lib/source-path.js

@@ -0,0 +1,25 @@
+import { realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+/** Keep file events and scanned sources in the same physical path namespace.
+ * Resolve the nearest existing parent for unlink events and newly added files.
+ */
+export function normalizeSourcePath(source) {
+    const absolute = resolve(source);
+    let parent = absolute;
+    const suffix = [];
+    for (;;) {
+        try {
+            return join(realpathSync(parent), ...suffix);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR')
+                throw error;
+            const next = dirname(parent);
+            if (next === parent)
+                return absolute;
+            suffix.unshift(basename(parent));
+            parent = next;
+        }
+    }
+}

package/lib/subtree-generation-preparer.js

@@ -82,6 +82,7 @@ export class SubtreeGenerationPreparer {
                 projectionDisposers.set(feature, dispose);
             }
             const snapshot = createSnapshotView(current.generation + 1, projected.state);
+            plugins.bindCandidateSnapshot(snapshot);
             const ownership = SourceOwnershipIndex.fromGeneration(this.graph, snapshot, this.model.featureIdsByPackageRoot);
             const replacements = new Map(plugins.createdScopeDisposers());
             // Local prepare still commits a complete immutable generation. The

package/lib/topology-generation-preparer.js

@@ -89,6 +89,7 @@ export class TopologyGenerationPreparer {
                 projectionDisposers.set(feature, dispose);
             }
             const snapshot = createSnapshotView(current.generation + 1, projected.state);
+            plugins.bindCandidateSnapshot(snapshot);
             const ownership = SourceOwnershipIndex.fromGeneration(this.graph, snapshot, featureTopology.featureIdsByPackageRoot);
             const replacements = new Map(plugins.createdScopeDisposers());
             const assets = this.model.assets.replaceScopes(graphOrder(this.graph), replacements, projectionDisposers);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/runtime",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Static Plugin graph, generation transaction and HMR Root runtime for Zhin.js",
   "type": "module",
   "main": "./lib/index.js",
@@ -20,24 +20,24 @@
     "es-module-lexer": "2.3.1",
     "import-meta-resolve": "4.2.0",
     "semver": "7.8.5",
-    "@zhin.js/feature-kit": "1.1.2",
-    "@zhin.js/plugin-runtime": "1.1.11"
+    "@zhin.js/plugin-runtime": "1.1.12",
+    "@zhin.js/feature-kit": "1.1.3"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
     "tsx": "^4.23.1",
     "typescript": "^6.0.3",
-    "@zhin.js/adapter": "1.1.15",
-    "@zhin.js/agent-feature": "1.1.2",
-    "@zhin.js/command": "1.1.3",
-    "@zhin.js/component": "1.1.2",
-    "@zhin.js/layout": "1.1.3",
-    "@zhin.js/mcp-feature": "1.1.2",
-    "@zhin.js/middleware": "1.1.2",
-    "@zhin.js/prompt-section": "1.1.2",
-    "@zhin.js/page": "1.1.3",
-    "@zhin.js/tool": "1.1.2",
-    "@zhin.js/skill": "1.1.2"
+    "@zhin.js/adapter": "1.1.17",
+    "@zhin.js/agent-feature": "1.1.4",
+    "@zhin.js/command": "1.1.5",
+    "@zhin.js/component": "1.1.4",
+    "@zhin.js/layout": "1.1.4",
+    "@zhin.js/mcp-feature": "1.1.4",
+    "@zhin.js/middleware": "1.1.4",
+    "@zhin.js/page": "1.1.4",
+    "@zhin.js/prompt-section": "1.1.3",
+    "@zhin.js/skill": "1.1.4",
+    "@zhin.js/tool": "1.1.4"
   },
   "repository": {
     "type": "git",