@smthrs/platform-node 0.0.0-stage → 1.0.0-rc.3

package/docs/api.md

@@ -0,0 +1,552 @@
+---
+title: "API reference"
+description: "Every export of @smthrs/platform-node: the NodeHost layers, the AtomicFileSystem adapter and its glob grammar, HostLiveness, ScopedProcess, and ProcessReaper's lifecycle and refusals."
+---
+
+`@smthrs/platform-node` composes the closed five-tag Host surface for Node.
+`NodeHost.layer` provides all of it:
+
+```ts
+import { NodeHost } from "@smthrs/platform-node"
+import * as Effect from "effect/Effect"
+import * as ChildProcess from "effect/unstable/process/ChildProcess"
+import { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner"
+
+const program = Effect.gen(function*() {
+  const spawner = yield* ChildProcessSpawner
+  return yield* spawner.string(ChildProcess.make("printf", ["hello"]))
+}).pipe(Effect.provide(NodeHost.layer))
+```
+
+:::warning
+These adapters require host APIs such as `node:child_process`; they cannot run
+in a browser. Use [@smthrs/platform-browser](/api/platform-browser) for a browser
+host and [@smthrs/platform-bun](/api/platform-bun) for the Bun host bundle.
+`ScopedProcess` supports ordinary Node and Bun runtime executables.
+:::
+
+There is no shell service. Running a command is Effect's `ChildProcess` /
+`ChildProcessSpawner`; a wall-clock budget is `Effect.timeout` around the
+effect, and cancellation is fiber interruption, never an `AbortSignal`. There is
+no HTTP service either: an outgoing request is Effect's `HttpClient`, provided
+here as `EgressHttpClient.layer(environment)`. That layer is Undici through the egress proxy
+`HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY` name, and the plain
+`NodeHttpClient.layerUndici` pool when they name none. Undici installs no
+redirect interceptor either way, so every hop stays visible to
+[@smthrs/kernel](/api/kernel).
+
+The complete host bundles require jj 0.39.0 or newer. Each bundle builds its jj
+layer with one version probe; construction can fail with `JjError`, including
+`not_installed` or `unsupported_version`. The version probe runs outside the host process ledger; repository commands
+use the selected process runner.
+
+## Requirements
+
+| Requirement                     | Why                                                                   |
+| ------------------------------- | --------------------------------------------------------------------- |
+| Node.js >=26.4.0                | the minimum this package's `engines` field declares                   |
+| the `smithers-jj-export` helper | `AtomicFileSystem` runs every guarded filesystem operation through it |
+| a POSIX host                    | Windows has none of those primitives and is unsupported               |
+
+The helper is a real prerequisite, not a soft one, and it fails LATE by
+design. `NodeHost.layer` builds cleanly on a host without it, because the
+executable is re-validated per request rather than once at construction: the
+file a path names can be replaced while a host runs, and a check that happened
+only at boot would be a check about a file that is no longer there. The
+consequence is that on `node:22-slim`, `node:22-alpine`, or a distroless image
+the layer builds, the run starts, and the first guarded filesystem call inside a
+flow body fails `PermissionDenied`. Build or install the helper, or point the
+adapter at it; see [Configure the filesystem helper](./guides/configure-the-filesystem-helper.md).
+
+## Entry points
+
+| Import                                     | Source                                                                                                                                        | Platform   |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `@smthrs/platform-node`                    | [src/index.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/platform-node/src/index.ts)                           | Node       |
+| `@smthrs/platform-node/NodeHost`           | [src/NodeHost.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/platform-node/src/NodeHost.ts)                     | Node       |
+| `@smthrs/platform-node/AtomicFileSystem`   | [src/AtomicFileSystem.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/platform-node/src/AtomicFileSystem.ts)     | Node       |
+| `@smthrs/platform-node/HostLiveness`       | [src/HostLiveness.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/platform-node/src/HostLiveness.ts)             | Node       |
+| `@smthrs/platform-node/ProcessReaper`      | [src/ProcessReaper.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/platform-node/src/ProcessReaper.ts)           | Node       |
+| `@smthrs/platform-node/ScopedProcess`      | [src/ScopedProcess.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/platform-node/src/ScopedProcess.ts)           | Node / Bun |
+| `@smthrs/platform-node/ProcessConfinement` | [src/ProcessConfinement.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/platform-node/src/ProcessConfinement.ts) | Node / Bun |
+| `@smthrs/platform-node/ProcessSandbox`     | [src/ProcessSandbox.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/platform-node/src/ProcessSandbox.ts)         | Node / Bun |
+
+The barrel exports `NodeHost`, `EgressHttpClient`, `HostLiveness`, `ProcessReaper`,
+`ScopedProcess`, `ProcessConfinement`, and `ProcessSandbox`.
+`AtomicFileSystem` is reached as `NodeHost.AtomicFileSystem` or through its own
+subpath, never from the barrel.
+
+`NodeHost` also re-exports the pieces it composes, so a program that wants one
+slot rather than the whole bundle needs no second dependency:
+
+| Re-export                          | What it is                                                       |
+| ---------------------------------- | ---------------------------------------------------------------- |
+| `NodeHost.AtomicFileSystem`        | this package's descriptor-relative filesystem, the bundle's slot |
+| `NodeHost.ProcessReaper`           | this package's containment sweep                                 |
+| `NodeHost.NodeCrypto`              | Effect's Node `Crypto`                                           |
+| `NodeHost.NodeFileSystem`          | Effect's raw Node filesystem, which carries NO atomic extension  |
+| `NodeHost.NodeChildProcessSpawner` | Effect's Node spawner                                            |
+| `NodeHost.NodeHttpClient`          | Effect's Undici-backed `HttpClient`                              |
+
+`NodeCrypto` is there for a different reason from the rest. `Crypto` is not a
+Host service, so it is not in the closed list, but every durable composition
+needs one and a program that already depends on this package for its host
+should not need a second dependency for the digest.
+
+`NodeHost.implementationIds` is a
+`Readonly<Record<HostServiceIds[number], string>>` naming the five raw bundle
+implementations. Contained factories replace the process runner with
+`ProcessReaper.layerSpawner`; the static identity table does not describe
+that substitution.
+
+## Layers
+
+| Layer                                       | Jj bound to           | Containment |
+| ------------------------------------------- | --------------------- | ----------- |
+| `NodeHost.layer`                            | the process directory | no          |
+| `NodeHost.layerAt(root)`                    | one absolute root     | no          |
+| `NodeHost.layerContained(options?)`         | the process directory | yes         |
+| `NodeHost.layerContainedAt(root, options?)` | one absolute root     | yes         |
+
+The contained pair is what `@smthrs/flows`' `NodeRuntime` composes. Each pipeline leg
+gets a prepared supervisor, a `SIGTERM`-then-`SIGKILL` deadline, and a
+`ProcessLedger` record before activation, `jj` runs
+through that same spawner rather than starting its own children, and
+`ProcessReaper.reap` sweeps the records a crashed incarnation left behind while
+the layer is built. The ledger is a requirement rather than a default: only the
+program knows whether it has a durable one.
+
+`NodeHost.ContainedOptions` is `graceMs` plus the reaper's `ownerPid` and
+`system`. It deliberately omits `ContainedSpawner.Options.platform`. The
+platform comes from the real `process.platform`, so the native process group
+and recorded identity agree. A caller cannot describe a Windows record for an
+owner that actually leads a POSIX group.
+
+## ScopedProcess
+
+A small scoped process API for transient CLI commands. It uses the same POSIX
+supervisor lifecycle as the contained hosts without requiring a filesystem,
+repository service, or durable process ledger.
+
+```ts
+interface Options extends ChildProcess.KillOptions {
+  readonly command: string
+  readonly args?: ReadonlyArray<string> | undefined
+  readonly cwd?: string | undefined
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined
+  readonly stdin?: "ignore" | "pipe" | undefined
+  readonly windowsVerbatimArguments?: boolean | undefined
+  readonly windowsHide?: boolean | undefined
+}
+
+interface Handle extends ChildProcessHandle {
+  readonly targetPid: number
+}
+
+const spawn: (options: Options) => Effect.Effect<Handle, PlatformError, Scope>
+
+interface Status {
+  readonly code: number | null
+  readonly signal: ChildProcess.Signal | null
+}
+
+const status: (handle: ChildProcessHandle) => Effect.Effect<Status, PlatformError>
+```
+
+`spawn` runs the literal executable and argv with piped stdout/stderr and
+`stdin: "ignore"` by default. When `env` is provided it is the complete target
+environment; when omitted it inherits the host environment. The default
+termination policy is `SIGTERM`, then `SIGKILL` after 2,000 milliseconds.
+`windowsHide` defaults to true. Failed startup cleans up its child scope before
+returning an error.
+
+On POSIX, `handle.pid` identifies the live supervisor and `targetPid` identifies
+the native target for diagnostics. `exitCode` describes the target;
+`status(handle)` preserves a terminating signal as `{ code: null, signal }`.
+A missing or invalid target result remains a platform failure. Use the handle's
+`kill` for cleanup rather than signalling either numeric pid yourself.
+
+Drain stdout, stderr, stdin and status concurrently when using pipes. Keep the
+whole operation inside `Effect.scoped`; a target's natural exit also triggers
+cleanup of children holding those pipes open. The private parent connection
+requests cleanup on host loss. This API has no durable ledger; use
+`NodeHost.layerContained` when a later host must reconcile retained records.
+
+## ProcessReaper.layerSpawner
+
+```ts
+type SpawnerOptions = Omit<ContainedSpawner.Options, "platform">
+
+const layerSpawner: (
+  options?: SpawnerOptions
+) => Layer.Layer<ChildProcessSpawner, never, ChildProcessSpawner | ProcessLedger>
+```
+
+Provides a contained spawner without the complete Node or Bun host. Supply a
+`ProcessLedger` and the underlying runtime spawner. On POSIX this factory uses
+the platform's prepared native adapter, whose pipe error listeners live until
+their descriptors close, including writes interrupted by owner loss. On
+Windows it retains the supplied raw runtime spawner. The platform always comes
+from `process.platform`; `graceMs` defaults to 2,000 milliseconds.
+
+The adapter supports the standard command's stdin/stdout/stderr options and
+additional descriptors named `fdN` for indices 3 through 65,535. Recognized
+indices outside that finite integer range fail before target execution; the
+operating system may impose a lower limit. Names Effect does not recognize
+are ignored. A missing target result fails status and pending I/O; it never
+proves successful cleanup.
+
+`NodeHost.layerContained`, `BunHost.layerContained`, and their rooted variants
+use this factory. It records new owners; `ProcessReaper.layer` separately
+reconciles records inherited from a previous incarnation.
+
+## ProcessReaper.processLifecycle
+
+```ts
+const processLifecycle: ContainedSpawner.Lifecycle
+```
+
+The lower-level Node/Bun platform hook for custom
+`ContainedSpawner.layer(options, lifecycle)` compositions. Prefer
+`ProcessReaper.layerSpawner` for the supplied native adapter as well as the
+lifecycle.
+It prepares a live supervisor, lets the kernel commit the owner identity with
+the original command digest, and activates the target only afterward. The
+supervisor keeps group ownership until cleanup completes, including after a
+natural target exit. Each pipeline leg gets its own owner and ledger record.
+
+The returned handle's `pid` is the supervisor's, while `exitCode` and
+`isRunning` describe the target. `unref` changes liveness references without
+relinquishing cleanup ownership. Scope close and repeated explicit kills share
+one cleanup result; the first accepted policy wins. Failed or unverified
+cleanup fails close and leaves `settled` false so the kernel retains its record.
+
+Default POSIX commands own a separate process group. With `detached: false`,
+the supervisor and target share the caller's group, and cleanup signals only
+the target: group cleanup is explicitly disabled. Explicit stopping of a live
+grouped target also attempts a revalidated ancestry sweep for descendants that
+moved to other groups. That positive-PID sweep is best effort; automatic
+cleanup after natural exit does not promise to reclaim deliberately escaped
+sessions. Windows remains unsupported best effort.
+
+The supervisor starts the current Node or Bun runtime. Compiled Bun
+applications and Node single-executable applications are refused before target
+execution because they do not implement the runtime's eval entry point.
+
+## Filesystem
+
+`AtomicFileSystem.layer` is `NodeHost`'s filesystem slot, and it is not Effect's
+`NodeFileSystem`. Node exposes no `openat(2)` or `renameat(2)`, so the adapter
+delegates each operation to a POSIX helper that opens the workspace root once,
+walks every component with `O_NOFOLLOW`, and performs the final syscall relative
+to a pinned parent descriptor. Under [@smthrs/kernel](/api/kernel)'s
+`FileSystem.layer` that is what makes a symlink swapped in after authorization
+unable to redirect the operation, and it is why the bundle returns
+`PermissionDenied` for an out-of-root path, a hard link, a symlink, or a special
+file rather than performing raw effects.
+
+An aliased workspace root and its canonical `realPath` spelling address the
+same pinned descriptor. Paths returned by `realPath` can therefore be used for
+subsequent reads, writes, and atomic sibling replacement. Capability resources
+remain rooted at the logical workspace name; child symlinks, sibling paths,
+and replacement of the pinned root retain the same refusal checks.
+
+| Constant or constructor               | What it is                                                            |
+| ------------------------------------- | --------------------------------------------------------------------- |
+| `AtomicFileSystem.layer`              | the adapter with every default                                        |
+| `AtomicFileSystem.layerWith(options)` | the same, with the helper and the ceilings configured                 |
+| `AtomicFileSystem.defaultExecutable`  | `/usr/local/bin/smithers-jj-export`, the last path searched           |
+| `AtomicFileSystem.defaultLimits`      | 16 MiB content, 24 MiB request, 24 MiB response, 64 KiB helper stderr |
+| `AtomicFileSystem.defaultConcurrency` | `os.availableParallelism()`                                           |
+| `AtomicFileSystem.defaultTimeoutMs`   | 300000                                                                |
+| `AtomicFileSystem.AtomicHelperError`  | the tagged configuration failure, below                               |
+
+**Configuration errors.** An option outside its bounds, a request that cannot
+be serialized, and a helper that is missing, unusable, or untrusted fail with
+`AtomicHelperError` (`_tag` `@smthrs/platform-node/AtomicHelperError`), never a
+bare `Error`. Classify one by `code`. A rejected option or request reaches an
+operation as `BadArgument` whose `cause` is the `AtomicHelperError`;
+`AtomicFileSystem.resolveHelper()` throws it directly.
+
+| `code`                          | Raised when                                                                 |
+| ------------------------------- | --------------------------------------------------------------------------- |
+| `limit_invalid`                 | a `limits` byte ceiling is not a positive safe integer within its bound     |
+| `concurrency_invalid`           | `concurrency` is not a positive integer                                     |
+| `timeout_invalid`               | `timeoutMs` is not a positive integer no greater than 2147483647            |
+| `request_not_serializable`      | JSON has no form for the request                                            |
+| `helper_missing`                | no helper exists at any searched location; the message carries install hint |
+| `helper_unusable`               | `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY` names a helper that cannot run        |
+| `helper_path_invalid`           | the helper path is relative, ends in a separator, or loops through links    |
+| `helper_not_regular_file`       | the helper path is not a regular file                                       |
+| `helper_inside_workspace`       | the helper lives in, or appeared in, the confined workspace                 |
+| `staging_directory_not_private` | the per-user staging directory is a link or has another owner               |
+| `staging_unavailable`           | no location can hold a staged copy of the helper                            |
+
+**Protocol faults.** A helper that answers out of protocol, over a bound, or
+not at all fails closed: the operation fails with a `PlatformError` whose `cause`
+is an `AtomicHelperFault` (`_tag` `@smthrs/platform-node/AtomicHelperFault`).
+Classify one by `code`: `response_unframed`, `response_tag_unknown`,
+`response_length_invalid`, `response_length_mismatch`, `envelope_malformed`,
+`field_malformed`, `file_type_unknown`, `payload_malformed`,
+`read_limit_exceeded`, `entries_malformed`, `batch_malformed`,
+`digest_malformed`, `result_malformed`, `operation_unsupported`,
+`helper_timeout`, `response_limit_exceeded`, `helper_rejected`, `helper_exited`.
+An errno the helper itself reports is an `AtomicHelperRejection` with the native
+`code` and `syscall`.
+
+**Cost.** Every operation starts one helper process. Under the kernel's guarded
+layer, authorization adds two more, resolving the path before and after the
+grant decision. That is the price of descriptor-relative confinement on a runtime with no
+`openat`, and it is why the adapter carries a process ceiling: without one, an
+`Effect.forEach(files, read, { concurrency: "unbounded" })` over fifty entries
+would start fifty helpers at once. Batch a wide fan-out, or raise
+`concurrency` deliberately. A directory listing is one helper for the whole tree,
+so `readDirectory(root, { recursive: true })` costs far less than a read per
+entry.
+
+Every field of `Options` except `executable` is read once, when the layer is
+built, so the ceilings cannot change under a running host.
+
+**Glob.** The helper cannot call Node's globber, so it implements the grammar:
+`*` and `?` inside one segment, `[...]` classes with `!` or `^` negation, `**`
+across zero or more whole segments, `{a,b}` alternation, a trailing `/` for
+directory-only matching, and the dotfile rule, which keeps a wildcard out of a
+name beginning with `.` while letting a segment that spells the dot, `.*` or
+`[.]*`, match one. Exclusions prune the walk itself: excluding a directory
+excludes everything below it, and nothing under an excluded directory is listed,
+counted against the entry ceiling, or charged against the response ceiling. An
+exclusion that names the root stops before the walk begins. An absolute exclude
+is rewritten against the glob root so it applies to the same names the selecting
+pattern does. The selecting pattern prunes the walk too: a directory is entered
+only when a remaining segment or an open `**` can still name something below it,
+and only selected names are charged against the response ceiling. A trailing `**` spans zero segments, so it also names its own
+anchor: a directory always, and a non-directory only when every segment before it
+is literal, which is the shortcut the native globber takes when it can address
+the path directly rather than read a directory. `top.txt/**` names the file;
+`t*.txt/**` names nothing. A one-member class is the literal it spells, so `[.]`
+is a `.` path segment: the globber drops a SPELLED `.` before it parses and
+collapses `[.]` only afterwards, so this one survives and, as the last segment,
+names its anchor under the same rule. One addition: a `**` immediately before it
+addresses nothing, so `**/[.]` names nothing while `**/deep/[.]` names the
+directory. Anywhere but last, and in an exclusion, a `.` segment names an entry
+no directory holds. Matching aligns path segments with bounded dynamic programming; each segment
+uses globset’s compiled, non-backtracking matcher.
+
+Two grammar bounds are refusals rather than silent truncation: a pattern longer
+than 4096 UTF-8 bytes, and one whose braces expand past 64 alternatives, both
+fail as `BadArgument`. The byte limit is checked before expansion; the alternative
+limit is enforced during bounded expansion. Each resulting alternative is
+validated before filesystem walking, so
+an over-large pattern costs no listing and answers with the typed refusal rather
+than with a fail-closed transport error. So do the three constructs this grammar
+does not implement: extglob (`+(a|b)`), any `[:` opener inside a character
+class (including POSIX classes), and brace bodies containing `..` (including
+ranges such as `{1..3}` and sets containing that text). These checks conservatively
+reject unsupported syntax before filesystem access. Reading unsupported constructs
+as ordinary characters could answer a different question; an exclusion could
+then return the paths it was meant to remove. The refusal therefore covers the exclude list as well
+as the pattern, and it recognises a character class, so `[!(]*` is an ordinary
+negated class and not an extglob.
+
+Backslashes follow Node's POSIX rules instead: an absolute selector and every
+exclude drop them while leaving following wildcard magic active; a relative
+selector containing one matches nothing. The public filesystem path is
+absolute, and the direct atomic protocol preserves the relative empty answer.
+
+Three answers are pinned rather than copied, because the native globber gives no
+single answer to copy.
+
+1. **Case.** Matching is case-sensitive on every host. Node's globber passes
+   `nocase: isMacOS || isWindows` with `nocaseMagicOnly: true`. On a
+   case-insensitive host a magic segment folds case (`*.TXT` finds `upper.txt`),
+   a literal segment the matcher decides is compared exactly (`**/MID.txt`
+   misses `mid.txt`), and a literal segment Node addresses directly comes back
+   with the pattern's own spelling (`TOP.TXT` returns `TOP.TXT`), even though the
+   directory does not hold that spelling. The adapter returns only names its
+   walk found. A pattern whose meaning depends on which host reads it is worse
+   than one that means the same everywhere, and worst of all in an exclusion,
+   so the adapter keeps one rule everywhere.
+2. **A trailing `**` in an exclusion** removes what is under a directory and
+   leaves the directory entry itself. Node's own answer here depends on the
+   shape of the SELECTING pattern: `**/*` with `exclude: ["nested/**"]` keeps
+   `nested`, and `**` with the same exclusion drops it. The adapter gives one
+   answer for every selector. Consequently, the directory-only `**/` names
+   directories below its own anchor but not that anchor: with `exclude: ["**/"]`,
+   `**` keeps the root and its files while pruning every directory.
+   Node empties the answer instead.
+3. **A dotted segment after `**`.** Node 22 matched nothing for `**/.hidden`;
+   Node 24 and later match the dotfiles. The adapter follows the newer reading
+   for the dotfiles themselves, but a `**` never spans a hidden directory, so
+   Node's further step of walking into a hidden directory that the next segment
+   matches is refused. With `.hidden/.secret` and `.hidden/.nested/.wanted`
+   present, Node returns `.hidden/.secret` for `**/.*` and `.hidden/.nested` for
+   `**/.*/**`; the adapter returns `.hidden` alone for both. Only a segment that
+   names the hidden directory enters it: `.hidden/.*` returns `.hidden/.nested`
+   and `.hidden/.secret`.
+
+**Removal.** `remove(path, { recursive: true })` walks iteratively with an
+explicit descriptor stack: depth is bounded at 512 levels and the total number
+of entries visited at 100000, counted as each directory is read, so a hostile
+wide directory is refused after 100000 names rather than allocated whole. One
+directory's names are read before any of its entries is unlinked, because
+unlinking from a directory while iterating it is undefined; the entry ceiling
+is what bounds the names held across the whole walk. Progress is partial on
+refusal, since entries already unlinked stay unlinked. `force: true` succeeds
+for a path whose ancestors do not exist, exactly as `fs.rm` does.
+
+## Liveness and reaping
+
+`ProcessReaper.groupSnapshotFor(platform)` selects the live cleanup probe,
+returning `(pgid) => { ownGroup, members } | undefined`. Each member carries
+`pid`, `startedAtMs`, and `zombie`. Linux reads `/proc` directly and needs no
+`ps` binary for live cleanup; other POSIX hosts use `/bin/ps`. Unreadable or
+malformed process data returns `undefined`, so the snapshot cannot claim
+success. `ProcessReaper.groupVacant(pgid)` asks the kernel first with signal 0:
+only `ESRCH` returns `true`, which proves the group has no process at all and
+needs no `ps` fork. A live member, a zombie, or any other error returns `false`,
+and the snapshot decides. `ProcessReaper.processLifecycle` uses both probes for
+the current platform.
+
+`HostLiveness.isAlive({ hostId })` is the probe a durable engine consults before
+it takes a run whose recorded owner it is not: an owner on a different host reads
+as alive, and an owner on this host reads as alive exactly while its pid is
+signalable. `@smthrs/run-store`'s `Ownership.sameHostPidProbe` answers the same
+question differently for a foreign host, and the two are not interchangeable;
+the JSDoc on `isAlive` names both inputs on which they disagree.
+
+`ProcessReaper.reap` kills the process groups a crashed incarnation of the same
+`hostId` abandoned. It signals a record only when every guard holds: the numbers
+name something the platform can signal, the group is not this host's, the owner
+is gone, and the pid still names the process the record describes. Two of those
+guards are identity questions: this process's own group, and when the
+recorded pid started. On Linux, `systemFor` answers both from `/proc`
+(`procSystem`), so an image without `procps` can still reap; other POSIX hosts
+ask `ps` (`posixSystem`). Either can go unanswered, and an unanswered guard
+refuses, because a guard that did not run is not a guard that passed. No
+evidence never authorizes a `SIGKILL`.
+
+`ProcessReaper.layer` reports every sweep: one log line with the kill count and
+the count per refusal, at `Warning` when `identity-unverified`,
+`own-group-unknown`, or `kill-failed` left a process running, and the
+`flows_process_reaper_refusals` counter with a `refusal` attribute.
+
+`reap` returns one `Reaped` per inherited record. The two outcomes are a union
+discriminated by `killed`: a killed entry carries no reason, and a kept entry
+always carries the `Refusal` that produced it, so one check on `killed` is what
+makes `refusal` readable.
+
+A refusal also decides whether the record is retired. Retiring says in the
+journal that nothing was signalled and stops every later incarnation
+re-examining a number the operating system has moved on from, so only a refusal
+a later incarnation cannot answer differently is final.
+
+| Refusal               | Retired |
+| --------------------- | ------- |
+| `owner-alive`         | no      |
+| `identity-unverified` | no      |
+| `own-group-unknown`   | no      |
+| `no-group`            | yes     |
+| `own-group`           | yes     |
+| `invalid-record`      | yes     |
+| `pre-boot`            | yes     |
+| `process-gone`        | yes     |
+| `identity-mismatch`   | yes     |
+| `kill-failed`         | no      |
+
+Windows reaping is unsupported best-effort. Windows is an unsupported platform
+and `AtomicFileSystem` fails every operation closed there, but
+`systemFor("win32")` still reaches `taskkill /T /F` through the sweep rather than
+retiring every record unsignalled, because a feature that appears to work
+partially is worse than one that says what it does.
+
+## Conformance
+
+The package runs the shared suite from
+[`@smthrs/kernel/test/contract`](/api/kernel) twice: once with explicit
+expectations, and once taking every default the suite offers, against a loopback
+HTTP server so the `HttpClient` success path is actually asserted rather than
+only its refusal. On top of that, the atomic
+filesystem is compared against `@effect/platform-node`'s own adapter: open
+flags, errno classification, `stat` fields, and the glob grammar are asserted
+row by row against the native implementation rather than against a hand-written
+expectation. Containment is driven over real detached process groups.
+
+## Reading next
+
+[@smthrs/kernel](/api/kernel) owns the closed list and decorates these same tags
+with capability checks. [@smthrs/platform-bun](/api/platform-bun) and
+[@smthrs/platform-browser](/api/platform-browser) are the sibling bundles.
+
+## Pinned web connections
+
+`EgressHttpClient.layer(environment)` supplies the kernel destination-pinning
+contract. Web requests get a fresh dispatcher using only their authorized IP
+addresses. Host and TLS server name retain the requested hostname; TLS
+verification stays enabled. `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`
+select the route by hostname. Proxied requests use CONNECT to the approved IP,
+including plain HTTP, so the proxy cannot resolve the destination again.
+A proxy must support IP tunnels; refusal never falls back to direct access.
+Dispatchers close after their response body and are destroyed on failure or
+cancellation. Ordinary requests without the web destination policy retain the
+shared dispatcher, including local model connections.
+
+A request whose pinned addresses include none of the family Undici asks for
+fails with a `TransportError` whose `cause` is an `EgressAddressError` (`_tag`
+`@smthrs/platform-node/EgressAddressError`, `code` `no_approved_address`).
+
+Pinned web requests support HTTP and HTTPS proxies only. Other proxy schemes
+fail closed. The transport sets Host from the URL and discards caller-supplied
+proxy authorization and connection framing headers.
+
+## ProcessConfinement
+
+`ProcessConfinement.layer(options?)` provides the kernel's process confinement.
+Compose it as an input to `@smthrs/kernel/ChildProcessSpawner.layer`, alongside
+the same `GrantStore` and `Workspace` used for filesystem authorization. The
+kernel checks approval, snapshots effective grants, and confines every pipeline
+stage before spawning any stage. All `NodeHost` bundles supply this service;
+a guarded spawner without it refuses execution.
+
+`make(options?)` returns the same service directly. Options are:
+
+| Option               | Default                | Behavior                                                                                |
+| -------------------- | ---------------------- | --------------------------------------------------------------------------------------- |
+| `unavailable`        | `"refuse"`             | Refuse a missing mechanism; `"unconfined"` explicitly permits execution with a warning. |
+| `temporaryDirectory` | OS temporary directory | Parent for private, scope-owned temporary storage.                                      |
+| `host`               | Real host probes       | Injectable mechanism selection and filesystem probes.                                   |
+
+Linux needs `bwrap`; macOS needs `/usr/bin/sandbox-exec`. An installed mechanism
+that fails to start never falls back to unconfined execution. A shell request
+runs inside the wrapper, including its redirections and subprocesses. Streams,
+exit codes, and cancellation retain Effect's process contract.
+
+The profile accepts writable directory trees without broadening file grants to
+their parents. A writable tree also needs read authority and write authority
+for its directory entry because a writable bind exposes existing data and
+metadata. Unsupported globs, partial ceilings, and ambiguous deny regions
+stay closed. Networking opens only for unrestricted grants across all network
+actions. Closed networking blocks socket creation. Native agent commands keep
+host Unix sockets closed when IP networking opens, except the fixed macOS
+system DNS resolver endpoint.
+The launcher receives a minimal environment; the command's environment is
+restored inside confinement without putting its values in launcher arguments.
+macOS also denies delegation through host IPC services. Runtime paths and
+private temporary storage are bootstrap permissions;
+known host credential locations stay masked. Workspace links do not grant
+reads of their external targets. This boundary does not isolate trusted host
+JavaScript or supply a remote sandbox provider.
+
+## ProcessSandbox
+
+The build graph and `ProcessConfinement` share this mechanism implementation.
+`select(request, host)`, `plan(request, location, host)`, and `wrap(plan, argv,
+environment, host?)` resolve a request into an enforced command.
+`seatbelt`, `bubblewrap`, and `docker` render each supported mechanism;
+`host`, `validateWrites`, `environment`, `diagnose`, `isUnenforceable`, and
+`unenforceable` expose its host probes, validation, environment, diagnostics,
+and refusals. Requests name `network`, `reads`, and writable directory `writes`,
+with optional `mechanism`, `writeFiles`, `readOnly`, `externalReads`, `strict`,
+and `unixSockets`. Native agent confinement uses a strict process and IPC
+policy and closes Unix sockets; build tools retain their declared policy. Build
+output files may open a parent directory; agent permission profiles never use
+that build-specific option.