@demicodes/shell 0.14.1 → 0.15.0

package/dist/{host-DIg4RxcL.d.mts → host-B-oKG7x5.d.mts}

@@ -1,6 +1,15 @@
 //#region src/host.d.ts
 interface Host {
   defaultCwd: string;
+  /**
+   * Directory where command artifacts (stdout.txt / stderr.txt / stdout.bin /
+   * meta.json) are written as plain files, laid out as
+   * `<dir>/<storageId>/<commandId>/`. Contract: the path is reachable through
+   * `fs` AND visible to processes started via `process.spawn` — one shared
+   * filesystem namespace, so any tool (portable or real) can read and search
+   * artifacts with ordinary file operations.
+   */
+  commandArtifactsDir: string;
   fs: HostFileSystem;
   process: HostProcess;
   store: HostStore;

package/dist/host-fs.d.mts

@@ -1,28 +1,21 @@
-import { t as Host } from "./host-DIg4RxcL.mjs";
+import { t as Host } from "./host-B-oKG7x5.mjs";
 import { BufferEncoding, CpOptions, DirentEntry, FileContent, FsStat, IFileSystem, MkdirOptions, ReadFileOptions, RmOptions, WriteFileOptions } from "@demicodes/just-bash/fs/interface";
 //#region src/host-fs.d.ts
-type VirtualFileSystemNode = {
-  kind: 'file';
-  content: Uint8Array;
-  mode?: number;
-  mtime?: Date;
-} | {
-  kind: 'directory';
-  entries: DirentEntry[];
-  mode?: number;
-  mtime?: Date;
-};
-interface VirtualFileSystemProvider {
-  lookup(path: string): Promise<VirtualFileSystemNode | null> | VirtualFileSystemNode | null;
+interface HostBackedFileSystemOptions {
+  /**
+   * Ceiling for a single file read through this filesystem. Portable commands
+   * (cat/grep/rg/head/...) run in-process and load files whole, so one read of
+   * an oversized file becomes resident memory in the embedding host — a broad
+   * scan over a large tree can balloon the process by gigabytes. Oversized
+   * files fail loudly instead; real-process routes (`bash -c`) stay available
+   * for genuinely large files.
+   */
+  maxFileReadBytes?: number;
 }
-/** Builds a virtual directory node; entry names containing a dot are treated as files. */
-declare function virtualDirectory(names: string[]): VirtualFileSystemNode;
-/** Builds a virtual file node from raw bytes. */
-declare function virtualFile(content: Uint8Array): VirtualFileSystemNode;
 declare class HostBackedFileSystem implements IFileSystem {
   private readonly host;
-  private readonly virtualProvider?;
-  constructor(host: Host, virtualProvider?: VirtualFileSystemProvider | undefined);
+  private readonly maxFileReadBytes;
+  constructor(host: Host, options?: HostBackedFileSystemOptions);
   readFile(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
   readFileBuffer(path: string): Promise<Uint8Array>;
   writeFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
@@ -44,8 +37,6 @@ declare class HostBackedFileSystem implements IFileSystem {
   readlink(path: string): Promise<string>;
   realpath(path: string): Promise<string>;
   utimes(path: string, atime: Date, mtime: Date): Promise<void>;
-  private lookupVirtual;
-  private assertWritablePath;
 }
 //#endregion
-export { HostBackedFileSystem, VirtualFileSystemNode, VirtualFileSystemProvider, virtualDirectory, virtualFile };
+export { HostBackedFileSystem, HostBackedFileSystemOptions };

package/dist/host-fs.mjs

@@ -1,78 +1,40 @@
 import { decodeUtf8, encodeUtf8, isAbsolutePath, normalizePath } from "@demicodes/utils";
 //#region src/host-fs.ts
-/** Builds a virtual directory node; entry names containing a dot are treated as files. */
-function virtualDirectory(names) {
-	return {
-		kind: "directory",
-		entries: names.sort().map((name) => ({
-			name,
-			isFile: name.includes("."),
-			isDirectory: !name.includes("."),
-			isSymbolicLink: false
-		}))
-	};
-}
-/** Builds a virtual file node from raw bytes. */
-function virtualFile(content) {
-	return {
-		kind: "file",
-		content
-	};
-}
+const DEFAULT_FILE_READ_LIMIT_BYTES = 67108864;
 var HostBackedFileSystem = class {
 	host;
-	virtualProvider;
-	constructor(host, virtualProvider) {
+	maxFileReadBytes;
+	constructor(host, options = {}) {
 		this.host = host;
-		this.virtualProvider = virtualProvider;
+		this.maxFileReadBytes = options.maxFileReadBytes ?? DEFAULT_FILE_READ_LIMIT_BYTES;
 	}
 	async readFile(path, options) {
 		return decodeBytes(await this.readFileBuffer(path), encodingFrom(options));
 	}
 	async readFileBuffer(path) {
-		const virtual = await this.lookupVirtual(path);
-		if (virtual) {
-			if (virtual.kind !== "file") throw new Error(`EISDIR: illegal operation on a directory, read '${path}'`);
-			return virtual.content;
-		}
+		const stat = await this.host.fs.stat(path, { cwd: this.host.defaultCwd });
+		if (stat.isFile && stat.size > this.maxFileReadBytes) throw new Error(`EFBIG: file exceeds the ${this.maxFileReadBytes}-byte in-shell read limit (${stat.size} bytes), read '${path}'; read a slice instead, or process it with a real process via 'bash -c'`);
 		return this.host.fs.readFile(path, { cwd: this.host.defaultCwd });
 	}
 	async writeFile(path, content, options) {
-		this.assertWritablePath(path);
 		await this.host.fs.writeFile(path, encodeContent(content, encodingFrom(options)), { cwd: this.host.defaultCwd });
 	}
 	async appendFile(path, content, options) {
-		this.assertWritablePath(path);
 		await this.host.fs.appendFile(path, encodeContent(content, encodingFrom(options)), { cwd: this.host.defaultCwd });
 	}
 	async exists(path) {
-		if (isVirtualPath(path)) return await this.lookupVirtual(path) !== null;
 		return this.host.fs.exists(path, { cwd: this.host.defaultCwd });
 	}
 	async stat(path) {
-		const virtual = await this.lookupVirtual(path);
-		if (virtual) return virtualStat(virtual);
 		return toFsStat(await this.host.fs.stat(path, { cwd: this.host.defaultCwd }));
 	}
 	async lstat(path) {
-		const virtual = await this.lookupVirtual(path);
-		if (virtual) return virtualStat(virtual);
 		return toFsStat(await this.host.fs.lstat(path, { cwd: this.host.defaultCwd }));
 	}
 	async readdir(path) {
-		const virtual = await this.lookupVirtual(path);
-		if (virtual) {
-			if (virtual.kind !== "directory") throw new Error(`ENOTDIR: not a directory, scandir '${path}'`);
-			return virtual.entries.map((entry) => entry.name);
-		}
 		return this.host.fs.readdir(path, { cwd: this.host.defaultCwd });
 	}
 	async readdirWithFileTypes(path) {
-		const virtual = await this.lookupVirtual(path);
-		if (virtual) {
-			if (virtual.kind !== "directory") throw new Error(`ENOTDIR: not a directory, scandir '${path}'`);
-			return virtual.entries;
-		}
 		return (await this.host.fs.readdir(path, {
 			cwd: this.host.defaultCwd,
 			withFileTypes: true
@@ -86,14 +48,12 @@ var HostBackedFileSystem = class {
 		return [];
 	}
 	async mkdir(path, options) {
-		this.assertWritablePath(path);
 		await this.host.fs.mkdir(path, {
 			cwd: this.host.defaultCwd,
 			recursive: options?.recursive
 		});
 	}
 	async rm(path, options) {
-		this.assertWritablePath(path);
 		await this.host.fs.rm(path, {
 			cwd: this.host.defaultCwd,
 			recursive: options?.recursive,
@@ -101,62 +61,32 @@ var HostBackedFileSystem = class {
 		});
 	}
 	async cp(src, dest, options) {
-		this.assertWritablePath(dest);
-		if (isVirtualPath(src)) {
-			const virtual = await this.lookupVirtual(src);
-			if (!virtual) throw new Error(`ENOENT: no such file or directory, copyfile '${src}'`);
-			if (virtual.kind !== "file") throw new Error(`EISDIR: illegal operation on a directory, copyfile '${src}'`);
-			await this.host.fs.writeFile(dest, virtual.content, {
-				cwd: this.host.defaultCwd,
-				createParents: options?.recursive
-			});
-			return;
-		}
 		await this.host.fs.cp(src, dest, {
 			cwd: this.host.defaultCwd,
 			recursive: options?.recursive
 		});
 	}
 	async mv(src, dest) {
-		this.assertWritablePath(src);
-		this.assertWritablePath(dest);
 		await this.host.fs.mv(src, dest, { cwd: this.host.defaultCwd });
 	}
 	async chmod(path, mode) {
-		this.assertWritablePath(path);
 		await this.host.fs.chmod(path, mode, { cwd: this.host.defaultCwd });
 	}
 	async symlink(target, linkPath) {
-		this.assertWritablePath(linkPath);
 		await this.host.fs.symlink(target, linkPath, { cwd: this.host.defaultCwd });
 	}
 	async link(existingPath, newPath) {
-		this.assertWritablePath(existingPath);
-		this.assertWritablePath(newPath);
 		await this.host.fs.link(existingPath, newPath, { cwd: this.host.defaultCwd });
 	}
 	async readlink(path) {
-		if (isVirtualPath(path)) throw new Error(`EINVAL: invalid argument, readlink '${path}'`);
 		return this.host.fs.readlink(path, { cwd: this.host.defaultCwd });
 	}
 	async realpath(path) {
-		if (isVirtualPath(path)) {
-			if (!await this.lookupVirtual(path)) throw new Error(`ENOENT: no such file or directory, realpath '${path}'`);
-			return normalizePath(path);
-		}
 		return this.host.fs.realpath(path, { cwd: this.host.defaultCwd });
 	}
 	async utimes(path, atime, mtime) {
-		this.assertWritablePath(path);
 		await this.host.fs.utimes(path, atime, mtime, { cwd: this.host.defaultCwd });
 	}
-	async lookupVirtual(path) {
-		if (!this.virtualProvider || !isVirtualPath(path)) return null;
-		return await this.virtualProvider.lookup(normalizePath(path)) ?? null;
-	}
-	assertWritablePath(path) {
-		if (isVirtualPath(path)) throw new Error(`EROFS: read-only virtual filesystem, '${path}'`);
-	}
 };
 function encodingFrom(options) {
 	if (!options) return void 0;
@@ -166,13 +96,13 @@ function encodingFrom(options) {
 function encodeContent(content, encoding) {
 	if (content instanceof Uint8Array) return content;
 	if (encoding === "binary" || encoding === "latin1") return latin1ToBytes(content);
-	if (encoding === "base64") return base64ToBytes$1(content);
+	if (encoding === "base64") return base64ToBytes(content);
 	if (encoding === "hex") return hexToBytes(content);
 	return encodeUtf8(content);
 }
 function decodeBytes(bytes, encoding) {
 	if (encoding === "binary" || encoding === "latin1") return bytesToLatin1(bytes);
-	if (encoding === "base64") return bytesToBase64$1(bytes);
+	if (encoding === "base64") return bytesToBase64(bytes);
 	if (encoding === "hex") return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
 	return decodeUtf8(bytes);
 }
@@ -186,10 +116,10 @@ function bytesToLatin1(bytes) {
 	for (let index = 0; index < bytes.length; index += 8192) result += String.fromCharCode(...bytes.subarray(index, index + 8192));
 	return result;
 }
-function base64ToBytes$1(content) {
+function base64ToBytes(content) {
 	return latin1ToBytes(atob(content));
 }
-function bytesToBase64$1(bytes) {
+function bytesToBase64(bytes) {
 	return btoa(bytesToLatin1(bytes));
 }
 function hexToBytes(content) {
@@ -215,28 +145,5 @@ function toDirentEntry(value) {
 		isSymbolicLink: value.isSymbolicLink
 	};
 }
-function virtualStat(node) {
-	const now = /* @__PURE__ */ new Date(0);
-	if (node.kind === "directory") return {
-		isFile: false,
-		isDirectory: true,
-		isSymbolicLink: false,
-		mode: node.mode ?? 365,
-		size: 0,
-		mtime: node.mtime ?? now
-	};
-	return {
-		isFile: true,
-		isDirectory: false,
-		isSymbolicLink: false,
-		mode: node.mode ?? 292,
-		size: node.content.byteLength,
-		mtime: node.mtime ?? now
-	};
-}
-function isVirtualPath(path) {
-	const normalized = normalizePath(path);
-	return normalized === "/@" || normalized.startsWith("/@/");
-}
 //#endregion
-export { HostBackedFileSystem, virtualDirectory, virtualFile };
+export { HostBackedFileSystem };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { a as HostProcess, c as HostSpawnHandle, i as HostFileSystem, l as HostSpawnParams, n as HostDirent, o as HostProcessOutputChunk, r as HostFileStat, s as HostSpawnExit, t as Host, u as HostStore } from "./host-DIg4RxcL.mjs";
-import { HostBackedFileSystem, VirtualFileSystemNode, VirtualFileSystemProvider, virtualDirectory, virtualFile } from "./host-fs.mjs";
-import { _ as runRegisteredCommand, a as CommandIO, c as CommandRegistry, d as CommandStdin, f as CommandStorage, g as renderCommandHelp, h as parseCommandInput, i as CommandExecutionContext, l as CommandRunContext, m as emptyStdin, n as COMMAND_HELP_DEFAULTS, o as CommandInputSpec, p as ParsedCommandInput, r as Command, s as CommandOutputSpec, t as AgentSessionCommandStorage, u as CommandRunResult } from "./storage-CNMBL9_j.mjs";
+import { a as HostProcess, c as HostSpawnHandle, i as HostFileSystem, l as HostSpawnParams, n as HostDirent, o as HostProcessOutputChunk, r as HostFileStat, s as HostSpawnExit, t as Host, u as HostStore } from "./host-B-oKG7x5.mjs";
+import { HostBackedFileSystem, HostBackedFileSystemOptions } from "./host-fs.mjs";
+import { _ as runRegisteredCommand, a as CommandIO, c as CommandRegistry, d as CommandStdin, f as CommandStorage, g as renderCommandHelp, h as parseCommandInput, i as CommandExecutionContext, l as CommandRunContext, m as emptyStdin, n as COMMAND_HELP_DEFAULTS, o as CommandInputSpec, p as ParsedCommandInput, r as Command, s as CommandOutputSpec, t as AgentSessionCommandStorage, u as CommandRunResult } from "./storage-DYvEwSc9.mjs";
 import { CommandName } from "@demicodes/just-bash/commands";
 import { Interpreter, InterpreterState } from "@demicodes/just-bash/interpreter";
 import { CommandRegistry as CommandRegistry$1, ExecResult } from "@demicodes/just-bash/types";
@@ -38,6 +38,9 @@ interface BackgroundJob {
   handle: HostSpawnHandle;
   stdoutBuffer: string;
   stderrBuffer: string;
+  /** Chars discarded from the head of each buffer once it outgrew the capture limit. */
+  droppedStdoutChars: number;
+  droppedStderrChars: number;
   stdoutPump: Promise<void>;
   stderrPump: Promise<void>;
   exitPromise: Promise<{
@@ -66,6 +69,10 @@ interface ForegroundProcess {
   /** Interleaved visible chunks with running byte offsets, for merged replay. */
   outputChunks: ShellOutputRecordChunk[];
   outputBytes: number;
+  /** Total bytes ingested across both streams; the capture limit judges this. */
+  capturedBytes: number;
+  /** Set when the capture limit was breached: the process is killed and further chunks dropped. */
+  captureOverflowed: boolean;
   audit: BashAuditEvent[];
   stdoutPump: Promise<void>;
   stderrPump: Promise<void>;
@@ -106,6 +113,19 @@ interface BashEnvironmentOptions {
    * above, where models are known.
    */
   maxBinaryBytes?: number;
+  /**
+   * Ceiling for the bytes a single command's output capture may ingest.
+   *
+   * Distinct from `maxOutputBytes`, which sizes the rendered view: capture is
+   * what the environment holds in memory while a command runs, and it holds
+   * several copies (raw bytes for the pipe, text renders, replay chunks). A
+   * foreground process that produces more than this is SIGKILLed and the
+   * command fails with an explicit error; a background job keeps only the most
+   * recent bytes within the ceiling. Without this ceiling one stray
+   * `rg`/`cat` over a large tree balloons the embedding process by tens of
+   * gigabytes until the kernel OOM-kills it.
+   */
+  maxCaptureBytes?: number;
 }
 interface ShellExecInput {
   script: string;
@@ -207,6 +227,8 @@ type ShellCommandStatus = {
   status: 'exited';
   shellId: string;
   commandId: string;
+  /** Real directory holding this command's artifact files. */
+  artifactDir: string;
   exitCode: number;
   stdout: ShellStreamView;
   stderr: ShellStreamView;
@@ -221,6 +243,7 @@ type ShellCommandStatus = {
   status: 'running';
   shellId: string;
   commandId: string;
+  artifactDir: string;
   stdout: ShellStreamView;
   stderr: ShellStreamView;
   output: ShellOutputView;
@@ -230,6 +253,7 @@ type ShellCommandStatus = {
   status: 'aborted';
   shellId: string;
   commandId: string;
+  artifactDir: string;
   stdout: ShellStreamView;
   stderr: ShellStreamView;
   output: ShellOutputView;
@@ -246,6 +270,7 @@ declare class BashEnvironment {
   private readonly initialEnv;
   private readonly defaultOutputLimitBytes;
   private readonly defaultBinaryLimitBytes;
+  private readonly captureLimitBytes;
   private readonly shells;
   private readonly defaultShellByAgentSessionId;
   private readonly commandsById;
@@ -283,11 +308,7 @@ declare class BashEnvironment {
   private collectAborted;
   private collectAbortedWithoutForeground;
   private commandStatus;
-  private lookupVirtualArtifact;
-  private commandArtifactIds;
-  private commandArtifact;
   private persistCommandArtifact;
-  private syncRunningRecord;
 }
 //#endregion
 //#region src/portable-commands.d.ts
@@ -308,6 +329,15 @@ declare class BashEnvironment {
  * we call portable.
  */
 declare const DEMI_PORTABLE_COMMANDS: readonly CommandName[];
+/**
+ * Portable commands routed real-binary-first (`preferHostSpawn`): recursive
+ * tree scanners whose in-process implementations read files whole and burn
+ * the embedding host's main thread for minutes on large trees. A real
+ * process runs off-thread with its output bounded by the capture limit;
+ * hosts without the binary fall back to the portable implementation on
+ * first use.
+ */
+declare const HOST_PREFERRED_SCAN_COMMANDS: ReadonlySet<string>;
 /**
  * Names registered commands must not shadow, derived from the actual portable
  * command set plus interpreter builtins and pass-through system tools — not a
@@ -321,4 +351,4 @@ declare function shellQuote(value: string): string;
 /** Picks a heredoc delimiter that does not collide with any line already in `body`. */
 declare function heredocDelimiter(body: string): string;
 //#endregion
-export { AgentSessionCommandStorage, BashAuditEvent, BashEnvironment, BashEnvironmentOptions, BinaryStdout, COMMAND_HELP_DEFAULTS, Command, CommandExecutionContext, CommandIO, CommandInputSpec, CommandMetadataRecord, CommandOutputSpec, CommandRegistry, CommandRunContext, CommandRunResult, CommandStdin, CommandStorage, DEMI_PORTABLE_COMMANDS, Host, HostBackedFileSystem, HostDirent, HostFileStat, HostFileSystem, HostProcess, HostProcessOutputChunk, HostSpawnExit, HostSpawnHandle, HostSpawnParams, HostStore, MAX_TIMEOUT_MS, ParsedCommandInput, RESERVED_COMMAND_NAMES, ShellAbortInput, ShellCommandStatus, ShellExecInput, ShellOutputChunk, ShellOutputRecordChunk, ShellOutputView, ShellStatusInput, ShellStreamView, ShellWriteInput, VirtualFileSystemNode, VirtualFileSystemProvider, emptyStdin, heredocDelimiter, parseCommandInput, renderCommandHelp, runRegisteredCommand, shellQuote, virtualDirectory, virtualFile };
+export { AgentSessionCommandStorage, BashAuditEvent, BashEnvironment, BashEnvironmentOptions, BinaryStdout, COMMAND_HELP_DEFAULTS, Command, CommandExecutionContext, CommandIO, CommandInputSpec, CommandMetadataRecord, CommandOutputSpec, CommandRegistry, CommandRunContext, CommandRunResult, CommandStdin, CommandStorage, DEMI_PORTABLE_COMMANDS, HOST_PREFERRED_SCAN_COMMANDS, Host, HostBackedFileSystem, HostBackedFileSystemOptions, HostDirent, HostFileStat, HostFileSystem, HostProcess, HostProcessOutputChunk, HostSpawnExit, HostSpawnHandle, HostSpawnParams, HostStore, MAX_TIMEOUT_MS, ParsedCommandInput, RESERVED_COMMAND_NAMES, ShellAbortInput, ShellCommandStatus, ShellExecInput, ShellOutputChunk, ShellOutputRecordChunk, ShellOutputView, ShellStatusInput, ShellStreamView, ShellWriteInput, emptyStdin, heredocDelimiter, parseCommandInput, renderCommandHelp, runRegisteredCommand, shellQuote };

package/dist/index.mjs

@@ -1,6 +1,6 @@
-import { HostBackedFileSystem, virtualDirectory, virtualFile } from "./host-fs.mjs";
+import { HostBackedFileSystem } from "./host-fs.mjs";
 import { AgentSessionCommandStorage } from "./storage.mjs";
-import { asError, base64ToBytes, bytesToBase64, concatBytes, decodeLatin1, decodeUtf8, decodeUtf8Strict, encodeLatin1, encodeUtf8, tail, utf8Bytes, utf8Slice } from "@demicodes/utils";
+import { asError, concatBytes, decodeLatin1, decodeUtf8, decodeUtf8Strict, encodeLatin1, encodeUtf8, tail, utf8Bytes, utf8Slice } from "@demicodes/utils";
 import { createLazyCommands, getCommandNames } from "@demicodes/just-bash/commands";
 import { ArithmeticError, BadSubstitutionError, ExecutionLimitError, ExitError, Interpreter } from "@demicodes/just-bash/interpreter";
 import { decodeBytesToUtf8, unsafeBytesFromLatin1 } from "@demicodes/just-bash/encoding";
@@ -46,6 +46,19 @@ const REAL_SPAWN_DEPENDENT_COMMANDS = /* @__PURE__ */ new Set([
 * we call portable.
 */
 const DEMI_PORTABLE_COMMANDS = getCommandNames().filter((name) => !REAL_SPAWN_DEPENDENT_COMMANDS.has(name));
+/**
+* Portable commands routed real-binary-first (`preferHostSpawn`): recursive
+* tree scanners whose in-process implementations read files whole and burn
+* the embedding host's main thread for minutes on large trees. A real
+* process runs off-thread with its output bounded by the capture limit;
+* hosts without the binary fall back to the portable implementation on
+* first use.
+*/
+const HOST_PREFERRED_SCAN_COMMANDS = /* @__PURE__ */ new Set([
+	"rg",
+	"grep",
+	"find"
+]);
 /** Shell language words and builtins the interpreter itself owns. */
 const SHELL_BUILTIN_NAMES = [
 	".",
@@ -501,7 +514,16 @@ function createOutputSinks(fs, cwd, redirections) {
 	}
 	return routes;
 }
-function recordForegroundChunk(foreground, sourceFd, chunk) {
+function recordForegroundChunk(foreground, sourceFd, chunk, captureLimitBytes) {
+	if (foreground.captureOverflowed) return;
+	if (foreground.capturedBytes + chunk.byteLength > captureLimitBytes) {
+		foreground.captureOverflowed = true;
+		foreground.rawStdoutBuffer = "";
+		foreground.rawStdoutBytes = [];
+		foreground.handle.kill("SIGKILL").catch(() => {});
+		return;
+	}
+	foreground.capturedBytes += chunk.byteLength;
 	const text = decodeUtf8(chunk);
 	foreground.lastOutputAt = Date.now();
 	if (sourceFd === 1) {
@@ -609,39 +631,63 @@ function appendVisibleChunk(foreground, targetFd, text, byteLength) {
 //#endregion
 //#region src/command-artifact-store.ts
 /**
-* Owns persistence of shell command artifacts: a per-storage-id cache plus the
-* set of released (tombstoned) commands. `BashEnvironment` delegates the storage
-* and release-tracking side of the `/@` virtual filesystem here, keeping only the
-* in-memory record lookups that need live command state.
+* Writes shell command artifacts as plain files under
+* `host.commandArtifactsDir/<storageId>/<commandId>/` — one shared filesystem
+* namespace with the processes the shell spawns, so any tool (portable or
+* real) reads and searches artifacts with ordinary file operations.
 */
 var CommandArtifactStore = class {
-	store;
-	storageById = /* @__PURE__ */ new Map();
+	host;
 	released = /* @__PURE__ */ new Set();
-	constructor(store) {
-		this.store = store;
-	}
-	/** The artifact storage for one agent session or anonymous shell. */
-	storageFor(commandStorageId) {
-		const existing = this.storageById.get(commandStorageId);
-		if (existing) return existing;
-		const storage = new AgentSessionCommandStorage(this.store, commandStorageId);
-		this.storageById.set(commandStorageId, storage);
-		return storage;
-	}
-	/** Whether a command's artifact has been released (tombstoned). */
+	writeChains = /* @__PURE__ */ new Map();
+	constructor(host) {
+		this.host = host;
+	}
+	dirFor(commandStorageId, commandId) {
+		return `${this.host.commandArtifactsDir}/${commandStorageId}/${commandId}`;
+	}
+	/** Whether a command's artifact has been released (removed from disk). */
 	isReleased(commandStorageId, commandId) {
 		return this.released.has(this.key(commandStorageId, commandId));
 	}
-	/** Persists an artifact unless its command has already been released. */
-	persist(commandStorageId, commandId, artifact) {
-		if (this.isReleased(commandStorageId, commandId)) return;
-		this.storageFor(commandStorageId).writeJson(`commands/${commandId}/artifact.json`, artifact).catch(() => {});
+	/** Persists the artifact files unless the command has already been released. */
+	persist(commandStorageId, commandId, files) {
+		const key = this.key(commandStorageId, commandId);
+		if (this.released.has(key)) return;
+		const dir = this.dirFor(commandStorageId, commandId);
+		this.chain(key, async () => {
+			if (this.released.has(key)) return;
+			const writeOptions = {
+				cwd: this.host.defaultCwd,
+				createParents: true
+			};
+			await this.host.fs.writeFile(`${dir}/meta.json`, encodeUtf8(files.meta), writeOptions);
+			await this.host.fs.writeFile(`${dir}/stdout.txt`, encodeUtf8(files.stdout), writeOptions);
+			await this.host.fs.writeFile(`${dir}/stderr.txt`, encodeUtf8(files.stderr), writeOptions);
+			if (files.stdoutBin) await this.host.fs.writeFile(`${dir}/stdout.bin`, files.stdoutBin, writeOptions);
+		});
 	}
-	/** Tombstones a command and removes its persisted artifact. */
+	/** Tombstones a command and removes its artifact directory. */
 	async release(commandStorageId, commandId) {
-		this.released.add(this.key(commandStorageId, commandId));
-		await this.storageFor(commandStorageId).delete(`commands/${commandId}/artifact.json`).catch(() => {});
+		const key = this.key(commandStorageId, commandId);
+		this.released.add(key);
+		await new Promise((resolve) => {
+			this.chain(key, async () => {
+				await this.host.fs.rm(this.dirFor(commandStorageId, commandId), {
+					cwd: this.host.defaultCwd,
+					recursive: true,
+					force: true
+				}).catch(() => {});
+				resolve();
+			});
+		});
+	}
+	chain(key, work) {
+		const next = (this.writeChains.get(key) ?? Promise.resolve()).then(work).catch(() => {});
+		this.writeChains.set(key, next);
+		next.finally(() => {
+			if (this.writeChains.get(key) === next) this.writeChains.delete(key);
+		});
 	}
 	key(commandStorageId, commandId) {
 		return `${commandStorageId}\0${commandId}`;
@@ -778,6 +824,13 @@ const DEFAULT_OUTPUT_LIMIT_BYTES = 1048576;
 * while still bounding a runaway producer.
 */
 const DEFAULT_BINARY_LIMIT_BYTES = 16777216;
+/**
+* Ceiling for a single command's in-memory output capture. Sized to the same
+* order as the in-shell file read limit: the execution model buffers whole
+* command outputs (in several copies), so this is a hard memory-safety bound
+* on the embedding process, not a view budget.
+*/
+const DEFAULT_CAPTURE_LIMIT_BYTES = 67108864;
 /** Upper bound for a single exec observation window (also the command-bridge wait ceiling). */
 const MAX_TIMEOUT_MS = 6e5;
 var BashEnvironment = class {
@@ -788,19 +841,21 @@ var BashEnvironment = class {
 	initialEnv;
 	defaultOutputLimitBytes;
 	defaultBinaryLimitBytes;
+	captureLimitBytes;
 	shells = /* @__PURE__ */ new Map();
 	defaultShellByAgentSessionId = /* @__PURE__ */ new Map();
 	commandsById = /* @__PURE__ */ new Map();
 	artifacts;
 	constructor(options) {
 		this.host = options.host;
-		this.artifacts = new CommandArtifactStore(this.host.store);
+		this.artifacts = new CommandArtifactStore(this.host);
 		this.commands = options.commands ?? new CommandRegistry();
 		this.shellIdFactory = options.shellIdFactory ?? (() => globalThis.crypto.randomUUID());
 		this.commandIdFactory = options.commandIdFactory ?? (() => globalThis.crypto.randomUUID());
 		this.initialEnv = options.initialEnv ?? {};
 		this.defaultOutputLimitBytes = options.maxOutputBytes ?? DEFAULT_OUTPUT_LIMIT_BYTES;
 		this.defaultBinaryLimitBytes = options.maxBinaryBytes ?? DEFAULT_BINARY_LIMIT_BYTES;
+		this.captureLimitBytes = options.maxCaptureBytes ?? DEFAULT_CAPTURE_LIMIT_BYTES;
 	}
 	getShell(shellId) {
 		return this.shells.get(shellId) ?? null;
@@ -931,7 +986,7 @@ var BashEnvironment = class {
 		const id = this.shellIdFactory();
 		const commandStorageId = agentSessionId ?? id;
 		const cwd = initialCwd ?? this.host.defaultCwd;
-		const fs = new HostBackedFileSystem(this.host, { lookup: (path) => this.lookupVirtualArtifact(commandStorageId, path) });
+		const fs = new HostBackedFileSystem(this.host);
 		const env = /* @__PURE__ */ new Map();
 		for (const [key, value] of Object.entries(this.initialEnv)) env.set(key, value);
 		env.set("PWD", cwd);
@@ -1025,7 +1080,7 @@ var BashEnvironment = class {
 		for (const command of this.commands.list()) forkCommands.set(command.name, commandToForkCommand(session, command, storage, this.host));
 		session.abortController = new AbortController();
 		const limits = resolveLimits({
-			maxOutputSize: 1073741824,
+			maxOutputSize: this.captureLimitBytes,
 			maxCommandCount: 1e6,
 			maxLoopIterations: 1e6,
 			maxCallDepth: 1e3,
@@ -1097,6 +1152,7 @@ var BashEnvironment = class {
 			id,
 			shellId: session.id,
 			commandStorageId: session.commandStorageId,
+			artifactDir: this.artifacts.dirFor(session.commandStorageId, id),
 			script,
 			startedAt: now,
 			lastOutputAt: now,
@@ -1135,15 +1191,26 @@ var BashEnvironment = class {
 			handle,
 			stdoutBuffer: "",
 			stderrBuffer: "",
+			droppedStdoutChars: 0,
+			droppedStderrChars: 0,
 			stdoutPump: Promise.resolve(),
 			stderrPump: Promise.resolve(),
 			exitPromise: handle.wait()
 		};
+		const retainLimit = this.defaultOutputLimitBytes;
 		job.stdoutPump = pumpStream(handle.stdout, (chunk) => {
 			job.stdoutBuffer += decodeUtf8(chunk);
+			if (job.stdoutBuffer.length > retainLimit) {
+				job.droppedStdoutChars += job.stdoutBuffer.length - retainLimit;
+				job.stdoutBuffer = job.stdoutBuffer.slice(-retainLimit);
+			}
 		});
 		job.stderrPump = pumpStream(handle.stderr, (chunk) => {
 			job.stderrBuffer += decodeUtf8(chunk);
+			if (job.stderrBuffer.length > retainLimit) {
+				job.droppedStderrChars += job.stderrBuffer.length - retainLimit;
+				job.stderrBuffer = job.stderrBuffer.slice(-retainLimit);
+			}
 		});
 		session.backgroundJobs.set(id, job);
 		session.state.lastBackgroundPid = id;
@@ -1191,7 +1258,8 @@ var BashEnvironment = class {
 		await Promise.allSettled([job.stdoutPump, job.stderrPump]);
 		session.backgroundJobs.delete(id);
 		const exitCode = exit.exitCode ?? 127;
-		const stderr = exit.exitCode === null && job.stderrBuffer.length === 0 ? `${job.command}: ${exit.signal ?? "command not found"}\n` : job.stderrBuffer;
+		const stdout = job.droppedStdoutChars > 0 ? `[... dropped ${job.droppedStdoutChars} chars of earlier stdout over the capture limit ...]\n${job.stdoutBuffer}` : job.stdoutBuffer;
+		const stderr = exit.exitCode === null && job.stderrBuffer.length === 0 ? `${job.command}: ${exit.signal ?? "command not found"}\n` : job.droppedStderrChars > 0 ? `[... dropped ${job.droppedStderrChars} chars of earlier stderr over the capture limit ...]\n${job.stderrBuffer}` : job.stderrBuffer;
 		session.accumulator.audit.push({
 			kind: "system-command",
 			name: job.command,
@@ -1200,7 +1268,7 @@ var BashEnvironment = class {
 			exitCode
 		});
 		return {
-			stdout: job.stdoutBuffer,
+			stdout,
 			stderr,
 			exitCode
 		};
@@ -1321,6 +1389,8 @@ var BashEnvironment = class {
 			stderrBuffer: "",
 			outputChunks: [],
 			outputBytes: 0,
+			capturedBytes: 0,
+			captureOverflowed: false,
 			audit: [{
 				kind: "system-command",
 				name: command,
@@ -1340,18 +1410,18 @@ var BashEnvironment = class {
 		if (opts.stdinProvided) await handle.closeStdin();
 		if (handle.output) {
 			foreground.stdoutPump = pumpOutputStream(handle.output, (chunk) => {
-				recordForegroundChunk(foreground, chunk.stream === "stdout" ? 1 : 2, chunk.chunk);
+				recordForegroundChunk(foreground, chunk.stream === "stdout" ? 1 : 2, chunk.chunk, this.captureLimitBytes);
 			});
 			foreground.stderrPump = Promise.resolve();
 		} else {
-			foreground.stdoutPump = pumpStream(handle.stdout, (chunk) => recordForegroundChunk(foreground, 1, chunk));
-			foreground.stderrPump = pumpStream(handle.stderr, (chunk) => recordForegroundChunk(foreground, 2, chunk));
+			foreground.stdoutPump = pumpStream(handle.stdout, (chunk) => recordForegroundChunk(foreground, 1, chunk, this.captureLimitBytes));
+			foreground.stderrPump = pumpStream(handle.stderr, (chunk) => recordForegroundChunk(foreground, 2, chunk, this.captureLimitBytes));
 		}
 		const exit = await foreground.exitPromise;
 		await Promise.allSettled([foreground.stdoutPump, foreground.stderrPump]);
-		const stdout = decodeLatin1(concatBytes(foreground.rawStdoutBytes));
-		const exitCode = exit.exitCode ?? 127;
-		const stderr = exit.exitCode === null && foreground.rawStderrBuffer.length === 0 ? `${command}: ${exit.signal ?? "command not found"}\n` : foreground.rawStderrBuffer;
+		const stdout = foreground.captureOverflowed ? "" : decodeLatin1(concatBytes(foreground.rawStdoutBytes));
+		const exitCode = foreground.captureOverflowed ? 137 : exit.exitCode ?? 127;
+		const stderr = foreground.captureOverflowed ? `${command}: output exceeded the ${this.captureLimitBytes}-byte capture limit and the process was killed; the shell buffers whole command outputs in memory — narrow the output at the source (filters, head, tighter paths)\n` : exit.exitCode === null && foreground.rawStderrBuffer.length === 0 ? `${command}: ${exit.signal ?? "command not found"}\n` : foreground.rawStderrBuffer;
 		foreground.audit[0] = {
 			kind: "system-command",
 			name: command,
@@ -1431,7 +1501,8 @@ var BashEnvironment = class {
 					totalBytes: bytes.length,
 					limitBytes: cap
 				};
-				stdoutText = `<binary stdout: ${bytes.length} bytes${truncated ? `, exceeds the ${cap}-byte binary limit` : ""}; raw bytes at /@/commands/${record.id}/stdout.bin>\n`;
+				stdoutText = `<binary stdout: ${bytes.length} bytes${truncated ? `, exceeds the ${cap}-byte binary limit` : ""}; raw bytes at ${record.artifactDir}/stdout.bin>\n`;
+				record.pendingBinaryArtifact = bytes;
 			}
 		}
 		const stderrText = foreground ? resultOrError.stderr : decodeBytesToUtf8(unsafeBytesFromLatin1(resultOrError.stderr));
@@ -1511,6 +1582,7 @@ var BashEnvironment = class {
 		const base = {
 			shellId: record.shellId,
 			commandId: record.id,
+			artifactDir: record.artifactDir,
 			stdout,
 			stderr,
 			output,
@@ -1538,70 +1610,24 @@ var BashEnvironment = class {
 			status: "running"
 		};
 	}
-	async lookupVirtualArtifact(commandStorageId, path) {
-		const parts = path.split("/").filter(Boolean);
-		if (parts.length === 1 && parts[0] === "@") return virtualDirectory(["commands"]);
-		if (parts.length === 2 && parts[0] === "@" && parts[1] === "commands") return virtualDirectory(await this.commandArtifactIds(commandStorageId));
-		if (parts.length === 3 && parts[0] === "@" && parts[1] === "commands") {
-			const artifact = await this.commandArtifact(commandStorageId, parts[2]);
-			if (!artifact) return null;
-			const entries = [
-				"meta.json",
-				"stderr.txt",
-				"stdout.txt"
-			];
-			if (artifact.stdoutBinary) entries.push("stdout.bin");
-			return virtualDirectory(entries);
-		}
-		if (parts.length !== 4 || parts[0] !== "@" || parts[1] !== "commands") return null;
-		const artifact = await this.commandArtifact(commandStorageId, parts[2]);
-		if (!artifact) return null;
-		const fileName = parts[3];
-		if (fileName === "stdout.txt") return virtualFile(encodeUtf8(artifact.stdout));
-		if (fileName === "stdout.bin" && artifact.stdoutBinary) return virtualFile(base64ToBytes(artifact.stdoutBinary.base64));
-		if (fileName === "stderr.txt") return virtualFile(encodeUtf8(artifact.stderr));
-		if (fileName === "meta.json") return virtualFile(encodeUtf8(`${JSON.stringify(commandArtifactMeta(artifact), null, 2)}\n`));
-		return null;
-	}
-	async commandArtifactIds(commandStorageId) {
-		const ids = /* @__PURE__ */ new Set();
-		for (const record of this.commandsById.values()) if (record.commandStorageId === commandStorageId && !this.artifacts.isReleased(commandStorageId, record.id)) ids.add(record.id);
-		const keys = await this.artifacts.storageFor(commandStorageId).list("commands").catch(() => []);
-		for (const key of keys) {
-			const match = /^commands\/([^/]+)\/artifact\.json$/.exec(key);
-			if (match && !this.artifacts.isReleased(commandStorageId, match[1])) ids.add(match[1]);
-		}
-		return [...ids];
-	}
-	async commandArtifact(commandStorageId, commandId) {
-		if (this.artifacts.isReleased(commandStorageId, commandId)) return null;
-		const record = this.commandsById.get(commandId);
-		if (record?.commandStorageId === commandStorageId) {
-			this.syncRunningRecord(record);
-			return commandArtifactFromRecord(record);
-		}
-		const value = await this.artifacts.storageFor(commandStorageId).readJson(`commands/${commandId}/artifact.json`).catch(() => null);
-		return isCommandArtifact(value) ? value : null;
-	}
 	persistCommandArtifact(record) {
 		const fingerprint = `${record.status}:${record.exitCode ?? ""}:${record.stdout.length}:${record.stderr.length}:${record.binaryStdout?.totalBytes ?? ""}`;
 		if (record.persistedFingerprint === fingerprint) return;
 		record.persistedFingerprint = fingerprint;
-		this.artifacts.persist(record.commandStorageId, record.id, commandArtifactFromRecord(record));
-	}
-	syncRunningRecord(record) {
-		const foreground = this.shells.get(record.shellId)?.foreground;
-		if (record.status === "running" && foreground?.commandId === record.id) {
-			record.stdout = foreground.stdoutBuffer;
-			record.stderr = foreground.stderrBuffer;
-			record.outputChunks = [...foreground.outputChunks];
-			record.lastOutputAt = foreground.lastOutputAt;
-		}
+		const stdoutBin = record.pendingBinaryArtifact;
+		record.pendingBinaryArtifact = void 0;
+		this.artifacts.persist(record.commandStorageId, record.id, {
+			meta: `${JSON.stringify(commandArtifactMeta(record), null, 2)}\n`,
+			stdout: record.stdout,
+			stderr: record.stderr,
+			...stdoutBin ? { stdoutBin } : {}
+		});
 	}
 };
 function createPortableCommands(session) {
 	return createLazyCommands([...DEMI_PORTABLE_COMMANDS]).map((command) => ({
 		...command,
+		preferHostSpawn: HOST_PREFERRED_SCAN_COMMANDS.has(command.name),
 		execute: async (args, ctx) => {
 			const result = await command.execute(args, ctx);
 			session.accumulator.audit.push({
@@ -1636,7 +1662,7 @@ function streamView(record, stream, explicitOffset, maxOutputBytes) {
 	if (explicitOffset === void 0) if (stream === "stdout") record.stdoutOffset = nextOffset;
 	else record.stderrOffset = nextOffset;
 	return {
-		path: `/@/commands/${record.id}/${stream}.txt`,
+		path: `${record.artifactDir}/${stream}.txt`,
 		offset: nextOffset,
 		delta,
 		tail: tailString(text),
@@ -1671,7 +1697,7 @@ function mergedOutputView(record, explicitOffset, maxOutputBytes) {
 	const truncated = nextOffset < totalBytes;
 	if (explicitOffset === void 0) record.outputOffset = nextOffset;
 	return {
-		path: `demi://shell/${record.shellId}/commands/${record.id}/output`,
+		path: record.artifactDir,
 		offset: nextOffset,
 		text,
 		tail: tailOutputText(record.outputChunks),
@@ -1698,55 +1724,29 @@ function ensureRecordOutputCoverage(record) {
 	appendRecordOutput(record, "stdout", record.stdout);
 	appendRecordOutput(record, "stderr", record.stderr);
 }
-function commandArtifactFromRecord(record) {
+function commandArtifactMeta(record) {
 	return {
 		status: record.status,
 		shellId: record.shellId,
 		commandId: record.id,
+		script: record.script,
 		startedAt: record.startedAt,
 		lastOutputAt: record.lastOutputAt,
 		exitCode: record.exitCode ?? null,
-		stdout: record.stdout,
-		stderr: record.stderr,
-		...record.binaryStdout ? { stdoutBinary: {
-			base64: bytesToBase64(record.binaryStdout.data),
-			truncated: record.binaryStdout.truncated,
-			totalBytes: record.binaryStdout.totalBytes
-		} } : {}
-	};
-}
-function commandArtifactMeta(artifact) {
-	const stdoutPath = `/@/commands/${artifact.commandId}/stdout.txt`;
-	const stderrPath = `/@/commands/${artifact.commandId}/stderr.txt`;
-	return {
-		status: artifact.status,
-		shellId: artifact.shellId,
-		commandId: artifact.commandId,
-		startedAt: artifact.startedAt,
-		lastOutputAt: artifact.lastOutputAt,
-		runningMs: Date.now() - artifact.startedAt,
-		idleMs: Date.now() - artifact.lastOutputAt,
-		exitCode: artifact.exitCode,
 		stdout: {
-			path: stdoutPath,
-			bytes: utf8Bytes(artifact.stdout)
+			path: `${record.artifactDir}/stdout.txt`,
+			bytes: utf8Bytes(record.stdout)
 		},
 		stderr: {
-			path: stderrPath,
-			bytes: utf8Bytes(artifact.stderr)
+			path: `${record.artifactDir}/stderr.txt`,
+			bytes: utf8Bytes(record.stderr)
 		},
-		...artifact.stdoutBinary ? { stdoutBinary: {
-			path: `/@/commands/${artifact.commandId}/stdout.bin`,
-			bytes: artifact.stdoutBinary.totalBytes,
-			truncated: artifact.stdoutBinary.truncated
+		...record.binaryStdout ? { stdoutBinary: {
+			path: `${record.artifactDir}/stdout.bin`,
+			bytes: record.binaryStdout.totalBytes
 		} } : {}
 	};
 }
-function isCommandArtifact(value) {
-	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
-	const record = value;
-	return (record.status === "running" || record.status === "exited" || record.status === "aborted") && typeof record.shellId === "string" && typeof record.commandId === "string" && typeof record.startedAt === "number" && typeof record.lastOutputAt === "number" && (typeof record.exitCode === "number" || record.exitCode === null) && typeof record.stdout === "string" && typeof record.stderr === "string";
-}
 function tailOutputText(chunks) {
 	const maxChars = 4096;
 	let text = "";
@@ -1774,4 +1774,4 @@ function heredocDelimiter(body) {
 	return delimiter;
 }
 //#endregion
-export { AgentSessionCommandStorage, BashEnvironment, COMMAND_HELP_DEFAULTS, CommandRegistry, DEMI_PORTABLE_COMMANDS, HostBackedFileSystem, MAX_TIMEOUT_MS, RESERVED_COMMAND_NAMES, emptyStdin, heredocDelimiter, parseCommandInput, renderCommandHelp, runRegisteredCommand, shellQuote, virtualDirectory, virtualFile };
+export { AgentSessionCommandStorage, BashEnvironment, COMMAND_HELP_DEFAULTS, CommandRegistry, DEMI_PORTABLE_COMMANDS, HOST_PREFERRED_SCAN_COMMANDS, HostBackedFileSystem, MAX_TIMEOUT_MS, RESERVED_COMMAND_NAMES, emptyStdin, heredocDelimiter, parseCommandInput, renderCommandHelp, runRegisteredCommand, shellQuote };

package/dist/{storage-CNMBL9_j.d.mts → storage-DYvEwSc9.d.mts}

@@ -1,4 +1,4 @@
-import { t as Host, u as HostStore } from "./host-DIg4RxcL.mjs";
+import { t as Host, u as HostStore } from "./host-B-oKG7x5.mjs";
 import { z } from "zod";
 //#region src/command.d.ts
 type CommandInputSpec = Record<string, z.ZodType>;

package/dist/storage.d.mts

@@ -1,2 +1,2 @@
-import { t as AgentSessionCommandStorage } from "./storage-CNMBL9_j.mjs";
+import { t as AgentSessionCommandStorage } from "./storage-DYvEwSc9.mjs";
 export { AgentSessionCommandStorage };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@demicodes/shell",
   "description": "Sandboxable bash engine and Host contract for Demi.",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -19,8 +19,8 @@
     }
   },
   "dependencies": {
-    "@demicodes/just-bash": "^3.0.1-demi.5",
-    "@demicodes/utils": "^0.14.1",
+    "@demicodes/just-bash": "^3.1.0-demi.3",
+    "@demicodes/utils": "^0.15.0",
     "zod": "^4.0.0"
   },
   "license": "Apache-2.0",