@jini-ai/platform 0.6.11 → 0.6.15-rc.1

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @jini-ai/platform
 
+## 0.6.13
+
+### Patch Changes
+
+- 5634614: Add vendor-neutral email sender contracts, source discovery and template preparation to the mail
+  surface, with a universal `@jini-ai/platform/mail/senders` entry. Add the Forms sender to
+  `@jini-ai/cms/forms/email-sender`, deriving tokens from stable field IDs, resolving authorized submissions and
+  permitted recipients, and configuring sender-owned email actions through an injected guarded writer.
+  Delivery planning and production readiness remain host responsibilities.
+  The dedicated sender entry requires the optional platform peer at ^0.6.15; the existing Forms
+  entry continues to load without platform installed.
+- 0728914: Engine guard clean-up (`pnpm guard` 106 -> 0): layer, subpath-isolation and module-state findings fixed by moving
+  shared contracts to their owners instead of reaching across domains. Additive public API: `@jini-ai/core/filesystem`
+  (guarded-reader contracts), `useFetchQueryScope` from `@jini-ai/ui` fetch-query (per-provider query scope),
+  `@jini-ai/chat/react` re-exports of the accepted-input, run-state and agent-plugin chat-state helpers. The Claude
+  filesystem probe cache in `@jini-ai/agent-runtime` is instance-owned. No behaviour change intended; host-facing
+  breaks are listed in `owner-store-to-server` and `guard-host-ports`.
+- 26bd2d2: Expose the mail engine through `@jini-ai/platform/mail`: host contracts, redacted
+  provider diagnostics, permission-aware domain reads, sender verification, delivery
+  policy wrapping, the purpose-gate predicate, provider resolution and status caching.
+  Retain existing exports and keep credential binding, persistence and product policy
+  in host-supplied ports.
+- c14aeb4: Add optional fetch injection, bounded/strict UTF-8 response text reading, text consumption within the fetch timeout scope, and descriptor-based guarded file reads. Existing defaults and positional fetch signatures remain unchanged.
+
+  Add an opt-in details overload to readFetchResponseText with retained-byte metadata, bounded-prefix truncation, and abortable reads with prompt cleanup. fetchTextWithTimeout now races every body read against its timeout, so an injected transport whose body ignores the abort signal still times out.
+
+- Updated dependencies [7479159]
+- Updated dependencies [c31264d]
+- Updated dependencies [0728914]
+- Updated dependencies [6ecbdb2]
+- Updated dependencies [63bacc5]
+  - @jini-ai/core@0.6.13
+
+## 0.6.12
+
+### Patch Changes
+
+- platform: `listProcessUsage()` RSS/CPU sampler for macOS, Windows and Linux; `@jini-ai/platform/secrets` adds `sealWithPassphrase`/`openWithPassphrase` (portable passphrase envelope for encrypted exports); internal mail engine contracts, provider-error redaction, domain reads and per-provider delivery wrapper (not yet exported).
+  - @jini-ai/core@0.6.12
+
 ## 0.6.11
 
 ### Patch Changes

package/README.md

@@ -98,6 +98,15 @@ The package also exposes `./http/guarded`, `./mail`, `./mail/smtp`,
 `./fs/guarded-reader`, `./fs/durable-json`, and `./secrets`. New APIs take a required
 object followed by an optional object. Application identity and policy values belong to the caller.
 
+Email event senders use the universal `@jini-ai/platform/mail/senders` entry (also exported by `/mail`).
+`EmailSender` exposes `listSources`, `describeSource`, `resolveEvent`, and `configureEmail`.
+Each operation authorizes its workspace and principal; the sender owns values, recipients and binding.
+Delivery providers are separate; `createEmailSenderRegistry` reuses core's keyed registry.
+`listEmailSources` lists events across senders; `validateEmailSourceTemplate` checks compatibility.
+`prepareSenderEmail` refuses disabled bindings and events before the latest activation.
+Preparation renders through the injected version-checked template port and sends nothing.
+Its result can be frozen in the feature's existing job; missing optional values produce token warnings.
+
 `@jini-ai/platform/web` loads these optional peers at import time: `parse5@7.3.0`,
 `hast-util-from-parse5@8.0.3`, `hast-util-to-mdast@10.1.2`,
 `mdast-util-to-markdown@2.1.2`, and `mdast-util-gfm-table@2.0.0`. Install all five
@@ -142,6 +151,49 @@ The SMTP subpath accepts a transport and clock; its nodemailer factory accepts t
 as a structural port. Core loads no mail vendor and adds no mail dependency.
 
 The guarded reader requires root, deny rules, all read/traversal limits, and a filesystem port.
+Its existing options object also accepts `descriptorRead: { exactMode?: number, rejectGrowth?: boolean }`.
+When present (including `{}`), reads open with `O_RDONLY | O_NOFOLLOW | O_NONBLOCK`, verify
+regular-file status and size with `fstatSync`, and read that same descriptor. `exactMode` compares
+exact permission bits including setuid/setgid/sticky (`mode & 0o7777`); `rejectGrowth: true` rejects bytes beyond its initial size.
+The filesystem's optional `fstatSync` and `constants` capabilities become required for this policy;
+unsupported flags fail closed. No-follow protects the final path component; ancestor-directory
+replacement races remain outside this guarantee. Omitting the policy retains existing reads.
+
+`@jini-ai/platform/fetch-with-timeout` also exports `TextReadOptions`,
+`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
+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
+errors during both headers and body consumption to `FetchTimeoutError`, returns `{ response, text }`,
+and leaves the response metadata available with its body consumed. The existing positional
+`fetchWithTimeout(url, init, { timeoutMs, fetch? })` now accepts transport injection and still returns
+the original unconsumed response. Neither function retries.
+
+For retained-byte metadata and optional truncation, use the single-object overload:
+
+```ts
+const { text, byteLength, truncated } = await readFetchResponseText({
+  response,
+  maxResponseBytes: 1024,
+  result: "details",
+  onLimit: "truncate",
+  signal,
+});
+```
+
+This overload requires a nonnegative safe-integer cap. `onLimit` defaults to `"reject"`;
+`strictUtf8` defaults to `false`. `byteLength` counts retained source bytes before decoding,
+and `truncated` becomes true only after observing bytes beyond the cap. An exact-sized body
+(including an empty body at a zero cap) requires EOF to establish completeness. Truncation
+cancels consumption and flushes the decoder; cutting a UTF-8 character produces replacement
+text by default or throws with `strictUtf8: true`. A signal interrupts pending reads and
+preserves its abort reason. Details-mode cancellation failures are observed without waiting
+for cancellation to settle, and every acquired reader's lock is released. Existing string
+overloads, defaults, and text-fetch behavior remain unchanged.
+
 The durable JSON factory requires file path, filesystem/time/sleep/liveness/random/reporting ports,
 and host notices. It preserves atomic replacement and corrupt-file states; parent-directory
 persistence and the inherited simultaneous stale-lock-break race remain filesystem/locking limits.

package/dist/asset-cache.js

@@ -29,7 +29,7 @@ import { isPrivateAddress } from './net/address.js';
 /** Media extensions we are willing to cache + proxy. Anything else (HTML,
  *  CSS, JS, fonts) is intentionally left alone so this surface never becomes a
  *  general-purpose open proxy. */
-export const CACHEABLE_MEDIA_EXT = /\.(?:png|jpe?g|webp|gif|avif|svg|mp4|webm|mov|m4v|ogg|mp3|wav)(?:$|[?#])/i;
+export const CACHEABLE_MEDIA_EXT = /\.(?:png|jpe?g|webp|gif|avif|mp4|webm|mov|m4v|ogg|mp3|wav)$/i;
 const EXT_TO_MIME = {
     '.png': 'image/png',
     '.jpg': 'image/jpeg',
@@ -37,7 +37,6 @@ const EXT_TO_MIME = {
     '.webp': 'image/webp',
     '.gif': 'image/gif',
     '.avif': 'image/avif',
-    '.svg': 'image/svg+xml',
     '.mp4': 'video/mp4',
     '.webm': 'video/webm',
     '.mov': 'video/quicktime',
@@ -46,6 +45,7 @@ const EXT_TO_MIME = {
     '.mp3': 'audio/mpeg',
     '.wav': 'audio/wav',
 };
+const CACHEABLE_MEDIA_MIME = new Set(Object.values(EXT_TO_MIME));
 /** True when `raw` is an absolute http(s) URL pointing at a media file we are
  *  willing to route through the cache. Pure + side-effect free so the URL
  *  rewriter and tests can share the exact predicate. */
@@ -55,11 +55,14 @@ export function isCacheableExternalUrl(raw) {
     const value = raw.trim();
     if (!/^https?:\/\//i.test(value))
         return false;
-    // `String#split` always returns a non-empty array (even `''.split(x)` is
-    // `['']`), so index 0 is never `undefined` — the `!` narrows a
-    // `noUncheckedIndexedAccess` false positive, not a real fallback path.
-    const pathOnly = value.split(/[?#]/)[0];
-    return CACHEABLE_MEDIA_EXT.test(pathOnly) || CACHEABLE_MEDIA_EXT.test(value);
+    // Only the parsed pathname establishes eligibility; a query/fragment that
+    // happens to end in .png must not turn an arbitrary endpoint into media.
+    try {
+        return CACHEABLE_MEDIA_EXT.test(new URL(value).pathname);
+    }
+    catch {
+        return false;
+    }
 }
 /** Map a cacheable external URL to its same-origin proxy URL. `routePath`
  *  defaults to `/api/asset-cache` but is caller-configurable since the route
@@ -158,13 +161,16 @@ export function createAssetCache(opts, options = {}) {
     const suppliedDispatcher = options.dispatcher ?? opts.dispatcher;
     const dispatcher = suppliedDispatcher ?? createAssetCacheDispatcher({}, opts.lookupImpl ? { lookupImpl: opts.lookupImpl } : {});
     const inflight = new Map();
-    async function readFromDisk(key) {
+    async function readFromDisk({ key }, _options = {}) {
         const blobPath = path.join(cacheDir, key);
         const metaPath = `${blobPath}.json`;
         try {
             const [buf, metaRaw] = await Promise.all([readFile(blobPath), readFile(metaPath, 'utf8')]);
             const meta = JSON.parse(metaRaw);
-            const contentType = typeof meta.contentType === 'string' && meta.contentType ? meta.contentType : 'application/octet-stream';
+            const contentType = meta.contentType;
+            // Old cache entries must satisfy the same passive-media policy as new fetches.
+            if (typeof contentType !== 'string' || !CACHEABLE_MEDIA_MIME.has(contentType))
+                return null;
             return { buf, contentType };
         }
         catch {
@@ -179,15 +185,23 @@ export function createAssetCache(opts, options = {}) {
         await rename(tmpPath, blobPath);
         await writeFile(`${blobPath}.json`, JSON.stringify({ contentType: result.contentType }));
     }
-    function resolveContentType(headerValue, url) {
+    function resolveContentType({ headerValue, url }, _options = {}) {
+        // Moved from URL eligibility, which now uses URL.pathname instead of split:
+        // `String#split` always returns a non-empty array (even `''.split(x)` is
+        // `['']`), so index 0 is never `undefined` — the `!` narrows a
+        // `noUncheckedIndexedAccess` false positive, not a real fallback path.
         // `(headerValue ?? '')` is reachable (no content-type header at all). The
         // trailing `?? ''` after the optional-chained `.split(';')[0]?.trim()` is
         // not: `String#split` always returns a non-empty array, so `[0]` is never
         // `undefined` and `?.` never short-circuits — kept for
         // `noUncheckedIndexedAccess`, not a real fallback path.
         const header = (headerValue ?? '').split(';')[0].trim().toLowerCase();
-        if (/^(?:image|video|audio)\//.test(header))
+        if (CACHEABLE_MEDIA_MIME.has(header))
             return header;
+        // An explicit active/unsupported type must never be relabelled by its URL.
+        if (header && header !== 'application/octet-stream') {
+            throw new AssetCacheError(415, `unsupported content-type: ${header}`);
+        }
         const ext = path.posix.extname(url.pathname).toLowerCase();
         const guessed = EXT_TO_MIME[ext];
         if (guessed)
@@ -262,7 +276,7 @@ export function createAssetCache(opts, options = {}) {
             const declaredLength = Number(response.headers.get('content-length') ?? '');
             if (Number.isFinite(declaredLength))
                 assertWithinLimit(declaredLength);
-            const contentType = resolveContentType(response.headers.get('content-type'), url);
+            const contentType = resolveContentType({ headerValue: response.headers.get('content-type'), url });
             const buf = await readBodyCapped(response, controller);
             const result = { buf, contentType };
             try {
@@ -283,7 +297,7 @@ export function createAssetCache(opts, options = {}) {
         }
         const url = rawUrl.trim();
         const key = assetCacheKey(url);
-        const cached = await readFromDisk(key);
+        const cached = await readFromDisk({ key });
         if (cached)
             return cached;
         const existing = inflight.get(key);

package/dist/command.d.ts

@@ -17,7 +17,7 @@ export type CommandInvocationRequest = {
  * @param request - The command, optional args, and env to base the invocation on.
  * @returns The `{ command, args }` (plus `windowsVerbatimArguments` when a shim is used) to spawn.
  */
-export declare function createCommandInvocation({ args, command, env }: CommandInvocationRequest): CommandInvocation;
+export declare function createCommandInvocation({ args, command, env }: CommandInvocationRequest, _options?: {}): CommandInvocation;
 /**
  * Build the invocation for re-entering the repo-pinned package manager. Prefers
  * `npm_execpath` (routing Node-loadable managers through `process.execPath`),

package/dist/command.js

@@ -25,10 +25,13 @@ import { extname } from "node:path";
 // into one literal arg with the `%` preserved. The two layers cancel, so the
 // child receives the original arg byte-for-byte while cmd never has a chance
 // to expand anything inside it.
-function quoteWindowsCommandArg(value) {
-    if (!/[\s"&<>|^%]/.test(value))
+function quoteWindowsCommandArg({ value }, _options = {}) {
+    if (/[\r\n]/.test(value))
+        throw new Error("Windows command shim arguments cannot contain line breaks");
+    if (value !== "" && !/[\s"&<>|^%=,;()]/.test(value))
         return value;
-    const escaped = value.replace(/"/g, '""').replace(/%/g, '"^%"');
+    // Backslashes before the closing quote must survive the child's argv parser.
+    const escaped = value.replace(/"/g, '""').replace(/%/g, '"^%"').replace(/\\+$/, '$&$&');
     return `"${escaped}"`;
 }
 // Build the `cmd.exe /d /s /c "<line>"` invocation Node uses internally for
@@ -45,8 +48,8 @@ function quoteWindowsCommandArg(value) {
 // Without this, paths containing spaces (`C:\Users\First Last\...\foo.cmd`)
 // get split on the first space and cmd.exe reports "not recognized as an
 // internal or external command" — see issue #315.
-function buildCmdShimInvocation(command, args, env) {
-    const inner = [command, ...args].map(quoteWindowsCommandArg).join(" ");
+function buildCmdShimInvocation({ command, args, env }, _options = {}) {
+    const inner = [command, ...args].map((value) => quoteWindowsCommandArg({ value })).join(" ");
     return {
         args: ["/d", "/s", "/c", `"${inner}"`],
         command: env.ComSpec ?? process.env.ComSpec ?? "cmd.exe",
@@ -63,9 +66,9 @@ const nodeLoadablePackageManagerExtensions = new Set([".js", ".cjs", ".mjs"]);
  * @param request - The command, optional args, and env to base the invocation on.
  * @returns The `{ command, args }` (plus `windowsVerbatimArguments` when a shim is used) to spawn.
  */
-export function createCommandInvocation({ args = [], command, env = process.env }) {
+export function createCommandInvocation({ args = [], command, env = process.env }, _options = {}) {
     if (process.platform === "win32" && /\.(bat|cmd)$/i.test(command)) {
-        return buildCmdShimInvocation(command, args, env);
+        return buildCmdShimInvocation({ command, args, env });
     }
     return { args, command };
 }
@@ -94,7 +97,7 @@ export function createPackageManagerInvocation(args, env = process.env) {
     // package manager out of the box, while a bare `pnpm` only resolves when a
     // separate global install or a `corepack enable` shim is present. See #2438.
     if (process.platform === "win32") {
-        return buildCmdShimInvocation("corepack", ["pnpm", ...args], env);
+        return buildCmdShimInvocation({ command: "corepack", args: ["pnpm", ...args], env });
     }
     return { args: ["pnpm", ...args], command: "corepack" };
 }

package/dist/download.js

@@ -186,17 +186,16 @@ async function writeSentinel(basePath) {
         schemaVersion: STORE_SCHEMA_VERSION,
     });
 }
-async function resetOwnedBase(basePath) {
+/** Clear only this target's data after rechecking store ownership; keep its lock held. */
+async function resetOwnedTarget({ target }, _options = {}) {
+    const { basePath } = target;
     const sentinel = await readJson(join(basePath, STORE_SENTINEL));
     if (!isStoreSentinel(sentinel)) {
         throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.STORE_NOT_OWNED, `download base is not owned: ${basePath}`);
     }
-    const entries = await readdir(basePath).catch(() => []);
-    for (const entry of entries) {
-        await rm(join(basePath, entry), { force: true, recursive: true }).catch(() => undefined);
+    for (const path of [target.finalPath, target.partialPath, target.manifestPath]) {
+        await rm(path, { force: true }).catch(() => undefined);
     }
-    await writeSentinel(basePath);
-    await ensureStoreDirs(basePath);
 }
 async function ensureStoreDirs(basePath) {
     await mkdir(join(basePath, STATE_DIR), { recursive: true });
@@ -540,8 +539,8 @@ async function releaseLock(lock) {
         return;
     await rm(lock.path, { force: true }).catch(() => undefined);
 }
-async function suspiciousReset(target) {
-    await resetOwnedBase(target.basePath);
+async function suspiciousReset({ target }, _options = {}) {
+    await resetOwnedTarget({ target });
     return { manifest: null, reset: true };
 }
 async function loadReusableState(target) {
@@ -549,18 +548,18 @@ async function loadReusableState(target) {
     const finalExists = await pathExists(target.finalPath);
     const partialExists = await pathExists(target.partialPath);
     if (manifest === "invalid") {
-        return await suspiciousReset(target);
+        return await suspiciousReset({ target });
     }
     if (manifest == null) {
-        return finalExists || partialExists ? await suspiciousReset(target) : { manifest: null };
+        return finalExists || partialExists ? await suspiciousReset({ target }) : { manifest: null };
     }
     if (!manifestMatchesTarget(manifest, target)) {
-        return await suspiciousReset(target);
+        return await suspiciousReset({ target });
     }
     if (manifest.state === "complete")
         return await reusableCompleteState({ manifest, target });
     if (!partialExists)
-        return await suspiciousReset(target);
+        return await suspiciousReset({ target });
     return { manifest };
 }
 /** Reuse a complete download only when its final file exists and still hashes to the requested checksum. */
@@ -570,10 +569,10 @@ async function reusableCompleteState(input) {
     // maps to `null` and fails the checksum comparison into the same reset.
     const actual = await hashFile(target.finalPath, target.checksum.algorithm).catch(() => null);
     if (actual !== target.checksum.value)
-        return await suspiciousReset(target);
+        return await suspiciousReset({ target });
     const bytes = await statFileSize(target.finalPath);
     if (bytes == null)
-        return await suspiciousReset(target);
+        return await suspiciousReset({ target });
     return {
         manifest,
         result: {
@@ -591,13 +590,13 @@ async function reusableCompleteState(input) {
 async function runManagedDownload(target, options) {
     await ensureManagedBase(target.basePath);
     await pruneManagedDownloads({ basePath: target.basePath }).catch(() => undefined);
-    const held = { lock: await acquireLock(target) };
+    const lock = await acquireLock(target);
     try {
-        const state = await loadStateAllowingOneReset({ held, target });
+        const state = await loadStateAllowingOneReset({ target });
         if (state.result != null)
             return state.result;
         const download = await downloadWithRetries(target, state.manifest, options);
-        const bytes = await promoteVerifiedPartial(target);
+        const bytes = await promoteVerifiedPartial({ target });
         await writeJson(target.manifestPath, createManifest(target, "complete", { totalBytes: download.totalBytes }));
         return {
             bucket: target.bucket,
@@ -611,36 +610,31 @@ async function runManagedDownload(target, options) {
         };
     }
     finally {
-        await releaseLock(held.lock);
+        await releaseLock(lock);
     }
 }
-/** Load reusable state, re-locking and reloading once if the first load had to reset the managed base. */
-async function loadStateAllowingOneReset(input) {
-    const { held, target } = input;
+/** Reload once after target cleanup, retaining the lock until the run finishes. */
+async function loadStateAllowingOneReset({ target }, _options = {}) {
     const state = await loadReusableState(target);
     if (state.reset !== true)
         return state;
-    // A reset removes the lock as part of the managed base cleanup, so
-    // reacquire it before writing the fresh target state. `held.lock` is
-    // nulled first so a failed re-acquire never releases (deletes) a lock
-    // another process may have taken in the meantime.
-    await releaseLock(held.lock);
-    held.lock = null;
+    // Whole-base cleanup used to remove the lock and require re-acquisition.
+    // Keep it throughout target cleanup so another process cannot take it
+    // before we write fresh state, or have its own lock deleted by our finally.
     await ensureManagedBase(target.basePath);
-    held.lock = await acquireLock(target);
     const reloaded = await loadReusableState(target);
     if (reloaded.reset === true) {
-        throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.STORE_CORRUPT, "download state kept resetting after base cleanup");
+        throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.STORE_CORRUPT, "download state kept resetting after target cleanup");
     }
     return reloaded;
 }
 /** Verify the downloaded partial's checksum, promote it to the final path, and return the final size. */
-async function promoteVerifiedPartial(target) {
+async function promoteVerifiedPartial({ target }, _options = {}) {
     const actual = await hashFile(target.partialPath, target.checksum.algorithm).catch((error) => {
         throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.STORE_CORRUPT, `downloaded partial could not be hashed: ${errorMessage(error)}`);
     });
     if (actual !== target.checksum.value) {
-        await resetOwnedBase(target.basePath).catch(() => undefined);
+        await resetOwnedTarget({ target }).catch(() => undefined);
         throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.CHECKSUM_MISMATCH, "downloaded file checksum did not match requested payload", {
             actual,
             expected: target.checksum.value,
@@ -650,7 +644,7 @@ async function promoteVerifiedPartial(target) {
     if (await pathExists(target.finalPath)) {
         const existing = await hashFile(target.finalPath, target.checksum.algorithm).catch(() => null);
         if (existing !== target.checksum.value) {
-            await resetOwnedBase(target.basePath).catch(() => undefined);
+            await resetOwnedTarget({ target }).catch(() => undefined);
             throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.STORE_CORRUPT, "existing complete file did not match requested payload");
         }
         await rm(target.partialPath, { force: true }).catch(() => undefined);

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

@@ -86,7 +86,44 @@ export interface FetchWithTimeoutOptions {
     /** Milliseconds before the call is aborted. Pick one of {@link FETCH_TIMEOUT_MS}, or a specific
      * justified number for a call site that doesn't fit those classes. */
     timeoutMs: number;
+    /** Host-supplied transport; defaults to the global fetch. */
+    fetch?: typeof fetch;
 }
+/** 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. */
+    maxResponseBytes?: number;
+    /** Reject malformed UTF-8, including an incomplete trailing character. */
+    strictUtf8?: boolean;
+};
+/**
+ * Consumes a response as UTF-8, checking bytes before decoding/retaining each chunk.
+ * 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 {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.
+ * @complexity O(n) time and retained text for n bytes, bounded by the optional cap.
+ * The upstream stream controls the allocation of individual incoming chunks.
+ * @example readFetchResponseText({ response, maxResponseBytes: 1024, result: "details", onLimit: "truncate" })
+ */
+export declare function readFetchResponseText(input: {
+    response: Response;
+    maxResponseBytes: number;
+    result: "details";
+    onLimit?: "reject" | "truncate";
+    strictUtf8?: boolean;
+    signal?: AbortSignal;
+}): Promise<{
+    text: string;
+    byteLength: number;
+    truncated: boolean;
+}>;
+export declare function readFetchResponseText({ response }: {
+    response: Response;
+}, options?: TextReadOptions): Promise<string>;
 /**
  * `fetch`, but aborted after `options.timeoutMs` if it hasn't settled by then. If `init.signal` is
  * already set, the call aborts on EITHER that signal or the timeout, via `AbortSignal.any` — a
@@ -103,4 +140,21 @@ export interface FetchWithTimeoutOptions {
  * genuine network error) propagates unchanged.
  */
 export declare function fetchWithTimeout(url: string | URL, init: RequestInit | undefined, options: FetchWithTimeoutOptions): Promise<Response>;
+/**
+ * Fetches and consumes text inside one timeout scope. The returned response keeps its metadata
+ * and has a consumed body. No retries; other fetch/read errors propagate unchanged.
+ * @throws {FetchTimeoutError} The timeout ends fetch or body consumption before caller abort.
+ * @throws {RangeError | TypeError} See {@link readFetchResponseText} for opt-in guards.
+ * @complexity O(n) time and text storage for n response bytes, optionally capped.
+ */
+export declare function fetchTextWithTimeout(required: {
+    url: string | URL;
+    timeoutMs: number;
+    init?: RequestInit;
+}, optional?: TextReadOptions & {
+    fetch?: typeof fetch;
+}): Promise<{
+    response: Response;
+    text: string;
+}>;
 //# sourceMappingURL=fetch-with-timeout.d.ts.map

package/dist/fetch-with-timeout.js

@@ -87,6 +87,107 @@ export const FETCH_TIMEOUT_MS = {
      * legitimately still-generating request early. */
     GENERATE: 10 * 60_000,
 };
+export async function readFetchResponseText(input, { maxResponseBytes, strictUtf8 = false } = {}) {
+    const details = "result" in input && input.result === "details";
+    const options = details ? input : { ...(maxResponseBytes === undefined ? {} : { maxResponseBytes }), strictUtf8 };
+    validateTextReadOptions({ maxResponseBytes: options.maxResponseBytes, requireCap: details });
+    if (!details && options.maxResponseBytes === undefined && !options.strictUtf8)
+        return input.response.text();
+    const result = await consumeResponseText({ response: input.response, awaitCancel: !details }, options);
+    return details ? result : result.text;
+}
+/** Owns reader cleanup for every caller; legacy failure cleanup keeps its awaited behavior.
+ * Signal-driven callers skip that wait: a body that ignores its signal may never settle cancel. */
+async function consumeResponseText({ response, awaitCancel }, options = {}) {
+    options.signal?.throwIfAborted();
+    if (response.body === null)
+        return { text: "", byteLength: 0, truncated: false };
+    const reader = response.body.getReader();
+    let failed = true;
+    try {
+        const result = await decodeResponseStream({ reader }, options);
+        if (result.truncated)
+            void cancelResponseReader({ reader });
+        failed = false;
+        return result;
+    }
+    catch (error) {
+        const cancellation = cancelResponseReader({ reader, reason: error });
+        if (awaitCancel)
+            await cancellation;
+        throw error;
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch (error) {
+            if (!failed)
+                throw error;
+        }
+    }
+}
+/** Observe synchronous/asynchronous cancellation failure without masking the consumption outcome. */
+function cancelResponseReader({ reader, reason }) {
+    try {
+        return reader.cancel(reason).catch(() => { });
+    }
+    catch {
+        return Promise.resolve();
+    }
+}
+/** Reject invalid caps before consumption, including for empty responses. */
+function validateTextReadOptions({ maxResponseBytes, requireCap = false }) {
+    if (maxResponseBytes === undefined && !requireCap)
+        return;
+    if (typeof maxResponseBytes !== "number" || !Number.isSafeInteger(maxResponseBytes) || maxResponseBytes < 0) {
+        throw new RangeError("maxResponseBytes must be a nonnegative safe integer");
+    }
+}
+/** Byte counting precedes decoding; final flush detects truncated UTF-8 in strict mode.
+ * Retains only the allowed prefix, independently of upstream chunk size or headers. */
+async function decodeResponseStream({ reader }, { maxResponseBytes = Infinity, strictUtf8 = false, onLimit = "reject", signal } = {}) {
+    const decoder = new TextDecoder("utf-8", { fatal: strictUtf8 });
+    let total = 0;
+    let text = "";
+    for (;;) {
+        const { done, value } = await readResponseChunk({ reader, signal });
+        if (done)
+            break;
+        const remaining = maxResponseBytes - total;
+        if (value.byteLength > remaining) {
+            if (onLimit === "reject")
+                throw new RangeError(`response exceeds the ${maxResponseBytes}-byte limit`);
+            text += decoder.decode(value.subarray(0, remaining), { stream: true });
+            return { text: text + decoder.decode(), byteLength: maxResponseBytes, truncated: true };
+        }
+        total += value.byteLength;
+        text += decoder.decode(value, { stream: true });
+    }
+    return { text: text + decoder.decode(), byteLength: total, truncated: false };
+}
+/** Race one read against cancellation, removing the listener on every outcome.
+ * Per-read listeners avoid accumulating pending race handlers over a long response. */
+async function readResponseChunk({ reader, signal }) {
+    if (!signal)
+        return reader.read();
+    signal.throwIfAborted();
+    let abort = () => { };
+    try {
+        return await Promise.race([
+            new Promise((_resolve, reject) => {
+                abort = () => reject(signal.reason);
+                signal.addEventListener("abort", abort, { once: true });
+                if (signal.aborted)
+                    abort();
+            }),
+            Promise.resolve().then(() => { signal.throwIfAborted(); return reader.read(); }),
+        ]);
+    }
+    finally {
+        signal.removeEventListener("abort", abort);
+    }
+}
 /**
  * `fetch`, but aborted after `options.timeoutMs` if it hasn't settled by then. If `init.signal` is
  * already set, the call aborts on EITHER that signal or the timeout, via `AbortSignal.any` — a
@@ -103,11 +204,37 @@ export const FETCH_TIMEOUT_MS = {
  * genuine network error) propagates unchanged.
  */
 export async function fetchWithTimeout(url, init = {}, options) {
-    const { timeoutMs } = options;
+    return executeFetchWithTimeout({ url, init, timeoutMs: options.timeoutMs, consume: async ({ response }) => response }, options);
+}
+/**
+ * Fetches and consumes text inside one timeout scope. The returned response keeps its metadata
+ * and has a consumed body. No retries; other fetch/read errors propagate unchanged.
+ * @throws {FetchTimeoutError} The timeout ends fetch or body consumption before caller abort.
+ * @throws {RangeError | TypeError} See {@link readFetchResponseText} for opt-in guards.
+ * @complexity O(n) time and text storage for n response bytes, optionally capped.
+ */
+export async function fetchTextWithTimeout(required, optional = {}) {
+    return executeFetchWithTimeout({
+        url: required.url,
+        timeoutMs: required.timeoutMs,
+        init: required.init ?? {},
+        consume: async ({ response, signal }) => {
+            const { maxResponseBytes, strictUtf8 = false } = optional;
+            validateTextReadOptions({ maxResponseBytes });
+            // Always stream under the scope's signal: an injected fetch's body may ignore that signal,
+            // and only racing each read lets the timeout end consumption.
+            const read = await consumeResponseText({ response, awaitCancel: false }, { ...(maxResponseBytes === undefined ? {} : { maxResponseBytes }), strictUtf8, signal });
+            return { response, text: read.text };
+        },
+    }, optional);
+}
+/** Shared signal composition/error mapping; consumption decides the timeout scope's endpoint. */
+async function executeFetchWithTimeout({ url, init, timeoutMs, consume }, options = {}) {
     const timeoutSignal = AbortSignal.timeout(timeoutMs);
     const signal = init.signal ? AbortSignal.any([init.signal, timeoutSignal]) : timeoutSignal;
     try {
-        return await fetch(url, { ...init, signal });
+        const response = await (options.fetch ?? fetch)(url, { ...init, signal });
+        return await consume({ response, signal });
     }
     catch (error) {
         // `timeoutSignal` is the original object this function created, not the (possibly composed)

package/dist/fs/directory-user-config.js

@@ -68,7 +68,8 @@ export function createDirectoryUserConfig({ homeDir, defaultFolder, envName, pol
     }
     function configuredRoots(saved) {
         const fromEnv = env[policy.rootsEnvName];
-        return fromEnv !== undefined ? fromEnv.split(",").map((root) => root.trim()).filter(Boolean) : saved.siteRoots ?? policy.sourceRoots ?? [];
+        // Saved roots are extras; policy roots remain implicit unless the environment overrides them.
+        return fromEnv !== undefined ? fromEnv.split(",").map((root) => root.trim()).filter(Boolean) : [...(policy.sourceRoots ?? []), ...(saved.siteRoots ?? [])];
     }
     // Prefer explicit settings, never coerce an existing regular file into a directory.
     function assertDirectories(checked) {