@avantf/dsh-plugin-base 0.3.1 → 0.4.1

package/dist/kit/prompt_files.js

@@ -1,5 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+/** A legal namespace: lowercase kebab-case, starting with a letter. */
+const NAMESPACE_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 /** The temp files {@link nodeIo.write} leaves beside a prompt file, and the age past which one
  *  certainly belongs to a writer that will never rename it. Same discipline as the provisioner's
  *  `fs.ts`, which sweeps `.atomic-*` the same way. */
@@ -62,13 +64,41 @@ function reason(error) {
 }
 export class PromptFiles {
     dir;
+    /** The validated namespace prefix, or `undefined` (pre-v3 behaviour: no prefix check). */
+    namespace;
+    /** Set when `namespace` was supplied but illegal; every `load` then degrades without touching disk. */
+    namespaceError;
     logger;
     io;
     constructor(options) {
+        if (options.namespace !== undefined && !NAMESPACE_PATTERN.test(options.namespace)) {
+            // A caller bug, not an environment failure. It must not throw (this module never throws — a
+            // throwing apply can fail a host boot), but it must also not fall back to "no prefix check",
+            // which would silently re-open the takeover hole. So the instance refuses to touch the prompt
+            // directory at all and warns on every load.
+            this.namespaceError = `PromptFiles: namespace ${JSON.stringify(options.namespace)} is not a legal prefix; expected lowercase kebab-case matching ${String(NAMESPACE_PATTERN)}`;
+            this.namespace = undefined;
+        }
+        else {
+            this.namespaceError = undefined;
+            this.namespace = options.namespace;
+        }
         this.dir = options.dir;
         this.logger = options.logger;
         this.io = options.io ?? nodeIo;
     }
+    /**
+     * Whether `file` belongs to this instance's namespace. `true` when no namespace was given (the
+     * legacy contract: the caller owns the whole directory naming convention as before).
+     */
+    ownsFile(file) {
+        const prefix = this.namespace;
+        if (prefix === undefined)
+            return true;
+        if (!file.startsWith(`${prefix}-`))
+            return false;
+        return !file.includes('/') && !file.includes('\\');
+    }
     /**
      * Ensure every spec's file exists with content, then return the text to inject. Ordered like the
      * manifest, so the caller can zip the result back onto its sections.
@@ -81,6 +111,21 @@ export class PromptFiles {
             source: 'default',
             wrote: false,
         });
+        if (this.namespaceError !== undefined) {
+            this.logger?.warn(`${this.namespaceError}; using the built-in defaults and not touching the prompt directory`);
+            return specs.map(fallbackOf);
+        }
+        if (this.namespace !== undefined && specs.some((spec) => !this.ownsFile(spec.file))) {
+            // Never touch disk for the offending spec: the whole point of the namespace is that a mistyped
+            // prefix must not read or write a file another plugin's user owns. Warn per offending file and
+            // degrade to the caller's fallback, exactly like the unusable-directory path.
+            for (const spec of specs) {
+                if (!this.ownsFile(spec.file)) {
+                    this.logger?.warn(`prompt file ${spec.file} is outside the "${this.namespace}-" namespace; using the built-in default and not touching the prompt directory`);
+                }
+            }
+            return specs.map((spec) => (this.ownsFile(spec.file) ? this.loadOne(spec) : fallbackOf(spec)));
+        }
         try {
             this.io.ensureDir(this.dir);
         }

package/dist/kit/typert.d.ts

@@ -4,7 +4,7 @@
  * A DSH plugin's Remote face is hand-written here (the Typert generator runs only inside the harness
  * workspace), and both plugins independently arrived at the same conventions. The GENERATOR-level
  * parts live here once; the descriptor assembly stays per plugin because the two really differ (the
- * work engine adds `stream`/cancellation methods, the memory plugin has a `parameter()` helper with
+ * mission engine adds `stream`/cancellation methods, the memory plugin has a `parameter()` helper with
  * `acceptsUndefined`). Only the genuinely identical part is hoisted — a fake abstraction with a bag
  * of switches would be worse than the duplication it removes.
  *
@@ -20,7 +20,7 @@ import type { ZodType } from 'zod';
  * Carries BOTH members on purpose. The host's validator moved from `codec.schema.parse` (dsh 0.1.5)
  * to `codec.create()` (0.1.6), and each generation checks only its own — so a codec missing one of
  * them makes a healthy host read as an incompatible one, and the failure shows up as a REFUSED mount
- * rather than as a missing neighbour. Measured on the memory plugin first; the work copy had drifted
+ * rather than as a missing neighbour. Measured on the memory plugin first; the mission copy had drifted
  * to the one-member shape and was fixed to match. Do not "simplify" this back.
  */
 export interface StrictCodec {

package/dist/kit/wellformed.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Well-formed text — the ONE repair for the family's single worst serialization defect, a LONE
+ * SURROGATE.
+ *
+ * The defect has exactly one shape: a UTF-16 code unit in `D800–DFFF` with no partner (an unpaired
+ * high half, an unpaired low half, or half of an emoji). Such a string is not a valid Unicode scalar
+ * sequence, yet `JSON.stringify` emits it verbatim as the escape `"\ud800"`. JavaScript's own
+ * `JSON.parse` accepts that, so EVERY test in this repository passes while a strict parser rejects the
+ * whole document — measured, not theorized:
+ *
+ *   - `printf '"\\ud800"' | jq .` → `jq: parse error: Invalid \uXXXX\uXXXX surrogate pair escape`;
+ *   - Python's `json.load` accepts the document but `print` raises
+ *     `UnicodeEncodeError: surrogates not allowed`;
+ *   - the same half-code-unit also poisons FTS indexes, embeddings and the UI.
+ *
+ * The repair is `String.prototype.toWellFormed()` (Node ≥20, present in this repo's Node ≥22.15): it
+ * replaces each lone surrogate with U+FFFD (`�`). {@link wellFormedText} uses the engine's own
+ * implementation when it exists and an EQUIVALENT `charCodeAt` scan when it does not, so an older Node
+ * degrades in behaviour, never in availability ({@link scanAndRepair}).
+ *
+ * WHERE this belongs — the two boundaries where a model can see a string:
+ *
+ *   - the INBOUND boundary, before a caller-supplied string is persisted or indexed (store writes,
+ *     entity names, caller paths);
+ *   - the OUTBOUND boundary, before a value is serialized for a model (tool results, JSON payloads,
+ *     rendered records).
+ *
+ * This module is well-formedness ONLY, deliberately: it repairs lone surrogates and touches nothing
+ * else. Unicode normalization (`normalize('NFC')`) is a PERSISTENCE policy — "two spellings of the
+ * same text must not become two rows / two FTS terms" — and stays with the caller that owns that
+ * policy (mem's write entry layers it on top of {@link wellFormedText}); applying it here to data this
+ * process did not just write would silently rewrite history for display.
+ *
+ * Both members are PURE and type-preserving: same input, same output, no I/O, no global state, and
+ * every non-string value comes back untouched (see {@link wellFormedDeep}). They are part of the shared
+ * kit so one base release fixes every consumer; a plugin that cannot reach the base keeps a local
+ * fallback copy as its documented degradation path (root `AGENTS.md`).
+ *
+ * @module @avantf/dsh-plugin-base/kit/wellformed
+ */
+/**
+ * Make ONE string well-formed: every lone surrogate becomes U+FFFD, every properly paired surrogate
+ * (a complete emoji, a CJK Extension B character) and every other code point is returned unchanged.
+ *
+ * Uses the engine's `String.prototype.toWellFormed()` when available and {@link scanAndRepair}
+ * otherwise; both produce the same result, so a pre-ES2024 Node never throws here.
+ *
+ * Idempotent (`wellFormedText(wellFormedText(x)) === wellFormedText(x)`) and pure — no I/O, no
+ * mutation, no normalization: quotes, backslashes, newlines and tabs come back byte-for-byte.
+ *
+ * @param text - the string to repair; anything else is the caller's type error (see the recursive
+ * {@link wellFormedDeep}, which leaves non-strings alone).
+ */
+export declare function wellFormedText(text: string): string;
+/**
+ * {@link wellFormedText} over a JSON-shaped value, so a whole result can be handed to a strict parser.
+ *
+ * Recursion rules, deliberately narrow — this member may repair strings but must never change a
+ * value's TYPE:
+ *
+ *  - strings are repaired with {@link wellFormedText};
+ *  - arrays are mapped (a new array; the input is never mutated);
+ *  - PLAIN records are rebuilt with well-formed keys and values. "Plain" means the prototype is
+ *    `Object.prototype` (an object literal) or `null` (`Object.create(null)`), and the object carries
+ *    no `toJSON` custom serialization. Object KEYS are repaired too: `JSON.stringify` emits a lone
+ *    surrogate in a property name verbatim, which breaks a strict parser exactly the same way, and a
+ *    replacer cannot fix keys, which is why this clones;
+ *  - EVERYTHING ELSE — numbers, booleans, `null`, `undefined`, bigints, symbols, functions, and every
+ *    object that is not a plain record (`Date`, `RegExp`, `Map`, a class instance, anything with a
+ *    `toJSON`) — is returned AS-IS, by identity. A `Date` must not become `{}`, which is what cloning
+ *    its enumerable properties would do, and a class instance must not lose its prototype.
+ *
+ * Pure and type-preserving: the result is structurally identical to the input apart from lone
+ * surrogates, and the input value is never mutated.
+ *
+ * @param value - the JSON-shaped value to repair.
+ */
+export declare function wellFormedDeep<T>(value: T): T;
+//# sourceMappingURL=wellformed.d.ts.map

package/dist/kit/wellformed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wellformed.d.ts","sourceRoot":"","sources":["../../src/kit/wellformed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAsDH;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAInD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAS7C"}

package/dist/kit/wellformed.js

@@ -0,0 +1,155 @@
+/**
+ * Well-formed text — the ONE repair for the family's single worst serialization defect, a LONE
+ * SURROGATE.
+ *
+ * The defect has exactly one shape: a UTF-16 code unit in `D800–DFFF` with no partner (an unpaired
+ * high half, an unpaired low half, or half of an emoji). Such a string is not a valid Unicode scalar
+ * sequence, yet `JSON.stringify` emits it verbatim as the escape `"\ud800"`. JavaScript's own
+ * `JSON.parse` accepts that, so EVERY test in this repository passes while a strict parser rejects the
+ * whole document — measured, not theorized:
+ *
+ *   - `printf '"\\ud800"' | jq .` → `jq: parse error: Invalid \uXXXX\uXXXX surrogate pair escape`;
+ *   - Python's `json.load` accepts the document but `print` raises
+ *     `UnicodeEncodeError: surrogates not allowed`;
+ *   - the same half-code-unit also poisons FTS indexes, embeddings and the UI.
+ *
+ * The repair is `String.prototype.toWellFormed()` (Node ≥20, present in this repo's Node ≥22.15): it
+ * replaces each lone surrogate with U+FFFD (`�`). {@link wellFormedText} uses the engine's own
+ * implementation when it exists and an EQUIVALENT `charCodeAt` scan when it does not, so an older Node
+ * degrades in behaviour, never in availability ({@link scanAndRepair}).
+ *
+ * WHERE this belongs — the two boundaries where a model can see a string:
+ *
+ *   - the INBOUND boundary, before a caller-supplied string is persisted or indexed (store writes,
+ *     entity names, caller paths);
+ *   - the OUTBOUND boundary, before a value is serialized for a model (tool results, JSON payloads,
+ *     rendered records).
+ *
+ * This module is well-formedness ONLY, deliberately: it repairs lone surrogates and touches nothing
+ * else. Unicode normalization (`normalize('NFC')`) is a PERSISTENCE policy — "two spellings of the
+ * same text must not become two rows / two FTS terms" — and stays with the caller that owns that
+ * policy (mem's write entry layers it on top of {@link wellFormedText}); applying it here to data this
+ * process did not just write would silently rewrite history for display.
+ *
+ * Both members are PURE and type-preserving: same input, same output, no I/O, no global state, and
+ * every non-string value comes back untouched (see {@link wellFormedDeep}). They are part of the shared
+ * kit so one base release fixes every consumer; a plugin that cannot reach the base keeps a local
+ * fallback copy as its documented degradation path (root `AGENTS.md`).
+ *
+ * @module @avantf/dsh-plugin-base/kit/wellformed
+ */
+/** U+FFFD REPLACEMENT CHARACTER: what a lone surrogate becomes. */
+const REPLACEMENT = '\uFFFD';
+/** A high surrogate: the FIRST half of an astral pair (`D800–DBFF`). */
+const HIGH_MIN = 0xd800;
+const HIGH_MAX = 0xdbff;
+/** A low surrogate: the SECOND half of an astral pair (`DC00–DFFF`). */
+const LOW_MIN = 0xdc00;
+const LOW_MAX = 0xdfff;
+/** The engine's own `String.prototype.toWellFormed`, or `undefined` (a pre-ES2024 runtime). */
+function nativeToWellFormed() {
+    try {
+        // Typed loosely on purpose: the repo compiles against `lib: es2023` (this must also run on older
+        // Node), so the ES2024 member is read structurally rather than named.
+        const candidate = String.prototype.toWellFormed;
+        return typeof candidate === 'function' ? candidate : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The local equivalent of `String.prototype.toWellFormed()`: one `charCodeAt` pass that copies paired
+ * code units as-is and substitutes U+FFFD for each unpaired one. Not exported — it is the fallback of
+ * {@link wellFormedText}, and its behaviour is pinned by the same assertions as the native path (the
+ * test deletes `String.prototype.toWellFormed`, so both paths run the identical expectations).
+ */
+function scanAndRepair(text) {
+    let out = '';
+    for (let index = 0; index < text.length; index += 1) {
+        const unit = text.charCodeAt(index);
+        if (unit >= HIGH_MIN && unit <= HIGH_MAX) {
+            const next = index + 1 < text.length ? text.charCodeAt(index + 1) : -1;
+            if (next >= LOW_MIN && next <= LOW_MAX) {
+                out += text.slice(index, index + 2); // a real pair: both units, unchanged
+                index += 1;
+                continue;
+            }
+            out += REPLACEMENT; // unpaired high: no low half follows
+            continue;
+        }
+        if (unit >= LOW_MIN && unit <= LOW_MAX) {
+            out += REPLACEMENT; // unpaired low: no high half preceded it (a paired one was consumed above)
+            continue;
+        }
+        out += text.slice(index, index + 1);
+    }
+    return out;
+}
+/**
+ * Make ONE string well-formed: every lone surrogate becomes U+FFFD, every properly paired surrogate
+ * (a complete emoji, a CJK Extension B character) and every other code point is returned unchanged.
+ *
+ * Uses the engine's `String.prototype.toWellFormed()` when available and {@link scanAndRepair}
+ * otherwise; both produce the same result, so a pre-ES2024 Node never throws here.
+ *
+ * Idempotent (`wellFormedText(wellFormedText(x)) === wellFormedText(x)`) and pure — no I/O, no
+ * mutation, no normalization: quotes, backslashes, newlines and tabs come back byte-for-byte.
+ *
+ * @param text - the string to repair; anything else is the caller's type error (see the recursive
+ * {@link wellFormedDeep}, which leaves non-strings alone).
+ */
+export function wellFormedText(text) {
+    const native = nativeToWellFormed();
+    if (native !== undefined)
+        return native.call(text);
+    return scanAndRepair(text);
+}
+/**
+ * {@link wellFormedText} over a JSON-shaped value, so a whole result can be handed to a strict parser.
+ *
+ * Recursion rules, deliberately narrow — this member may repair strings but must never change a
+ * value's TYPE:
+ *
+ *  - strings are repaired with {@link wellFormedText};
+ *  - arrays are mapped (a new array; the input is never mutated);
+ *  - PLAIN records are rebuilt with well-formed keys and values. "Plain" means the prototype is
+ *    `Object.prototype` (an object literal) or `null` (`Object.create(null)`), and the object carries
+ *    no `toJSON` custom serialization. Object KEYS are repaired too: `JSON.stringify` emits a lone
+ *    surrogate in a property name verbatim, which breaks a strict parser exactly the same way, and a
+ *    replacer cannot fix keys, which is why this clones;
+ *  - EVERYTHING ELSE — numbers, booleans, `null`, `undefined`, bigints, symbols, functions, and every
+ *    object that is not a plain record (`Date`, `RegExp`, `Map`, a class instance, anything with a
+ *    `toJSON`) — is returned AS-IS, by identity. A `Date` must not become `{}`, which is what cloning
+ *    its enumerable properties would do, and a class instance must not lose its prototype.
+ *
+ * Pure and type-preserving: the result is structurally identical to the input apart from lone
+ * surrogates, and the input value is never mutated.
+ *
+ * @param value - the JSON-shaped value to repair.
+ */
+export function wellFormedDeep(value) {
+    if (typeof value === 'string')
+        return wellFormedText(value);
+    if (Array.isArray(value))
+        return value.map((item) => wellFormedDeep(item));
+    if (value !== null && typeof value === 'object' && isPlainRecord(value)) {
+        const out = {};
+        for (const [key, item] of Object.entries(value))
+            out[wellFormedText(key)] = wellFormedDeep(item);
+        return out;
+    }
+    return value;
+}
+/**
+ * Whether `value` is a JSON-shaped plain record: an object literal (`Object.prototype`) or a
+ * null-prototype map (`Object.create(null)`), with no `toJSON` custom serialization. Everything else
+ * is a different type and is left alone — see {@link wellFormedDeep}.
+ */
+function isPlainRecord(value) {
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null)
+        return false;
+    return typeof value.toJSON !== 'function';
+}
+//# sourceMappingURL=wellformed.js.map

package/dist/layout.d.ts

@@ -17,8 +17,23 @@ export declare function quarantineRoot(home: string): string;
 export declare function stagingDir(home: string, itemId: string, sequence: number): string;
 /** A quarantine directory for one bad version directory. */
 export declare function quarantineDir(home: string, sequence: number): string;
-/** Is `child` inside `parent` (or equal to it)? Both are absolute and already normalised. */
-export declare function isInside(parent: string, child: string): boolean;
+/** The platform slice {@link isInside} needs; injected so win32 semantics are testable on Linux. */
+export interface PathSemantics {
+    parse(path: string): {
+        readonly root: string;
+    };
+    relative(from: string, to: string): string;
+    readonly sep: string;
+}
+/**
+ * Is `child` inside `parent` (or equal to it)? Both are absolute and already normalised.
+ *
+ * The root comparison comes FIRST and is what makes this fail-closed on Windows: `win32.relative`
+ * answers a cross-drive/UNC pair with the other drive's absolute path (`D:\evil\x`), which does not
+ * start with `..`, so a bare relative check called every cross-root path "inside". `pathImpl` is a
+ * parameter only so the win32 branch is exercised from Linux; callers pass nothing.
+ */
+export declare function isInside(parent: string, child: string, pathImpl?: PathSemantics): boolean;
 /** Reject a `target.root` that is absolute or escapes `home` (`invalid-option`). */
 export declare function assertSafeRelativeRoot(root: string): void;
 /** Reject a provider-supplied relative path that is absolute or escapes its root. */

package/dist/layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"AAQA,qDAAqD;AACrD,eAAO,MAAM,WAAW,aAAa,CAAA;AAErC,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,MAAM,CAAA;AAEnC,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AACD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AACD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AACD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AACD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AACD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AACD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AACD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGjF;AAED,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,6FAA6F;AAC7F,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAG/D;AAED,oFAAoF;AACpF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAQzD;AAED,qFAAqF;AACrF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAQzD;AAED,mFAAmF;AACnF,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,aAAa,GAAE,MAAyB,GACvC,MAAM,CAOR"}
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"AAQA,qDAAqD;AACrD,eAAO,MAAM,WAAW,aAAa,CAAA;AAErC,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,MAAM,CAAA;AAEnC,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AACD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AACD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AACD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AACD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AACD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AACD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AACD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGjF;AAED,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,oGAAoG;AACpG,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;IAC1C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,aAAwC,GAAG,OAAO,CAKnH;AAED,oFAAoF;AACpF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAQzD;AAED,qFAAqF;AACrF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAQzD;AAED,mFAAmF;AACnF,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,aAAa,GAAE,MAAyB,GACvC,MAAM,CAOR"}

package/dist/layout.js

@@ -3,7 +3,7 @@
  * @module layout
  */
 import { createHash } from 'node:crypto';
-import { join, relative, sep } from 'node:path';
+import { join, parse, relative, sep } from 'node:path';
 import { ProvisionError } from './errors.js';
 /** The control-plane directory name under `home`. */
 export const CONTROL_DIR = '.envinit';
@@ -45,10 +45,20 @@ export function stagingDir(home, itemId, sequence) {
 export function quarantineDir(home, sequence) {
     return join(quarantineRoot(home), `${String(Date.now())}-${String(process.pid)}-${String(sequence)}`);
 }
-/** Is `child` inside `parent` (or equal to it)? Both are absolute and already normalised. */
-export function isInside(parent, child) {
-    const rel = relative(parent, child);
-    return rel === '' || (!rel.startsWith('..') && !rel.startsWith(`..${sep}`));
+/**
+ * Is `child` inside `parent` (or equal to it)? Both are absolute and already normalised.
+ *
+ * The root comparison comes FIRST and is what makes this fail-closed on Windows: `win32.relative`
+ * answers a cross-drive/UNC pair with the other drive's absolute path (`D:\evil\x`), which does not
+ * start with `..`, so a bare relative check called every cross-root path "inside". `pathImpl` is a
+ * parameter only so the win32 branch is exercised from Linux; callers pass nothing.
+ */
+export function isInside(parent, child, pathImpl = { parse, relative, sep }) {
+    // Windows drive letters and UNC shares are case-insensitive; lowercasing a POSIX root is a no-op.
+    if (pathImpl.parse(parent).root.toLowerCase() !== pathImpl.parse(child).root.toLowerCase())
+        return false;
+    const rel = pathImpl.relative(parent, child);
+    return rel === '' || (!rel.startsWith('..') && !rel.startsWith(`..${pathImpl.sep}`));
 }
 /** Reject a `target.root` that is absolute or escapes `home` (`invalid-option`). */
 export function assertSafeRelativeRoot(root) {

package/dist/lint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../src/lint.ts"],"names":[],"mappings":"AASA,mDAAmD;AACnD,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAAsF,CAAA;AAEjI,uCAAuC;AACvC,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAAgB,CAAA;AAErE,0EAA0E;AAC1E,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAA8C,CAAA;AAErG,+EAA+E;AAC/E,eAAO,MAAM,mCAAmC,EAAE,SAAS,MAAM,EAMhE,CAAA;AAED,oFAAoF;AACpF,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAAoC,CAAA;AAEjF,oCAAoC;AACpC,eAAO,MAAM,WAAW,EAAE,SAAS,MAAM,EAUxC,CAAA;AAED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,CAGzF;AAED,MAAM,WAAW,WAAW;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAA;CAC1C;AAUD,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAIpD;AAED,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAqDD,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,QAAQ,EAAE,OAAO,GAAG,UAAU,CAgJ1D;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CASzD"}
+{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../src/lint.ts"],"names":[],"mappings":"AASA,mDAAmD;AACnD,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAAsF,CAAA;AAEjI,uCAAuC;AACvC,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAA6B,CAAA;AAElF,0EAA0E;AAC1E,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAAiC,CAAA;AAExF,+EAA+E;AAC/E,eAAO,MAAM,mCAAmC,EAAE,SAAS,MAAM,EAMhE,CAAA;AAED,oFAAoF;AACpF,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAAoC,CAAA;AAEjF,oCAAoC;AACpC,eAAO,MAAM,WAAW,EAAE,SAAS,MAAM,EAUxC,CAAA;AAED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,CAGzF;AAED,MAAM,WAAW,WAAW;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAA;CAC1C;AAUD,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAIpD;AAED,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAqDD,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,QAAQ,EAAE,OAAO,GAAG,UAAU,CAgJ1D;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CASzD"}

package/dist/lint.js

@@ -8,9 +8,9 @@ import { assertRange } from './semver.js';
 /** The built-in kinds whose names are reserved. */
 export const BUILTIN_KINDS = ['npm-package', 'binary-archive', 'model-cache'];
 /** Item policy keys the core reads. */
-export const IMPLEMENTED_POLICY_KEYS = ['mirrors'];
+export const IMPLEMENTED_POLICY_KEYS = ['mirrors', 'timeoutMs'];
 /** Item policy keys the surface declares but this build does not read. */
-export const UNIMPLEMENTED_POLICY_KEYS = ['concurrency', 'timeoutMs', 'platforms'];
+export const UNIMPLEMENTED_POLICY_KEYS = ['concurrency', 'platforms'];
 /** Provision-policy keys the surface declares but this build does not read. */
 export const UNIMPLEMENTED_PROVISION_POLICY_KEYS = [
     'packumentMirrors',

package/dist/lock.d.ts

@@ -1,4 +1,15 @@
 import type { ProvisionLock } from './types.js';
+/** What a waiter observed when it refused to reclaim a lock whose holder is still alive. */
+export interface SlowHoldInfo {
+    readonly path: string;
+    readonly pid: number;
+    readonly startedAt: number;
+    /** How old the lock file's mtime already is — the value that crossed `staleMs`. */
+    readonly heldMs: number;
+    readonly staleMs: number;
+    /** How long this `acquire()` call has been waiting so far. */
+    readonly waitedMs: number;
+}
 /** `true` when the pid exists; `EPERM` counts as alive. */
 export declare function pidIsAlive(pid: number): boolean;
 export interface DefaultLockOptions {
@@ -6,6 +17,13 @@ export interface DefaultLockOptions {
     readonly clock?: () => number;
     /** Poll interval while waiting; defaults to 25 ms. */
     readonly pollMs?: number;
+    /**
+     * Called (rate-limited) when a waiter sees a lock whose mtime crossed `staleMs` while its holder
+     * pid is still ALIVE — the one case the lock deliberately refuses to reclaim. A long critical
+     * section is legal; this is how "the lock contract is being stretched" becomes visible instead of
+     * being silently papered over by stealing the lock.
+     */
+    readonly onSlowHold?: (info: SlowHoldInfo) => void;
 }
 /** The default {@link ProvisionLock}. */
 export declare function defaultLock(options?: DefaultLockOptions): ProvisionLock;

package/dist/lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../src/lock.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAc,aAAa,EAAE,MAAM,YAAY,CAAA;AAO3D,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAO/C;AAoBD,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAA;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,yCAAyC;AACzC,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,aAAa,CA2D3E"}
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../src/lock.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAc,aAAa,EAAE,MAAM,YAAY,CAAA;AAO3D,4FAA4F;AAC5F,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAO/C;AAwCD,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAA;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,CAAA;CACnD;AAED,yCAAyC;AACzC,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,aAAa,CAsG3E"}

package/dist/lock.js

@@ -34,21 +34,43 @@ async function readHolder(path) {
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
+/**
+ * Last warning time per `(path, holder)` pair. The poll loop re-observes the same stale-but-alive
+ * holder every `pollMs`, and a caller may retry `acquire` — both would otherwise emit the same line
+ * hundreds of times. The window is one `staleMs` (at least 1 s), i.e. the same period the warning is
+ * about; the holder identity makes a genuinely new holder warn again immediately.
+ */
+const slowHoldWarnedAt = new Map();
+/** Bound on the rate-limit state; a lock home far past this just re-warns once more. */
+const SLOW_HOLD_WARN_STATE_LIMIT = 64;
+function warnSlowHold(onSlowHold, info) {
+    const key = `${info.path}\u0000${String(info.pid)}\u0000${String(info.startedAt)}`;
+    const now = Date.now();
+    const last = slowHoldWarnedAt.get(key);
+    if (last !== undefined && now - last < Math.max(1_000, info.staleMs))
+        return;
+    if (slowHoldWarnedAt.size >= SLOW_HOLD_WARN_STATE_LIMIT)
+        slowHoldWarnedAt.clear();
+    slowHoldWarnedAt.set(key, now);
+    onSlowHold(info);
+}
 /** The default {@link ProvisionLock}. */
 export function defaultLock(options = {}) {
     const clock = options.clock ?? Date.now;
     const pollMs = options.pollMs ?? 25;
+    const onSlowHold = options.onSlowHold;
     return {
         async acquire(path, { timeoutMs, staleMs }) {
             // Ensure the control-plane directory exists.
             await mkdir(dirname(path), { recursive: true });
-            const deadline = clock() + timeoutMs;
+            const started = clock();
+            const deadline = started + timeoutMs;
             for (;;) {
                 const mine = { pid: process.pid, startedAt: clock() };
+                let handle;
                 try {
-                    const handle = await open(path, 'wx');
+                    handle = await open(path, 'wx');
                     await handle.writeFile(JSON.stringify(mine), 'utf8');
-                    await handle.close();
                     return {
                         dispose: () => {
                             // Remove the lock only while it is still ours.
@@ -62,28 +84,73 @@ export function defaultLock(options = {}) {
                     };
                 }
                 catch (error) {
+                    // The file we just created is OURS even though the write failed. Leaving a zero-byte
+                    // `.lock` behind is exactly the wedge this function has to recover from, so remove it
+                    // before rethrowing. Close first: Windows refuses to unlink an open handle.
+                    if (handle !== undefined) {
+                        await handle.close().catch(() => undefined);
+                        handle = undefined;
+                        await unlink(path).catch(() => undefined);
+                    }
                     // Only EEXIST is contention; any other error is rethrown.
                     if (error.code !== 'EEXIST') {
                         throw new ProvisionError('unknown-error', `无法创建锁 ${path}：${error instanceof Error ? error.message : String(error)}`);
                     }
                 }
+                finally {
+                    // The success path returns from inside the `try`, so the handle is released here — a
+                    // `writeFile`/`close` failure must never leak it.
+                    if (handle !== undefined)
+                        await handle.close().catch(() => undefined);
+                }
                 const holder = await readHolder(path);
+                // The lock file's own mtime, read from the filesystem. It is compared against the WALL clock
+                // rather than the injectable one: `clock` drives the timeout budget and the recorded
+                // `startedAt`, but an injected clock that is deliberately far from wall time would make a
+                // fresh lock look arbitrarily old.
+                const info = await stat(path).then(value => value, () => undefined);
+                const fileStale = info !== undefined && Date.now() - info.mtimeMs > staleMs;
+                const heldMs = info === undefined ? 0 : Math.round(Date.now() - info.mtimeMs);
+                const waitedMs = Math.round(clock() - started);
                 if (holder === undefined) {
-                    // A missing or unreadable holder still honours the timeout budget.
+                    // No readable holder. mtime is the only trustworthy signal that this is a corrupt /
+                    // half-written lock rather than a live writer caught mid-write, so a stale file is
+                    // reclaimed and a fresh one still honours the timeout budget.
+                    if (fileStale && await unlink(path).then(() => true, () => false))
+                        continue;
                     if (clock() >= deadline) {
-                        throw new ProvisionError('lock/timeout', `等待发布锁超时（${String(timeoutMs)} ms）：${path} 存在但不是可读的锁文件`);
+                        throw new ProvisionError('lock/timeout', `等待发布锁超时（预算 ${String(timeoutMs)} ms，已等待 ${String(waitedMs)} ms）：${path} 存在但不是可读的锁文件` +
+                            (info === undefined ? '' : `；锁文件 mtime 年龄 ${String(heldMs)} ms（staleMs ${String(staleMs)} ms）`));
                     }
-                    const stillThere = await stat(path).then(() => true, () => false);
-                    if (stillThere)
+                    if (info !== undefined)
                         await sleep(pollMs);
                     continue;
                 }
-                if (!pidIsAlive(holder.pid) && clock() - holder.startedAt > staleMs) {
-                    await unlink(path).catch(() => undefined);
+                // A readable holder. The pid is AUTHORITATIVE: a lock is reclaimed only when its holder is
+                // provably GONE. mtime alone must never reclaim a live holder — a critical section is allowed
+                // to outlive `staleMs` (a GiB-scale copy fallback on Windows takes minutes), and stealing the
+                // lock from a live writer is worse than making the waiter fail visibly: two writers entering
+                // the same snapshot directory is a correctness break, a timeout is a report. `recordedStale`
+                // stays the secondary signal for a dead pid, keeping recovery working under an injected clock
+                // or where mtime is not meaningful.
+                const alive = pidIsAlive(holder.pid);
+                const recordedStale = !alive && clock() - holder.startedAt > staleMs;
+                if (!alive && (recordedStale || fileStale) && await unlink(path).then(() => true, () => false))
                     continue;
+                if (alive && fileStale && onSlowHold !== undefined) {
+                    warnSlowHold(onSlowHold, {
+                        path,
+                        pid: holder.pid,
+                        startedAt: holder.startedAt,
+                        heldMs,
+                        staleMs,
+                        waitedMs,
+                    });
                 }
                 if (clock() >= deadline) {
-                    throw new ProvisionError('lock/timeout', `等待发布锁超时（${String(timeoutMs)} ms）：${path} 由 pid ${String(holder.pid)} 持有`);
+                    const state = alive ? '仍存活（活体持有者，不回收）' : '已消失（尚未满足可回收条件）';
+                    throw new ProvisionError('lock/timeout', `等待发布锁超时（预算 ${String(timeoutMs)} ms，已等待 ${String(waitedMs)} ms）：${path} 由 pid ${String(holder.pid)} ` +
+                        `持有（startedAt ${String(holder.startedAt)}），该进程${state}；锁文件 mtime 年龄 ${String(heldMs)} ms（staleMs ${String(staleMs)} ms）`);
                 }
                 await sleep(pollMs);
             }