processkit-cli

processkit-cli is the standalone command runner for ProcessKit. It executes one shell-free command inside the public processkit crate's containment boundary, preserves the child's exit code, and records a versioned JSONL lifecycle stream without requiring a Rust or Python runtime at the call site.

The runner owns the command-line and event contracts. ProcessKit-rs remains the single source of truth for containment, teardown, PID-reuse discipline, and platform lifecycle behavior. The cover above represents the wider ProcessKit family; this CLI deliberately focuses on one contained run and its control plane rather than exposing the core crate's pipelines, retries, or scheduling APIs.

For an adoption-oriented comparison with timeout, process groups, systemd, containers, Tini, and PowerShell, see Why ProcessKit CLI?. The guide explicitly identifies the cases where a smaller or wider supervisor is the better fit.

Install

Download a platform archive from the latest GitHub release, or build and install from crates.io:

cargo install processkit-cli

Release archives contain the binary, shell completions, man pages, the JSON Schema, a SHA-256 checksum, and a signed build-provenance attestation. See Installation and distribution for target selection, checksum/attestation verification, completions, man pages, and post-install preflight.

Quick start

Run a command directly, with no shell between the runner and the program:

processkit-cli run --jsonl events.jsonl -- cargo --version

Child stdout and stderr pass through unchanged. Lifecycle events go only to events.jsonl, so an adapter can consume them without parsing or contaminating the child's output.

Use a stable run id when another process needs to inspect or stop the live run:

processkit-cli run --run-id build-42 --jsonl events.jsonl -- cargo test
processkit-cli inspect --run-id build-42 --json
processkit-cli cancel --run-id build-42

The control commands address a per-user registry entry and a live local IPC endpoint, never an operating-system PID. A reused PID therefore cannot retarget an old command at an unrelated process.

Choose a run shape

The Cookbook gives copyable complete invocations. The narrative guides explain why combinations are accepted or rejected.

Use from automation agents

An automation or coding agent can use this binary without a dedicated SDK. A project instruction can simply require external tools to be launched through processkit-cli run with a unique run id, finite deadlines, lifecycle JSONL, and bounded capture. The agent then has explicit inspect / cancel / wait / kill recovery operations instead of tracking a fragile PID or cleaning up by process name.

This makes agent-driven builds, tests, compilers, and long-lived workers more robust: descendant cleanup is scoped to the run, silent hangs can be bounded, diagnostics survive an interrupted agent turn, and different workloads can use different timeout, output, environment, and resource strategies. It does not pretend that disappearance of an arbitrary agent process is itself a portable cleanup signal; prefer foreground runs, terminate the runner during agent teardown, and use finite deadlines. Detached work needs a separate supervisor.

See Agent and automation workflows for a ready-to-paste agent policy and complete foreground, recovery, and escalation examples.

What the runner guarantees

• One owned process tree. Normal completion, timeout, cancellation, and runner errors tear down the current run's ProcessKit container. Cleanup never searches by executable name.
• Exit-code fidelity. A normal child exit is returned unchanged. Runner failures occupy the documented 100-119 band and also emit runner_exit, so a child code is never silently aliased.
• Separated streams. Child output stays on stdout/stderr; JSONL events stay in --jsonl; runner diagnostics never enter child stdout.
• Redacted diagnostics. Events contain a SHA-256 argv fingerprint and a classified worker hint by default. Raw arguments require --argv-raw.
• Bounded capture. --capture-dir tees stdout and stderr into separate, size-capped transcripts with byte counts, hashes, and truncation metadata.
• Honest platform reporting. run_started records the active containment mechanism and the real abrupt-runner-death cleanup guarantee rather than presenting every operating system as equivalent.

Command surface

Run processkit-cli <command> --help for the complete flag set. The integration guide shows a fail-closed adapter workflow from preflight through cleanup.

Platform behavior

Every ordinary teardown still uses the active container on every supported platform. The last column is intentionally narrower: it describes only a crash, SIGKILL, or comparable event that prevents the runner from executing its own cleanup path. See the architecture and troubleshooting guide for the exact caveats.

Guides

The 60-second tour

# 1. Prove the installed runner supports the contract your caller needs.
processkit-cli probe --json \
  --require-schema-version 1 \
  --require-exit-code-band 100-119 \
  --require-surface run:--capture-dir

# 1b. Once per host: prove this machine can actually contain and control a process.
processkit-cli doctor --json

# 2. Start one shell-free command with a stable id and bounded transcripts.
processkit-cli run --run-id demo --capture-dir ./demo-output \
  --jsonl demo.jsonl -- cargo test

# 3. While it is live, inspect or cancel it from another process.
processkit-cli inspect --run-id demo --json
processkit-cli cancel --run-id demo

# 4. Read its lifecycle story back — live, or long after it finished.
processkit-cli events --run-id demo --follow
processkit-cli events --file demo.jsonl

# 5. Discover or clean up registry state after an orchestrator restart.
processkit-cli list --json
processkit-cli prune --dry-run --json

The JSONL file is the durable lifecycle record. The registry and control endpoint exist only while a run is live (or as detectable stale leftovers after an abrupt runner death).

Source, release history, and contribution guidance live in the GitHub repository.

Why ProcessKit CLI?

ProcessKit CLI is for one shell-free command whose process tree must be cleaned up on ordinary completion, timeout, or cancellation, while an adapter receives a stable lifecycle record. It is not a universal service manager, container runtime, or security sandbox. Choose the tool that owns the widest requirement; the choices below can also be layered.

Quick choice

Comparison at a glance

The ProcessKit row is deliberately conditional. Read the actual mechanism and abrupt_cleanup values from run_started; do not infer Windows' whole_tree owner-death guarantee on Linux, FreeBSD, or macOS. The normative matrix is in Platform support.

Compared with GNU timeout

GNU timeout is the right answer for many shell scripts: it is already installed, concise, supports a configurable signal and kill-after interval, and normally preserves a command's status when the command finishes before the deadline.

Choose ProcessKit CLI when the deadline is only one part of the contract: cleanup must be tied to the obtained container, stdout and stderr must remain separate from machine events, another process must inspect or stop a live run, or an adapter must distinguish child exit, timeout, cancellation, and runner failure without reverse-engineering shell status conventions. ProcessKit CLI is larger and requires a JSONL destination; timeout is simpler when no consumer needs those guarantees.

Compared with setsid or start_new_session

POSIX setsid creates a session and a new process group. Python's start_new_session=True requests the same primitive. That is useful for terminal detachment and for giving the caller a group to signal, but it is not a persistent list of every descendant: a cooperating or hostile descendant may start another session, and the session does not gain a kill-on-owner-death policy.

ProcessKit itself may honestly fall back to a process group, especially on macOS/non-FreeBSD BSDs or when Linux cgroup delegation is unavailable. In that case the CLI reports mechanism as process_group; resource-limit requests fail rather than becoming no-ops, and the documented escape and abrupt-death limitations apply. FreeBSD instead reports its distinct process_reaper mechanism, whose normal teardown and membership scope cover the whole reaper tree but whose resource limits and statistics remain unsupported. Use plain setsid when that primitive plus your own wait/signal code is sufficient.

Compared with systemd-run --scope

On a systemd Linux host, systemd is the natural owner of long-lived service lifecycle and the cgroup tree. A transient service or scope gives administrators native unit state, resource policy, accounting, and journal integration. Systemd's documented delegation model is also the correct way to grant a nested manager its own cgroup subtree. Prefer it for host services, boot integration, restart policy, and durable supervision.

ProcessKit CLI instead standardizes one child run across operating systems and emits its own portable event schema. It does not replace systemd. They can be layered: let systemd own the service and its outer limits, and use ProcessKit CLI inside it when an adapter still needs per-invocation JSONL and the same command contract on Windows and macOS. In a normal non-delegated systemd unit, ProcessKit may report process_group; do not mount or rewrite cgroup state merely to force a different mechanism.

Compared with a container runtime

A container runtime solves a wider isolation and deployment problem. Docker, for example, provides cgroup-backed resource constraints and configurable restart policies, while an orchestrator adds scheduling, health, networking, secrets, and rollout policy. ProcessKit CLI provides none of that isolation and intentionally trusts other processes running as the same OS user.

Use the outer runtime for container lifetime and limits. ProcessKit CLI can be the container entrypoint when one payload still needs its portable JSONL, timeout/cancel outcome, and local control plane. Cgroup v2 is not automatically delegated inside ordinary containers, so this layering can legitimately report the process-group fallback; see Running in containers.

Compared with Tini or another subreaper

Tini is intentionally small: as PID 1 or a Linux subreaper it adopts and reaps zombies, forwards signals to its child, can signal the child's process group, and exits with the child's status. Docker's --init mode addresses the same PID 1 hygiene problem.

That is a feature, not an omission: Tini is an excellent choice when zombie reaping and signal forwarding are the whole problem. ProcessKit CLI adds a command deadline, reported containment, capture, resource-limit negotiation, versioned events, and live-run IPC. It is correspondingly more opinionated and requires persistent paths for JSONL and registry state.

Compared with PowerShell jobs and raw Windows Job Objects

A PowerShell background job is a shell-level concurrency and result abstraction. It exposes job state and PowerShell's output, error, warning, and other streams; remote and thread jobs cover still different execution shapes. The official about_Jobs documentation describes that session-owned repository. Prefer it when a PowerShell operator wants asynchronous objects or remoting rather than a language-neutral binary contract.

A PowerShell job is not the same thing as the Win32 kernel Job Object used by ProcessKit on Windows. A raw Win32 Job Object can group processes, enforce limits, and terminate the job on last-handle close. It is the right primitive for a Windows-native host willing to implement its own spawn race handling, nested-job policy, exit mapping, diagnostics, IPC security, and wire schema. ProcessKit CLI packages that work behind a tested command surface, but a custom host can expose deeper application-specific integration.

Exit status, telemetry, and secrets

ProcessKit CLI preserves the child's exact status only when the child chose the ordinary outcome. A timeout, cancellation, output-overflow stop, or runner failure uses a documented reserved code and a terminal runner_exit event, so those cases cannot masquerade as the child's decision. See the exit-code contract and JSONL schema.

The JSONL stream is separate from child stdout/stderr and versioned for adapters. Argv is hashed by default, with only a classified worker hint; raw argv is an explicit --argv-raw opt-in. Other supervisors may provide richer native logs or object streams, but their command metadata has its own disclosure rules. Do not assume that switching wrappers preserves ProcessKit CLI's redaction contract.

A practical decision rule

1. Need isolation, deployment, restart, or a durable host service? Choose the container runtime/orchestrator or systemd first.
2. Need only a Unix deadline, a new session, PowerShell concurrency, or PID 1 reaping? Use the smaller native tool.
3. Need one cross-platform invocation contract plus tree teardown and lifecycle JSONL? Use ProcessKit CLI, then validate mechanism and abrupt_cleanup for the actual host.
4. Need both layers? Let the outer supervisor own machine/container policy and ProcessKit CLI own one inner command. Treat the outer supervisor's OOM, eviction, and restart events as authoritative for that outer boundary.

Continue with Installation and distribution, or start from the copyable Cookbook.

Installation and distribution

processkit-cli is distributed as one self-contained executable. A machine that runs the binary does not need Python, a virtual environment, or a Rust toolchain. Choose a prebuilt archive directly or through cargo-binstall for production and CI; use cargo install when building from source is already part of your environment.

Prebuilt archives

One-command verified install

The repository installers select the host archive, download its published .sha256 sidecar, fail closed on any mismatch, and install only after successful verification. They refuse to replace an existing destination unless running that file with --version identifies it as processkit-cli.

Linux or macOS:

curl -fsSL https://raw.githubusercontent.com/ZelAnton/ProcessKit-CLI/main/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/ZelAnton/ProcessKit-CLI/main/install.ps1 | iex

The defaults install the latest release under ~/.local/bin. For a pinned version, custom destination, or explicit target, download the script and pass its options directly:

sh install.sh --version X.Y.Z --install-dir /opt/processkit/bin

.\install.ps1 -Version X.Y.Z -InstallDir C:\Tools\ProcessKit

The scripts print the installed binary's --version result and tell you when the destination is not yet on PATH. The POSIX installer supports the published Linux x86_64/Arm64 and macOS Arm64 builds; use --target x86_64-unknown-linux-musl or --target aarch64-unknown-linux-musl when the static musl archive is required for the matching architecture. The PowerShell installer selects x86_64 or Arm64 from PROCESSOR_ARCHITECTURE.

Every GitHub Release contains one archive per supported target:

The naming convention is processkit-cli-v<version>-<target>.<format>. Each archive has a neighboring .sha256 file and a signed GitHub build-provenance attestation.

Linux and macOS

version=X.Y.Z
target=x86_64-unknown-linux-gnu
archive="processkit-cli-v${version}-${target}.tar.gz"
base="https://github.com/ZelAnton/ProcessKit-CLI/releases/download/v${version}"

curl -sSLO "$base/$archive"
curl -sSLO "$base/$archive.sha256"
sha256sum -c "$archive.sha256" # macOS: shasum -a 256 -c
tar -xzf "$archive"
install -m 0755 processkit-cli "$HOME/.local/bin/processkit-cli"

Windows PowerShell

$version = 'X.Y.Z'
$target = 'x86_64-pc-windows-msvc'
$archive = "processkit-cli-v$version-$target.zip"
$base = "https://github.com/ZelAnton/ProcessKit-CLI/releases/download/v$version"

Invoke-WebRequest "$base/$archive" -OutFile $archive
Invoke-WebRequest "$base/$archive.sha256" -OutFile "$archive.sha256"
Get-FileHash -Algorithm SHA256 $archive
# Compare the printed hash with the value in $archive.sha256 before extracting.
Expand-Archive $archive -DestinationPath .\processkit-cli

Put processkit-cli.exe in a directory already present in PATH, or add its installation directory to PATH for the account that launches the runner.

Verify provenance

The checksum detects damaged or substituted bytes. The attestation additionally proves that GitHub Actions built the archive from this repository:

gh attestation verify "$archive" --repo ZelAnton/ProcessKit-CLI

Both checks are useful in automation: the checksum is portable and offline once downloaded, while attestation verification ties the bytes to the release workflow and repository identity.

Package-manager manifests

After the release-archive matrix settles, the release workflow reads the published .sha256 sidecars for each archive the channels use and attaches distributor-ready manifests for winget, Scoop, and a Homebrew tap. The same files are collected in processkit-cli-v<version>-package-manifests.tar.gz, with a neighboring bundle checksum. The generator rejects a sidecar unless it names the exact archive the manifest will download, so URLs and digests cannot be paired accidentally.

Package managers need a repository of their own; a manifest attached to this project's GitHub Release is distributor input, not a public package source. The release workflow can publish the Homebrew and Scoop files into repositories this project owns, but that publication stays off until an operator provisions those repositories (see "Publishing to a tap or bucket" below), and winget's is external by nature. The current publication boundary is explicit:

Once a source is actually published, that package manager provides its normal install and upgrade lifecycle. Until its availability row changes, use the verified installer, cargo-binstall, or cargo install; do not paste a future bucket/tap name into automation and assume it exists.

Publishing to a tap or bucket

The last job of .github/workflows/release.yml, publish-package-repos, takes the formula and Scoop manifest the job before it attached to the Release and pushes each into the package repository it belongs in. It is inert until an operator sets that up, and it cannot fail a release:

To turn a channel on:

1. Create the target repository under the same owner. For Homebrew the name is not free-form: brew tap <owner>/tap resolves to <owner>/homebrew-tap.
2. Add the repository secret (Settings → Secrets and variables → Actions) with a token that can push to that repository and nothing else — a fine-grained personal access token with Contents: read and write on the tap/bucket alone, or a GitHub App installation token. The workflow's built-in GITHUB_TOKEN cannot be used: it is scoped to this repository.
3. Optionally set the repository variable HOMEBREW_TAP_REPOSITORY or SCOOP_BUCKET_REPOSITORY when the target is named differently. The token secret alone decides whether a channel publishes; the variable only renames the target.
4. After a release has actually published, update the availability table above. That table, not this section, is what a reader is told to trust.

The two channels are independent — configure either, both, or neither. The job publishes exactly the bytes attached to the Release rather than regenerating them, pushes nothing when the target already holds identical bytes, and can be re-run on its own. Without the secret it skips and logs a notice naming the repository and secret to create. A configured channel that fails (repository missing, token expired, protected branch) is reported as an annotation but leaves the release green, because publication runs after crates.io, the tag, the GitHub Release, and every asset upload.

For this repository today, neither ZelAnton/homebrew-tap nor ZelAnton/scoop-bucket exists, so no release has published to either and the availability rows above still say so. As soon as the operator creates ZelAnton/homebrew-tap and sets HOMEBREW_TAP_TOKEN, the next release publishes the formula there automatically and brew install ZelAnton/tap/processkit-cli becomes a working command — the point at which that row has to change.

Why winget is submitted by hand

winget has no repository under this project's control. A version becomes installable only after a pull request to microsoft/winget-pkgs passes Microsoft's automated validation and human review. Automating that submission with wingetcreate submit — the standard tool — would require a maintained fork of that repository plus a token scoped broadly enough to push to it, and a green release step still would not mean the version is installable, because the decision belongs to reviewers outside this project and a rejected or stalled pull request is not something a release workflow can act on. The three-file manifest is therefore attached to the Release and submitted deliberately, by hand or with wingetcreate submit, when the maintainer chooses to.

Install with cargo-binstall

If cargo-binstall is already available, install the matching prebuilt binary without a local source build:

cargo binstall processkit-cli

The crate metadata resolves to the same GitHub Release archive documented above: .tar.gz with a root-level processkit-cli on Unix, and .zip with a root-level processkit-cli.exe on Windows. The adjacent .sha256 and signed provenance attestation belong to that same release, but cargo-binstall does not verify those sidecars automatically. Use the manual archive path when policy requires those checks or when you also need completions/, man/, or schema/.

Install from crates.io

cargo install processkit-cli

This builds for the current host and installs into Cargo's binary directory. Use cargo install processkit-cli --locked when you want the dependency graph from the published lockfile rather than a newly resolved compatible graph.

Building from source also generates shell completions and man pages under target/assets/ in the build tree. Release archives already contain those assets.

Shell completions

The completions/ directory contains bash, zsh, fish, PowerShell, and Elvish scripts generated from the same clap definition as the binary.

# bash
install -Dm644 completions/processkit-cli.bash \
  "$HOME/.local/share/bash-completion/completions/processkit-cli"

# fish
install -Dm644 completions/processkit-cli.fish \
  "$HOME/.config/fish/completions/processkit-cli.fish"

$destination = Join-Path (Split-Path $PROFILE) '_processkit-cli.ps1'
Copy-Item completions\_processkit-cli.ps1 $destination
Add-Content $PROFILE ". '$destination'"

The exact filenames are visible in the extracted completions/ directory; shell conventions differ slightly between package managers.

Man pages

Each subcommand has a page under man/man1/, plus the top-level processkit-cli.1 page:

install -Dm644 man/man1/*.1 "$HOME/.local/share/man/man1/"
man processkit-cli-run

Schema files in an archive

Release archives carry schema/schema.json and schema/events.jsonl. They are the machine-readable JSON Schema and golden event stream for the binary's current schema_version. An installed binary can print the same schema without an archive:

processkit-cli probe --json --print-schema > processkit-cli.schema.json

See Compatibility and upgrades before replacing a runner that is consumed by an adapter.

Post-install verification

processkit-cli --version
processkit-cli probe --json \
  --require-schema-version 1 \
  --require-exit-code-band 100-119 \
  --require-surface run \
  --require-surface run:--jsonl

The first command confirms which executable PATH resolves. The second is a side-effect-free compatibility check: it launches no child, creates no registry entry, and exits with 110 when a requirement is not met.

Next steps

• Cookbook — copyable task-oriented examples.
• Running commands — argv, working directory, environment, run identity, and foreground behavior.
• Platform support — containment strength and the meaning of mechanism / abrupt_cleanup.

Cookbook

Task-oriented command shapes for ProcessKit CLI. Each recipe keeps the JSONL destination explicit and places the child after --, so the boundary between runner options and child argv remains visible.

For copyable scripts exercised on Linux and Windows in CI, see the runnable examples.

Run a command and preserve its exit code

processkit-cli run --jsonl run.jsonl -- cargo test

For a foreground run, the CLI exits with the child's exact code after tearing down the contained tree. Runner-owned failures and cancellations use the reserved band; read Exit-code contract when the caller must distinguish them from a child that returned the same number.

Run in another directory

processkit-cli run \
  --cwd ./services/catalog \
  --jsonl catalog-test.jsonl \
  -- cargo test --locked

run_started.cwd records the resolved absolute directory.

Start from a controlled environment

processkit-cli run \
  --env-clear \
  --env PATH=/usr/bin:/bin \
  --env HOME=/tmp/worker-home \
  --env CI=true \
  --jsonl hermetic.jsonl \
  -- worker

Use absolute program paths when clearing PATH entirely. Applied order is clear → remove → env-file → set → --run-id-env.

Remove one inherited secret

processkit-cli run \
  --env-remove GITHUB_TOKEN \
  --env-remove AWS_SECRET_ACCESS_KEY \
  --jsonl sanitized.jsonl \
  -- third-party-tool

Environment values are not placed in JSONL, but the child can still echo them.

Let the child know which run it is in

processkit-cli run \
  --run-id-env PROCESSKIT_RUN_ID \
  --jsonl correlated.jsonl \
  -- ./build.sh

The child reads the run's final id — the explicit --run-id when given, the generated one otherwise — from PROCESSKIT_RUN_ID, matching run_started.run_id and the registry record. Correlation only: the value authorizes nothing and anything that can set an environment variable can forge it.

Capture output without echoing it live

processkit-cli run \
  --no-echo \
  --capture-dir ./capture \
  --capture-max-bytes 16m \
  --jsonl captured.jsonl \
  -- noisy-build

Read output_captured.truncated before treating either file as complete.

Feed a finite input file

processkit-cli run \
  --stdin-file request.json \
  --capture-dir ./response \
  --jsonl request-run.jsonl \
  -- json-transform

The file closes the child's stdin at EOF and its bytes never enter argv.

Run an interactive terminal program

processkit-cli run --inherit-stdio --jsonl interactive.jsonl -- repl-tool

The child sees the caller's existing terminal. Capture, no-echo, idle timeout, detach, and --create-no-window are unavailable in this mode. This preserves a terminal; it does not create a PTY.

Bound total runtime

processkit-cli run \
  --timeout 15m \
  --grace 10s \
  --jsonl timed.jsonl \
  -- integration-tests

Expiry emits timeout with reason: "overall", then the cleanup sequence and terminal runner_exit.

Kill a worker that stops producing output

processkit-cli run \
  --idle-timeout 2m \
  --grace 5s \
  --jsonl worker.jsonl \
  -- build-worker

Every observed stdout/stderr chunk re-arms the idle clock. Use only for tools whose silence is a meaningful health signal.

Give no soft-stop grace

processkit-cli run --timeout 30s --grace 0 --jsonl fast.jsonl -- disposable-task

0 is legal for grace and means immediate progression to the hard tier. It is rejected for overall, idle, and wait deadlines.

Launch out of band and supervise later

processkit-cli run \
  --detach \
  --run-id nightly-build \
  --capture-dir ./nightly-output \
  --jsonl nightly.jsonl \
  -- cargo build --release

processkit-cli inspect --run-id nightly-build
processkit-cli wait --run-id nightly-build --timeout 30m

The detached launcher's 0 means “started.” Read terminal JSONL for the child's eventual result.

Inspect a live tree as JSON

processkit-cli inspect --run-id nightly-build --json

The snapshot includes the mechanism, root pid, start time, and current members with nullable enriched fields. It is an observation at request time, not a durable history.

Ask one run to stop cooperatively

processkit-cli cancel --run-id nightly-build
processkit-cli wait --run-id nightly-build --timeout 30s

cancel acknowledges the request; wait is the completion barrier.

Hard-kill one run now

processkit-cli kill --run-id wedged-worker
processkit-cli wait --run-id wedged-worker --timeout 10s

This skips soft stop and grace and produces a distinct killed outcome.

Shut down every currently live run

processkit-cli cancel --all
processkit-cli wait --all --timeout 30s
processkit-cli prune --dry-run
processkit-cli prune

Both --all operations use their own snapshots. Prevent new launches during a global shutdown or repeat the sequence to catch later registrations.

Discover runs without knowing their ids

processkit-cli list
processkit-cli list --json
processkit-cli list --label pipeline=ci --health live

The human table abbreviates argv_sha256; JSON Lines carry the full digest. live, stale, and unprobed are intentionally distinct health states. Label filters are exact and conjunctive, matching the aggregate control commands. New records also expose absolute jsonl and optional capture_dir locators, so a supervisor discovering a detached run can open its artifacts without launch-time state.

Preview stale-record cleanup

processkit-cli prune --dry-run --json

Only entries whose liveness probe succeeded and reported stale appear as candidates. unprobed entries are preserved.

Verify a runner before using it

processkit-cli probe --json \
  --require-schema-version 1 \
  --require-exit-code-band 100-119 \
  --require-surface run:--capture-dir \
  --require-surface cancel:--all \
  --require-surface wait:--all

Exit 110 means the binary is incompatible with at least one requirement. No child or registry entry is created.

Qualify the host, not just the binary

processkit-cli doctor --json
processkit-cli doctor --require-abrupt-cleanup whole_tree
processkit-cli doctor --json --check-resource-controller --require-resource-controller

probe proves the binary; doctor proves the machine, by running a bounded scratch containment of this binary's own harmless child and reporting the registry, containment, control-transport, and cleanup facts it observed. Exit 116 means a phase failed or a --require-* expectation about the host was not met — and a failed phase keeps a diagnostics directory the report names. Unlike probe it has real (self-cleaning) side effects, so run it once per host at setup time rather than before every launch.

Export the exact event schema

processkit-cli probe --json --print-schema > processkit-cli.schema.json

This prints the schema embedded in that exact binary, which is useful when the consumer has an installed executable but no matching git checkout.

Require whole-tree resource caps

processkit-cli run \
  --max-memory 2g \
  --max-processes 64 \
  --cpu-quota 2 \
  --jsonl limited.jsonl \
  -- untrusted-compiler

Unsupported enforcement fails before spawn with limit_hit; it never runs the child without the requested policy. See Resource limits before using this in Linux containers or systemd.

Hide a detached Windows console

processkit-cli run --detach --create-no-window `
  --run-id headless-worker `
  --jsonl headless.jsonl `
  -- worker.exe

Use this only for a child that does not require a console. The runner never forces CREATE_NO_WINDOW by default.

Invoke a shell explicitly

processkit-cli run --jsonl shell.jsonl -- sh -c 'make all && make test'

processkit-cli run --jsonl shell.jsonl -- `
  pwsh -NoProfile -Command 'Get-ChildItem Env: | Sort-Object Name'

The shell is now an explicit child program. Its quoting, expansion, and pipeline semantics are outside ProcessKit CLI.

Keep child stdout machine-clean

processkit-cli run --jsonl events.jsonl -- report-generator > report.bin

JSONL never goes to stdout. Runner diagnostics use stderr, and child stderr is also forwarded there. Use --no-echo --capture-dir when stdout must not be forwarded at all.

Read a run's lifecycle events

processkit-cli events --run-id build-42            # what happened, rendered
processkit-cli events --run-id build-42 --follow   # ... as it happens
processkit-cli events --file build-42.jsonl        # once the record is gone
processkit-cli events --file build-42.jsonl --json # raw lines, for a parser

events is read-only: it resolves the stream through the registry (--run-id) or reads a path directly (--file), never contacts the run, and mutates nothing. It hands out only complete lines, and --follow stops at the terminal runner_exit — or, for a runner killed before it could write one, once the run is gone and the stream has stopped growing.

Check a stream against the event schema

processkit-cli events --file fixture.jsonl --validate

Checks every line against the schema embedded in that exact binary and reports each violation by line number; exit 0 when all lines conform, 114 (EVENTS_INVALID) when any does not. Useful in CI for an adapter's own recorded fixtures — no separate validator, and no second copy of the schema to keep in sync.

Tail lifecycle events safely in your own reader

When something other than events reads the stream, treat JSONL as an append-only sequence of complete lines. A reader should:

1. buffer until newline;
2. parse one object;
3. verify schema_version;
4. dispatch on the event discriminator, tolerating unknown event types, unknown fields, new always-present fields on an event it already parses, and repeats of an event type that previously occurred only once (see Compatibility and upgrades);
5. stop only after terminal runner_exit or an explicit external recovery decision.

The file may end with a partial line if the runner is killed during a write. Do not parse that suffix as a complete event.

Recover after the supervising application restarts

processkit-cli list --json
processkit-cli inspect --run-id recovered-run --json
processkit-cli wait --run-id recovered-run --timeout 30s

Use the registry for current liveness and the JSONL file for durable history. Never reconnect by recorded PID.

Give an automation agent a bounded execution policy

Instruct the agent to launch external tools through a foreground runner with a unique run id, finite deadlines, lifecycle JSONL, and bounded capture:

mkdir -p .agent-runs/agent-task-42
processkit-cli run --run-id agent-task-42 \
  --timeout 20m --idle-timeout 3m \
  --capture-dir .agent-runs/agent-task-42/capture \
  --jsonl .agent-runs/agent-task-42/events.jsonl \
  -- <program> <args...>

The agent should cancel and wait by run id, never clean up by PID or process name, and reserve --detach for work with a separate supervisor. See Agent and automation workflows for a ready-to-paste instruction, recovery strategy, and the precise limits of cleanup when the agent itself stops.

Use as a container entrypoint

ENTRYPOINT ["/usr/local/bin/processkit-cli", "run", "--jsonl", "/run/events.jsonl", "--"]
CMD ["/app/worker"]

Exec form preserves signal delivery and avoids a shell wrapper. Ensure /run is writable and the orchestrator's termination grace exceeds the CLI's grace.

Diagnose a failed start

1. Read stderr for the operator message.
2. Read JSONL for spawn_failed, limit_hit, or container_failed.
3. Read terminal runner_exit for runner code and nullable child code.
4. If a registry entry remains after abrupt runner death, use list and prune --dry-run; do not kill the recorded pid.

Guide map

Runnable examples

The repository ships four paired POSIX and PowerShell examples. They are executed against the built binary on Linux and Windows in CI, so their public command shapes cannot drift unnoticed.

See the repository's examples README for prerequisites, PROCESSKIT_CLI_BIN selection, and cleanup guarantees.

Running external tools from automation agents

An automation or coding agent can use processkit-cli as the execution boundary for builds, tests, compilers, package managers, development servers, and other external tools. The agent does not need a special SDK: it only needs to be instructed to invoke the tool through the runner instead of starting it directly.

This is especially useful for commands that can spawn workers, become silent, hold output handles open, or outlive the agent action that launched them.

Why use a runner

A direct process launch gives an agent one process handle, but the real workload may be a tree: a compiler can start helpers, a test host can start workers, and a build tool can keep reusable nodes alive. Treating only the root PID as the unit of cleanup creates several failure modes:

• stopping the agent or cancelling its tool call may leave descendants running;
• a descendant that retains stdout or stderr can make the caller wait forever;
• a lost process handle leaves the next agent turn with little reliable state;
• cleanup by process name can terminate unrelated work;
• a reused PID can make delayed cleanup target the wrong process;
• unbounded output and silent hangs consume time, disk, and compute without a useful diagnostic record.

ProcessKit CLI gives the agent a higher-level unit: one run with a contained process tree, explicit deadlines, bounded transcripts, versioned lifecycle events, and a run-id-based control plane.

A drop-in instruction for an agent

The following policy can be placed in an AGENTS.md, system prompt, tool description, or project automation guide. Adjust paths and default durations to the repository:

When launching an external command that may run for more than a few seconds, spawn descendants, or require reliable cleanup, execute it through processkit-cli run rather than starting it directly. Create a private, per-invocation run directory and a unique, non-secret run id. Pass the program and its arguments after -- without a shell unless shell syntax is explicitly required. Always write JSONL events, set a total timeout, add an idle timeout when silence indicates a stuck tool, and use bounded capture when output may be needed for diagnosis. Prefer a foreground run. On cancellation or uncertainty, address the run by its run id with inspect, cancel, wait, and finally kill if graceful cancellation does not finish. Never clean up by process name or by a PID copied from earlier output. Use --detach only when a separate supervisor deliberately owns the continuing run.

The executable can be preflighted once per agent session:

processkit-cli probe --json \
  --require-schema-version 1 \
  --require-exit-code-band 100-119 \
  --require-surface run:--timeout \
  --require-surface run:--capture-dir \
  --require-surface cancel:--run-id

That preflight is about the executable. If the agent runs on a machine it has not used before — a fresh CI image, a new container, an unfamiliar developer box — the host itself is worth qualifying once as well, since a compatible binary can still meet an unwritable registry directory or a containment mechanism the kernel will not hand out:

processkit-cli doctor --json

It performs one bounded scratch containment of this binary's own harmless child and reports what the host did, exiting 116 if a phase failed. Unlike probe it has real (self-cleaning) side effects, so it belongs at session setup rather than before every tool invocation.

An agent can then adapt this invocation template to each tool:

# Create RUN_DIR first and choose a unique RUN_ID for this invocation.
processkit-cli run \
  --run-id "$RUN_ID" \
  --timeout 20m \
  --idle-timeout 3m \
  --grace 5s \
  --capture-dir "$RUN_DIR/capture" \
  --capture-max-bytes 16m \
  --jsonl "$RUN_DIR/events.jsonl" \
  -- <program> <args...>

The runner's exit code is the program's exit code on normal completion. The documented 100-119 band is a useful first signal for runner outcomes, but a child can coincidentally return a number in the same range. The terminal runner_exit event is authoritative: its source and separate child_code let the agent distinguish a failing test from a timeout, cancellation, spawn failure, or backend failure without guessing from the number alone.

A robust foreground strategy

Foreground execution is the safest default for an agent action:

1. Generate a unique run id and create its diagnostic directory.
2. Start processkit-cli run with an overall timeout and durable JSONL path.
3. Stream ordinary child output to the agent, or use --no-echo with bounded capture when live output would consume too much context.
4. Interpret the returned code together with terminal runner_exit.
5. If the tool call is cancelled, send a supported stop signal to the foreground runner and wait for its normal container teardown.
6. If completion becomes uncertain, use list --json and inspect --json rather than guessing from a PID.
7. Request cancel, wait for a bounded interval, and use kill only as the escalation step.
8. Retain JSONL and capture files for failed runs; discard them according to the project's artifact policy after success.

This makes retries safer because each attempt has a distinct identity and diagnostic record. A later agent turn can tell whether an earlier attempt is live, finished, stale, or unprobeable before deciding whether to retry.

Strategy examples

Build or test with a hard ceiling

mkdir -p .agent-runs/agent-test-42
processkit-cli run --run-id agent-test-42 \
  --timeout 15m --idle-timeout 2m \
  --capture-dir .agent-runs/agent-test-42/capture \
  --jsonl .agent-runs/agent-test-42/events.jsonl \
  -- cargo test --all-features

This protects the agent from both a long-running test suite and a build worker that stops producing output.

Keep verbose output out of the agent context

mkdir -p .agent-runs/agent-build-42
processkit-cli run --run-id agent-build-42 \
  --timeout 20m --no-echo \
  --capture-dir .agent-runs/agent-build-42/capture \
  --jsonl .agent-runs/agent-build-42/events.jsonl \
  -- cargo build --release

The agent can read the bounded transcript only when it needs to diagnose a failure. JSONL still provides the lifecycle and terminal result.

Recover after an interrupted agent turn

processkit-cli list --json
processkit-cli inspect --run-id agent-build-42 --json
processkit-cli cancel --run-id agent-build-42
processkit-cli wait --run-id agent-build-42 --timeout 30s --report-outcome

If the bounded wait expires and the run must stop immediately:

processkit-cli kill --run-id agent-build-42

Control commands resolve the registry identity and live IPC endpoint. They do not target the root PID printed by an earlier observation. The reporting wait keeps its own exit-code contract and emits the remembered run's terminal runner_exit fields as JSON; status:"unknown" means the waiter could not recover that event and must not guess the outcome.

Apply a policy to expensive tools

Where the platform can enforce whole-tree limits, an agent can combine time and resource budgets:

mkdir -p .agent-runs/agent-compiler-42
processkit-cli run --run-id agent-compiler-42 \
  --timeout 20m --max-memory 4g --max-processes 64 --cpu-quota 4 \
  --jsonl .agent-runs/agent-compiler-42/events.jsonl \
  -- compiler <args...>

Limit requests fail before spawn when the active backend cannot enforce them. The agent should treat that as a policy failure, not silently rerun the command without limits.

What happens when the agent stops

The runner substantially improves cancellation and cleanup, but it is important to state the boundary precisely:

• If the agent host cancels the foreground tool call by delivering a supported stop signal to processkit-cli, the runner performs its normal whole-container teardown.
• Overall and idle timeouts remain active inside a surviving runner, so work is bounded even if the agent no longer observes the call.
• The runner does not monitor an agent identity and cannot infer that an unrelated parent application has disappeared. If the host abandons the runner without terminating it, the run may continue until its own deadline or child completion.
• If the runner itself is killed before normal teardown, the abrupt_cleanup field reports the real platform guarantee: whole_tree for the Windows Job Object; direct_child_only on Linux, whether the mechanism is cgroup_v2 or the process_group fallback; none for FreeBSD's process_reaper; and none for the macOS/other-Unix process_group fallback. FreeBSD's reaper still covers the whole tree during normal teardown; none describes only cleanup after an abrupt runner death.
• A detached run deliberately outlives the launching call. It requires a durable JSONL path, a stable run id, deadlines, and a separate supervisor or recovery policy.

For a host that must guarantee cleanup when an agent session ends, combine the runner with an explicit host policy: keep run in the foreground, terminate the runner during agent teardown, require finite deadlines, and reconcile remaining registry entries before the next session. Do not describe --detach as a leak prevention mechanism.

Diagnostic workflow for agents

When a command fails or appears stuck, an agent can collect evidence in this order:

1. Read the processkit-cli exit code.
2. Read the final complete JSONL records, especially runner_exit and any preceding timeout, cancellation, spawn, container, or limit event — processkit-cli events --run-id <id> (or --file <events.jsonl> once the registry record is gone) renders them without an external tailer, and events --json hands the raw lines to a parser unchanged.
3. Read bounded stdout/stderr capture only when the program's output is needed.
4. If the run may still be live, call inspect --json for the current member snapshot and containment mechanism.
5. Use cancel followed by bounded wait; escalate to kill only when needed.
6. Use prune --dry-run --json before removing confirmed-stale registry state; add the same --label KEY=VALUE filters to preview and reap when the registry is shared with other projects or orchestrators.

This separates program failure, runner failure, policy failure, and ambiguous external interruption instead of collapsing them into “the command hung.”

See also

• Cookbook — shorter copyable command recipes.
• Running commands — argv, environment, and flag interactions.
• Timeouts and cancellation — deadline and escalation semantics.
• Detached runs — the intentionally out-of-band mode.
• Integration guide — a complete adapter lifecycle.
• Platform support — normal and abrupt cleanup strength.

Running commands

run executes exactly one program inside a ProcessKit container and keeps the runner alive until the child and its descendants have been reaped. The program is always passed after --:

processkit-cli run [RUNNER OPTIONS] --jsonl <events.jsonl> -- <program> [args...]

The separator makes the ownership boundary explicit. Everything before -- belongs to processkit-cli; everything after it is the child argv.

Shell-free argv

There is no shell mode. The runner does not expand wildcards, interpolate variables, interpret pipes, or process redirection characters:

processkit-cli run --jsonl run.jsonl -- git status --short

This starts git directly with two arguments. A string such as *.rs, $HOME, %TEMP%, |, or > remains a literal argument unless the child itself gives it special meaning.

If a shell is genuinely required, name it as the program so that the security and quoting boundary is visible at the call site:

processkit-cli run --jsonl shell.jsonl -- sh -c 'printf "%s\n" "$HOME"'

processkit-cli run --jsonl shell.jsonl -- pwsh -NoProfile -Command 'Get-Date'

Prefer direct execution whenever possible. It preserves argv boundaries and avoids a second language's quoting and injection rules.

Working directory

By default the child inherits the runner's current directory. Set it explicitly when the caller and payload use different roots:

processkit-cli run --cwd ./service --jsonl service.jsonl -- cargo test

The runner resolves the effective directory before launch and records its absolute form in run_started.cwd. An invalid or inaccessible directory fails before the child starts.

Environment

Without environment flags, the child inherits the runner's environment. Five options make the result explicit:

Application order is fixed, regardless of flag order: clear, remove, env-file, explicit set, run-id injection. Repeated files are applied in argument order, an explicit --env therefore wins over every file or removal for the same key, and --run-id-env — applied last — wins over all of them. A file read, UTF-8, or syntax failure is SETUP (111) before the child starts. Every flag that names a key holds it to one rule: non-empty, and no whitespace or control characters. Diagnostics for malformed entries do not repeat their values.

processkit-cli run \
  --env-clear \
  --env PATH=/usr/bin:/bin \
  --env CI=true \
  --jsonl env.jsonl \
  -- /usr/bin/env

Environment values are not copied into lifecycle events or registry records. They can still reach child output, so capture files and echoed output require the same secret-handling discipline as any other process log.

Publishing the run id to the child

--run-id-env KEY sets KEY in the child's environment to this run's final id — the explicit --run-id when one was given, otherwise the id the runner generated:

processkit-cli run \
  --run-id-env PROCESSKIT_RUN_ID \
  --jsonl build.jsonl \
  -- ./build.sh

The injected value is the same one run_started.run_id, the registry record, and every control-plane reply carry, so the child (and anything it spawns) can correlate its own work with the run without the caller minting an id itself and passing it twice as --run-id <id> --env KEY=<id> — which duplicates an identity that can then drift, and rules out a generated id, since a generated id is not knowable outside the run until the run has started.

The flag is strictly opt-in: omit it and nothing is injected. No key is set by default.

Collisions are settled without reference to flag order:

The last row is the deliberate choice: an explicit --env for the same key asks for a different value of one variable, and silently discarding what the caller typed would be worse than refusing the pair. The refusal names the key and never repeats the value beside it.

"The same key" is decided the way the platform decides it. Windows environment names are case-insensitive, so --env KEY=value --run-id-env key names one child variable there and is refused just like the identical spelling; on other platforms KEY and key are two variables, so that pair is accepted and each keeps its own value.

The value is correlation data, not a credential or a security proof. It says which run some work belongs to; it does not establish who started that run, carries no authority, and can be set by anything able to write an environment variable. Do not use it to authorize anything — see Threat model.

Run identity

--run-id gives the run a stable application-level name:

processkit-cli run \
  --run-id build-2026-07-27 \
  --jsonl build.jsonl \
  -- cargo build

When omitted, the runner generates an id and writes it in run_started. A caller that needs to address the live run immediately should provide an id or read the first event before calling inspect, cancel, kill, attest, or wait. Whichever way the id was decided, --run-id-env KEY publishes that final value into the child's environment (see Publishing the run id to the child).

Explicit ids must contain 1-256 Unicode characters and cannot contain terminal control or invisible formatting characters. The same validation applies to every by-id command, so an unsafe id is rejected before registry access.

Run ids are not operating-system PIDs and are not required to be globally unique. Two live runs with the same explicit id make by-id control ambiguous; the client fails rather than choosing one. list shows every record, and the aggregate --all commands address records rather than resolving a shared id.

Repeat --label KEY=VALUE on run to attach non-secret operator metadata. The resulting map appears in run_started.labels and list; later values replace earlier values for a duplicate key. Keys are 1-64 ASCII bytes, begin with a letter or _, and otherwise contain letters, digits, ., -, or _. Values are at most 256 characters and, like an explicit run id above, cannot contain terminal control or invisible formatting characters; the same check runs on read, so a label an older record already carries is dropped from that record's map when it fails, while the record itself is kept. Repeated label filters on cancel --all, kill --all, and wait --all combine with logical AND.

Foreground lifecycle

A foreground invocation has four high-level phases:

1. Validate arguments and open the JSONL destination.
2. Create a ProcessKit container, spawn the child, and publish the registry record/control endpoint.
3. Wait for child exit, timeout, signal, or control-plane action while pumping output when the selected I/O mode requires it.
4. Tear down the owned container, write terminal events, remove the registry record, and exit.

On normal completion the runner exits with the child's exact code. A runner failure or runner-imposed ending uses the reserved band documented in Exit-code contract.

Child stdout and stderr

The default mode pipes both child streams through ProcessKit and echoes them to the runner's matching streams. JSONL never goes to stdout. This allows a parent to treat processkit-cli like the command it wraps while independently tailing the lifecycle file.

For terminal inheritance, stdin sources, echo suppression, and bounded transcripts, see Standard I/O and capture.

Time bounds and cancellation

processkit-cli run \
  --timeout 20m \
  --idle-timeout 2m \
  --grace 5s \
  --jsonl bounded.jsonl \
  -- cargo build

The overall and idle clocks are independent. Either expiry enters the shared soft-stop → grace → hard-kill path. Ctrl-C and cancel use the same teardown shape but remain distinguishable outcomes. See Timeouts and cancellation.

Recorded tree snapshots

processkit-cli run \
  --snapshot-interval 30s \
  --jsonl long-run.jsonl \
  -- ./build-fleet

By default the tree's shape is recorded once, right after spawn. --snapshot-interval re-emits that same members_snapshot event on the given cadence while the child runs, so a long, quiet, or detached run leaves a recorded history of how the tree evolved rather than one that is only observable live via inspect. The periodic events are told apart from the post-spawn one by the event's reason field (interval vs spawn), and stop as soon as the run's ending is decided. A sample whose member read fails is still recorded, carrying read_error: true and an empty member list rather than being dropped. See JSONL event schema.

It composes with every I/O mode, including --inherit-stdio, and it is forwarded by --detach — see Detached runs, the scenario it exists for.

Sizing the stream: there is intentionally no ceiling

Before this flag, a run's JSONL file held a fixed handful of events regardless of how long the run took. A cadence changes that: the file now grows with the run's duration, and the runner imposes no ceiling, rotation, or sampling on it. That is a deliberate choice, not an oversight, and it is the opposite of the choice made for captured child output (--capture-max-bytes with an explicit --capture-overflow truncate|cancel policy). Three reasons:

• The operator already holds the dial. Output volume is dictated by the child and is unknowable in advance, which is why capture needs a runtime ceiling. Here the volume is a direct, computable consequence of a number the operator typed — a ceiling would only second-guess an explicit instruction.
• Neither truncation policy fits. Silently dropping later snapshots would destroy exactly the end-of-run history the feature exists to record, and ending the run over a diagnostics budget would let an observability option kill the payload it was only meant to watch.
• The bound belongs where the file does. The stream's destination is the operator's --jsonl path; disk budgets, retention, and rotation are properties of that location, not of the runner.

The arithmetic. One snapshot line costs roughly 130 bytes of envelope plus about 80 bytes per member of the tree, and the run writes duration / interval of them:

Choosing an interval. Pick the coarsest cadence that still answers the question you expect to ask; the resolution that matters is usually "when did this change", not "what was it at every instant". Seconds-scale intervals are for short investigations, minutes-scale for day-long or detached runs. As a rule of thumb keep the projected line count in the thousands rather than the millions — with a 100-process tree that is a few tens of megabytes, which any run that was worth supervising can afford.

If the file cannot be written, the runner reports the failure once on stderr and then stops emitting events for the rest of the run; the run itself continues. A full disk therefore shows up as a stream that simply ends mid-run, and in a detached run (whose stderr is null) with no warning anywhere. This is the pre-existing behavior of the JSONL emitter, not something the cadence introduces, but a long cadence is the most likely way to meet it — one more reason to size the interval rather than rely on a ceiling that does not exist.

Resource limits

processkit-cli run \
  --max-memory 2g \
  --max-processes 64 \
  --cpu-quota 2 \
  --jsonl limited.jsonl \
  -- build-worker

Limits apply to the whole contained tree where the active mechanism can enforce them. Unsupported limits fail before launch instead of silently running unbounded. Platform constraints are collected in Resource limits.

Windows console policy

--create-no-window maps to Windows CREATE_NO_WINDOW and is a no-op on other platforms. It is intentionally opt-in: a normal run should not suppress a console the child legitimately expects.

It conflicts with --inherit-stdio, because hiding the child's console and promising to preserve the caller's terminal are contradictory. It is especially useful with detached runs, whose detached runner owns no console for a console child to inherit.

--windows-graceful-ctrl-break opts a Windows console child into ProcessKit's cooperative CTRL_BREAK tier before Job Object escalation. It is a no-op off Windows and conflicts with both consoleless modes (--create-no-window, --detach).

Flag interaction summary

Parse-time conflicts are usage failures (100); no child is spawned.

Next steps

• Cookbook for complete command shapes.
• Detached runs for out-of-band supervision.
• JSONL event schema for the machine-readable lifecycle.
• Live-run control plane for inspect, cancel, kill, and attest.

Standard I/O and capture

I/O mode determines whether ProcessKit can observe the child's streams, whether the child sees a terminal, and whether the runner can capture or suppress output. Choose the mode from the child's actual contract rather than treating terminal inheritance as a cosmetic switch.

Mode matrix

The JSONL file is independent of every mode. Events always go to --jsonl, never to stdout.

Default: closed stdin, pipe and echo

processkit-cli run --jsonl run.jsonl -- cargo test

The child cannot wait forever for input the runner does not own. Its stdout and stderr are drained through separate pipes and retransmitted to the runner's stdout and stderr.

Because the child sees pipes rather than a terminal, it may disable color, progress bars, cursor movement, and interactive prompts. This is intentional and makes the default suitable for CI and automation.

Inherit all three handles

processkit-cli run --inherit-stdio --jsonl interactive.jsonl -- cargo watch

--inherit-stdio passes the caller's stdin, stdout, and stderr handles directly to the child. If the caller is attached to a terminal, the child sees that same terminal. The runner does not create a PTY.

Direct inheritance means there is no output pump. The following features are therefore unavailable and rejected at parse time:

• --capture-dir and --capture-max-bytes;
• --no-echo;
• --idle-timeout;
• --create-no-window;
• --inherit-stdin and --stdin-file;
• --detach.

That list is bounded by the pump, not by observability in general. --snapshot-interval composes with every I/O mode, --inherit-stdio included: a snapshot queries the container's own member list, so it needs no pipes to observe and conflicts with nothing here. --idle-timeout is the contrast that makes the boundary concrete — it is rejected above precisely because it can only re-arm on bytes the pump observes, while --snapshot-interval never looks at the child's output at all. --jsonl likewise keeps recording the full lifecycle under inheritance; only the child's bytes are outside the runner's view in this mode.

Terminal signal behavior is platform-dependent. On Unix a child in a separate foreground process group may receive Ctrl-C directly and report a signal exit; on Windows both child and runner can observe the console event. Use the local control-plane cancel command when an orchestrator needs one deterministic runner-owned cancellation outcome.

Inherit stdin only

processkit-cli run --inherit-stdin --jsonl input.jsonl -- sort

The child reads from the runner's input handle, while stdout/stderr remain on the default pump. The runner neither records nor mediates stdin bytes. This mode does not create a terminal; redirected caller input remains redirected input.

Feed a file

processkit-cli run \
  --stdin-file requests.ndjson \
  --jsonl importer.jsonl \
  -- importer --format jsonl

The checked file is streamed to the child and stdin closes at EOF. File bytes do not enter argv or lifecycle JSONL. A missing or unreadable file is a pre-spawn SETUP (111) failure.

--stdin-file and --inherit-stdin are mutually exclusive. For small literal input, create a file or explicitly invoke a shell/pipeline outside the runner; the CLI intentionally has no string-to-stdin flag that could encourage secrets inside process listings or shell history.

Suppress live echo

processkit-cli run \
  --no-echo \
  --capture-dir ./capture \
  --jsonl run.jsonl \
  -- noisy-worker

--no-echo removes only the runner's retransmission. Pipes stay open and the pump continues to:

• drain the child so it cannot block on a full pipe;
• write bounded capture files;
• re-arm --idle-timeout on observed output;
• preserve lifecycle events.

This is the normal embedding mode for an orchestrator that owns presentation and does not want the runner's live copy of child output interleaved with its own logs.

Bounded transcript capture

--capture-dir DIR creates two files:

DIR/
├── stdout.log
└── stderr.log

Streams remain separate and are still echoed unless --no-echo is present. Each file is capped independently at 8 MiB by default:

processkit-cli run \
  --capture-dir ./capture \
  --capture-max-bytes 32m \
  --jsonl run.jsonl \
  -- compiler

The terminal output_captured event reports, per stream:

Do not infer completeness from file size. Use truncated; a file whose length equals the cap may still be complete when the stream ended at exactly that boundary.

Capture setup is all-or-nothing

Both transcripts are opened before either one is emptied, and a setup that fails part-way — for example a stderr.log path that already names a directory, or a transcript the runner may not write — rolls back the files and directories that attempt created. Such a run exits SETUP (111) before the child spawns, and without leaving an empty stdout.log behind to be mistaken for a real, silent transcript.

Paths the runner found rather than created are not rollback candidates: the rollback neither removes nor empties them, so a setup that cannot open one of the two transcripts leaves an existing file at either path as it was, contents included, and leaves an existing capture directory in place. A successful setup still starts both transcripts empty — a run owns its capture files — so keep anything worth retaining out of the capture directory.

Two independent bounds

--capture-max-bytes limits retained disk bytes per stream. The ProcessKit pump also has a fixed 64 MiB in-flight line-assembly ceiling for a single unterminated line. They protect different resources and neither derives from the other.

Binary output

The live echo and capture path operate on bytes. Capture files preserve the bytes written up to the cap; they are not decoded or line-normalized. Runner diagnostics remain on stderr and are not written into stdout.log or stderr.log.

When stdout itself is a binary protocol, use --no-echo plus capture, or invoke the child directly if no lifecycle control is needed. The JSONL stream never shares stdout, so it cannot corrupt a binary child stream.

Secret hygiene

Argv is redacted in events by default, but child output is not. A command may echo credentials, environment values, file contents, or tokens into live output and capture files. Apply access controls and retention policies to:

• the JSONL file when --argv-raw is used;
• stdout.log and stderr.log;
• any parent process that records runner stdout/stderr.

Diagnosing a degraded terminal UI

If a tool loses color, switches to plain progress messages, or refuses an interactive prompt under the default mode, confirm that it requires a TTY. Use --inherit-stdio only when the caller already owns a real console/terminal and does not need capture or idle detection.

ProcessKit CLI does not emulate a PTY. A program that specifically requires PTY semantics cannot obtain them from this runner today.

See also

• Running commands — argv, cwd, environment, and run ids.
• Timeouts and cancellation — how output drives the idle deadline.
• JSONL event schema — normative output_captured fields.
• Troubleshooting — terminal and capture symptoms.

Detached runs

--detach transfers a run to a detached copy of processkit-cli and returns once that copy has provably started the child. It is intended for an orchestrator that wants to launch now and supervise later from a different process.

processkit-cli run \
  --detach \
  --run-id build-42 \
  --capture-dir ./build-42-output \
  --jsonl build-42.jsonl \
  -- cargo build

processkit-cli inspect --run-id build-42 --json
processkit-cli wait --run-id build-42

What successful return proves

The launching invocation waits until run_started is readable in the JSONL file. That event is written after the detached runner has:

1. created the ProcessKit container;
2. published the registry record and control endpoint;
3. spawned the child.

After a successful return, the run is discoverable by list, addressable by inspect / cancel / kill, and waitable by wait. A timeout in the detached startup handshake kills the detached copy instead of leaving an unreported run behind.

Exit-code semantics change

Foreground run forwards the child's exact exit code. Detached launch cannot: the launching process exits while the child is still running.

The child's eventual result is in the terminal runner_exit event. A detached caller must treat 0 as “started,” never as “payload succeeded.” See Exit-code contract.

Output behavior

The detached runner owns none of the launching caller's standard handles. It uses the same pump as --no-echo: child output is drained, but not retransmitted to a terminal that no longer exists.

These features remain active:

• --jsonl (still required);
• --capture-dir and --capture-max-bytes;
• --idle-timeout;
• --snapshot-interval (see below);
• overall timeout, grace, environment, cwd, and resource limits.

--inherit-stdio and --inherit-stdin are rejected because there is no caller left to provide those handles. Use --stdin-file when a detached payload needs finite input.

Recorded tree snapshots without a live watcher

--snapshot-interval <duration> works under --detach — the launcher forwards it to the detached copy like any other run flag — and this is the mode it was designed for. A detached run is precisely the one nobody is watching with inspect at the interesting moment, so the periodic members_snapshot events are the only record of how the tree evolved between spawn and teardown.

processkit-cli run --detach \
  --run-id nightly-index \
  --snapshot-interval 5m \
  --jsonl /var/lib/my-orchestrator/runs/nightly-index.jsonl \
  -- indexer

Two consequences are specific to detaching:

• The JSONL file is the only diagnostic channel. The detached runner's stdin/stdout/stderr are null, so every warning the foreground runner would print reaches nobody. This is why a failed member read is recorded in the stream as a members_snapshot with read_error: true rather than merely warned about (see JSONL event schema). It is also why a JSONL write failure — a full disk, most plausibly — is invisible: the runner disables event logging after one unseen warning and the stream simply stops mid-run.
• Detached runs are the longest ones, so size the cadence first. The stream grows as duration / interval; a day-scale run wants minutes, not seconds. The arithmetic and the recorded decision not to impose a ceiling are in Running commands.

Windows

The detached runner is created with DETACHED_PROCESS and owns no console. A console child may therefore receive a new visible console from Windows. Pass --create-no-window for a headless payload:

processkit-cli run --detach --create-no-window `
  --run-id worker `
  --jsonl worker.jsonl `
  -- worker.exe

A detached runner cannot escape a Job Object that already contains its caller. If the outer job is kill-on-close, its owner still controls the detached run's ultimate lifetime.

Unix

The detached copy starts a new session with setsid, so terminal hang-up and Ctrl-C from the launching session no longer target it. After the launcher exits, the system's init process adopts the detached runner.

This changes session ownership, not ProcessKit's containment mechanism. The detached run reports the mechanism it actually obtained:

FreeBSD is distinct from the POSIX process-group fallback: its process_reaper covers the whole reaper tree during normal teardown, including descendants that call setsid or double-fork. It has no owner-death cleanup primitive, so abrupt_cleanup remains none if the detached runner is killed before it can perform teardown. The table's Linux value is direct_child_only for both the cgroup and process-group cases; the last column applies only when an abrupt death prevents the runner from reaching its cleanup code.

Supervision pattern

Use one durable JSONL path and one stable run id per detached run:

run_id=nightly-index
events="/var/lib/my-orchestrator/runs/${run_id}.jsonl"

processkit-cli run --detach --run-id "$run_id" --jsonl "$events" -- indexer
processkit-cli wait --run-id "$run_id" --timeout 30m

The run id is an address while the runner is live. The JSONL file is the durable record after the registry entry has been removed on clean completion.

Reading the stream back — events

events closes the detach loop: it reads that JSONL stream back without an external tailer or JSON filter, and without the caller having to look the locator up first.

# Watch a detached run as it happens, until its terminal `runner_exit`.
processkit-cli events --run-id nightly-index --follow

# What happened, after the fact — the registry record is gone, the file is not.
processkit-cli events --file "$events"

# The runner's own bytes, for a machine (line-for-line, nothing re-serialized).
processkit-cli events --file "$events" --json

# Conformance-check a stream against this binary's embedded event schema.
processkit-cli events --file "$events" --validate

Naming the stream. --run-id resolves the locator through the registry — the same jsonl field list --json publishes — which works while a record exists, live or merely not yet reaped. --file reads a path directly and is the answer once the record is gone (a clean exit deletes its own record, and prune reaps what an abrupt death left), or for a stream this registry never knew about. The two are mutually exclusive and exactly one is required; passing both is a USAGE (100) error rather than a silent choice between them. When --run-id names no single readable stream — no record, several records naming different streams, or a run started without --jsonl — the refusal is the same CONTROL (103) verdict every other by-run-id command gives.

Where a follow stops. --follow polls the file for growth (there is no notification to subscribe to for either a file or a runner's death) and returns at the first of: the terminal runner_exit event, or the registry reporting the run over with the stream no longer growing. The second case is what an abruptly killed runner leaves behind — it never got to write its terminal event — and it is explained on stderr rather than passed off as a complete stream. --follow never invents a deadline of its own: it is bounded by the run's lifetime, so a caller that wants a wall-clock bound imposes one itself (wait --timeout alongside it, or a bound on the whole invocation).

Read-only, like list/wait. events opens the registry read-only, never connects to a run's control transport, and mutates nothing — so following a production run cannot disturb, end, or even be noticed by it.

Shutdown sequence

For one detached run:

processkit-cli cancel --run-id nightly-index
processkit-cli wait --run-id nightly-index --timeout 30s
processkit-cli prune

For all runs confirmed live at one instant:

processkit-cli cancel --all
processkit-cli wait --all --timeout 30s
processkit-cli prune --dry-run
processkit-cli prune

The --all target set is a snapshot. A run registered afterward is out of scope; repeat the sequence when the surrounding system allows concurrent new launches.

Recovery after orchestrator restart

1. Run list --json to discover registry entries.
2. Read each durable JSONL file back with events --file <path> (or events --run-id <id> --follow for one still live), instead of hand-rolling a tailer: it hands out only complete lines, so a run being appended to while it is read never yields a half-written event.
3. Use inspect --json only for entries confirmed live.
4. Treat stale records as evidence of abrupt runner loss, not as permission to address the recorded PID.
5. Preview prune --dry-run --json, then prune confirmed-stale entries.

See also

• Run registry — liveness and stale-entry semantics.
• Live-run control plane — control acknowledgements.
• Integration guide — adapter startup and recovery.
• Platform support — abrupt-runner-death guarantees.

Timeouts and cancellation

ProcessKit CLI has separate outcomes for a child exit, overall timeout, idle timeout, local cancellation, control-plane cancellation, and immediate kill. They share teardown machinery without collapsing their meaning.

Overall deadline

processkit-cli run --timeout 10m --jsonl run.jsonl -- cargo test

--timeout bounds wall-clock lifetime from launch. When it expires, the runner enters soft-stop → grace → hard-kill teardown and exits TIMEOUT (106). The child did not choose that code; the terminal runner_exit.child_code is therefore separate.

Idle deadline

processkit-cli run \
  --idle-timeout 90s \
  --capture-dir ./capture \
  --jsonl run.jsonl \
  -- build-worker

--idle-timeout measures silence, not total duration. Every observed stdout or stderr chunk re-arms the clock. A chatty ten-hour process can remain healthy, while a stuck worker that produces no output for 90 seconds is torn down.

Idle detection requires the output pump. It conflicts with --inherit-stdio, but composes with capture and --no-echo. Overall and idle deadlines may be used together; the first to expire wins.

Both expiries use code 106. The JSONL timeout.reason field distinguishes overall from idle.

Duration grammar

Durations are non-negative integers with an optional unit:

0 is rejected for overall, idle, and wait deadlines because it expires before the first meaningful check. --grace 0 is valid and requests no pause between the soft and hard tiers.

Grace window

processkit-cli run \
  --timeout 20m \
  --grace 5s \
  --jsonl run.jsonl \
  -- service

The runner first asks the tree to stop, waits up to the grace window, and then hard-kills survivors through the owning container. cleanup_finished reports whether a soft request was delivered, was unsupported, or failed. Its shutdown object also records the pre-attempt soft_stop_scope and ProcessKit's ShutdownReport: observed member counts, early drain, escalation, and elapsed time.

Grace is a maximum opportunity for cooperative exit, not a promise that every platform has a signal capable of reaching the child.

Local stop signals

The foreground runner catches:

These use the local CANCELLED code (107). The cancelled.source field names the exact source (ctrl_c, sigterm, sighup, ctrl_break, ctrl_close, ctrl_logoff, or ctrl_shutdown).

An inherited Unix terminal can deliver Ctrl-C directly to the foreground child group. In that case the runner may report a child signal exit rather than a runner-owned 107. Use the control plane when a supervisor needs one stable outcome independent of terminal routing.

Control-plane cancel

processkit-cli cancel --run-id build-42

cancel reaches the live runner over local IPC and requests the same soft → grace → hard teardown. The run exits CONTROL_CANCELLED (108) and writes a cancelled event whose source identifies the control command.

The client returns only after the runner acknowledges the command. An acknowledgement means the run accepted the request, not that teardown has already completed; use wait as the barrier.

Immediate kill

processkit-cli kill --run-id build-42

kill skips soft stop and grace, hard-kills the container immediately, and produces CONTROL_KILLED (109) plus a killed event. Use it when cooperative shutdown is not wanted or after an external policy has already spent its grace budget.

Aggregate cancellation

processkit-cli cancel --all
processkit-cli wait --all --timeout 30s

--all takes one snapshot of entries confirmed live. It addresses each by record identity and remembered endpoint, so duplicate run ids do not make the aggregate ambiguous. A newly registered or initially unprobed run is outside that invocation's target set.

The command prints a JSON array with per-target accepted, already_gone, or failed status. Any unresolved target makes the aggregate exit CONTROL (103); an empty snapshot is successful.

Windows soft-stop behavior

A Job Object has no POSIX signal. ProcessKit first tries a best-effort soft close of eligible windowed members. run --windows-graceful-ctrl-break also launches the direct console child as an addressable console process-group leader, so ProcessKit can send CTRL_BREAK before the grace window. The flag is a no-op off Windows and conflicts with --create-no-window/--detach because those modes have no shared console through which to deliver the event.

The runner probes soft_stop_scope before delivery and reports none when no eligible target exists. It never labels the grace as served by the child when nothing was delivered.

Windows gives a console-close handler only a short system deadline. For that source the runner caps an excessive grace request so it can finish teardown and write terminal events before the OS ends the process.

Unix soft-stop behavior

The soft tier sends SIGTERM to the contained process group or cgroup members, then hard-kills survivors after grace. A descendant that deliberately escapes a POSIX process group is outside that weaker mechanism; the runner reports the active mechanism so an adapter can decide whether that limitation is acceptable.

Event ordering

A runner-imposed ending normally emits:

timeout | cancelled | killed
resource_summary
cleanup_started
cleanup_finished
runner_exit

resource_summary — what the tree consumed — is part of the tail on every ending, not just a natural exit: the child ran, so it has consumption to report. It sits between the reason event and cleanup_started because what it reads lives in the container that cleanup_finished hard-kills. A run that also requested a resource cap emits limit_evidence immediately before it, from the same read point.

On these endings the read happens before the soft stop, while the tree is still running — which is why a forced ending is the better case for the numbers, not the worse one. On Linux cgroup v2 it is in fact the only case that populates peak_memory_bytes and total_cpu_ms at all: there they are summed over the members live at the read point, so a child that exited on its own leaves both null (resource limits, consequence 5).

members_snapshot is not part of that tail: one is emitted right after run_started, and — with the opt-in --snapshot-interval <duration> cadence — more of them while the child runs, but the cadence stops the instant the ending is decided, so none can appear between the reason event and runner_exit.

Exact presence and ordering rules are normative in JSONL event schema.

See also

• Exit-code contract — numeric outcomes.
• Live-run control plane — request/ack protocol.
• Platform support — containment caveats.
• Troubleshooting — failures and stale records.

Resource limits

Three run flags request kernel-enforced limits over the whole contained tree:

processkit-cli run \
  --max-memory 1g \
  --max-processes 32 \
  --cpu-quota 1.5 \
  --jsonl limited.jsonl \
  -- compiler-worker

Omitting a flag leaves that resource unbounded. The runner never invents a default cap.

Fail closed, before spawn

A requested limit is a requirement, not a hint. If the active platform and containment mechanism cannot enforce it, run:

1. does not spawn the child;
2. emits limit_hit naming memory, processes, or cpu;
3. emits container_failed and terminal runner_exit;
4. exits BACKEND (102).

An adapter must inspect limit_hit; code 102 also covers unrelated backend failures.

Platform matrix

The run_started.mechanism field tells an observer what was actually obtained.

Linux controller requirements

The current ProcessKit implementation can apply limits when the runner is a direct member of the real cgroup-v2 root and can enable the required controllers. This is common in a minimal init environment, but not in:

• a normal systemd user session, scope, or service;
• ordinary Docker or Kubernetes containers;
• typical GitHub Actions jobs;
• any environment that delegates a nested cgroup without writable controllers.

In those environments a limit request fails rather than falling back to an unenforced process-group run.

Linux process-count caveat

The cgroup pids controller reliably bounds descendants forked inside the cgroup. It does not reject additional top-level launches into the same group in the same way Windows Job Object active-process limits do.

For ProcessKit CLI, which launches one root per run, interpret --max-processes as a cap on that tree's own growth. It protects against a contained fork explosion; it is not a general admission controller for unrelated launchers.

Size parsing

Units are binary:

Zero, malformed values, and overflow are usage failures (100). CPU quota also rejects negatives, NaN, and infinities.

Applied limit versus observed limit hit

limit_hit proves only that a requested limit could not be applied before launch. It does not describe a successfully installed cap firing later, and its payload and meaning remain unchanged for compatibility.

With processkit 3.2.0, a run that requested at least one cap emits a separate limit_evidence event after the child ending is known and immediately before the teardown pair. It carries one verdict for each axis (memory, processes, and cpu):

This event exists only when ProcessGroup::with_options successfully creates a container. On FreeBSD's process reaper, on macOS and other BSD process groups, and on the Linux process-group fallback, ProcessKit returns ResourceLimit during group creation because that mechanism has no whole-tree limit primitive. The runner therefore emits the existing pre-spawn limit_hit event and its backend-error tail, but there is no group from which to read limit_evidence; the event is not emitted on that path. unknown is reserved for a successfully created group whose active mechanism cannot provide the post-run answer.

• Three-valued, never a boolean. The JSONL limit_evidence event represents Tripped / NotTripped / Unknown as tripped / not_tripped / unknown. Unknown never collapses into "did not fire": that would silently misreport a platform's inability to answer as a clean run on every axis where evidence is unavailable.
• Authoritative on Linux cgroup v2 only. There, Tripped/NotTripped come from real kernel counters (memory.events' oom, pids.events' max, cpu.stat's nr_throttled). On Windows Job Object and on a POSIX process group that was successfully created, a capped axis instead reports Unknown as a measured result, not an omission — those mechanisms keep no post-mortem record that a cap fired. In practice the POSIX limit request fails during group creation as described above, so POSIX fallback runs have no post-run event at all. Windows is a first-class platform for this CLI, and runtime limit attribution remains unknown there; this closes the gap on Linux cgroup v2 only.
• Readable only while the container still exists. The evidence lives in the container itself, so the runner reads it before ProcessGroup is dropped or consumed by shutdown. limit_evidence therefore precedes cleanup_started, preserving the cleanup_started → cleanup_finished ordering.

The event is absent when no cap was requested. On an event that is present, uncapped axes are reported as not_tripped by ProcessKit because nothing was in force that could fire; unknown is reserved for a missing authoritative answer from the active mechanism.

None of this changes what limit_hit means today: it stays the pre-spawn "the requested cap could not be applied" event, and a cap-dependent adapter still treats it as a hard failure signal in that scope (see docs/schema.md).

What the tree consumed

limit_hit and limit_evidence are both about a cap: one says it could not be installed, the other whether it fired. Neither says how much the tree actually used. That is the separate resource_summary event, which every run that spawned a child emits exactly once — no flag, no cap required, every platform (normative field list: docs/schema.md). With processkit 3.3.0 it takes one ProcessGroup::stats() reading of whatever the active mechanism accounts for — a Job Object's own accounting block on Windows; on Linux the cgroup's io.stat/pids.peak counters plus a per-member /proc sum for memory and CPU, which is why the matrix below ties those two axes to the read point — at the same place in the teardown tail as limit_evidence and immediately after it.

What it does not prove

• It is not limit attribution. A peak_memory_bytes at or near a requested --max-memory is not evidence the cap engaged; only limit_evidence's tripped is, and only where that verdict is authoritative (Linux cgroup v2). Reading a high peak as "it was capped" would invent an attribution the kernel never made.
• It is not a time series. One reading at the end of the run, not a sample. It cannot say when the peak occurred, or what the tree looked like at any earlier moment. run --snapshot-interval answers the second of those — the tree's shape over time, and it is opt-in precisely because that has an ongoing cost — but it carries no resource numbers, so nothing in this stream is a consumption series.
• It is not a per-process breakdown. Every number is whole-tree. A member's individual share is not recoverable from it.
• It does not measure disk. Bytes written to a capture file are output_captured.bytes (see docs/io-and-capture.md); the IO counters here are the tree's own read/write traffic and are a different quantity that happens to share a unit.

Platform matrix

Every measurement is independently nullable, and null means this mechanism, at this read point, does not account for it — never zero, and never a number the runner improved by taking a maximum over its own periodic reads (that would report when the runner looked, not what the tree did). Two of the axes below depend on the read point and not on the platform alone, so the "mechanism" column is a necessary condition for a number, never a sufficient one. This matrix is normative; do not read completeness into the event's field list.

Five consequences that are easy to misread as bugs:

1. peak_process_count is always null on Windows. A Job Object keeps ActiveProcesses (how many are in it now) and TotalProcesses (how many were ever assigned to it). Neither is a high-water mark of concurrency, and this runner will not synthesize one from its own stats() calls.

2. IO bytes are always null on FreeBSD, macOS, non-FreeBSD BSDs, and the Linux process-group fallback. Those mechanisms contain a tree without accounting for it. On Linux cgroup v2 they additionally require the io controller to be enabled for the group's cgroup — which is what makes io.stat exist at all. This CLI does not enable it: processkit enables exactly the controllers a requested ResourceLimits needs (memory, pids, cpu) and no others, so io is on only if the environment already delegated and enabled it. The same is true of pids.peak, which needs the pids controller — in practice that means a run with --max-processes.

3. The IO counters are not comparable across platforms. A Job Object counts bytes moved by every read/write the job's processes issued, whatever the target. A cgroup's io.stat counts only what crossed the block layer, so a read served from the page cache, or any traffic over a pipe, socket, or tmpfs, is simply not in it. The same workload legitimately reports very different numbers on the two, and neither is wrong. Compare a series only against itself on one mechanism; read run_started.mechanism to know which one produced it.

4. On Linux, io_write_bytes can undercount. A write reaches the block layer when the kernel writes the page back, which may be after the member that dirtied it exited — or never, if the page is still dirty when the group is torn down. A short write-and-exit run can report fewer bytes than it handed to write(2).

5. On Linux cgroup v2, peak_memory_bytes and total_cpu_ms are null after a natural exit — the most common ending, so this is the ordinary reading there and not a corner case. Unlike the two axes beside them, these are not counters the cgroup keeps: ProcessKit sums them out of /proc/<pid> over the members listed in cgroup.procs at the moment of the read, and it does so whether or not a cap was requested (memory.peak and cpu.stat are never consulted, so --max-memory does not change it). A process leaves cgroup.procs as soon as it exits — a zombie never appears there — and this read happens after the ending is decided, so on the natural-exit path the child has already exited and been reaped and there is normally nothing left to sum. Both axes then come back null with read_error: false, which is a correct answer about that read point and not a failure. Two corollaries follow, and the second is the useful one:

   • A child that leaked a descendant which outlived it makes the two axes non-null — but they then cover only the survivor, arbitrarily far below what the tree as a whole used. A small number here is not a whole-tree total.
   • On a runner-imposed ending (timeout, cancelled, killed, output_overflow) the read happens before the soft stop, while the tree is still running, so there both axes are populated. If a workload's memory or CPU is what you need on Linux, a run the runner itself ended is the only place this stream carries it: no other event does, members_snapshot (including --snapshot-interval's samples) carrying member identity only — pid, ppid, name, start_time.

   Neither Windows nor Linux's other two axes are affected. A Job Object's accounting block outlives the processes charged to it, so its memory and CPU cover the whole job whatever the ending; io_read_bytes/io_write_bytes and peak_process_count on Linux are cgroup-kept counters and likewise survive their members — whether they are present is the controller question in consequence 2.

peak_memory_bytes and total_cpu_ms are likewise platform-specific in meaning (committed memory vs. resident high-water mark; the whole job's history vs. only the members live at the read point), so the same caution applies to them: comparable within a mechanism, not across.

A failed read is in the stream, not missing from it

If stats() fails, the event is still emitted with read_error: true and every measurement null. Check that flag before drawing a conclusion from a null, because an all-null summary is also a correct success — it is exactly what row 3 and row 4 of the matrix above report by design, and what row 2 reports as well for the commonest case of all: a plain run on Linux cgroup v2 that ended by its child exiting has no live member left to sum for memory and CPU (consequence 5) and — unless the environment itself enabled the io controller, and --max-processes the pids one — no container counter to answer for the other three (consequence 2), so all five measurements are null with read_error: false. An all-null summary therefore carries no information about whether the read worked, on any platform: read_error is the only thing that separates "this mechanism, at this read point, accounts for nothing" from "the read failed", and a foreground run's stderr warning does not help a --detach run, whose stderr is null.

Preflighting it

resource_summary is present on every build that has it, so a consumer pins the event, not a platform:

processkit-cli probe --json --require-surface run:resource-summary

That token's presence guarantees the event will be in the stream. It does not promise any particular axis is populated — that is what the matrix above governs, and it follows from run_started.mechanism, plus (on Linux cgroup v2, for memory and CPU) from how the run ended. Never from a probe token.

Limits and outer containers

An outer Docker/Kubernetes/systemd limit and a ProcessKit CLI limit are separate layers. The stricter layer wins, but only the outer runtime can explain its own termination reason. If the outer runtime kills the runner itself, the platform-specific abrupt_cleanup contract applies.

Use outer-runtime limits when they are the authoritative scheduler policy. Use CLI limits only where ProcessKit can install them and the adapter needs the limit request attached to this specific run.

Operational checklist

1. Run probe --json to verify the flags exist.
2. Launch a harmless limited command in the real deployment environment.
3. Read run_started.mechanism rather than assuming cgroup availability.
4. Treat pre-spawn limit_hit as a hard configuration failure.
5. For a successfully created capped run, read limit_evidence for post-run attribution and preserve unknown as distinct from not_tripped. For a pre-spawn limit_hit, do not expect post-run evidence: the container did not exist to be queried.
6. For actual consumption, read resource_summary — present on every run that spawned a child, capped or not. Check read_error first, then treat each null as "this mechanism does not account for it at this read point" per the matrix in "What the tree consumed", never as zero, and never compare its IO counters across platforms. On Linux cgroup v2 in particular, do not expect peak_memory_bytes or total_cpu_ms from a run whose child exited on its own — there they are null by construction (consequence 5).
7. Keep a separate outer-runtime signal for limits imposed outside this run.

See also

• Platform support — mechanism selection.
• Running in containers — cgroup delegation in images and orchestrators.
• JSONL event schema — normative event fields; see also resource_summary for what the tree consumed.
• Exit-code contract.

Platform support

ProcessKit CLI exposes one command surface across Windows, Linux, macOS, and source-built BSD targets, but it does not pretend their kernel containment primitives are equivalent. Every run reports both the mechanism it obtained and what happens if the runner dies before it can execute teardown.

Release targets

Other Rust-supported targets may build from source, but are not part of the release-artifact or CI promise unless listed here.

Mechanism and abrupt cleanup

run_started contains two independent fields:

• mechanism: how normal teardown addresses the tree;
• abrupt_cleanup: what the kernel guarantees when the runner never executes normal teardown.

Normal completion, timeout, caught cancellation signals, and control-plane actions still run the full owned-container teardown on every platform. The last column applies only to a crash, SIGKILL, outer Job termination, or an equivalent event that prevents the runner from reaching its cleanup code.

Windows Job Objects

A run owns a Job Object configured for kill-on-close. Child processes and their descendants are assigned to the job, and closing the last owning handle reaps the whole job.

Properties:

• strongest abrupt-owner-death guarantee (whole_tree);
• whole-tree memory, CPU, and active-process limits;
• member snapshots through Job queries;
• atomic hard kill on timeout/cancel/kill teardown;
• best-effort graceful close before hard kill where a member exposes a window;
• opt-in CTRL_BREAK for console children via --windows-graceful-ctrl-break.

Nested jobs

Modern Windows versions allow nested Job Objects when the outer job's policy permits it. A CI runner, service host, or container runtime may already place the CLI in a job. The E2E suite covers nested-job launch behavior, but an outer job remains authoritative and can terminate the runner plus its child job.

Console behavior

The runner does not allocate a console. A normal child inherits what the platform would ordinarily provide. --create-no-window is an explicit Windows-only request and conflicts with --inherit-stdio.

--windows-graceful-ctrl-break keeps the shared console, creates a child console process group, and lets ProcessKit address that group during graceful teardown. It therefore conflicts with --create-no-window and detached execution.

Linux cgroup v2

When cgroup v2 is available and delegated, ProcessKit creates a run cgroup and moves the child tree into it. Normal hard teardown addresses all members in the cgroup.

If controller/delegation requirements are not met, an unrestricted run may fall back to a POSIX process group and reports process_group. A run that explicitly requests resource limits fails instead, because falling back would discard a required policy.

Linux parent-death signaling kills the direct child if the runner dies abruptly. The cgroup itself persists and does not automatically kill every grandchild, hence direct_child_only rather than whole_tree.

FreeBSD process reaper

On FreeBSD, ProcessKit 3.3 uses the kernel's procctl(2) process reaper. Normal teardown and member discovery cover the whole reaper tree, including descendants that call setsid or double-fork. This is stronger than the POSIX process-group fallback for membership and kill scope, so it reports process_reaper rather than process_group.

FreeBSD does not provide the resource-limit or statistics primitives used by ProcessKit's other backends. A run that requests a resource cap fails before spawn with the normal limit_hit/backend-error sequence; an unrestricted run reports resource_summary with all measurements null and read_error: false. Parent-death cleanup remains none: procctl(2) gives normal teardown a whole-tree scope, but ProcessKit 3.3 has no supported owner-death primitive for this path.

macOS and non-FreeBSD Unix

The runner uses a POSIX process group. Normal teardown signals and kills the group, covering ordinary descendants that remain in it.

Limitations:

• a descendant can deliberately escape with setsid / double-fork;
• the backend cannot provide whole-tree resource limits;
• a just-exited member may still appear briefly during diagnostics;
• no portable owner-death primitive reaps the group after an uncatchable runner death, so abrupt_cleanup is none.

The mechanism field exists so an adapter can reject this weaker contract when its workload requires stronger containment.

Capability matrix

CI coverage

The repository's GitHub Actions matrix builds and tests Windows, Linux, and macOS, including Arm runners where available. FreeBSD is source-build-only and is not currently a CI or release-artifact target. The opt-in E2E tier drives the built binary through real containment scenarios: leaked descendants, nonzero roots, abrupt runner death, nested Windows jobs, PID reuse, real console/terminal I/O, and cancellation.

That matrix proves the repository's release contract; it does not prove that a particular Linux deployment grants cgroup controllers. Test mechanism selection and limit application in the actual service/container environment.

Confirming the table on the machine in front of you

Everything above is what a platform can give. Which of it this particular host actually gives is a question about the host — cgroup delegation may be absent, a registry directory may be unwritable, a local endpoint may not bind — and doctor answers it by running a bounded scratch containment and reporting what it observed:

processkit-cli doctor --json

Its containment.mechanism and containment.abrupt_cleanup are the same two fields this page's first table lists, read off a real run on this host rather than inferred from the platform; --check-resource-controller additionally reports whether the limit rows of the capability matrix are available here. It is the setup-time counterpart to the run-time acceptance policy below, and unlike probe it proves the containment path end to end — see docs/troubleshooting.md, "Qualifying a host: doctor".

Choosing an acceptance policy

An adapter can read the first run_started event and fail closed:

require mechanism == job_object or cgroup_v2
require abrupt_cleanup == whole_tree        # Windows-only today

The same two policies can be applied one step earlier, to the host rather than to a run, with the same vocabulary and an exit code instead of a field to compare:

processkit-cli doctor --require-mechanism cgroup_v2
processkit-cli doctor --require-abrupt-cleanup whole_tree

Each is an exact match against what this host reports — deliberately not an "at least this strong" comparison, because the three abrupt_cleanup levels are platform facts and this project publishes no ordering between them. An unmet requirement exits HOST_UNQUALIFIED (116) and still prints the full report.

These are separate policies. A Linux cgroup gives strong normal teardown but not Windows-equivalent abrupt cleanup.

See also

• Running in containers.
• Resource limits.
• Timeouts and cancellation.
• JSONL event schema.
• Troubleshooting — qualifying a host with doctor, and reading a negative verdict.

Running in containers

ProcessKit CLI can run inside Windows and Linux containers, but an outer container and an inner ProcessKit run solve different problems. The outer runtime controls the pod/container; ProcessKit owns one payload tree and its lifecycle contract inside that boundary.

Choosing the Linux archive

The musl archives are statically linked against libc and are suitable for images without glibc, on both x86_64 and Arm64. They are a distribution option, not a different containment mechanism.

Minimal multi-stage image

FROM alpine:3.22 AS unpack
ARG PROCESSKIT_CLI_VERSION
ARG ARCHIVE=processkit-cli-v${PROCESSKIT_CLI_VERSION}-x86_64-unknown-linux-musl.tar.gz
ADD https://github.com/ZelAnton/ProcessKit-CLI/releases/download/v${PROCESSKIT_CLI_VERSION}/${ARCHIVE} /tmp/processkit-cli.tar.gz
RUN tar -xzf /tmp/processkit-cli.tar.gz -C /tmp

FROM scratch
COPY --from=unpack /tmp/processkit-cli /usr/local/bin/processkit-cli
ENTRYPOINT ["/usr/local/bin/processkit-cli"]

On an Arm64 host, override the build argument instead of the default: --build-arg ARCHIVE=processkit-cli-v${PROCESSKIT_CLI_VERSION}-aarch64-unknown-linux-musl.tar.gz.

Verify the archive checksum and attestation in the build pipeline before this copy step; the abbreviated example focuses on final-image shape.

Shell-free entrypoints

The CLI itself does not require a shell. Use JSON/exec-form container commands:

ENTRYPOINT ["/usr/local/bin/processkit-cli", "run", "--jsonl", "/run/events.jsonl", "--"]
CMD ["/usr/local/bin/worker", "--serve"]

In Kubernetes, express the same boundary with command and args. Avoid wrapping the runner in sh -c unless the payload truly needs shell semantics; the wrapper changes signal routing and adds another process to diagnose.

Persist lifecycle data

--jsonl is required. Mount or create a writable location whose lifetime matches the observer's needs:

volumeMounts:
  - name: run-state
    mountPath: /var/lib/processkit-cli
args:
  - run
  - --jsonl
  - /var/lib/processkit-cli/events.jsonl
  - --
  - /app/worker

Use a second bounded directory for --capture-dir when transcripts must survive the container process. Apply a storage quota outside the CLI in addition to its per-stream byte cap.

PID 1 and signals

When processkit-cli is PID 1, it receives the container runtime's SIGTERM directly. The runner catches it and performs ordinary cancel teardown, including terminal JSONL events and registry cleanup, before exit.

Set the orchestrator's termination grace period longer than the runner's --grace plus application shutdown overhead. If the orchestrator sends SIGKILL first, normal teardown cannot run and Linux guarantees only the abrupt_cleanup value reported in run_started.

cgroup v2 is not automatically delegated

Seeing /sys/fs/cgroup or a cgroup-v2 mount does not mean the runner may create and configure child cgroups. Ordinary Docker/Kubernetes containers usually run inside a delegated subtree without permission to enable controllers at the effective root.

Consequences:

• an unrestricted run may report process_group fallback;
• --max-memory, --max-processes, or --cpu-quota may fail before spawn with limit_hit / BACKEND (102);
• mounting cgroup files read-write or running privileged changes the threat boundary and should not be done solely to silence that failure.

Prefer outer container limits when the orchestrator is the resource-policy owner.

Outer limits and inner limits

If both layers install limits, the stricter limit wins. ProcessKit currently cannot attribute an outer OOM kill or every inner kernel limit event; use the orchestrator's status/events as the source of truth for outer-runtime termination.

Registry location and container users

The run registry is per-user and created with owner-only permissions. Keep the same user identity for run and its inspect / cancel / kill / attest / wait clients. A sidecar running under a different UID should not expect access.

For detached runs, ensure the registry and JSONL locations survive for as long as the detached runner. An ephemeral container that exits immediately after launch cannot host a meaningful detached child.

Read-only root filesystems

The binary itself works from a read-only image, but it still needs writable locations for:

• the required JSONL file;
• the per-user registry/control socket directory;
• optional capture files.

Mount explicit writable volumes or tmpfs paths and set the child working directory accordingly. A setup failure is reported before the payload runs.

Health and shutdown pattern

The CLI does not implement retries, pooling, or application health checks. Let the orchestrator own restart policy and use ProcessKit CLI for deterministic one-run control:

1. start run as the container's main process;
2. read run_started before declaring startup complete;
3. on shutdown, send SIGTERM and allow the configured grace;
4. collect terminal JSONL and capture files;
5. use the outer runtime's status for OOM/eviction attribution.

See also

• Installation and distribution.
• Platform support.
• Resource limits.
• Detached runs.

Live-run control plane

The control plane lets a client query and (later) steer a running processkit-cli run. It lives in the live runner process, not in named kernel objects (AGENTS.md, "The control plane lives in the live runner process"): a runner must stay alive to hold its kill-on-drop container, so the live process is exactly where clients reach it. If the runner dies, the container tears the tree down and the run becomes detectably gone — never a dangling handle a client could act on by mistake.

This document is the normative description of the local transport, the wire protocol, and the four clients — the read-only inspect and attest, and the mutating cancel / kill — including their behavior when the runner cannot be reached. Four clients, not four callers: doctor (docs/troubleshooting.md, "Qualifying a host: doctor") drives two of these very verbs — inspect, then cancel — through the same client code, against the scratch run it started for itself and never against a caller's run. It adds no verb, no reply shape, and no behavior of its own here; it is a consumer of this contract, which is what makes a successful qualification evidence about this contract working on this host. Discovery — how a client finds a live runner — is the run registry, described in docs/registry.md. The in-code source of truth is src/control/.

cancel and kill add verbs to the same transport and protocol as inspect without reshaping either: one request verb line in, one JSON line out, connection closed. They are mutating — they end the live run — and they reuse the run's own teardown path (the same one a --timeout or a Ctrl-C drives, see docs/schema.md), so a control command never invents a second way to kill a tree.

Discovery: the registry, never a PID

A client never addresses a run by PID (AGENTS.md: "Nothing is addressed by PID"). It finds one through the per-user run registry: it scans records, matches the target run_id, and acts only on a live entry (see docs/registry.md, "Staleness"). A record's endpoint field carries the address of that run's local transport — the channel this document describes.

The registry does not enforce run_id uniqueness, so more than one live entry can match. That is an ambiguous run id — a hard CONTROL (103) failure for every verb (inspect included), never a silent pick of whichever entry the scan returns first. See docs/registry.md, "Run id resolution — ambiguity is a hard failure".

Local transport

Each run stands up one local IPC endpoint, restricted to the current user, and publishes its address in the run's registry record:

• Unix: a unix domain socket. The socket file is created in a short per-run owner-only (0700) directory under /tmp (with the platform temp directory as a fallback), and its own mode is tightened to 0600. The short path is independent of the registry location so deeply nested CI/project paths cannot exceed macOS's sun_path limit. The endpoint address is the socket's absolute path.
• Windows: a named pipe (\\.\pipe\processkit-cli-<unique>), created with a protected DACL that grants full access to the current user alone (D:P(A;;FA;;;<current-user-SID>), built from the same SID the registry restricts to), created with FILE_FLAG_FIRST_PIPE_INSTANCE (so no other process can pre-own the name), and rejecting remote clients. The endpoint address is the pipe name.

Both are locked to the same single user as the registry, because an endpoint is a control channel — a world-reachable one would hand it to any local process.

Concurrency, and never blocking the run

The transport is served concurrently with the child's output pump, on the same runtime. It never blocks the happy path:

• A live run that no one inspects pays only an idle accept.
• The run's exit and teardown do not wait on any control client. When the child exits (or a --timeout / Ctrl-C ends the run), the run resolves and the control server is dropped along with it — tearing the transport down. The child's exit-code fidelity is never at the mercy of a slow or absent control client.

The transport is best-effort infrastructure: if it cannot be stood up, the runner warns on stderr, records a null endpoint, and runs the child normally — the run is simply not inspectable. Losing it never costs the child its faithfully forwarded exit code (AGENTS.md, "Exit-code fidelity").

Cleanup and leaks

On a clean teardown (a normal child exit, a --timeout, or a Ctrl-C) the transport is torn down with the run — on unix the socket file and its private directory are removed. An abrupt runner death (crash, SIGKILL, a parent's Job Object terminate) skips that removal, stranding the socket directory exactly as it strands the registry record and lock. The leak is inert while it lasts: a client detects the run as stale through the registry before it ever connects, so it never touches the orphaned socket.

It does not last, either. prune reaps all three together: reaping a confirmed-stale record now also removes the pkc-… directory and socket that record published, so an abrupt death no longer accumulates dead socket directories in /tmp — see docs/registry.md, "Reaping — prune", for the shape check that endpoint has to pass first (it is untrusted data, like everything else in a record) and for what the reaper deliberately refuses to touch. On Windows there is nothing to reap: the pipe simply vanishes with the process.

Wire protocol

Line-oriented and deliberately tiny. Over an accepted connection:

1. The client writes one request verb line, UTF-8, terminated by \n. The verbs are inspect, cancel, kill, and attest. (An empty line is also treated as inspect, so a bare connect-and-read probe still works.)
2. The server writes back one JSON line — the response — and closes the connection.

The responses per verb:

No verb carries an argument, and for attest that is load-bearing. The request line is the verb and nothing else, so everything a response depends on is either the run's own state or a property of the connection itself. attest answers about the process on the other end of this connection, which the runner reads from the transport rather than from the request — see below.

An unrecognized verb yields a JSON error object ({"error":"..."}) instead, and changes nothing about the run — a foreign client cannot end a run by sending garbage. Short error diagnostics retain their existing text; when JSON escaping would make an error envelope reach the line ceiling, the diagnostic is shortened and marked ... (truncated) before it is written. The writer also applies the same bound as a final guard to every response serializer, replacing an unexpectedly oversized non-error payload with a fixed structured error.

Every request and response line, including its terminating newline, is bounded at 64 KiB. The runner checks a complete inspect snapshot before writing it. If the member list or enriched member fields make that snapshot too large, it sends the bounded structured error {"error":"control-plane inspect snapshot exceeds the 65536-byte response limit"} instead of truncating or fragmenting the snapshot. The client reports that reply through the existing CONTROL (103) error path; it is not a successful, partial snapshot and does not change attest, version, or other error reply semantics.

For the mutating verbs the runner writes its ack first, then signals its own main loop to tear down. The client therefore always receives its confirmation even though the run ends the instant the signal lands; and if the ack cannot even be written (a broken client), no teardown is signaled — an unconfirmed cancel never silently ends a run.

inspect

processkit-cli inspect (--run-id <id> | --all [--label <KEY=VALUE>]...) [--json]

inspect finds the live runner for <id> through the registry, connects to its endpoint, sends the inspect verb, and prints the snapshot to stdout — as a single JSON line with --json, or, by default, as a human-readable rendering (snapshot version, run id, mechanism, root pid, start time, artifact locators, and a member table), mirroring list/prune's optional --json. --json is optional; inspect --json's output is unchanged from before --json became optional.

The aggregate form takes one snapshot of all confirmed-live registry records, optionally filters them by repeated exact --label KEY=VALUE matches (logical AND), and addresses each target by the record path and endpoint captured in that snapshot. Without --json, it prints a terminal-safe table with one row per target and the three-way status inspected / already_gone / failed, followed by a detailed snapshot block for each inspected target. Those blocks reuse the single-run renderer, including its member table and bounded handling of every untrusted string. An empty matching fleet prints no live runs to inspect.

With --json, the original output remains one byte-compatible JSON array. Each element has run_id and either a snapshot with error: null, or snapshot: null with a bounded error string. If any target fails, either output form returns CONTROL (103) after printing the complete report. This preserves partial fleet visibility without turning registry churn into silent omission.

The inspect snapshot

The snapshot is the machine-readable state of a live run. It is the control plane's own client/runner contract, versioned on its own axis (snapshot_version), distinct from the JSONL event schema_version and the registry_version.

Example:

{"snapshot_version":2,"run_id":"build-42","mechanism":"job_object","root_pid":4242,"started_at":"2026-07-20T21:00:00.000Z","jsonl":"C:\\runs\\build-42.jsonl","capture_dir":null,"members":[{"pid":4242,"ppid":4200,"name":"build.exe","start_time":"133456789000000000"}]}

Snapshot version: a newer runner's reply is refused, an older one is read

snapshot_version is not decoration — the client checks it and acts on it. This is the normative statement of that policy; the two inspect forms share one implementation of it (src/control/mod.rs, SnapshotReply::accept).

The rule. This build reads a snapshot declaring version 1 or 2 — the range from MIN_READABLE_SNAPSHOT_VERSION to SNAPSHOT_VERSION in src/control/mod.rs — and refuses anything outside it with the reserved CONTROL (103) code and a message naming the version that arrived, the range this build reads, and which way the runner is out of that range (newer than this client, or older than anything it still decodes). Nothing about a refused reply is printed: it never reaches the human rendering or --json, and under --all that target is reported failed (with the message in its error field), never inspected and never the successful already_gone — the runner did not end, it answered something this client cannot read. The verdict is taken from the declared number before the payload's shape is parsed, so it holds even for a newer reply this build could not deserialize at all (which is exactly the shape a breaking change produces).

Why a newer version is refused. A number above the one this build implements is the runner's statement that the shape moved on in some way this build predates, and this build cannot know which way: it holds no decoder for a contract written after it. Rendering it anyway would present a payload interpreted under semantics its sender never promised — and quietly, because the client re-serializes what it parsed, so a newer runner's added fields are dropped at deserialization and never appear in the output. The operator would see a confident rendering with no marker of what was lost. This is the mixed-binaries case a mid-upgrade user really has (an older inspect against a newer run), and the one this check exists for.

Why an older version is not. The refusal is deliberately one-sided. A lower number does not, by itself, mean "unreadable": the only bump this contract has had — 1 → 2 — was purely additive (it introduced jsonl and capture_dir, both optional with a default, and changed no existing field), so this build decodes a version-1 snapshot correctly, reporting those two as null — "not reported", which is precisely what a version-1 runner meant. That is not a tolerance policy about numbers in general; it is a checkable fact about this repository, pinned by a regression test, and it matters in practice: every binary released so far (v0.1.0 … v0.3.1) writes version 1, so refusing it would make an upgraded client unable to inspect the runs its own predecessor started. When a future bump does make the older shape undecodable or misleading — a removed, renamed, or retyped field, or an existing field whose meaning changed — the floor (MIN_READABLE_SNAPSHOT_VERSION) moves up in that same change, and that is where the judgement is recorded, rather than being inferred from the number.

This is a narrower refusal than the registry read side's, which skips a record whose registry_version is not exactly its own (docs/registry.md), and the difference is earned: that check gates destructive action — probing a lock file and reaping the record behind it — on liveness semantics an unknown version may have redefined. A snapshot is read-only output whose only failure mode is being misread.

What is printed. The snapshot_version in a rendered snapshot is the value the runner declared, unchanged — it reports which contract answered, so against an older runner it is legitimately lower than the version this binary implements. The rest of the object is this client's own re-serialization, so its field set is always this build's. fixtures/schema/cli/inspect.schema.json therefore admits the readable range on this field rather than pinning one value, and it moves when the range moves.

What to do about a refusal. Inspect that run with a processkit-cli build that implements its snapshot version — for a newer runner, one at least as new as the binary that started the run. Retrying the same command will not change the answer. probe --json reports the version (and probe_version) of the binary you run, which is how you tell two installed builds apart; it does not report a runner's snapshot version, and no preflight can — that number arrives only in the runner's own reply, which is what the refusal message quotes back to you.

Consequence for a bump. Bumping SNAPSHOT_VERSION is a real event for a mixed deployment, not just a schema edit: every older client loses the ability to inspect a runner that writes the new number — loudly, with 103, rather than by misinterpreting it. Newer clients keep reading older runners as long as the floor allows, so a bump is not automatically a fleet-wide outage; deciding whether the floor moves with it is part of making the bump, and both are announced in CHANGELOG.md. cancel/kill are unaffected (their ack carries no version and is verified by accepted/action/run_id instead), as are list, wait, and prune, which never read a snapshot, and attest, whose reply is versioned on its own separate axis ("Attestation version" below) and moves only when that number does.

attest

processkit-cli attest --run-id <id> [--json]

Asks the live run named <id> one question: is the process running this command inside your container? The runner answers from the kernel's own record of who opened the connection, so a positive answer is a containment fact rather than a claim the caller repeated.

This is what an environment variable cannot be. An adapter that gates work on "the caller belongs to run X" can otherwise only check the shape of a string the caller carries — a convention enforced by instructions, not a checkable fact, since any process can hold any string (and a string is inherited by processes that later leave the container). attest turns that convention into an invariant the runner itself verifies.

The caller cannot name a process, and that is the whole design. There is no --pid and no equivalent. A caller-supplied pid would prove that some chosen process is a member, which says nothing about the caller and would let any process launder a membership claim about a pid it picked. The identity comes from the transport:

• Unix — the socket's peer credentials. On Linux (and Android/OpenBSD) that is getsockopt(SOL_SOCKET, SO_PEERCRED), whose ucred carries the peer's pid. On macOS SO_PEERCRED does not exist and the portable getpeereid(3) reports only the effective uid/gid — not an identity a membership check can use — so the pid comes from the Darwin-specific getsockopt(SOL_LOCAL, LOCAL_PEEREPID) instead; NetBSD uses LOCAL_PEEREID, and Solaris/illumos getpeerucred(3C). The mechanism differs per platform; the guarantee — a pid the kernel attributes to the peer, not one the peer asserted — does not.
• Windows — GetNamedPipeClientProcessId on the connected pipe instance, which the object manager answers from its own record of the handle that opened it.

PID reuse cannot produce a false positive. The identity is read from the connection while it is open, and the membership check runs on that same open connection: a process holding an open socket or pipe handle has not exited, so its pid cannot yet have been recycled onto a different process. An attestation is therefore a statement about a peer that is demonstrably still there, which is also why it carries checked_at — it is a point-in-time fact about a live connection, not a token to keep and present later.

The pid is checked against the run's own container membership, through the very same members_info() read that produces the inspect snapshot and the JSONL members_snapshot (docs/schema.md, "Enriched member fields") — one notion of "a container member" for the whole binary, never a second list assembled for this command, and never a pid read back from the registry or any other file on disk.

The reply (--json; the default is the same fields rendered for a terminal):

{"attestation_version":1,"run_id":"build-42","verdict":"member","peer_pid":4242,
 "mechanism":"job_object","checked_at":"2026-07-20T21:00:05.000Z"}

The three verdicts are three outcomes, deliberately not a boolean:

There is a fourth outcome, and it is deliberately not a verdict: if the runner cannot read its own container membership at that moment (the members_info() query itself fails), it produces no attestation at all. The client gets the same structured error an unrecognized verb does, surfaces the runner's own words, and reports CONTROL (103) — "the runner could not read its own container membership, so it refused to decide". Answering not_a_member there would state a decided verdict, and deny access through exit 115, on the strength of a failed query; answering peer_identity_unsupported would blame the wrong thing, since the caller was named. This is the same honest-degradation discipline the JSONL members_snapshot event's read_error flag follows — an inspect snapshot still degrades that failure to an empty members array, because a diagnostic that reports nothing is still a diagnostic, while a verdict that decides on nothing is not a verdict.

The attestation is printed on stdout for every verdict, including the two that make the command exit non-zero — the same shape probe --json and inspect --all --json already use when they report and then fail. The verdict is the answer the caller asked for; the exit code says what to do about it, and under --error-format json the matching envelope goes to stderr while stdout stays exactly as it is (fixtures/schema/cli/attest.schema.json).

Why a negative gets its own code. Every CONTROL (103) result means no answer you can act on — the target is missing, stale, unprobeable, ambiguous, unreachable, too slow, or speaking a contract this build refuses. A not_a_member is the opposite: the target was resolved, reached, and answered. An adapter that gated a lease on membership must be able to tell "the runner says no" from "no runner said anything", because the correct response differs (deny versus investigate or retry), so the two never share a code. See docs/exit-codes.md.

Fail-closed on a platform that cannot answer. A runner whose transport cannot name its peer reports peer_identity_unsupported rather than degrading to an unproven member. A consumer establishes that this cannot happen before it depends on attestation, at preflight, with the capability token in probe --json's surface:

processkit-cli probe --json --require-surface attest --require-surface attest:peer-identity

That token carries no -- precisely because it is not a flag: it says this build can obtain a kernel-authenticated peer identity on this platform, and it is absent where the build cannot promise that. A missing capability is then the ordinary fail-closed PROBE_INCOMPATIBLE (110) every other unmet --require-* produces, at preflight, rather than a surprise in the middle of a job. The claim is deliberately one-directional: its presence is a guarantee, its absence withholds one rather than predicting failure (FreeBSD, for instance, supplies a peer pid on a new enough kernel and not on an older one, which no compile-time claim can distinguish — so it is excluded rather than over-claimed, and attest there still answers from whatever the kernel really provides).

What member means, per mechanism

member means exactly this: the run's own container reports the caller as one of its members. Since that is the same enumeration inspect and members_snapshot publish, what a member answer covers follows the mechanism the run obtained (run_started.mechanism, and the mechanism field of the attestation itself):

• job_object (Windows), cgroup_v2 (Linux), and process_reaper (FreeBSD) enumerate the whole contained tree, so any process in the tree — a grandchild, a great-grandchild — attests as a member. The FreeBSD reaper keeps descendants that call setsid in its subtree, unlike the POSIX process-group fallback.
• process_group (the POSIX fallback: macOS and the non-FreeBSD BSDs, and Linux with no usable cgroup) contains a whole tree but enumerates only the tracked group leaders. Membership there is therefore decided against the caller's own process group — the predicate that mechanism actually enforces, and the one its teardown (killpg) reaches — so a contained grandchild attests as a member on this mechanism too, and a process that escaped the group with setsid (and so escaped this mechanism's containment) correctly does not.

An unknown mechanism is the conservative forward-compatible fallback for a ProcessKit mechanism this CLI does not recognize. It is not evidence that the runner selected a fourth current backend, and consumers that require a specific containment guarantee must fail closed on it.

Nested runs. A run started inside another run is an ordinary run: a client inside it attests against it exactly as a client inside a top-level run does, on every platform. Whether that client is also a member of the outer run is mechanism-dependent, and the honest answer differs: Windows Job Objects nest, so the inner run's processes are in the outer job as well and attest as members of it; a Linux cgroup leaf is created inside the outer run's own cgroup, and a process moved into that leaf is no longer listed in the outer cgroup's cgroup.procs, so it attests as a non-member of the outer run even though the outer run's recursive teardown would still reach it. Neither is a bug — each is a faithful report of what that mechanism enumerates — so ask about the run you actually mean, and read mechanism if you need to reason about the containment behind the answer.

Attestation version

attestation_version is the contract's own axis, exactly as snapshot_version is inspect's, and the client acts on it: a reply declaring any other version is refused with CONTROL (103) / incompatible_contract rather than rendered.

That is stricter than inspect's range, on purpose rather than by omission. A misread snapshot is a diagnostic shown under the wrong semantics; a misread attestation is a security verdict, and an adapter would grant or deny access on a sentence its sender never said. And strictness costs nothing here: this contract has had exactly one version, so there is no older shape being refused — unlike snapshot_version, whose floor records a checked fact about a bump that really happened (see "Snapshot version: a newer runner's reply is refused, an older one is read"). If an additive bump ever makes an older attestation genuinely readable, the range widens in the same change that makes the widening true.

The boundary: containment, not authentication

attest reports a containment fact inside the existing same-OS-user threat model (docs/threat-model.md). It is not authentication between mutually hostile peers, and must not be used as one:

• the control transport is owner-only, so every party to this exchange is already the same OS user, and that user's processes are inside the trust boundary this project draws — a same-user process that wanted to interfere with a run never needed to forge an attestation, since it can reach the control plane directly;
• what attest closes is the forgeable correlation: a process that is not contained claiming it is, by carrying a string. That is a real and common failure mode (a stale environment variable, a copied id, a process that outlived the run it was started for), and it is closed by asking the kernel instead of the caller;
• what it does not close is a same-user process that is genuinely inside the container behaving badly, nor anything about a different user (that is the transport's owner-only permissions, not this verb), nor any claim that survives the connection — the fact is scoped to the moment it was checked.

A consumer that needs a security boundary between mutually distrusting parties needs OS-level isolation (separate users, containers, sandboxes); attest is a containment invariant within one such boundary, not a replacement for one.

cancel and kill

processkit-cli cancel (--run-id <id> | --all [--label <KEY=VALUE>]...)
processkit-cli kill   (--run-id <id> | --all [--label <KEY=VALUE>]...)

--run-id and --all are mutually exclusive and exactly one is required, the same clap convention docs/registry.md's wait --all (T-216) established — a bare cancel/kill with neither is a USAGE (100) form error at parse time.

--run-id <id> finds the live runner for <id> through the registry exactly as inspect does — by matching run_id, never a PID — connects to its endpoint, sends the verb, and ends the run. cancel and kill differ only in how the run is ended:

• cancel asks the runner to run its shared soft-stop → grace → hard-kill teardown — the same path a --timeout or a Ctrl-C drives. On Unix a real SIGTERM is delivered to the tree, the --grace window (if the run was started with one) elapses, and the container's kill-on-drop then hard-tears-down whatever remains. On Windows a Job Object has no POSIX signal, so the soft tier is WM_CLOSE to windowed members plus CTRL_BREAK for a child launched with --windows-graceful-ctrl-break; a capability probe reports when neither target exists, and ProcessKit then escalates atomically. The run exits with the reserved CONTROL_CANCELLED (108).
• kill hard-kills the whole tree immediately: no soft stop, no grace. The run exits with the reserved CONTROL_KILLED (109).

The scope of either is only the target run's container, discovered by run_id through the registry. Nothing is ever killed by executable name, and no process outside the run's own ProcessKit container is touched.

The ack

On success the runner replies with one JSON line — an ack — and the client prints it to stdout before exiting 0:

{"accepted":true,"action":"cancel","run_id":"build-42"}

The client parses the ack back and checks it names the action it asked for; a rejected or garbled reply is treated as an unreachable-runner failure (below), never a false success.

The outcome is visible to any observer, not just the client

The client's ack is not the only record of the command. The run also writes the outcome to its JSONL stream (--jsonl), so an external observer reading the event file — not the control client — still sees that the run ended by an outside command:

• cancel writes a cancelled event with source control_cancel (told apart from the local stop signals, which are ctrl_c / sigterm / sighup (Unix) / ctrl_break / ctrl_close / ctrl_logoff / ctrl_shutdown (Windows)), a resource_summary, the cleanup_started / cleanup_finished teardown pair, and a terminal runner_exit with source control_cancel and code 108.
• kill writes a dedicated killed event with source control_kill, a resource_summary, the cleanup pair (with soft_terminate null — no soft stop was attempted), and a terminal runner_exit with source control_kill and code 109.

An outside command therefore does not cost the observer the run's consumption figures: resource_summary is emitted on these endings exactly as on a natural exit, before the teardown that destroys what it reads. The reading is if anything more complete here, because it happens while the tree is still running — on Linux cgroup v2 that is what makes peak_memory_bytes and total_cpu_ms present at all (resource limits, consequence 5).

See docs/schema.md for these events.

cancel --all / kill --all

--all is the aggregate counterpart to --run-id: instead of one named run, it acts on every registry record confirmed live in a snapshot taken the moment the invocation starts. Repeated --label KEY=VALUE filters narrow that snapshot with logical AND; only records carrying every exact pair remain, and labels are rejected with the by-id form. This is the mutating counterpart to wait --all (T-216; see docs/registry.md, "Waiting — wait", "The aggregate barrier — wait --all"), reusing its exact snapshot discipline. The target set is fixed once, before the first mutation is dispatched: a run that registers after the snapshot is out of scope for this invocation, and a run that is only unprobed (not confirmed live) at that instant is excluded from the snapshot outright, the same asymmetry wait --all documents. Each target is keyed by its unique registry-record path and the endpoint that exact record advertised at snapshot time, never by its potentially duplicated run_id. --all can therefore reach two live records sharing an id independently, while the by-run-id form remains the hard ambiguity described above. Immediately before dispatch the client re-reads and probes that exact record path, without scanning or probing unrelated entries, and requires it to remain live with the same id and endpoint; only then does it use the ordinary wire exchange.

An empty snapshot (no confirmed-live entry at all — an empty or fully-stale registry) is not an error, mirroring prune: it prints an empty report ([]) and exits 0. Opening or scanning the registry itself failing (not "found nothing", but "could not even look") is a exit::SETUP (111) failure, the same support/prerequisite failure list/prune/wait report for the identical condition — distinct from the single-run form's CONTROL (103), since there is no one target's reachability in question yet at that point.

The report. Instead of the single-run form's one ack object, --all prints one JSON array, one entry per snapshot target, to stdout:

[{"run_id":"build-42","accepted":true,"status":"accepted"},{"run_id":"build-43","accepted":false,"status":"already_gone"}]

A target that disappears or becomes confirmed stale between the snapshot and its dispatch is reported as already_gone: no runner acknowledged the verb, so accepted remains false, but the aggregate's terminal-state goal is already met and the outcome is non-error. An entry that becomes unprobeable, changes identity, cannot be reached while still confirmed live, or rejects/mismatches its ack is failed and does not stop fan-out to the remaining targets. --all never skips a snapshot entry silently: every one gets exactly one array entry.

The aggregate exit code. Full success — every snapshot target is either accepted or already_gone — is 0. A partial or full failure is never a silent 0: it reuses the reserved CONTROL (103) code (the same one the single-run form uses for "could not reach the target run" — there being one or more unreachable targets is the same class of fact for the aggregate), with a summary message on stderr naming how many of the snapshot targets failed; the full per-target detail is only in the JSON report on stdout, printed before that failing exit. A caller that needs --all to fail loudly on any partial failure (the typical teardown sequence — cancel --all before wait --all/prune) gets that for free from the non-zero exit; one that wants the detail parses the report.

Skipped entries — unchanged from the single-run form. A registry entry that is stale or unprobed at snapshot time is never in the target set at all (--all acts only on entries Health::Live confirms), exactly the same bar the single-run form's own resolver applies — --all only distributes that existing rule over a snapshot, it never widens or narrows it.

When the runner cannot be reached: a distinguishable result, never a hang

Every client — inspect, cancel, kill, and attest — can lose the runner the same three ways (this applies per target under --all too, one snapshot entry at a time). All of them are reported as the reserved CONTROL exit code (103) — "could not reach the target run" (see docs/exit-codes.md) — with an explanatory message on stderr (naming the action and the run) and nothing on stdout for the single-run form (under --all, the same message text lands in that target's error field in the report instead). None is a generic error, and none hangs:

• Stale registry entry. The runner died abruptly, leaving its record behind; the released liveness lock makes the entry stale. The client detects this before connecting and reports the run as gone (its registry entry is stale).
• Unprobeable registry entry. The liveness probe could not be performed at all — the entry's lock file would not open (a directory in its place, a permission error, a rejected symlink/reparse point), the same case list prints as unprobed and prune refuses to reap (see docs/registry.md). The client refuses just as it does for a stale entry — it acts only on a confirmed-live match, and this is not one — but it says so differently: the message reports that liveness could not be probed and names the entry unprobed, never that the runner is gone, which is a confirmed death nothing established. So a refusal you cross-check against list will always agree with what list shows for that record.
• Died mid-conversation. The entry read live, but the runner exited between the liveness probe and the reply — so the connect fails, or the connection closes before a complete response arrives. The client reports that the runner could not be reached or closed the connection before answering.

Every wait — connecting, and the whole request/response exchange — is bounded by a deadline, so a runner that accepts a connection but never answers cannot wedge the client either; it, too, ends as a bounded CONTROL failure. A run id that is not registered at all is likewise a CONTROL failure naming the missing run.

For the mutating verbs this matters twice over: a cancel/kill against a run that is already gone is the same bounded CONTROL (103) result — it never blocks waiting for a teardown that will not happen, and it does not mistake a dead run for a successful cancel.

Two refusals share this code without being a lost runner, and both belong to the read-only verbs. A runner that answers with a snapshot declaring a snapshot_version outside the range this client reads is reachable and perfectly healthy — the exchange completed and the reply arrived — but that reply cannot be interpreted, so inspect refuses it with the same 103 instead of rendering it (see "Snapshot version: a newer runner's reply is refused, an older one is read"). attest has the same refusal for its own attestation_version, plus one more of its own: a runner that could not obtain a kernel-authenticated identity for the caller answers peer_identity_unsupported, which is again 103 — reached, healthy, and unable to give an answer this client may act on. That is what sets these apart from the reasons above: they are all ways the target could not be resolved or reached, while here the target answered and its answer was rejected or withheld. (Determinism is not the distinguishing property — a confirmed-stale entry and an ambiguous run_id are just as unaffected by a retry; only "died mid-conversation" is genuinely transient.) cancel/kill cannot hit any of them — their ack carries no version and no identity.

attest's not_a_member is emphatically not in this family, even though it is also a non-zero exit from a control client: nothing was lost or unreachable, the runner answered, and the answer is the point. It carries NOT_A_MEMBER (115) for exactly that reason (see "attest").

This is the exit-code half of the contract: a caller distinguishes "here is the run's state" / "the command was accepted" (exit 0, JSON on stdout) from "that run is not reachable" (exit 103, message on stderr) without parsing free text.

Telling the reasons within that 103 apart is the one thing the code cannot do — which is what the global --error-format json is for: under it the same failure prints a bounded JSON object on stderr whose kind is exactly the distinction this section draws (stale, unprobed, control_unreachable, ipc_deadline, ambiguous_run_id, not_found, and — for the two refusals above — incompatible_contract and peer_identity_unsupported). Still no free text parsed, and stdout is untouched. See docs/exit-codes.md.

Run registry

The run registry is the first brick of processkit-cli's control plane. The control plane lives in the live run process, not in named kernel objects (AGENTS.md, "The control plane lives in the live runner process"): a runner must stay alive to hold its kill-on-drop container, so the live process is exactly where inspect / cancel / kill / attest reach it. The registry is how those clients find a live runner — a per-user directory holding one record per in-flight run.

This document is the normative description of the registry's location, record format, and staleness signal. The transport those clients speak over, and the inspect client itself, are described in docs/control-plane.md; here we define only the registry.

list (see "Discovery" below), prune (see "Reaping" below), and wait (see "Waiting" below) are the clients that read the registry directly, without connecting to any runner's control transport: list scans every entry and prints it, so an operator that has lost (or never had) a run_id can find one before reaching for inspect/cancel/kill; prune reaps the entries list would show as stale; and wait blocks on one entry until it is no longer live, so a supervisor that is not the runner's parent can still wait for a run to end.

Location

The registry is a per-user directory — not system-wide and not tied to any one run. It is resolved in this order:

1. PROCESSKIT_CLI_REGISTRY_DIR — if set (and non-empty), it is used verbatim as the registry directory. This lets an orchestrator pin the location and lets the tests isolate a scratch registry.
2. Platform default, otherwise:
   • Unix: $XDG_RUNTIME_DIR/processkit-cli/runs when XDG_RUNTIME_DIR is set — a user-private, per-session runtime directory is the natural home for live-run state — else $HOME/.local/state/processkit-cli/runs.
   • Windows: %LOCALAPPDATA%\processkit-cli\runs, falling back to the same path built from %USERPROFILE%.

Permissions

The registry directory is created restricted to its owner, and every mutating open guarantees that restriction before a record is written into it — including on a pre-existing directory whose permissions were widened out of band, which is repaired rather than trusted. A record names a run's private control-channel endpoint, so a world-readable registry would hand that channel to any local process. Two commands take that open: run, which is about to write a record, and doctor, whose whole job is to establish that this host reaches the state described here (it re-reads the resulting permissions and reports them, rather than assuming the open succeeded means it worked — see docs/troubleshooting.md, "Qualifying a host: doctor"). The read-only open every other client takes — list, prune, wait, events, and the control clients — deliberately does neither: it does not create the directory and does not touch its permissions, since a read-only scan must not mutate registry state.

• Unix: mode 0700. Applied at creation and re-asserted with chmod (which, unlike the creating mkdir, is not filtered by the umask) on every mutating open.
• Windows: a protected DACL that grants full control only to the current user — the equivalent of 0700. Concretely the directory's DACL is D:P(A;OICI;FA;;;<current-user-SID>): Protected (inherited ACEs from the parent are blocked), a single allow-Full-Access ACE for the current user, inherited by child objects and containers (OICI) so the records and lock files inside are covered too. The directory is created carrying that descriptor, so it never exists momentarily reachable through permissions inherited from its parent.

The two platforms differ in how a mutating open reaches that state, because the cost of asserting it differs by three orders of magnitude. Unix simply re-applies the mode: one chmod, constant cost. Windows first verifies — one read of the directory's own security descriptor — and writes only when what it finds is not already exactly the DACL above; the write it avoids is SetNamedSecurityInfoW, which re-propagates the inheritable ACE across every record and lock file in the directory and therefore costs more the more runs the registry remembers (measured at roughly 0.15 ms per file — about 310 ms for a registry holding 1024 entries — by benches/registry_open_bench.rs).

The guarantee is identical either way, and deliberately so: the write is skipped only when the directory's DACL is already the target, compared ACE for ACE (protected bit, allow type, inheritance flags, access mask, and binary SID). Any deviation, any unreadable descriptor, and any path that is not a directory all fall through to the unconditional write. Nothing weaker — the directory merely existing, a marker file, a timestamp, a cached "already done" flag — is ever accepted as evidence, precisely because a principal who cannot defeat the DACL could still forge those and suppress the repair.

Record format

Each run writes one record file (<opaque-stem>.json) plus a sibling lock file (<opaque-stem>.lock). The record is a single JSON object:

{
  "registry_version": 1,
  "run_id": "run-1234-...",
  "endpoint": "\\\\.\\pipe\\processkit-cli-1234-...",
  "started_at": "2026-07-20T21:00:00.000Z",
  "argv_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "hint": null,
  "labels": { "batch": "42" },
  "liveness": {
    "kind": "advisory_lock",
    "lock_file": "run-000...-0000.lock"
  }
}

Serialized size policy

The serialized record has an inclusive limit of 65,536 bytes (64 KiB). Readers read one byte beyond that boundary so they can distinguish an exact-boundary record from an oversized one. Writers serialize the complete JSON object first and apply the same byte limit before creating the .json file; a record exactly at 64 KiB remains discoverable by list, wait, and the control-plane readers.

An oversized record is rejected as InvalidData with its measured size and the supported maximum in the diagnostic. The runner treats this as best-effort registry degradation: it warns on stderr, continues the contained child, and preserves the child's exit code. It does not truncate or silently drop individual labels or artifact locators. The reservation guard removes the pre-publication .lock, so a rejected record cannot leave a .json/.lock pair for prune to recover.

Registry identity, endpoint, and artifact-path strings remain byte-for-byte intact for matching and JSON output. Every human-readable renderer of one sanitizes terminal formatting and limits the field to 256 characters plus an explicit ... marker, so a corrupt record cannot create an unbounded terminal row — list, inspect, and prune for the fields each prints, and events for the single field it echoes: the jsonl locator, named in the diagnostics for a stream it could not open or read.

list --label KEY=VALUE applies the same exact-match, logical-AND label filters as the aggregate control and wait commands. list --health live|stale|unprobed restricts that result to one liveness verdict; the two filter kinds combine.

Which run is which — and what a record never carries

argv_sha256 and hint exist so an operator (or an orchestrator) staring at several live entries can tell which run is which before picking one to inspect/cancel/kill — see "Discovery" below, where both are printed. They are the redaction-safe half of the run's command: the fingerprint says whether two entries are running the same command, the hint names a recognized worker shape, and neither can disclose a command line (AGENTS.md, "Argv is redacted by default"). Both are produced by exactly the implementation the JSONL stream uses, so the same run never fingerprints differently in the two artifacts.

The artifact locators are published on every new run (capture_dir only when that feature is enabled). This is deliberate: they are operator-selected observability locations rather than argv, and the registry is already owner-only because it holds the live control endpoint. Publishing them closes the detached-run discovery loop: a supervisor with only a run_id can find the event stream and transcripts as well as inspect, wait for, or stop the run. Paths can still contain a sensitive project or user name, so consumers must treat registry JSON as private operational metadata and must not copy it into public logs. Human list/inspect output terminal-sanitizes and visibly bounds both paths; JSON preserves the exact strings.

The raw argv is never written to a record, under any flag. --argv-raw widens the run_started event only; the registry's register is handed a fingerprint-and-hint value, not the argv, so there is no code path — and no future flag — through which a command line can reach a registry record.

Two further fields were considered for the same "tell runs apart" purpose and deliberately left out:

• root_pid would put a reused-at-any-moment number in front of an operator inside the one artifact whose entire design says a PID cannot identify a run (see "No PID addressing" below) — an invitation to kill the process that inherited it. The fingerprint distinguishes runs without that hazard.
• cwd is raw, unredacted text with no redaction rule in this project's contract (which covers argv only), and a working directory routinely spells out a customer, ticket, branch, or user name. Persisting it verbatim into a long-lived per-user file that every local client of this binary reads is a disclosure decision distinct from the run_started event's — that stream is written only to a file the caller explicitly asked for with --jsonl. It would also add a second untrusted path to validate on read.

Reading a record: additive fields, and untrusted values

The command-identification and artifact fields are optional on read, and that is what makes adding them a non-breaking change to registry_version (still 1):

• A record written before they existed — or by any writer that publishes none — reads back with them null. They are deserialized as optional/defaulted, so their absence is never an error.
• A record written by a newer writer, carrying fields this binary does not know, is read as an ordinary record: unknown fields are ignored, not treated as corruption. Both directions matter in the mixed registry a mid-upgrade user actually has, where an older list/prune binary and a newer run share one directory.

A registry_version bump is reserved for the opposite kind of change: renaming, removing, or retyping an existing field, changing what a value means, or adding a field a reader must understand in order to behave correctly.

Like every other field, both are untrusted deserialized data on the read side (the same stance liveness.lock_file and endpoint are held to) and are validated by shape: argv_sha256 must be exactly 64 lowercase hex characters, and hint must be a non-empty, at-most-64-character label of ASCII lowercase letters, digits, and _ — the snake_case shape the classifier catalog requires. hint is checked by shape rather than membership in this binary's own catalog on purpose, so a label minted by a newer runner is not silently dropped.

A value failing its check is dropped to null, and the record is kept — unlike a malformed started_at or lock_file, which skip the whole record. The difference is what the value can do: those two steer an action (a path that gets opened, an ordering every client reasons about), while these two are reported and nothing more. Discarding a record over one of them would let a purely cosmetic field hide a live run from list, wait, and every control client at once — one hand-edited byte in a live entry's hint and cancel/kill could no longer find the run they are aimed at. Losing the field is strictly the smaller loss.

No PID addressing

A record is never indexed or identified by a bare PID (AGENTS.md: "Nothing is addressed by PID"). The file name (<opaque-stem>) is a PID-free time+counter token whose only job is to be unique; the authoritative identity is the run_id field. Clients find a run by scanning records and matching run_id, so PID reuse cannot alias one run onto another. Uniqueness of the file name is guaranteed by the filesystem (the lock file is created with O_EXCL / CREATE_NEW), so concurrent runs always get independent entries that neither overwrite nor block each other.

Staleness — detectable, and not by file existence

If a runner dies abruptly (crash, SIGKILL, a parent's Job Object terminate), the kernel container reaps the whole process tree, but the record file is left behind. A client must be able to tell that leftover record from a live one — and crucially, the file merely existing is not enough to conclude the run is alive.

The signal is an OS advisory lock:

• A live runner holds an exclusive advisory lock on the record's lock file for the entire run (flock(LOCK_EX) on unix; LockFileEx with LOCKFILE_EXCLUSIVE_LOCK on Windows). The lock is tied to the open file handle, and the operating system releases it automatically when the process dies — by any means, clean or abrupt.
• A client checks liveness by trying to take that same lock, non-blocking:
  • Denied (the lock is held) → a live runner owns it → the entry is live.
  • Acquired (no one holds it) → the runner is gone → the entry is stale.
  • Lock file missing → stale by definition.

Because the verdict comes from the lock — which the OS frees on death — and not from the file's presence, an orphaned record is reliably classified as stale. A client performing a pure liveness query releases the lock immediately after acquiring it; a client that intends to reclaim a stale entry would instead keep the lock held to claim it atomically.

Run id resolution — ambiguity is a hard failure

The registry does not enforce uniqueness of run_id at register time: two concurrent runs started with the same explicit --run-id are both written as independent entries (independent opaque file stems — see "No PID addressing" above) and both read as live for as long as they run. Resolution is therefore the client's job — in resolve_live_endpoint (src/control/mod.rs) for the control-plane verbs, and in Registry::probe_run (src/registry/mod.rs) for the registry-only wait, which reaches the same verdict from its own scan — and it is deliberately conservative:

• The client scans every entry and filters to those matching the requested run_id, then counts how many of those are live (see "Staleness" above) — deliberately before ever looking at whether they publish an endpoint. A live entry that has not (yet, or ever) published an endpoint — a disconnected or failed transport — still counts as a live duplicate; if endpoint presence narrowed the count first, such an entry would be silently skipped and a duplicate could evade detection.
• Zero live matches → a distinguishable CONTROL (103) failure naming why (no such run registered at all, or the sole match is stale) — see docs/control-plane.md.
• More than one live match → also a CONTROL (103) failure, "ambiguous run id", instead of silently acting on whichever entry the directory scan happens to return first. This applies to every by-run-id client the same way — the destructive cancel/kill verbs, the read-only inspect and attest, and the registry-only wait — rather than a softer fallback for the read-only ones: guessing wrong on a mutating verb ends the other run instead of the intended one, a snapshot of the wrong run under inspect is exactly as misleading as acting on it, an attest verdict attributed to the wrong run would answer a containment question nobody asked, and a wait that silently tracked one of two duplicates would report "your run finished" on the strength of the wrong run's ending. A caller that hits this is expected to pick a --run-id that is unique among currently live runs.
• Exactly one live match → only now does its endpoint matter: resolved normally if it published one, or a distinguishable CONTROL (103) failure ("the run is live but exposes no control endpoint") if it did not.

That single check happening once, at the start of the call, is a TOCTOU race for the mutating verbs: register never enforces uniqueness, so a duplicate can register under the same run_id in the window between the scan and the verb reaching the runner over the transport (the connect round trip in between). cancel/kill narrow that window as tightly as the registry's decentralized, no locking-across-processes design allows: immediately before writing the verb, the client re-runs the same scan+match and requires it to resolve back to the exact endpoint it already connected to — any other outcome (a fresh ambiguity, the entry having gone stale, or the resolution landing on a different entry) aborts the command without ever writing to the wire. inspect does not repeat this check: being read-only, a race that surfaces a snapshot from just before a duplicate registered is merely stale information, not a wrong-target action.

That pre-dispatch re-check is a synchronous scan, while the verb write that follows it is a separate, later .await; the two cannot be made atomic with each other, so a duplicate can in principle still register in the sub-instruction gap between the re-check returning and the write reaching the OS. Closing that residual gap completely would need a run_id-keyed lock held across process boundaries through the write — a registry redesign this resolver deliberately does not attempt (see "No PID addressing" above). It is not needed for correctness, though: by the time the re-check runs, the client has already connected to the target's specific, uniquely-tokened transport endpoint (endpoint_tokens_are_unique in src/control/tests.rs), and a later registry write cannot retarget bytes already destined for an open connection. So the guarantee the re-check actually buys is narrower than "no ambiguity can ever exist at write time" (impossible without that cross-process lock) and is instead: the verb can never be misdirected to a different run than the one already resolved and reconfirmed. A duplicate that registers in the residual gap is simply invisible to that call — it becomes visible on the next one — never a wrong-target action. See racing_duplicate_after_reconfirm_does_not_misdirect_the_dispatched_verb in src/control/tests.rs for a deterministic proof of this property.

Discovery — list

processkit-cli list [--json] opens the registry through [Registry::open_read_only] (src/registry/mod.rs) — not the mutating [Registry::open] run and doctor use, so listing never creates the registry directory and never touches its permissions — and scans it with [Registry::entries], the same scan every other client shares, printing every entry it finds, whatever its health: run_id, health (live/stale/unprobed), started_at, hint, argv_sha256, labels, jsonl, capture_dir, and endpoint. It is deliberately read-only and never connects to any runner's control transport, so it carries none of the "could not reach the target run" failure modes inspect/cancel/kill/attest do — it has no single target to fail to reach.

• No --json prints a human-readable table (or no runs registered for an empty registry). Because record files are untrusted input, control characters in identity, endpoint, or artifact paths are collapsed to spaces and visibly bounded at this terminal boundary; they cannot forge another row or inject an ANSI sequence.
• --json prints one JSON object per entry, one per line, sorted by run_id, then started_at, then the entry's registry record path (a tertiary tie-break, never itself printed) for a fully deterministic order even when two entries share both a run_id and a millisecond-precision started_at — the same "JSON Lines" shape inspect --json uses for a single snapshot.
• An empty registry is not an error: list prints an empty result (or the no runs registered notice) and exits 0, exactly like scanning any other registry state.
• A stale (or unprobed) entry is listed, not hidden — unlike inspect/cancel/kill/attest, which treat anything other than a confirmed-live match as an unreachable-run failure, list's whole purpose is discovery, so a stale leftover (evidence of a runner that died abruptly without cleaning up) is exactly the kind of thing an operator wants to see, e.g. before reaping it.
• unprobed is a distinct value, never folded into stale (T-206). A record whose liveness lock could not even be opened (permission denied, a rejected symlink/reparse point, or an unexpected non-regular file in its place) is health unprobed: the probe could not run, so nothing is confirmed — printing it as stale would assert a confirmed death the probe never established, which could lead an operator to hand-delete a record that may still belong to a live run. This is the same three-way vocabulary prune --json's unprobed tally and wait's RunStatus::Unprobed already use for the identical case (see "The reaping safety invariant" and "Liveness it cannot confirm" below) — list's health field is additive: existing --json consumers that already treat any non-"live" value as "not live" need no change, only ones that matched exhaustively on exactly "live"/"stale".
• Telling several live runs apart. Health, run_id, and started_at cannot say what a run is running, so a registry with three live entries used to leave an operator guessing which one to act on. Each entry therefore also prints the two redaction-safe command fields the record carries (see "Which run is which" above): hint — the worker-shape label, or -/null when the command matches no known shape — and argv_sha256, the one-way argv fingerprint, which is equal for two entries exactly when they are running the same command. Neither discloses a command line, which is why they can be printed at all.
  • In the table, ARGV_SHA256 is abbreviated to its first 12 hex characters followed by ... (a full digest is six times the width of every other column put together, for a value read comparatively rather than character by character). An absent value renders as -, exactly like an absent ENDPOINT.
  • In --json both are full-precision fields — argv_sha256 carries the whole 64-character digest, so it can be compared byte-for-byte against the same run's run_started event — and both are always present, null when the record carries no value. Additive: a consumer reading the fields it knows is unaffected.
  • labels is the full key/value object in JSON and a comma-separated LABELS cell in the table. Human output passes both keys and values through the terminal sanitizer.
• A single corrupt or unreadable record is skipped by Registry::entries itself (see "Staleness" and the per-record degradation documented there) and never blinds list to the other, healthy entries — including a record whose started_at is not the well-formed YYYY-MM-DDTHH:MM:SS.sssZ shape a runner actually writes. A malformed hint/argv_sha256 is the one case that does not skip the record: the offending field alone is dropped to null (see "Reading a record" above), so a cosmetic value can never hide an entry from this listing.

Reaping — prune

processkit-cli prune [--json] [--label KEY=VALUE]... is the cleanup counterpart to list. Where list shows a stale leftover, prune deletes it: it opens the registry through [Registry::open_read_only] (src/registry/mod.rs) — like list, so it never creates the directory or touches its permissions; a missing or empty registry simply has nothing to prune — scans it with the same shared scan list uses, and for each scanned record deletes both its files (<stem>.json then <stem>.lock, the same order [Registration::remove] uses) only when it can confirm the record is stale. On unix it deletes a third leftover of the same death — the control socket that record published, see "Reaping the control socket" below.

Repeated --label KEY=VALUE filters use the shared label parser and combine with logical AND. When filters are present, only paired records carrying every requested label enter the prune tally or liveness probe. Lone orphaned .lock files have no record from which labels or ownership can be recovered, so an explicitly filtered prune leaves them out of scope entirely. With no filter, the original registry-wide paired-record and orphan-lock passes are unchanged.

It then makes a second pass over any orphaned lock files — a .lock with no .json sibling at all. Such a .lock is invisible to the shared scan (which only ever walks .json records), so however long it has sat there the paired-record pass above can never find it. An orphan can still arise two ways: Registry::register reserves and locks the .lock file before it writes the .json record, so a fs::write failure in between would otherwise leave the fresh lock file behind forever — this is now closed at the source by a Drop-backstop guard on the reservation, armed until the record is published and disarmed right after, so a failed register deletes its own lock file instead of leaking it; or Registration::remove's best-effort .json delete can succeed while its .lock delete does not, which is not similarly guarded. The second pass reuses the exact same lock-probe safety as the first (a Live lock is never touched, a probe failure leaves the file in place, only a confirmed-stale lock is deleted) and reports its reaps under the separate orphaned_locks tally below — kept distinct from pruned because it deletes one file, not a .json/.lock pair.

A record-less lock file needs one more guard the paired-record pass does not: a freshly create_new-d .lock file that a just-starting Registry::register has not yet locked is, for a moment, indistinguishable from a genuine, long-dead orphan — both are simply an unlocked .lock with no .json next to them. The second pass therefore only ever considers a candidate whose mtime is already at least a few seconds old (ORPHAN_LOCK_MIN_AGE in src/registry/mod.rs); a genuine orphan never ages out of that check, so the extra latency costs nothing, while the two-syscall reservation window reliably falls inside it. Registry::reserve_entry closes the same window from its own side: after taking its lock it re-checks that lock_path still resolves to the identical file it is holding open (device/inode on Unix, file index + volume serial number on Windows) before trusting it enough to publish a record naming it, and retries with a fresh stem — never a hard error — both when the lock is denied and when that identity check fails. Together these close the race a lock-probe-only guarantee would otherwise leave open (see "The reaping safety invariant" below).

Reaping the control socket

An abruptly-killed runner leaves more than a .json/.lock pair behind. On unix its control transport is a socket file inside a per-run 0700 directory named pkc-<token>, created under /tmp (or the platform temp directory) and removed only by the clean-teardown Drop that an abrupt death never runs — see docs/control-plane.md, "Cleanup and leaks". The dead record publishes that socket's path in its endpoint field, and nothing else on the system knows about it, so once the record went the directory was stranded forever: over time, SIGKILLs and crashes accumulate dead pkc-* directories that no prune pass ever looked at. Reaping a confirmed-stale entry therefore also reaps the socket that entry published, closing the half of the "leftovers of runners that died abruptly" contract that used to stay open.

It is reaped before the record naming it, still under the same held lock: the record is the only thing that points at the socket directory, so a pass interrupted between the two deletions must not be the one that leaves the socket unreferenced.

A record's endpoint is untrusted deserialized data, exactly like its liveness.lock_file (whose own single-component name check the scan already applies before ever joining it onto the registry directory) — and this step deletes what it names, so it is never used as a path on trust. It is first validated by shape, and a value failing any part of that check simply contributes no deletion at all (the record and lock are still reaped as usual — the check gates only this extra step):

• absolute, and written as plain /-separated names: a relative path, a ./.. segment, a doubled separator, or an embedded NUL/control character is refused — and refused as written, without normalizing anything away first;
• the final component is exactly the socket file name the control server binds (c.sock), and its parent is pkc- plus a non-empty token of ASCII alphanumerics and - — the character set the transport's own token generator mints;
• that parent sits directly inside one of the base directories the control server binds in (/tmp, or the platform temp directory). A perfectly-shaped path anywhere else — /etc/pkc-x/c.sock, $HOME/pkc-x/c.sock, one directory deeper — is not a candidate.

Shape alone cannot settle whether the path is a symlink, since that answer can change between the check and the deletion. So it is settled where it cannot be raced, at open time: the validated directory is opened with O_NOFOLLOW | O_DIRECTORY (the same discipline the liveness probe applies to a lock file), and the socket is then removed relative to that open handle. A pkc-… name that is really a symlink fails the open outright, and a swap landing after it cannot redirect the deletion. Two further refusals bound what can be deleted: only an entry that really is a socket is unlinked (a regular file, a symlink, or a device node under that name is left alone), and the directory itself is removed with rmdir, which never follows a final symlink and only ever removes an empty directory — so anything unexpected still inside keeps the directory too.

Every step is best-effort, exactly like the record/lock deletions: a socket that will not go is a leftover to retry next pass, never a reason to abort the reaping of other entries. A run whose socket was created under a different temp directory than the pruning process sees (a changed TMPDIR between the run and the prune) keeps its socket rather than having an unrecognized path deleted on its behalf. The tally is unchanged: a reaped socket is counted by its own entry's pruned, not by a counter of its own — the socket belongs to that entry and is never reaped without it.

Windows is unaffected. A Windows run publishes a named pipe, which lives in the kernel object namespace and disappears with the process that created it. There is no filesystem leftover to reap, so no endpoint is ever a candidate there and prune behaves exactly as it did before.

The reaping safety invariant

Pruning deletes files, so it is deliberately conservative: an entry is reaped only when its own liveness probe succeeds and reports stale. The three probe outcomes are kept strictly apart — and this is the load-bearing distinction:

• Confirmed stale ⇒ reaped. The lock file is absent (stale by definition), or its exclusive lock was free and the probe took it (no live runner holds it). Only this case deletes anything.
• Live ⇒ never touched. A live runner holds the lock, so its entry is left exactly as it is. Prune never deletes a running run's record.
• Probe failed ⇒ left in place. The probe could not even be performed — the lock file would not open (a directory in its place, a permission error, a rejected symlink/reparse point) or the lock call itself errored. Liveness is unknown, not confirmed stale, so the entry is kept, on every repeated prune. This is the same case Registry::entries reports as [Health::Unprobed] (T-206) — never folded into Stale — so the read path list/inspect share already keeps it apart from a confirmed-dead entry too, at the Health level; inspect/cancel/ kill/attest still act on it exactly as they do on Stale (they refuse, because they act only on [Health::Live], and a probe-failed record is not that whichever of the two non-live values it carries) — but they no longer word the refusal the same way: an unprobeable entry is reported as unprobed, liveness unknown, not as a runner confirmed gone (see docs/control-plane.md, "When the runner cannot be reached"). Prune, though, cannot simply reuse Entry::health here even now that it distinguishes the case: reaping needs the probe's acquired lock held across the two deletions below, and a pure liveness query like entries() already released it — so prune probes on its own path that keeps the failure distinct and keeps the lock, and errs toward keeping a record it is unsure about.

Two further guarantees hold, mirroring the rest of the registry:

• Never by PID. A reaped entry is addressed only through the record path the directory scan produced (the same PID-free tokened stem — see "No PID addressing" above), never by a process id, so PID reuse can never misdirect a deletion.
• Reclaim under the lock. A confirmed-stale entry is deleted while the probe still holds its exclusive lock — the "keep the lock to reclaim" behavior noted under "Staleness" above — so a second concurrent prune sees the entry as live and skips it instead of racing on the same files.

A .lock file with no .json sibling carries one further precondition before any of the three probe outcomes above even apply: it must already be at least ORPHAN_LOCK_MIN_AGE old (by mtime). A confirmed-stale-or-live-or-unprobed verdict on a lock-probe alone is not enough to call a record-less lock file safe to touch, because a freshly reserved-but-not-yet-locked file would otherwise read as "probe succeeded, no live holder" — indistinguishable from a genuine orphan purely by scheduling luck. A too-young candidate (or one whose age could not be confirmed at all) is simply left alone this round, to be reconsidered once it has aged.

Corrupt records the scan already skips (unreadable, unparsable JSON, a malformed started_at, or a lock_file that is not a simple in-directory name) are not prune candidates: they are never probed and never deleted, exactly as list leaves them alone — and a .lock file that does have a .json sibling, however corrupt, is likewise left to that first pass (or to neither pass, for a corrupt record), never treated as orphaned. Every deletion is best-effort and per-entry — an OS error reaping one entry never aborts the reaping of the others (the leftover just reads as stale again next time) — and pruning an already-clean, empty, or missing registry is a no-op that exits 0.

• No --json prints a one-line summary (no stale entries to prune when there was nothing to reap).
• --json prints a single JSON object with the tally: pruned (paired entries reaped — each including whatever control socket that entry published, see "Reaping the control socket" above), live (live entries left untouched, paired or orphaned lock alike), unprobed (entries whose probe failed and were left in place, paired or orphaned lock alike), and orphaned_locks (lone .lock files with no .json sibling that were reaped). These four fields are unchanged: reaping a socket adds no counter of its own.

Previewing a reap — prune --dry-run

processkit-cli prune --dry-run [--json] [--label KEY=VALUE]... answers "what would prune reap right now?" without reaping anything. It is [Registry::preview_prune] (src/registry/mod.rs), the non-destructive sibling of [Registry::prune]: the exact same two-pass scan (paired records via Registry::scan, then orphaned locks via Registry::orphaned_lock_paths) classified through the exact same [probe_for_prune] three-way probe described in "The reaping safety invariant" above, so a candidate here is confirmed stale by precisely the same rule a real prune would use to reap it. The only thing that differs is the action taken on a confirmed-stale (Reapable) verdict: instead of deleting the entry's files while holding the probe-acquired lock, preview_prune releases that lock immediately — there is nothing to reclaim it for, since nothing is being reaped — and records the candidate instead. Live and probe-Err verdicts are handled identically to prune. The result is that preview_prune's aggregate tally is exactly what a following, untouched prune pass over the same on-disk registry state would report, and the preview itself never calls fs::remove_file on anything, so the registry is left byte-for-byte as it was.

Label filters are applied before the same liveness probes in both paths. A filtered preview therefore lists and counts exactly what a real prune with the identical filters would reap; it also excludes ownerless orphan locks by the same rule.

Because a paired record carries run_id/started_at but an orphaned .lock file has no record to pull identifying fields from at all, each candidate is described differently:

• a confirmed-stale paired entry is identified by its run_id and started_at, the same fields list already prints for it, plus the control-socket directory (socket_dir) a real reap would remove along with its two files;
• a confirmed-stale orphaned lock is identified by its lock file name (there is no run_id/started_at to report).

socket_dir is classified by the very same shape check the real reap applies (see "Reaping the control socket" above), so the preview can neither promise a deletion the reap would refuse nor stay silent about one it would perform. It is null whenever that reap would remove nothing — no endpoint was published, the endpoint is not the shape a control server creates, or the record is a Windows one, whose named-pipe endpoint has no filesystem leftover. Like every other part of a preview it is read from the record alone: nothing is stat-ed, so a directory named here may already be gone (reaping it is best-effort, exactly like the record/lock deletions).

• No --json lists each confirmed-stale candidate on its own line — a paired entry as run_id=<id> started_at=<ts>, followed by socket_dir=<path> when there is a socket directory to reap with it (omitted entirely when there is not), an orphaned lock by its file name — then the same summary-line shape prune's human-readable output uses, prefixed would throughout since nothing is actually reaped (no stale entries to prune (dry run) when there is nothing to preview). Control characters in the record's run_id or the directory entry's lock-file name are collapsed to spaces before interpolation, so neither can forge output lines.
• --json prints a single JSON object with the exact same aggregate fields prune --json reports (pruned/live/unprobed/orphaned_locks), plus an additional candidates array: one object per confirmed-stale candidate, internally tagged "kind":"entry" (with run_id/started_at/socket_dir, the last always present and null when there is no socket to reap) or "kind":"orphaned_lock" (with lock_file_name).
• prune without --dry-run is unchanged: its human-readable and --json output, and its exit codes, are identical to before this flag existed.
• Like prune, --dry-run opens the registry through Registry::open_read_only, so previewing never creates the registry directory or touches its permissions, and an empty or missing registry previews an all-zero tally with an empty candidates list rather than erroring.

Waiting — wait

processkit-cli wait (--run-id <id> [--report-outcome] | --all [--report-outcome]) [--timeout <duration>] is the lifetime counterpart to list's discovery and prune's cleanup: it blocks while its target is live and returns as soon as it is not. --run-id and --all are mutually exclusive (clap rejects both together) and exactly one is required — see "The aggregate barrier — wait --all" below for the second mode. It exists for the supervisor that did not start the run — an adapter that restarted, a cleanup step, anything holding only a run_id (or nothing but "I want every run gone") — and therefore has no child process to wait on. Like list and prune it opens the registry through Registry::open_read_only (src/registry/mod.rs), so waiting never creates the registry directory or touches its permissions, and unlike inspect/cancel/kill/attest it never connects to the run's control transport: the run is not disturbed, not ended, and not even aware of the waiter. A run whose transport never came up (a null endpoint, see "Record format" above) is still perfectly waitable — wait needs no endpoint.

A run started with run --detach is the case this was written for: that call returns once the run has started and is never the runner's parent, so wait is how its caller learns the run is over. wait --report-outcome also consumes the run's published --jsonl locator and terminal event for callers that want the outcome in the same supervision step. A detached run publishes an ordinary record here — nothing about the entry, its liveness lock, or its removal on a clean exit differs — so list, prune, and wait treat it exactly like any other.

How it waits. Liveness is the advisory lock described under "Staleness" above, and that lock offers no event, notification, or wakeup a third process could subscribe to. Waiting on it is therefore honest periodic probing — one scan plus one non-blocking lock attempt per matching record, a few times a second (POLL_INTERVAL in src/wait.rs) — not an event subscription dressed up as one. Blocking on the lock itself would be worse than merely slow-to-notice: acquiring a stale entry's lock is how a reclaimer claims it (see "Reaping" above), and it would still miss the ordinary clean exit, which deletes both files rather than handing the lock over.

Three outcomes, by exit code:

• 0 — the run is over: no record matches the run_id any more, or every record that does probed as stale.
• WAIT_TIMEOUT (112) — the --timeout given to wait elapsed while the run was still live. This is the waiter's deadline, not the run's: the run was left running, untouched, and will report its own ending in its own time. It is deliberately not the run's TIMEOUT (106), which means the opposite — see docs/exit-codes.md, "A waiter's deadline is not a run's deadline". Without --timeout, wait blocks indefinitely.
• CONTROL (103) — the run_id is ambiguous: more than one live entry matches, so there is no single run whose end could be waited for (see "Run id resolution" above). Re-checked on every probe, not just the first, since a duplicate can register at any moment.

Nothing is printed on ordinary success. --report-outcome instead prints exactly one JSON object for --run-id, or one JSON array for --all, while leaving all exit-code semantics above untouched:

{"run_id":"build-42","status":"reported","code":7,"source":"child_exit","child_code":7}

The waiter remembers the sole confirmed-live record's absolute jsonl locator on its polling passes. Once that record disappears, it reads the terminal runner_exit; code, source, and child_code use that event's vocabulary. A short bounded retry bridges the runner's normal teardown ordering, where record removal can precede the final flushed event by a few instructions. If the waiter never observed the run live, an older record published no locator, the runner died without a terminal event, or the stream cannot be read, success remains honest data:

{"run_id":"build-42","status":"unknown","code":null,"source":null,"child_code":null}

The mode does not forward code as the wait process's exit status. A registry that cannot be opened or read at all remains a SETUP (111) failure, exactly as for list/prune.

An unknown run_id reads as "finished"

A run that exits cleanly deletes its own registry entry (see "Lifecycle" below), and the registry keeps no history of what used to be there. So "build-42 was never registered" and "build-42 finished a moment before you asked" are the same observation: no matching record. Nothing in the registry can separate them.

wait therefore answers both the same way — exit 0, "it is not running" — rather than inventing a third outcome that could only ever be a guess. Failing on an unknown id would be worse than unhelpful: it would make the result depend on when the caller asked, turning the ordinary, expected race (the run finished while the adapter was starting up) into a hard error — precisely the failure mode a wait command exists to remove.

The consequence a caller must plan for is the mirror image: a mistyped run_id returns 0 immediately, indistinguishable from a fast, successful run. wait's 0 means "not running", never "existed and completed". A caller that needs the stronger fact must establish it separately — it launched the run itself, or it saw the id in list — and must not read a 0 as proof the run ever existed.

Liveness it cannot confirm

Scoped to wait --run-id only — see "The aggregate barrier — wait --all" below for how --all reuses this same conservative stance on every pass after its snapshot, but not on the snapshot step itself, which excludes an unconfirmed entry rather than waiting on it (a genuine, documented asymmetry with the single-run_id case below).

One case is neither live nor confirmed over: a matching record whose lock file cannot be probed at all (a directory in its place, a permission error, a rejected reparse point — the same "probe failed" case "The reaping safety invariant" above keeps apart from "confirmed stale"). Registry::entries reports that case as its own [Health::Unprobed] value (T-206), never folded into Stale — right for list, whose whole purpose is showing the operator exactly what was and was not confirmed, and behaviorally unchanged for the control clients inspect/cancel/kill/attest, which act only on [Health::Live] and so refuse on Unprobed exactly as they refuse on Stale (their message now tells the two apart, so no client asserts a death this case never established). Minting a positive "finished" from that same unconfirmed case would still be wrong for wait --run-id, whose 0 is a positive claim about a run's lifetime — so on this path wait probes through [Registry::probe_run] directly and does not read Entry::health at all, live or otherwise. (wait --all does read it — see below.)

So wait --run-id probes on its own path and keeps waiting on an unconfirmable entry rather than announcing a completion it never observed. A bounded caller still gets a definite answer when --timeout elapses (WAIT_TIMEOUT, honestly meaning "could not confirm completion in time"); an unbounded one keeps waiting for a real verdict. This is the same "unknown is not confirmed" stance prune takes when it refuses to reap an entry it could not probe.

The aggregate barrier — wait --all

wait --all [--label KEY=VALUE]... [--timeout <duration>] [--report-outcome] is the counterpart for a caller that does not hold one run_id but wants a barrier on every run — the typical orchestrator teardown sequence: cancel everything, wait for it all to be gone, then prune. It reuses the exact same periodic-probing mechanism (src/wait.rs::run_all), differing from --run-id only in what it tracks.

Repeated label filters combine with logical AND and are applied while forming the one initial snapshot: a record must carry every exact pair to enter the target set. Conflicting filters for one key therefore match no run. Labels are rejected with the by-id form.

Snapshot semantics, fixed rather than left ambiguous. At the moment --all starts, wait takes a single [Registry::entries] scan and fixes its target set to exactly the entries confirmed Health::Live at that instant, each identified by its record file (not by run_id — two entries can share one, since the registry never enforces uniqueness; see "Run id resolution" above). A run that registers after the snapshot is out of scope for this invocation and is never waited for — this is a deliberate, documented trade-off, the same "one clear rule beats a plausible-sounding but unbounded alternative" stance the "An unknown run_id reads as finished" section above already takes for the single-run case. The alternative — keep discovering new runs forever — would leave a caller unable to say when --all could ever return at all. A caller that wants to catch a run starting concurrently with the wait re-issues wait --all once this one returns.

Unprobed entries stay "not confirmed done" — once they are in the target set. On every later pass, a snapshot entry that re-probes Health::Live or Health::Unprobed stays outstanding — the exact same conservative stance the "Liveness it cannot confirm" section above documents for --run-id, applied per-entry instead of to a single target. An entry that re-probes Health::Stale, or that has vanished from the scan entirely (a clean exit deletes its own record), is dropped from the target set — the same "confirmed over" observation that lets an unknown run_id read as finished.

This conservative rule governs every pass after the snapshot, not the snapshot itself: because the target set is fixed to exactly the entries confirmed Health::Live at the snapshot instant (above), an entry that is only Health::Unprobed — not confirmed live — at that instant is excluded from the target set from the start, never entering it at all. This is a genuine, deliberate asymmetry with --run-id, which never excludes its one target this way (it always has exactly the id it was asked to wait for): a registry holding only unprobeable entries and no confirmed-live ones makes wait --all return 0 immediately, the same as an empty registry, even though none of those entries' liveness was actually established. A caller relying on --all as a teardown barrier must not read that 0 as proof every run in the registry was actually confirmed over — only that nothing was confirmed live at the moment the snapshot was taken.

Outcomes. Success (0) means every snapshot entry probed stale or vanished; a bounded --timeout that elapses with entries still outstanding is the same WAIT_TIMEOUT (112) --run-id uses, reporting how many snapshot entries are still outstanding and, when at least one of them was only Unprobed on the last pass, saying so rather than confidently claiming they are all still live. There is no aggregate CONTROL/ambiguity outcome: --all never resolves an id at all, so the duplicate-id question --run-id answers with CONTROL does not arise for it. Nothing is printed on success without --report-outcome, exactly like --run-id. With the flag, success prints one JSON array after the barrier clears, with one entry per original snapshot target in stable run_id then record-path order. Each entry has the same run_id/status/code/source/child_code shape as the single-run report and uses reported when its snapshotted JSONL locator yields a terminal runner_exit, or unknown with null outcome fields when the locator is absent, unavailable, or malformed. A timeout still prints no report and exits WAIT_TIMEOUT (112); outcome data never changes the barrier's exit code.

Lifecycle

• Create. run writes the record and takes the liveness lock before the child is spawned, so the entry exists for the whole run. Creating the registry is best-effort: if it fails, the runner warns on stderr and proceeds — the registry is control-plane discovery infrastructure, and losing it must never cost the child its faithfully forwarded exit code (AGENTS.md, "Exit-code fidelity").
• Remove. On a clean exit the entry is removed from the same teardown site as the container reap (clear_registration in src/run/teardown.rs), on every decided ending — a normal child exit, a --timeout, a local stop-signal cancel (Ctrl-C, on Unix a SIGTERM/SIGHUP, or on Windows a Ctrl-Break/console close/logoff/system shutdown, all of which the runner catches), or a control-plane cancel/kill — not just the happy path.
• Leak → stale. An abrupt death skips that removal by definition, leaving the record on disk — and, on unix, the control socket that record published (see "Reaping the control socket" above). The released lock makes the record detectably stale, per the section above. This is genuinely abrupt death only — a crash, a SIGKILL, an outer Job Object terminate — not an ordinary Unix SIGTERM/SIGHUP or a caught Windows console-control event (Ctrl-Break/console close/logoff/system shutdown), all of which the runner catches and turns into the clean removal above.
• Stale → reaped. prune is what finally clears such a leftover, deleting the record, its lock, and the socket directory together — only once it has confirmed the entry stale.

Troubleshooting

This is an operator's guide: symptom, what to look at, and where the normative answer lives. It does not restate the normative documents — docs/schema.md, docs/exit-codes.md, docs/registry.md, and docs/control-plane.md — it points at them. For the consumer/adapter walkthrough (preflight, launching, reading the stream, supervision, housekeeping), see docs/integration.md instead; this document is organized by symptom rather than by call sequence, and each entry below is deliberately short. On any disagreement between this document and one of the normative ones, the normative document is the source of truth.

Qualifying a host: doctor

Symptom. probe says the binary is compatible, but the first real run on this machine fails — or runs work on one host and not on another, and you want to know which part of the environment differs before spending a production run finding out.

Diagnose. Run the host qualification:

processkit-cli doctor          # human-readable
processkit-cli doctor --json   # one JSON line, for an adapter

doctor is the side-effecting counterpart of probe, and the difference is the whole point of having both. probe reads compile-time constants and the in-memory CLI tree: it proves this binary exposes the surface you need, spawns nothing, and touches no registry, container, or transport. doctor proves this host can actually run a contained process, by doing it: it performs a bounded scratch run of this binary's own harmless child (doctor --scratch-child, which sleeps briefly and does nothing else), drives that run as an ordinary control-plane client, and reports what it observed. A passing probe and a failing doctor is the normal shape of an environment problem.

The report is a list of facts, never one boolean:

Reading a negative verdict. doctor exits HOST_UNQUALIFIED (116) when a phase failed or a --require-* expectation was not met, and prints the report either way (see docs/exit-codes.md, "Qualifying a host: doctor"). The two cases are distinguishable in the report itself: failures names phases that did not work, mismatches names host properties that are not what you asked for. A failed phase keeps its evidence: the scratch directory is not deleted, and diagnostics_dir names it — it holds the scratch run's own JSONL stream, the runner's stdout/stderr, and a copy of the report. A qualified host leaves nothing behind at all.

Pinning what you need. The requirement flags gate the exit code and nothing else — the observed facts are reported identically with or without them:

processkit-cli doctor --json --require-abrupt-cleanup whole_tree
processkit-cli doctor --json --require-mechanism cgroup_v2
processkit-cli doctor --json --check-resource-controller --require-resource-controller

Each compares for exact equality against the value this host reports, and names both sides on a mismatch. --require-abrupt-cleanup in particular is not an "at least this strong" comparison: the three levels are platform facts (docs/platform-support.md), and this project publishes no ordering between them to compare against.

What it costs, and what it touches. One (or, with --check-resource-controller, two) short scratch runs of this binary against itself, in the real per-user registry the host uses — which is the point: a qualification of an isolated sandbox would qualify the sandbox. The whole check is bounded by --timeout (default 30s), and the scratch run and its child carry that bound themselves, so a doctor that is itself killed leaves nothing running behind it.

BACKEND (102) with a limit_hit event, often only on CI or under systemd

Symptom. run --max-memory <size> / --max-processes <n> / --cpu-quota <cores> exits BACKEND (102) immediately — no child output at all — even though the same command works locally without the flag, or works locally with it.

Diagnose. Read the --jsonl stream: a limit_hit event (naming which limit — memory / processes / cpu — in its limit field) precedes the container_failed (phase: "create") and terminal runner_exit (source: "container_error", code: 102). The limit_hit event, not the exit code, is what tells you this specific ending was a resource cap the platform could not apply — see docs/schema.md.

Why it happens. A whole-tree cap needs a real container. On Linux that means cgroup v2 at the real hierarchy root — a minimal, non-systemd init. It does not work under a systemd session/scope/service, inside an ordinary container (Docker/Kubernetes), or under typical hosted CI (including GitHub Actions' ubuntu-latest), because the controllers cannot be enabled there; the run fails fast rather than silently running unbounded. FreeBSD's process reaper still provides whole-tree normal containment, membership, and kill/teardown semantics, but it has no memory, CPU, or process-count cap support, so any cap request fails there too. macOS and non-FreeBSD BSD process groups, along with the Linux process-group fallback, have no whole-tree cap container at all, so any cap request fails the same way there too. See the resource-limit platform matrix for the separate FreeBSD process-reaper row and the distinct macOS/non-FreeBSD BSD process-group row, and docs/exit-codes.md for why this reuses BACKEND (102) instead of a dedicated code.

Fix. Either run somewhere the cap can actually be enforced (a Windows Job Object, or a real Linux cgroup v2 root), or drop the resource-limit flags — there is no partial/best-effort mode.

The honest fallback: cgroup_v2 → process_group

Symptom. On Linux you expected cgroup v2 containment (whole-tree teardown and process accounting) but observe process-group-only behavior instead — for example a descendant that left the process group via setsid/double-fork surviving an ordinary teardown, or a just-exited child still listed briefly in a post-kill member snapshot.

Diagnose. The run_started event's mechanism field (also echoed live by inspect --json's snapshot) reports which containment mechanism this specific run actually got — cgroup_v2 or process_group — never a promise based on the platform alone; that field alone tells you whether the fallback happened. Do not use abrupt_cleanup (also on run_started) to tell the two apart: it is a separate, OS-derived contract — whole_tree on Windows, direct_child_only on Linux, none on macOS/other Unix — sourced from the platform's parent-death-signal capability, not from which mechanism this run got. On Linux it reads direct_child_only whether the run got cgroup_v2 or fell back to process_group, so comparing it against mechanism tells you nothing about the fallback. See docs/schema.md and docs/control-plane.md.

Why it happens. Where cgroup v2 delegation is unavailable to the runner, it falls back to the POSIX process-group mechanism rather than claiming a cgroup it did not get — the same unavailability this document's first entry covers for resource limits, but here it is a silent, successful fallback instead of a hard failure, because plain containment (unlike a requested cap) has a working fallback. What the fallback actually costs is ordinary teardown/accounting strength, not extra abrupt-death coverage: if the runner itself dies abruptly, a cgroup does not automatically kill grandchildren either — only the direct child is covered, by the parent-death signal, under either mechanism. See README.md, "Platform matrix", for the per-mechanism guarantees.

A console window pops up for a detached run

Symptom. run --detach launches a console-based child on Windows and a new, unwanted console window appears (or flashes) even though nothing about the invocation looks interactive.

Diagnose. No JSONL event is involved — this is purely an OS behavior: Windows gives a console-allocating child a fresh console of its own whenever its parent has none. The detached runner itself has no console (it was launched with DETACHED_PROCESS), so any console-based child it starts gets one unless told not to.

Fix. Pass --create-no-window alongside --detach — it maps directly onto ProcessKit's Command::create_no_window() (the CREATE_NO_WINDOW creation flag; a no-op on non-Windows platforms). It defaults to off for an ordinary foreground run (so a bare run still behaves like a direct launch), but a detached run is exactly the case where passing it matters most. See README.md, "Windows console", and README.md, "Detached runs".

list shows an entry as unprobed

Symptom. list/list --json shows a registry entry's health as unprobed rather than live or stale, and you are not sure whether it is safe to delete by hand; or prune --json's tally keeps reporting a non-zero unprobed count across repeated runs instead of reaping those entries.

Diagnose. list's health field has three values, matching the same tri-state verdict prune/wait already use internally: "live", "stale" (confirmed dead — the liveness lock probed as released), and "unprobed" (the liveness lock genuinely could not be probed at all: the lock file would not open — a directory in its place, a permission error, a rejected reparse point — or the lock call itself errored). "unprobed" is a deliberately distinct, conservative verdict — "could not confirm liveness" is not the same claim as "confirmed dead" — and prune (and its non-destructive prune --dry-run preview) never reap an entry in this state, on every repeated run, until the probe itself can succeed. A control client (inspect/cancel/kill/attest) aimed at such an entry refuses with CONTROL (103), since it acts only on a confirmed-live entry — but its message, too, reports that liveness could not be probed rather than that the runner is gone (see the CONTROL (103) entry below).

A non-zero unprobed count in prune --json/prune --dry-run --json is not always the same set of things list shows you as unprobed, though: the tally is shared between this per-entry probe (one .json/.lock pair, the same one list reports on) and a second, independent pass over orphaned .lock files — a .lock with no .json sibling at all, invisible to list, which only ever walks .json records. So the count can include lock files list has no entry for at all, on top of any unprobed entries list already showed you. See docs/registry.md ("Discovery" for what list reports) and docs/registry.md for exactly which of the three probe outcomes prune reaps.

Fix. Run prune --dry-run --json first to see precisely what a real prune would reap (and what it would leave as unprobed) before running the destructive form. For an unprobed entry list already shows you, or for any excess the dry-run's tally reports beyond that, investigate the registry directory and its .lock files directly (the usual cause is a permissions issue or a path collision) rather than deleting registry files by hand.

CONTROL (103): the runner could not be reached

Symptom. inspect / cancel / kill / attest exits 103 and prints an explanatory line on stderr. For the by-run_id form this means the command did nothing to any run; cancel --all / kill --all are the exception — see "cancel --all / kill --all and a partial 103" below before assuming nothing happened.

Diagnose. stderr names which reason applied. Most of them mean the runner itself was never reached: a run_id the registry names nowhere (not_found) or names more than once ("An ambiguous run_id" below), plus the three described here, where an entry was found but no answer came back. The read-only verbs then add two refusals of their own below, where the target was reached and did answer. If you are diagnosing this from a script rather than by eye, re-run the same command with --error-format json, which prints the reason as a machine-readable kind (stale / unprobed / control_unreachable, plus not_found, ambiguous_run_id, ipc_deadline, incompatible_contract, and peer_identity_unsupported) instead of a sentence: a stale registry entry (the runner died abruptly, so the entry's record is left behind but its liveness lock has been released, detected before connecting), an unprobeable registry entry (the liveness lock could not be probed at all, so the runner is not confirmed gone — the message says liveness could not be probed and calls the entry unprobed, never "the runner is gone"), or died mid-conversation (the entry read live, but the runner exited between the liveness probe and the reply, or the connection closed before a complete response arrived). All three are bounded — no client hangs waiting for a runner that is not going to answer. list is the fastest cross-check for the first two without retrying the failing command, and it reports the same verdict the refusal did: a stale entry shows as stale, an unprobeable one as unprobed (see "list shows an entry as unprobed" above for what to do with that one — in short, do not hand-delete it). See docs/control-plane.md, "When the runner cannot be reached: a distinguishable result, never a hang", and the CONTROL (103) row of the reserved-band table in docs/exit-codes.md.

The read-only verbs add a refusal the three above cannot produce, and it is not a lost runner. If the message says the runner answered with a control-plane version this client does not read (kind: "incompatible_contract"), the runner is reachable and healthy: the exchange completed, and it is the answer that was rejected, because it declares a contract this binary does not implement — in practice a runner newer than the client you are running. inspect and attest each carry a version axis of their own, and either one can be refused this way — the same kind, a different contract, a different fix:

• inspect says "the runner answered with control-plane snapshot version …", naming the number that arrived and the range this build reads. Retrying will not help: inspect that run with a build that implements its snapshot version — for a newer runner, one at least as new as the binary that started the run.
• attest says "the runner answered with control-plane attestation version …", naming the number that arrived and the single version this build reads. There is no read-down range on that axis on purpose — a misread membership verdict is a security answer rather than a diagnostic — so retrying is equally useless: attest that run with a build that implements its attestation version.

cancel/kill cannot hit either refusal (their ack carries no version), and neither can list/wait/prune, which ask no runner for one, so in both cases the run itself is still fully controllable. processkit-cli probe --json reports the version of whichever binary you run, which is how you tell two installed builds apart (no preflight can report a runner's snapshot or attestation version — those numbers only arrive in its reply). See docs/control-plane.md, "Snapshot version: a newer runner's reply is refused, an older one is read" and "Attestation version", and docs/integration.md §6 ("An unreadable contract version").

Beyond that shared refusal, attest has one more of its own, and it is neither a lost runner nor a negative verdict. If the message says the runner could not obtain a kernel-authenticated identity for this client from the control transport (kind: "peer_identity_unsupported"), the runner is reachable and healthy: the exchange completed, and it declined to decide membership because a transport that cannot name the caller leaves it nothing to decide on — reporting an unproven member is the one answer it will not give. This is a refusal, never a "no": a decided non-membership is not a 103 at all but NOT_A_MEMBER (115), kind: "not_a_member" (the attestation is printed on stdout either way). Retrying will not help, because the capability is a property of the runner's platform and build rather than of the moment; rule it out at preflight instead, with processkit-cli probe --json --require-surface attest:peer-identity run against the runner's own binary — meeting it at runtime means that check was skipped, or the runner is a different build. No other command can hit it: inspect/cancel/kill/wait/list never ask the question, and the run itself is untouched and still going, since attest is read-only. See docs/control-plane.md, "attest", and docs/integration.md §6 ("A caller the runner cannot name").

wait does not share this code. The registry-only wait --run-id <id> never connects to a run's control transport, so "died mid-conversation" is not something it can hit, and a stale registry entry does not give it 103 either — only the ambiguous-run_id reason below does. A stale or missing entry makes wait exit 0, the same as a run that finished cleanly (the registry keeps no history, so "build-42 was never registered" and "build-42 finished a moment before you asked" read identically): do not take a 0 from wait as proof a stale-looking run_id was ever live. See docs/registry.md.

Not a run outcome. A 103 says nothing about how the target run itself ended (or whether it is still running) — for the by-run_id form it is purely "this client could not resolve or reach a single target run". Do not conflate it with the run-outcome codes (106–109, or the child's own code), which come only from the run's own process exit. (cancel --all / kill --all's 103 is different — see below.)

cancel --all / kill --all and a partial 103

Symptom. cancel --all or kill --all exits 103, but the JSON report it printed to stdout shows at least one target with "accepted": true — so, unlike the by-run_id form's 103 above, this run was acted on.

Diagnose. --all's 103 is a different fact from the by-run_id form's: it means "one or more targets in the confirmed-live snapshot could not be reached or did not acknowledge the command", not "nothing was found or reached". A snapshot with several live runs commonly has a mix — most targets ack cleanly while one becomes unprobeable, changes identity, or does not respond in time — and the aggregate exit code reflects that any failure occurred so an automated caller never mistakes a partial teardown for a complete one. Read the JSON report on stdout (not just the stderr tally) to see exactly which records failed and why; stderr on its own only gives the failure count. A duplicate run_id is not itself an aggregate failure because --all addresses each record path and endpoint independently. Likewise status: "already_gone" is non-error: the target ended after the snapshot, so accepted is false but teardown is already complete for it. See docs/control-plane.md, "cancel --all / kill --all", and the CONTROL (103) row of the reserved-band table in docs/exit-codes.md.

Fix. Re-running cancel --all / kill --all is safe: a target already ended is absent from the next snapshot (or already_gone if it ended during this one), and a target that failed for a transient reason (e.g. it was mid-exit) is retried. If a specific run_id keeps failing, use list --json or inspect --run-id <id> to see why (a stale entry, an unprobed one, or a genuine ambiguity — the same reasons the by-run_id sections above and below cover).

An ambiguous run_id

Symptom. inspect / cancel / kill / attest / wait --run-id <id> exits CONTROL (103) with an "ambiguous run id" message, even though you believe exactly one run with that id is alive.

Diagnose. The registry does not enforce run_id uniqueness at register time: two runs started concurrently with the same explicit --run-id are both written as independent, live entries. Every by-run-id client — including the read-only inspect and attest, and the registry-only wait — fails closed with CONTROL (103) the moment more than one live entry matches, rather than silently acting on whichever entry a directory scan happens to return first; run list --json and filter by run_id to see the duplicates directly. See docs/registry.md, "Run id resolution — ambiguity is a hard failure".

Fix. Keep run_ids unique among your own concurrently-live runs (a counter, a UUID, or any value your launcher does not reuse before the matching run has ended); there is no way to disambiguate after the fact other than avoiding the collision at launch time.

The child's terminal behavior degrades under the default pipe + echo

Symptom. Colors, progress bars, spinners, or other cursor-based rendering from the child look wrong, missing, or replaced with plain line-by-line output — even though the same command renders correctly when run directly in a terminal.

Diagnose. By default run gives the child pipe + echo, not a real inherited terminal: ProcessKit reads the child's stdout/stderr through pipes and this runner re-emits the bytes onto its own stdout/stderr. The child therefore sees no TTY on either stream, so any code path in it that checks isatty() (or equivalent) before drawing takes its non-interactive branch — this is the child's own, otherwise-correct terminal detection working as designed, not a bug in the runner's pump.

Fix. Pass --inherit-stdio for an interactive command: it hands the child the runner's own stdin, stdout, and stderr handles directly — no pump, no echo, no --capture-dir tee in this mode — so an existing terminal is preserved unmediated instead of proxied. It is mutually exclusive with --capture-dir, --create-no-window, --inherit-stdin, --stdin-file, --no-echo, --idle-timeout, and --detach (a detached run has no terminal to hand over in the first place); Ctrl-C behavior also becomes platform-dependent under this flag rather than the runner's own uniform cancelled/107 outcome. See README.md, "Standard I/O", for the full contract, including exactly how Ctrl-C is delivered in this mode on each platform.

See also

• docs/schema.md — the normative JSONL event schema.
• docs/exit-codes.md — the normative reserved exit-code band.
• docs/registry.md — the normative registry location, staleness signal, and reaping rules.
• docs/control-plane.md — the normative local transport, wire protocol, and inspect/cancel/kill/attest behavior.
• docs/integration.md — the consumer/adapter walkthrough, organized by call sequence rather than by symptom.
• docs/platform-support.md — what each platform guarantees, and which of those guarantees doctor confirms on the machine in front of you.

Integration guide for adapters

This is the walkthrough for a consumer of processkit-cli — an orchestrator or adapter (in particular the processkit-py CLI) that launches runs through this binary and reads its results back — rather than for a contributor to this repository (see docs/architecture.md for that audience). It ties together, in the order an adapter actually exercises them, the five normative documents that each cover one part of the compatibility surface on their own: docs/schema.md, docs/exit-codes.md, docs/control-plane.md, docs/registry.md, and docs/compatibility.md. This document does not restate their normative text — every concrete claim below is a pointer to, and a minimal worked example of, the contract those documents define; on any disagreement, the linked document is the source of truth.

1. Fail-closed preflight: probe (the binary), then doctor (the host)

Before launching anything through a candidate processkit-cli binary, verify it is compatible. probe is side-effect-free — it spawns no child and touches no registry or container — and prints one JSON report line to stdout:

processkit-cli probe --json \
  --require-schema-version 1 \
  --require-exit-code-band 100-119 \
  --require-surface run:--jsonl \
  --require-surface run:--capture-dir \
  --require-surface inspect:--json \
  --require-surface cancel:--run-id \
  --require-surface kill:--run-id

The report (one line, shown reformatted here):

{
  "probe_version": 1,
  "binary": "processkit-cli",
  "version": "0.2.2",
  "schema_version": 1,
  "exit_code_band": { "start": 100, "end": 119 },
  "surface": ["cancel", "cancel:--run-id", "inspect", "..."],
  "compatible": true,
  "mismatches": []
}

• Pin schema_version (--require-schema-version <N>) and the reserved exit-code band (--require-exit-code-band <start>-<end>) so a future breaking change is caught here, before a run, rather than by a JSONL parser or an exit-code table drifting silently out of sync.
• Pin the exact CLI flags the adapter is about to use with one --require-surface <token> per token (a bare subcommand name, or <subcommand>:--<long-flag>) — this is how an adapter confirms a flag it depends on (for example run:--capture-dir) actually exists on this build before passing it.
• Pin run:resource-summary if the adapter will read what a run consumed — peak memory, CPU, IO bytes, peak process count. Like the token below it this is a capability, not a spelling (note the missing --), and it says this build's run emits the terminal resource_summary event. Requiring it is the only way to learn that before a run: an older binary simply writes no such line, which an adapter would otherwise discover by finding it missing from a stream it has already finished collecting. The token guarantees the event, not any particular number in it — which measurements are populated follows the containment mechanism and, for memory and CPU on Linux cgroup v2, how the run ended, per docs/resource-limits.md. Read that matrix before building an adapter around a specific axis; pinning the token is not the same as learning a number will be there.
• Pin attest:peer-identity if the adapter will gate anything on containment membership (§4). It is the other capability rather than a spelling — note the missing -- — and it says this build can obtain a kernel-authenticated identity for a control-plane client on this platform, which is what makes attest able to answer at all. Requiring it turns "this platform cannot prove membership" into an ordinary fail-closed PROBE_INCOMPATIBLE (110) here, instead of a peer_identity_unsupported refusal in the middle of a job. Its presence is a guarantee; its absence withholds one rather than predicting failure, so an adapter that requires it is choosing not to depend on an unguaranteed capability.
• An unmet expectation makes probe exit PROBE_INCOMPATIBLE (110) with compatible: false and the concrete mismatches; a malformed --require-* argument (not an incompatibility, a bad flag) is the ordinary USAGE (100). A satisfied — or unrequested — surface exits 0.

This is a fail-closed contract: an adapter that skips the preflight (or silently proceeds after a PROBE_INCOMPATIBLE) re-introduces exactly the uncontained-launch hazard this project exists to prevent. See src/probe.rs and the normative exit-code table in docs/exit-codes.md.

The report's shape is published as a JSON Schema with a golden fixture — fixtures/schema/cli/probe.schema.json and probe.jsonl — so an adapter can validate what it parsed instead of re-deriving the shape by hand. Every machine-readable output in this guide has such a pair; see fixtures/schema/cli/README.md for the full table, and docs/compatibility.md, "Machine-output schemas", for why some of these outputs carry no version field of their own (the probe report's probe_version, the inspect snapshot's snapshot_version, the failure envelope's error_version — §7 — the attestation's attestation_version — §4 — and the qualification report's doctor_version — below — are the five that do).

probe --print-schema is a separate, simpler mode on the same subcommand: it prints this binary's embedded JSONL event-schema document instead of the report above and exits 0, so an adapter that only needs the schema for its own version — no clone, no tag to match — can fetch it offline without a compatibility check. It cannot be combined with any --require-* flag: that combination is rejected as an ordinary USAGE (100) parse error, never a silent skip of the requested checks, so it can never produce a false "ok" on an invocation that also asked probe to verify expectations. See docs/schema.md, "Getting the schema without a git checkout".

Qualifying the host: doctor

A passing probe says the binary you found is the one you need. It does not say this machine can run a contained process — by construction, since proving that would mean running one, and a preflight that spawned a child would not be a preflight. The two claims come apart in practice: a registry directory that cannot be created or is not owner-only, a containment mechanism the kernel will not hand out, a local IPC endpoint that will not bind. Each of those passes every --require-* check above and fails the first production run.

doctor closes that gap by doing the thing:

processkit-cli doctor --json   --require-abrupt-cleanup whole_tree   --check-resource-controller --require-resource-controller

It performs a bounded scratch run of this binary's own harmless child (doctor --scratch-child), drives that run through the ordinary control plane (inspect, cancel, terminal wait), confirms teardown left nothing, and reports the facts it observed — the registry directory and its owner-only protection, the containment mechanism and abrupt-cleanup level this host really gives a run, the transport round-trip, a confirmed-empty cleanup, and per-phase timings. On success it leaves nothing behind; on a failed phase it keeps a diagnostics directory and names it in the report (diagnostics_dir).

Where it belongs in an adapter's flow: once per host, at setup or install time, not before every run. It is the counterpart of the probe above, on the other axis —

The requirement flags gate the exit code only; the report carries the observed facts either way, so an adapter can act on the code and still log everything the qualification saw. --require-resource-controller needs --check-resource-controller alongside it — a requirement about a fact this invocation never observed is refused as a USAGE (100) rather than guessed.

doctor --json's shape is published like every other machine-readable output here: fixtures/schema/cli/doctor.schema.json and doctor.jsonl. See docs/troubleshooting.md, "Qualifying a host: doctor", for reading a negative verdict, and docs/exit-codes.md, "Qualifying a host: doctor", for why 116 is its own code.

2. Launching a run

The recommended invocation for an adapter:

processkit-cli run \
  --run-id build-42 \
  --jsonl .processkit/build-42.jsonl \
  --capture-dir .processkit/build-42/capture \
  --env-clear \
  --env PATH="$PATH" \
  --env-remove CI_SECRET_TOKEN \
  --timeout 10m \
  --grace 5s \
  -- dotnet build

• --jsonl <file> is the only place lifecycle events are written — never stdout, so the child's own stdout/stderr stay pristine. Give every run a distinct path; the file is created or truncated at the start of the run.
• --run-id <id> is the identifier inspect/cancel/kill/attest later match on — supply one you control (rather than the generated default) so the supervision step (§4) has a stable handle. Two live runs sharing one --run-id is legal but makes every supervision command against it fail closed as ambiguous (§4, §6) — keep run ids unique across an adapter's own concurrently-live runs.
• --capture-dir <dir> additionally tees stdout/stderr to <dir>/stdout.log / <dir>/stderr.log with a byte count, a SHA-256, and explicit truncation/write-error flags per stream (the output_captured event, §3) — use this when the adapter needs the transcript as a file rather than (or in addition to) the live echo.
• --no-echo suppresses the runner's own live retransmission of the child's stdout/stderr — the exact "pure noise" an adapter reading results from --jsonl/--capture-dir alone does not want interleaved with its own output. The pipe, --capture-dir, and the JSONL stream are all unaffected; it conflicts with --inherit-stdio, which runs no pump to suppress in the first place.
• --detach returns as soon as the run has provably started instead of blocking for its whole duration — the "launch and let go" shape, for an adapter that supervises out of band (§4) rather than by staying the runner's parent. It re-spawns the CLI detached (a new session on Unix, a DETACHED_PROCESS on Windows) and waits only until that copy has registered the run and written run_started to --jsonl, so on return the run is already visible to list/inspect/wait. An adapter that captures the launch command's output (subprocess.run(..., capture_output=True)) gets end-of-file when the call returns, not when the run ends: the detached runner keeps none of the caller's pipes open. The exit code changes meaning under this flag and only under it: it reports the start — 0 once the run started, or the same reserved code the failure would have produced in the foreground (a missing program is still SPAWN 101) — never the child's own code, which stays in the terminal runner_exit event (§3). Adapters that need the child's result must read it there, or via wait plus the event stream. It conflicts with --inherit-stdio/--inherit-stdin (nothing interactive survives detaching) and implies --no-echo's discarding sinks, while --jsonl, --capture-dir, --idle-timeout, and --snapshot-interval behave exactly as they do in the foreground. The detached runner's own stderr is null, so --jsonl is the only channel that reports anything — including a failed member read, which is why that failure is a flagged event rather than a warning (§3). On Windows, pair it with --create-no-window for a console child: the detached runner has no console to lend it, so the OS gives the child one of its own. See docs/exit-codes.md, "Detached runs".
• --env-clear / --env-remove <KEY> / --env-file <file> / --env <KEY=VALUE> give the adapter control over the child's environment, applied in that fixed order — clear, then remove, then files, then explicit sets — regardless of flag order on the command line, so an explicit --env always wins on a duplicated key. See README.md, "Environment", for the full precedence rule.
• --run-id-env <KEY> hands the child the run's final id — the --run-id above, or the generated one when the adapter did not supply an id — in the named environment variable, applied after every flag in the previous bullet. This is the alternative to minting an identity adapter-side and passing it twice (--run-id <id> --env KEY=<id>): one value, no second copy to drift, and it is the only way to give the child a runner-generated id, which is otherwise not knowable until the run has already started. It is opt-in (no key is injected by default) and it composes with --detach — the detached copy is re-spawned with an explicit --run-id for the id its caller already reported, so the child sees the same value the caller has. An explicit --env <KEY>=… for the same key is refused as a USAGE (100) parse error rather than silently overridden — "the same key" by the platform's own rule, so on Windows an --env entry differing from <KEY> only in case is that same refusal. Treat the value as correlation data only: it identifies a run, it does not authenticate one, and any process able to set an environment variable can forge it.
• --max-memory <size> / --max-processes <n> / --cpu-quota <cores> cap the run's whole process tree. Enforcement needs a real container (Windows Job Object or Linux cgroup v2 at the real hierarchy root); where the platform or environment can't apply a cap the run fails fast with a limit_hit event (§3) and BACKEND (102) rather than running silently unbounded — so an adapter that depends on a cap must treat a limit_hit as a hard failure, not a warning. See the resource-limit platform matrix, which has a separate FreeBSD process-reaper row — normal whole-tree containment, membership, and kill/teardown, but no memory/process/CPU caps or resource_summary accounting — and the distinct macOS/non-FreeBSD BSD process-group row; cgroup v2 is often unenforceable under systemd/containers/typical CI, and the Linux --max-processes caveat.
• Command-line redaction. run_started's command field is redacted by default: the raw argv is not recorded, only a one-way SHA-256 fingerprint (argv_sha256) and a classified worker-shape hint (both derived from argv but unable to reveal it) — filled on every run whether or not --argv-raw is given. Pass --argv-raw only when the adapter's own storage for the resulting JSONL is at least as trusted as the command line itself; do not default to it. See docs/schema.md ("Command redaction") for the exact fingerprint encoding, which an adapter reproducing the digest independently must match byte for byte. That encoding is defined over each element's canonical bytes, which are platform-specific for an argument that is not valid Unicode (Unix: the argument's own bytes; Windows: the WTF-8 encoding of its UTF-16 code units) — an adapter that hashes a UTF-8-decoded string instead will agree on every ordinary command line and disagree on exactly those. The same case is the one where --argv-raw's argv array carries an escaped element rather than the argument verbatim; an adapter that re-runs or compares a recorded argv must decode it. An adapter that stores what it read must also check its sink: an escaped element is the only string value in this schema that can contain U+0000, and while the JSONL line itself stays NUL-free text (the wire form is the ordinary six-character escape), a decoded value handed to a sink that forbids NUL is rejected or truncated — PostgreSQL refuses a jsonb document containing it, so an adapter ingesting whole event lines into jsonb loses the entire event rather than one field. All three rules are in docs/schema.md.

run is not shell-free by accident — everything after -- is the literal <program> <args...>, with no shell to expand or reinterpret it; an adapter that needs shell features passes the shell as the program explicitly.

3. Reading the JSONL stream

--jsonl accumulates one JSON object per line as the run proceeds; parse it as newline-delimited JSON, dispatching on each object's event field. A minimal reader:

import json

with open(jsonl_path, encoding="utf-8") as f:
    for line in f:
        evt = json.loads(line)
        if evt["schema_version"] != 1:
            raise IncompatibleSchema(evt["schema_version"])
        handle(evt["event"], evt)

Pin schema_version here too (or rely on the probe preflight in §1 to have already ruled out a mismatch) — never assume a fixed shape without checking it.

Or let the binary read it back for you. events is the first-party reader of the same stream, so an adapter that only needs to show a run's story — or to check one — does not have to write the loop above at all:

processkit-cli events --run-id build-42               # rendered for a human
processkit-cli events --run-id build-42 --follow      # ... as it happens
processkit-cli events --file "$jsonl" --json          # the runner's own bytes
processkit-cli events --file "$jsonl" --validate      # conformance check

It resolves the stream through the registry (--run-id, the same jsonl locator list --json publishes in §5) or reads a path directly (--file, for a stream whose registry record is already gone — a clean exit deletes its own record — or one this registry never knew about). Exactly one of the two is required and they are mutually exclusive; there is no precedence rule, so passing both is a USAGE (100) error. Like list/wait it is read-only: registry opened read-only, no control-plane round trip, nothing mutated.

Three properties matter for an adapter:

• --json is a pass-through, not a re-serialization. Each line is emitted byte for byte as the runner wrote it, so a field a newer runner added survives the trip — the pipeline processkit-cli events --file … --json | your-parser is exactly as lossless as reading the file yourself. A line that is not JSON is reported on stderr instead of emitted, so stdout stays parseable JSONL.
• --follow is bounded by the run, never by an invented deadline. It returns at the terminal runner_exit, or once the registry reports the run over and the stream has stopped growing — the abrupt-death case, explained on stderr rather than passed off as a complete stream. It hands out only complete lines, so a half-written event is never parsed as an event.
• --validate is a conformance gate. It checks every line against the schema document this binary embeds — the same one probe --print-schema prints in §1 — reports each violation by line number and by what it violated, and exits EVENTS_INVALID (114) if any line fails, 0 if none does. An unreadable stream is still SETUP (111) and a --run-id naming no single stream is still CONTROL (103), so a fixture-checking CI job can tell "invalid" from "could not be checked". This is the recommended way for an adapter to keep its own recorded fixtures honest against the runner version it targets.

Ordering (normative: docs/schema.md). A normal run emits, in order:

1. run_started — the child was spawned; carries run_id, root_pid, containment mechanism, the abrupt_cleanup tri-state, and the redacted command.
2. members_snapshot (reason: "spawn") — the container's members at that point. Exactly one by default; a run started with --snapshot-interval <duration> emits additional members_snapshot events (reason: "interval") on that cadence, all of them after this one and all of them before step 3 — never inside the teardown pair. Route by event type and treat the count as open-ended: within a schema version an adapter must not assume an event type it knows occurs only once (the full list of what a reader must tolerate within a version is in docs/compatibility.md). Every one of these events carries read_error; when it is true the read failed and members is an empty fallback, not a confirmed-empty tree — check the flag before drawing a conclusion about the tree from an empty array.
3. Either the natural-exit path (root_exited, cleanup_started, cleanup_finished) or a runner-imposed ending's reason event (timeout, cancelled, or killed) followed by the same cleanup_started / cleanup_finished pair. Treat a zero/empty cleanup_finished snapshot as confirmed only when both read_error and kill_error are false: a failed hard kill can be followed by a successful empty member read without establishing that the container itself was left clean.
4. resource_summary — what the tree consumed, inserted between the ending event of step 3 and its cleanup_started. Exactly one, on every run that spawned the child: no flag turns it on and no platform turns it off (a limit_evidence, when a cap was requested, sits immediately before it). Every measurement is independently nullable, null means "this mechanism, at this read point, does not account for it" rather than zero, and read_error must be checked before concluding anything from a null. The event's presence is guaranteed; its contents are not — on Linux cgroup v2 an ordinary run whose child exited on its own reports all five as null with read_error: false. See docs/schema.md and the platform matrix in docs/resource-limits.md.
5. output_captured, only when --capture-dir was set.
6. runner_exit — always the last line, the terminal event of every run, including a runner failure before the child ever started (in which case spawn_failed or container_failed precedes it instead, with no run_started and no resource_summary — there was no tree to measure).

Telling outcomes apart. Two signals distinguish how a run ended, and an adapter should use both together: the process's own exit code (fastest to check, no parsing needed) and the terminal runner_exit event's source and code fields (authoritative — see docs/exit-codes.md, "Why a band is not enough on its own"):

Only source: "child_exit" carries a non-null child_code; every other source means the child's own exit code was never produced or is not what code reports, and child_code is null. See the full field reference in docs/schema.md and the exit-code contract in docs/exit-codes.md.

Telling the two readings of a reserved-band code apart without opening the stream. The table above is the authoritative answer, and it costs a file read after every call: a 106 is the runner's TIMEOUT or a child that happened to exit 106, and only runner_exit.source settles it. There is a cheaper answer for the common case — and it is why this guide offers no terminal receipt file (§8). Under the global --error-format json (§7), a runner-owned ending prints exactly one envelope line on stderr and a child's own exit prints none, so the envelope's presence — not the numeric code — separates the two readings:

processkit-cli --error-format json run --run-id build-42 \
  --jsonl .processkit/build-42.jsonl --no-echo -- ./build.sh 2>build-42.err
rc=$?
# rc=106, no envelope line in build-42.err -> the child itself exited 106
# rc=106, one envelope line in it          -> {"error_version":1,"code":106,"kind":"timeout",...}

Test for the envelope's presence, not for an empty file. Even with the echo suppressed, stderr may carry processkit-cli: warning: … prose lines — a registry that could not be opened, event logging that switched itself off, a member read that failed. Those are not envelopes and not failures, and they keep their prose in both modes (see docs/exit-codes.md, "What the envelope does not cover"), so an adapter that reads an empty file as "the child's own code" will misread a genuine 106 the moment any harmless warning appears. Look for the one line that parses as JSON carrying error_version: there is at most one per invocation.

The envelope's kind is spelled exactly like the source column of the table above — every row of it but child_exit, which is by definition the reading that prints no envelope — so the two channels need no separate vocabulary. --no-echo is what keeps the child's own bytes off the runner's stderr, and it is the only flag that does — --capture-dir is an independent axis that files a transcript without suppressing anything, so pass it alongside --no-echo when the child's output is still wanted (the pump stays wired either way, so the transcript is complete). With the echo left on, the envelope is still emitted — it is the runner's own final stderr line — but the child's stderr is interleaved with it, which is one more reason to match on the line rather than on the stream as a whole.

This does not make the stream optional, and it is not a second outcome artifact. --jsonl is required on every run, the envelope reports only the runner-owned endings, and everything else a supervisor reads — the containment mechanism and abrupt_cleanup level, root_pid, the tree snapshots, the capture accounting — lives in the stream and only there.

4. Supervising a live run: inspect / cancel / kill / attest / wait

Once a run has started (its run_id is known — supplied at launch, per §2), an adapter can query, steer, and wait for it while it is still live. Every command resolves the target purely by run_id through the per-user registry — never by PID. This is also the whole supervision story for a run launched with --detach (§2): a detached run is an ordinary run in the registry, and these five commands are how an adapter that is no longer its parent steers it — alongside events (§3), which reads that run's stream back without contacting it at all:

processkit-cli inspect --run-id build-42 --json
processkit-cli cancel  --run-id build-42
processkit-cli kill    --run-id build-42
processkit-cli attest  --run-id build-42 --json
processkit-cli wait    --run-id build-42 --timeout 10m

The first four reach the live runner over the local control plane described normatively in docs/control-plane.md; wait does not contact the runner at all and is described in docs/registry.md, "Waiting — wait".

• inspect is read-only: it prints a snapshot (mechanism, root_pid, started_at, the current members) to stdout and changes nothing — as JSON with --json (shown above), or a human-readable rendering by default.
• cancel ends the run through the same soft-stop → grace → hard-kill teardown a --timeout or a local Ctrl-C drives, exiting the run with CONTROL_CANCELLED (108).
• kill hard-kills the whole tree immediately — no soft stop, no grace — exiting the run with CONTROL_KILLED (109).
• attest answers one question about the calling process: is it inside this run's container? The runner decides it from the kernel's own record of who opened the control connection — there is no --pid and no way to ask about any other process — so a member answer is a containment fact rather than a string the caller carried. This is what turns an adapter's "the caller belongs to run X" convention into a runner-checked invariant: verdict member exits 0, not_a_member exits NOT_A_MEMBER (115) — a decided answer, deliberately not a CONTROL (103) — and peer_identity_unsupported exits 103, the fail-closed refusal a platform that cannot name its callers gives instead of an unproven "ok" (pin attest:peer-identity at preflight, §1, to rule that out up front). The attestation is printed on stdout for every verdict, including the failing ones, and carries its own attestation_version (§1) — this answer's contract axis, independent of inspect's snapshot_version. The client reads it strictly: a reply declaring any number other than the single one this build implements is refused with CONTROL (103) and kind: "incompatible_contract" (§6) instead of being read as a verdict its sender never promised, because unlike a snapshot this answer is one an adapter gates access on — there is deliberately no read-down range. Read mechanism if you need to know how strong the containment behind a member answer is; nested runs, the per-mechanism scope, and why this axis has no read-down range are covered in docs/control-plane.md, "attest" and "Attestation version".
• wait blocks until the run is no longer live and exits 0. It is the answer for an adapter that is not the runner's parent — one that restarted, or that supervises runs another process launched — and so has no child process to wait on. It prints nothing (the exit code is the answer), never touches the run, and needs no control endpoint, so it also works for a run whose transport never came up. Adding --report-outcome makes the single-run form print one JSON object, while the --all form prints one JSON array in stable snapshot order, naming how each run ended — status reported with the terminal event's code/source/child_code, or status unknown with all three null when the outcome could not be established — without changing any of the exit codes below. See docs/registry.md, "Waiting — wait".

Each of these outputs has a published JSON Schema and golden fixture under fixtures/schema/cli/: inspect.schema.json (the single snapshot and the --all array), control-ack.schema.json (the cancel/kill ack and the --all report array), attest.schema.json (the attestation), and wait.schema.json (--report-outcome in either single-run or aggregate form).

Both mutating verbs' outcomes are also written to the target run's own --jsonl stream (a cancelled/killed event with source control_cancel/control_kill, and the matching terminal runner_exit), so an adapter watching that stream sees the command take effect even without reading the cancel/kill client's own ack.

Tearing down everything at once: --all (T-217). cancel --all / kill --all (mutually exclusive with --run-id, one of the two required) are the aggregate counterpart to the by-run_id form above: instead of one named run they act on every run confirmed live in a snapshot taken when the invocation starts, applying the identical per-run mutation to each, and print a single JSON array on stdout — one {"run_id":...,"accepted":...} entry per snapshot target — instead of one ack. An adapter driving a full environment teardown (e.g. before shutting down its own process) typically issues cancel --all in place of a loop over individually-known run_ids, then wait --all / list --json / prune to confirm the fleet is actually gone. See docs/control-plane.md, "cancel --all / kill --all", for the exit-code and report contract — it differs from the by-run_id form's 103 in the note right below.

Waiting for a run an adapter did not launch. The typical shape — cancel a run, then confirm it is really gone before releasing the resources it held:

processkit-cli cancel --run-id build-42          # 0: the runner acked
processkit-cli wait   --run-id build-42 --timeout 30s
case $? in
  0)   ;;                    # the run is over; its own exit/JSONL say how it ended
  112) ;;                    # still live at the deadline — the run was NOT touched
  103) ;;                    # ambiguous run id: more than one live run uses it (§6)
esac

• 0 means "not running". It is also what an unknown run_id returns, on purpose: a clean exit deletes its own registry entry, so "never registered" and "already finished and cleaned up" are the same observation, and failing on the second would turn the ordinary "it finished while I was starting up" race into an error. The flip side an adapter must respect: a typo'd run_id also returns 0, so never read wait's 0 as proof the run existed — establish that from the launch itself or from list (§5).
• WAIT_TIMEOUT (112) is the waiter's deadline, not the run's: the run was left running and untouched, and is still going. Do not confuse it with the run's own TIMEOUT (106) in §3's table, which means the runner tore the tree down. Retrying the same wait is a reasonable response to a 112.
• CONTROL (103) here means only one thing — an ambiguous run_id (§6); wait has no runner to fail to reach.
• Without --timeout, wait blocks indefinitely. Prefer an explicit deadline in an adapter, so a supervisor never inherits an unbounded wait.

CONTROL (103) is the one exit code all five of these clients' by-run_id form can return, and for all five the usual reason is the same: the command could not be resolved to the single target run. Two further reasons belong to the read-only verbs, where the target was resolved and reached and did answer. The first is shared by both of them: a reply declaring a contract version this client does not read is refused rather than acted on — inspect's snapshot_version (see docs/control-plane.md, "Snapshot version: a newer runner's reply is refused, an older one is read") or attest's attestation_version (ibid., "Attestation version"). The second is attest's alone: it was answered peer_identity_unsupported — the runner could not name the caller, so it declined to decide. attest's decided negative is not a 103 at all but NOT_A_MEMBER (115). See §6 for the concrete situations that produce a 103, those included. cancel --all / kill --all reuse the same code for a different reason — one or more snapshot targets failed, not "no single target run" — see the --all paragraph above and docs/control-plane.md.

5. Housekeeping: list / prune

list and prune scan the registry directly rather than reaching a specific live run, and are the tools for an adapter that manages many runs or wants to clean up after abrupt failures — see the normative "Discovery" and "Reaping" sections of docs/registry.md.

processkit-cli list  --json   # every registered run, whatever its health
processkit-cli prune --json   # reap only the confirmed-stale entries

• list --json prints one JSON object per registry entry (run_id, health, started_at, hint, argv_sha256, endpoint), sorted deterministically. argv_sha256 and hint are the same redaction-safe command identification the run_started event carries (§3) — the full 64-character digest here, so an adapter can join a registry entry to the events of the run that wrote it, or group several live entries by "same command" without ever handling a command line. Both are null on a record written before those fields existed, and hint is null for the common case of a command matching no known worker shape. Health is live, stale (confirmed dead — no live holder found), or unprobed (the liveness lock could not even be opened, e.g. permission denied — a distinct, additive value: liveness is unknown, never printed as the confirmed-dead stale). All three are listed, never hidden — a stale entry (a leftover from a runner that died abruptly) is exactly what an operator or adapter wants visible here, and an unprobed one is exactly the case where guessing would mislead.
• prune --json deletes only entries it can confirm are stale, printing a tally: {"pruned":N,"live":N,"unprobed":N,"orphaned_locks":N}. A live run is never touched, and an entry whose liveness could not even be probed is left in place rather than guessed at — see "The reaping safety invariant" in docs/registry.md. On unix each reaped entry also takes with it the private control-socket directory that record published, so an abruptly-killed run leaves no pkc-… litter in the temp directory either; the tally fields are unchanged (that socket is counted by its own entry's pruned). Worth scheduling if your adapter starts many runs — see "Reaping the control socket" in docs/registry.md.

Both are read-only with respect to any live run's control transport; neither carries the "could not reach the target run" failure modes of §4.

Their machine-readable shapes are published too: fixtures/schema/cli/list.schema.json (one entry object per line) and fixtures/schema/cli/prune.schema.json (the plain tally and, as #/$defs/dryRunReport, the --dry-run form with its candidates list), each with a golden *.jsonl fixture beside it.

6. Typical errors

Every distinction in this section is available as a machine-readable value, not only as prose: run any of these commands with the global --error-format json and the failure prints one bounded JSON object on stderr whose kind names exactly the case below (stale, unprobed, ambiguous_run_id, incompatible_contract, …). The kind column is noted per bullet; §7 has the full contract.

• Stale registry entry. (kind: "stale") The runner behind a run_id died abruptly (crash, SIGKILL, a parent's Job Object terminate); its record is left behind but its liveness lock is released. inspect/cancel/kill/attest detect this before connecting and report it as a CONTROL (103) failure with an explanatory message on stderr — never a hang, and never silently treated as live. list still shows the entry (marked stale); prune is what removes it. An ordinary Unix SIGTERM/SIGHUP, or a Windows Ctrl-Break/console close/logoff/system shutdown, is not in this class: the runner catches those signals/events and runs the full cancel teardown (a cancelled event, the cleanup pair, runner_exit cancelled/107, and removal of the registry entry), so stopping a run with kill <pid> (Unix) or a closed console (Windows) leaves neither a stale entry nor a surviving descendant.
• Unprobeable registry entry. (kind: "unprobed") The entry's liveness lock could not be probed at all (permission denied, a rejected symlink/reparse point, a non-regular file in its place), so nothing about the run is confirmed either way. This is the same CONTROL (103) refusal — inspect/cancel/kill/attest act only on a confirmed-live entry — but it is reported honestly as unprobed, not as a gone runner; list shows the same entry as unprobed and prune leaves it in place. Investigate the registry directory rather than deleting the record by hand (see docs/troubleshooting.md).
• Died mid-conversation. (kind: "control_unreachable", or "ipc_deadline" when a bounded window elapsed instead) The registry entry read as live, but the runner exited between the liveness check and the reply reaching the client — the connect fails, or the connection closes before a complete response. Also a bounded CONTROL (103) failure, never a wedge: every wait in the control plane (connecting, and the request/response exchange) is deadline-bounded.
• Ambiguous run_id. (kind: "ambiguous_run_id") The registry does not enforce run_id uniqueness; if more than one live entry matches, every by-run-id command — the read-only inspect, attest, and wait included — fails closed with CONTROL (103) rather than guessing which entry the scan happened to return first. Keep run_ids unique among an adapter's own concurrently-live runs (§2) to avoid this entirely.
• An unreadable contract version (inspect and attest). (kind: "incompatible_contract") The runner was reached and answered, but the reply declared a contract version this client does not read, so it was refused instead of being acted on under semantics its sender never promised. Both read-only verbs can hit this, each on its own version axis: an inspect reply carrying a control-plane snapshot_version outside the range this client reads — newer than the version it implements, or older than the version it still decodes — and an attest reply carrying an attestation_version other than the single one this client reads (that axis is read strictly, with no range, since a misread membership verdict is a security answer rather than a diagnostic; §4). Also a CONTROL (103), with a message naming the version that arrived and the version — or range — this build reads. Unlike the four above it says nothing about the run's liveness: the target is registered, live, reachable, and healthy, and the run stays fully controllable, since cancel/kill acks carry no version and wait/list ask the runner for nothing. Do not treat it as a lost runner or retry it; re-run the same command with a build that implements the runner's version of that contract — for inspect, its snapshot version (for a newer runner, a build at least as new as the binary that started the run); for attest, its attestation version. See docs/control-plane.md, "Snapshot version: a newer runner's reply is refused, an older one is read" and "Attestation version", and docs/compatibility.md, "Machine-output schemas".
• A caller the runner cannot name (attest only). (kind: "peer_identity_unsupported") The runner was reached and refused to decide membership, because its transport could not supply a kernel-authenticated identity for the connecting process. Also a CONTROL (103), and for the same reason as the bullet above: an answer that cannot be trusted is withheld rather than guessed — here in the safe direction, since the alternative would be reporting an unproven member. It says nothing about the run's liveness or about membership. Rule it out at preflight by requiring attest:peer-identity (§1); meeting it at runtime means that check was skipped or the runner is a different build.
• A decided non-membership is not in this class. (kind: "not_a_member", exit NOT_A_MEMBER 115) When attest reports that the caller is not in the run's container, nothing failed: the target was resolved, reached, and answered. It has a code of its own precisely so an adapter can tell "the runner says no" (deny the request) from "no runner said anything" (investigate, or retry). Never fold it into the 103 handling above.
• CONTROL-class exit codes are not run outcomes. A 103 from the by-run_id form of inspect/cancel/kill/attest/wait describes a failure on the client's side of the exchange — it could not resolve or reach a single target, or (the two read-only cases above) could not read or obtain the answer it asked for — and says nothing about how the target run itself ended (or is still running). Do not conflate it with the run-outcome codes in §3's table (106–109, or the child's own code); those come only from the run's own process exit and its runner_exit event. The same separation applies to WAIT_TIMEOUT (112): it is the waiting client giving up, never the run being stopped (§4). cancel --all / kill --all's own 103 is the one exception where the code can coincide with some targets having genuinely been acted on — see the --all paragraph in §4.
• A --detach exit code is not a run outcome either. run --detach's 0 means "the run started", not "the child succeeded", and its non-zero codes mean "the run never started" — carrying the same reserved code the failure would have produced in the foreground. An adapter that branches on a detached launch's exit code as if it were the child's result will read every long-running failure as a success; the child's outcome is in the terminal runner_exit event (§3), reached after wait (§4). See docs/exit-codes.md, "Detached runs".
• SETUP (111) vs. INTERNAL (104). (kind: "setup" versus "internal"; an unreadable registry narrows further to "registry") A run that could not write its --jsonl/--capture-dir, or open a --stdin-file, fails closed with SETUP (111) — an ordinary, usually-actionable environment problem (bad path, permissions), not a runner bug. INTERNAL (104) is reserved for a genuine invariant violation in the runner's own logic. See "Setup failures vs internal faults" in docs/exit-codes.md.

7. Machine-readable failures: --error-format json

Everything in §6 is a real distinction the CLI already makes — but by default an adapter can only read it as English on stderr, because the exit code is coarse: one CONTROL (103) covers six of those bullets at once — eight kind values in all, since the "died mid-conversation" bullet is two of them (control_unreachable and ipc_deadline) and not_found, a run id the registry names nowhere, gets no bullet of its own above. The global, opt-in --error-format json publishes the distinction instead:

processkit-cli --error-format json inspect --run-id build-42
# stderr, exactly one line:
# {"error_version":1,"code":103,"kind":"stale","operation":"inspect",
#  "run_id":"build-42","retryable":false,"message":"cannot inspect run `build-42`: …"}

• Opt in wherever it is convenient. The flag is global: it parses before or after the subcommand, and every subcommand honors it. Pin it in the preflight like any other flag — --require-surface inspect:--error-format (§1).
• Branch on kind (and code), never on message. error_version, code, kind, operation, run_id, and retryable are the contract; message is free text that may be reworded in any release.
• kind maps onto §6. stale, unprobed, ambiguous_run_id, control_unreachable, ipc_deadline, not_found, and the two refusals incompatible_contract and peer_identity_unsupported — those eight are the ones that exist to split the single CONTROL (103) — plus not_a_member (the decided verdict, 115), host_unqualified (the other decided verdict, 116, and the one about the host rather than a run — §1), registry/setup/internal, wait_timeout, events_invalid, probe_incompatible, and — for a failing run — the terminal runner_exit event's own source spellings (spawn_error, container_error, timeout, cancelled, control_cancel, control_kill, output_overflow). Unrecognized value? Fall back to code; the vocabulary grows additively.
• stdout is untouched. The envelope is on stderr, so an adapter can leave the flag on for every invocation without any risk to the JSON it parses from stdout — including for a command that prints a report and then fails, such as probe --json exiting 110 or inspect --all --json exiting 103.
• The default is unchanged. Without the flag, stderr is byte-for-byte the prose every earlier release printed.
• One documented gap. clap's parse-time usage errors (exit USAGE, 100 — an unknown flag, a malformed duration, a missing subcommand) stay human-readable in v1: they happen before the binary knows what it was asked to do, so there is no operation to name. Use the §1 preflight to establish that a flag exists before using it. Every post-parse failure is covered.

The shape is published like every other machine-readable output in this guide: fixtures/schema/cli/error.schema.json with a golden error.jsonl beside it. The normative field-by-field contract, the full kind table, and the retryable rule are in docs/exit-codes.md.

8. Decided: no terminal receipt file

An adapter reading this guide may reasonably ask for one more thing: a small file the runner drops at the end of a run — a run --outcome-json <path>, atomically replaced at terminal completion with the outcome, a cleanup confirmation, and artifact locators — so the common path costs one tiny read instead of a walk over the lifecycle stream. It was proposed, evaluated against a real adapter, and declined. This section records why, so the question does not have to be reopened from scratch; the durable record, including the one alternative that was deferred rather than rejected, is ADR 0007.

• It would not remove the read it exists to remove. A supervising adapter does not read the stream only for the terminal event. The one this decision was measured against consumes four event types after every call — run_started (for root_pid, mechanism, abrupt_cleanup), members_snapshot, output_captured, and runner_exit — and treats a missing run_started or output_captured as a failure reason of its own. A terminal receipt carries terminal facts; the start-time facts exist only in the stream (§3). Such an adapter would gain a second artifact and keep the loop.
• The read is seven lines. A foreground run emits seven events — eight with --capture-dir, and one more again when a requested resource cap (--max-memory / --max-processes / --cpu-quota) adds its post-run limit_evidence. Six of the seven were the whole stream until resource_summary joined them unconditionally; that one line is the sole growth a caller did not opt into, and it is one line, once, at the end. Every other way the stream grows is a caller asking for more events on purpose — --capture-dir, a cap, and --snapshot-interval's extra members_snapshot samples. docs/schema.md, "Ordering", is the full rule.
• A cheaper answer already exists, and it is the recipe in §3: the --error-format json envelope resolves exactly this ambiguity with no path to allocate, no artifact to clean up, and no second durable shape to version.
• A receipt could not report its own failure. It would be written after the child's exit code is already decided. If that write, or its atomic replace, failed, the runner's options would be to fail the run — rewriting the child's exit code, which docs/exit-codes.md forbids outright — or to say nothing, which would make the receipt's absence mean either "the runner died abruptly" or "the receipt could not be written". The property that made the idea attractive is the first thing its own failure mode would take away. The lifecycle stream is not exposed this way: it carries the whole run, so a write failure truncates it visibly rather than turning one expected artifact into a silent nothing.

What this does not claim: that every terminal read is already as cheap as it could be. There is no first-party bounded terminal read over an arbitrary stream file today. events --json (§3) is a whole-stream pass-through, and wait --report-outcome (§4) reports an outcome only for a run that invocation observed live — a finished foreground run has already deleted its own registry record, so it answers status: "unknown" for one. If that ever becomes a measured cost rather than an anticipated one, ADR 0007 records why the answer would be a read-side flag over --file, reusing the shape wait --report-outcome already publishes, rather than a second write path out of the runner.

See also

• docs/agent-workflows.md — a policy and execution strategy for automation agents that launch external tools through the runner.
• docs/schema.md — the normative JSONL event schema (every field, every event, versioning rules).
• fixtures/schema/cli/README.md — the JSON Schema documents and golden fixtures for every machine-readable output in this guide (probe, list, inspect, the cancel/kill acks, prune, wait --report-outcome, attest, doctor, and the --error-format json failure envelope), and the versioning decision behind them (probe, inspect, attest, doctor, and the envelope carry their own version field; the other four deliberately carry none).
• docs/compatibility.md — the compatibility surfaces, the pinning procedure, and the upgrade/downgrade checklists.
• docs/exit-codes.md — the normative reserved exit-code band and the child-fidelity rule.
• docs/control-plane.md — the normative local transport, wire protocol, and inspect/cancel/kill/attest behavior.
• docs/registry.md — the normative registry location, record format, and staleness/reaping rules.
• docs/architecture.md — the map of this repository's own modules, for a contributor rather than a consumer.
• docs/troubleshooting.md — symptom-to-cause diagnosis for an operator, organized by what you observe rather than by call sequence.

Compatibility and upgrades

ProcessKit CLI has three public compatibility surfaces:

1. command names and flags;
2. the reserved runner exit-code band;
3. JSONL schema_version.

Three, and only three — a versioned payload is not a fourth surface. Several machine-readable outputs carry a version field of their own: probe --json's probe_version, inspect's snapshot_version, the --error-format json failure envelope's error_version, and attest --json's attestation_version. Each of those rides on the list above — on the command and flag that produce it (surface 1), and, for the failure envelope and the attestation, on the reserved code it reports (surface 2) — and pins its own shape inside the payload rather than adding a further thing to pin before launching. (Count them separately: "three compatibility surfaces" and "how many version fields this project publishes" are different questions with different answers.) The registry record's registry_version is not on the list either, for a different reason: the per-user registry is a private contract between this binary and itself, not something a caller reads off an invocation (see docs/registry.md). Which outputs carry a version field, and why the rest deliberately do not, is "Machine-output schemas" below.

The human CLI surface is guarded by through-binary golden snapshots for the root help and every public subcommand in fixtures/cli-help/. An intentional flag, value-name, default, or help change must be regenerated with UPDATE_CLI_HELP_GOLDEN=1 cargo test --test cli_help and the fixture diff reviewed. The test normalizes only the Windows .exe suffix and line endings; all contract text and ordering remain exact.

Breaking any of those three surfaces requires a major release. An adapter should verify the exact pieces it uses before launching a payload rather than discovering an incompatible binary after work has started.

Fail-closed preflight

processkit-cli probe --json \
  --require-schema-version 1 \
  --require-exit-code-band 100-119 \
  --require-surface run \
  --require-surface run:--jsonl \
  --require-surface run:--capture-dir \
  --require-surface inspect:--json \
  --require-surface cancel

probe is side-effect-free. It launches no child, creates no container, and does not touch the registry. A missing requirement exits PROBE_INCOMPATIBLE (110) and reports all mismatches.

That answers a question about the binary. The matching question about the host — can this machine actually create the registry, contain a process, and round-trip the control plane? — is what doctor answers, by doing all three in a bounded scratch run and reporting what it observed; an unmet host requirement exits HOST_UNQUALIFIED (116). It is a setup-time check rather than a per-launch one, because unlike probe it has real (self-cleaning) side effects. See docs/integration.md §1 and docs/troubleshooting.md, "Qualifying a host: doctor".

Surface tokens

A surface token takes one of three forms — a subcommand, subcommand:--long-flag, or subcommand:capability:

run
run:--jsonl
run:--idle-timeout
inspect
inspect:--json
cancel:--all
attest:peer-identity
run:resource-summary

The first two forms name a spelling the parser accepts, and are derived from the live clap definition so they cannot drift from the real one. The third names a capability instead — "can this binary do the thing", which no parser can answer — and is told apart by carrying no --. The missing -- is what keeps the two categories from being read as one another, so an adapter that validates this array with a pattern of its own must admit the ---less form; the published grammar is the surface pattern in fixtures/schema/cli/probe.schema.json.

There are two capability tokens, and they differ in why they might be absent:

• attest:peer-identity — a platform capability. Published exactly where this build can obtain a kernel-authenticated identity for a control-plane client, which is what makes attest able to return a membership verdict at all (see docs/control-plane.md and docs/integration.md, §1). A given target may lack it.
• run:resource-summary — a build capability. Published by every build whose run emits the terminal resource_summary event (see docs/schema.md). No platform removes it; only an older binary lacks it. That is exactly why it needs a token: an event's presence is otherwise undiscoverable until a run has already finished without it, which is after the work the number was wanted for.

A consumer requires either with the same --require-surface and does not need to know which kind it is holding.

A capability token's presence is a guarantee, and it is worth being precise about what is guaranteed in each case. attest:peer-identity guarantees this target names the peer, so a negative membership answer from it is a real verdict rather than a missing capability in disguise. run:resource-summary guarantees the event will be in the stream — not that any particular measurement in it is populated: which axes carry numbers is a property of the containment mechanism (run_started.mechanism) and, for memory and CPU on Linux cgroup v2, of how the run ended. The normative matrix is in docs/resource-limits.md. A single token could not honestly carry five per-platform facts, and splitting it into five would publish as capabilities what are really documented properties of the mechanism — which is also why no token could have promised numbers a read point decides.

A capability's absence withholds its guarantee rather than predicting failure — attest on a build without the token still answers from whatever the kernel actually provides, and fails closed with peer_identity_unsupported when that is nothing. Requiring it therefore turns "this platform cannot prove membership" into an ordinary PROBE_INCOMPATIBLE (110) at preflight, instead of a refusal in the middle of a job.

Require only the features the adapter will actually use. This permits additive CLI releases while preventing an invocation from reaching a binary that lacks a needed flag. That is why the preflight example above pins no capability token: it shows an adapter that uses run, inspect, and cancel and nothing else. An adapter that will gate work on containment membership adds --require-surface attest:peer-identity to its own invocation — an adapter that will not must leave it out, since requiring an unused capability would fail preflight on a platform whose missing capability could not have affected it.

Schema pinning

Every event carries schema_version. An adapter should reject an unknown value before interpreting event-specific fields. The current schema is documented in JSONL event schema and available from the installed binary:

processkit-cli probe --json --print-schema > schema.json

--print-schema is mutually exclusive with --require-*: printing the document and checking compatibility are separate operations, so neither can be silently skipped.

What a reader must tolerate within one version

Within one schema version, a reader must tolerate every one of the following. Removing a field, renaming it, or changing the meaning or type of an existing one is what requires a new schema version — nothing below does.

1. New event types — including ones that appear in every run. Route by the event discriminator and ignore a type you do not know, rather than failing on it or assuming the stream is corrupt. Note the scope of this obligation carefully: a new type need not be gated behind a flag. resource_summary (see docs/schema.md) is the worked example — it is emitted by every run that spawned a child, so a default run's stream is one line longer than an earlier v1 build's. Nothing existing changed, which is what makes it additive; a reader that pinned the exact set of event types a run emits, rather than routing by tag, is the only kind that notices.

2. More occurrences of an event type you already know, including a type that previously occurred at most once. Within a version you may not assume any event type is unique, or that its position in the stream is fixed relative to other types beyond what the ordering contract states. members_snapshot is the worked example: it appeared exactly once per run until run --snapshot-interval made a run emit it on a cadence.

3. New fields on an event you already parse — including always-present ones, not only optional ones. "Additive" here means "no existing field changes", not "the new field may be absent": members_snapshot gained an always-present reason and an always-present read_error, timeout gained an always-present reason, and cleanup_started/cleanup_finished gained always-present read_error flags, and cleanup_finished gained an always-present kill_error qualifier, all within version 1. A reader must therefore consume the fields it uses rather than pin an event's exact field set — validating with additionalProperties: false against a copy of a published document will fail on the next additive release (see "Machine-output schemas" below). The new limit_evidence event is likewise additive: readers should route by event, ignore the new type when they do not use resource-limit attribution, and keep schema_version pinned at 1.

   A requested cap that fails during ProcessGroup creation remains the pre-spawn limit_hit path. Since no group exists on that path, it has no limit_evidence event; readers must not synthesize an unknown evidence record for it.

   The resource_summary event carries the same obligation in a stronger form, because every one of its measurements is nullable: a null means "this mechanism, at this read point, does not account for it" and must not be read as, or replaced by, 0. Check its read_error flag before drawing any conclusion from a null — an all-null summary is a correct reading on a mechanism with no whole-tree accounting, and equally on a flagless Linux cgroup v2 run whose child exited on its own; only that flag distinguishes either from a read that failed. The per-axis platform matrix is in docs/resource-limits.md — read it before relying on an axis, because two of them are governed by the read point and not by the platform alone — and its two IO counters are explicitly not comparable across platforms.

4. New values in an open-ended descriptive string field — a new cancelled source, a new runner_exit source, a new hint label. Treat an unrecognized value as "some other trigger" and keep routing by event type.

5. New values in the growing mechanism vocabulary. process_reaper is an additive value within schema v1: no existing mechanism changed meaning, and readers must treat an unfamiliar mechanism as an unsupported containment choice rather than reject the complete event or machine-output record. unknown is an intentional contract value emitted by the CLI's conservative fallback for a future processkit::Mechanism variant, not a projection error. The published schemas enumerate the current vocabulary, so an older frozen schema may reject a newer value; strict validation must use the producer-matching schema, and an adapter's runtime parser must not treat the old enum as exhaustive.

6. An escaped element in --argv-raw's argv array. The field's type is unchanged (array of string) and every element that is valid Unicode is still the argument verbatim, but an argument the platform accepts and Unicode cannot express — ill-formed bytes on Unix, an unpaired surrogate on Windows — is now recorded losslessly in an escaped form opened by U+0000, instead of the U+FFFD-mangled reconstruction earlier v1 builds wrote. A reader that displays or logs argv needs no change, and neither does one that stores or relays the JSONL line: U+0000 goes on the wire as the ordinary six-character JSON escape, so the line stays NUL-free text. The correction adds two reader obligations, both confined to that one element shape:

   • A reader that reconstructs an argv (to re-run, compare, or match against one it holds) must decode that form — the grammar is in docs/schema.md, "Raw argv that is not valid Unicode" — and must not take an escaped element literally.
   • A reader that stores or forwards a decoded element must check that its sink accepts U+0000; this is the only place in the schema where a string value can carry that code point, so a sink that rejects it will have accepted every stream earlier builds produced. PostgreSQL refuses a jsonb document containing it (an adapter that ingests whole event lines into jsonb loses the entire run_started event, not just the field), a C-string API truncates the element at its leading NUL and is left with nothing, and some YAML and log transports refuse a NUL in a scalar. Such a reader decodes the escape and re-renders it for its sink — or escapes or drops the marker itself — instead of passing the decoded string through.

   argv_sha256 adds no obligation at all, since every digest an earlier build produced for an ordinary command line is unchanged.

7. Unknown fields anywhere in the envelope or event body.

The normative source is docs/schema.md, not this page: its "Ordering" section (and specifically "Multiplicity of members_snapshot") states how many of each event a stream may carry and where, and its "Versioning" section defines exactly which changes are additive and which are breaking. This section restates those obligations for an adapter author; where the two ever disagree, docs/schema.md wins and the disagreement is a bug in this page.

How the borrowed vocabularies are kept in step

Several of the enumerations above are not this project's own inventions: the mechanism, abrupt_cleanup, limit_evidence verdict, soft_stop_scope, soft_signal, and outcome values are projections of closed enums in the processkit library this runner is built on. Those enums grow — process_reaper above is one such growth — and every projection here ends in a deliberate fallback (unknown, none, failed) so that a build which meets a value it predates degrades honestly instead of guessing.

A fallback is a safe answer, not a good one, so the project does not rely on noticing upstream growth by hand. processkit publishes a machine-readable dictionary of its stable identifiers inside its own package, and a gating test tier (tests/spec_drift.rs; see CONTRIBUTING.md, "Upstream identifier drift") holds every projection and every published schema enum against the dictionary belonging to the exact library version this binary is built with. A value that would land in a fallback arm fails the build, naming the enum and the identifier.

What that means for an adapter is narrow and worth stating exactly. It is a promise about this project's process — that a borrowed vocabulary cannot grow without someone deciding what the new value means here — and not a promise that your pinned schema copy stays complete: a decision may still add a value in a later release. Points 4 and 5 above are unchanged obligations. It also covers only the vocabularies borrowed from processkit; the ones this CLI mints itself (a cancelled source, a runner_exit source, a hint label) have no upstream dictionary to be checked against and remain open-ended by design.

Machine-output schemas

The JSONL stream is not the only machine-readable output. The discovery and control commands print machine-readable JSON to stdout too, and each of those shapes has a published JSON Schema (draft 2020-12, self-contained) plus a golden fixture under fixtures/schema/cli/:

The failure-envelope row is the odd one out in two ways, both deliberate. It is printed on stderr, not stdout — that is what keeps stdout reserved for successful output, so a command that prints a report and then fails leaves its stdout untouched — and it describes a failure rather than a success, which is exactly why the eight success shapes beside it could never have covered it. It is opt-in: without --error-format json, a failure prints the same free-text prose it always did.

Two of the table's rows are verdict shapes, and both are routinely printed alongside a non-zero exit, with no flag involved in either. Two of attest --json's three verdicts make the command fail, and the attestation is printed for all three (see docs/control-plane.md, "attest"); doctor --json exits HOST_UNQUALIFIED (116) whenever a phase failed or a --require-* expectation about the host went unmet, and prints the same report either way (see docs/integration.md §1 and docs/troubleshooting.md, "Qualifying a host: doctor"). In both cases the verdict is the answer and the exit code only says what to do about it, so neither channel replaces the other: do not treat a non-zero exit as "there is no stdout to parse". (probe --json behaves the same way but only when the caller asked for a --require-* expectation the binary did not meet, and inspect --all's and cancel/kill --all's report arrays precede a CONTROL (103) that reports what could not be done rather than what was decided — a different fact, the same reading discipline. wait --report-outcome is neither: it prints only when the wait succeeded.)

events --json is deliberately absent from that table: it passes the runner's own JSONL lines through byte for byte, so the document that describes it is the event schema above (fixtures/schema/v1/schema.json), not a second one of its own. That is also what events --validate checks a stream against.

tests/machine_output.rs validates the real binary's output for each of these against its document on every test run, so an accidental shape change fails CI instead of reaching an adapter. A document whose family has more than one output form has a root oneOf over named $defs, so a consumer can validate against the exact form it invoked — for example inspect.schema.json#/$defs/snapshot.

Five rows of that table carry a version field; the other four deliberately do not. probe --json carries probe_version, inspect --json carries snapshot_version — the same field the runner puts on the control-plane wire — the failure envelope carries error_version, attest --json carries attestation_version, and doctor --json carries doctor_version. probe.schema.json, error.schema.json, attest.schema.json, and doctor.schema.json pin their value with const; inspect.schema.json admits the range of snapshot versions this build renders (see the snapshot_version bullet below), because that field reports the runner's contract, not the invoked binary's. The shape follows the reader's tolerance rather than a sibling's precedent: attest's value also comes off the wire, and is pinned anyway, because its client refuses any version but its own outright — a membership verdict read under unpromised semantics is worse than no verdict. Either way a bump is visible in the payload itself. Pin those five on their own version field, not on the CLI version alone: ignoring a snapshot_version bump across an upgrade is exactly the class of mistake this section exists to prevent. All five are versioned for the reason the project's other two versioned contracts (the durable JSONL stream's schema_version and the registry record's registry_version) are: each can be read by a party that did not invoke the binary — the snapshot and the attestation cross a process boundary to a runner that may be a different build, the probe report's whole job is to be read before the binary's version is known, a failure envelope is routinely read out of its invoking context altogether (captured stderr in a CI log, read back later by a different tool than the one that ran the binary), and a doctor report is meant to be kept: a failed qualification writes it into the diagnostics directory it leaves behind, precisely so it can be read later, elsewhere, by whoever is debugging the host rather than by whoever ran it.

The remaining four — list --json, the cancel/kill ack and --all report, prune --json, and wait --report-outcome in both its forms — carry no version field, deliberately. Each is a synchronous stdout rendering read by the caller that just invoked this exact binary. That includes the printed ack, whose content does arrive over the wire but is re-serialized by the client from the three fields it parsed and verified, so its field set is the client's own (see fixtures/schema/cli/README.md, "Versioning"). Such a caller already knows the version and can pin the shape through the probe preflight above — the reported version, plus one --require-surface token per subcommand and flag it will actually use. A per-output version field would be a second, redundant pinning axis, so none was added.

Consequently:

• The unversioned four ride on the first compatibility surface (command names and flags), not on a version integer of their own. A breaking change to any of them — removing a field, renaming it, changing its type or the meaning of a value — is a major release, announced in the changelog.
• probe --json, inspect --json, the failure envelope, attest --json, and doctor --json additionally bump their own field. A breaking change to either of the first two shapes bumps probe_version / snapshot_version respectively, and that field is what a consumer should check. The envelope's error_version works the same way: removing or re-typing one of its stable fields, or changing what an existing kind means, bumps it, while a new field or a new kind value is additive and does not (see docs/exit-codes.md, "Machine-readable failures", and the "Stability" section there). For the snapshot, this binary's own inspect client checks it too, and does so asymmetrically: a runner answering with a snapshot_version newer than this build implements is refused with CONTROL (103) rather than rendered under semantics its sender never promised, while an older one is still read for as long as this build genuinely decodes it (today: version 1, the version every release so far writes). See docs/control-plane.md, "Snapshot version: a newer runner's reply is refused, an older one is read", for the rule, the floor, and what moves it. Two consequences for an upgrade: a bump is a hard boundary for older clients in a mixed deployment, not merely a signal to read; and the snapshot_version on stdout is the runner's number, so inspect.schema.json admits the range this build renders instead of pinning a single value. attest --json's attestation_version is checked too and is the strict case of the same rule — any version but this build's own is refused, because a membership verdict must never be read under semantics its sender did not promise, and because that contract has had only one version so far, so strictness refuses nothing that ever existed. Whether a wire-supplied version pin is a range or a single value follows what its reader actually decodes, never what a sibling document does.
• Every document under fixtures/schema/cli/ is updated in place. There is no vN/ directory there (unlike fixtures/schema/v1/, whose v1 is the JSONL schema_version), because a version here, where there is one, lives in the payload rather than in a path. If a future release gives one of the unversioned four a version field of its own, that is the point to revisit the layout.
• Additive changes remain minor/patch, exactly as they are for the JSONL stream, and a reader that consumes the fields it knows is unaffected.

The published documents set additionalProperties: false so that this repository's own tests fail when a field is added without publishing it. An adapter that copies a document into its own pipeline and wants to tolerate a future additive field should relax that keyword on its copy rather than pin a field set the project treats as additive.

Exit-code compatibility

Normal foreground runs forward the child code. Runner-owned outcomes occupy 100–119. Because a child may itself return a number inside that band, the terminal runner_exit.child_code / runner reason remains the authoritative machine distinction.

Verify the whole reserved band, not only the individual codes your current version knows. This protects space for additive runner outcomes without making an old adapter classify them as child exits.

Detached launch is the documented exception: launcher 0 means the run started, and the child's eventual code is in terminal JSONL.

Upgrade procedure

1. Download and verify the new archive without replacing the active binary.
2. Run the new binary by absolute path with the adapter's full probe requirements.
3. Compare probe --print-schema with the adapter's pinned schema version.
4. Exercise one harmless run through the same I/O, capture, and control-plane flags used in production.
5. Confirm run_started.mechanism in the actual deployment environment.
6. Atomically replace the installed binary.
7. Keep the previous binary until terminal events from the smoke run have been consumed successfully.

Reading release notes

The project changelog uses Keep a Changelog categories. Look for:

• Added: optional flags/events/features an adapter may adopt;
• Changed: behavior that remains inside the current compatibility contract;
• Fixed: corrections that may alter previously buggy observations;
• Removed: major-version migration work.

The manifest version, v<version> tag, crates.io artifact, and GitHub Release are produced by one release workflow and should identify the same release.

Rolling upgrades with live runs

The control plane lives inside each running process. Replacing the executable on disk does not upgrade a runner already in memory. A new client must therefore remain compatible with the live run's registry/control/schema contract until that run finishes.

For a conservative rolling upgrade:

1. stop launching new work through the old binary;
2. let or cancel old live runs;
3. wait for the registry to become empty;
4. preview and prune stale entries;
5. replace the binary and launch new work.

Do not use recorded PIDs to bridge versions.

Downgrades

Run the target older binary's probe by absolute path before replacing the newer one. An older binary may lack an additive flag even when the JSONL schema version is unchanged. Surface-token verification catches that case.

Preserve event files across a downgrade; they are durable observations from the binary that produced them and must be decoded according to their own schema_version, not the currently installed executable.

The rolling-upgrade and downgrade procedures above are not only described here. A scheduled, non-gating workflow (.github/workflows/interop.yml) downloads the latest published release and runs both directions of them against the current build every week — new clients over an old runner and the reverse, an abandoned record reaped from either side, probe pinning both ways, and each binary's JSONL stream read under the other's schema. See CONTRIBUTING.md, "Cross-version interop".

Adapter acceptance checklist

• exact supported schema_version;
• exact reserved exit-code band;
• every command and long flag the adapter invokes;
• required containment mechanism;
• required abrupt_cleanup strength;
• I/O mode/capture assumptions;
• resource-limit applicability in the real environment.

The last four are properties of the deployment, not of the binary, so probe cannot answer them: confirm them on each host with doctor (--require-mechanism, --require-abrupt-cleanup, --check-resource-controller --require-resource-controller), which reports what the machine actually did rather than what its platform can do in principle.

See also

• Integration guide — complete adapter lifecycle.
• Exit-code contract.
• JSONL event schema.
• Platform support.

JSONL event schema (v1)

This is the normative description of processkit-cli's JSONL lifecycle-event contract. It is part of the project's public compatibility surface — CLI flags + exit-code ranges + schema_version (see AGENTS.md) — because adapters, in particular the processkit-py CLI, pin schema_version and reimplement these shapes. Treat every field below as public API.

• The in-code source of truth is src/events.rs.
• The golden sample stream is fixtures/schema/v1/events.jsonl; the golden test (events::tests::golden_stream_matches_the_fixture) keeps this document, the code, and the fixture in lockstep.
• A machine-readable JSON Schema (draft 2020-12) is published at fixtures/schema/v1/schema.json — one variant per event type plus the shared envelope, transcribed from this document. This prose document remains the normative source of truth; the JSON Schema is a mechanical mirror of it, kept honest by tests::golden_fixture_validates_against_the_schema (tests/events.rs), which validates the golden fixture (and, in several other tests in that file, live streams emitted by the binary) against it — so a discrepancy between the schema and the fixture/code fails CI rather than drifting silently. On any disagreement between the schema and this document, trust this document and treat the schema as needing a fix. The schema's version is synchronized with schema_version: it lives under fixtures/schema/v1/ alongside the fixture, and a breaking change that bumps schema_version (see "Versioning") moves both to a new fixtures/schema/vN/ directory together, never one without the other.

Getting the schema without a git checkout

fixtures/schema/v1/schema.json lives in the repository, so a consumer who only has an installed binary (cargo install) or an unpacked release archive — no clone, no tag to check out — could otherwise only get the exact schema for their version by guessing which git tag matches. Two offline alternatives avoid that:

• processkit-cli probe --json --print-schema prints the schema document embedded into that specific binary at build time (src/probe.rs's SCHEMA_JSON, via include_str! — the file above stays the single source of truth, this is a verbatim, byte-for-byte copy of it, never a hand-maintained second one). It replaces the usual probe report, and cannot be combined with any --require-* flag: that combination is rejected at parse time as an ordinary usage error (exit 100), not silently accepted with the requested checks skipped — a probe invocation that asks for expectations to be verified must never exit 0 without verifying them (see docs/integration.md, "Fail-closed preflight"). --print-schema itself is an ordinary, additive CLI surface token (probe:--print-schema) like any other probe flag.
• Every release archive (.github/workflows/release.yml) bundles a schema/ directory alongside the binary, completions/, and man/, containing schema.json and the golden events.jsonl fixture exactly as checked out for that release.

And to check a stream against it without a checkout — or a JSON Schema validator of your own — processkit-cli events --file <stream.jsonl> --validate validates every line against that same embedded document, reporting each violation by line number and exiting EVENTS_INVALID (114) when any line does not conform (see docs/exit-codes.md, "Checking a stream: events --validate"). It is the recommended way for an adapter to keep its own recorded fixtures honest against the runner version it targets. The checker is in-binary and adds no runtime dependency: it interprets the embedded document over the keyword subset that document uses and refuses to run on anything it does not implement, and the test tier holds its verdict against a real JSON Schema engine's, line for line, over the golden fixture and a generated mutation corpus.

Transport

• Events are written to the file named by run's --jsonl option, never to stdout. The child's stdout and stderr pass through untouched; runner diagnostics go to the --jsonl file or to stderr, never interleaved into the child's stdout (AGENTS.md, "Streams are strictly separated").
• The file is one event per line (JSON Lines): each line is a single, complete JSON object followed by \n. Lines are UTF-8.
• The --jsonl file is created or truncated at the start of a run, so it holds exactly that run's stream. Each line is flushed as it is written, so the stream is durable even though a completed run forwards the child's exit code via an immediate process exit.
• If the --jsonl file cannot be created, the run fails closed before the child is spawned (a runner-band exit code) rather than running the child with no event stream. A write failure after the child has started is best-effort: the runner warns once on stderr and continues, because the child's exit-code fidelity outranks diagnostics.

Envelope

Every line shares a common envelope, always in this order:

The time field is the moment the runner emitted the event. For root_exited it therefore doubles as the child's exit timestamp — the moment the runner observed the child leave.

Events

Fields marked nullable are always present; when a value is unknown or does not apply they are the JSON literal null (explicitly absent), never omitted.

run_started

The run has begun: the child is spawned into the container.

abrupt_cleanup is distinct from mechanism and from ordinary teardown. It is whole_tree on Windows because closing the runner's last Job Object handle kills all members; direct_child_only on Linux because the runner enables ProcessKit's parent-death signal for the root child while cgroups themselves persist; and none on FreeBSD, macOS, and other Unix because the current public API has no parent-death primitive there. Normal completion, timeout, and cancellation still invoke the reported container mechanism's regular teardown.

members_snapshot

A point-in-time snapshot of the container's members. It is a snapshot, not a census: a listed PID may exit immediately afterward, and a process spawned during the read may be missing.

A member object:

How many, and when (reason). Every run emits one snapshot immediately after run_started, carrying reason: "spawn". A run given run --snapshot-interval <duration> additionally re-emits the same event on that cadence for as long as the child runs, each carrying reason: "interval" — recorded observability for how the tree evolved (when the worker fleet grew, whether helpers lingered, what the tree looked like just before a deadline fired), for the long, quiet, or detached runs where nobody is likely to have been watching live with inspect at the interesting moment.

• reason and read_error are always present, including on the single spawn snapshot a run without the flag emits. reason is the only difference between a post-spawn snapshot and a periodic one: both are produced by the same code through the same members_info() enrichment, so a periodic snapshot's members cannot drift in shape from the first one's.
• The periodic snapshots stop the moment the run's ending is decided, so they appear only between run_started and the ending's own event (root_exited, or the timeout/cancelled/killed reason event) — never interleaved into the cleanup_started/cleanup_finished teardown pair. See "Ordering".
• Repeating an existing event is additive within schema v1 — no field is renamed, retyped, or given a new meaning, and a reader that pins a version must already tolerate additional events (see "Versioning"). The cadence is also opt-in: without --snapshot-interval a run emits exactly the one snapshot, at exactly the point, it always did. The event's wire form, however, changed for every run including the flagless one: reason and read_error are new, always-present fields, additive within v1 but not "unchanged" (see Compatibility and upgrades for the reader obligations that follow).
• Snapshots are read from the container's own member list, not from the runner's output pump, so --snapshot-interval composes with every I/O mode — --inherit-stdio included, unlike --idle-timeout.

Honest degradation on a failed sample. When the members_info() read itself fails, the snapshot is still emitted, with read_error: true and an empty members array — the same convention cleanup_started/cleanup_finished use for their own failed reads (see "Honest degradation on a teardown read failure"). members is then a fallback, not an observation: a consumer must check read_error before reading an empty array as a confirmed-empty tree. The runner also warns on its stderr, but that warning is not the contract: a --detached runner's stdin/stdout/stderr are null (see Detached runs), so in the long, quiet, detached runs this cadence exists for, the flagged event in the JSONL file is the only report of the failure that reaches anyone. A failed sample therefore never appears as a gap in the cadence; a genuine gap means the run ended, the interval had not elapsed yet, or the stream itself stopped (see "Stream size" below).

Stream size. The cadence is the first thing in this stream whose event count scales with a run's duration, and it is deliberately unbounded — see Running commands for the recorded decision, the sizing arithmetic, and how to choose an interval.

root_exited

The root child exited on its own.

On Windows a killed process reports exited with a platform code (there is no signal abstraction), so signalled is Unix-only.

cleanup_started

Container teardown is beginning.

cleanup_finished

Container teardown finished (after the hard kill).

remaining_pids is a snapshot: on the Job Object and cgroup mechanisms a process leaves membership on exit, so it is empty after the kill; on the POSIX process-group fallback an unreaped just-exited child can still be listed until it is reaped. soft_terminate is one of:

• signalled — a soft stop really was delivered to the tree: on Unix a SIGTERM broadcast; on Windows, where a Job Object has no POSIX signal, ProcessKit's best-effort soft close — a WM_CLOSE to every top-level window owned by a live member plus a console CTRL_BREAK to a child opted in with --windows-graceful-ctrl-break.
• unsupported — nothing in the tree could receive a soft stop, so none was sent and the runner does not pretend otherwise. Windows-only in practice, and the ordinary case there for a plain console child: no windowed member and no console-CTRL leader means the soft tier has nothing to trigger. The grace window still elapsed before the atomic Job Object kill.
• failed — the soft stop could not be delivered; the hard kill ran regardless.

shutdown is null for natural exits and immediate kill endings. Otherwise it contains:

The last three fields are null only when ProcessGroup::stop itself failed and could not return a ShutdownReport; the owning container's hard-kill backstop still runs. This is additive to schema v1 and leaves soft_terminate in place for existing consumers.

Honest degradation on teardown confirmation failures. members_before/remaining/ remaining_pids are read from the live container (ProcessGroup::members()), which can itself fail (an OS-level enumeration error). Rather than let a read failure masquerade as a confirmed 0/empty observation, each event carries an explicit read_error flag: false on every successful read (the common case, unaffected by this), true when the read failed, in which case the numeric field(s) fall back to 0/an empty array — not a fabricated fact, only the absence of one. A consumer that treats cleanup_finished.remaining == 0 as "the tree is confirmed empty" must first check read_error is false.

cleanup_finished.kill_error qualifies a separate operation: it is true when ProcessGroup::kill_all() itself returned an error. A subsequent member read can still succeed and return an empty list in that state — notably when ProcessKit drained the tree but could not thaw the container — so remaining: 0, remaining_pids: [], and read_error: false are not conclusive on their own. Confirmed-clean teardown requires kill_error: false, read_error: false, and remaining: 0. A successful hard kill followed by the same empty snapshot keeps both flags false. The field is always present and additive within schema v1; no existing field changed meaning.

The runner also warns on stderr whenever this happens, though — as for members_snapshot's own flag above — that warning reaches nobody in a detached run, so the flags in the stream, not the warning, are the contract. This mirrors output_captured's write_error flag (both are explicit failure markers, never inferred from the accompanying data alone).

limit_hit

A requested ProcessKit resource limit (--max-memory, --max-processes, or --cpu-quota) could not be applied.

When it is emitted. Enforcement of a whole-tree cap needs a real container — a Windows Job Object or a Linux cgroup v2. Where none can carry the request, the run fails fast rather than running silently unbounded, and this event records it. The emission is deliberately narrow:

• Only the "could not be applied" branch. ProcessKit signals a limit failure only at group creation (pre-spawn — the child never started); it exposes no separate "the tree was killed mid-run for exceeding a cap" runtime signal (the OS reaps an offender itself — a Job Object/cgroup OOM or CPU throttle — without the crate translating that into an event). So limit_hit covers the unenforceable / unsupported case, not a live overrun: memory/cpu/processes where the platform cannot provide the requested whole-tree cap (macOS and non-FreeBSD BSD process groups, plus the Linux process-group fallback, have no whole-tree cap container; FreeBSD's process reaper provides whole-tree normal containment, membership, and kill/teardown semantics but no memory, CPU, or process-count resource-limit support), or a Linux cgroup v2 whose controllers can't be enabled (not the real hierarchy root — under systemd, an ordinary container, or typical CI; see README.md, "Resource limits"). This is the pre-spawn admission failure only; post-run evidence for successfully applied caps is carried by the additive limit_evidence event below and follows the platform matrix in docs/resource-limits.md.
• Nonsense values never reach it. A degenerate value (--max-memory 0, a non-positive/non-finite --cpu-quota) is a USAGE (100) form error rejected at argument-parse time, so limit_hit never carries an "invalid value" reason.
• Ordering. limit_hit is emitted first, then the same container_failed (phase: "create") → runner_exit (source: "container_error", code BACKEND = 102) tail every other group-creation failure takes. The dedicated limit_hit event — not the exit code — is the authoritative signal that the ending was a resource limit (docs/exit-codes.md, "Why a band is not enough on its own"). A run whose caps were applied emits no limit_hit at all and proceeds normally. Its post-run evidence, when requested, is the separate limit_evidence event below.

limit_evidence

Post-run, per-axis evidence for a run that requested at least one resource cap and whose ProcessGroup::with_options call successfully created the container. The runner reads ProcessGroup::limit_evidence() while that group still exists, after the ending event (root_exited, timeout, cancelled, killed, or output_overflow) when one exists, and before cleanup_started consumes the group. If group creation returns ProcessKit's ResourceLimit error, the group does not exist: the runner emits the pre-spawn limit_hit event and its existing backend-error tail, with no limit_evidence event.

tripped is emitted only for authoritative kernel evidence that the cap engaged; not_tripped is authoritative evidence that it did not engage (and is also ProcessKit's result for an uncapped axis); unknown means a successfully created group's mechanism cannot provide a post-run answer. Linux cgroup v2 can report all three states. A successfully created Windows Job Object reports unknown for capped axes. FreeBSD's process reaper provides whole-tree normal membership and kill/teardown semantics but no resource-limit primitive, so a cap request fails before a capped group exists. The POSIX process-group fallback and macOS/non-FreeBSD BSD process groups likewise fail before a capped group exists, so they emit limit_hit and no limit_evidence. The event is absent when no cap was requested. This is an additive event within schema_version = 1.

resource_summary

What the contained tree actually consumed. The runner takes one ProcessGroup::stats() reading after the ending is decided and before cleanup_finished hard-kills the group — the same read point, and for the same reason, as limit_evidence: what it reads lives in the container, so it is gone with it. What that reading can cover is per-mechanism, and on Linux cgroup v2 memory and CPU depend on the read point itself (see the platform matrix linked below, consequence 5).

Emitted on every run that spawned the child. Exactly once, no flag, no cap, every platform, every ending. A run whose child never started (spawn_failed, a container_failed with phase create or attach, a pre-spawn limit_hit) emits none: there was no tree, and on the create path no container to read.

Decision: always, not behind a flag. This is deliberate and recorded here rather than left implicit. Three reasons:

• It is one synchronous read of accumulators the kernel already maintains, not a sampling cadence, so an opt-in would save one syscall's worth of work and one line of output. Contrast --snapshot-interval, which is opt-in: that adds unbounded volume on a timer, which is a real cost worth a flag.
• The platform that needs these numbers most would be the one left silent. On Windows, limit_evidence can only ever answer unknown for a capped axis (a Job Object keeps no post-mortem record that a cap fired), and on the POSIX fallback there is no limit_evidence at all. The measured peak_memory_bytes is the only honest resource fact available there — and a caller who had to know to pass a flag would not get it.
• An opt-in event costs more contract, not less: a flag, a probe token for the flag, and a conditional in the ordering rule, all to gate a single line.

The cost is paid honestly: this event does grow every run's stream by one line, so the foreground-run event count in docs/integration.md and ADR 0007 is now seven rather than six, and it is the one growth that is not a caller opting in. A reader that routes by event type — which docs/compatibility.md requires within a version — is unaffected.

Honest degradation, and why the flag is load-bearing. A failed stats() does not skip the event: it is emitted with read_error: true and every measurement null. That flag is not ceremony. An all-null summary is also a perfectly correct success: it is what a mechanism with no whole-tree accounting reports (FreeBSD's process reaper, macOS/non-FreeBSD BSD process groups, and the Linux process-group fallback), and it is equally what a plain flagless run on Linux cgroup v2 reports when its child exited on its own — memory and CPU have no live member left to sum at the read point, and no io/pids controller is enabled to answer for the rest. So the numbers alone cannot distinguish "this mechanism measured nothing here" from "we could not measure", on any platform. Only read_error can, and a consumer must check it before concluding anything from a null. A foreground run also gets a stderr warning, but that reaches nobody on a --detach run (whose stderr is Stdio::null()), which is why the fact is recorded in the stream.

Nothing here is improved, and null never means zero. Each axis is independently nullable, and null always means this mechanism, at this read point, does not account for it. The runner does not substitute 0, and does not take a maximum over its own periodic reads to fill a gap — that would describe when the runner looked, not what the tree did. A caller who wants a sampled series over the run wants --snapshot-interval's own event, knowingly — noting that it samples the tree's membership, not its consumption, so no event in this stream is a consumption series.

The normative platform matrix — which axis is null where, why the read point decides two of them, and why two platforms' IO counters are not comparable with each other — is in docs/resource-limits.md, together with what this event does not prove about a limit. Three consequences worth stating here because they are easy to misread as bugs:

• peak_process_count is null on all of Windows. A Job Object counts how many processes are in it now and how many were ever assigned to it; neither is a peak.
• On Linux cgroup v2, peak_memory_bytes and total_cpu_ms are null after a natural exit. They are not cgroup counters: they are summed from /proc over the members live at the read point, and a child that exited on its own has left none. The same two axes are populated on a runner-imposed ending (timeout, cancelled, killed, output_overflow), whose read happens while the tree still runs. Windows, whose Job Object accounting outlives its processes, is unaffected. This is the ordinary case on Linux, not an edge one — consequence 5 of the matrix states it normatively.
• total_cpu_ms truncates, so a run using under a millisecond of CPU reports a measured 0. null is the only value that means unknown.

active_process_count — which ProcessKit's snapshot does carry — is deliberately not on this event. It is a "how many right now" reading, and this read happens after the ending is decided, so it would report the moment the runner looked rather than anything about the run. The tree size at teardown already has an honest home in cleanup_started.members_before.

This is an additive event within schema_version = 1.

timeout

A runner deadline elapsed while the child was still running: either the whole-run --timeout, or the --idle-timeout (the child produced no output for the idle window). Both share this event, the reserved TIMEOUT (106) terminal code, and the soft-stop → grace → hard-kill teardown described by the following cleanup_started / cleanup_finished events (see docs/exit-codes.md); the always-present reason field tells them apart.

--idle-timeout re-arms its deadline on every chunk of the child's output, so a child that keeps producing output is never reaped no matter how long it runs — only one that goes silent past the window is. It reuses TIMEOUT (106) rather than minting a new exit code (the same class of ending — a deadline the runner enforced — distinguished by the more specific reason on this earlier event) and its terminal runner_exit source stays timeout, exactly as for --timeout. It requires the runner's output pump, so it conflicts with --inherit-stdio at parse time (like --capture-dir); it does compose with --capture-dir, whose tee re-arms the same one timer.

output_overflow

A capture stream exceeded its configured per-stream ceiling while --capture-overflow cancel was active. The event is emitted before the same soft-stop → grace → hard-kill teardown used by a timeout.