@zhivex-ai/harness 0.6.1 → 0.7.0

package/docs/CLI.md

@@ -1,10 +1,15 @@
 # CLI contract
 
-Zhivex Harness `0.6.x` is Bun-first and exposes a human terminal interface plus versioned JSON documents for automation.
+Zhivex Harness `0.7.x` is Bun-first and exposes a durable agent console plus versioned JSON documents and JSON Lines events for automation.
 
 ## Commands
 
 ```text
+zhx
+zhx run --route reviewer=gemini [options] "task"
+zhx run --jsonl [options] "task"
+zhx chat [--continue|--session <sessionId>]
+zhx sessions list|inspect|rename|fork|archive
 zhivex-harness run [options] "task"
 zhivex-harness review [options] "review task"
 zhivex-harness chat [options]
@@ -20,12 +25,36 @@ zhivex-harness --version
 zhivex-harness --help
 ```
 
+## Command compatibility
+
+`zhx` and `zhivex-harness` point to the same installed executable. The short command is the primary interactive UX; the long command remains supported for existing scripts. Running `zhx` with no arguments in a TTY opens the console. An implicit prompt such as `zhx "inspect this repository"` and explicit `zhx run` remain one-shot executions.
+
+## Interactive console
+
+Each console session is a scoped, durable chain of immutable run IDs. The session index stores provider/model/status metadata and never stores prompts, model messages, tool payloads, or provider data; those remain in the governed run store. `zhx chat --continue` opens the latest session and `--session <id>` selects one explicitly.
+
+```text
+/provider [id]                 /model [id]
+/route [role=provider[:model]] /route clear [role]
+/status                        /diff
+/review <task>                 /resume <last|sessionId>
+/compact                       /new [title]
+/rename <title>                /clear
+/help                          /exit
+```
+
+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`.
+
 `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.
 
 `--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.7.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.
 
 Enforced execution is opt-in:
@@ -69,7 +98,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"
+  "kind": "providers | doctor | run-result | review-group | run-list | run-inspection | run-export | run-cancellation | run-cleanup | session-list | session"
 }
 ```
 
@@ -79,6 +108,12 @@ Provider diagnostics include credential variable names and boolean presence only
 
 `run-result.mutations` contains the mutation audit entries produced by the current harness process. `run-result.children` reports bounded child identity, status, steps, tool/error counts, and usage without raw child messages or tool payloads. Capability evidence, configured MCP server names, and the execution backend/binding/image are included. `review-group` contains a group ID and one bounded member result. Operational inspect/export documents are redacted and do not include raw messages, tool inputs/outputs, approval arguments, metadata, or full output text; `run-inspection.hierarchy` adds the redacted run tree. Tool-level repository-editing documents use their own schema version `1` and kinds such as `edit-proposal`, `patch-result`, `mutation-audit`, and `workspace-diff`; see [REPOSITORY_EDITING.md](./REPOSITORY_EDITING.md).
 
+## JSON Lines
+
+`--jsonl` is available for `run` and approval `resume`, and is mutually exclusive with `--json`. Every event line has `schemaVersion: 1`, `kind: "run-event"`, a monotonic `sequence`, and an event `type`. A separately projected compact `run-result` is emitted as the final sequenced line; it contains only run identity/status, step/tool counts, redacted approval identity, and child run identity/status. It omits output text, mutations, approval arguments, paths, scope, provider payloads, and configuration bindings.
+
+The event projector allowlists safe fields. Text deltas and token usage are retained; tool IDs/names, approval IDs, status, step counts, compaction counts, and provider/model identity are allowed. Tool inputs/outputs, approval arguments, provider payloads, image content, full durable states/messages, raw errors, stacks, and telemetry metadata are omitted. Consumers must still treat model text as untrusted application data.
+
 ## 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.

package/docs/DURABLE_OPERATIONS.md

@@ -12,6 +12,8 @@ Every durable key is isolated by:
 
 Use the same workspace, state directory, backend, tenant, user, and namespace for `run`, `resume`, and every `runs` command. A run fingerprint is bound to the canonical workspace, durable scope, provider/model, tool contract, approval policy, config schema, harness version, and execution-environment policy. Under OCI, the resolved image identity is also bound. Resume fails closed when a current binding differs.
 
+Provider transport configuration is represented by a non-secret SHA-256 fingerprint too. Endpoint, region, and provider-workspace values are never persisted in plaintext, but changing them invalidates a paused run binding.
+
 CLI-created runs persist the resolved non-secret harness configuration in versioned run metadata. The terminal prints a scope-complete locator command, and `resume` restores the original OCI policy before fingerprint validation, so approval restart does not silently fall back to `execution=none`. Explicit conflicting overrides are rejected by the existing binding check.
 
 ```bash
@@ -43,6 +45,29 @@ zhivex-harness runs cleanup --before 2026-08-01T00:00:00Z
 
 `inspect` and `export` share the same redacted operational artifact. Export changes only the document kind to `run-export`; it does not create an unredacted archive on disk.
 
+## Durable CLI sessions
+
+The `0.7.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.
+
+```bash
+zhx chat
+zhx chat --continue
+zhx chat --session <sessionId>
+zhx sessions list
+zhx sessions inspect <sessionId> --json
+zhx sessions rename <sessionId> "checkout repair"
+zhx sessions fork <sessionId>
+zhx sessions archive <sessionId>
+```
+
+The store uses SQLite WAL transactions, optimistic revisions, workspace/scope hashes, owner-only permissions, soft deletion/retention, and bounded session/run/metadata/index sizes. It rejects a new run while the latest session run is active or waiting for approval. Fork and archive operations also require a terminal branch point.
+
+## Provider handoff safety
+
+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.7.x`.
+
 ## Budgets
 
 Default limits are:
@@ -79,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.6.x
+
+`0.7.0` keeps configuration schema version `4`, final JSON schema `1`, existing run commands, and the `zhivex-harness` binary. It adds the `zhx` alias, session tables, optional route metadata, and a JSONL event schema without rewriting existing run rows.
+
+Paused `0.6.x` approvals are intentionally not resumable by `0.7.x`: the durable binding includes the harness version, so resume fails closed before a tool side effect. Resolve or deny pending `0.6.x` approvals with the matching `0.6.x` artifact before upgrading. Do not relax the fingerprint or edit stored state. Completed `0.6.x` runs remain available to redacted operator inspection; a new `0.7.x` session can start from an explicitly compacted summary.
+
 ## Migration from 0.3.x
 
 Opening either backend under the default local/workspace scope scans legacy unscoped file-backed runs in the selected state directory. Runs absent from the scoped store are copied with their tool journals and marked `metadata.migratedFrom: "0.3-file-store"`. With the default backend the target is SQLite; `--store file` creates scoped file copies as a temporary compatibility path. Migration is idempotent and retains the unscoped source files for rollback; it does not delete or rewrite the legacy state. Custom tenant, user, or namespace scopes never import unscoped legacy data implicitly; library operators must call `migrateLegacyFileRuns` intentionally with the target scoped store.

package/docs/EXTENSIBILITY.md

@@ -1,6 +1,14 @@
 # Extensibility and orchestration
 
-Zhivex Harness `0.5.x` adds governed external tools and bounded multi-agent work without adding a generic shell or weakening the workspace contract. Configuration schema version `3` binds capability requirements, MCP policy, subagent profiles, child budgets, and scope into the durable harness fingerprint.
+Zhivex Harness `0.7.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
+
+Built-in registrations are Meta, Qwen, OpenAI, and Gemini. Each registration owns its descriptor, default model, credential names, capability/support labels, factory, and declarative diagnostics. The registry never dynamically imports provider code or returns credential/endpoint values from diagnostics.
+
+Library callers can use `DEFAULT_PROVIDER_REGISTRY`, `BUILTIN_PROVIDER_REGISTRATIONS`, `createProviderRegistry`, or `DEFAULT_PROVIDER_REGISTRY.extend(...)`, then pass the registry to `resolveHarnessConfig`, `createProviderModel`, provider diagnostics, or `createHarness({ providerRegistry })`. Registration IDs, environment-variable names, defaults, diagnostics, and factories are validated before they become selectable.
+
+Gemini uses `@zhivex-ai/gemini@0.10.4`, default model `gemini-3.6-flash`, `GEMINI_API_KEY` or `GOOGLE_GENERATIVE_AI_API_KEY`, and optional `GEMINI_BASE_URL`. It is provisional until proposal/approval/restart, delegation, mixed routing, and OCI execution pass the credentialed harness live matrix; adapter-level evidence alone does not make the harness integration certified.
 
 ## Capability gate
 
@@ -88,6 +96,30 @@ The parent receives `delegate_explorer`, `delegate_implementer`, `delegate_teste
 
 Child mutations and checks do not inherit an approval automatically. A paused child approval is promoted to the parent as `kind: "subagent"`; approving the parent resumes the same durable child checkpoint. Completed child tools are protected by the shared exactly-once journal.
 
+## Per-role model routing
+
+Route selected profiles without changing the parent model:
+
+```bash
+zhx run \
+  --provider openai \
+  --route explorer=qwen \
+  --route reviewer=gemini:gemini-3.6-flash \
+  "implement the change and review it"
+```
+
+The grammar is `<profile>=<provider>[:<model>]`; supported profiles are `explorer`, `implementer`, `tester`, and `reviewer`. Omitting a model uses the provider registration's default. Duplicate roles, unknown providers, invalid model text, missing credentials, and capability mismatches fail before the parent run starts. Providers are instantiated only for selected routes.
+
+The resolved route plan is persisted without credentials in CLI resume metadata and instantiated child capabilities participate in the harness fingerprint. Changing a route never mutates or resumes a run under another model; the interactive console starts a new session turn.
+
+## 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.7.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.
+
 ## Budgets and cancellation
 
 Defaults per child are 8 steps, 16 tool calls, 3 tool errors, 30,000 input tokens, 8,000 output tokens, 36,000 total tokens, and a five-minute timeout. Override them with the `--subagent-*` options or matching `ZHIVEX_HARNESS_SUBAGENT_*` variables.

package/docs/LIVE_CERTIFICATION.md

@@ -1,160 +1,59 @@
 # Live provider certification
 
-The live provider smoke is an explicit release gate. It is not part of the deterministic unit-test suite because it makes billable upstream requests.
+Live certification is an explicit release gate because it makes billable upstream requests. It is separate from deterministic tests, installed-artifact validation, and registry publication.
 
 ## What it proves
 
-For each selected provider, the smoke:
+For each selected provider, the base gate:
 
-1. starts a fresh process and asks the real model to create one exact digest-bound proposal and apply that returned proposal;
-2. verifies that interrupt approval persists while the target file is still absent;
-3. exits that process and starts a second process against the same scoped SQLite run store;
-4. approves and resumes the saved run;
-5. verifies the completion token, one successful patch result, one completed tool-journal entry, and the exact file contents.
+1. creates one digest-bound proposal with a real model;
+2. pauses before the mutation and persists the approval request;
+3. restarts against the same scoped durable store;
+4. approves and resumes the saved run; and
+5. verifies exact completion, patch contents, and exactly-once journal evidence.
 
-The temporary workspace and state store are removed after each provider. Credential values are never written to output, prompts, fixtures, or results. Error output is redacted against every configured provider credential, custom endpoint, and Qwen workspace identifier before it is printed.
+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.
 
-Success and failure evidence is emitted as JSON. A success record identifies the provider and model and records the approval, restart, tool-execution, and journal checks; it never contains a credential value. The complete default matrix continues after an individual provider failure, reports every provider result, and exits non-zero when any entry fails.
+## Running the gates
 
-Meta supports only automatic tool choice, and Qwen 3.8 thinking cannot use named or required tool choice. The complete matrix therefore uses automatic selection and an exact two-tool prompt: `propose_edits` must run first, and its returned `proposalId` must then be passed unchanged to `apply_patch`. Qwen and OpenAI run through Responses. Qwen Responses cannot accept `maxTokens`, so the harness enforces Qwen token budgets before and after each provider step without transporting that ceiling upstream; one step can cross the measured limit before the output guard observes it. Meta intentionally runs through Chat streaming to cover the fragmented tool-call assembler fixed in `@zhivex-ai/meta@0.2.1`.
+The package exposes dedicated Bun scripts for:
 
-## Run it
+- the base provider approval/restart matrix;
+- bounded reviewer delegation and persistence;
+- mixed-provider parent/child routing;
+- model-directed command, review, and import; and
+- real OCI boundary enforcement.
 
-Keep provider credentials in the repository `.env`; Bun loads that file when the script starts. The gate refuses to make requests without the explicit opt-in variable:
+Live scripts require an explicit network opt-in and explicit local credentials. Provider selection and model or endpoint overrides use the normal configuration contract. The scripts fail closed when prerequisites are missing and print the required invocation without revealing configured values.
 
-```bash
-ZHIVEX_HARNESS_LIVE=1 bun run scripts/live-provider-smoke.ts
-```
+Keep credentials and account-specific configuration only in the ignored local environment file. Never commit that file or copy its contents into prompts, fixtures, evidence, or issue reports.
 
-The default gate requires and tests Meta, Qwen, and OpenAI. To certify one provider while diagnosing an upstream or account issue:
+## Support labels
 
-```bash
-ZHIVEX_HARNESS_LIVE=1 \
-ZHIVEX_HARNESS_LIVE_PROVIDERS=qwen \
-bun run scripts/live-provider-smoke.ts
-```
+The default live matrix contains only providers marked `certified` by the registry. A provisional provider must be selected explicitly and remains provisional until all required provider, delegation, routing, and execution gates pass for the release candidate.
 
-Optional model overrides are:
+Gemini is integrated as a provisional provider in `0.7.0`. Deterministic adapter tests or independent SDK certification are insufficient to promote it.
 
-- `ZHIVEX_HARNESS_LIVE_META_MODEL`
-- `ZHIVEX_HARNESS_LIVE_QWEN_MODEL`
-- `ZHIVEX_HARNESS_LIVE_OPENAI_MODEL`
+## Evidence contract
 
-Endpoint, Qwen workspace, and Qwen region overrides use the normal `META_BASE_URL`, `QWEN_BASE_URL`, `QWEN_WORKSPACE_ID`, `QWEN_REGION`, and `OPENAI_BASE_URL` variables.
+Certification evidence is provider-, model-, endpoint-, account-, artifact-, and date-bound. A valid record contains only:
 
-The separate delegation matrix uses the same opt-in, provider selection, credentials, and model overrides:
+- provider and model identifiers;
+- pass/fail status for each required boundary;
+- approval, restart, persistence, journal, routing, and execution checks;
+- the source commit and exact artifact identity; and
+- a timestamp suitable for determining staleness.
 
-```bash
-ZHIVEX_HARNESS_LIVE=1 bun run smoke:live:orchestration
-```
+Evidence must not contain credential values, custom endpoints, workspace or account identifiers, raw prompts, tool arguments, provider payloads, durable messages, stack traces, or repository contents. Operator-specific evidence belongs in protected CI artifacts with bounded retention; public documentation records only the support conclusion and its limits.
 
-For every provider it requires exactly one `delegate_reviewer` call, verifies the bounded child response and aggregate token accounting, closes and reopens SQLite, and confirms the persisted parent/child link through the redacted hierarchical inspection. It does not make the legacy reviewed-edit smoke pass through delegation.
+## Redaction and failure behavior
 
-Certification evidence is date-bound and account-bound. A local deterministic pass, installed-package pass, or one provider's live pass does not certify the other providers.
+Credential values and account-specific configuration are redacted from text and structured errors before output. The complete matrix continues after an individual provider failure, reports a bounded result for every selected provider, and exits non-zero when any required entry fails.
 
-Because `0.4.0` adds the production safety policy, harness binding, scoped SQLite persistence, required leases, budgets, and exactly-once journal recovery, `0.3.0` live evidence does not certify the new runtime path. The supported providers must pass the refreshed `apply_patch` approval/restart gate before the private milestone is considered complete.
+A missing credential, unavailable container runtime, upstream failure, incomplete tool sequence, routing mismatch, stale artifact, or redaction failure leaves the affected path uncertified. Deterministic tests, successful package installation, or credential presence are never substitutes for live evidence.
 
-## 0.4.0 private-milestone evidence
+## Current public status
 
-Evidence collected on 2026-08-17 with the default models and locally configured account. The complete matrix passed together at `2026-08-17T00:53:17.752Z` against the final scoped SQLite, fingerprint, and production-policy candidate.
+Meta, Qwen, and OpenAI retain the previously published `0.6.x` support conclusion for the unchanged runtime paths. `0.7.0` adds Gemini and mixed-provider routing as provisional surfaces; they require fresh release-candidate evidence before certification.
 
-| Provider | Model | Result | Evidence |
-| --- | --- | --- | --- |
-| Meta | `muse-spark-1.2` | Certified | Approval persisted in scoped SQLite, the process restarted, and exactly one patch execution and completed journal entry were observed. |
-| Qwen | `qwen3.8-max` | Certified | Responses completed the proposal-first workflow with durable token enforcement, process restart, and exactly-once patch journaling. |
-| OpenAI | `gpt-5.4` | Certified | Responses completed the proposal-first workflow with an upstream-compatible output ceiling, process restart, and exactly-once patch journaling. |
-
-This evidence certifies provider interaction for the private `0.4.0` candidate only. It does not prove registry publication, provenance, or availability of a public artifact.
-
-## 0.5.0 orchestration status
-
-The `0.4.0` matrix remains valid evidence for the shared proposal, approval, SQLite restart, and exactly-once patch path, but it does not certify model-directed delegation or provider behavior with the expanded MCP/subagent tool surface.
-
-`0.5.0` has deterministic evidence for capability rejection, MCP discovery/approval/resume, prompt-injection and output bounds, durable child approval promotion, exactly-once child mutation, cancellation propagation, scoped hierarchical inspection, aggregate budgets, and application-owned parallel review.
-
-The complete delegation matrix passed at `2026-08-17T02:21:45.553Z`. Each provider made exactly one model-directed `delegate_reviewer` call, completed the bounded child, accounted for aggregate tokens, persisted parent and child, reopened SQLite, and exposed a redacted two-run hierarchy.
-
-| Provider | Model | Result | Evidence |
-| --- | --- | --- | --- |
-| Meta | `muse-spark-1.2` | Certified | One reviewer delegation completed; parent and child survived reopen with a two-run hierarchy and aggregate usage. |
-| Qwen | `qwen3.8-max` | Certified | Responses parent delegation and generated child output completed; persistence, hierarchy, and aggregate usage passed. |
-| OpenAI | `gpt-5.4` | Certified | Responses parent delegation and generated child output completed; persistence, hierarchy, and aggregate usage passed. |
-
-This certifies the bounded reviewer-delegation path, not arbitrary task quality or every subagent profile.
-
-The separate controlled MCP interoperability gate passed at `2026-08-17T16:48:09.043Z` against a real loopback Streamable HTTP server. It exercised protocol `2025-06-18`, authorization and protocol headers, session negotiation, `initialize`, `notifications/initialized`, `tools/list`, `tools/call`, JSON and SSE responses, schema-backed discovery, bounded output, and the forced interrupt-approval policy for network tools. Run it with:
-
-```bash
-bun run smoke:mcp
-```
-
-This is stronger than an injected `fetch` fixture because it uses the operating system network stack and a running server. It certifies the harness transport contract against the controlled implementation; it does not claim compatibility with every third-party MCP server or unsupported `stdio` transport.
-
-## 0.6.0 execution and interoperability status
-
-`0.6.0` adds a third, independent MCP transport gate implemented with the official `@modelcontextprotocol/server@2.0.0` package. It passed at `2026-08-17T16:48:09.141Z` over a real loopback Streamable HTTP endpoint. The harness negotiated its supported `2025-06-18` protocol through the server's documented legacy-stateless compatibility mode, discovered one schema-backed tool, preserved the mandatory network approval, called it exactly once, and validated the bounded response.
-
-```bash
-bun run smoke:mcp:official
-```
-
-This is interoperability evidence for that exact SDK version and compatibility mode, not a claim that the harness implements the newer `2026-07-28` wire protocol or every official SDK feature.
-
-Enforced execution has separate evidence layers:
-
-- deterministic injected-runtime tests for environment/session semantics;
-- installed-package proof for the exported execution API;
-- `ZHIVEX_HARNESS_OCI_REQUIRED=1 bun run smoke:oci` for the real Docker/Podman boundary;
-- billable provider matrices for model-directed tools and delegation.
-
-The final real Docker gate passed on macOS/Docker Desktop at `2026-08-17T16:48Z` with Docker `29.7.2` and image digest `sha256:b7d0366ff1c11bd3897aeaca2e3d215ee1e5902932073434ffc9186ca0a3ac96`. It verified secret exclusion, denied outbound network, a read-only root, total-workspace and changed-file quotas, read-only dependency reuse without snapshot persistence, the configured cgroup PID ceiling under a spawn burst, memory exhaustion containment, combined-output termination, prompt cancellation with immediate container removal, transactional snapshot publication, isolated package checks, approved host patch import, terminal artifact cleanup, and zero remaining harness-labeled containers or volumes.
-
-The live workflow requires this real OCI gate before provider execution. Date-bound model-directed environment results are recorded only after the provider commands complete; implementation, credential presence, or the container result alone is not provider certification.
-
-The billable model-directed matrix is:
-
-```bash
-ZHIVEX_HARNESS_LIVE=1 bun run smoke:live:execution
-```
-
-For each selected provider it requires exactly one approved argv-only environment command, one patch inspection, and one separately approved host import. It verifies exact tool order, durable journal completion, host contents, image/environment binding, and the provider-specific completion token.
-
-The complete Meta/Qwen/OpenAI enforced-execution matrix passed together against the final quota-backed workspace implementation at `2026-08-17T16:49:12.975Z` and image digest `sha256:b7d0366ff1c11bd3897aeaca2e3d215ee1e5902932073434ffc9186ca0a3ac96`.
-
-| Provider | Model | Result | Evidence |
-| --- | --- | --- | --- |
-| Meta | `muse-spark-1.2` | Certified | One approved OCI command, one patch inspection, one separately approved import, exact host contents, and environment binding. |
-| Qwen | `qwen3.8-max` | Certified | One approved OCI command, one patch inspection, one separately approved import, exact host contents, and environment binding. |
-| OpenAI | `gpt-5.4` | Certified | Responses mode persisted across both approval continuations; exact OCI tool order, host import, journal, and binding passed. |
-
-The base proposal/approval/process-restart matrix passed again for all three providers at `2026-08-17T16:22:34.885Z`. The reviewer-delegation/child-persistence/SQLite-reopen/hierarchy/aggregate-budget matrix passed again at `2026-08-17T16:24:14.381Z`. These refreshes cover the `0.6.0` dependency and harness artifact; registry publication is proved separately.
-
-The full deterministic gate then passed with 99 tests, 468 assertions, seven golden evaluations, both MCP implementations, real OCI, and installed-package smoke. The exact 31-file tarball passed SHA-512 inspection and isolated consumer execution. `@zhivex-ai/harness@0.6.0` was subsequently published through the protected OIDC workflow; on 2026-08-17 America/Argentina/Buenos_Aires, the downloaded registry tarball, `latest` tag, integrity, SLSA subject, repository, workflow, branch, and source commit were verified against `fd420f7560b2`.
-
-`0.6.1` does not change provider, tool, approval, execution, or streaming behavior, so it inherits this date-bound provider evidence subject to the normal exact-artifact and registry release gates. Its new hostile-repository demo is deterministic control-plane evidence, not a substitute for the billable provider matrix.
-
-## 0.3.0 private-milestone evidence
-
-Evidence collected on 2026-08-16 with the default models and locally configured account. After aligning the gate with the required proposal-first workflow, Qwen and OpenAI passed together at `2026-08-16T23:37:23.791Z`. After upgrading to `@zhivex-ai/meta@0.2.1`, Meta passed four consecutive runs from `2026-08-16T23:32:50.716Z` through `2026-08-16T23:33:27.161Z`.
-
-| Provider | Model | Result | Evidence |
-| --- | --- | --- | --- |
-| Qwen | `qwen3.8-max` | Certified | Digest-bound patch approval persisted, the process restarted, and exactly one patch execution and completed journal entry were observed. |
-| OpenAI | `gpt-5.4` | Certified | Digest-bound patch approval persisted through Responses, the process restarted, and exactly one patch execution and completed journal entry were observed. |
-| Meta | `muse-spark-1.2` | Certified | Four consecutive proposal-first runs produced complete tool arguments, persisted approval, restarted the process, and observed exactly one patch execution and completed journal entry. |
-
-The supported `0.3.0` live matrix is Meta, Qwen, and OpenAI. Earlier Meta failures remain relevant historical evidence: `@zhivex-ai/meta@0.2.0` split one streamed Chat tool call across `id` and `index` buffers, while a direct-apply smoke prompt could also be rejected because it skipped `propose_edits`. The adapter and gate now cover those separate failures.
-
-## 0.2.0 release-candidate evidence
-
-Evidence collected on 2026-08-16 with the default models and the locally configured account:
-
-The supported Qwen/OpenAI matrix passed again at `2026-08-16T19:47:49.773Z` after the final release-candidate changes.
-
-| Provider | Model | Result | Evidence |
-| --- | --- | --- | --- |
-| Qwen | `qwen3.8-max` | Certified | Approval persisted, process restarted, one tool execution, and one completed journal entry. |
-| OpenAI | `gpt-5.4` | Certified | Approval persisted, process restarted, one tool execution, and one completed journal entry through Responses. |
-| Meta | `muse-spark-1.2` | Provisional | One isolated run completed the full path, but the complete-matrix rerun emitted an empty `{}` argument object for `write_file`; schema validation failed closed before any side effect. |
-
-The supported `0.2.0` release matrix is therefore Qwen and OpenAI. Meta remains integrated but provisional until the automatic tool-call path passes repeatably. The failed Meta attempt did not write a file or consume an approval.
+The controlled and official-SDK MCP interoperability gates remain separate transport evidence. They certify only the tested protocol, implementation, and compatibility mode, not every MCP server or future protocol version.

package/docs/RELEASE.md

@@ -1,6 +1,6 @@
 # Release process
 
-`@zhivex-ai/harness@0.6.0` is public on npm with exact registry integrity and SLSA workflow provenance verified against source tag `v0.6.0`. `0.6.1` is the next source candidate, but 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.6.1` is public on npm with exact registry integrity and SLSA workflow provenance verified against source tag `v0.6.1`. `0.7.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.
 
 ## Deterministic gates
 
@@ -28,7 +28,7 @@ ZHIVEX_HARNESS_LIVE=1 bun run smoke:live:execution
 ZHIVEX_HARNESS_OCI_REQUIRED=1 bun run smoke:oci
 ```
 
-The base reviewed-edit gate and the separate delegation gate must pass for every provider in the supported release matrix. The `0.6.x` workflow must additionally pass the real OCI boundary before live model execution; model-directed environment use is recorded separately from deterministic container enforcement. Integrated provisional providers are reported separately and must not be described as certified. `bun run check` also runs controlled Streamable HTTP MCP interoperability gates; each external implementation claim remains bounded to the tested server/version. See [LIVE_CERTIFICATION.md](./LIVE_CERTIFICATION.md).
+The base reviewed-edit gate and the separate delegation gate must pass for every provider in the supported release matrix. The workflow must additionally pass the real OCI boundary before live model execution; model-directed environment use is recorded separately from deterministic container enforcement. Gemini remains provisional until its three provider gates and a mixed-provider route pass. Integrated provisional providers are reported separately and must not be described as certified. `bun run check` also runs controlled Streamable HTTP MCP interoperability gates; each external implementation claim remains bounded to the tested server/version. See [LIVE_CERTIFICATION.md](./LIVE_CERTIFICATION.md).
 
 ## Exact artifact gate
 
@@ -42,47 +42,32 @@ The release workflow performs this sequence across an unprivileged validation jo
 6. install that same tarball in an isolated consumer and execute its CLI and public API;
 7. transfer only the tarball and `SHA512SUMS` into the `npm` environment, then revalidate the checksum and artifact contract;
 8. pass that same file to the npm CLI for the registry transaction; and
-9. retry through registry propagation, then verify the distribution tag, byte-identical SHA-512 integrity, and SLSA subject/repository/workflow/branch/commit evidence.
+9. retry within one absolute five-minute deadline through registry and attestation propagation, capping every request and sleep by the remaining time, then verify the distribution tag, byte-identical SHA-512 integrity, and SLSA subject/repository/workflow/ref/commit evidence. The ref must be `main` or the exact `v<package-version>` tag; arbitrary branches and tags fail closed.
 
 For a local artifact rehearsal after the source gate:
 
 ```bash
 mkdir -p release-artifacts
-bun pm pack --filename release-artifacts/zhivex-ai-harness-0.6.1.tgz --ignore-scripts
-bun run artifact:check -- release-artifacts/zhivex-ai-harness-0.6.1.tgz
-bun run smoke:artifact -- release-artifacts/zhivex-ai-harness-0.6.1.tgz
+bun pm pack --filename release-artifacts/zhivex-ai-harness-0.7.0.tgz --ignore-scripts
+bun run artifact:check -- release-artifacts/zhivex-ai-harness-0.7.0.tgz
+bun run smoke:artifact -- release-artifacts/zhivex-ai-harness-0.7.0.tgz
 ```
 
 `release-artifacts/`, `.npmrc`, `.env`, source tests, Git metadata, and local run state are excluded from the package.
 
 ## External prerequisites
 
-Before a `0.6.1` dispatch, reverify rather than assuming the previous release state:
+Before a release dispatch, reverify repository/package visibility compatibility, protected-environment reviewers, package ownership with 2FA, and that the Trusted Publisher identity matches the repository workflow. Do not rely on a previous release's state.
 
-- confirm `Zhivex/zhivex-harness` remains public; npm cannot generate public provenance from a private repository;
-- enable GitHub private vulnerability reporting;
-- protect the GitHub `npm` environment with required reviewers and restrict it to `main`/release tags;
-- verify an npm account with 2FA still administers the public `@zhivex-ai/harness` package; and
-- confirm the npm Trusted Publisher is organization `Zhivex`, repository `zhivex-harness`, workflow `release.yml`, environment `npm`, allowed action `npm publish`.
-
-The one-time `0.5.0` bootstrap and the protected `0.6.0` publication are complete: the package exists, Trusted Publishing is configured, and the temporary token was removed/revoked. The release workflow intentionally supplies no `NODE_AUTH_TOKEN` or npm token. Do not reintroduce one as a fallback; a failed OIDC assertion is a stop condition to diagnose.
+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.
 
 ## Tag and dispatch
 
-After the release commit is reviewed, merged, and pushed to `main`:
-
-```bash
-git tag -a v0.6.1 -m "Release v0.6.1"
-git push origin v0.6.1
-gh workflow run release.yml \
-  -f tag=v0.6.1 \
-  -f channel=latest \
-  -f confirm_publication=true
-```
+After review and merge, maintainers create an annotated version tag from the exact release commit and dispatch the protected workflow with an explicit publication confirmation. The canonical dispatch is bound to `main`; recovery is limited to the exact annotated version tag after proving it resolves to the expected commit and remains reachable from `origin/main`.
 
-The boolean confirmation is intentional because npm versions are immutable. The `npm` environment should add a second human approval boundary. Do not use `bun publish`, a local npm session, or a manual registry upload as an alternate path.
+The confirmation is intentional because registry versions are immutable, and the protected environment adds a second human approval boundary. Do not use a local registry session or manual upload as an alternate path.
 
 If npm accepted the immutable version but the post-publication verifier failed during propagation, rerun only the failed `publish` job. It downloads the already validated artifact, skips `npm publish` only when the registry version has byte-identical integrity, and repeats the registry/provenance verification. Never rebuild, bump, or republish the same version to recover a post-publication false negative.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhivex-ai/harness",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Governed, provider-portable runtime for coding agents with durable approvals and isolated repository execution.",
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,8 @@
     "zhivex"
   ],
   "bin": {
-    "zhivex-harness": "./dist/cli.js"
+    "zhivex-harness": "./dist/cli.js",
+    "zhx": "./dist/zhx.js"
   },
   "exports": {
     ".": {
@@ -56,7 +57,7 @@
   "scripts": {
     "dev": "bun run src/cli.ts",
     "start": "bun run dist/cli.js",
-    "build": "bun build ./src/index.ts ./src/cli.ts --outdir ./dist --target bun --packages external && bun build ./scripts/hostile-repository-demo.ts --outfile ./dist/hostile-repository-demo.js --target bun --packages external && tsc --emitDeclarationOnly",
+    "build": "bun build ./src/index.ts ./src/cli.ts --outdir ./dist --target bun --packages external && cp ./dist/cli.js ./dist/zhx.js && bun build ./scripts/hostile-repository-demo.ts --outfile ./dist/hostile-repository-demo.js --target bun --packages external && tsc --emitDeclarationOnly",
     "prepack": "bun run build",
     "docs:check": "bun run scripts/check-docs.ts",
     "typecheck": "tsc --noEmit",
@@ -69,6 +70,7 @@
     "smoke:oci": "bun run scripts/oci-execution-smoke.ts",
     "smoke:live": "bun --env-file=.env run scripts/live-provider-smoke.ts",
     "smoke:live:orchestration": "bun --env-file=.env run scripts/live-orchestration-smoke.ts",
+    "smoke:live:routing": "bun --env-file=.env run scripts/live-routing-smoke.ts",
     "smoke:live:execution": "bun --env-file=.env run scripts/live-execution-smoke.ts",
     "demo:hostile": "bun run dist/hostile-repository-demo.js",
     "artifact:check": "bun run scripts/check-release-artifact.ts",
@@ -81,6 +83,7 @@
   "dependencies": {
     "@zhivex-ai/agents": "1.2.0",
     "@zhivex-ai/core": "1.6.0",
+    "@zhivex-ai/gemini": "0.10.4",
     "@zhivex-ai/meta": "0.2.1",
     "@zhivex-ai/openai": "0.9.5",
     "@zhivex-ai/qwen": "0.10.1",