shell

Report the last configuration hot-reload outcome: last_outcome (applied|rejected), last_error, and rejected_reloads (count since boot). A rejected outcome or non-zero count means a stored config was refused and shell is enforcing an older policy than the central store. Takes no arguments.

Run an allowlisted command in the foreground and return its full output. Put the program name in `command` (string) and arguments in `args` (string[]) — do NOT pass argv as an array in `command`. `timeout_ms` is capped at the configured max; negative/fractional values fall back to the default. `target` defaults to the host; pass { kind: "sandbox", sandbox_id } to run in a microVM. Optional host-only `cwd` scopes this call to a directory (jail-confined exactly like shell::fs::* paths; escaping it is S215), optional `env` (object) sets per-call values — but only for keys already in allowed_env and never for PATH/IFS/HOME/LD_*/DYLD_* or other loader/lookup and interpreter-startup keys (those reject S210) — and optional host-only `stdin` (string) is written to the program's standard input (use it for `tee`, `patch`, or any stdin filter instead of a shell heredoc). cwd/env/stdin on a sandbox target reject S210. Backend errors return { code, message }; common: S216 host exec error, S300 VM boot failed, S200 in-VM failure. argv-parse and allowlist/denylist rejections are plain-string messages naming the violation.

Spawn an allowlisted command as a background job; returns { job_id, argv } immediately. Same payload as shell::exec (command + args, do NOT pass argv as an array), including the optional host-only `cwd` (jail-confined; escape is S215), `env` (only allowed_env keys, never PATH/IFS/HOME/LD_*/DYLD_* or other loader/lookup and interpreter-startup keys), and `stdin` (string written to the job's stdin); violations and cwd/env/stdin on a sandbox target reject with an S210 message. Poll with shell::status, terminate with shell::kill, list with shell::list. Host background jobs ignore the per-call timeout_ms and run until they exit or shell::kill terminates them; set the operator config `max_bg_timeout_ms` (0 = unbounded, the default) to force-kill a runaway job after that long. Spawn-time failures (argv-parse, allowlist/denylist, cwd/env gating, spawn, concurrency cap) are plain-string messages naming the violation; once spawned, per-job failures surface through shell::status (the job record's status/stderr), not this call's return.

Change permissions. `mode` is an octal string like "0644". `uid`/`gid` optionally chown. `recursive: true` walks the tree (symlinks skipped). Returns { entries_changed, path, recursive }. Errors return { code, message }; common: S210 bad mode, S211 not found, S215 jail/denylist.

Search file contents. `pattern` is a Rust regex (RE2-like). `recursive` defaults true. `include_glob`/`exclude_glob` filter paths. Returns { matches, truncated }. Errors return { code, message }; common: S217 bad regex, S215 jail/denylist.

List directory contents. `path` is relative to the configured fs jail root (fs.host_root) when set, otherwise absolute. `target` defaults to host; pass { kind: "sandbox", sandbox_id } to run in a microVM. Errors return { code, message }; common: S210 bad path, S211 not found, S212 not a directory, S215 jail/denylist.

Create a directory. `mode` is an octal string like "0755". `parents: true` creates missing parents and is idempotent. Returns { created, path, already_existed }. Errors return { code, message }; common: S210 bad mode, S213 exists, S215 jail/denylist.

Move/rename a path. `overwrite: true` allows replacing an existing dst. Returns { moved, src, dst, overwrote }. Errors return { code, message }; common: S211 src not found, S213 dst exists, S215 jail/denylist.

Stream a file from a path. Returns a ContentRef the caller reads from, plus size/mode/mtime. Errors return { code, message }; common: S211 not found, S212 path is a directory, S215 jail/denylist, S218 file exceeds max_read_bytes, S216 channel/IO error.

Remove a path. `recursive: true` is required to delete a non-empty directory. Returns { removed, path, was_present }. Errors return { code, message }; common: S211 not found, S214 dir not empty (pass recursive), S215 jail/denylist.

Find-and-replace across files. `pattern` is a Rust regex by default (set regex:false for a literal). Provide either `files` (explicit list) or `path` (+ recursive). Returns { results, total_replacements }. Errors return { code, message }; common: S217 bad regex, S211 not found, S215 jail/denylist.

Stat a single path (jail-relative when fs.host_root is set). Returns the entry's type, size, mode, and mtime. Errors return { code, message }; common: S211 not found, S215 jail/denylist.

Write a file. Simplest form: { path, content: "text" } — `content` as a plain STRING is written inline (host target only), no streaming channel needed. For large/streamed payloads or a sandbox target, pass `content` as a ContentRef { channel_id, access_key, direction } from a write stream channel you opened through the engine's streaming layer (inline strings reject S210 on a sandbox target). To write several files at once, pass `files: [{ path, content, mode?, parents? }, ...]` instead of the single-file fields (host target, inline content) — the response then carries per-file results in `files`. `mode` is octal (default "0644"); `parents: true` creates missing parents. Errors return { code, message }; common: S210 bad mode/payload or inline-on-sandbox, S215 jail/denylist, S218 payload exceeds max_write_bytes, S216 channel/IO error.

Terminate a running background job by job_id (the UUID from shell::exec_bg). Errors return { code, message }; common: S211 no such job, S216 kill/signal delivery failure.

List background jobs (running + recently completed). Takes no arguments.

Internal: reload the security policy + fs backend on configuration change.

Fetch the full record (status, exit_code, timing) of a background job by job_id. Errors return { code, message }; common: S211 no such job.