@demicodes/shell 0.17.4 → 0.19.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-BDRwHNOB.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.
-*/
-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.
+* → JavaScriptCommandName all live in separate, non-portable type unions).
+* Unix names `hostSpawn` first (`preferHostSpawn`); portable is fallback for
+* `executable_not_found` only.
 */
-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",
@@ -127,6 +128,7 @@ function emptyStdin() {
 		bytes: /* @__PURE__ */ new Uint8Array(0)
 	};
 }
+async function* emptyStdinStream() {}
 const EXECUTION_ONLY_FIELDS = [
 	"successOutput",
 	"failureOutput",
@@ -220,7 +222,7 @@ function parseArgs(command, path, argv, startIndex, stdin) {
 		setParsedValue(values, field, token);
 		positionalIndex += 1;
 	}
-	if (command.stdinField) values[command.stdinField] = stdin.text;
+	if (command.stdinField && values[command.stdinField] === void 0) values[command.stdinField] = stdin.text;
 	return {
 		path: [...path],
 		help: false,
@@ -261,7 +263,9 @@ async function runRegisteredCommand(root, ctx) {
 		cwd: ctx.cwd,
 		io: parsed.json ? capture : ctx.io,
 		storage: ctx.storage,
-		host: ctx.host
+		host: ctx.host,
+		signal: ctx.signal ?? new AbortController().signal,
+		stdinStream: ctx.stdinStream ?? emptyStdinStream()
 	});
 	if (parsed.json && result.exitCode === 0) {
 		const raw = capture.stdoutText();
@@ -695,24 +699,34 @@ var CommandArtifactStore = class {
 };
 //#endregion
 //#region src/registered-command-adapter.ts
-function commandToForkCommand(session, command, storage, host) {
+/**
+* Runs a registered command as a shell foreground job: it exposes the same
+* control surface as a host process (abort signal, live stdout/stderr view,
+* stdin as a post-start chunk stream) through a virtual process handle, so
+* `shell_status` / `shell_write` / `shell_abort` apply uniformly.
+*/
+function commandToForkCommand(session, command, storage, host, captureLimitBytes) {
 	return {
 		name: command.name,
 		consumesStdin: treeConsumesStdin(command),
 		execute: async (args, ctx) => {
 			const stdin = decodeForkStdin(ctx.stdin);
-			const io = createForwardingIO();
 			const argv = [command.name, ...args];
+			const job = new VirtualForegroundJob(session, command.name, args, ctx.cwd, captureLimitBytes);
+			job.install();
 			try {
-				const result = await runRegisteredCommand(command, {
+				const result = await Promise.race([runRegisteredCommand(command, {
 					argv,
 					stdin,
 					env: mapToRecord(ctx.env),
 					cwd: ctx.cwd,
-					io,
+					io: job.io,
 					storage,
-					host
-				});
+					host,
+					signal: job.signal,
+					stdinStream: job.stdinChunks()
+				}), job.killedResult()]);
+				if (job.foreground.captureOverflowed) return job.overflowResult();
 				session.accumulator.audit.push({
 					kind: "registered-command",
 					name: command.name,
@@ -726,12 +740,13 @@ function commandToForkCommand(session, command, storage, host) {
 					metadata: result.metadata
 				});
 				return {
-					stdout: io.stdoutLatin1(),
+					stdout: job.stdoutLatin1(),
 					stdoutKind: "bytes",
-					stderr: io.stderrText(),
+					stderr: job.stderrText(),
 					exitCode: result.exitCode
 				};
 			} catch (error) {
+				if (job.foreground.captureOverflowed) return job.overflowResult();
 				const message = error instanceof Error ? error.message : String(error);
 				session.accumulator.audit.push({
 					kind: "registered-command",
@@ -740,35 +755,171 @@ function commandToForkCommand(session, command, storage, host) {
 					exitCode: 1
 				});
 				return {
-					stdout: io.stdoutLatin1(),
+					stdout: job.stdoutLatin1(),
 					stdoutKind: "bytes",
-					stderr: `${io.stderrText()}${command.name}: ${message}\n`,
+					stderr: `${job.stderrText()}${command.name}: ${message}\n`,
 					exitCode: 1
 				};
+			} finally {
+				job.release();
 			}
 		}
 	};
 }
-/** Collects command output as raw bytes; stdout stays byte-clean for the pipe. */
-var ForwardingIO = class {
-	stdoutChunks = [];
-	stderrChunks = [];
-	async stdout(data) {
-		this.stdoutChunks.push(typeof data === "string" ? encodeUtf8(data) : data);
+/**
+* In-process stand-in for an OS process. `kill` maps to the abort signal
+* (there is no OS process to signal); a SIGKILL additionally abandons the
+* run so the shell never waits on an in-process function that ignores its
+* signal.
+*/
+var VirtualForegroundJob = class {
+	session;
+	captureLimitBytes;
+	foreground;
+	io;
+	abortController = new AbortController();
+	stdinQueue = new StdinChunkQueue();
+	settleExit;
+	killed;
+	killedPromise;
+	exitPromise;
+	installed = false;
+	constructor(session, command, args, cwd, captureLimitBytes) {
+		this.session = session;
+		this.captureLimitBytes = captureLimitBytes;
+		this.exitPromise = new Promise((resolve) => {
+			this.settleExit = resolve;
+		});
+		this.killedPromise = new Promise((_resolve, reject) => {
+			this.killed = reject;
+		});
+		this.killedPromise.catch(() => {});
+		const handle = {
+			stdout: emptyByteStream(),
+			stderr: emptyByteStream(),
+			writeStdin: async (data) => this.stdinQueue.push(data),
+			closeStdin: async () => this.stdinQueue.close(),
+			kill: async (signal) => {
+				this.abortController.abort();
+				this.stdinQueue.close();
+				if (signal === "SIGKILL") {
+					this.settleExit({
+						exitCode: 137,
+						signal: "SIGKILL"
+					});
+					this.killed(/* @__PURE__ */ new Error(`${command}: killed`));
+				}
+			},
+			wait: () => this.exitPromise
+		};
+		const startedAt = Date.now();
+		this.foreground = {
+			commandId: session.activeCommandId ?? "",
+			command,
+			args,
+			cwd,
+			handle,
+			startedAt,
+			lastOutputAt: startedAt,
+			rawStdoutBuffer: "",
+			rawStdoutBytes: [],
+			rawStderrBuffer: "",
+			stdoutBuffer: "",
+			stderrBuffer: "",
+			outputChunks: [],
+			outputBytes: 0,
+			capturedBytes: 0,
+			captureOverflowed: false,
+			audit: [],
+			stdoutPump: Promise.resolve(),
+			stderrPump: Promise.resolve(),
+			exitPromise: this.exitPromise,
+			outputSinks: createOutputSinks(session.fs, cwd, void 0),
+			abortController: this.abortController
+		};
+		this.io = {
+			stdout: (data) => {
+				recordForegroundChunk(this.foreground, 1, toBytes(data), this.captureLimitBytes);
+			},
+			stderr: (data) => {
+				recordForegroundChunk(this.foreground, 2, toBytes(data), this.captureLimitBytes);
+			}
+		};
 	}
-	async stderr(data) {
-		this.stderrChunks.push(typeof data === "string" ? encodeUtf8(data) : data);
+	get signal() {
+		return this.abortController.signal;
+	}
+	stdinChunks() {
+		return this.stdinQueue.stream();
+	}
+	killedResult() {
+		return this.killedPromise;
+	}
+	/** Registers this job as the session foreground so shell control verbs route here. */
+	install() {
+		if (this.session.foreground || !this.foreground.commandId) return;
+		this.session.foreground = this.foreground;
+		this.installed = true;
+		notifyForegroundWaiters(this.session.foregroundWaiters, this.foreground);
+	}
+	release() {
+		this.stdinQueue.close();
+		this.settleExit({ exitCode: 0 });
+		if (this.installed && this.session.foreground === this.foreground) this.session.foreground = void 0;
 	}
 	stdoutLatin1() {
-		return decodeLatin1(concatBytes(this.stdoutChunks));
+		return decodeLatin1(concatBytes(this.foreground.rawStdoutBytes));
 	}
 	stderrText() {
-		return decodeUtf8(concatBytes(this.stderrChunks));
+		return this.foreground.rawStderrBuffer;
+	}
+	overflowResult() {
+		return {
+			stdout: "",
+			stdoutKind: "bytes",
+			stderr: `${this.foreground.command}: output exceeded the ${this.captureLimitBytes}-byte capture limit and the command was stopped; the shell buffers whole command outputs in memory — narrow the output at the source (filters, head, tighter paths)\n`,
+			exitCode: 137
+		};
+	}
+};
+/** Async chunk queue: each pushed chunk is delivered once, in order; close ends the stream. */
+var StdinChunkQueue = class {
+	chunks = [];
+	waiter = null;
+	isClosed = false;
+	push(data) {
+		if (this.isClosed) return;
+		this.chunks.push(data);
+		this.wake();
+	}
+	close() {
+		if (this.isClosed) return;
+		this.isClosed = true;
+		this.wake();
+	}
+	async *stream() {
+		while (true) {
+			const chunk = this.chunks.shift();
+			if (chunk) {
+				yield chunk;
+				continue;
+			}
+			if (this.isClosed) return;
+			await new Promise((resolve) => {
+				this.waiter = resolve;
+			});
+		}
+	}
+	wake() {
+		const waiter = this.waiter;
+		this.waiter = null;
+		waiter?.();
 	}
 };
-function createForwardingIO() {
-	return new ForwardingIO();
+function toBytes(data) {
+	return typeof data === "string" ? encodeUtf8(data) : data;
 }
+async function* emptyByteStream() {}
 function treeConsumesStdin(command) {
 	if (command.stdinField) return true;
 	return command.subcommands?.some(treeConsumesStdin) ?? false;
@@ -877,7 +1028,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 +1095,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 +1120,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 +1148,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 +1169,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 +1218,7 @@ var BashEnvironment = class {
 			fs,
 			interpreter: void 0,
 			forkCommands,
+			cwdHandle,
 			accumulator: {
 				stdout: "",
 				stderr: "",
@@ -1077,7 +1232,7 @@ var BashEnvironment = class {
 		};
 		for (const command of createPortableCommands(session)) forkCommands.set(command.name, command);
 		const storage = new AgentSessionCommandStorage(this.host.store, commandStorageId);
-		for (const command of this.commands.list()) forkCommands.set(command.name, commandToForkCommand(session, command, storage, this.host));
+		for (const command of this.commands.list()) forkCommands.set(command.name, commandToForkCommand(session, command, storage, this.host, this.captureLimitBytes));
 		session.abortController = new AbortController();
 		const limits = resolveLimits({
 			maxOutputSize: this.captureLimitBytes,
@@ -1096,6 +1251,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 +1337,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 +1525,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 +1583,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 +1610,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 +1825,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 +1840,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 +1975,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 +2023,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-BDRwHNOB.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>;
@@ -47,6 +47,13 @@ interface CommandRunContext {
   storage: CommandStorage;
   /** Host of the BashEnvironment executing this command. */
   host: Host;
+  /** Aborted when the shell command is aborted (shell_abort, shell teardown). */
+  signal: AbortSignal;
+  /**
+   * Stdin written after the command started: each `shell_write` call arrives
+   * as one chunk. Ends when the command's shell job is released.
+   */
+  stdinStream: AsyncIterable<Uint8Array>;
 }
 interface CommandRunResult {
   exitCode: number;
@@ -77,6 +84,8 @@ interface CommandExecutionContext {
   io: CommandIO;
   storage: CommandStorage;
   host: Host;
+  signal?: AbortSignal;
+  stdinStream?: AsyncIterable<Uint8Array>;
 }
 declare class CommandRegistry {
   private readonly commands;

package/dist/storage.d.mts

@@ -1,2 +1,2 @@
-import { t as AgentSessionCommandStorage } from "./storage-DYvEwSc9.mjs";
+import { t as AgentSessionCommandStorage } from "./storage-BDRwHNOB.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.4",
+  "version": "0.19.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -19,8 +19,8 @@
     }
   },
   "dependencies": {
-    "@demicodes/just-bash": "^3.1.0-demi.3",
-    "@demicodes/utils": "^0.17.4",
+    "@demicodes/just-bash": "^3.1.0-demi.4",
+    "@demicodes/utils": "^0.19.0",
     "zod": "^4.0.0"
   },
   "license": "Apache-2.0",