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

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,215 @@
+---
+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).
+
+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, tail-first when truncated.            |
+| `stdoutTruncated`, `stderrTruncated`       | Whether that stream is a fragment.                          |
+| `stdoutDroppedBytes`, `stderrDroppedBytes` | Bytes omitted from the start.                               |
+| `invalidProbe`                             | Present when the shell refused to start the command at all. |
+
+Each stream is bounded at 30,000 bytes and the tail is kept, because a failing
+command prints its verdict last. Never write a truncated stream to a file: it is
+the end of a log, 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.

package/docs/guides/run-the-test-suite.md

@@ -0,0 +1,154 @@
+---
+title: "Run the test suite and attribute a failure"
+description: "Declare how the project under test runs its suite, select what to run, and use against:'base' to separate the failures your edit introduced from the ones that were already there."
+sidebar:
+  order: 5
+---
+
+The `test` flow answers three questions a shell command cannot: what the suite
+reported, which of the failures are yours, and whether the run failed about the
+code at all.
+
+## Declare the runner once
+
+A caller of `test` selects **which** tests, never **how** to run them. The
+invocation is a host declaration, bound through the `TestRunner` service:
+
+```ts
+import * as TestRunner from "@smthrs/std/TestRunner"
+
+const runner = TestRunner.layer({
+  command: "python -m pytest -q",
+  cwd: "/testbed",
+  root: "/workspace/repo",
+  container: "testbed",
+  env: { PYTHONDONTWRITEBYTECODE: "1" },
+  timeoutMs: 900_000
+})
+```
+
+| Field       | Meaning                                                              |
+| ----------- | -------------------------------------------------------------------- |
+| `command`   | The runner command line, with no test selection in it.               |
+| `cwd`       | Where the runner runs. The container's path when `container` is set. |
+| `root`      | The host path of the git repository, when it differs from `cwd`.     |
+| `container` | A container to route the run through, via the `Container` transport. |
+| `env`       | Environment the runner needs.                                        |
+| `baseRef`   | The ref whose commit is the pristine base.                           |
+| `timeoutMs` | Default wall-clock budget for one run.                               |
+
+`cwd` and `root` differ exactly when the runner runs in a container: the
+container sees the repository at `cwd`, the host sees it at `root`, and a
+baseline checkout created at `<root>/.flows-test-base/run-<lease>` is visible to the runner
+at `<cwd>/.flows-test-base/run-<lease>`, because it is one directory under two names.
+
+A host with no runner binds `TestRunner.layerNoop`. The flow then fails with
+`provider_unavailable` and tells the caller to use `bash` with the command the
+project's own documentation gives.
+
+## Run a selection
+
+```ts
+import * as TestRun from "@smthrs/std/TestRun"
+
+const result = TestRun.run({
+  selection: ["tests/test_admin.py::AdminViewBasicTest::test_change_list"]
+})
+```
+
+Selection entries reach the runner as arguments, never as text spliced into the
+command line. The invocation is `bash -lc '<command> "$@"' <command> id...`, so a
+test id holding `::`, `[`, `]`, spaces, or shell metacharacters stays data.
+Omitting `selection` runs everything.
+
+The result is a reading, not a log:
+
+| Field                               | Meaning                                                                    |
+| ----------------------------------- | -------------------------------------------------------------------------- |
+| `command`                           | The logical invocation, without container transport arguments.             |
+| `exitCode`                          | The runner's exit code.                                                    |
+| `passed`                            | Tests reported passing. Zero when `parsed` is false.                       |
+| `failed`                            | Ids of the tests reported failing or erroring.                             |
+| `parsed`                            | Whether the runner's complete report could be read.                        |
+| `tail`                              | The end of the runner's combined output.                                   |
+| `tailTruncated`, `tailDroppedBytes` | Whether `tail` is a fragment, and by how much.                             |
+| `invalidProbe`                      | Present when the exit code describes the command, not the code under test. |
+
+When `parsed` is false, `tail` is all there is, and base attribution is omitted
+rather than guessed at.
+
+Unittest skips and expected failures, and TAP skips and TODO failures, do not
+count as passing or failing tests. A successful TAP TODO counts as passing.
+Unittest unexpected successes count as failures; attribution requires their
+reported ids. Python 3.10 class-only headers and Python 3.11+ full test ids are
+both supported. Missing failure ids or unknown unittest summary fields leave
+`parsed` false.
+
+## Who the failure belongs to
+
+A non-zero exit is a runner's verdict about the code it ran, not about the
+command it was handed. A run that names a test, a file, a module, an
+environment, or a program that does not exist never reaches any code and still
+exits non-zero, so it reads the same before and after a correct fix.
+`invalidProbe` is present when this run was one of those, with a `reason` from
+that closed list and a `message` saying what the result does and does not
+prove.
+
+Jev makes that attribution. The flow asks the `probe/attribution` classifier
+through the `Evaluator` service of [`@smthrs/model`](/api/model), so a host
+binds an evaluator on a subscription seat. Only a zero exit is attributed without a judge. Exit codes 126 and 127
+also go through attribution: a runner can return them after executing tests.
+A judge that cannot
+be reached, refuses, times out, or answers something unusable fails the call
+with `provider_unavailable`, `timeout`, or `request_failed`, because a guess at
+whether a reproduction reproduced is worth less than no answer at all.
+
+## Attribute a failure to your own edit
+
+The native CLI supports workspace tests. Baseline comparison refuses before any
+command starts; isolated staging is tracked in
+[#3234](https://github.com/smithersai/smithers/issues/3234). A host declares this
+with `baseline: false`.
+
+`against: "base"` runs the same selection a second time against the pristine
+base commit, in a scratch checkout, and differences the two failure sets:
+
+```ts
+const result = TestRun.run({
+  selection: ["tests/test_admin.py"],
+  against: "base"
+})
+
+result.introduced // failing here and not on the base tree: yours
+result.preexisting // failing on both: not yours, and not worth investigating
+result.fixed // failing on the base tree and passing here
+result.base // the base run's own outcome, plus its ref and commit
+```
+
+That is the whole of attribution, in one call. Without it, the same question
+costs a revert of the very work it was meant to prove.
+
+The baseline commit is resolved from the runner's `baseRef`, then from
+`TestRunner.captureBase` (`refs/flows/capture-base`), then from `HEAD`. A
+`baseRef` that does not resolve is an error rather than a fallback, because a
+baseline against the wrong tree answers the attribution question wrong.
+
+The baseline is a detached checkout at `<root>/.flows-test-base/run-<lease>`, under
+`TestRun.scratchDirectory`. Each call gets a unique lease. Existing checkouts
+are left alone; a `SIGKILL` can leave one behind. Inside the repository is the only place that works:
+a runner reaching the repository through a container mount sees a scratch
+checkout anywhere else on the host as a path that does not exist. It is removed
+when the call ends, however it ends. It is written from a temporary shadow
+`GIT_DIR`, like a checkpoint, so no hook or filter driver in the workspace's
+`.git` runs on the host and the repository's format is never changed.
+
+`against: "base"` needs a repository directory. A runner declaring neither `root`
+nor `cwd` fails with `invalid_input`.
+
+## Bound the run
+
+`timeoutMs` on the call overrides the runner's own, which overrides
+`TestRun.DEFAULT_TIMEOUT_MS` (ten minutes). The run holds at most
+`TestRun.MAX_CAPTURE_BYTES` of output in memory, and `tail` carries the last
+30,000 bytes of it, so `tail` holds the part of a long run that says what
+failed. A timeout is a `timeout` failure, not a result.