@zhivex-ai/harness 1.0.0 → 1.1.0-rc.10

package/CHANGELOG.md

@@ -4,7 +4,174 @@ All notable changes to Zhivex Harness are documented in this file.
 
 The project follows Semantic Versioning. During `0.x`, minor releases may change user-facing contracts when the change is documented with a migration note. Patch releases remain backwards compatible bug fixes.
 
-## Unreleased
+## 1.1.0-rc.10 - 2026-09-23
+
+- Restore `qwen3.8-max` as the default for new CLI/Desktop selections and RC.10 certification. Keep saved models and historical release mappings unchanged.
+- Remove transient provider/SDK investigation reports and their local trial evidence; retain them in Git history.
+
+- Recover once when Meta Responses rejects a function receipt continuation because its response ID is unavailable. Replay the identical request after a bounded delay, preserve cancellation, and exclude hosted tools and unrelated HTTP errors. Host tools are not executed again.
+- Bind the new Meta transport policy to durable run identity. Use Qwen 3.8 Max, OpenAI Luna 6 and Muse Spark 1.3 release models; full release certification remains required.
+
+## 1.1.0-rc.9 - 2026-09-23
+
+- Upgrade Core to 1.23.0-next.2 and Agents to 1.9.0-next.2. All eight consumer redaction cases pass, including later rejection and file-store reopen. Qwen Flash orchestration remains intermittent, so RC certification is still blocked.
+
+- Default new Meta selections to Muse Spark 1.3 and use Responses for built-in Meta agent tool loops. Bind the transport migration to durable run identity; preserve saved model IDs and historical evidence. Certification remains pending.
+
+- Add application-owned read delegation contracts: models select task IDs while Harness preserves task text, enforces file scope and validates acceptance. Keep durable SDK execution and budgets; expose finite error classifications without logging task content.
+- Allow trusted strict-mode applications to select a fingerprint-bound tool catalog and render only relevant tool instructions. Use scoped contracts/catalogs in live certification without weakening effect, approval, journal or marker checks.
+- Integrate the published SDK next batch with failed-child linkage/accounting and OpenAI function receipt fixes. Update native-tool fixtures to the consistent metadata contract.
+- Publication remains blocked: governed Flash orchestration passed three local executions, but the scoped base campaign failed one of three cases on exact approval arguments before mutation. These are local validation results, not a new RC certification.
+
+## 1.1.0-rc.8 - 2026-09-22
+
+- Preserve OpenAI function tool receipts through approval resume using SDK result envelopes. Prevent function names such as `apply_patch` from being mistaken for native Responses tools and losing their output. Keep release assertions and fail-fast gates unchanged.
+
+## 1.1.0-rc.7 - 2026-09-22
+
+- Select `gpt-6-luna` as the OpenAI default for new CLI/Desktop choices and pin it in RC7 release certification. Preserve explicitly saved models and historical certification mappings.
+- Identify failed base live-smoke checkpoints with allowlisted labels and assertion kinds, without retaining raw assertion values or model responses.
+
+## 1.1.0-rc.6 - 2026-09-22
+
+- Stop release gates and remaining providers after a confirmed failure while retaining exhaustive manual diagnostics.
+- Preserve completed certification cases across report failures and record bounded, sanitized error structure and finalization phases.
+
+## 1.1.0-rc.5 - 2026-09-22
+
+Unpublished candidate targeting npm `next`, superseding the tagged but unpublished RC.4.
+
+- Use `qwen3.8-flash` as the default Qwen model in CLI/Desktop and the new release certification matrix. Keep Max selectable and preserve explicitly saved model choices and historical certification pins. Flash requires fresh release-bound certification.
+
+## 1.1.0-rc.4 - 2026-09-22
+
+- Align the SDK batch with the latest stable packages verified on 2026-09-22:
+  Agents 1.8.0, Core 1.22.0, Gemini 0.12.1, Meta 0.2.6, OpenAI 0.13.4 and
+  Qwen 0.15.0. Keep the compatible TypeScript 6.0.3 compiler API for architecture
+  and Stable signature checks while building with TypeScript 7.0.2.
+
+- Use searchable provider/model selection during first use, detect a lone environment
+  provider, recover failed keychain setup with explicit temporary use or retry, and
+  show one ready screen with credential source and approval policy.
+- Make `doctor` follow conversation defaults and inspect the selected environment
+  or keychain credential without contacting the provider. Human diagnostics focus
+  on the selected provider; JSON retains the full provider inventory. One-shot
+  execution continues to require explicit profiles and environment credentials.
+
+- Retain recent conversation groups by estimated tokens, adapt repair compaction
+  to remaining input allowance, and preserve structured working plans across
+  repeated summaries. Keep SDK approval/checkpoint ownership and explicit overrides.
+- Unify context estimates, reuse transport measurements and cache tool-schema
+  serialization. Default discovery to ten search matches and path-only listings;
+  callers can explicitly request larger results and digests.
+
+- Add `--no-token-budget` / `unlimitedTokens: true` to disable cumulative token
+  budgets for main runs and subagents while preserving usage accounting,
+  compaction, per-request limits, and non-token execution controls.
+
+Unpublished release candidate targeting npm `next`, following published RC.3.
+Fresh protected certification is required before publication. Stable `latest`
+remains 1.0.0.
+
+- Make appended command help independent of task/configuration validation, group options with examples, and accept `--name=value` for value options.
+- Add explicit UTF-8 task input through `zhx run -` and `zhx review -`, bounded to 1 MiB and retaining approval requirements.
+- Add atomic personal profile updates with `zhx init --update`, reopen provider/model selection after declining the default profile, and give actionable usage/configuration recovery messages.
+- Share the curated model catalog across CLI and Desktop, with primary/other groups, explicit lifecycle and validation metadata, custom model IDs, and optional HTTPS catalog distribution with cached fallback.
+- Improve the separate Desktop alpha with rendered Markdown, file diffs, conversation navigation and local preferences, accessible panels and controlled external links. Desktop retains its independent private alpha version.
+
+## 1.1.0-rc.3 - 2026-09-22
+
+Published release candidate on npm `next`. The changes below describe RC.3;
+subsequent work belongs to RC.4. Stable `latest` remains 1.0.0.
+
+- Group interactive tool activity into a bounded live line and summaries between assistant messages. Preserve individual failures, check receipts and approval requests; `/verbose` restores event detail.
+- Identify token-budget and step-limit failures without mislabeling them as provider stream failures or exposing arbitrary provider error payloads.
+- Enforce cumulative Qwen token budgets between responses for runs without subagents, including approval resume, without injecting a transport `maxTokens` parameter. An over-budget response cannot execute its requested tools or trigger another call.
+- Organize CLI, runtime, providers, persistence, tools and Desktop integration behind explicit module boundaries, with architecture checks and unchanged public API contracts.
+- Make the packaged conversation smoke select its fixture provider explicitly; onboarding is verified separately.
+- Add release preparation and early metadata validation, retain release tarballs for recovery, and distinguish publication from verification in workflow summaries.
+
+## 1.1.0-rc.2 - 2026-09-22
+
+Release candidate superseding the unpublished RC.1, targeting npm `next`.
+
+- Register the exact candidate's external model pins and reject missing pins before live certification.
+- Preserve historical 1.0 certification checks while allowing later candidates in the shared matrix.
+- Bound the governed benchmark's retained history to the latest correlated tool group so verbose Qwen turns can compact within the existing 12,000-token input ceiling. Approval, isolation and independent verification requirements remain unchanged.
+- Add deterministic coverage for the previous compaction failure and current-version model pin drift.
+
+Fresh protected certification is required for this candidate before publication.
+
+## 1.1.0-rc.1 - 2026-09-22
+
+Release candidate for the next compatible minor release, targeting the `next` channel.
+The latest stable release remains 1.0.0. Desktop has its own private alpha version.
+
+### Desktop preview
+
+- Add an experimental Electron client with durable conversations, project/worktree
+  navigation, model selection, native credential storage and governed approvals.
+- Add recoverable installation and verified update machinery. Production signing,
+  notarization and update trust configuration remain pending; automatic updates
+  remain disabled in the default alpha build.
+
+### Release validation and profile safety
+
+- Install the pinned Electron runtime explicitly before macOS native tests, including
+  the general validation job; keep other dependency lifecycle scripts disabled.
+- Bind default-profile confirmation to the displayed provider/model so a profile
+  changed while the prompt is open cannot redirect the current invocation.
+
+### Developer experience and documentation
+
+- Keep initial menu and model options visible on asynchronous terminals by preserving
+  readline prompt and menu write order; no extra arrow key is required to draw them.
+
+- Lead `zhx --help` with everyday actions; add command-specific help and `zhx help all` for the complete reference.
+- Show common slash actions first, retaining full-catalog search and `/help all`. Pending approval controls remain visible in the short help.
+- Shorten onboarding, separate user/integration/maintenance guides, and standardize maintained Desktop guides in English while quoting current UI labels.
+- Exclude maintainer-only documentation from npm using explicit guide entries and validate links inside the packed archive.
+
+Existing commands, aliases, machine output and persisted state remain compatible.
+These changes are assigned to 1.1.0-rc.1 and require fresh artifact-bound certification before publication.
+
+### Local service and replay
+
+- Add a private authenticated Unix transport and Node runtime owner with graceful drain and explicit dead-process recovery.
+- Persist redacted activity with stable event IDs, cursor replay, bounded retention and expired-cursor snapshots.
+- Coordinate approval revisions/expiry and active cancellation across clients; verify crash recovery and a single edit journal receipt against the installed artifact.
+
+### Shared client contract
+
+- Add an experimental versioned in-process adapter over existing sessions, runs, approvals and checkpoint cancellation. Strict command validation, connection-scoped idempotency and expected revisions are explicit.
+- Add a JSON Schema, integration documentation and an offline reference client tested against the installed package. No service listener, replay stream or multi-client coordination is introduced.
+
+### Daily CLI workflow
+
+- Add installed-package first-use coverage, recovery guidance and a runnable example.
+- Search project sessions and reconcile durable state and pending approvals before continuation.
+- Inspect attachment limits, retained skill receipts and context compaction; clarify exact approval scope and verification outcomes.
+- Persist per-provider/model usage across child calls and resumed runs. Optional dated pricing and per-run monetary limits block unknown or stale pricing and unknown usage; displayed costs remain estimates.
+- Prepare a frozen two-repository evaluation cohort and installed-artifact pilot driver. Complete the authorized live baseline and pilot (HAR-HU-14, 20): both artifacts scored 6/10; release recommendation remains HOLD.
+
+### Console input and streaming
+
+- Insert bracketed clipboard content as bounded, editable literal text; prevent
+  pasted commands and approval answers from executing accidentally.
+- Suppress input echo while a run is active, preserve drafts across terminal resize,
+  and deliver partial streamed lines during provider pauses and on error cleanup.
+- Extend the offline Node PTY demonstration with clipboard safety, cursor editing,
+  resize, provider failure and history recovery. JSON/JSONL and persisted state
+  contracts are unchanged.
+
+### Migration from 1.0.0
+
+- Existing CLI commands, JSON/JSONL output, public stable APIs and state format 1
+  remain compatible. Back up durable state before testing a prerelease.
+- Local service and shared client APIs remain experimental. Desktop remains a
+  separately versioned private alpha, outside the stable CLI/library guarantee.
+- Use the source development workflow until this candidate is published to npm
+  `next`; npm `latest` continues to install 1.0.0.
 
 ## 1.0.0 - 2026-09-20
 
@@ -636,3 +803,19 @@ No configuration, SQLite, approval, or execution-policy migration is required. E
 ### Added
 
 - Initial provider-portable coding harness MVP for Meta, Qwen, and OpenAI.
+
+### Experimental local service CLI
+
+- Added opt-in `--service` for run/resume/chat and session list/inspect/rename,
+  with durable event replay and existing versioned JSON/JSONL documents.
+- Persisted the shared CLI result projection and explicitly bound service run
+  admission to host scope. Added CLI/second-client crash recovery in installed smoke.
+
+### Experimental desktop chat
+
+- Added redacted per-run chat activity with durable prompts, bounded tool snapshots
+  and actual check exit codes. Session reads remain available during execution.
+- Preserved CLI JSONL compatibility; desktop strips rich engine/CLI/approval payloads,
+  deduplicates replay and reconciles lost responses before allowing another send.
+- Verified packaged macOS chat with duplicate submission, failed check, expired
+  snapshot, transport interruption, renderer reload and split-secret fixtures.

package/README.md

@@ -1,330 +1,76 @@
 # Zhivex Harness
 
-**Governed execution for coding agents.**
+**Work on your code with an agent. Review consequential actions before approving them.**
 
-[![npm](https://img.shields.io/npm/v/%40zhivex-ai%2Fharness?logo=npm)](https://www.npmjs.com/package/@zhivex-ai/harness)
-[![CI](https://github.com/Zhivex/zhivex-harness/actions/workflows/ci.yml/badge.svg)](https://github.com/Zhivex/zhivex-harness/actions/workflows/ci.yml)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22.13-339933?logo=nodedotjs)](https://nodejs.org/)
-[![License](https://img.shields.io/badge/license-MIT-22c55e.svg)](./LICENSE)
+Zhivex Harness is a local terminal assistant and TypeScript library. It supports
+OpenAI, Qwen and Meta, with provisional Gemini support. Conversations and pending
+approvals survive restarts.
 
-![Zhivex Harness: Let agents work. Control every change.](https://raw.githubusercontent.com/Zhivex/zhivex-harness/main/assets/social-preview.png)
+This development branch prepares `1.1.0-rc.9` (unpublished), with console, local
+service and Desktop preview improvements. The commands below install stable 1.0.0.
 
-Zhivex Harness runs coding agents against real repositories with conflict-safe edits, durable approvals, isolated execution, and redacted operational evidence. It is a Node-first local CLI and TypeScript library portable across Meta, Qwen, OpenAI, and provisional Gemini support, built on the Stable `@zhivex-ai/agents` runtime. Bun remains supported as development tooling and as an explicitly selected repository package manager.
+## Quick start
 
-The model provides capability. The harness controls what it may inspect, execute, change, resume, and prove. Every provider uses the same bounded tool and approval contract.
+Requires Node.js 22.13.0 or newer, Git and a provider API key.
 
-Version `1.0.0` is the current source release candidate for stable publication; it is not yet published. The latest public stable release remains `0.11.1`, and `1.0.0-rc.14` is published on `next`. RC.14 passed protected live certification and 42/42 representative cases; its security review is complete under the explicit [user-delegated AI exception](./docs/RC14_DELEGATED_SECURITY_DECISION.md), not an independent human audit. The [repository release status](https://raw.githubusercontent.com/Zhivex/zhivex-harness/main/release-status.json) records the pending stable candidate. Stable publication requires its own deterministic, installed-package, OCI, live-provider and representative gates and verified provenance. See the [readiness gate](./docs/GA_READINESS.md), [API stability policy](./docs/STABILITY.md), [support matrix](./docs/SUPPORT_MATRIX.md), [threat model](./docs/THREAT_MODEL.md), [roadmap](./ROADMAP.md) and [changelog](./CHANGELOG.md).
-
-## Why Zhivex Harness
-
-Provider choice, MCP, subagents, and containers are useful building blocks. Zhivex Harness focuses on the change-control path that connects them:
-
-1. copy an eligible, secret-free repository snapshot into an enforced OCI environment;
-2. execute only approved, allowlisted argv commands without host shell interpolation or container network;
-3. inspect a content- and run-bound patch while the host workspace remains unchanged;
-4. require a separate durable approval before importing that exact patch; and
-5. reject the import if either the reviewed patch or the host preconditions changed.
-
-Approvals, leases, idempotency claims, execution bindings, and exactly-once tool journals survive process restarts. Host deletions remain recoverable through quarantine, and operator exports are redacted by default.
-
-## Prove the boundary in five minutes
-
-The hostile-repository demo creates a disposable fixture containing malicious instructions and a decoy `.env`, then exercises the real OCI, approval, restart, patch-import, ledger, and stale-host boundaries:
-
-```bash
-bun install --frozen-lockfile
-docker pull node:24-bookworm-slim
-bun run build
-bun run demo:hostile
-```
-
-The expected result is a schema-versioned JSON proof with `secretExcluded`, `networkDenied`, `exactlyOnceJournal`, and `staleHostImportBlocked` all set to `true`. Pass `--keep` to retain the disposable workspace for inspection. The complete scenario and evidence limits are documented in [docs/HOSTILE_REPOSITORY_DEMO.md](./docs/HOSTILE_REPOSITORY_DEMO.md).
-
-## What RC.13 adds
-
-- explicit personal provider/model profiles through `zhx init` and `--profile`, stored outside the repository without credentials;
-- Tab command completion, previewed multiline tasks, bounded task history, and Alt+Enter input;
-- `/context` inspection and bounded, digest-checked `/attach` excerpts for the next task;
-- Ctrl+C cancellation with runtime cleanup and preserved pending approvals, plus recovery to the prompt after command/provider errors; and
-- terminal-safe Markdown and optional colored diffs, with unsolicited input discarded before approval prompts.
-
-See the [RC.13 changelog and migration notes](./CHANGELOG.md#100-rc13---2026-09-03) and [interactive workflow guide](./docs/CLI.md#interactive-daily-workflow). No configuration or store migration from RC.12 is required.
-
-Earlier release changes and migrations are recorded in the [changelog](./CHANGELOG.md). Browse the [documentation index](./docs/README.md) for usage, architecture, maintenance, and historical reports.
-
-It does not include arbitrary host shell access, `stdio` MCP, permanent deletion, Git writes, a desktop UI, a remote worker, or a managed sandbox service. Without `--execution oci`, shell-class tools remain unavailable. The opt-in `--oci-shell ask` policy exposes approval-bound `sh` only inside OCI. With OCI enabled, repository tools, checks, and enabled subagents share the acquired snapshot; network MCP is rejected because it cannot truthfully satisfy the no-network execution policy.
-
-## Requirements
-
-- Node.js 22.13.0 or newer. Node 24 LTS is used by the default OCI image and release workflow.
-- Git for repository status and diff inspection.
-- At least one supported provider credential for real model execution.
-- Docker or Podman plus a preloaded image when `--execution oci` is requested.
-
-## Installation
-
-Run the Node-first `latest` release with an exact version:
-
-```bash
-bunx @zhivex-ai/harness@0.11.1 --version
-```
-
-To try the published RC.13 candidate on `next`, pin its exact version:
-
-```bash
-bunx @zhivex-ai/harness@1.0.0-rc.13 --version
-bunx @zhivex-ai/harness@1.0.0-rc.13 init --profile daily --provider openai
-bunx @zhivex-ai/harness@1.0.0-rc.13 doctor --profile daily
-bunx @zhivex-ai/harness@1.0.0-rc.13 --profile daily "inspect this repository"
-```
-
-RC.13 is a prerelease; publication on `next` does not promote it to GA.
-
-To exercise the source checkout, contributors use Bun for deterministic repository tooling while the built CLI itself runs on Node:
-
-```bash
-bun install --frozen-lockfile
-cp .env.example .env
-bun run dev --version
-```
-
-RC.13 includes first-run setup that stores only a provider and model in an explicit personal profile. From a source checkout:
-
-```bash
-bun run dev init --profile daily --provider openai
-bun run dev doctor --profile daily
-bun run dev --profile daily "inspect this repository"
-```
-
-Installed builds expose the same flow as `zhx init`. Profiles are private user configuration outside the repository, use owner-only permissions, contain no credentials, and are never selected implicitly. CLI flags override the selected profile; the selected profile overrides environment variables; environment variables override built-in defaults.
-
-Configure only the providers you plan to use:
-
-```dotenv
-OPENAI_API_KEY=...
-MODEL_API_KEY=...
-DASHSCOPE_API_KEY=...
-GEMINI_API_KEY=...
-```
-
-`MODEL_API_KEY` is used by the Meta Model API. Qwen also accepts `QWEN_API_KEY`; `DASHSCOPE_API_KEY` takes precedence. Gemini also accepts `GOOGLE_GENERATIVE_AI_API_KEY`.
-
-## Diagnose the environment
-
-`doctor` is local and does not contact provider endpoints:
-
-```bash
-zhx doctor
-zhx doctor --profile daily
-zhx doctor --provider qwen --json
-```
-
-For a source checkout, replace `zhivex-harness` with `bun run dev`.
-
-## Usage
-
-Start the durable console with the ergonomic command, or use the long alias in existing scripts:
-
-```bash
+```sh
+npm install -g @zhivex-ai/harness@1.0.0
+cd /path/to/your/project
 zhx
-zhx chat --continue
-zhivex-harness --version
-```
-
-Inside the console, `/help` lists `/provider`, `/model`, `/route`, `/status`, `/diff`, `/review`, `/resume`, `/pending`, `/approve`, `/deny`, `/compact`, `/new`, `/rename`, and `/exit`. Tool and step activity is rendered without tool payloads; approval cards sanitize terminal controls and keep governed edit/command payloads fully reviewable.
-
-The published RC.13 also adds Tab command completion, `/paste` for previewed
-multiline tasks, `/context` for active project rules/skills, and `/attach <path>` for
-bounded file excerpts. Ctrl+C interrupts active work while retaining the session;
-errors return to the prompt. See the [interactive workflow](./docs/CLI.md#interactive-daily-workflow)
-for attachment limits, approval behavior, and recovery. These source additions are
-not yet published or live-certified.
-
-Project context engineering is enabled by default. A root `AGENTS.md` plus an optional `.zhivex/harness.json` can declare bounded context files, rule files, and progressively loaded `SKILL.md` directories. Disable discovery with `--no-project-context` or select another manifest with `--context-config`.
-
-Show providers and detected configuration without printing secrets:
-
-```bash
-zhx providers
-zhx providers --json
 ```
 
-Run a task against the current directory:
+On first use, choose a provider and model, then enter your API key in the hidden
+prompt. Save it in the system keychain (macOS/Linux) or use it only for the current
+CLI session. Existing environment keys take precedence. See [First use](docs/FIRST_USE.md)
+and [Credentials](docs/CREDENTIALS.md) for setup and automation.
 
-```bash
-zhivex-harness run --provider openai "review the repository and fix the tests"
-zhivex-harness run --provider meta "document the current architecture"
-zhivex-harness run --provider qwen "implement the pending endpoint"
-zhx run --provider gemini "review the proposed implementation"
-```
+Try: “Explain this repository and suggest a small improvement.”
 
-Operate on another workspace:
+Type `/` for common actions. `/model` changes the model, `/sessions` finds previous
+conversations, and `/diff` shows changes. Review requested actions before approving
+them. Ctrl+C stops active work; it does not undo completed changes.
 
-```bash
-zhivex-harness run --provider qwen --workspace ../my-app "fix the typecheck errors"
-```
+## A few commands are enough
 
-Interactive mode:
+| Command | Purpose |
+| --- | --- |
+| `zhx` | Open the conversation |
+| `zhx --continue` | Continue the latest conversation |
+| `zhx run "task"` | Run one task for automation |
+| `zhx doctor` | Diagnose local configuration |
+| `zhx --help` | Show the short guide |
 
-```bash
-zhx chat --provider meta
-zhx chat --continue
-zhx sessions list
-```
+Use `zhx <command> --help` for command-specific options, or `zhx help all` for the
+complete reference. Existing `zhx chat` and `zhivex-harness` commands remain supported.
 
-Route only selected subagent roles; credentials are required only for providers actually instantiated:
+## CLI, library or Desktop?
 
-```bash
-zhx run --provider openai --route explorer=qwen --route reviewer=gemini \
-  "implement the change, then review it independently"
-```
+The npm package includes the CLI and TypeScript library. [Desktop](https://github.com/Zhivex/zhivex-harness/blob/main/desktop/README.md)
+is a separate Electron application, currently alpha for macOS Apple Silicon.
+It is not included in npm and has its own build and distribution process. Its local
+package is unsigned and unnotarized; automatic updates are disabled pending production trust setup and validation.
 
-Routing with `--max-cost-usd` remains rejected in `0.11.1`: aggregate usage cannot yet be priced correctly when roles use different models.
-
-Writes and checks pause for approval. In a non-interactive execution, state is saved in `.zhivex-harness/runs/operations.sqlite`:
-
-```bash
-zhivex-harness resume <runId> --approve
-zhivex-harness resume <runId> --deny
-```
-
-Duplicate external requests can share a durable run identity:
-
-```bash
-zhivex-harness run --idempotency-key issue-482 "fix the reported regression"
-```
-
-Operate on runs without loading a provider or requiring its credential:
-
-```bash
-zhivex-harness runs list --status waiting_approval
-zhivex-harness runs inspect <runId> --json
-zhivex-harness runs export <runId> --json
-zhivex-harness runs cancel <runId> --reason "superseded"
-zhivex-harness runs cleanup --before 2026-08-01T00:00:00Z
-```
+## Permissions and limits
 
-Operations are scope-bound. The defaults are tenant `local` and a namespace derived from the canonical workspace. Supply the same `--tenant`, `--user`, and `--namespace` values across run and operator commands. Migration, budgets, redaction, retention, and compatibility limits are documented in [docs/DURABLE_OPERATIONS.md](./docs/DURABLE_OPERATIONS.md).
+Edits and checks require approval by default. Files such as `.env`, private keys,
+Git internals and dependency directories are excluded from model exploration.
+The default runtime has no OS isolation and exposes no shell-class tools. Running
+commands in isolation requires an explicitly configured Docker or Podman environment;
+see [Execution environments](docs/EXECUTION_ENVIRONMENTS.md).
 
-Use governed MCP and bounded subagents explicitly:
+Gemini remains provisional. See the [support matrix](docs/SUPPORT_MATRIX.md) and
+[security policy](SECURITY.md) for supported configurations and reporting concerns.
 
-```bash
-zhivex-harness run --mcp-config examples/mcp-config.json "consult the allowed documentation tools"
-zhivex-harness run --subagent explorer --subagent reviewer "analyze the boundary"
-zhivex-harness review --reviewer explorer --reviewer reviewer --json "review the durable runtime"
-```
-
-MCP configuration, capability gates, child budgets, promoted approvals, review groups, migration, and known limits are documented in [docs/EXTENSIBILITY.md](./docs/EXTENSIBILITY.md).
-
-`--yes` automatically approves tools with side effects. Use it only inside a disposable or isolated workspace:
-
-```bash
-zhivex-harness run --provider openai --yes "apply the change and validate it"
-```
-
-Structured automation output uses schema version `1`:
-
-```bash
-zhivex-harness run --provider qwen --json "analyze the issue without modifying files"
-zhx run --provider gemini --jsonl "analyze the issue without modifying files"
-```
-
-The JSON shapes and exit codes are documented in [docs/CLI.md](./docs/CLI.md).
-
-Create a portable change-admission envelope from structured, redacted evidence and the exact patch bytes, then verify it without provider credentials or network access:
-
-```bash
-zhx changes create examples/change-envelope-input.json --patch examples/change.patch > change-envelope.json
-zhx changes verify change-envelope.json --patch examples/change.patch
-```
+## Documentation
 
-The verifier proves integrity, expiry, and explicit preconditions; it deliberately reports approval and external-attestation authenticity as `not-verified`. See [docs/CHANGE_ENVELOPES.md](./docs/CHANGE_ENVELOPES.md).
+- **Users:** [First use](docs/FIRST_USE.md), [daily workflow](docs/CLI.md#interactive-daily-workflow), [usage reference](docs/USAGE.md).
+- **Integrators:** [CLI contracts](docs/CLI.md), [extensibility](docs/EXTENSIBILITY.md), [API stability](docs/STABILITY.md).
+- **Contributors:** [Development](https://github.com/Zhivex/zhivex-harness/blob/main/CONTRIBUTING.md) and [maintenance](https://github.com/Zhivex/zhivex-harness/blob/main/docs/MAINTENANCE.md).
 
-Repository edits use digest-bound proposals. Discovery returns `nextCursor` when another deterministic page is available; mutating tools reject stale content instead of merging or overwriting it. Deletions move files into harness-owned quarantine and return a recovery identifier. The complete contract and migration from `0.2.x` are documented in [docs/REPOSITORY_EDITING.md](./docs/REPOSITORY_EDITING.md).
+[Browse documentation](docs/README.md).
 
-The default check allowlist is `test`, `typecheck`, `lint`, and `build`. Replace it with repeatable CLI flags when a repository uses different declared scripts:
-
-```bash
-zhivex-harness run --allow-check test:unit --allow-check format "apply the fix and validate it"
-```
-
-The harness uses a pinned `packageManager` field when present; otherwise it accepts one unambiguous npm, pnpm, Yarn, or Bun lockfile and defaults to npm when neither signal exists. It executes only the selected script and rejects symbolic-link or ambiguous lockfiles plus implicit `pre<script>`/`post<script>` lifecycle hooks.
-
-Enable enforced local execution explicitly. The image must already exist locally; the harness never pulls it implicitly:
-
-```bash
-docker pull node:24-bookworm-slim
-zhivex-harness doctor --execution oci
-zhivex-harness run --execution oci --yes "inspect, implement, test, review the environment patch, and import it"
-zhivex-harness run --execution oci --oci-shell ask "use a reviewed shell pipeline inside the isolated snapshot"
-```
-
-`--yes` approves eligible command execution and the distinct host patch import; it cannot enable a shell whose policy is `deny`. Omit it when a human should review each durable approval. Configuration, threat boundary, cleanup, and certification details are in [docs/EXECUTION_ENVIRONMENTS.md](./docs/EXECUTION_ENVIRONMENTS.md).
-
-## Providers and defaults
-
-| Provider | Default model | Support in `latest` (`0.11.1`) |
-| --- | --- | --- |
-| Meta | `muse-spark-1.2` | `MODEL_API_KEY` · 0.11.1 release-bound base, delegation, and OCI execution certified |
-| Qwen | `qwen3.8-max` | `DASHSCOPE_API_KEY` or `QWEN_API_KEY` · 0.11.1 release-bound base, delegation, routing, and OCI execution certified |
-| OpenAI | `gpt-5.6-luna` | `OPENAI_API_KEY` · 0.11.1 release-bound base, delegation, routing, and OCI execution certified |
-| Gemini | `gemini-3.6-flash` | `GEMINI_API_KEY` or `GOOGLE_GENERATIVE_AI_API_KEY` · provisional until the harness live matrix passes |
-
-Override any model with `--model`. Optional provider overrides are `META_BASE_URL`, `QWEN_BASE_URL`, `QWEN_WORKSPACE_ID`, `QWEN_REGION`, `OPENAI_BASE_URL`, and `GEMINI_BASE_URL`. Non-credential transport settings are hash-bound to durable resumes without persisting their values.
-
-The exact `v0.11.1` tag passed proposal/approval/restart, bounded delegation, OpenAI-parent/Qwen-reviewer routing, and model-directed OCI execution for Meta `muse-spark-1.2`, Qwen `qwen3.8-max`, and OpenAI `gpt-5.6-luna` on 2026-08-23. Luna remains the OpenAI default, while Terra and Sol remain explicit `--model` selections with older local base evidence only. Controlled and official-SDK MCP interoperability are verified separately and do not imply compatibility with every server or protocol feature. Provider capability claims remain artifact- and date-bound under the [live certification contract](./docs/LIVE_CERTIFICATION.md); credential detection and deterministic tests do not replace real provider evidence.
-
-For `next`, the exact `v1.0.0-rc.13` artifact passed protected live certification and all 14 representative cases for each of Meta `muse-spark-1.2`, Qwen `qwen3.8-max`, and OpenAI `gpt-5.6-luna` on 2026-09-08. See the [RC.13 release evidence](./docs/LIVE_CERTIFICATION.md#current-public-status) for the workflow and artifact identity. Gemini remains provisional.
-
-## Security boundaries
-
-- Every workspace path is resolved against a canonical root.
-- Reads and writes that cross an external symlink are rejected.
-- Dependencies, build output, Git internals, harness state, `.env`, `.npmrc`, and private keys are excluded from model exploration.
-- The model has no generic shell.
-- Only explicitly allowed, declared package scripts can run; the model must provide the exact script text for approval binding.
-- Checks run without automatic `.env` loading and with a reduced environment.
-- Patch application, moves, quarantine, restore, and command execution require interruptible approval.
-- Every edit carries the digest observed during inspection; stale creates and updates fail closed.
-- Existing file modes are preserved and successful replacements are published atomically.
-- Unsafe state roots, protected workspace paths, files, and symlink targets are rejected before a run store is created.
-- Environment values are not injected into prompts, diagnostics, or tool responses.
-- Remote MCP output is bounded, schema-checked, treated as untrusted, and rejected on common prompt-injection directives.
-- Network MCP always pauses for approval; custom read-only annotation trust must be explicit and injected by the host application.
-- Subagent children inherit scope, workspace, cancellation, approval, and store policy while retaining independent budgets and fingerprints.
-- OCI execution binds the durable run to the resolved image identity and enforced policy; resume fails if either changes.
-- Snapshot discovery excludes secrets, Git internals, harness state, dependency trees, and build output. Dependencies may be mounted separately read-only.
-- Untrusted commands receive a quota-backed tmpfs workspace, never a writable host bind; only successful, frozen, validated snapshots replace durable environment state.
-- Container processes receive no provider credentials or arbitrary host environment values, and host changes require a separately approved digest-bound patch import.
-
-The default `none` backend provides governance but no OS isolation and therefore exposes no shell-class tool. The local OCI backend enforces the documented container boundary, but it is not a VM or a managed hostile-code sandbox; use a dedicated host or microVM when the container runtime itself is outside the threat model.
-
-## Development
-
-```bash
-bun run typecheck
-bun run readiness:1.0
-bun test
-bun run build
-bun run evaluate
-bun run benchmark:workspace
-bun run benchmark:workspace -- --files 50000 --repetitions 10 --warmups 2
-bun run benchmark:oci -- --files 1000 --commands 20 --repetitions 10 --warmups 1
-bun run benchmark:safe-fix:ci
-bun run smoke:package
-bun run pack:inspect
-bun run check
-```
-
-The workspace benchmark reports topology-only and digest-bound listing separately, plus independent versus batched search with alternating pair order. The OCI benchmark reports environment setup, snapshot/session acquisition, first command, reused commands, mutation, and end-to-end time to first successful command. Both fixtures exclude setup, validate results, use sequential repetitions, and emit host/runtime metadata, nearest-rank p50/p95/p99, and success rates. `--repetitions` and `--warmups` are configurable; host filesystem caches are not flushed, so publish the commit and exact command with any result. Use at least 100 successful samples before treating p99 as representative.
-
-The [Time-to-Safe-Fix benchmark](./docs/TIME_TO_SAFE_FIX.md) adds task-level clean/attacked matrices, `safeResolved` scoring, approval/system latency separation, Wilson rate intervals, and matched overhead against a direct profile. Its bundled deterministic smoke validates only the benchmark pipeline. Public capability or safety claims require a real external driver, exact dataset revision, matched model/runtime controls, and disclosed failures.
-
-Full generated reports remain local and Git-ignored under `./results/` (source checkout). Commit only digest-verified, sanitized evidence snapshots under [`benchmarks/baselines`](./benchmarks/baselines/).
-
-The live gate is opt-in and billable:
-
-```bash
-ZHIVEX_HARNESS_LIVE=1 bun run scripts/live-provider-smoke.ts
-ZHIVEX_HARNESS_LIVE=1 bun run smoke:live:routing
-```
+Version `1.0.0` is the current public npm release. Source checkout changes can be
+newer than the published package. Consult the [changelog](CHANGELOG.md) and
+[repository release status](https://raw.githubusercontent.com/Zhivex/zhivex-harness/main/release-status.json)
+for release identity; [release evidence](https://github.com/Zhivex/zhivex-harness/blob/main/docs/LIVE_CERTIFICATION.md)
+records validation scope and limitations.

package/SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Supported versions
 
-Security fixes are provided for the latest published `0.11.x` patch. Older minors and private checkpoints are not supported release channels. Registry integrity and provenance do not substitute for the separate provider and execution evidence recorded in [docs/LIVE_CERTIFICATION.md](./docs/LIVE_CERTIFICATION.md).
+Security fixes are provided for the latest published `1.0.x` patch. Older minors and private checkpoints are not supported release channels. Registry integrity and provenance do not substitute for the separate provider and execution evidence recorded in [docs/LIVE_CERTIFICATION.md](https://github.com/Zhivex/zhivex-harness/blob/main/docs/LIVE_CERTIFICATION.md).
 
 ## Reporting a vulnerability
 

package/SUPPORT.md

@@ -1,8 +1,8 @@
 # Support
 
-Zhivex Harness `0.11.x` is the latest supported pre-1.0 Node-first CLI and TypeScript library. Observable contracts may change in a later minor release when the change and migration path are documented in [CHANGELOG.md](./CHANGELOG.md). The mutable machine-readable public release state is recorded in the repository [release-status.json](https://raw.githubusercontent.com/Zhivex/zhivex-harness/main/release-status.json), outside immutable npm artifacts.
+Zhivex Harness `1.0.x` is the latest supported Node-first CLI and TypeScript library. Stable 1.x contracts follow [the stability policy](./docs/STABILITY.md); incompatible changes require a major release except documented urgent security corrections. Beta and experimental surfaces retain their declared policies. The mutable machine-readable public release state is recorded in the repository [release-status.json](https://raw.githubusercontent.com/Zhivex/zhivex-harness/main/release-status.json), outside immutable npm artifacts.
 
-The detailed 1.0 target is tracked in the [machine-readable support matrix](./docs/support-matrix.json) and its [human-readable view](./docs/SUPPORT_MATRIX.md). Compatibility and removals follow [DEPRECATIONS.md](./docs/DEPRECATIONS.md) once 1.0 is promoted.
+The 1.0 support scope is tracked in the [machine-readable support matrix](./docs/support-matrix.json) and its [human-readable view](./docs/SUPPORT_MATRIX.md). Compatibility and removals follow [DEPRECATIONS.md](./docs/DEPRECATIONS.md) for the published 1.x line.
 
 ## Supported baseline
 
@@ -13,7 +13,11 @@ The detailed 1.0 target is tracked in the [machine-readable support matrix](./do
 - the provider/model combinations marked certified in the package documentation; and
 - HTTPS or explicitly allowed loopback-HTTP MCP endpoints using the documented bounded JSON-RPC subset.
 
-Only the most recent published `0.11.x` patch receives routine fixes. The exact `v0.11.1` tag passed the protected release-bound base, orchestration, routing, and model-directed execution matrix for Meta, Qwen, and OpenAI on 2026-08-23. Gemini remains provisional until its complete harness live matrix passes against an exact release candidate. Live provider evidence is account-, model-, endpoint-, artifact-, and date-dependent; see [docs/LIVE_CERTIFICATION.md](./docs/LIVE_CERTIFICATION.md).
+Only the most recent published `1.0.x` patch receives routine fixes. The exact `v1.0.0` tag passed protected release-bound base, orchestration, routing and model-directed execution for Meta, Qwen and OpenAI on 2026-09-20; the complete representative matrix passed on its authorized second attempt. Gemini remains provisional until its complete harness live matrix passes against an exact release candidate. Live provider evidence is account-, model-, endpoint-, artifact-, and date-dependent; see [docs/LIVE_CERTIFICATION.md](https://github.com/Zhivex/zhivex-harness/blob/main/docs/LIVE_CERTIFICATION.md).
+
+## Installation diagnostics
+
+Follow the [stable installation commands](./README.md#installation) or [isolated Bun example](./examples/README.md). Run `zhx --version`, `zhx --help`, and `zhx doctor` before reporting an installation issue. Doctor is local: a missing provider credential produces a diagnostic failure until that credential is configured. Include the version, OS, Node/Bun versions and sanitized diagnostics in a report; never include keys or your `.env` file.
 
 ## Support channels