@zhivex-ai/harness 0.8.0 → 0.10.0

package/docs/CHANGE_ENVELOPES.md

@@ -0,0 +1,116 @@
+# Change envelopes
+
+Zhivex Harness `0.9.x` adds `ChangeEnvelope v1`: a content-addressed change-admission document that can be produced by any coding agent and verified offline before another system accepts its patch artifact. It is a portable evidence contract, not a new patch format and not a replacement for the harness approval/import boundary.
+
+## What it proves
+
+An envelope binds these values into one canonical SHA-256 identifier:
+
+- the logical workspace and exact source-tree digests supplied by the producer;
+- an artifact identifier and the SHA-256 digest of the exact patch bytes;
+- harness, policy, and execution-environment fingerprints;
+- structured check status, timing, exit code, and optional digests of redacted output or the check runner;
+- optional expiry, approval references/scopes, and external-attestation references.
+
+Verification checks the strict schema, canonical envelope and evidence digests, rejects a future creation time, enforces expiry, exact patch bytes, and any caller-supplied preconditions. A check cannot complete after the envelope is created. Raw command output, prompts, approval reasoning, and credentials are intentionally not representable.
+
+## Create and verify
+
+The CLI is provider-free and performs no network requests. `create` reads the exact patch bytes, computes `patch.patchDigest`, rejects a conflicting declared digest, and writes canonical JSON to stdout:
+
+```bash
+zhx changes create examples/change-envelope-input.json \
+  --patch examples/change.patch > change-envelope.json
+```
+
+Verify the envelope against those same bytes:
+
+```bash
+zhx changes verify change-envelope.json \
+  --patch examples/change.patch
+```
+
+Verification returns a `change-envelope-verification` JSON document. Exit `0` means every integrity, expiration, and supplied-precondition check passed; exit `1` means the document is well-formed enough to report but is not admissible. Invalid CLI syntax or an unreadable/non-JSON artifact returns exit `2`.
+
+For deterministic replay, `--now <ISO-8601>` selects the verification instant. Production admission should normally omit it and use the current clock.
+
+## Input contract
+
+The creation input is strict JSON:
+
+```json
+{
+  "createdAt": "2026-08-20T12:00:00.000Z",
+  "expiresAt": "2026-08-21T12:00:00.000Z",
+  "base": {
+    "workspaceDigest": "sha256:...",
+    "treeDigest": "sha256:..."
+  },
+  "patch": {
+    "patchId": "candidate-42"
+  },
+  "fingerprints": {
+    "harness": "sha256:...",
+    "policy": "sha256:...",
+    "environment": "sha256:..."
+  },
+  "checks": [
+    {
+      "checkId": "tests",
+      "status": "passed",
+      "redacted": true,
+      "startedAt": "2026-08-20T11:59:00.000Z",
+      "completedAt": "2026-08-20T11:59:01.000Z",
+      "durationMs": 1000,
+      "exitCode": 0,
+      "redactedOutputDigest": "sha256:..."
+    }
+  ]
+}
+```
+
+The CLI fills `patchDigest` from `--patch`; the library-level `createChangeEnvelope` input requires it explicitly. Timestamps use millisecond-precision ISO-8601 UTC. Checks, approvals, scopes, and attestations are sorted canonically, so semantically identical set-like inputs produce the same envelope ID.
+
+`workspaceDigest` identifies the governed workspace/scope chosen by the producer. `treeDigest` identifies the exact base tree to which the candidate applies. The envelope validates that these are SHA-256 values and binds them, but it does not guess their meaning or compute them from a Git repository: the admission system must supply and verify the correct values for its own source-control model.
+
+## Verification preconditions
+
+Pass a strict JSON object with `--preconditions` when an admission system has expected values:
+
+```json
+{
+  "baseTreeDigest": "sha256:...",
+  "harnessFingerprint": "sha256:...",
+  "policyFingerprint": "sha256:...",
+  "environmentFingerprint": "sha256:...",
+  "requiredPassedChecks": ["tests", "typecheck"],
+  "requiredApprovalScopes": ["workspace:write", "checks:accept"],
+  "requiredAttestationDigests": ["sha256:..."]
+}
+```
+
+Supported preconditions cover the envelope ID, workspace/tree, patch ID/digest, harness/policy/environment, evidence digest, required passing check IDs, active approval digests/scopes, and referenced external-attestation bundle digests. The CLI always adds the digest of the exact `--patch` bytes and rejects a conflicting value in the precondition file. A recorded failed or skipped check is evidence, but it satisfies no `requiredPassedChecks` entry.
+
+## Authenticity boundary
+
+`ChangeEnvelope v1` is content-addressed, not signed. Anyone who can replace an envelope can recompute its SHA-256 identifiers. The verifier therefore reports:
+
+```text
+verificationScope = integrity-expiration-and-preconditions-only
+approvals.authenticity = not-verified
+externalAttestations.authenticity = not-verified
+```
+
+An `externalAttestations` entry binds only an attestation ID, format, media type, and bundle digest. Validate the referenced Sigstore, in-toto, SLSA, or organization-specific bundle with its native trust policy, then pass its expected digest as an admission precondition. Never treat a recorded approval reference as proof of who approved it.
+
+## Library API
+
+The package exports `createChangeEnvelope`, `verifyChangeEnvelope`, `canonicalizeChangeEnvelope`, `digestChangeEnvelopeArtifact`, the digest recomputation helpers, strict Zod schemas, and all corresponding TypeScript types. This keeps the contract agent-agnostic: a CI gate, code-review bot, local harness, or deployment controller can produce or consume the same document.
+
+## Known limits
+
+- The CLI binds a supplied patch artifact but does not apply it, infer a Git base, run checks, or mint approvals.
+- Check evidence is a redacted summary supplied by the producer; a trusted runner fingerprint or external attestation is needed when provenance matters.
+- Creation-time and expiration decisions depend on the verifier's clock.
+- SHA-256 integrity does not provide signer identity, transparency logging, revocation, or policy authorization.
+- The v1 contract supports bounded UTF-8 JSON metadata and a patch artifact of at most 64 MiB; large binary release artifacts need a separate artifact policy.

package/docs/CLI.md

@@ -1,6 +1,6 @@
 # CLI contract
 
-Zhivex Harness `0.8.x` is Bun-first and exposes a durable agent console plus versioned JSON documents and JSON Lines events for automation.
+Zhivex Harness `0.10.x` is Node-first and exposes a durable agent console, offline change-envelope operations, plus versioned JSON documents and JSON Lines events for automation. Bun remains a supported target-repository package manager and contributor tool.
 
 ## Commands
 
@@ -21,6 +21,8 @@ zhivex-harness runs inspect <runId>
 zhivex-harness runs export <runId>
 zhivex-harness runs cancel <runId> [--reason <text>] [--cascade] [--final]
 zhivex-harness runs cleanup --before <date|timestamp> [--status <status>] [--limit <n>]
+zhivex-harness changes create <input.json> --patch <artifact>
+zhivex-harness changes verify <envelope.json> --patch <artifact> [--preconditions <file>] [--now <ISO-8601 UTC>]
 zhivex-harness --version
 zhivex-harness --help
 ```
@@ -47,13 +49,13 @@ Provider/model changes apply only to the next run. The console blocks them while
 
 `/resume` selects a conversation session; it does not approve a run. A pending approval still requires the explicit operator command `zhx resume <runId> --approve` or `--deny`.
 
-`doctor` is local and makes no provider or MCP request. It checks the Bun version, workspace, Git, supported package scripts, state-directory safety, provider credential presence, endpoint shape, provider configuration, the local MCP configuration file, and—when requested—the OCI runtime and preloaded image without returning secret or endpoint values.
+`doctor` is local and makes no provider or MCP request. It checks the active Node/Bun runtime, detected repository package manager, workspace, Git, supported package scripts, state-directory safety, provider credential presence, endpoint shape, provider configuration, the local MCP configuration file, and—when requested—the OCI runtime and preloaded image without returning secret or endpoint values.
 
 `--allow-check <script>` is repeatable and replaces the default check allowlist for that invocation. Values are declared `package.json` script names, never command text.
 
 `--require-capability <name>`, `--subagent <profile>`, and `--reviewer <explorer|reviewer>` are repeatable. `--mcp-config <path>` loads a schema-versioned file inside the canonical workspace. Child limits use `--subagent-max-steps`, `--subagent-max-tool-calls`, `--subagent-max-tool-errors`, `--subagent-max-input-tokens`, `--subagent-max-output-tokens`, `--subagent-max-total-tokens`, and `--subagent-timeout-ms`. Parallel review is capped by `--max-parallel-reviews`.
 
-`--route <profile=provider[:model]>` is repeatable for `explorer`, `implementer`, `tester`, and `reviewer`. Omit the model to use that provider's default. Duplicate roles and unknown providers fail before a model is created. Only routed roles are instantiated. `--max-cost-usd` cannot be combined with routes in `0.8.x`, because the current budget has one operator-supplied price pair and cannot price heterogeneous child usage accurately.
+`--route <profile=provider[:model]>` is repeatable for `explorer`, `implementer`, `tester`, and `reviewer`. Omit the model to use that provider's default. Duplicate roles and unknown providers fail before a model is created. Only routed roles are instantiated. `--max-cost-usd` cannot be combined with routes in `0.10.x`, because the current budget has one operator-supplied price pair and cannot price heterogeneous child usage accurately.
 
 `review` is application-owned parallelism and accepts only read-only explorer/reviewer members. Model-directed delegation occurs only inside `run` or `chat` when the parent invokes an enabled `delegate_<profile>` tool.
 
@@ -74,14 +76,22 @@ Enforced execution is opt-in:
 --oci-tmpfs-mb <n>
 ```
 
-`--oci-allow-command` is repeatable, replaces the default executable allowlist, and must include `bun` so declared package checks can run. Commands are exact argv arrays, never shell strings. See [EXECUTION_ENVIRONMENTS.md](./EXECUTION_ENVIRONMENTS.md).
+`--oci-allow-command` is repeatable, replaces the default executable allowlist, and must include at least one supported repository package manager: `npm`, `pnpm`, `yarn`, or `bun`. The default is `node,npm`; custom images must still provide Node for the internal controller. Commands are exact argv arrays, never shell strings. See [EXECUTION_ENVIRONMENTS.md](./EXECUTION_ENVIRONMENTS.md).
+
+## Change admission
+
+`changes create` and `changes verify` are local operator commands. They do not load a provider, inspect a repository, run checks, apply a patch, or contact a network service. Both require `--patch <artifact>` so the envelope is checked against exact bytes rather than a filename or mutable logical ID.
+
+`create` accepts a strict JSON input, fills `patch.patchDigest`, and emits one canonical `change-envelope` JSON document. `verify` emits a `change-envelope-verification` document and can require expected bindings through `--preconditions <file>`. It returns exit `1` for an integrity, expiration, exact-patch, or precondition failure. `--now` exists for deterministic replay; omit it for normal admission.
+
+The verifier never claims signer identity. Approval and attestation references remain `authenticity: "not-verified"` until an external trust verifier validates the referenced artifact. See [CHANGE_ENVELOPES.md](./CHANGE_ENVELOPES.md).
 
 ## Exit codes
 
 | Code | Meaning |
 | --- | --- |
 | `0` | Command completed successfully. |
-| `1` | Runtime, provider, or agent failure. |
+| `1` | Runtime, provider, agent, or change-admission verification failure. |
 | `2` | Invalid CLI usage. |
 | `3` | `doctor` found a blocking configuration problem. |
 
@@ -98,7 +108,7 @@ All structured documents include:
 ```json
 {
   "schemaVersion": 1,
-  "kind": "providers | doctor | run-result | review-group | run-list | run-inspection | run-export | run-cancellation | run-cleanup | session-list | session"
+  "kind": "providers | doctor | run-result | review-group | run-list | run-inspection | run-export | run-cancellation | run-cleanup | session-list | session | change-envelope | change-envelope-verification"
 }
 ```
 

package/docs/DURABLE_OPERATIONS.md

@@ -1,6 +1,6 @@
 # Durable operations
 
-Zhivex Harness durable operations make local runs inspectable and recoverable across process restarts. The default store is Bun SQLite at `<workspace>/.zhivex-harness/runs/operations.sqlite`; `--store file` remains a migration fallback.
+Zhivex Harness durable operations make local runs inspectable and recoverable across process restarts. The default store is runtime-portable SQLite at `<workspace>/.zhivex-harness/runs/operations.sqlite`, backed by `node:sqlite`; `--store file` remains a migration fallback. The `0.10.x` runtime change does not alter the SQLite file or table format.
 
 ## Scope and identity
 
@@ -47,7 +47,7 @@ zhivex-harness runs cleanup --before 2026-08-01T00:00:00Z
 
 ## Durable CLI sessions
 
-The `0.8.x` console maintains a scoped session index in prefixed tables inside `operations.sqlite`. A session is an ordered chain of immutable run references; it is not a mutable provider run. The index stores session ID/title, parent/fork metadata, run ID, provider, model, role, status, and timestamps. It never stores prompts, messages, tool calls/results, approval arguments, provider data, or environment values.
+The console maintains a scoped session index in prefixed tables inside `operations.sqlite`. A session is an ordered chain of immutable run references; it is not a mutable provider run. The index stores session ID/title, parent/fork metadata, run ID, provider, model, role, status, and timestamps. It never stores prompts, messages, tool calls/results, approval arguments, provider data, or environment values.
 
 ```bash
 zhx chat
@@ -66,7 +66,7 @@ The store uses SQLite WAL transactions, optimistic revisions, workspace/scope ha
 
 Every console turn preallocates a new run ID and binds it permanently to one provider/model. Provider or model changes take effect only on the next run and are blocked while an approval is pending. Before transferring context to another provider/model, the console creates a bounded deterministic redacted summary: text is truncated and common credentials are removed, while tool inputs, outputs, and provider payloads are replaced by tool/type names.
 
-Per-role routes are stored as non-secret provider/model metadata in the durable resume envelope so an approval restart reconstructs the same subagent models and fingerprint. A route never performs in-run failover. Heterogeneous routes cannot be combined with the single-price `--max-cost-usd` contract in `0.8.x`.
+Per-role routes are stored as non-secret provider/model metadata in the durable resume envelope so an approval restart reconstructs the same subagent models and fingerprint. A route never performs in-run failover. Heterogeneous routes cannot be combined with the single-price `--max-cost-usd` contract in `0.10.x`.
 
 ## Budgets
 
@@ -104,6 +104,20 @@ The default compactor activates at 60 messages or an estimated 40,000 input toke
 
 Operational artifacts are schema version `1`. By default they exclude raw messages, tool inputs, tool outputs, approval arguments, run metadata, and full output text. Traces, ledger previews, and journal errors apply the production secret/email redaction policy. This is a defensive export boundary, not a guarantee that arbitrary model-generated prose can never contain sensitive business data; control prompt contents and workspace permissions accordingly.
 
+## Migration from 0.9.x
+
+Before invoking `0.10.x`, install Node.js `22.13.0` or newer; Bun is no longer required to run the packaged CLI. Back up the state directory, then complete or deny paused approvals with the exact `0.9.x` artifact that created them before installing the exact `0.10.x` artifact. After upgrading, run `zhx doctor`, `zhx runs list`, and `zhx sessions list` against the same workspace and scope.
+
+`0.10.0` keeps configuration schema `4`, final JSON schema `1`, all durable table names, and the SQLite file format. The runtime now opens the same database through `node:sqlite`, so existing `operations.sqlite` files require no conversion or export/import step.
+
+Paused `0.9.x` approvals remain bound to their original harness version, tool contract, and execution policy; `0.10.x` intentionally rejects an incompatible resume. Completed `0.9.x` runs and sessions remain available for redacted inspection, while new runs select npm, pnpm, Yarn, or Bun from the repository's pinned `packageManager` or unambiguous lockfile. Bun-managed repositories should keep an explicit `packageManager` field or one Bun lockfile; OCI runs also need a Node-capable image and the selected package manager in the executable allowlist.
+
+## Migration from 0.8.x
+
+`0.9.0` retains configuration schema `4`, final JSON schema `1`, session tables, run-store layout, provider defaults, and both executable aliases. The new change-envelope commands are provider-free and do not add persisted run state.
+
+The repository tool fingerprint changes because `read_files` and `search_many` join the read-only surface. Resolve or deny paused `0.8.x` approvals with the matching `0.8.x` artifact; `0.9.x` intentionally rejects a resume whose harness version or tool contract differs. Completed `0.8.x` runs remain available to redacted operator inspection, and new `0.9.x` sessions can start normally.
+
 ## Migration from 0.7.x
 
 `0.8.0` keeps configuration schema version `4`, final JSON schema `1`, session storage, CLI commands, and both executable aliases. The OpenAI default changes from `gpt-5.4` to `gpt-5.6-luna`; pass an explicit model when retaining the previous behavior is required.

package/docs/EXECUTION_ENVIRONMENTS.md

@@ -8,7 +8,7 @@ This is a local enforced runner. It is not a hosted sandbox, a virtual machine,
 
 The harness trusts the operator, host OS, Docker or Podman daemon, configured image, Zhivex packages, and its own state directory. The model and code executed in the container are outside that trust boundary.
 
-The OCI policy is enforced per tool call with:
+The OCI policy is enforced for one acquired run session, with each command committed as a separate validated transaction:
 
 - `--network none`;
 - a read-only container root filesystem;
@@ -17,7 +17,7 @@ The OCI policy is enforced per tool call with:
 - a size-bounded writable `tmpfs` at `/workspace` plus a separate bounded `tmpfs` at `/tmp`;
 - an optional host `node_modules` directory mounted read-only at `/dependencies` and linked into the container workspace;
 - exact argv execution through the configured entrypoint, with no shell interpolation;
-- a fixed container environment containing only `HOME`, `TMPDIR`, `BUN_INSTALL_CACHE_DIR`, and `CI`;
+- a fixed container environment containing only `HOME`, `TMPDIR`, `NPM_CONFIG_CACHE`, and `CI`;
 - time, output, memory, CPU, PID, workspace-size, and per-file patch limits.
 
 The snapshot is populated through the normal bounded workspace discovery contract. Git internals, harness state, dependency/build output, `.env`, `.npmrc`, private keys, secret-like paths, external symlinks, and special files are not copied. Provider credentials and arbitrary host environment variables are never passed to the container.
@@ -29,7 +29,7 @@ When the backend is disabled, these OCI claims do not apply. The harness respond
 Preload the image intentionally; the harness never pulls or updates images:
 
 ```bash
-docker pull oven/bun:1.3.7-slim
+docker pull node:24-bookworm-slim
 bun run dev doctor --execution oci
 bun run dev run --execution oci --yes "implement the change, test it, inspect the environment patch, and import it"
 ```
@@ -40,8 +40,8 @@ Podman is also supported through `--oci-runtime podman`. Defaults are:
 | --- | ---: |
 | Backend | `none` |
 | Runtime | `docker` |
-| Image | `oven/bun:1.3.7-slim` |
-| Allowed commands | `bun` |
+| Image | `node:24-bookworm-slim` |
+| Allowed commands | `node,npm` |
 | Process time | 120,000 ms |
 | Retained process output | 20,000 bytes |
 | Memory | 1,024 MB |
@@ -68,7 +68,7 @@ ZHIVEX_HARNESS_OCI_MAX_FILE_WRITE_BYTES
 ZHIVEX_HARNESS_OCI_TMPFS_MB
 ```
 
-`ZHIVEX_HARNESS_OCI_ALLOWED_COMMANDS` is comma-separated. `bun` is mandatory because `run_check` invokes declared scripts as `bun --no-env-file run <script>`. Adding an executable permits that bare entrypoint but does not add a shell or wildcard. Each environment command still requires normal high-risk interrupt approval unless the operator deliberately supplied `--yes`.
+`ZHIVEX_HARNESS_OCI_ALLOWED_COMMANDS` is comma-separated and must include at least one supported package manager (`npm`, `pnpm`, `yarn`, or `bun`). `run_check` selects the manager from `packageManager` or one unambiguous lockfile and defaults to npm. Adding an executable permits that bare entrypoint but does not add a shell or wildcard. The configured image must always provide Node for the internal controller; Bun-managed repositories additionally need a Node-and-Bun image and `bun` in the allowlist. Each environment command still requires normal high-risk interrupt approval unless the operator deliberately supplied `--yes`.
 
 The image is inspected before model construction. Its immutable image ID/digest, runtime/server version, complete policy, canonical workspace identity, and environment manifest contribute to the run binding. A missing daemon/image fails before model execution. A changed image or policy makes a paused resume fail closed.
 
@@ -79,12 +79,22 @@ The acquired environment contains two owner-only copies under `<state-dir>/envir
 - `base`: the immutable comparison snapshot;
 - `workspace`: the mutable snapshot used by repository tools and containers.
 
-For each successful command, the harness seeds a fresh, size-bounded `/workspace` tmpfs from the durable snapshot, pauses the container, copies the result into a new owner-only staging directory, rejects symlinks, hard links, special files, oversized workspaces, excessive entries, and oversized changed files, then atomically replaces the durable snapshot. The host snapshot is never mounted writable into an untrusted container. Failed, cancelled, timed-out, or output-limited commands do not publish partial filesystem mutations.
+In `0.9.x`, acquisition keeps only a bounded metadata inventory in memory, writes each verified source file to `base` once, and creates `workspace` with filesystem copy-on-write cloning when available. Unsupported filesystems fall back to an independent normal copy. Patch comparison inventories both trees but rereads file content only for paths whose digest or mode changed. This changes host I/O and memory use, not the two-copy trust model: mutations in `workspace` remain observable as a patch against `base` and never mutate `base`.
+
+`environment_status` includes cumulative `io` counters for inventory passes/pages, verified content reads/bytes, snapshot files/bytes, clone fallbacks, container starts/reuses, successful workspace publications, and changed-workspace exports. They are diagnostics for profiling and regression tests, not admission evidence or a stable performance guarantee.
+
+The first command seeds a size-bounded `/workspace` tmpfs from the durable snapshot and subsequent successful commands reuse that run container while the host snapshot fingerprint remains unchanged. The controller-only container remains warm with the same CPU, memory, PID, capability, filesystem, and network restrictions. A command cycle executes argv, rejects surviving background processes before and after sealing, clears `/tmp`, and computes a canonical workspace seal inside one framed attestation. `run_environment_batch` applies the same checks to a reviewed sequence, stops on the first failure, and pays one final seal/publication cycle. An unchanged seal takes a no-export fast path. A changed seal copies `/workspace` out through the runtime into a new owner-only staging directory, rejects symlinks, hard links, special files, oversized workspaces, excessive entries, and oversized changed files, then atomically replaces the durable snapshot. The host snapshot is never mounted writable into an untrusted container.
+
+Failed, cancelled, timed-out, output-limited, invalid, or background-spawning commands do not publish partial workspace mutations: their container and tmpfs volume are destroyed. A later command reseeds from the last durable snapshot. Repository-tool changes made outside the container alter the host-side snapshot fingerprint, which likewise discards the warm container and reseeds before execution. This preserves one durable source of truth instead of silently carrying stale container state.
 
 `inspect_environment_patch` compares them deterministically and returns a run-bound patch identifier plus create/update/delete entries, content digests, and before/after permission modes. Content-identical mode changes remain visible, and modes are part of the reviewed `patchId`. It rejects binary changes, more than 50 files, a patch above 4 MiB, or a file above the configured import ceiling.
 
 `apply_environment_patch` is a different high-risk tool and approval. Immediately before import it recomputes the patch identifier and verifies every host precondition against the digest and mode captured at acquisition. Creates must still be absent; updates and deletes must still match. Writes publish content and mode atomically, including newly created executable files and mode-only updates; rollback restores both. Deletions use recoverable quarantine, and a deletion failure triggers best-effort rollback. The host remains unchanged until this import succeeds.
 
+`verify_and_apply_environment_patch` provides a stricter combined path when the caller already knows the exact verifier argv. One interrupt approval binds the inspected `patchId`, executable, and arguments. The harness rechecks the patch, runs the allowlisted verifier inside OCI, requires exit code zero, recomputes the patch ID to reject verifier-created drift, and only then imports it with the same host precondition and rollback rules. A failed verifier or changed patch leaves the host untouched.
+
+`verify_and_apply_reviewed_edits` collapses the preceding edit and publication sequence when the OCI snapshot is still clean. One interrupt approval binds every path, expected host digest, complete replacement content, executable, and argument. The harness applies exactly those edits to the snapshot, rejects additional patch paths, verifies inside OCI, rejects patch drift, and imports only the successful content-bound patch. Applications may explicitly designate this tool as terminal in `runHarness`; the runtime then validates the approval binding and optional signature, executes through OCI authorization and the durable tool journal, persists the completed receipt, and returns without another provider call. If that terminal tool rejects a stale edit digest, the runtime journals the approved failure, destroys the unpublished OCI session, and resumes the model with the error result. A corrected digest or edit is a new tool call with a new content-bound approval; the runtime never rewrites or silently reapproves the failed request. Other terminal failures still stop the run because their side-effect status may be uncertain.
+
 Because repository tools are snapshot-scoped while OCI is active, `apply_patch`, moves, quarantine, and restore alter only the snapshot. The model-facing `git_diff` tool is omitted in this mode because it would read the canonical host outside the environment boundary; the caller still receives the canonical final host Git status/diff after any approved import.
 
 ## Resource and network policy
@@ -99,7 +109,7 @@ PID limits are the primary fork-bomb control. Memory and CPU limits constrain re
 
 Environment artifacts are keyed by a hash of the durable run ID and include an owner-only metadata file bound to that exact run, workspace, environment fingerprint, and image. Reacquisition reuses the same snapshot only when every binding matches.
 
-Each runtime container and temporary workspace volume carries `com.zhivex.harness.execution=v1` and a hashed run label. Session release force-removes resources for that run and records the terminal status and release timestamp. `runs cleanup --before <cutoff>` removes only released terminal artifact directories older than the cutoff; with OCI configured it also removes labeled containers in `created`, `exited`, `dead`, or `paused` state and unused labeled volumes. Unknown directories, symlinks, active resources, and unlabeled OCI resources are skipped.
+Each runtime container and temporary workspace volume carries `com.zhivex.harness.execution=v1` and a hashed run label; warm containers also carry the local controller PID. Between successful commands the container runs only its inert controller under the enforced limits. Session release force-removes all resources for that run before recording status and release time. `runs cleanup --before <cutoff>` removes only released terminal artifact directories older than the cutoff; with OCI configured it removes labeled stopped containers, running containers whose recorded local controller process no longer exists, and unused labeled volumes. Running containers owned by a live controller, unknown directories, symlinks, active volumes, and unlabeled OCI resources are skipped.
 
 Crash recovery relies on the same labels and durable artifacts. An operator can rerun cleanup after a process crash. The harness does not issue broad container/volume prune commands and never deletes an unlabeled OCI resource.
 
@@ -111,18 +121,26 @@ The default backend remains `none`, so upgrades do not unexpectedly start a cont
 
 Applications constructing the harness can inject a `HarnessOciRuntimeAdapter` for a controlled runtime implementation. They should use the exported SDK environment rather than bypassing authorization or importing snapshot files directly.
 
+## Migration from 0.9.x
+
+The `0.10.x` execution policy advances to `2026-08-21-v3`, changes the default image from Bun to Node 24, and makes repository checks package-manager-aware. Complete paused `0.9.x` environment approvals with their original artifact; the changed image, allowlist, controller, and policy fingerprint intentionally prevent a silent resume under `0.10.x`. Durable SQLite state remains readable without conversion.
+
 ## Certification
 
-The deterministic tests use an injected runtime to cover acquisition, secret exclusion, snapshot-only mutation, patch binding/import, separate approvals, image-fingerprint resume rejection, release, and safe artifact cleanup. The installed-package smoke imports the public OCI API and proves that a consumer can perform the same snapshot/import flow.
+The deterministic tests use an injected runtime to cover acquisition, secret exclusion, snapshot-only mutation, patch binding/import, separate and combined approvals, failed-verifier non-import, image-fingerprint resume rejection, release, and safe artifact cleanup. The installed-package smoke imports the public OCI API and proves that a consumer can perform the same snapshot/import flow.
+
+`bun run smoke:oci` exercises a real Docker/Podman daemon and preloaded image. It verifies secret exclusion, denied outbound network, denied root-filesystem writes, warm-container reuse, host-tool reseeding, background-process rejection, snapshot mutation, enforced workspace capacity, package checks, host non-mutation before import, approved import, cancellation, release, orphan cleanup, and artifact retention cleanup. The smoke skips locally when no daemon is available unless `ZHIVEX_HARNESS_OCI_REQUIRED=1`; Linux CI, release validation, and live certification set that variable so absence is a failure.
+
+`bun run benchmark:oci -- --files 1000 --commands 20 --batch-commands 5 --repetitions 10 --warmups 1` runs isolated sessions sequentially and reports nearest-rank p50/p95/p99, success rates, host/runtime metadata, runtime-I/O counters, and runtime-reported command-phase attribution. Its end-to-end TTI is measured from the start of OCI environment inspection through the successful response from the first command. The reported phases are environment/image inspection, workspace snapshot and session acquisition, first command/container start, reused no-op commands, one multi-command batch sharing a final attestation, and mutation validation/publication; command attribution further separates host synchronization, session creation, command plus attestation, attestation copy, and workspace export when those phases apply. Fixture creation, `Workspace.open`, final release, and cleanup are excluded. Host filesystem caches are not flushed. Use at least 100 successful samples before treating p99 as representative.
 
-`bun run smoke:oci` exercises a real Docker/Podman daemon and preloaded image. It verifies secret exclusion, denied outbound network, denied root-filesystem writes, snapshot mutation, enforced workspace capacity, package checks, host non-mutation before import, approved import, cancellation, release, orphan cleanup, and artifact retention cleanup. It skips locally when no daemon is available unless `ZHIVEX_HARNESS_OCI_REQUIRED=1`; Linux CI, release validation, and live certification set that variable so absence is a failure.
+`bun run benchmark:workspace -- --files 50000 --page-size 200 --repetitions 10 --warmups 2` separately reports path-only topology listing and digest-bound listing, then compares three independent missing-token searches with `searchMany`. Every repetition opens fresh topology and digest-bound `Workspace` instances: the first-page measurement builds each application index, later phases reuse it, and the paired search order alternates. Warmups prime only the runtime and host filesystem cache. Fixture creation and `Workspace.open` are excluded. Results intended for comparison must include the commit, exact command, host, runtime versions, and OCI image digest where applicable.
 
 Provider certification is separate and billable. The live workflow runs the required OCI gate before the model-directed Meta, Qwen, and OpenAI matrices. A deterministic OCI pass does not by itself certify a provider, and live provider success does not replace exact installed-artifact or published-registry proof.
 
 ## Known limits
 
 - Docker and Podman use different host security implementations; current gates certify behavior, not identical internals.
-- The default Bun image and read-only host `node_modules` mount optimize JavaScript/TypeScript checks. Other ecosystems need an explicit image and executable allowlist, and dependencies should be prepared without exposing secrets.
+- The default Node image and read-only host `node_modules` mount optimize npm-managed JavaScript/TypeScript checks. pnpm, Yarn, Bun, and other ecosystems need an explicit Node-capable image and executable allowlist, and dependencies should be prepared without exposing secrets.
 - The local container daemon, kernel, image, and mounted dependency tree remain trusted. This backend is not a microVM boundary.
 - Network is deny-only in this policy version. Domain allowlists, package installation, browser automation, and network MCP require a future policy/backend rather than an implicit exception.
 - Patch import accepts bounded UTF-8 text changes only. Binary artifacts and large generated trees must use a future reviewed artifact-transfer contract.

package/docs/EXTENSIBILITY.md

@@ -1,6 +1,6 @@
 # Extensibility and orchestration
 
-Zhivex Harness `0.8.x` combines governed external tools and bounded multi-agent work with a public provider registry and explicit per-role model routing. Configuration schema remains version `4`; registry selection, runtime model capabilities, routed child models, non-secret provider transport settings, MCP, execution policy, budgets, and scope are bound into the durable harness fingerprint.
+Zhivex Harness `0.10.x` combines governed external tools and bounded multi-agent work with a public provider registry and explicit per-role model routing. Configuration schema remains version `4`; registry selection, runtime model capabilities, routed child models, non-secret provider transport settings, MCP, execution policy, budgets, and scope are bound into the durable harness fingerprint.
 
 ## Provider registry
 
@@ -84,7 +84,7 @@ Four profiles are enabled by default:
 | --- | --- | --- |
 | `explorer` | Repository discovery and evidence | Read-only workspace inspection |
 | `implementer` | One bounded implementation task | Workspace tools; mutations remain approval-gated |
-| `tester` | Focused verification | Read-only inspection plus approved Bun checks |
+| `tester` | Focused verification | Read-only inspection plus approved repository package-manager checks |
 | `reviewer` | Independent correctness/security review | Read-only diff and audit inspection |
 
 Select an explicit subset with repeatable flags:
@@ -119,7 +119,7 @@ The resolved route plan is persisted without credentials in CLI resume metadata
 ## Routing limits
 
 - There is no automatic failover inside a run and no provider change while an approval is pending.
-- `--max-cost-usd` with any route is rejected because `0.8.x` has one operator-supplied price pair, not pricing per model/run.
+- `--max-cost-usd` with any route is rejected because `0.10.x` has one operator-supplied price pair, not pricing per model/run.
 - Routing does not infer speed, quality, price, or a “best” provider; presets remain deferred until the model catalog contains reliable evidence.
 - The CLI registry is static. Applications may inject a validated registry through the TypeScript API, but configuration files cannot load arbitrary provider modules.
 - Cross-provider console context uses deterministic redacted compaction and omits tool/provider payloads; it is a portable summary, not a byte-identical transcript handoff.

package/docs/HOSTILE_REPOSITORY_DEMO.md

@@ -7,7 +7,7 @@ The hostile-repository demo is a reproducible product proof for the governed cha
 One run exercises the real harness contracts in this order:
 
 1. create a secret-bearing hostile fixture under the operating-system temporary directory;
-2. request one allowlisted Bun command and stop at a durable `run_environment_command` approval;
+2. request one allowlisted Node command and stop at a durable `run_environment_command` approval;
 3. close and reopen the SQLite-backed harness before approving the command;
 4. verify from inside OCI that `.env` is absent and outbound network is denied;
 5. modify only the ephemeral snapshot and inspect the content- and run-bound patch;
@@ -19,15 +19,16 @@ The model in this demo is deterministic and scripted. That keeps the proof focus
 
 ## Prerequisites
 
-- Bun 1.3.7 or newer;
+- Node.js 22.13.0 or newer;
+- Bun 1.4.0 or newer for the source-checkout build command;
 - Docker or Podman running locally; and
 - the configured image already present locally.
 
-The default command uses Docker and `oven/bun:1.3.7-slim`:
+The default command uses Docker and `node:24-bookworm-slim`:
 
 ```bash
 bun install --frozen-lockfile
-docker pull oven/bun:1.3.7-slim
+docker pull node:24-bookworm-slim
 bun run build
 bun run demo:hostile
 ```

package/docs/RELEASE.md

@@ -1,6 +1,6 @@
 # Release process
 
-`@zhivex-ai/harness@0.7.0` is the latest public npm release. `0.8.0` is a source release candidate, not a published artifact. Publication is never performed from a development checkout. The confirmation-gated `.github/workflows/release.yml` workflow builds, inspects, transfers, and publishes one exact tarball through npm Trusted Publishing/OIDC. Creating a tag alone does not publish anything.
+`@zhivex-ai/harness@0.9.0` is the latest public npm release. `0.10.0` is a Node-first source candidate, not a published artifact. Publication is never performed from a development checkout. The confirmation-gated `.github/workflows/release.yml` workflow builds, inspects, transfers, and publishes one exact tarball through npm Trusted Publishing/OIDC. Creating a tag alone does not publish anything.
 
 ## Deterministic gates
 
@@ -36,7 +36,7 @@ The release workflow performs this sequence across an unprivileged validation jo
 
 1. check out an existing annotated `v<package-version>` tag with complete history;
 2. prove that the tag resolves to `main`, the worktree is clean, and the version is absent from npm;
-3. run the complete Bun release gate;
+3. run the complete release gate with Bun-managed contributor tooling and the supported Node runtime;
 4. create one tarball with `bun pm pack --ignore-scripts`;
 5. allow only the documented package roots, verify the packed manifest, and write `SHA512SUMS`;
 6. install that same tarball in an isolated consumer and execute its CLI and public API;
@@ -48,9 +48,9 @@ For a local artifact rehearsal after the source gate:
 
 ```bash
 mkdir -p release-artifacts
-bun pm pack --filename release-artifacts/zhivex-ai-harness-0.8.0.tgz --ignore-scripts
-bun run artifact:check -- release-artifacts/zhivex-ai-harness-0.8.0.tgz
-bun run smoke:artifact -- release-artifacts/zhivex-ai-harness-0.8.0.tgz
+bun pm pack --filename release-artifacts/zhivex-ai-harness-0.10.0.tgz --ignore-scripts
+bun run artifact:check -- release-artifacts/zhivex-ai-harness-0.10.0.tgz
+bun run smoke:artifact -- release-artifacts/zhivex-ai-harness-0.10.0.tgz
 ```
 
 `release-artifacts/`, `.npmrc`, `.env`, source tests, Git metadata, and local run state are excluded from the package.
@@ -61,7 +61,7 @@ Before a release dispatch, reverify repository/package visibility compatibility,
 
 The release workflow intentionally supplies no long-lived registry token. Do not introduce one as a fallback; a failed OIDC assertion is a stop condition to diagnose.
 
-Trusted Publishing currently requires npm CLI `11.5.1` or newer and Node `22.14.0` or newer. The workflow follows npm's current Node 24 guidance and uses npm only for the OIDC/provenance-aware registry transaction; dependency management, build, tests, packing, and artifact installation remain Bun-first.
+Trusted Publishing currently requires npm CLI `11.5.1` or newer and Node `22.14.0` or newer. The workflow follows npm's current Node 24 guidance and uses npm only for the OIDC/provenance-aware registry transaction. Dependency management, tests, and packing use Bun as contributor tooling; the built CLI, public library, SQLite reopen, and installed artifact execute under Node.
 
 ## Tag and dispatch
 

package/docs/REPOSITORY_EDITING.md

@@ -19,7 +19,11 @@ These controls prevent silent workspace drift; they do not isolate the host. Run
 
 ## Discovery and digests
 
-`list_files` and `search_files` return deterministic pages. Each response includes `truncated` and, when another page exists, an opaque `nextCursor`. Supply that cursor unchanged to request the next page. A cursor is bound to the original operation and parameters; it must not be edited or reused for a different path, query, case-sensitivity setting, or page size.
+`list_files` and `search_files` return deterministic pages. `list_files` keeps digest-bound entries as the default; set `includeDigests=false` for path-only topology discovery without reading every file. Before proposing a mutation, use `read_file` or `read_files` to obtain the exact current digest. Each response includes `truncated` and, when another page exists, an opaque `nextCursor`. Supply that cursor unchanged to request the next page. A cursor is bound to the original operation and parameters, including the topology/digest mode; it must not be edited or reused for a different path, query, case-sensitivity setting, or page size.
+
+In `0.9.x`, pagination reuses a topology-only index. Before each reuse, the harness validates visible directory metadata and the metadata plus content digests of applicable ignore files. A structural or ignore-policy change invalidates the index and makes an older cursor fail as stale. File bytes and content digests are never served from that index: every listed page, read, and search uses the stable anti-race file reader, so an external content-only change is observed even when the topology remains valid.
+
+Use `read_files` for up to 20 independent file/range requests with a 2 MiB aggregate source limit; duplicate paths share one stable read. Use `search_many` for up to 10 literal queries and 500 aggregate matches; it reads each candidate file once for the whole query set. The single-file tools remain available for focused reads and cursor-paginated search. Batch tools are read-only and do not enable global tool parallelism, so write ordering and approval behavior are unchanged.
 
 Listed files and every search match include a content digest. `read_file` also returns the digest of the complete file, even when only a line range was requested. Digests are the concurrency contract for later edits: reading content and then editing it without carrying the observed digest does not provide stale-workspace protection.
 
@@ -74,7 +78,7 @@ Quarantine is a recovery boundary, not a backup system. Retention and permanent
 
 ## Checks
 
-Checks remain explicit package scripts executed through Bun. `test`, `typecheck`, `lint`, and `build` are the default allowlist. `--allow-check` and `ZHIVEX_HARNESS_ALLOWED_CHECKS` replace that default with an explicit set of declared package-script names; they do not accept command text. The requested script text must still exactly match the current `package.json`; a changed script fails closed.
+Checks remain explicit package scripts executed through the repository package manager. `packageManager` is authoritative when pinned; otherwise one unambiguous npm, pnpm, Yarn, or Bun lockfile is detected, and repositories without either default to npm. `test`, `typecheck`, `lint`, and `build` are the default allowlist. `--allow-check` and `ZHIVEX_HARNESS_ALLOWED_CHECKS` replace that default with an explicit set of declared package-script names; they do not accept command text. The requested script text must still exactly match the current `package.json`; a changed script, symbolic-link/ambiguous lockfile, or implicit `pre<check>`/`post<check>` hook fails closed.
 
 Checks do not load the workspace `.env` automatically. A non-zero exit, timeout, or truncated output is recorded as returned evidence and must not be summarized as a successful validation.