@smthrs/std 0.0.0-stage → 1.0.0-rc.12

package/docs/guides/reach-the-network.md

@@ -0,0 +1,141 @@
+---
+title: "Reach the network"
+description: "Get a URL with fetch, post a body with http-post, render a page with webfetch, and search the web through a provider bound to the WebSearch service."
+sidebar:
+  order: 7
+---
+
+Four flows leave the machine, and they differ in what they promise. All of them
+go through [`@smthrs/kernel`](/api/kernel)'s `HttpClient`, so the permission
+kernel sees the request.
+
+| Flow        | Tier           | Capability   | Use it for                                            |
+| ----------- | -------------- | ------------ | ----------------------------------------------------- |
+| `fetch`     | `sealed`       | `net:get:*`  | A raw GET whose body you want as text.                |
+| `webfetch`  | `sealed`       | `net:get:*`  | A page you want rendered as Markdown or plain text.   |
+| `http-post` | `irreversible` | `net:post:*` | Sending data. The remote side may already have acted. |
+| `websearch` | `sealed`       | `net:post:*` | A search through a configured provider.               |
+
+Provide the host's `GrantStore` alongside the pin-capable `HttpClient` from
+`@smthrs/platform-node/EgressHttpClient.layer(process.env)` (also used by the
+Bun host bundle). Unsupported transports fail closed. Every destination,
+including redirects, is checked before DNS or transport. Private destinations
+also need an exact `net:private` action grant for the normalized URL origin.
+See [HTTP destination permissions](../reference/flows.md#http-destination-permissions).
+
+## Get a URL
+
+```ts
+import * as Fetch from "@smthrs/std/Fetch"
+
+const response = Fetch.run({
+  url: "https://example.com/data.json",
+  headers: { accept: "application/json" }
+})
+// response.status, response.body, response.truncated, response.notice
+```
+
+An error status is an ordinary value: a 500 comes back as `status: 500` with its
+body. Only a transport failure, a permission refusal, or a body that exceeds the
+cap uses the error channel.
+
+The URL must be absolute `http` or `https` with no user information, or the call
+fails with `invalid_input`. A response larger than 5 MiB fails with
+`response_too_large` before decoding. The returned body is capped at 60,000
+bytes, head first, and says so through `truncated` and `notice`.
+
+## Post a body
+
+```ts
+import * as HttpPost from "@smthrs/std/HttpPost"
+
+const response = HttpPost.run({
+  url: "https://example.com/hooks/build",
+  body: JSON.stringify({ ref: "main" }),
+  contentType: "application/json"
+})
+```
+
+`contentType` defaults to `application/json`. The body is sent verbatim. The
+output shape and the limits match `fetch`.
+
+This is the one network flow declared `irreversible`, which is what makes a
+scheduler treat it as a real side effect rather than a retrievable read.
+
+## Render a page
+
+`webfetch` is for reading documentation rather than consuming an API:
+
+```ts
+import * as WebFetch from "@smthrs/std/WebFetch"
+
+const page = WebFetch.run({
+  url: "https://effect.website/docs",
+  format: "markdown",
+  timeout: 30
+})
+// page.url is the final URL after redirects
+// page.status, page.contentType, page.content, page.truncated, page.notice
+```
+
+`format` is `markdown` (the default), `text`, or `html`. HTML is converted only
+when the response is actually HTML; anything else is passed through as it
+arrived.
+
+Five behaviors are worth knowing:
+
+- Up to 10 redirects are followed, and `page.url` is where it ended. Crossing an
+  origin drops the `authorization` and `cookie` headers.
+- A content type that is not `text/*` and carries neither `json` nor `xml` fails
+  with `unsupported_content_type`. This flow renders text, not binaries.
+- `timeout` is in seconds, defaults to 30, and is capped at 120. It bounds the
+  request and the body read, and expiry is a `timeout` failure.
+- A response past 5 MiB is `response_too_large`, checked against
+  `content-length` first and then while reading.
+- The rendered `content` keeps its first 60,000 bytes. A longer page sets
+  `truncated: true` and a `notice` with the kept and total bytes.
+
+## Search the web
+
+`websearch` has no built-in provider. It calls the `WebSearch` service, so the
+host decides who answers:
+
+```ts
+import * as WebSearch from "@smthrs/std/WebSearch"
+
+const results = WebSearch.run({
+  query: "effect schema optional fields",
+  numResults: 5,
+  freshness: "month"
+})
+// results.results: [{ title, url, snippet, publishedAt? }]
+```
+
+`numResults` is 1 through 20 and defaults to 8. `freshness` is `day`, `week`,
+`month`, or `year`.
+
+The package ships one provider. `ExaWebSearch.layer` reads its API key from a
+named credential rather than from the environment:
+
+```ts
+import * as ExaWebSearch from "@smthrs/std/ExaWebSearch"
+
+const provider = ExaWebSearch.layer("exa-api-key")
+```
+
+It needs [`@smthrs/control`](/api/control)'s `Credential` service and
+[`@smthrs/kernel`](/api/kernel)'s `HttpClient`. It maps provider outcomes onto
+the standard codes: a 429 or a refusal carrying `Retry-After` becomes
+`rate_limited` with the advice in the message, a 401 or 403 becomes
+`provider_unavailable`, a 5xx becomes `provider_unavailable` naming the status,
+and any other non-2xx becomes `request_failed`. A request or response deadline
+becomes `timeout`. Snippets are clipped at 2,000 characters, the request is
+bounded at 30 seconds, and a response body over 5 MiB fails with
+`response_too_large` before it is decoded.
+
+A host with no provider binds `WebSearch.layerNoop`, and the call fails with
+`provider_unavailable`.
+
+`websearch` is not in `Manifest.readOnly`, because its provider contract
+requires `net:post` authority, which is mutating under the kernel capability
+taxonomy. A read-only tool surface gets `fetch` and `webfetch` instead.

package/docs/guides/read-and-edit-a-file.md

@@ -0,0 +1,240 @@
+---
+title: "Read and edit a file"
+description: "Page a file with read, anchor an edit by exact text or by an earlier hit's line range, and read what a miss reports back so the next attempt lands."
+sidebar:
+  order: 2
+---
+
+Four flows cover a file: `read`, `write`, `edit`, and `apply_patch`. This guide
+is about the loop that matters, which is reading a region and then changing it
+without losing the anchor in between.
+
+## Read a page
+
+```ts
+import * as Read from "@smthrs/std/Read"
+
+const page = Read.run({ path: "/workspace/src/widen.ts", offset: 40, limit: 20 })
+```
+
+`offset` and `limit` are 1-based lines. With neither, you get the first 2,000
+lines. The result is:
+
+| Field                  | Meaning                                                 |
+| ---------------------- | ------------------------------------------------------- |
+| `content`              | Raw page text, byte for byte as the file holds it.      |
+| `startLine`, `endLine` | The 1-based range this page covers.                     |
+| `totalLines`           | The file's line count.                                  |
+| `truncated`            | Whether anything was cut.                               |
+| `notice`               | What was shown out of what there was, when `truncated`. |
+
+`content` carries no line-number gutter. That is deliberate: an anchor copied
+out of a numbered read carries the numbers with it, so every `edit` built from
+one misses. Line numbers are facts about the page, so they are page fields.
+
+Source lines split on `\n`. A trailing `\r` is part of the line, including in
+CRLF files. Pages omit the final `\n` and retain every `\r`. For example,
+`"one\r\ntwo\r\n"` reads as `"one\r\ntwo\r"`. Copy that text unchanged into
+`oldString` or `expect`. Replacement text is also literal: retain the `\r`
+bytes in `newString` to keep CRLF endings, including the last line of a range.
+A line-range edit leaves the final `\n` outside the replaced span.
+
+A page cut by the byte budget ends on a whole line rather than handing back a
+fragment that looks like an anchor and is not one. A line longer than 2,000
+characters is clipped, and the notice says so by name, because a clipped line
+cannot be an anchor either.
+
+Reading an empty file returns an empty page with `startLine: 1`, `endLine: 0`,
+and `totalLines: 0`. Only an `offset` past the end is
+`offset_out_of_range`. A directory is `is_directory`; a file holding a NUL byte
+or invalid UTF-8 is `binary_file`.
+
+## Edit by exact text
+
+The first anchor form is the file's own bytes:
+
+```ts
+import * as Edit from "@smthrs/std/Edit"
+
+const applied = Edit.run({
+  path: "/workspace/src/widen.ts",
+  oldString: "  return value * 2",
+  newString: "  return value * 3"
+})
+```
+
+The match is byte exact. There is no fuzzy fallback, because a match that is not
+your bytes is an edit nobody inspected.
+
+`oldString` must occur exactly once. When it occurs more than once, the call
+fails with `invalid_input` naming every line the anchor sits on, so you can widen
+it without re-reading the file. Pass `replaceAll: true` to change all of them on
+purpose.
+
+When it occurs nowhere, the call fails with `no_match`, and the message carries
+the file's **actual** bytes at the nearest region, with that region's line range:
+
+```text
+oldString does not occur in /workspace/src/widen.ts. Lines 1-3 actually hold this, raw:
+export function widen(value: number): number {
+  return value * 2
+}
+
+Copy the lines you meant from that text, or anchor by startLine/endLine instead.
+```
+
+When not even one line of the anchor occurs in the file, the message says that
+instead: the file is the wrong one, or the region is not what you remember.
+
+That is the point of the failure: re-anchor from reality inside the same frame,
+rather than re-reading, re-guessing, and missing again.
+
+## Edit by line range
+
+The second anchor form reuses a hit you already have from `read` or `grep`,
+instead of retyping the text:
+
+```ts
+const applied = Edit.run({
+  path: "/workspace/src/widen.ts",
+  startLine: 2,
+  endLine: 2,
+  expect: "  return value * 2",
+  newString: "  return value * 3"
+})
+```
+
+`startLine` and `endLine` are both required and inclusive. `expect` is optional
+and turns the retyped copy into a checked assertion rather than a search key: if
+those lines hold anything else, the call fails with `no_match` and prints what
+they actually hold, which is what a file that moved under your line numbers looks
+like.
+
+The two forms do not mix. Each of these is `invalid_input`:
+
+- `oldString` together with `startLine` or `endLine`.
+- Neither `oldString` nor a line range. Use `write` to create a file.
+- An empty `oldString`.
+- `expect` together with `oldString`.
+- `replaceAll` together with a line range.
+- `endLine` before `startLine`.
+
+A range past the end of the file is `offset_out_of_range`.
+
+## Read the hunk back
+
+Every successful edit returns the region it wrote, raw, with two lines of
+context on each side:
+
+```ts
+// applied.startLine, applied.endLine: the range of the returned hunk
+// applied.replacements: how many occurrences changed
+// applied.hunk: the edited region as it now stands
+```
+
+A mis-indented edit costs one glance at `hunk` instead of an investigation.
+
+## Concurrent changes
+
+On ordinary filesystem hosts, `edit`, `write`, and `apply_patch` hold exclusive sibling directory locks from
+before reading until their mutation finishes. Existing symlink aliases share
+the resolved file's lock. Case and Unicode normalization variants conservatively
+share a lock, even on a case-sensitive filesystem. Separate hosts and processes using these handlers
+coordinate through the same filesystem; it must implement exclusive directory
+creation. A competing call fails with `no_match` and names the busy file before
+changing it. Re-read and retry after the other writer finishes. Anchors and
+line-range `expect` are checked again on every retry.
+
+A patch locks all source and destination paths before reading update contents.
+It may create destination parent directories first. Failure to acquire any lock
+releases the locks already acquired without applying file changes. Locks also
+release on ordinary failure and Effect interruption. Process death leaves a
+`.smithers-*.lock` directory and subsequent calls refuse to write. Stop all
+writers for that file, inspect its contents, and remove only the lock named in
+the refusal before retrying. Locks are never reclaimed by age.
+
+These locks coordinate standard handlers sharing a filesystem, including patch
+adds, deletes, and moves. Shell commands, editors, and other programs that do
+not use this protocol are outside that guarantee. Whole-file `write` and patch
+add operations intentionally replace contents; use an anchored edit when a
+previously read version must still match.
+
+On versioned hosts, the existing `Read.Preconditions` policy must provide
+`prepare(paths, session)`. It captures immutable read bases for that invocation
+and returns `read(path)` and `commit(changes)` operations. `read` must return
+bytes matching the captured base, or refuse; edits compute only from those bytes. Each handler submits one complete
+batch of writes and removals; a move includes both its destination write and
+source removal. The provider must compare every captured base before applying
+any mutation: a stale preflight leaves the whole batch unchanged. The production
+coding provider follows ADR 0004 protocol 7: an application failure may retain a
+durable prefix and requires fresh reads of every affected path. The host does
+not issue compensating writes. Only a complete validated settlement advances
+the ledger. Missing or malformed receipts and transport failures revoke read
+authority even when the old bytes remain. Tool-internal reads never refresh the
+model's read base.
+
+A host semaphore keeps preparation and diagnostics ordered. It does not exclude
+outside writers; that is the provider's responsibility. Versioned handlers create
+no parent or lock directories before commit and never fall back to ordinary
+filesystem writes. Missing providers fail with `provider_unavailable`. Diagnostics
+are updated only after the complete batch succeeds. The production coding host
+currently refuses mutations until its guest provider qualifies.
+
+## Write a whole file
+
+`write` replaces a file, creating parent directories:
+
+```ts
+import * as Write from "@smthrs/std/Write"
+
+const written = Write.run({ path: "/workspace/notes.md", content: "# Notes\n" })
+// written.bytesWritten, written.created
+```
+
+It preserves the file's mode, and it refuses to write over a directory with
+`command_failed`. Prefer `edit` for a targeted change: a whole-file write of a
+file you only partly know is how an unrelated region disappears.
+
+On ordinary filesystem hosts, `write`, `edit`, and `apply_patch` updates stage replacement bytes in a unique
+sibling file, preserve existing permission bits and ownership, then rename it
+over the destination. A failure before rename leaves the original bytes intact.
+Existing symlinks continue to target the same file. Hard links to the old inode
+keep its old contents. The host must support exclusive creation and atomic
+rename; unsupported operations fail without falling back to truncation.
+
+Temporary files are removed on failure and Effect interruption. Process death
+can leave an unused temporary file. This is per-file atomicity, not a transaction
+across a whole patch or a promise of persistence after power loss. No `fsync` is
+performed. Timestamps and extended metadata such as ACLs are not copied.
+
+## Apply a patch instead
+
+`apply_patch` accepts Codex's V4A patch text as one string, so a model trained on
+that tool can use the shape it knows:
+
+```ts
+import * as ApplyPatch from "@smthrs/std/ApplyPatch"
+
+const result = ApplyPatch.run({
+  input: [
+    "*** Begin Patch",
+    "*** Update File: src/widen.ts",
+    "@@",
+    "-  return value * 2",
+    "+  return value * 3",
+    "*** End Patch"
+  ].join("\n")
+})
+// result.added, result.modified, result.deleted, result.output
+```
+
+One rule to know: a patch naming the same file in two sections is refused whole
+rather than applied by halves. Every update hunk is derived from the file as it
+is on disk, so the second section would start from an original the first has
+already replaced. A file needing several changes carries several `@@` chunks
+inside one section.
+
+Because a patch names its files inside its own text, `apply_patch` cannot narrow
+its effect envelope for one call, and declares the workspace-wide worst case.
+`edit` narrows to the one path it was given, so prefer `edit` where a scheduler
+is running calls concurrently.

package/docs/guides/run-a-shell-command.md

@@ -0,0 +1,236 @@
+---
+title: "Run a shell command"
+description: "Send a command line or a script that needs no quoting, route it into a container, declare a hermetic envelope, and read the exit code, the bounded output, and the invalid-probe flag."
+sidebar:
+  order: 4
+---
+
+`bash` runs one command. It takes two shapes, and the difference is where the
+payload is parsed.
+
+## A command line
+
+```ts
+import * as Bash from "@smthrs/std/Bash"
+
+const result = Bash.run({
+  mode: "unhermetic",
+  command: "pnpm vitest run src/widen.test.ts",
+  cwd: "/workspace",
+  timeoutMs: 120_000
+})
+```
+
+The line goes to the platform shell exactly as written, and it carries its own
+arguments.
+
+## A script, delivered as data
+
+```ts
+const result = Bash.run({
+  mode: "unhermetic",
+  interpreter: "python3",
+  script: "import sys\nprint(sys.argv[1:])\n",
+  args: ["alpha", "beta"],
+  cwd: "/workspace"
+})
+```
+
+`script` is program text delivered to the interpreter on standard input. Nothing
+quotes it, escapes it, or terminates it with a heredoc marker, so the class of
+failure that eats a quote out of
+`docker exec c bash -lc '...python - <<EOF...'` cannot happen. `args` reach the
+script as arguments rather than as interpolated text.
+
+`interpreter` defaults to `bash`. `bash`, `zsh`, `sh`, and `dash` are told to
+read the program with `-s`; `python` and `python3` with `-`; `node`, `ruby`,
+`perl`, and anything else are given no file, which is how they read a program
+from standard input.
+
+Six input combinations are refused with `invalid_input`, each naming the fix:
+`command` with `script`, neither of the two, `script` with `stdin`, `command`
+with `args`, `command` with `interpreter`, and a hermetic containerised call.
+
+## Declare the environment
+
+Host commands inherit a bootstrap allowlist, not the whole Smithers process
+environment: `PATH`, `HOME`, `USER`, `LANG`, every `LC_*` locale variable,
+`TERM`, `TMPDIR`, and `SHELL`. Add a variable to `env` when the command needs
+it. Caller-declared names are applied last, including credential-shaped names,
+so declaring one is an explicit decision to make its value readable by the
+command. Undeclared provider keys and tokens are withheld.
+
+Containerised commands receive the `env` entries through the container
+transport; their remaining environment belongs to the container image. The
+Docker and Podman transport supplies each value to the host child as
+`SMITHERS_CONTAINER_ENV_KEY`, passes `-e SMITHERS_CONTAINER_ENV_KEY`, and renames
+it to `KEY` inside the container with `sh -c`, so the container needs `sh`. A
+requested `PATH` or `LD_PRELOAD` therefore never configures the host `docker`
+process. An `env` name that is not a POSIX shell name is `invalid_input`. Timeout errors show the logical command without
+container transport arguments.
+
+## Route it into a container
+
+```ts
+const result = Bash.run({
+  mode: "unhermetic",
+  container: "testbed",
+  command: "python -m pytest tests/test_admin.py",
+  cwd: "/testbed"
+})
+```
+
+`container` names a container the host knows how to reach, and the `Container`
+service turns the request into the argv the host spawns. `Container.layerCommand`
+builds the `docker exec` form, which `podman` shares.
+
+The native CLI refuses named-container execution with `provider_unavailable`.
+An existing Docker daemon is outside its OS sandbox. Isolated providers are
+tracked in [#1790](https://github.com/smithersai/smithers/issues/1790).
+
+A host sealed to one container is the exception. `SMITHERS_BASH_CONTAINER` names
+the container, and `bash` and `test` then run in it through the `docker` CLI.
+Every other container, and a call that names none, fails with
+`outside_container`. The file flows (`read`, `edit`, `apply_patch`, `grep` and
+the rest) act on the container's files through the same transport, resolving a
+relative path under `SMITHERS_TEST_CWD`, and `grep` and `glob` answer through
+`RemoteSearch`. The transport process runs outside the OS sandbox, which
+denies the daemon's socket, and receives the host's `DOCKER_HOST`,
+`DOCKER_CONTEXT`, `DOCKER_CONFIG`, `DOCKER_TLS_VERIFY`, and `DOCKER_CERT_PATH`,
+so it reaches a rootless daemon.
+
+The transport always goes through a login shell, because the images an agent
+meets activate the project's interpreter from `/etc/profile.d`. A program
+spawned directly by `docker exec` gets a different Python from the one that owns
+the repository's dependencies.
+
+A host that binds no transport refuses the call with `provider_unavailable` and
+a message telling the caller to drop the `container` field. That is the honest
+answer: this host has no container route.
+
+## Declare a hermetic envelope
+
+`mode: "hermetic"` requires explicit `reads` and `writes`, and the handler
+checks the command's explicit path tokens against them before spawning:
+
+```ts
+const result = Bash.run({
+  mode: "hermetic",
+  command: "cp /workspace/src/a.ts /workspace/build/a.ts",
+  reads: ["/workspace/src/**"],
+  writes: ["/workspace/build/**"]
+})
+```
+
+A token outside the declaration fails with `outside_declared_reads` or
+`outside_declared_writes` before anything runs, and the narrowed envelope makes
+the call `compensable` instead of `irreversible`, so a scheduler can run it
+beside work that touches other paths.
+
+Read [Hermetic mode is a pre-check, not a sandbox](../concepts/effects-and-capabilities.md#hermetic-mode-is-a-pre-check-not-a-sandbox)
+before you rely on this. The check is lexical: it bounds what the caller
+declared it would do, not what the process can do.
+
+## Confine approved commands
+
+The CLI and native flow hosts use bubblewrap on Linux and seatbelt on macOS.
+Approval to start a command does not open filesystem writes or networking.
+The host derives those permissions from its effective grants, including the
+current capability ceiling. A missing sandbox refuses the command.
+
+Matching `fs:read:/workspace/build/**`, `fs:write:/workspace/build`, and
+`fs:write:/workspace/build/**` grants open the `build` tree for writing.
+The directory entry needs its own write authority. Literal writes,
+complex globs, and permissions narrowed by a deny stay closed when the native
+mechanism cannot represent them safely. Egress opens only with unrestricted
+`net:get`, `net:post`, and `net:private` grants. Host-specific network grants
+keep networking closed. Host Unix sockets stay closed with open IP networking,
+except the fixed macOS system DNS resolver endpoint. Commands also receive private temporary storage.
+
+`NodeHost` and `BunHost` supply confinement. A custom native host provides
+[`ProcessConfinement.layer()`](/api/platform-node#processconfinement) to the
+kernel spawner. A missing confinement service refuses execution.
+`mode: "hermetic"` continues to check declarations before execution; it does
+not grant additional OS access.
+
+## Read the result
+
+A non-zero exit code is an ordinary value, not a failure. Only a timeout, a
+spawn failure, a permission refusal, and the hermetic pre-check use the error
+channel.
+
+| Field                                      | Meaning                                                     |
+| ------------------------------------------ | ----------------------------------------------------------- |
+| `exitCode`                                 | The command's exit code.                                    |
+| `stdout`, `stderr`                         | The captured streams; start and end when truncated.         |
+| `stdoutTruncated`, `stderrTruncated`       | Whether that stream is a fragment.                          |
+| `stdoutDroppedBytes`, `stderrDroppedBytes` | Bytes omitted from the middle.                              |
+| `invalidProbe`                             | Present when the shell refused to start the command at all. |
+
+Each stream is bounded at 30,000 bytes: its first 15,000 and its last 15,000.
+A search prints its matches first and a failing command prints its verdict
+last, so both survive. One line stands where the middle was:
+
+```text
+MARKER-HEAD
+xxxxxxxxxxxx
+[10025 bytes omitted]
+xxxxxxxxxxxx
+MARKER-TAIL
+```
+
+Never write a truncated stream to a file: it is a fragment, not the content it
+came from. `@smthrs/harness` reads the `Truncated` flags to refuse exactly that.
+
+`timeoutMs` defaults to `Bash.DEFAULT_TIMEOUT_MS`, ten minutes.
+
+## The invalid-probe flag
+
+A non-zero exit is a runner's verdict about the code it ran. It is not a verdict
+about the command it was handed. When a command names a test, a file, a module,
+an environment, or a program that does not exist, the runner never reaches any
+code and still exits non-zero.
+
+`invalidProbe` names that case, with a `reason` from a closed list
+(`unknown-command`, `unknown-test`, `unknown-path`, `unknown-module`,
+`unknown-environment`), the `evidence` it rests on, and a `message` stating
+what the result does and does not prove.
+
+```ts
+if (result.invalidProbe !== undefined) {
+  // The exit code is about the command. Fix the names and run it again
+  // before drawing any conclusion from it.
+}
+```
+
+`bash` does not infer a launch failure from exit code 126 or 127: a launched
+runner can return either status after running a check. It returns the captured
+command result without `invalidProbe` when launch cannot be established. The
+`test` flow asks the attribution judge whether a non-zero exit describes the
+code under test or an unresolved name. See
+[Run the test suite](./run-the-test-suite.md#who-the-failure-belongs-to).
+
+## The Codex-shaped alternative
+
+`shell_command` is a clone of the Codex CLI tool of the same name, for a model
+trained on that shape. It takes `command`, `workdir`, and `timeout_ms`, and it
+returns Codex's own rendering:
+
+```ts
+import * as ShellCommand from "@smthrs/std/ShellCommand"
+
+const result = ShellCommand.run({ command: "ls -la", workdir: "/workspace" })
+// result.output: "Exit code: 0\nWall time: 0.1 seconds\nOutput:\n..."
+// result.exitCode: 124 when the command timed out
+```
+
+The timeout defaults to 10 seconds, not ten minutes, and a timeout is a
+successful value with exit code `ShellCommand.TIMEOUT_EXIT_CODE`. Output is
+shaped to a 10,000-token budget by truncating the middle rather than the head.
+Codex's `sandbox_permissions`, `justification`, and `prefix_rule` approval
+parameters are deliberately absent: the permission kernel owns sandboxing and
+escalation here.
+
+Prefer `bash` for new work. It carries the effect envelope, the container
+transport, the script form, and the per-stream truncation fields that
+`shell_command` does not.