@zhivex-ai/harness 0.10.0 → 0.11.0

package/docs/CLI.md

@@ -1,6 +1,6 @@
 # CLI contract
 
-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.
+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.
+
+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.10.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>
@@ -78,6 +84,8 @@ Enforced execution is opt-in:
 
 `--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
 
 `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.
@@ -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

@@ -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.10.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,12 @@ 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.

package/docs/EXECUTION_ENVIRONMENTS.md

@@ -125,6 +125,12 @@ Applications constructing the harness can inject a `HarnessOciRuntimeAdapter` fo
 
 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 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.
@@ -139,6 +145,14 @@ Provider certification is separate and billable. The live workflow runs the requ
 
 ## 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 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.

package/docs/EXTENSIBILITY.md

@@ -1,6 +1,6 @@
 # Extensibility and orchestration
 
-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.
+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
 
@@ -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.10.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/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.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.
+`@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
 
@@ -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.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
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhivex-ai/harness",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Governed, provider-portable runtime for coding agents with durable approvals and isolated repository execution.",
   "type": "module",
   "license": "MIT",