@jerryan/just-bash 3.6.0 → 3.7.0

package/dist/commands/js-exec/js-exec.d.ts

@@ -7,6 +7,10 @@
  * This command is Node.js only (uses worker_threads).
  */
 import type { RuntimeCommand } from "../../types.js";
+/** @internal Set the idle-teardown delay — for focused lifecycle tests only. */
+export declare function _setJsExecWorkerIdleTimeoutMsForTests(ms: number): void;
+/** @internal Whether the shared worker is currently alive — for tests only. */
+export declare function _hasSharedJsExecWorkerForTests(): boolean;
 /** @internal Reset singleton worker state — for focused protocol tests only. */
 export declare function _resetJsExecWorkerForTests(): void;
 export declare const jsExecCommand: RuntimeCommand;

package/dist/commands/worker-bridge/bridge-handler.d.ts

@@ -12,9 +12,6 @@ export interface BridgeOutput {
     stderr: string;
     exitCode: number;
 }
-/**
- * Handles requests from a worker thread.
- */
 export declare class BridgeHandler {
     private fs;
     private cwd;
@@ -29,6 +26,10 @@ export declare class BridgeHandler {
     private outputLimitExceeded;
     private startTime;
     private timeoutMs;
+    /** Complete buffer of the last published oversized result, retained
+     * so the worker can fetch it in READ_RESULT_RANGE slices. Replaced on
+     * every publish. */
+    private lastResult;
     constructor(sharedBuffer: SharedArrayBuffer, fs: IFileSystem, cwd: string, commandName: string, secureFetch?: SecureFetch | undefined, maxOutputSize?: number, exec?: ((command: string, options: CommandExecOptions) => Promise<ExecResult>) | undefined, invokeTool?: ((path: string, argsJson: string) => Promise<string>) | undefined);
     /**
      * Returns remaining milliseconds before the overall execution deadline.
@@ -45,8 +46,13 @@ export declare class BridgeHandler {
     run(timeoutMs: number): Promise<BridgeOutput>;
     stop(): void;
     private handleOperation;
+    /** Publish a result of any size; oversized results are fetched by the
+     * worker in READ_RESULT_RANGE slices from the retained buffer. */
+    private publishResult;
+    private handleReadResultRange;
     private resolvePath;
     private handleReadFile;
+    private handleWriteFileRange;
     private handleWriteFile;
     private handleStat;
     private handleLstat;

package/dist/commands/worker-bridge/protocol.d.ts

@@ -33,6 +33,8 @@ export declare const OpCode: {
     readonly REALPATH: 13;
     readonly RENAME: 14;
     readonly COPY_FILE: 15;
+    readonly WRITE_FILE_RANGE: 17;
+    readonly READ_RESULT_RANGE: 18;
     readonly WRITE_STDOUT: 100;
     readonly WRITE_STDERR: 101;
     readonly EXIT: 102;
@@ -41,14 +43,34 @@ export declare const OpCode: {
     readonly INVOKE_TOOL: 400;
 };
 export type OpCodeType = (typeof OpCode)[keyof typeof OpCode];
-/** Status codes for synchronization */
-export declare const Status: {
-    readonly PENDING: 0;
-    readonly READY: 1;
-    readonly SUCCESS: 2;
-    readonly ERROR: 3;
+/**
+ * Two-word request/result state. The previous single STATUS word was
+ * written by THREE actors with TWO meanings (worker READY = "request
+ * published", host SUCCESS/ERROR = "result published", stop() READY =
+ * "wake for cancel") — a worker waiting for a result could observe a
+ * request-channel value and read a torn buffer (the CI flake class).
+ * Splitting the channels makes the torn state unrepresentable: a
+ * result wait is only ever woken by a result write. A state outside
+ * the tables on wake is a genuine protocol bug and fails loudly.
+ */
+/** Worker + stop() write; the host waits on this word. */
+export declare const RequestState: {
+    readonly IDLE: 0;
+    /** Worker has published an op. */
+    readonly REQUEST: 1;
+    /** stop() cancellation wake. The host treats any non-REQUEST wake as
+     * loop-abort (stop() also flips its `running` flag). */
+    readonly CANCELLED: 2;
 };
-export type StatusType = (typeof Status)[keyof typeof Status];
+type RequestStateType = (typeof RequestState)[keyof typeof RequestState];
+/** Host writes; the worker waits on this word. stop() never touches
+ * it, so a result wait cannot be torn by cancellation. */
+export declare const ResultState: {
+    readonly NONE: 0;
+    readonly SUCCESS: 1;
+    readonly ERROR: 2;
+};
+type ResultStateType = (typeof ResultState)[keyof typeof ResultState];
 /** Error codes */
 export declare const ErrorCode: {
     readonly NONE: 0;
@@ -59,11 +81,35 @@ export declare const ErrorCode: {
     readonly PERMISSION_DENIED: 5;
     readonly INVALID_PATH: 6;
     readonly IO_ERROR: 7;
-    readonly TIMEOUT: 8;
     readonly NETWORK_ERROR: 9;
     readonly NETWORK_NOT_CONFIGURED: 10;
+    readonly NOT_EMPTY: 11;
+    readonly LOOP: 12;
+    readonly FILE_TOO_LARGE: 13;
+    readonly NO_SPACE: 14;
+    readonly BUSY: 15;
+    readonly READ_ONLY: 16;
+    readonly CROSS_DEVICE: 17;
 };
 export type ErrorCodeType = (typeof ErrorCode)[keyof typeof ErrorCode];
+/**
+ * The canonical errno-name <-> wire-code table. Both bridge sides ship
+ * together, so the table lives here (not per-side copies): the host
+ * maps thrown errnos to wire codes with it, and workers derive guest-
+ * facing codes from its inverse via wireToErrnoName(). EPERM precedes
+ * EACCES so the inverse prefers the common node spelling.
+ */
+export declare const ERRNO_TO_WIRE: Record<string, ErrorCodeType>;
+/** Errno name for a wire code, or undefined for non-errno wire codes
+ * (NONE, IO_ERROR, network conditions). PERMISSION_DENIED inverts to
+ * EACCES (the more common spelling in node guests). */
+export declare function wireToErrnoName(code: number): string | undefined;
+/** Buffer sizes */
+export declare const Size: {
+    readonly PATH_BUFFER: 4096;
+    readonly DATA_BUFFER: 8388608;
+    readonly TOTAL: 8392740;
+};
 /** Flags for operations */
 export declare const Flags: {
     readonly NONE: 0;
@@ -82,8 +128,10 @@ export declare class ProtocolBuffer {
     constructor(buffer: SharedArrayBuffer);
     getOpCode(): OpCodeType;
     setOpCode(code: OpCodeType): void;
-    getStatus(): StatusType;
-    setStatus(status: StatusType): void;
+    getRequest(): RequestStateType;
+    setRequest(request: RequestStateType): void;
+    getResultState(): ResultStateType;
+    setResultState(state: ResultStateType): void;
     getPathLength(): number;
     setPathLength(length: number): void;
     getDataLength(): number;
@@ -104,6 +152,13 @@ export declare class ProtocolBuffer {
     setDataFromString(str: string): void;
     getResult(): Uint8Array;
     setResult(data: Uint8Array): void;
+    /**
+     * Publish a result of ANY size: the first DATA_BUFFER bytes land in
+     * the data region and RESULT_LENGTH carries the FULL length. The
+     * worker detects the overflow and fetches the rest with
+     * READ_RESULT_RANGE ops (served from the host's retained buffer).
+     */
+    setResultPrefix(data: Uint8Array): void;
     getResultAsString(): string;
     setResultFromString(str: string): void;
     encodeStat(stat: {
@@ -122,20 +177,16 @@ export declare class ProtocolBuffer {
         size: number;
         mtime: Date;
     };
-    waitForReady(timeout?: number): "ok" | "timed-out" | "not-equal";
-    waitForReadyAsync(timeout?: number): {
-        async: false;
-        value: "not-equal" | "timed-out";
-    } | {
-        async: true;
-        value: Promise<"ok" | "timed-out">;
-    };
     /**
-     * Wait for status to become READY.
-     * Returns immediately if status is already READY, or waits until it changes.
+     * Wait for the request word to become REQUEST.
+     * Returns immediately if already REQUEST; CANCELLED or any unexpected
+     * state returns false (the caller's running-flag check aborts the loop).
      */
     waitUntilReady(timeout: number): Promise<boolean>;
+    /** Worker-side blocking wait on the RESULT word (host writes). */
     waitForResult(timeout?: number): "ok" | "timed-out" | "not-equal";
-    notify(): number;
+    notifyRequest(): number;
+    notifyResult(): number;
     reset(): void;
 }
+export {};

package/dist/commands/worker-bridge/sync-backend.d.ts

@@ -12,6 +12,9 @@ export declare class SyncBackend {
     private operationTimeoutMs;
     constructor(sharedBuffer: SharedArrayBuffer, operationTimeoutMs?: number);
     private execSync;
+    /** Build an op failure that preserves the bridge's numeric error code,
+     * so downstream errno mapping prefers it over substring matching. */
+    private opError_;
     readFile(path: string): Uint8Array;
     writeFile(path: string, data: Uint8Array): void;
     stat(path: string): {

package/dist/fs/fs-error.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Filesystem error carrying its errno as a STRUCTURED field.
+ *
+ * The contract: the errno is chosen at the throw site and carried on
+ * `.code`; consumers read `.code` and never re-derive it from message
+ * prose. There is deliberately NO message-parsing fallback here —
+ * parsing "CODE:" prefixes back out of strings is the legacy path this
+ * module replaces, and keeping it would leave two sources of truth
+ * (the field and the phrasing) with an illusion of robustness.
+ *
+ * Message format is preserved as a DISPLAY convention only: FsError
+ * renders `${code}: ${message}` so existing user-facing text and
+ * message-asserting tests are unchanged. The prefix is produced FROM
+ * the code, never parsed back INTO one.
+ *
+ * Contract for IFileSystem implementations (documented on the
+ * interface): throw FsError, or any node-style error with a string
+ * `.code`. Errors without a structured code are coerced to EIO at
+ * classification boundaries (toFsError) — an honest unknown, never a
+ * fabricated specific errno.
+ */
+export declare class FsError extends Error {
+    readonly code: string;
+    /** The message WITHOUT the "CODE: " transport prefix — what
+     * user-facing display paths should render. */
+    readonly bareMessage: string;
+    constructor(code: string, message: string);
+}
+/** Extract a structured errno from any thrown value, or undefined when
+ * the value carries none (bare Errors, strings, foreign objects). */
+export declare function fsErrorCode(err: unknown): string | undefined;
+/** True when the error carries the given structured errno. */
+export declare function isFsErrorCode(err: unknown, code: string): boolean;
+/**
+ * Classify any thrown value at a boundary: structured codes pass
+ * through unchanged; everything else becomes the fallback (EIO by
+ * default) with the original message preserved. Provided as PUBLIC API
+ * for custom IFileSystem implementations and host-side adapters that
+ * need to normalize third-party errors before handing them to
+ * just-bash internals. Internally, boundaries that only need the code
+ * (e.g. the worker bridge) read fsErrorCode directly instead.
+ */
+export declare function toFsError(err: unknown, fallbackCode?: string): FsError;

package/dist/fs/interface.d.ts

@@ -96,6 +96,19 @@ export interface CpOptions {
  * - InMemoryFs (in-memory, default)
  * - Real filesystem (via node:fs)
  * - Custom implementations (e.g., remote storage, browser IndexedDB)
+ *
+ * ERROR CONTRACT: implementations signal failure kind by throwing
+ * {@link FsError} (or any node-style error with a string `.code`
+ * property) using POSIX errno names — `"ENOENT"`, `"EACCES"`,
+ * `"EEXIST"`, `"ENOTDIR"`, `"EISDIR"`, `"ENOTEMPTY"`, `"EPERM"`,
+ * `"EINVAL"`, `"EBUSY"`, `"ELOOP"`, `"EFBIG"`, `"EXDEV"`, `"ENOSPC"`,
+ * `"EROFS"`, `"EIO"`. Consumers
+ * (commands, bridged runtimes like python3, and error mappings) read
+ * the code from `.code`; they never parse it out of message prose.
+ * Errors with no structured code are classified at the boundary as
+ * EIO — an honest unknown, never a fabricated specific errno.
+ * Message text is free-form; by convention FsError renders
+ * `"ECODE: message"` for display.
  */
 export interface IFileSystem {
     /**

package/dist/fs/mountable-fs/mountable-fs.d.ts

@@ -1,5 +1,6 @@
 import { type ByteString } from "../../encoding.js";
 import type { BufferEncoding, CpOptions, FileContent, FsStat, IFileSystem, MkdirOptions, ReadFileOptions, RmOptions, WriteFileOptions } from "../interface.js";
+import type { OverlayDiff } from "../overlay-fs/overlay-fs.js";
 /**
  * Configuration for a mount point
  */
@@ -58,6 +59,25 @@ export declare class MountableFs implements IFileSystem {
         mountPoint: string;
         filesystem: IFileSystem;
     }>;
+    /**
+     * Combined change set across all diff-capable mounts. `space` selects
+     * the path form: "vfs" (default) keeps full virtual paths (mount
+     * prefix retained — directly replayable by a template merge);
+     * "host" maps each entry to its real-absolute host path (for
+     * template.apply / applyDiffToRealFs). The base fs is shared scratch
+     * and is not diffed. Mounts without a diff() method fail loudly —
+     * a merged view cannot silently omit a mount's changes.
+     */
+    diff(options?: {
+        space?: "vfs" | "host";
+    }): OverlayDiff;
+    /**
+     * Reconciliation support (template merge replay): set the changedAt
+     * ordering stamp of the node at `path` and its ancestors, routing to
+     * the owning mount. Paths outside every mount (shared scratch) have
+     * no stampable overlay and are ignored.
+     */
+    restamp(path: string, changedAt: number, scope?: "full" | "ancestors"): void;
     /**
      * Check if a path is exactly a mount point.
      */

package/dist/fs/overlay-fs/apply.d.ts

@@ -17,6 +17,20 @@ export declare function removeFromRealFs(path: string): void;
  * symlinks are recreated with the recorded target; files get the recorded
  * content (unless metadataOnly — a chmod/utimes copy-up), the recorded
  * mode (POSIX only — mode bits are advisory on Windows), and the recorded
- * mtime restored after the content write.
+ * mtime restored after the content write. A type-conflicting on-disk
+ * target is replaced (the change-set supersedes the base).
  */
 export declare function applyWriteToRealFs(path: string, write: Omit<OverlayWrite, "path">): void;
+/**
+ * Apply a change set with real absolute paths to the real filesystem:
+ * deletions first (deepest path first, so subtrees go before their
+ * parents), then writes (shallowest first, so explicit directory
+ * entries land before their children). Standalone counterpart of
+ * AgentSandbox.applyChanges for the fork model — no overlay instance
+ * is involved and nothing is dropped; the caller owns the overlays'
+ * lifecycle (typically: discard after diff()).
+ */
+export declare function applyDiffToRealFs(diff: {
+    writes: OverlayWrite[];
+    deletions: string[];
+}): void;

package/dist/fs/overlay-fs/index.d.ts

@@ -1 +1,2 @@
+export { applyDiffToRealFs } from "./apply.js";
 export { type OverlayDiff, OverlayFs, type OverlayFsOptions, type OverlayNodeType, type OverlayWrite, } from "./overlay-fs.js";

package/dist/fs/overlay-fs/overlay-fs.d.ts

@@ -48,6 +48,13 @@ export interface OverlayWrite {
     mode: number;
     /** Modification time; hosts may apply it (utimes) for fidelity. */
     mtime: Date;
+    /**
+     * Wall-clock time the overlay recorded this mutation (attach or last
+     * in-place change). Unlike `mtime` this cannot be set from inside the
+     * sandbox, which makes it the trustworthy ordering key for merging
+     * change sets from independent overlays (see mergeDiffs).
+     */
+    changedAt?: number;
     /**
      * When true, only metadata changed (chmod/utimes via a metacopy shadow):
      * apply `mode` and `mtime` and never touch file content.
@@ -70,6 +77,13 @@ export interface OverlayDiff {
      * never nest, so each entry is a top-most deletion covering its subtree.
      */
     deletions: string[];
+    /**
+     * Wall-clock creation time of each whiteout, aligned with `deletions`
+     * (same order). Overlay-assigned and untamperable — the ordering key
+     * for merging deletions against writes from other overlays. Present
+     * whenever `deletions` is non-empty; absent otherwise.
+     */
+    deletionChangedAt?: number[];
 }
 export interface OverlayFsOptions {
     /**
@@ -116,6 +130,20 @@ export declare class OverlayFs implements IFileSystem {
     private readonly allowSymlinks;
     private readonly tree;
     private nextMemoryIdentity;
+    /** The real directory this overlay reads through and diffs against. */
+    get rootDir(): string;
+    /**
+     * Reconciliation support (template merge replay, host-side change-set
+     * application): stamp the node at `path` with `changedAt` (the
+     * replayed entry's own stamp), and correct any NEWER stamps among its
+     * ancestors and descendants. Post-sort, a newer stamp can only be a
+     * fresh wall-clock stamp minted by the replay op itself (ensured
+     * parents, resurrection whiteouts) — those belong to the replayed
+     * entry and take its stamp; earlier replayed entries (older stamps)
+     * are never touched. This is a host-side reconciliation API, not a
+     * guest operation: changedAt is the ordering key merges rely on.
+     */
+    restamp(path: string, changedAt: number, scope?: "full" | "ancestors"): void;
     private identityFor;
     constructor(options: OverlayFsOptions);
     /**
@@ -285,6 +313,9 @@ export declare class OverlayFs implements IFileSystem {
      */
     private inheritedMode;
     appendFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
+    /** Append to an existing upper file node, completing a metacopy
+     * copy-up first when needed (preserving the node's upper mode). */
+    private appendToExisting_;
     exists(path: string): Promise<boolean>;
     stat(path: string, seen?: Set<string>): Promise<FsStat>;
     lstat(path: string): Promise<FsStat>;

package/dist/fs/overlay-fs/overlay-tree.d.ts

@@ -36,6 +36,21 @@ export interface OverlayFileNode {
     lowerSize?: number;
     /** Append segments retained without copying the complete file per append. */
     appendChunks?: Uint8Array[];
+    /**
+     * Mutation sequence stamp (tree-local, monotonically increasing).
+     * Set by in-place mutations (appendChunk, chmod, utimes) so sync()
+     * can compare-and-swap: an entry checked against disk is only
+     * detached if it has not been mutated since the check began.
+     * Node replacement (attach/detach) needs no stamp — object identity
+     * already changes. Undefined means never mutated in place.
+     */
+    seq?: number;
+    /**
+     * Wall-clock time of the last mutation (attach/touch), stamped by the
+     * tree. Distinct from `mtime`: user-visible and utimes-able, whereas
+     * changedAt is the untamperable ordering key mergeDiffs relies on.
+     */
+    changedAt?: number;
     mode: number;
     mtime: Date;
     identity?: string;
@@ -44,6 +59,10 @@ export interface OverlayDirNode {
     type: "directory";
     /** Child nodes keyed by name segment, in insertion order. */
     children: Map<string, OverlayNode>;
+    /** In-place mutation stamp (see OverlayFileNode.seq). */
+    seq?: number;
+    /** Wall-clock time of the last mutation (see OverlayFileNode.changedAt). */
+    changedAt?: number;
     mode: number;
     mtime: Date;
     identity?: string;
@@ -51,12 +70,18 @@ export interface OverlayDirNode {
 export interface OverlaySymlinkNode {
     type: "symlink";
     target: string;
+    /** In-place mutation stamp (see OverlayFileNode.seq). */
+    seq?: number;
+    /** Wall-clock time of the last mutation (see OverlayFileNode.changedAt). */
+    changedAt?: number;
     mode: number;
     mtime: Date;
 }
 /** Leaf marker hiding a lower-layer (real-FS) path and everything under it. */
 export interface OverlayWhiteoutNode {
     type: "whiteout";
+    /** Wall-clock time the whiteout was created (merge ordering). */
+    changedAt?: number;
 }
 export type OverlayEntryNode = OverlayFileNode | OverlayDirNode | OverlaySymlinkNode;
 export type OverlayNode = OverlayEntryNode | OverlayWhiteoutNode;
@@ -101,6 +126,7 @@ export declare class OverlayTree {
     private readonly maxMemoryBytes;
     private rootNode;
     private bytes;
+    private mutationSeq_;
     constructor(maxMemoryBytes: number);
     /** The root directory node — the VFS root ("/"). */
     get root(): OverlayDirNode;
@@ -160,6 +186,19 @@ export declare class OverlayTree {
      * Append a chunk to a file node, accounting its bytes against capacity.
      */
     appendChunk(node: OverlayFileNode, chunk: Uint8Array): void;
+    /** Stamp a node as mutated in place (see OverlayFileNode.seq). */
+    touch(node: {
+        seq?: number;
+        changedAt?: number;
+    }): void;
+    /**
+     * Compare-and-swap detach: remove the node at `path` only if it is
+     * still the exact same object with the same mutation sequence — i.e.
+     * nothing changed it while the caller's (async) verification ran.
+     * Also refuses to detach a directory that has gained children.
+     * Returns whether the detach happened.
+     */
+    detachIfUnchanged(path: string, node: OverlayNode, seq?: number): boolean;
     /**
      * Yield every node, parents before children (pre-order), starting with the
      * root at path "/". Whiteouts are included; callers filter as needed.

package/dist/fs/path-utils.d.ts

@@ -39,6 +39,11 @@ export declare function resolvePath(base: string, path: string): string;
  * Join a parent path with a child name.
  * Handles the root-path edge case (`"/" + "child"` → `"/child"`).
  */
+/** Convert an OS-form path fragment to VFS slash form (win32
+ * backslashes become slashes; on POSIX this is a no-op). VFS paths are
+ * always slash-form — use when reconstructing a virtual path from a
+ * real-OS path (e.g. slicing off a real root). */
+export declare function toVirtualSlashes(path: string): string;
 export declare function joinPath(parent: string, child: string): string;
 /**
  * Resolve a symlink target relative to the symlink's location.

package/dist/fs/vfs-template.d.ts

@@ -0,0 +1,74 @@
+import { MountableFs } from "./mountable-fs/mountable-fs.js";
+import type { OverlayDiff } from "./overlay-fs/overlay-fs.js";
+/** One privatized subtree: virtual mount point + real backing root. */
+export interface VfsTemplateMount {
+    /** Virtual absolute path the overlay serves (e.g. "/project"). */
+    at: string;
+    /** Real absolute directory the overlay reads through and diffs against. */
+    root: string;
+}
+export interface VfsTemplateOptions {
+    /**
+     * Subtrees privatized per fork. Everything else (/, /tmp, ...) lives
+     * in the template's shared scratch memory fs: writes there are
+     * visible to every fork immediately and never appear in diffs.
+     */
+    mounts: VfsTemplateMount[];
+    /**
+     * Per-overlay content-byte budget (OverlayFs maxMemoryBytes),
+     * bounding each fork's copy-up memory. Default: the OverlayFs
+     * default.
+     */
+    maxMemoryBytes?: number;
+}
+/**
+ * Template for cheap parallel forks (see
+ * docs/design/vfs-template-fork-model.md). The template owns the shared
+ * scratch fs and the mount configuration; each fork() stamps out a
+ * ready MountableFs with fresh copy-on-write overlays over every
+ * mounted real root. Forks are unmanaged: the template keeps no
+ * registry, consumes nothing, and never tracks lifecycles.
+ *
+ * MERGE IS A REPLAY. `merge` combines the given change sets (fork
+ * instances are diffed in vfs space; plain diffs pass through), orders
+ * every entry by (changedAt, input order), and applies the entries to a
+ * fresh fork with the stock filesystem operations — the same codepath
+ * the forks themselves used, over the same lower. Anything the
+ * filesystem refuses (write under a file, chmod of a deleted path, ...)
+ * is skipped, which keeps conflicting (racy) input deterministic and
+ * contained to the conflicted path. After each replayed operation the
+ * touched node's changedAt is rewritten from the replay position, so
+ * merged output is byte-deterministic and wall-clock-free. The merged
+ * fork is returned: diff it and discard it, or keep working on it.
+ *
+ * ```ts
+ * const tpl = createVfsTemplate({ mounts: [{ at: "/project", root: projDir }] });
+ * const a = tpl.fork();
+ * const b = tpl.fork();
+ * await Promise.all([runAgent(a), runAgent(b)]);
+ * const merged = await tpl.merge([a, b]);
+ * tpl.apply(merged.diff({ space: "host" }));
+ * ```
+ */
+export interface VfsTemplate {
+    /** A fresh per-call filesystem: shared scratch + fresh overlays. */
+    fork(): MountableFs;
+    /**
+     * Replay the given sources' change sets onto a fresh fork and return
+     * it. Sources may be fork instances (diffed in vfs space) or plain
+     * diffs (e.g. serialized across a process boundary). Array order is
+     * the tie-break for equal changedAt stamps. Entries outside every
+     * mount point replay into the shared scratch (ordinary fork
+     * semantics, never reported in diff()) — merge expects diffs in
+     * this template's vfs space.
+     */
+    merge(sources: Array<MountableFs | OverlayDiff>): Promise<MountableFs>;
+    /**
+     * Validate a merged host-space diff against the mount map (every
+     * entry inside a registered root, no symlink writes, no root-self
+     * deletion) and apply it to the real filesystem. Type-conflicting
+     * on-disk targets are replaced (the change-set supersedes the base).
+     */
+    apply(merged: OverlayDiff): void;
+}
+export declare function createVfsTemplate(options: VfsTemplateOptions): VfsTemplate;

package/dist/index.d.cts

@@ -8,11 +8,13 @@ export type { CommandContextOptions, CustomCommand, LazyCommand, } from "./custo
 export { createCommandContext, defineCommand, } from "./custom-commands.js";
 export type { ByteString, OutputKind } from "./encoding.js";
 export { bytesOutput, decodeBytesToUtf8, EMPTY_BYTES, encodeUtf8ToBytes, latin1FromBytes, stdoutAsBytes, stdoutKind, textOutput, unsafeBytesFromLatin1, } from "./encoding.js";
+export { FsError, fsErrorCode, isFsErrorCode, toFsError, } from "./fs/fs-error.js";
 export { InMemoryFs } from "./fs/in-memory-fs/index.js";
 export type { BufferEncoding, CpOptions, DirectoryEntry, FileContent, FileEntry, FileInit, FileSystemFactory, FsEntry, FsStat, InitialFiles, LazyFileEntry, LazyFileProvider, MkdirOptions, RmOptions, SymlinkEntry, } from "./fs/interface.js";
 export { MountableFs, type MountableFsOptions, type MountConfig, } from "./fs/mountable-fs/index.js";
-export { type OverlayDiff, OverlayFs, type OverlayFsOptions, type OverlayNodeType, type OverlayWrite, } from "./fs/overlay-fs/index.js";
+export { applyDiffToRealFs, type OverlayDiff, OverlayFs, type OverlayFsOptions, type OverlayNodeType, type OverlayWrite, } from "./fs/overlay-fs/index.js";
 export { ReadWriteFs, type ReadWriteFsOptions, } from "./fs/read-write-fs/index.js";
+export { createVfsTemplate, type VfsTemplate, type VfsTemplateMount, type VfsTemplateOptions, } from "./fs/vfs-template.js";
 export type { AllowedUrl, AllowedUrlEntry, NetworkConfig, RequestTransform, SecureFetch, } from "./network/index.js";
 export { NetworkAccessDeniedError, RedirectNotAllowedError, TooManyRedirectsError, } from "./network/index.js";
 export { parse } from "./parser/parser.js";

package/dist/index.d.ts

@@ -8,11 +8,13 @@ export type { CommandContextOptions, CustomCommand, LazyCommand, } from "./custo
 export { createCommandContext, defineCommand, } from "./custom-commands.js";
 export type { ByteString, OutputKind } from "./encoding.js";
 export { bytesOutput, decodeBytesToUtf8, EMPTY_BYTES, encodeUtf8ToBytes, latin1FromBytes, stdoutAsBytes, stdoutKind, textOutput, unsafeBytesFromLatin1, } from "./encoding.js";
+export { FsError, fsErrorCode, isFsErrorCode, toFsError, } from "./fs/fs-error.js";
 export { InMemoryFs } from "./fs/in-memory-fs/index.js";
 export type { BufferEncoding, CpOptions, DirectoryEntry, FileContent, FileEntry, FileInit, FileSystemFactory, FsEntry, FsStat, InitialFiles, LazyFileEntry, LazyFileProvider, MkdirOptions, RmOptions, SymlinkEntry, } from "./fs/interface.js";
 export { MountableFs, type MountableFsOptions, type MountConfig, } from "./fs/mountable-fs/index.js";
-export { type OverlayDiff, OverlayFs, type OverlayFsOptions, type OverlayNodeType, type OverlayWrite, } from "./fs/overlay-fs/index.js";
+export { applyDiffToRealFs, type OverlayDiff, OverlayFs, type OverlayFsOptions, type OverlayNodeType, type OverlayWrite, } from "./fs/overlay-fs/index.js";
 export { ReadWriteFs, type ReadWriteFsOptions, } from "./fs/read-write-fs/index.js";
+export { createVfsTemplate, type VfsTemplate, type VfsTemplateMount, type VfsTemplateOptions, } from "./fs/vfs-template.js";
 export type { AllowedUrl, AllowedUrlEntry, NetworkConfig, RequestTransform, SecureFetch, } from "./network/index.js";
 export { NetworkAccessDeniedError, RedirectNotAllowedError, TooManyRedirectsError, } from "./network/index.js";
 export { parse } from "./parser/parser.js";

package/dist/interpreter/builtin-dispatch.d.ts

@@ -21,6 +21,16 @@ export type ExecuteUserScriptFn = (scriptPath: string, args: string[], stdin?: s
 /**
  * Dispatch context containing dependencies needed for builtin dispatch
  */
+/** Stdio contract passed to builtin handlers. */
+export interface BuiltinIo {
+    stdin: string;
+    /** True when a redirection gave this command its own fd 0. `stdin`
+     * alone cannot express it: `cmd < empty-file` and an unredirected
+     * command both arrive as `""`, but only the first means EOF rather
+     * than "inherit the shell's stdin". */
+    stdinRedirected: boolean;
+    stdinSourceFd: number;
+}
 export interface BuiltinDispatchContext {
     ctx: InterpreterContext;
     runCommand: RunCommandFn;