@zhivex-ai/harness 0.9.0 → 0.11.0

package/docs/CLI.md

@@ -1,6 +1,6 @@
 # CLI contract
 
-Zhivex Harness `0.9.x` is Bun-first and exposes a durable agent console, offline change-envelope operations, plus versioned JSON documents and JSON Lines events for automation.
+Zhivex Harness `0.11.x` is Node-first and exposes a durable agent console, bounded project context, 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
 
@@ -40,6 +40,7 @@ Each console session is a scoped, durable chain of immutable run IDs. The sessio
 /route [role=provider[:model]] /route clear [role]
 /status                        /diff
 /review <task>                 /resume <last|sessionId>
+/pending                       /approve | /deny
 /compact                       /new [title]
 /rename <title>                /clear
 /help                          /exit
@@ -47,15 +48,19 @@ Each console session is a scoped, durable chain of immutable run IDs. The sessio
 
 Provider/model changes apply only to the next run. The console blocks them while the current run has an unresolved approval. Before a cross-model handoff it replaces future context with a bounded deterministic summary that redacts common credentials and retains tool names but not tool inputs or outputs. It never rebinds an existing run to another provider.
 
-`/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`.
+`/resume` selects a conversation session and restores its exact persisted provider, routing, context, and execution policy. `/pending` renders the current approval card without executing it; `/approve` or `/deny` continues that durable run inside the console. The operator command `zhx resume <runId> --approve|--deny` remains available for scripts and out-of-process operation.
 
-`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.
+Human terminal mode renders redacted step/tool lifecycle lines and never prints tool inputs, outputs, provider payloads, or raw errors. Governed edits, checks, argv commands, and OCI shell scripts show their complete sanitized approval payload; unknown provider/MCP tools use a bounded summary with an explicit full view. `q`, EOF, or interruption leaves the entire approval batch pending.
+
+`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.
 
+Project context discovery reads a root `AGENTS.md` and the optional `.zhivex/harness.json` manifest. Use `--context-config <path>` to choose another workspace-contained manifest or `--no-project-context` to disable both. Context/rules are bounded and fingerprinted; skills expose metadata first and their instructions only through `load_skill`.
+
 `--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.9.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.11.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.
 
@@ -66,6 +71,7 @@ Enforced execution is opt-in:
 --oci-runtime <docker|podman>
 --oci-image <reference>
 --oci-allow-command <bare-name>
+--oci-shell <deny|ask>
 --oci-max-process-runtime-ms <n>
 --oci-max-process-output-bytes <n>
 --oci-max-memory-mb <n>
@@ -76,7 +82,9 @@ 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).
+
+`--oci-shell` defaults to `deny`. `ask` exposes `run_environment_shell`, whose complete script requires durable approval and runs as `sh -lc` inside the acquired no-network container. It does not add a host shell, enable networking, or remove the separate host patch-import approval. The entrypoint allowlist constrains the command requested from the container runtime; it is not a kernel-level descendant-process allowlist.
 
 ## Change admission
 
@@ -126,6 +134,6 @@ The event projector allowlists safe fields. Text deltas and token usage are reta
 
 ## Configuration schema
 
-Resolved library configuration includes `schemaVersion: 4`, an explicit `allowedChecks` array, `storeBackend`, `scope`, parent `budget`, `compaction`, `requiredCapabilities`, optional `mcpConfigPath`, an `orchestration` object with profiles, child budget/timeout, and review concurrency, and a discriminated `execution` policy. The check default is `test`, `typecheck`, `lint`, and `build`; `--allow-check` or `ZHIVEX_HARNESS_ALLOWED_CHECKS` replaces that set. Execution defaults to `{ backend: "none" }`; an OCI policy records the runtime, image, allowed commands, and every resource ceiling. Passing a different explicit schema version fails before a model or tool can run. During `0.x`, a minor release may add a new schema version with a documented migration; patch releases remain compatible.
+Resolved library configuration includes `schemaVersion: 5`, an explicit `allowedChecks` array, `storeBackend`, `scope`, parent `budget`, `compaction`, `requiredCapabilities`, project `context`, optional `mcpConfigPath`, an `orchestration` object with profiles, child budget/timeout, and review concurrency, and a discriminated `execution` policy. The check default is `test`, `typecheck`, `lint`, and `build`; `--allow-check` or `ZHIVEX_HARNESS_ALLOWED_CHECKS` replaces that set. Execution defaults to `{ backend: "none" }`; an OCI policy records the runtime, image, allowed entrypoints, shell mode, and every resource ceiling. Passing a different explicit schema version fails before a model or tool can run. During `0.x`, a minor release may add a new schema version with a documented migration; patch releases remain compatible.
 
 The default state directory is `<workspace>/.zhivex-harness/runs` and the default backend is scoped SQLite at `operations.sqlite`. Explicit external state directories are supported, but the workspace root, filesystem root, sensitive workspace paths, regular files, and symbolic-link targets are rejected before the run store is created. See [DURABLE_OPERATIONS.md](./DURABLE_OPERATIONS.md) for state migration and operations, and [EXTENSIBILITY.md](./EXTENSIBILITY.md) for capability, MCP, subagent, and review-group configuration.

package/docs/CONTEXT_ENGINEERING.md

@@ -0,0 +1,77 @@
+# Context engineering
+
+Zhivex Harness `0.11.x` can load bounded project instructions without turning repository content into a way around harness policy.
+
+## Discovery and precedence
+
+Project context is enabled by default. The harness reads a root `AGENTS.md` when present and an optional `.zhivex/harness.json` manifest. Use `--context-config <workspace-relative-path>` to select another manifest or `--no-project-context` to disable project context discovery. Library callers use `contextConfigPath` and `projectContext: false` for the same controls.
+
+Harness safety instructions always remain authoritative. Project context and rules can describe architecture, commands, conventions, and desired workflows; they cannot expand the workspace, expose secrets, enable tools, waive approvals, change budgets, enable network access, or weaken OCI policy.
+
+The manifest uses schema version `1`:
+
+```json
+{
+  "schemaVersion": 1,
+  "contextFiles": ["docs/ARCHITECTURE.md"],
+  "ruleFiles": [".zhivex/rules/typescript.md"],
+  "skillDirectories": [".zhivex/skills"]
+}
+```
+
+Paths are relative to the workspace. Version `1` does not accept globs, absolute paths, traversal, symbolic links, special files, sensitive filenames, or paths excluded by the workspace policy. File and aggregate byte limits apply before content is added to instructions.
+
+## Progressive skills
+
+Each immediate child of a configured skill directory may contain `SKILL.md`:
+
+```markdown
+---
+name: repository-review
+description: Review a repository change for correctness and security.
+---
+
+# Procedure
+
+Inspect the diff, reproduce failures, and report evidence.
+```
+
+Initial instructions contain only the skill ID, description, scope, and digest. The read-only `load_skill` tool returns the bounded instructions only when the model selects that exact skill. Scripts and assets are not executed or loaded implicitly.
+
+## Lifecycle hooks
+
+The library can accept trusted, application-registered lifecycle handlers with stable IDs and versions. Their identities are bound into the harness fingerprint, and events contain safe lifecycle metadata rather than prompts, messages, tool arguments/results, or provider payloads.
+
+```ts
+const harness = await createHarness({
+  lifecycleHooks: [{
+    id: "local-audit",
+    version: "1",
+    events: ["approval-requested", "run-finished"],
+    timeoutMs: 2_000,
+    failureMode: "ignore",
+    handle(event) {
+      auditSink.record(event);
+    }
+  }],
+  onLifecycleHookError(failure) {
+    diagnostics.record(failure.hookId, failure.event);
+  }
+});
+
+try {
+  // runHarness(...)
+} finally {
+  await harness.close();
+}
+```
+
+Hooks run sequentially, support selected events and bounded timeouts, and default to best-effort failure handling. Set `failureMode: "fail"` only when the registered application hook must stop the lifecycle operation.
+
+Repository manifests cannot register executable code. Project-selected executable hooks, host shell hooks, and implicit `pre<script>`/`post<script>` package hooks remain unavailable. A future command-hook contract must execute within the acquired environment and preserve approval, journal, patch-review, and host-import boundaries.
+
+## Durable compatibility
+
+Context/rule/skill digests and trusted hook identities form part of the durable harness binding. Changing them intentionally prevents a paused run from resuming under different instructions. Complete or deny the old run with the artifact and context that created it, then start a new run.
+
+Version `0.11.x` advances the resolved configuration schema from `4` to `5`. Existing SQLite state remains readable, but paused `0.10.x` approvals must be completed or denied with the matching artifact because project instructions and trusted hook identities are now part of the run fingerprint. Library cleanup should `await harness.close()` so the final lifecycle event and environment release complete.

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.9.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.9.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.11.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.10.x
+
+Version `0.11.0` advances configuration schema `4` to `5` and binds project context, progressive skill metadata, trusted application hook identities, and OCI shell mode into durable compatibility. The SQLite schema and file format do not change.
+
+Complete or deny paused `0.10.x` approvals with the exact `0.10.x` artifact and context that created them. New `0.11.x` runs enable bounded project context by default; disable it explicitly when required, and await `harness.close()` so asynchronous lifecycle hooks and execution-environment cleanup finish.
+
+## 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.

package/docs/EXECUTION_ENVIRONMENTS.md

@@ -17,7 +17,7 @@ The OCI policy is enforced for one acquired run session, with each command commi
 - 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.
 
@@ -83,7 +83,7 @@ In `0.9.x`, acquisition keeps only a bounded metadata inventory in memory, write
 
 `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 container stays paused while idle. After every command the harness rejects surviving background processes, clears `/tmp`, and computes a canonical workspace seal. An unchanged seal takes a no-export fast path. A changed seal freezes the container, 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.
+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.
 
@@ -91,6 +91,10 @@ Failed, cancelled, timed-out, output-limited, invalid, or background-spawning co
 
 `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
@@ -105,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. The container remains paused between successful commands and 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 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.
 
@@ -117,18 +121,40 @@ 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.
+
+## Migration from 0.10.x
+
+Version `0.11.x` advances the execution policy to `2026-08-21-v4` and configuration schema to `5`. Existing OCI configuration retains `shellMode: "deny"`; opt into `"ask"` only when exact-script approval inside the denied-network environment is intended.
+
+Complete or deny paused `0.10.x` environment approvals with their original artifact. The new shell tool, context binding, and policy fingerprint intentionally prevent silent resume under a different authority surface; 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. `bun run benchmark:oci` reports first-command, warm no-op, mutation, snapshot, and runtime-I/O measurements on a configurable synthetic repository. 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 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 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
 
+### 0.11.x opt-in shell policy
+
+Version `0.11.x` advances the execution policy to `2026-08-21-v4` and adds `--oci-shell deny|ask`. `deny` is the default and does not expose a shell tool. `ask` exposes `run_environment_shell`; the exact script is included in the durable approval payload and is passed as one argument to `sh -lc` by the OCI controller. The host process never parses the script.
+
+The shell shares the same ephemeral snapshot, denied network, empty inherited environment, non-root identity, read-only root filesystem, resource ceilings, failure discard/reseed behavior, and distinct content-bound host import approval as argv commands. `--yes` may resolve an exposed `ask` approval, but cannot turn `deny` into an enabled shell.
+
+`allowedCommands` is an entrypoint policy, not a seccomp-style descendant-process policy: an allowed runtime such as `node` or `npm` can itself spawn child processes inside the container. Network-enabled shell profiles remain unsupported until egress can be enforced below the process rather than merely declared.
+
 - 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.9.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.11.x` combines governed external tools and bounded multi-agent work with a public provider registry and explicit per-role model routing. Configuration schema is version `5`; registry selection, runtime model capabilities, routed child models, non-secret provider transport settings, project context, trusted hook identities, 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.9.x` has one operator-supplied price pair, not pricing per model/run.
+- `--max-cost-usd` with any route is rejected because `0.11.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/LIVE_CERTIFICATION.md

@@ -14,6 +14,8 @@ For each selected provider, the base gate:
 
 Separate gates exercise reviewer delegation, mixed-provider routing, model-directed OCI execution, and the real container boundary. Passing one gate never implies that another provider or execution path is certified.
 
+The default mixed-provider route uses OpenAI as parent and Qwen as reviewer, keeping the release gate inside the certified cohort. Set `ZHIVEX_HARNESS_LIVE_PARENT_PROVIDER` and `ZHIVEX_HARNESS_LIVE_REVIEWER_PROVIDER` explicitly to certify another pair; selecting Gemini remains provisional and requires its credential plus every provider gate.
+
 ## Running the gates
 
 The package exposes dedicated Bun scripts for:

package/docs/RELEASE.md

@@ -1,6 +1,6 @@
 # Release process
 
-`@zhivex-ai/harness@0.8.0` is the latest public npm release. `0.9.0` is a 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.
+`@zhivex-ai/harness@0.10.0` is the latest public npm release and `v0.10.0` is its matching repository tag. Version `0.11.0` is the current local source release candidate; it is not a published artifact until its own reviewed commit, annotated `v0.11.0` tag, protected workflow, registry integrity, and provenance all agree. 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.9.0.tgz --ignore-scripts
-bun run artifact:check -- release-artifacts/zhivex-ai-harness-0.9.0.tgz
-bun run smoke:artifact -- release-artifacts/zhivex-ai-harness-0.9.0.tgz
+bun pm pack --filename release-artifacts/zhivex-ai-harness-0.11.0.tgz --ignore-scripts
+bun run artifact:check -- release-artifacts/zhivex-ai-harness-0.11.0.tgz
+bun run smoke:artifact -- release-artifacts/zhivex-ai-harness-0.11.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,7 @@ 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.
 
@@ -78,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.