@demicodes/shell 0.17.3 → 0.18.0

package/README.md

@@ -12,6 +12,8 @@ same agent can target local, container, remote, or in-memory backends.
 
 Subpaths: `@demicodes/shell/storage`, `@demicodes/shell/host-fs`.
 See [docs/shell-yield-control-plan.md](../../docs/shell-yield-control-plan.md) for
-the model-facing control surface and yield wakeups.
+the model-facing control surface and yield wakeups, and
+[docs/bash-behavior.md](../../docs/bash-behavior.md) for Host-backed behavior
+versus GNU bash.
 
 Part of [Demi](../../README.md). Apache-2.0.

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

@@ -13,6 +13,12 @@ interface Host {
   fs: HostFileSystem;
   process: HostProcess;
   store: HostStore;
+  identity: HostIdentity;
+}
+interface HostIdentity {
+  uid: number;
+  gid: number;
+  hostname: string;
 }
 interface HostFileSystem {
   readFile(path: string, options?: {
@@ -80,6 +86,17 @@ interface HostFileSystem {
 }
 interface HostProcess {
   spawn(params: HostSpawnParams): Promise<HostSpawnHandle>;
+  openCwd(path: string): Promise<HostCwd>;
+}
+type SpawnErrorKind = 'executable_not_found' | 'permission_denied' | 'cwd_unusable' | 'is_directory' | 'other';
+interface HostCwd {
+  readonly path: string;
+  spawnPath(): string;
+  chdir(path: string): Promise<void>;
+  snapshot(): Promise<{
+    restore(): void;
+  }>;
+  close(): Promise<void>;
 }
 /**
  * Keyed JSON state storage. Implementations must round-trip `Uint8Array` and
@@ -99,6 +116,13 @@ interface HostFileStat {
   mode: number;
   size: number;
   mtime: Date;
+  uid?: number;
+  gid?: number;
+  ino?: number;
+  dev?: number;
+  nlink?: number;
+  isCharacterDevice?: boolean;
+  isFIFO?: boolean;
 }
 interface HostDirent {
   name: string;
@@ -129,6 +153,11 @@ interface HostProcessOutputChunk {
 interface HostSpawnExit {
   exitCode: number | null;
   signal?: string;
+  spawnError?: {
+    kind: SpawnErrorKind;
+  };
 }
+/** Path-string cwd for test doubles and Hosts that cannot hold a directory fd. */
+declare function createLogicalHostCwd(initialPath: string): HostCwd;
 //#endregion
-export { HostProcess as a, HostSpawnHandle as c, HostFileSystem as i, HostSpawnParams as l, HostDirent as n, HostProcessOutputChunk as o, HostFileStat as r, HostSpawnExit as s, Host as t, HostStore as u };
+export { HostFileSystem as a, HostProcessOutputChunk as c, HostSpawnParams as d, HostStore as f, HostFileStat as i, HostSpawnExit as l, createLogicalHostCwd as m, HostCwd as n, HostIdentity as o, SpawnErrorKind as p, HostDirent as r, HostProcess as s, Host as t, HostSpawnHandle as u };

package/dist/host-fs.d.mts

@@ -1,4 +1,4 @@
-import { t as Host } from "./host-B-oKG7x5.mjs";
+import { t as Host } from "./host-BupAFtK6.mjs";
 import { BufferEncoding, CpOptions, DirentEntry, FileContent, FsStat, IFileSystem, MkdirOptions, ReadFileOptions, RmOptions, WriteFileOptions } from "@demicodes/just-bash/fs/interface";
 //#region src/host-fs.d.ts
 interface HostBackedFileSystemOptions {

package/dist/host-fs.mjs

@@ -134,7 +134,14 @@ function toFsStat(value) {
 		isSymbolicLink: value.isSymbolicLink,
 		mode: value.mode,
 		size: value.size,
-		mtime: value.mtime
+		mtime: value.mtime,
+		uid: value.uid,
+		gid: value.gid,
+		ino: value.ino,
+		dev: value.dev,
+		nlink: value.nlink,
+		isCharacterDevice: value.isCharacterDevice,
+		isFIFO: value.isFIFO
 	};
 }
 function toDirentEntry(value) {

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-B-oKG7x5.mjs";
+import { a as HostFileSystem, c as HostProcessOutputChunk, d as HostSpawnParams, f as HostStore, i as HostFileStat, l as HostSpawnExit, m as createLogicalHostCwd, n as HostCwd, o as HostIdentity, p as SpawnErrorKind, r as HostDirent, s as HostProcess, t as Host, u as HostSpawnHandle } from "./host-BupAFtK6.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 { _ 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-CAc1N6MN.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";
@@ -19,6 +19,7 @@ interface ShellSession {
   fs: HostBackedFileSystem;
   interpreter: Interpreter;
   forkCommands: CommandRegistry$1;
+  cwdHandle: HostCwd;
   accumulator: ExecAccumulator;
   foreground?: ForegroundProcess;
   activeCommandId?: string;
@@ -43,10 +44,7 @@ interface BackgroundJob {
   droppedStderrChars: number;
   stdoutPump: Promise<void>;
   stderrPump: Promise<void>;
-  exitPromise: Promise<{
-    exitCode: number | null;
-    signal?: string;
-  }>;
+  exitPromise: Promise<HostSpawnExit>;
 }
 interface ForegroundProcess {
   commandId: string;
@@ -76,10 +74,7 @@ interface ForegroundProcess {
   audit: BashAuditEvent[];
   stdoutPump: Promise<void>;
   stderrPump: Promise<void>;
-  exitPromise: Promise<{
-    exitCode: number | null;
-    signal?: string;
-  }>;
+  exitPromise: Promise<HostSpawnExit>;
   outputSinks: Record<1 | 2, ForegroundSink>;
   abortController: AbortController;
 }
@@ -303,6 +298,7 @@ declare class BashEnvironment {
   private raceForeground;
   private waitForBoundary;
   private hostSpawn;
+  private hostResolveCommand;
   private collectExited;
   private finishExited;
   private collectAborted;
@@ -320,24 +316,12 @@ declare class BashEnvironment {
  * copy: `CommandName` is just-bash's own "safe to run anywhere" set — it
  * already excludes the commands that need real process/network access
  * (curl → NetworkCommandName, python3/python → PythonCommandName, js-exec/node
- * → JavaScriptCommandName all live in separate, non-portable type unions). A
- * hand-picked subset of this list drifts silently as just-bash adds commands
- * (this one was missing echo, pwd, printf, date, env, hostname, whoami, gzip,
- * tar, split, sqlite3, xan, and more — all already categorized as safe
- * upstream, just never backported here). Deriving it removes that drift
- * entirely: everything just-bash calls portable (minus the exceptions above),
- * we call portable.
+ * → JavaScriptCommandName all live in separate, non-portable type unions).
+ * Unix names `hostSpawn` first (`preferHostSpawn`); portable is fallback for
+ * `executable_not_found` only.
  */
 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>;
+declare function shouldPreferHostSpawn(name: string): boolean;
 /**
  * Names registered commands must not shadow, derived from the actual portable
  * command set plus interpreter builtins and pass-through system tools — not a
@@ -351,4 +335,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_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 };
+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, HostCwd, HostDirent, HostFileStat, HostFileSystem, HostIdentity, HostProcess, HostProcessOutputChunk, HostSpawnExit, HostSpawnHandle, HostSpawnParams, HostStore, MAX_TIMEOUT_MS, ParsedCommandInput, RESERVED_COMMAND_NAMES, ShellAbortInput, ShellCommandStatus, ShellExecInput, ShellOutputChunk, ShellOutputRecordChunk, ShellOutputView, ShellStatusInput, ShellStreamView, ShellWriteInput, SpawnErrorKind, createLogicalHostCwd, emptyStdin, heredocDelimiter, parseCommandInput, renderCommandHelp, runRegisteredCommand, shellQuote, shouldPreferHostSpawn };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { HostBackedFileSystem } from "./host-fs.mjs";
 import { AgentSessionCommandStorage } from "./storage.mjs";
-import { asError, concatBytes, decodeLatin1, decodeUtf8, decodeUtf8Strict, encodeLatin1, encodeUtf8, tail, utf8Bytes, utf8Slice } from "@demicodes/utils";
+import { asError, concatBytes, decodeLatin1, decodeUtf8, decodeUtf8Strict, encodeLatin1, encodeUtf8, isAbsolutePath, 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";
@@ -30,6 +30,21 @@ const REAL_SPAWN_DEPENDENT_COMMANDS = /* @__PURE__ */ new Set([
 	"sleep"
 ]);
 /**
+* just-bash portable names that implement bash builtins (or shell state).
+* They stay in-process. `true`/`false` are omitted from the registry so the
+* interpreter builtins run.
+*/
+const IN_PROCESS_PORTABLE_COMMANDS = /* @__PURE__ */ new Set([
+	"echo",
+	"printf",
+	"pwd",
+	"alias",
+	"unalias",
+	"history",
+	"help",
+	"time"
+]);
+/**
 * Fork portable commands BashEnvironment registers in every shell, so
 * cat/ls/grep-class tools work without local coreutils on any Host backend.
 *
@@ -37,28 +52,14 @@ const REAL_SPAWN_DEPENDENT_COMMANDS = /* @__PURE__ */ new Set([
 * copy: `CommandName` is just-bash's own "safe to run anywhere" set — it
 * already excludes the commands that need real process/network access
 * (curl → NetworkCommandName, python3/python → PythonCommandName, js-exec/node
-* → JavaScriptCommandName all live in separate, non-portable type unions). A
-* hand-picked subset of this list drifts silently as just-bash adds commands
-* (this one was missing echo, pwd, printf, date, env, hostname, whoami, gzip,
-* tar, split, sqlite3, xan, and more — all already categorized as safe
-* upstream, just never backported here). Deriving it removes that drift
-* entirely: everything just-bash calls portable (minus the exceptions above),
-* we call portable.
+* → JavaScriptCommandName all live in separate, non-portable type unions).
+* Unix names `hostSpawn` first (`preferHostSpawn`); portable is fallback for
+* `executable_not_found` only.
 */
-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"
-]);
+const DEMI_PORTABLE_COMMANDS = getCommandNames().filter((name) => !REAL_SPAWN_DEPENDENT_COMMANDS.has(name) && name !== "true" && name !== "false");
+function shouldPreferHostSpawn(name) {
+	return !IN_PROCESS_PORTABLE_COMMANDS.has(name);
+}
 /** Shell language words and builtins the interpreter itself owns. */
 const SHELL_BUILTIN_NAMES = [
 	".",
@@ -82,17 +83,17 @@ const SHELL_BUILTIN_NAMES = [
 	"shift",
 	"source",
 	"test",
+	"true",
+	"false",
 	"unset",
 	"wait"
 ];
 /**
 * Ecosystem tools the model expects to reach through Host.process.spawn.
 *
-* xargs and yq are deliberately absent even though real versions exist: both
-* now have a real (non-simulated-elsewhere) implementation in just-bash's own
-* portable set above, which registers and dispatches before Host.process.spawn
-* is ever consulted — listing them here too would claim they fall through to
-* a real spawn, which no longer happens.
+* xargs and yq stay out of this list: they are already in the portable set
+* (`preferHostSpawn`, then the in-process implementation if the Host has no
+* binary). Listing them here would duplicate a reserved name.
 */
 const SYSTEM_TOOL_NAMES = [
 	"bun",
@@ -877,7 +878,7 @@ var BashEnvironment = class {
 		if (input.cwd !== void 0) {
 			if (!(await this.host.fs.stat(input.cwd).catch(() => null))?.isDirectory) throw new Error(`Shell exec cwd is not a directory: ${input.cwd}`);
 		}
-		const session = input.shellId ? this.requireShell(input.shellId) : input.ephemeral ? this.createShell(input.agentSessionId, input.cwd) : this.availableDefaultShell(input.agentSessionId);
+		const session = input.shellId ? this.requireShell(input.shellId) : input.ephemeral ? await this.createShell(input.agentSessionId, input.cwd) : await this.availableDefaultShell(input.agentSessionId);
 		if (session.exited) throw new Error(`Shell session "${session.id}" has exited`);
 		if (session.pendingExec || session.foreground) {
 			const commandId = session.activeCommandId ?? session.foreground?.commandId ?? "unknown";
@@ -944,6 +945,7 @@ var BashEnvironment = class {
 			await job.exitPromise.catch(() => {});
 		}
 		session.backgroundJobs.clear();
+		await session.cwdHandle.close().catch(() => {});
 		if (session.abortController) session.abortController.abort();
 	}
 	requireShell(shellId) {
@@ -968,21 +970,21 @@ var BashEnvironment = class {
 		if (!foreground || foreground.commandId !== commandId) throw new Error(`Command "${commandId}" has no foreground process`);
 		return foreground;
 	}
-	defaultShell(agentSessionId) {
+	async defaultShell(agentSessionId) {
 		if (!agentSessionId) return this.createShell(void 0);
 		const existingShellId = this.defaultShellByAgentSessionId.get(agentSessionId);
 		const existing = existingShellId ? this.shells.get(existingShellId) : void 0;
 		if (existing && !existing.exited) return existing;
-		const shell = this.createShell(agentSessionId);
+		const shell = await this.createShell(agentSessionId);
 		this.defaultShellByAgentSessionId.set(agentSessionId, shell.id);
 		return shell;
 	}
-	availableDefaultShell(agentSessionId) {
-		const shell = this.defaultShell(agentSessionId);
+	async availableDefaultShell(agentSessionId) {
+		const shell = await this.defaultShell(agentSessionId);
 		if (!agentSessionId || shell.exited || !shell.pendingExec && !shell.foreground) return shell;
 		return this.createShell(agentSessionId);
 	}
-	createShell(agentSessionId, initialCwd) {
+	async createShell(agentSessionId, initialCwd) {
 		const id = this.shellIdFactory();
 		const commandStorageId = agentSessionId ?? id;
 		const cwd = initialCwd ?? this.host.defaultCwd;
@@ -996,10 +998,12 @@ var BashEnvironment = class {
 		if (!env.has("PS1")) env.set("PS1", "");
 		if (!env.has("PS2")) env.set("PS2", "> ");
 		if (!env.has("SHLVL")) env.set("SHLVL", "1");
+		const cwdHandle = await this.host.process.openCwd(cwd);
 		const exportedVars = /* @__PURE__ */ new Set(["PWD", "DEMI_SHELL_ID"]);
 		if (agentSessionId) exportedVars.add("DEMI_SESSION_ID");
 		for (const key of env.keys()) if (key !== key.toLowerCase()) exportedVars.add(key);
 		for (const key of Object.keys(this.initialEnv)) exportedVars.add(key);
+		if (!env.has("HOSTNAME")) env.set("HOSTNAME", this.host.identity.hostname);
 		const state = {
 			env,
 			cwd,
@@ -1015,8 +1019,8 @@ var BashEnvironment = class {
 			lastBackgroundPid: 0,
 			virtualPid: 1,
 			virtualPpid: 0,
-			virtualUid: 1e3,
-			virtualGid: 1e3,
+			virtualUid: this.host.identity.uid,
+			virtualGid: this.host.identity.gid,
 			bashPid: 1,
 			nextVirtualPid: 2,
 			currentLine: 1,
@@ -1064,6 +1068,7 @@ var BashEnvironment = class {
 			fs,
 			interpreter: void 0,
 			forkCommands,
+			cwdHandle,
 			accumulator: {
 				stdout: "",
 				stderr: "",
@@ -1096,6 +1101,11 @@ var BashEnvironment = class {
 				exitCode: 0
 			}),
 			hostSpawn: (command, args, opts) => this.hostSpawn(session, command, args, opts),
+			hostResolveCommand: (name, env) => this.hostResolveCommand(session, name, env),
+			hostCwd: {
+				enter: (path) => session.cwdHandle.chdir(path),
+				snapshot: () => session.cwdHandle.snapshot()
+			},
 			rejectTimedPipelines: true,
 			jobControl: {
 				startBackground: (statement) => this.startBackgroundJob(session, statement),
@@ -1177,7 +1187,7 @@ var BashEnvironment = class {
 		const handle = await this.host.process.spawn({
 			command: backgroundCommand.command,
 			args: backgroundCommand.args,
-			cwd: session.state.cwd,
+			cwd: session.cwdHandle.spawnPath(),
 			env: this.exportedEnv(session),
 			killProcessGroup: true
 		});
@@ -1365,10 +1375,11 @@ var BashEnvironment = class {
 	}
 	async hostSpawn(session, command, args, opts) {
 		if (session.foreground) throw new Error(`hostSpawn: session "${session.id}" already has a foreground process`);
+		const spawnCwd = session.cwdHandle.spawnPath();
 		const handle = await this.host.process.spawn({
 			command,
 			args,
-			cwd: opts.cwd,
+			cwd: spawnCwd,
 			env: opts.env,
 			killProcessGroup: true
 		});
@@ -1422,8 +1433,13 @@ var BashEnvironment = class {
 		const exit = await foreground.exitPromise;
 		await Promise.allSettled([foreground.stdoutPump, foreground.stderrPump]);
 		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;
+		let exitCode = foreground.captureOverflowed ? 137 : exit.exitCode ?? 127;
+		let 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` : foreground.rawStderrBuffer;
+		let spawnError = exit.spawnError;
+		if (!foreground.captureOverflowed && exit.spawnError) {
+			exitCode = spawnErrorExitCode(exit.spawnError.kind);
+			stderr = spawnErrorStderr(command, opts.cwd, opts.env, exit.spawnError.kind);
+		} else if (!foreground.captureOverflowed && exit.exitCode === null && foreground.rawStderrBuffer.length === 0) stderr = `${command}: ${exit.signal ?? "command not found"}\n`;
 		foreground.audit[0] = {
 			kind: "system-command",
 			name: command,
@@ -1444,9 +1460,39 @@ var BashEnvironment = class {
 			stdout,
 			stdoutKind: "bytes",
 			stderr,
-			exitCode
+			exitCode,
+			...spawnError ? { spawnError } : {}
 		};
 	}
+	async hostResolveCommand(session, name, env) {
+		if (name.includes("/")) {
+			const resolved = isAbsolutePath(name) ? name : `${session.state.cwd.replace(/\/+$/, "")}/${name}`;
+			try {
+				if (!(await this.host.fs.stat(resolved)).isDirectory) return {
+					kind: "file",
+					value: name
+				};
+			} catch {
+				return null;
+			}
+			return null;
+		}
+		const pathEnv = env.PATH ?? "";
+		for (const dir of pathEnv.split(":")) {
+			if (!dir) continue;
+			const full = isAbsolutePath(dir) ? `${dir.replace(/\/+$/, "")}/${name}` : `${session.state.cwd.replace(/\/+$/, "")}/${dir}/${name}`;
+			try {
+				if ((await this.host.fs.stat(full)).isDirectory) continue;
+				return {
+					kind: "file",
+					value: isAbsolutePath(dir) ? full : `${dir}/${name}`
+				};
+			} catch {
+				continue;
+			}
+		}
+		return null;
+	}
 	collectExited(session, record, resultOrError, foreground, input = {}) {
 		if (record.status !== "running") return this.commandStatus(record, input);
 		if (resultOrError instanceof Error) {
@@ -1629,7 +1675,7 @@ var BashEnvironment = class {
 function createPortableCommands(session) {
 	return createLazyCommands([...DEMI_PORTABLE_COMMANDS]).map((command) => ({
 		...command,
-		preferHostSpawn: HOST_PREFERRED_SCAN_COMMANDS.has(command.name),
+		preferHostSpawn: shouldPreferHostSpawn(command.name),
 		execute: async (args, ctx) => {
 			const result = await command.execute(args, ctx);
 			session.accumulator.audit.push({
@@ -1644,6 +1690,20 @@ function createPortableCommands(session) {
 	}));
 }
 /** True when the string contains a char > 0xFF, i.e. already-decoded Unicode text. */
+function spawnErrorExitCode(kind) {
+	if (kind === "permission_denied" || kind === "is_directory") return 126;
+	return 127;
+}
+function spawnErrorStderr(command, cwd, env, kind) {
+	if (kind === "permission_denied") return `bash: ${command}: Permission denied\n`;
+	if (kind === "is_directory") return `bash: ${command}: Is a directory\n`;
+	if (kind === "cwd_unusable") return `bash: ${cwd}: No such file or directory\n`;
+	if (kind === "executable_not_found") {
+		if (command.includes("/") || !env.PATH) return `bash: ${command}: No such file or directory\n`;
+		return `bash: ${command}: command not found\n`;
+	}
+	return `bash: ${command}: ${kind}\n`;
+}
 function hasWideChar(value) {
 	for (let i = 0; i < value.length; i += 1) if (value.charCodeAt(i) > 255) return true;
 	return false;
@@ -1765,6 +1825,41 @@ function tailString(value) {
 	return tail(value, 4096);
 }
 //#endregion
+//#region src/host.ts
+/** Path-string cwd for test doubles and Hosts that cannot hold a directory fd. */
+function createLogicalHostCwd(initialPath) {
+	let path = initialPath;
+	return {
+		get path() {
+			return path;
+		},
+		spawnPath() {
+			return path;
+		},
+		async chdir(next) {
+			if (next === ".") return;
+			path = resolveLogicalCwd(path, next);
+		},
+		async snapshot() {
+			const saved = path;
+			return { restore() {
+				path = saved;
+			} };
+		},
+		async close() {}
+	};
+}
+function resolveLogicalCwd(base, next) {
+	if (next.startsWith("/")) return next;
+	const parts = base.split("/").filter(Boolean);
+	for (const part of next.split("/")) {
+		if (!part || part === ".") continue;
+		if (part === "..") parts.pop();
+		else parts.push(part);
+	}
+	return `/${parts.join("/")}`;
+}
+//#endregion
 //#region src/shell-quote.ts
 /** Single-quotes a value for safe use as one shell word. */
 function shellQuote(value) {
@@ -1778,4 +1873,4 @@ function heredocDelimiter(body) {
 	return delimiter;
 }
 //#endregion
-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 };
+export { AgentSessionCommandStorage, BashEnvironment, COMMAND_HELP_DEFAULTS, CommandRegistry, DEMI_PORTABLE_COMMANDS, HostBackedFileSystem, MAX_TIMEOUT_MS, RESERVED_COMMAND_NAMES, createLogicalHostCwd, emptyStdin, heredocDelimiter, parseCommandInput, renderCommandHelp, runRegisteredCommand, shellQuote, shouldPreferHostSpawn };

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

@@ -1,4 +1,4 @@
-import { t as Host, u as HostStore } from "./host-B-oKG7x5.mjs";
+import { f as HostStore, t as Host } from "./host-BupAFtK6.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-DYvEwSc9.mjs";
+import { t as AgentSessionCommandStorage } from "./storage-CAc1N6MN.mjs";
 export { AgentSessionCommandStorage };

package/package.json

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