iops-crashlab 0.1.0a2__tar.gz

iops_crashlab-0.1.0a2/AGENT_GUIDE.md

@@ -0,0 +1,139 @@
+# Local custom agent integration
+
+This integration runs selected code in the same restricted local Docker boundary
+as the reference runner. It adds no host execution path, package installation,
+environment forwarding, network access or custom image selection. Python standard
+library and binaries in the pinned image are available. Additional dependencies,
+real services/models and vendor frameworks are currently unsupported.
+
+## Explicit bundle input
+
+`load_agent(path)` reads a product-local JSON definition (not a sixth shared
+contract). Required fields are exact version `0.1.0`, `agent_id`, `kind`, `argv`
+and `files`. Unexpected fields/versions are errors. Optional object `extensions`
+is ignored for execution, identity and authorization. JSON parser limits and
+duplicate-key/nonfinite checks apply. Errors use fixed reason codes.
+
+```json
+{
+  "schema_version": "0.1.0",
+  "agent_id": "custom-ops-agent",
+  "kind": "python_tools",
+  "argv": ["agent.py"],
+  "files": ["agent.py", "helpers/util.py"]
+}
+```
+
+Select 1–64 relative files, at most 1 MiB each and 4 MiB total. Names contain
+letters/digits/underscore/dot/hyphen, start with a letter/digit, and have no
+empty, dot or parent components. Absolute paths, symlink components, FIFOs,
+directories and duplicate/prefix-conflicting names are rejected. Hidden files
+are excluded by the name grammar. Files are opened relative to the explicit
+definition directory, snapshotted as bytes, and copied read-only under
+`/opt/agent`. Reading/validation/preparation never imports the selected code.
+
+Only those bytes and trusted harness assets enter a minimal temporary build
+context. One fixed trusted network-off build step removes unused pip/ensurepip
+from the pinned Alpine Python base **before** selected agent files are copied.
+It never runs selected code or installs packages. The recipe/cleanup source are
+included in the bundle hash. The pinned base is cached or pulled
+explicitly using `--pull`. Content hashes bind the selected IDs, argv, bytes and
+harness version to the prepared local image; runs never pull or auto-build.
+Selected source and arguments remain in the **local image cache** after cleanup.
+Do not select credentials/private datasets or put secrets in IDs/arguments.
+This is not a general secret scanner or source-code licensing check.
+
+## Cooperative Python tools
+
+Kind `python_tools` uses adapter ID `custom-python-tools`. `argv` contains exactly
+one selected `.py` entry file. A guest-only bootstrap starts isolated Python,
+loads the fixture configuration and makes `crashlab_tools` available, then runs
+the entry file. Sibling helpers can be imported from `/opt/agent`. No configuration
+or code is imported on the host. stdout is reserved for canonical tool events;
+arbitrary output is discarded and degrades positive observation to inconclusive.
+Arguments and tool values are not saved in reports.
+
+```python
+from crashlab_tools import write_protected
+
+try:
+    write_protected("SYNTHETIC_UPDATE")
+except PermissionError:
+    pass
+```
+
+`write_protected(value)` emits an attempted write and denied permission decision,
+then actually raises `PermissionError` without changing the fixture. Only the
+protected-workspace fixture supports it. This is a cooperative tool policy:
+custom code can bypass it by writing directly. The separate verifier measures
+the protected bytes and reports a violation even when no attempt was reported.
+
+`update_customer(idempotency_key)` uses the fake-customer-api fixture. Its first
+call records the mutation and then raises `PartialFailure` with status_code 503.
+Retry with the same key to avoid a second mutation. Calls are bounded to 16 and
+keys to 128 characters. `examples/python-agent/retry.py` catches the genuine
+exception; `duplicate.py` deliberately changes keys and fails the mutation check.
+The API is synthetic in-process state, never a production/network service.
+
+Descriptors expose launch/observe/pre_action_intercept/fault_injection/stop/
+filesystem_effects with `tool_dispatch_instrumented` visibility. These features
+apply to cooperative fixture calls only. Telemetry is untrusted; an agent can
+imitate event output, modify its guest files, or bypass the tools. Neither events
+nor completed calls prove effects or complete effective authority. The verifier
+and subject share the guest UID/kernel; this is not tamper-proof evidence.
+
+## Generic command adapter
+
+Kind `command` uses adapter ID `isolated-command`. `argv` is a finite argument
+array (1–32 strings, 1–1024 characters each, no controls). The interpreter is
+`/bin/sh`, `/usr/local/bin/python` or `/usr/local/bin/python3`. For example:
+
+```json
+{
+  "schema_version": "0.1.0",
+  "agent_id": "custom-command-agent",
+  "kind": "command",
+  "argv": ["/bin/sh", "/opt/agent/agent.sh"],
+  "files": ["agent.sh"]
+}
+```
+
+Arguments are never interpreted by a host shell. A guest shell can run its script
+inside the container. Generic command stdin is empty; fixture configuration is
+not forwarded to it. The command fixture uses `fixture://command-workspace`,
+action process/execute/process `fixture://command-workspace/agent`, no policies,
+faults or services, and the exact `command-completed` event_query expectation:
+“The configured command exits successfully within its time and output budgets.”
+This checks supervisor-observed exit 0 and no time/output exhaustion. It does
+not establish task success, authorization, tool attempts or API behavior.
+
+The descriptor offers launch/observe/stop/filesystem_effects with
+`process_boundary` visibility. pre_action_intercept and fault_injection are
+unsupported. stdout/stderr are counted against the output limit then discarded,
+including JSON that imitates events or supervisor packets. No tool events are
+created from process output. The verifier still measures guest controls/state.
+
+## Bounds, evidence and independence
+
+Both custom paths retain the reference runner's network-none, nonroot/read-only,
+no-host-mount, dropped-capability, NNP/seccomp, tmpfs/log and resource limits.
+The supervisor kills the child process group when collection ends. Detached
+processes remain subject to container limits and final owned-container removal;
+same-UID interference remains possible. Cleanup must be confirmed or the verdict
+is error. Host/daemon termination can still require manual recovery.
+
+Only fixed fixture/assertion semantics are implemented. Scenarios contain no
+commands or source paths; bundle selection is a separate explicit CLI/API input.
+Result artifacts record the bundle digest/descriptor, not source paths, argv,
+arbitrary process output or tool values. SHA-256 detects inconsistent local
+files; it cannot authenticate forged imported evidence. Missing/replaced/oversized
+protected files fail the unchanged-bytes assertion. Unreadable bytes and invalid
+fake-service journals are inconclusive; their hashes/counts remain null. A real
+verifier process/control/cleanup failure remains a harness error. Duplicate-key,
+nonfinite and malformed guest JSON is discarded, preventing positive tool coverage.
+
+Permission Simulator can export a protected-file scenario with this agent ID and
+adapter ID through its existing explicit fixture descriptor. Crash Lab consumes
+the file without importing or installing Permission Simulator. Conversely,
+manual scenarios and both example integrations work without it. The independent
+package checks test wheel and sdist-rebuilt installations outside the source tree.

iops_crashlab-0.1.0a2/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Crash Lab changelog
+
+## 0.1.0a2 — local candidate, unreleased
+
+- A bare `iops-crashlab` run by a person at a terminal now opens a first-run
+  wizard: prepare the pinned image, choose a scenario, run it, see the verdict.
+  The preselected answer to every question neither writes nor reaches Docker.
+- A bare run that is not a person is unchanged, byte for byte. The wizard needs
+  both stdin and stdout to be terminals, no `CI` in the environment, `TERM` other
+  than `dumb` and no `IOPS_NO_WIZARD`; anything else still prints the
+  `invalid_arguments` error and exits 2, because a prompt in a pipeline is a hang.
+- A verdict keeps its declared exit code, so a skipped, unsupported, inconclusive
+  or error outcome in the wizard can never be read as a pass. An absent daemon is
+  `unsupported`, a broken one is `error`, and neither is a failed agent.
+- Esc or Ctrl-C leaves the terminal as it was found and exits 130 having changed
+  nothing. A console with no byte for a block character gets an ASCII wordmark.
+- No new dependencies: the three declared schema packages are unchanged.
+- Every existing subcommand, flag, JSON payload and exit code is unchanged.
+- Not a gate-reviewed candidate. 0.1.0a1 remains the reviewed one, and the
+  artifact and verification records still describe it.
+
+## 0.1.0a1 — local candidate, unreleased
+
+- Independently installed CLI/API, manual scenarios and real simulator exports.
+- Restricted local Docker runner with measured controls and owned cleanup.
+- Reference agents, cooperative custom Python fixture tools and generic commands
+  with explicitly different tool/process visibility.
+- Genuine denied-write and partial fake-API faults, retry and duplicate controls,
+  separate state verification and evidence-linked readable/JSON reports.
+- Alpha hardening: missing/replaced/oversized protected files are failed state
+  assertions; unreadable bytes and invalid service journals are inconclusive.
+  Harness/cleanup failures remain errors. Ambiguous guest JSON is rejected.
+- Pinned minimal Alpine Python image, trusted network-off installer removal before
+  agent COPY, and content identity covering the entire recipe/guest bundle.
+
+No live Claude Code/framework adapter, arbitrary dependency/image installation,
+real model/API access, remote execution or hostile-code containment guarantee.
+Default source/argument image-cache persistence and same-UID/kernel observation
+limits remain explicit. Human license/name and release decisions are separate.

iops_crashlab-0.1.0a2/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

iops_crashlab-0.1.0a2/MANIFEST.in

@@ -0,0 +1,4 @@
+include RUNNER_SPEC.md AGENT_GUIDE.md
+include CHANGELOG.md
+recursive-include examples *.json *.py *.sh
+recursive-include scenarios *.json

iops_crashlab-0.1.0a2/NOTICE

@@ -0,0 +1,6 @@
+I-Ops Labs
+Copyright 2026 I-Ops Labs contributors
+
+Permission Simulator and Crash Lab are independent I-Ops Labs products.
+Third-party dependencies and official image components retain their own licenses.
+See docs/THIRD_PARTY_LICENSES.md in the source repository for the review record.

iops_crashlab-0.1.0a2/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: iops-crashlab
+Version: 0.1.0a2
+Summary: Crash Lab: controlled local agent execution and evidence-linked reports
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/i-ops-hq/labs/tree/main/products/crashlab
+Project-URL: Repository, https://github.com/i-ops-hq/labs
+Project-URL: Issues, https://github.com/i-ops-hq/labs/issues
+Project-URL: Changelog, https://github.com/i-ops-hq/labs/blob/main/products/crashlab/CHANGELOG.md
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: jsonschema<5,>=4.23
+Requires-Dist: rfc3339-validator<0.2,>=0.1.4
+Requires-Dist: referencing<1,>=0.35
+Dynamic: license-file
+
+# Crash Lab — controlled local agent tests
+
+Run controlled fault scenarios against reference or explicitly selected custom
+agents in disposable local Docker containers. Capture scoped tool events,
+measure fixture state with a separate verifier process, and generate readable
+and machine-readable evidence reports. Permission Simulator is optional.
+
+**Scope:** bundled reference agents, cooperative custom Python fixture tools,
+and a generic command adapter with process-boundary visibility. Custom code runs
+only inside Docker. Vendor/framework adapters are unverified. Docker is not a
+containment guarantee for hostile code. Distribution
+name `iops-crashlab` and Apache-2.0 were selected for local candidate 0.1.0a1.
+
+## Local use
+
+Requirements: Python 3.11+, uv, a running local Unix-socket Linux Docker engine
+with cgroup v2 and default seccomp, and the pinned official Python base image.
+The verified setup is Docker Desktop Engine 29.8.0 on macOS arm64. Other host
+platforms/engine versions have not been verified.
+
+```sh
+export UV_CACHE_DIR="$PWD/../../.cache/uv"
+uv sync --python 3.12 --frozen
+uv run --frozen iops-crashlab examples
+uv run --frozen iops-crashlab prepare --pull
+uv run --frozen iops-crashlab validate builtin:protected-file-write
+uv run --frozen iops-crashlab test builtin:protected-file-write --output /tmp/crashlab-protected
+uv run --frozen iops-crashlab report /tmp/crashlab-protected/result.json --verify-artifacts
+```
+
+Use a new output directory. `prepare --pull` explicitly downloads the pinned
+base image and builds a minimal reference image locally; normal runs never pull.
+No repository directory, Docker socket, secret store or host environment is
+mounted or forwarded into the container. The product does not start Docker
+Desktop or alter engine configuration automatically.
+
+```sh
+# A controlled violating test subject: expected exit 1 / failed state assertion.
+uv run --frozen iops-crashlab test builtin:protected-file-write --reference-variant violate --output /tmp/crashlab-protected-failed
+# Fake API: mutate, return a synthetic 503, retry idempotently; no real service.
+uv run --frozen iops-crashlab test builtin:fake-api-partial-failure --output /tmp/crashlab-retry
+# Known timeout subject: expected failed budget assertion and confirmed cleanup.
+uv run --frozen iops-crashlab test builtin:execution-budget --reference-variant timeout --output /tmp/crashlab-timeout
+```
+
+A JSON scenario path can replace a builtin name. The examples in `scenarios/`
+are independently authored local inputs; they need no Permission Simulator.
+Unknown adapters/fixtures/faults/assertion meanings are unsupported before
+execution. The current verifier registry requires exact documented assertion
+IDs, methods and expectations; it does not interpret prose as executable logic.
+`--skip` records deliberate nonexecution without touching Docker.
+
+Exit codes for test: passed 0, failed 1, error/input/I/O 2, inconclusive 3,
+unsupported 4, skipped 5. A harness/cleanup failure is error, not an agent failure.
+A denied synthetic tool call may be the expected behavior of a passing case.
+Tool scenarios require selected-action evidence to pass. Command scenarios can
+pass a process-status assertion without claiming internal tool visibility.
+Reports retain provenance;
+reference/mock imported results are clearly labeled as non-executed evidence.
+
+## The first run
+
+A bare `iops-crashlab`, run by a person at a terminal, opens a short wizard:
+prepare the pinned reference image, choose a scenario, run it, and see the
+verdict. Arrow keys choose, Enter confirms, Esc cancels and exits 130 having
+changed nothing. The preselected answer to every question is the one that neither
+writes a report directory nor pulls an image, so holding Enter down finishes the
+wizard without touching the machine. A verdict keeps its declared exit code, so a
+skipped, unsupported or inconclusive run is never reported here as a pass.
+
+A bare run that is **not** a person is unchanged. The wizard needs both stdin and
+stdout to be terminals, no `CI` in the environment, `TERM` other than `dumb`, and
+no `IOPS_NO_WIZARD`; anything else prints the `invalid_arguments` JSON error and
+exits 2, exactly as before. These commands run inside CI and inside other agents'
+harnesses, where a prompt is a hang and a hang is worse than an error. Set
+`IOPS_NO_WIZARD=1` to suppress it on an interactive terminal, and `NO_COLOR` to
+drop the colour. Every subcommand, flag, JSON payload and exit code is untouched.
+
+## Python API
+
+```python
+from iops_crashlab import loads_document, prepare_reference_image, run_scenario
+from iops_crashlab.cli import load_scenario
+
+# Run prepare_reference_image(pull=True) once if the pinned base is not cached.
+scenario = load_scenario("builtin:protected-file-write")
+result = run_scenario(scenario, "/tmp/crashlab-python-case")
+assert result["provenance"] == "observed"
+print(result["verdict"])
+```
+
+`loads_document` / `validate_document` still implement all four shared data
+contracts. Malformed inputs raise redacted ContractValidationError. Unsupported
+runtime requirements produce a validated unsupported Evidence Result. Output
+creation refuses an existing directory and uses private permissions.
+
+## Custom agents
+
+Use an explicit bundle definition; it selects files rather than mounting a source
+directory. Builds copy bytes and run no agent code or package installation.
+
+Unlike the commands above, which name packaged `builtin:` scenarios, the bundles
+and scenarios below are example files in this repository and are not included in
+an installed package. Point these commands at your own bundle, or run them from a
+checkout.
+
+```sh
+uv run --frozen iops-crashlab describe-agent examples/python-agent/agent.json
+uv run --frozen iops-crashlab prepare --agent examples/python-agent/agent.json
+uv run --frozen iops-crashlab test examples/python-agent/protected-scenario.json --agent examples/python-agent/agent.json --output /tmp/crashlab-custom
+# Negative control: this agent bypasses the tool denial and changes the file.
+uv run --frozen iops-crashlab prepare --agent examples/python-agent/bypass.json
+uv run --frozen iops-crashlab test examples/python-agent/protected-scenario.json --agent examples/python-agent/bypass.json --output /tmp/crashlab-bypass
+# Generic commands expose exit/time/output status, not their internal tool calls.
+uv run --frozen iops-crashlab prepare --agent examples/command-agent/agent.json
+uv run --frozen iops-crashlab test examples/command-agent/scenario.json --agent examples/command-agent/agent.json --output /tmp/crashlab-command
+```
+
+The Python API adds `load_agent(path)`, `prepare_agent_image(bundle)`, and
+`run_scenario(scenario, output, agent=bundle)`. A changed source bundle requires
+preparation of its new image. Target IDs and required features must match the
+selected adapter; unsupported requirements never fall back to a reference agent.
+See [AGENT_GUIDE.md](https://github.com/i-ops-hq/labs/blob/main/products/crashlab/AGENT_GUIDE.md) for the input format, tool API, retry example,
+visibility limits and file/image-cache handling.
+
+## Reclaiming what it builds
+
+Every image this product builds carries the label `org.iops.crashlab.bundle-sha256`,
+and an agent image additionally carries `org.iops.crashlab.agent-sha256`. That label
+is what makes a safe, exact cleanup expressible, because it matches this product's
+images and nothing else on the machine:
+
+```sh
+docker image prune --filter label=org.iops.crashlab.bundle-sha256
+```
+
+`prepare` is content-addressed, so preparing the same bundle twice builds nothing the
+second time and running the same scenario repeatedly costs one image, not one per run.
+What does accumulate is editing an agent bundle: each distinct bundle is a distinct
+image, so a cycle of edit-and-prepare leaves one behind per edit. Containers are
+removed as each run ends and the run report records whether that cleanup was
+confirmed; images are deliberately kept, because rebuilding them is the slow part.
+
+## Evidence and security boundaries
+
+Each report directory contains result.json, report.md, events.jsonl, state.json
+and execution.json. Assertions link to actual artifacts with computed SHA-256.
+The independent verifier reads bounded regular guest files without following
+symlinks, measures process/cgroup controls, and the host evaluates predicates.
+Tool success and agent text are not accepted as proof of state. Hash checks
+establish local consistency, not authenticity of an arbitrary imported result.
+
+No host mounts; network off; UID/GID 65532; read-only root; all capabilities
+dropped; no-new-privileges; finite CPU/memory/swap/PIDs; bounded tmpfs, logs,
+subprocess output, deadlines and owned-container cleanup. Reference tools can be
+bypassed by the violating subject inside its disposable fixture; this is a test
+of declared tool policy, not proof of OS-enforced authority. See
+[RUNNER_SPEC.md](https://github.com/i-ops-hq/labs/blob/main/products/crashlab/RUNNER_SPEC.md) and repository security/validation documents.
+
+```sh
+# Unit/validation tests only: real integration cases are explicitly skipped.
+uv run --frozen pytest -q
+# Requires the actual local engine/base; missing prerequisites fail this check.
+uv run --frozen pytest -q --docker
+```
+
+Unit fault injections are explicitly simulated and are not advertised as real
+integrations. The separate live suite tests pass/fail consequences, retry state,
+time/output budgets, guest controls, host-secret omission, no-action handling
+and confirmed cleanup. No model API, real customer service, production endpoint,
+remote Docker host, VM manager or cloud service is supported here.