@demicodes/shell 0.14.2 → 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,22 +1,7 @@
-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 {
-  lookup?: VirtualFileSystemProvider['lookup'];
   /**
    * 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
@@ -27,13 +12,8 @@ interface HostBackedFileSystemOptions {
    */
   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 options;
   private readonly maxFileReadBytes;
   constructor(host: Host, options?: HostBackedFileSystemOptions);
   readFile(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
@@ -57,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, HostBackedFileSystemOptions, VirtualFileSystemNode, VirtualFileSystemProvider, virtualDirectory, virtualFile };
+export { HostBackedFileSystem, HostBackedFileSystemOptions };

package/dist/host-fs.mjs

@@ -1,83 +1,40 @@
 import { decodeUtf8, encodeUtf8, isAbsolutePath, normalizePath } from "@demicodes/utils";
 //#region src/host-fs.ts
 const DEFAULT_FILE_READ_LIMIT_BYTES = 67108864;
-/** 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
-	};
-}
 var HostBackedFileSystem = class {
 	host;
-	options;
 	maxFileReadBytes;
 	constructor(host, options = {}) {
 		this.host = host;
-		this.options = options;
 		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
@@ -91,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,
@@ -106,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.options.lookup || !isVirtualPath(path)) return null;
-		return await this.options.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;
@@ -171,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);
 }
@@ -191,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) {
@@ -220,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, HostBackedFileSystemOptions, 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";
@@ -227,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;
@@ -241,6 +243,7 @@ type ShellCommandStatus = {
   status: 'running';
   shellId: string;
   commandId: string;
+  artifactDir: string;
   stdout: ShellStreamView;
   stderr: ShellStreamView;
   output: ShellOutputView;
@@ -250,6 +253,7 @@ type ShellCommandStatus = {
   status: 'aborted';
   shellId: string;
   commandId: string;
+  artifactDir: string;
   stdout: ShellStreamView;
   stderr: ShellStreamView;
   output: ShellOutputView;
@@ -304,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
@@ -329,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
@@ -342,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, 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, 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 = [
 	".",
@@ -618,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}`;
@@ -811,7 +848,7 @@ var BashEnvironment = class {
 	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());
@@ -949,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);
@@ -1115,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,
@@ -1463,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));
@@ -1543,6 +1582,7 @@ var BashEnvironment = class {
 		const base = {
 			shellId: record.shellId,
 			commandId: record.id,
+			artifactDir: record.artifactDir,
 			stdout,
 			stderr,
 			output,
@@ -1570,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({
@@ -1668,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),
@@ -1703,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),
@@ -1730,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 = "";
@@ -1806,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.2",
+  "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.2",
+    "@demicodes/just-bash": "^3.1.0-demi.3",
+    "@demicodes/utils": "^0.15.0",
     "zod": "^4.0.0"
   },
   "license": "Apache-2.0",