@jini-ai/platform 0.6.15-rc.2 → 0.6.16

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @jini-ai/platform
 
+## 0.6.15
+
+### Minor Changes
+
+- Add optional `now` and opaque per-install `settings` to `MailAdapterCreateContext`, inherited by
+  `MailProviderModule.create`. Export `createMailAdapterContext` from `@jini-ai/platform/mail` so hosts
+  can supply a live real clock and fresh empty settings at composition time while legacy direct
+  create calls remain compatible. Provider modules retain ownership of settings validation.
+
+- Add opt-in plugin source suffix exclusions and test-file inclusion. Explicit allow-paths and their ancestors now override name exclusions, while excluded descendants and suffix exclusions still skip. Default packing stays unchanged when the new options and conflicting allow/name rules are absent.
+
+  Export ResponseLimitExceededError with limitBytes from platform/fetch-with-timeout and the platform root. Guarded response-text overflow throws this RangeError subclass; invalid caps keep plain RangeError and existing truncation behavior is preserved.
+
+  Accept jsdom 26 and 27 as optional CMS peers alongside 25; media uses DOM APIs shared across these versions.
+
+- Add `createDeadlineSignal` and `DeadlineSignalOptions` to `@jini-ai/platform/fetch-with-timeout`
+  and the root entry. Compose a tool's remaining wait budget with optional caller cancellation,
+  subtract elapsed time through an optional start time and clock port, and clamp remaining time to zero.
+
+- `createDeadlineSignal` accepts an optional cancellable `wait({ ms, signal })`
+  timer port alongside its existing clock port. It now returns `{ signal, dispose }`;
+  rc.1/rc.2 consumers must destructure the signal and call `dispose()` in `finally`.
+  Disposal cancels the pending wait and detaches parent listeners without aborting the
+  returned signal. Deadline expiry and parent cancellation also release resources;
+  parent abort reasons and elapsed-budget accounting are preserved.
+
 ## 0.6.13
 
 ### Patch Changes

package/README.md

@@ -14,12 +14,9 @@ that were split out of OD's monolithic daemon (see the archived provenance ledge
 npm install @jini-ai/platform
 ```
 
-`undici@^7.25.0` is an optional peer for the SSRF-safe asset cache's default dispatcher.
-Install it when calling `createAssetCacheDispatcher` or creating a cache without a host-supplied
-guarded dispatcher. Root imports and `@jini-ai/platform/asset-cache` imports do not load undici;
-the synchronous factory loads it on demand and reports a missing-peer error if it is absent.
-The root declarations retain undici types, so TypeScript consumers of those declarations also
-need the peer available. The dispatcher validates DNS at connection time, and cache `close()`
+`undici@^7.25.0` is a regular dependency, installed with this package for the SSRF-safe asset
+cache's default dispatcher. The synchronous factory constructs it on demand and propagates
+construction failures. The dispatcher validates DNS at connection time, and cache `close()`
 closes only its default dispatcher; a host-supplied dispatcher remains owned by the host.
 Interactive terminal sessions (`createTerminalService`)
 need a `PtySpawn` implementation supplied by the caller — this package defines the `PtyProcess`/
@@ -37,7 +34,8 @@ need a `PtySpawn` implementation supplied by the caller — this package defines
   so profile-only `PATH` entries are visible).
 - **Filesystem** — `pathContains`, `atomicCopyFile`, `removePathBestEffort`, `readLogTail`.
 - **HTTP readiness** — `waitForHttpOk`.
-- **Deadline signals** — `createDeadlineSignal({ waitMs }, { signal, startedAt, now })` from `@jini-ai/platform/fetch-with-timeout`; subtracts elapsed milliseconds using the optional `now: () => number` clock (default `Date.now`) and combines the remaining budget with caller cancellation.
+- **Response byte limits** — `ResponseLimitExceededError` from `@jini-ai/platform/fetch-with-timeout` carries `limitBytes` and extends `RangeError` for guarded response-text overflow.
+- **Deadline signals** — `createDeadlineSignal({ waitMs }, { signal, startedAt, now, wait })` from `@jini-ai/platform/fetch-with-timeout` (also root) returns `{ signal, dispose }`. It subtracts elapsed milliseconds using the optional `now: () => number` clock (default `Date.now`) and combines the remaining budget with caller cancellation. The optional `wait({ ms, signal }): Promise<void>` timer port resolves after the delay and must release its timer and settle when its signal aborts; real timers are the default. Call idempotent `dispose()` in `finally` to cancel the pending wait and detach parent listeners without aborting the returned signal. Deadline expiry uses a `DOMException` named `TimeoutError`; parent abort preserves its reason.
 - **Toolchain discovery** — `wellKnownUserToolchainBins` (npm/pnpm/bun/cargo/deno/go/pyenv,
   asdf/volta/mise/nvm/fnm shims).
 - **Proxy-aware env** — `resolveSystemProxyEnv`, `mergeProxyAwareEnv` (macOS `scutil` / Windows
@@ -164,7 +162,8 @@ replacement races remain outside this guarantee. Omitting the policy retains exi
 `readFetchResponseText({ response }, { maxResponseBytes?, strictUtf8? })`, and
 `fetchTextWithTimeout({ url, timeoutMs, init? }, { fetch?, maxResponseBytes?, strictUtf8? })`.
 Text defaults to unlimited bytes and replacement UTF-8 decoding. Caps must be nonnegative safe
-integers; exactly the cap is accepted, overflow throws `RangeError`, and strict UTF-8 throws on
+integers; exactly the cap is accepted, overflow throws `ResponseLimitExceededError` (a `RangeError`
+with `limitBytes`), invalid caps throw plain `RangeError`, and strict UTF-8 throws on
 malformed/truncated input. Streamed bytes are counted before decoding, independent of Content-Length;
 failed guarded consumption cancels and releases the reader without masking the original error.
 Incoming chunk allocation is controlled by the upstream stream. The text-fetch helper maps timeout

package/dist/asset-cache.adapter.d.ts

@@ -1,7 +1,7 @@
 import type { LookupFunction } from 'node:net';
 import type { Agent } from 'undici';
-/** Load the optional vendor only for a default dispatcher; the cache owns lookup validation.
- * @throws When the optional peer cannot be loaded or its Agent cannot be constructed.
+/** Construct the dispatcher with platform's required undici dependency; the cache owns lookup validation.
+ * @throws When the Agent cannot be constructed.
  */
 export declare function createUndiciAssetCacheDispatcher({ lookup }: {
     lookup: LookupFunction;

package/dist/asset-cache.adapter.js

@@ -1,7 +1,7 @@
 import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
-/** Load the optional vendor only for a default dispatcher; the cache owns lookup validation.
- * @throws When the optional peer cannot be loaded or its Agent cannot be constructed.
+/** Construct the dispatcher with platform's required undici dependency; the cache owns lookup validation.
+ * @throws When the Agent cannot be constructed.
  */
 export function createUndiciAssetCacheDispatcher({ lookup }, _options = {}) {
     const { Agent } = require('undici');

package/dist/asset-cache.d.ts

@@ -52,9 +52,7 @@ export interface AssetCache {
     /** Closes only the default adapter; an injected dispatcher remains owned by its host. */
     close?(): Promise<void>;
 }
-/** Default adapter: validate DNS at connection time, so the checked address is the connected one.
- * @throws {AssetCacheError} When the host has not installed the optional undici peer.
- */
+/** Default adapter: validate DNS at connection time, so the checked address is the connected one. */
 export declare function createAssetCacheDispatcher(_required: Record<string, never>, { lookupImpl }?: {
     lookupImpl?: DnsLookupCb;
 }): Agent;

package/dist/asset-cache.js

@@ -130,21 +130,9 @@ export function createValidatingLookup(lookupImpl = dnsLookupCb) {
         });
     };
 }
-/** Default adapter: validate DNS at connection time, so the checked address is the connected one.
- * @throws {AssetCacheError} When the host has not installed the optional undici peer.
- */
+/** Default adapter: validate DNS at connection time, so the checked address is the connected one. */
 export function createAssetCacheDispatcher(_required, { lookupImpl } = {}) {
-    // Keep the factory synchronous while root imports and host-supplied dispatchers need no undici.
-    try {
-        return createUndiciAssetCacheDispatcher({ lookup: createValidatingLookup(lookupImpl) });
-    }
-    catch (error) {
-        if (error instanceof Error && error.code === 'MODULE_NOT_FOUND'
-            && error.message.split('\n')[0] === "Cannot find module 'undici'") {
-            throw new AssetCacheError(500, 'Asset cache dispatcher requires the optional peer "undici"; install undici@^7.25.0 or supply a guarded dispatcher.');
-        }
-        throw error;
-    }
+    return createUndiciAssetCacheDispatcher({ lookup: createValidatingLookup(lookupImpl) });
 }
 /** Build a disk-backed cache for external sandboxed-content media. Concurrent
  *  requests for the same URL share one in-flight fetch; completed fetches

package/dist/blob-storage.js

@@ -19,6 +19,7 @@
  */
 import path from 'node:path';
 import { promises as fsp } from 'node:fs';
+import { trimChars, trimCharsEnd, trimCharsStart } from '@jini-ai/core/primitives';
 import { encodeS3PathSegment, signSigV4 } from './aws-sigv4.js';
 /** Error thrown by {@link BlobStorage} implementations, distinguishing not-found/traversal/IO failures. */
 export class StorageError extends Error {
@@ -187,12 +188,13 @@ export class S3BlobStorage {
     keyFor(namespace, relpath, { allowPrefix = false } = {}) {
         validateNamespace(namespace);
         const normalized = validateRelpath(relpath, { allowPrefix });
-        const segments = [this.options.prefix?.replace(/^\/+|\/+$/g, ''), namespace, normalized].filter((s) => typeof s === 'string' && s.length > 0);
+        const prefix = this.options.prefix === undefined ? undefined : trimChars({ text: this.options.prefix, chars: '/' });
+        const segments = [prefix, namespace, normalized].filter((s) => typeof s === 'string' && s.length > 0);
         return segments.join('/');
     }
     endpointBase() {
         if (this.options.endpoint)
-            return this.options.endpoint.replace(/\/+$/, '');
+            return trimCharsEnd({ text: this.options.endpoint, chars: '/' });
         return `https://${this.options.bucket}.s3.${this.options.region}.amazonaws.com`;
     }
     async signedRequest(args) {
@@ -224,7 +226,8 @@ export class S3BlobStorage {
             credentials: this.options.credentials,
             now,
         });
-        const url = `${base.replace(/\/+$/, '')}${pathSegment}${args.extraQuery ? `?${args.extraQuery}` : ''}`;
+        const query = args.extraQuery ? `?${args.extraQuery}` : '';
+        const url = `${trimCharsEnd({ text: base, chars: '/' })}${pathSegment}${query}`;
         const init = {
             method: args.method,
             headers,
@@ -320,12 +323,10 @@ function namespaceEntries(entries, namespacePrefix) {
     for (const e of entries) {
         // It includes the non-empty, validated namespace and its trailing separator,
         // so sibling namespaces (ns10 vs ns1) cannot leak into this listing.
-        if (!e.key.startsWith(namespacePrefix))
-            continue;
-        const rel = e.key.slice(namespacePrefix.length).replace(/^\/+/, '');
-        if (!rel)
-            continue; // skip the prefix marker itself
-        out.push({ path: rel, size: e.size, mtimeMs: e.lastModifiedMs });
+        const rel = e.key.startsWith(namespacePrefix) ? trimCharsStart({ text: e.key.slice(namespacePrefix.length), chars: '/' }) : '';
+        // An empty rel is either a foreign key or the prefix marker itself; both are skipped.
+        if (rel)
+            out.push({ path: rel, size: e.size, mtimeMs: e.lastModifiedMs });
     }
     return out;
 }

package/dist/child-environment.js

@@ -44,7 +44,7 @@ export function nodeLoginShellPorts() {
 function parseNullSeparatedEnvironment({ stdout }) {
     const entries = stdout.split('\0').flatMap(pair => {
         const at = pair.indexOf('=');
-        return at > 0 && /^[A-Za-z_][A-Za-z0-9_]*$/.test(pair.slice(0, at)) ? [[pair.slice(0, at), pair.slice(at + 1)]] : [];
+        return at > 0 && /^[A-Za-z_]\w*$/.test(pair.slice(0, at)) ? [[pair.slice(0, at), pair.slice(at + 1)]] : [];
     });
     return Object.fromEntries(entries);
 }

package/dist/command.js

@@ -11,6 +11,7 @@
  * itself.
  */
 import { extname } from "node:path";
+import { trimCharsEnd } from "@jini-ai/core/primitives";
 // `cmd.exe /s /c "..."` runs percent-expansion on the inner line *regardless*
 // of whether the `%name%` pair sits inside a `"..."` quoted segment, so a
 // `.cmd` / `.bat` shim spawn with an attacker-influenced argv (e.g. an LLM
@@ -31,7 +32,9 @@ function quoteWindowsCommandArg({ value }, _options = {}) {
     if (value !== "" && !/[\s"&<>|^%=,;()]/.test(value))
         return value;
     // Backslashes before the closing quote must survive the child's argv parser.
-    const escaped = value.replace(/"/g, '""').replace(/%/g, '"^%"').replace(/\\+$/, '$&$&');
+    const quoted = value.replace(/"/g, '""').replace(/%/g, '"^%"');
+    const trailingBackslashes = quoted.slice(trimCharsEnd({ text: quoted, chars: '\\' }).length);
+    const escaped = quoted + trailingBackslashes;
     return `"${escaped}"`;
 }
 // Build the `cmd.exe /d /s /c "<line>"` invocation Node uses internally for

package/dist/core/effective-port.d.ts

@@ -0,0 +1,6 @@
+/** The port a URL actually connects to: its explicit port, else 443 for `https:` and 80 otherwise.
+ *  @complexity O(1). */
+export declare function effectivePort({ url }: {
+    url: URL;
+}, _optional?: Record<string, never>): number;
+//# sourceMappingURL=effective-port.d.ts.map

package/dist/core/effective-port.js

@@ -0,0 +1,8 @@
+/** The port a URL actually connects to: its explicit port, else 443 for `https:` and 80 otherwise.
+ *  @complexity O(1). */
+export function effectivePort({ url }, _optional = {}) {
+    if (url.port)
+        return Number(url.port);
+    return url.protocol === "https:" ? 443 : 80;
+}
+//# sourceMappingURL=effective-port.js.map

package/dist/download.js

@@ -75,6 +75,7 @@ function normalizeChecksum(input) {
     }
     return { algorithm: input.algorithm, value };
 }
+const DOT_SEGMENTS = new Set([".", ".."]);
 function normalizeSegment(value, label) {
     if (typeof value !== "string" || value.length === 0) {
         throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.INVALID_TARGET, `${label} must be a non-empty string`);
@@ -83,7 +84,7 @@ function normalizeSegment(value, label) {
     // `isAbsolute`/`[\\/]` checks above don't reject it, but `path.win32.resolve`
     // treats it as a real drive reference, which can escape `basePath` onto a
     // different drive entirely.
-    if (value === "." || value === ".." || value.includes("\0") || value.includes(":") || /[\\/]/.test(value) || isAbsolute(value)) {
+    if (DOT_SEGMENTS.has(value) || value.includes("\0") || /[:\\/]/.test(value) || isAbsolute(value)) {
         throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.INVALID_TARGET, `${label} must be a safe single path segment`);
     }
     return value;
@@ -210,15 +211,15 @@ async function ensureManagedBase(basePath) {
     }
     const sentinelPath = join(basePath, STORE_SENTINEL);
     const sentinel = await readJson(sentinelPath);
+    if (sentinel != null && !isStoreSentinel(sentinel)) {
+        throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.STORE_NOT_OWNED, `download base has an invalid ownership marker: ${basePath}`);
+    }
     if (sentinel == null) {
         if (!(await directoryIsEmpty(basePath))) {
             throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.STORE_NOT_OWNED, `download base is not empty and has no ownership marker: ${basePath}`);
         }
         await writeSentinel(basePath);
     }
-    else if (!isStoreSentinel(sentinel)) {
-        throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.STORE_NOT_OWNED, `download base has an invalid ownership marker: ${basePath}`);
-    }
     await ensureStoreDirs(basePath);
 }
 function isChecksum(value) {
@@ -241,21 +242,20 @@ function isManifest(value) {
     if (!isPlainObject(value))
         return false;
     const record = value;
-    return (record.kind === MANIFEST_KIND &&
-        record.schemaVersion === MANIFEST_SCHEMA_VERSION &&
+    const versionMatches = record.kind === MANIFEST_KIND && record.schemaVersion === MANIFEST_SCHEMA_VERSION;
+    const knownState = record.state === "complete" || record.state === "partial";
+    return (versionMatches &&
         MANIFEST_STRING_FIELDS.every((field) => typeof record[field] === "string") &&
         isChecksum(record.checksum) &&
-        (record.state === "complete" || record.state === "partial"));
+        knownState);
 }
 function isDownloadLockFile(value) {
     if (!isPlainObject(value))
         return false;
     const record = value;
-    return typeof record.createdAt === "string" &&
-        typeof record.pid === "number" &&
-        Number.isInteger(record.pid) &&
-        record.pid > 0 &&
-        (record.processStartedAt == null || typeof record.processStartedAt === "string");
+    const validPid = typeof record.pid === "number" && Number.isInteger(record.pid) && record.pid > 0;
+    const validStartedAt = record.processStartedAt == null || typeof record.processStartedAt === "string";
+    return typeof record.createdAt === "string" && validPid && validStartedAt;
 }
 function parseTimeMs(value) {
     if (value == null)
@@ -293,14 +293,12 @@ async function readManifest(path) {
         return "invalid";
     }
 }
+const MANIFEST_IDENTITY_FIELDS = ["bucket", "fileName", "targetKey", "identityDigest", "urlDigest"];
 function manifestMatchesTarget(manifest, target) {
-    return (manifest.bucket === target.bucket &&
-        manifest.fileName === target.fileName &&
-        manifest.targetKey === target.targetKey &&
-        manifest.identityDigest === target.identityDigest &&
-        manifest.urlDigest === target.urlDigest &&
-        manifest.checksum.algorithm === target.checksum.algorithm &&
-        manifest.checksum.value.toLowerCase() === target.checksum.value);
+    const identityMatches = MANIFEST_IDENTITY_FIELDS.every((field) => manifest[field] === target[field]);
+    const checksumMatches = manifest.checksum.algorithm === target.checksum.algorithm &&
+        manifest.checksum.value.toLowerCase() === target.checksum.value;
+    return identityMatches && checksumMatches;
 }
 function createManifest(target, state, patch = {}) {
     const now = new Date().toISOString();
@@ -468,10 +466,12 @@ async function downloadWithRetries(target, manifest, options) {
     const deps = { emit: options.emit, fetchImpl: options.fetchImpl };
     for (let attempt = 1; attempt <= options.maxAttempts; attempt += 1) {
         try {
-            if (nextManifest?.state === "partial") {
-                const resume = await tryResumeDownload({ ...deps, manifest: nextManifest, target }, options);
-                if (resume !== "restart")
-                    return resume;
+            const resume = nextManifest?.state === "partial"
+                ? await tryResumeDownload({ ...deps, manifest: nextManifest, target }, options)
+                : null;
+            if (resume !== null && resume !== "restart")
+                return resume;
+            if (resume === "restart") {
                 await rm(target.partialPath, { force: true }).catch(() => undefined);
                 nextManifest = null;
             }
@@ -859,9 +859,10 @@ async function removeEntriesOlderThan(root, olderThan) {
         if (info == null || info.mtimeMs > olderThan)
             continue;
         const result = await removePathBestEffort(path);
+        // A successful removal never carries an error, so the two checks are exclusive.
         if (result.removed)
             removed += 1;
-        else if (result.error != null)
+        if (result.error != null)
             warnings.push(result.error);
     }
     return { removed, warnings };

package/dist/fetch-with-timeout.d.ts

@@ -37,7 +37,7 @@
  * module has zero imports of its own — no `node:*` builtin, no `undici` — unlike the package's root
  * barrel (`index.ts`), which re-exports sibling modules (`process.ts`, `fs.ts`, `terminal.ts`,
  * `asset-cache.ts`, …) that import `node:child_process`, `node:fs`, etc.; the asset-cache
- * dispatcher loads the optional `undici` peer only when its synchronous factory is called.
+ * dispatcher constructs its required `undici` dependency only when its synchronous factory is called.
  * Importing from the root barrel in browser-bundled code is silently fine in a *production* build
  * through Vite/Rollup — tree-shaking (this package sets `sideEffects: false`) proves the Node-only
  * re-exports are unused and drops them before the `node:*` imports are ever resolved — but it is
@@ -59,6 +59,15 @@ export declare class FetchTimeoutError extends Error {
     readonly timeoutMs: number;
     constructor(url: string, timeoutMs: number);
 }
+/** Observed response bytes exceeded the configured cap. Extends RangeError for existing catches;
+ * invalid cap configuration still throws a plain RangeError. */
+export declare class ResponseLimitExceededError extends RangeError {
+    readonly limitBytes: number;
+    /** Records the byte ceiling without retaining response content. O(1) time and space. */
+    constructor({ limitBytes }: {
+        limitBytes: number;
+    }, _options?: Record<string, never>);
+}
 /**
  * Shared, documented timeout classes for outbound `fetch()` calls. Every call site names one
  * explicitly (or its own justified number) rather than relying on an unstated default.
@@ -96,22 +105,32 @@ export interface DeadlineSignalOptions {
     startedAt?: number;
     /** Clock port in milliseconds; defaults to Date.now and is read only with startedAt. */
     now?: () => number;
+    /** Resolves after ms; aborting signal must release the wait and settle its promise. */
+    wait?: (input: {
+        ms: number;
+        signal: AbortSignal;
+    }) => Promise<void>;
 }
 /**
  * Creates one signal that aborts when the remaining wait budget expires or the caller cancels.
  * Spent time is subtracted once; future start times cannot increase the original budget.
  * @param input - Wait budget in milliseconds. Negative remaining budgets become zero.
- * @param options - Optional caller signal, start time and clock port.
- * @returns A native deadline signal preserving the first abort reason. Zero expires asynchronously,
+ * @param options - Optional caller signal, start time, clock and cancellable wait ports.
+ * @returns A signal preserving the first abort reason and an idempotent dispose function.
+ * Dispose in finally to cancel the wait and detach the parent without aborting the returned signal.
+ * Zero expires asynchronously,
  * following AbortSignal.timeout(0); an already-aborted caller is reflected immediately.
- * Creates a native timeout without mutating inputs or the caller's signal.
+ * Uses real timers by default without mutating inputs or the caller's signal.
  * @throws {RangeError} If the remaining delay is invalid for AbortSignal.timeout.
  * @complexity O(1) time and space.
- * @example createDeadlineSignal({ waitMs: 5_000 }, { signal, startedAt, now: Date.now })
+ * @example const { signal, dispose } = createDeadlineSignal({ waitMs: 5_000 }, { wait });
  */
 export declare function createDeadlineSignal({ waitMs }: {
     waitMs: number;
-}, { signal, startedAt, now }?: DeadlineSignalOptions): AbortSignal;
+}, { signal, startedAt, now, wait }?: DeadlineSignalOptions): {
+    signal: AbortSignal;
+    dispose: () => void;
+};
 /** Opt-in byte and decoding guards; defaults remain unlimited and replacement-decoded. */
 export type TextReadOptions = {
     /** Nonnegative safe integer. Actual streamed bytes, independent of Content-Length. */
@@ -124,7 +143,8 @@ export type TextReadOptions = {
  * Details mode reports retained source bytes and truncates only on observed overflow;
  * reaching the cap still requires EOF to establish completeness. Defaults reject overflow
  * and replace malformed UTF-8. A supplied signal interrupts even a stalled read.
- * @throws {RangeError} An invalid cap or a response exceeding it.
+ * @throws {RangeError} An invalid cap.
+ * @throws {ResponseLimitExceededError} Observed bytes exceed the cap (also a RangeError).
  * @throws {TypeError} Invalid UTF-8 when strict decoding is enabled.
  * Read failures and abort reasons propagate; acquired readers are cancelled on failure
  * and always released. Details mode observes cancellation failures without awaiting cleanup.

package/dist/fetch-with-timeout.js

@@ -37,7 +37,7 @@
  * module has zero imports of its own — no `node:*` builtin, no `undici` — unlike the package's root
  * barrel (`index.ts`), which re-exports sibling modules (`process.ts`, `fs.ts`, `terminal.ts`,
  * `asset-cache.ts`, …) that import `node:child_process`, `node:fs`, etc.; the asset-cache
- * dispatcher loads the optional `undici` peer only when its synchronous factory is called.
+ * dispatcher constructs its required `undici` dependency only when its synchronous factory is called.
  * Importing from the root barrel in browser-bundled code is silently fine in a *production* build
  * through Vite/Rollup — tree-shaking (this package sets `sideEffects: false`) proves the Node-only
  * re-exports are unused and drops them before the `node:*` imports are ever resolved — but it is
@@ -64,6 +64,17 @@ export class FetchTimeoutError extends Error {
         this.timeoutMs = timeoutMs;
     }
 }
+/** Observed response bytes exceeded the configured cap. Extends RangeError for existing catches;
+ * invalid cap configuration still throws a plain RangeError. */
+export class ResponseLimitExceededError extends RangeError {
+    limitBytes;
+    /** Records the byte ceiling without retaining response content. O(1) time and space. */
+    constructor({ limitBytes }, _options = {}) {
+        super(`response exceeds the ${limitBytes}-byte limit`);
+        this.name = "ResponseLimitExceededError";
+        this.limitBytes = limitBytes;
+    }
+}
 /**
  * Shared, documented timeout classes for outbound `fetch()` calls. Every call site names one
  * explicitly (or its own justified number) rather than relying on an unstated default.
@@ -87,24 +98,53 @@ export const FETCH_TIMEOUT_MS = {
      * legitimately still-generating request early. */
     GENERATE: 10 * 60_000,
 };
+/** Browser-safe timer adapter; completion and cancellation both release its listener. */
+function waitForDeadline({ ms, signal }, _options = {}) {
+    return new Promise((resolve, reject) => {
+        signal.throwIfAborted();
+        const abort = () => { clearTimeout(timer); reject(signal.reason); };
+        const timer = setTimeout(() => { signal.removeEventListener("abort", abort); resolve(); }, ms);
+        // Like native timeout signals, pending deadlines must not keep a Node process alive.
+        if (typeof timer === "object")
+            timer.unref();
+        signal.addEventListener("abort", abort, { once: true });
+    });
+}
 /**
  * Creates one signal that aborts when the remaining wait budget expires or the caller cancels.
  * Spent time is subtracted once; future start times cannot increase the original budget.
  * @param input - Wait budget in milliseconds. Negative remaining budgets become zero.
- * @param options - Optional caller signal, start time and clock port.
- * @returns A native deadline signal preserving the first abort reason. Zero expires asynchronously,
+ * @param options - Optional caller signal, start time, clock and cancellable wait ports.
+ * @returns A signal preserving the first abort reason and an idempotent dispose function.
+ * Dispose in finally to cancel the wait and detach the parent without aborting the returned signal.
+ * Zero expires asynchronously,
  * following AbortSignal.timeout(0); an already-aborted caller is reflected immediately.
- * Creates a native timeout without mutating inputs or the caller's signal.
+ * Uses real timers by default without mutating inputs or the caller's signal.
  * @throws {RangeError} If the remaining delay is invalid for AbortSignal.timeout.
  * @complexity O(1) time and space.
- * @example createDeadlineSignal({ waitMs: 5_000 }, { signal, startedAt, now: Date.now })
+ * @example const { signal, dispose } = createDeadlineSignal({ waitMs: 5_000 }, { wait });
  */
-export function createDeadlineSignal({ waitMs }, { signal, startedAt, now = Date.now } = {}) {
+export function createDeadlineSignal({ waitMs }, { signal, startedAt, now = Date.now, wait = waitForDeadline } = {}) {
     const elapsedMs = startedAt === undefined ? 0 : Math.max(0, now() - startedAt);
-    const deadline = AbortSignal.timeout(Math.max(0, waitMs - elapsedMs));
-    if (signal === undefined)
-        return deadline;
-    return AbortSignal.any([deadline, signal]);
+    const ms = Math.max(0, waitMs - elapsedMs);
+    if (!Number.isSafeInteger(ms))
+        throw new RangeError("remaining deadline must be a nonnegative safe integer");
+    const deadline = new AbortController();
+    const timer = new AbortController();
+    const dispose = () => { timer.abort(); signal?.removeEventListener("abort", onAbort); };
+    const finish = (reason) => {
+        if (!timer.signal.aborted)
+            deadline.abort(reason);
+        dispose();
+    };
+    const onAbort = () => finish(signal.reason);
+    if (signal?.aborted)
+        onAbort();
+    else {
+        signal?.addEventListener("abort", onAbort, { once: true });
+        void wait({ ms, signal: timer.signal }).then(() => finish(new DOMException("The operation was aborted due to timeout", "TimeoutError")), finish);
+    }
+    return { signal: deadline.signal, dispose };
 }
 export async function readFetchResponseText(input, { maxResponseBytes, strictUtf8 = false } = {}) {
     const details = "result" in input && input.result === "details";
@@ -176,7 +216,7 @@ async function decodeResponseStream({ reader }, { maxResponseBytes = Infinity, s
         const remaining = maxResponseBytes - total;
         if (value.byteLength > remaining) {
             if (onLimit === "reject")
-                throw new RangeError(`response exceeds the ${maxResponseBytes}-byte limit`);
+                throw new ResponseLimitExceededError({ limitBytes: maxResponseBytes });
             text += decoder.decode(value.subarray(0, remaining), { stream: true });
             return { text: text + decoder.decode(), byteLength: maxResponseBytes, truncated: true };
         }

package/dist/fs/atomic-write.js

@@ -3,6 +3,7 @@ import * as fsPromises from "node:fs/promises";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { defaultPlatformMessages } from "../messages.js";
+import { errorCodeOf } from "./errno.js";
 /** Optional adapter wiring: no layout, env key, or application name is selected here. */
 export function createNodeAtomicFilesystem(_required, { filesystem = fs } = {}) {
     return {
@@ -19,7 +20,8 @@ export function createNodeAtomicFilesystem(_required, { filesystem = fs } = {})
 }
 const DIRECTORY_SYNC_UNSUPPORTED = ["EPERM", "EISDIR", "EINVAL", "EACCES", "ENOTSUP"];
 function hasErrorCode(error, codes) {
-    return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" && codes.includes(error.code);
+    const code = errorCodeOf(error);
+    return code !== undefined && codes.includes(code);
 }
 function isMissing(error) {
     return hasErrorCode(error, ["ENOENT"]);
@@ -78,8 +80,9 @@ function checkedTempPath({ filePath, temporary }, options) {
         throw new RangeError(messagesFor(options).atomicTempPathInvalid());
     return temporary;
 }
+const DOT_SEGMENTS = new Set([".", ".."]);
 function tokenTempPath({ filePath, token }, options) {
-    if (!token || token === "." || token === ".." || /[/\\\x00]/.test(token))
+    if (!token || DOT_SEGMENTS.has(token) || token.includes("\0") || /[/\\]/.test(token))
         throw new RangeError(messagesFor(options).atomicTempNameInvalid());
     return path.join(path.dirname(filePath), `.${path.basename(filePath)}.${token}.tmp`);
 }

package/dist/fs/boot-identity.d.ts

@@ -14,10 +14,6 @@ export declare function readBootIdentity(_required: Record<string, never>, _opti
  * beyond this tolerance proves an earlier boot; shorter gaps fall back to the PID probe.
  */
 export declare const BOOT_CLOCK_TOLERANCE_MS: number;
-/** True only when a recorded holder provably predates this boot. Linux boot_id is a random UUID and is
- * compared exactly; numeric (time-derived) ids and legacy timestamps get the tolerance above. A record
- * from a "later" boot is clock skew, never proof of death. @complexity O(1).
- */
 export declare function fromEarlierBoot({ boot, bootId, atMs }: {
     boot: BootIdentity | undefined;
     bootId: string | undefined;

package/dist/fs/boot-identity.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import { execFileSync } from "node:child_process";
+import { windowsPowerShell } from "../windows-system-tools.js";
 let cached;
 const NATIVE_TIMEOUT_MS = 3000;
 function linuxBootIdentity() {
@@ -16,8 +17,7 @@ function darwinBootIdentity() {
     return timestampIdentity(Number(/sec\s*=\s*(\d+)/.exec(text)?.[1]) * 1000);
 }
 function windowsBootIdentity() {
-    // eslint-disable-next-line sonarjs/no-os-command-from-path -- Fixed OS utility with fixed argv, resolved through the desktop operator's trusted PATH; no request controls the executable.
-    const text = execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", "(Get-CimInstance Win32_OperatingSystem).LastBootUpTime.ToUniversalTime().ToString('o')"], { encoding: "utf8", timeout: NATIVE_TIMEOUT_MS, windowsHide: true });
+    const text = execFileSync(windowsPowerShell(), ["-NoProfile", "-NonInteractive", "-Command", "(Get-CimInstance Win32_OperatingSystem).LastBootUpTime.ToUniversalTime().ToString('o')"], { encoding: "utf8", timeout: NATIVE_TIMEOUT_MS, windowsHide: true });
     return timestampIdentity(Date.parse(text.trim()));
 }
 const PLATFORM_READERS = { linux: linuxBootIdentity, darwin: darwinBootIdentity, win32: windowsBootIdentity };
@@ -46,10 +46,16 @@ export const BOOT_CLOCK_TOLERANCE_MS = 10 * 60_000;
  * compared exactly; numeric (time-derived) ids and legacy timestamps get the tolerance above. A record
  * from a "later" boot is clock skew, never proof of death. @complexity O(1).
  */
+/** Legacy records carry only a timestamp; time-derived boot ids are numeric; a UUID id has no time. */
+function recordedBootTimeMs({ bootId, atMs }) {
+    if (bootId === undefined)
+        return atMs;
+    return /^\d+$/.test(bootId) ? Number(bootId) : undefined;
+}
 export function fromEarlierBoot({ boot, bootId, atMs }, _options = {}) {
     if (!boot)
         return false;
-    const recordedAtMs = bootId === undefined ? atMs : /^\d+$/.test(bootId) ? Number(bootId) : undefined;
+    const recordedAtMs = recordedBootTimeMs({ bootId, atMs });
     return recordedAtMs === undefined ? bootId !== boot.id : recordedAtMs < boot.startedAtMs - BOOT_CLOCK_TOLERANCE_MS;
 }
 //# sourceMappingURL=boot-identity.js.map

package/dist/fs/directory-registry.js

@@ -14,8 +14,8 @@ export function createDirectoryRegistry(
         if (result.state !== "ok")
             throw new Error("The shared directory registry is unreadable; nothing was overwritten.");
         const state = result.value;
-        if (state?.version !== 1 || !Array.isArray(state.entries) || !Array.isArray(state.migrations) ||
-            !state.migrations.every((item) => typeof item === "string") || !state.entries.every(validRecord)) {
+        const shapeOk = state?.version === 1 && Array.isArray(state.entries) && Array.isArray(state.migrations);
+        if (!shapeOk || !state.migrations.every((item) => typeof item === "string") || !state.entries.every(validRecord)) {
             throw new Error("The shared directory registry has an invalid format; nothing was overwritten.");
         }
         return state;

package/dist/fs/directory-running-lock.js

@@ -67,11 +67,16 @@ function validRunningRecord(value) {
     if (!value || typeof value !== "object")
         return false;
     const record = value;
-    return Number.isSafeInteger(record.pid) && record.pid > 0 && Number.isInteger(record.port) && record.port >= 0 && record.port <= 65535 &&
-        validRunningIdentity({ record }) && ["http", "https"].includes(record.scheme);
+    const validPid = Number.isSafeInteger(record.pid) && record.pid > 0;
+    const validPort = Number.isInteger(record.port) && record.port >= 0 && record.port <= 65535;
+    return validPid && validPort && validRunningIdentity({ record }) && ["http", "https"].includes(record.scheme);
 }
 function validRunningIdentity({ record }, _options = {}) {
-    return typeof record.app === "string" && record.app.length > 0 && typeof record.token === "string" && record.token.length > 0 &&
-        (record.bootId === undefined || typeof record.bootId === "string") && typeof record.started === "string" && Number.isFinite(Date.parse(record.started));
+    const validBootId = record.bootId === undefined || typeof record.bootId === "string";
+    const validStarted = typeof record.started === "string" && Number.isFinite(Date.parse(record.started));
+    return isNonEmptyString(record.app) && isNonEmptyString(record.token) && validBootId && validStarted;
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
 }
 //# sourceMappingURL=directory-running-lock.js.map