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

package/docs/FIRST_USE_EXAMPLE.md

@@ -0,0 +1,40 @@
+# Worked example: approvals and recovery
+
+Use a supported Node runtime and Bun for the example's checks. Copy the packaged
+`examples/first-use` directory to a disposable working directory. Initialize Git
+there so `git_diff` can show the reviewed changes. Run `bun test` to verify the
+unchanged example.
+
+1. Run `zhx init --profile first-use --provider openai --model gpt-5.6-luna`.
+   Substitute another supported provider/model if desired. The profile stores
+   provider/model selection, never an API key.
+2. Set the provider credential in your shell using its secure input mechanism.
+   Do not paste it into a task or commit it. `zhx providers` lists variable names.
+3. Run `zhx doctor --profile first-use --workspace .`. This checks credential
+   presence, runtime and workspace configuration, not whether the remote API
+   accepts the key. The first actual model request verifies that boundary.
+4. Run `zhx chat --profile first-use --workspace . --allow-check test`.
+5. Ask: “Extend greeting to trim whitespace and return Hello, world! for an empty
+   name. Add focused tests. Read the existing files first, request approval for
+   changes, run the test check and inspect the final diff.”
+6. Review the complete paths, digest-bound edits and exact test command before
+   answering the approval. Use `/diff` to inspect the result, `/context` to inspect
+   context and `/usage` to inspect provider/model usage. No price means unknown
+   cost. A completed model turn alone does not certify checks.
+7. Exit and reopen with `zhx chat --continue --workspace .`. Pending approvals
+   and durable status appear before a new task. `/sessions [text]` searches this
+   project; `/rename <title>` labels the current session.
+
+Missing credentials: set the named environment variable and rerun doctor. Rejected
+credentials: correct or rotate the key at the provider, then retry a read-only task.
+Provider unavailable: check its availability, wait or select another configured
+provider for a new task; inspect persisted runs before repeating an edit.
+OCI unavailable: start Docker/Podman and preload the configured immutable image,
+then rerun doctor. Do not bypass requested isolation. See [support](SUPPORT_MATRIX.md)
+for the platforms and providers actually certified.
+
+The repository's `bun run scripts/first-use-smoke.ts /absolute/installed/dist/cli.js`
+reproduces initialization, secret-free diagnostics, an approved edit/check/diff,
+restart, missing/invalid credentials, unavailable provider and missing OCI with
+an entirely local transport fixture. `smoke:artifact` runs it on an installed
+tarball. This proves the client flow; it is not live credential certification.

package/docs/HOSTILE_REPOSITORY_DEMO.md

@@ -87,7 +87,7 @@ The deterministic demo does not certify model-directed tool use. The billable li
 ZHIVEX_HARNESS_LIVE=1 bun run smoke:live:execution
 ```
 
-Provider evidence is date-, model-, endpoint-, account-, and credential-dependent. See [LIVE_CERTIFICATION.md](./LIVE_CERTIFICATION.md).
+Provider evidence is date-, model-, endpoint-, account-, and credential-dependent. See [LIVE_CERTIFICATION.md](https://github.com/Zhivex/zhivex-harness/blob/main/docs/LIVE_CERTIFICATION.md).
 
 ## Evidence limits
 

package/docs/LOCAL_SERVICE.md

@@ -0,0 +1,142 @@
+# Local runtime service and durable activity
+
+The experimental shared service uses a Unix-domain socket in an owner-private
+0700 directory. There is no TCP listener. The socket, bootstrap credentials and
+ownership file are 0600. Every request authenticates a random 256-bit bearer token;
+Origin and Sec-Fetch-Site browser requests are rejected, including authenticated
+ones. The renderer must communicate through a trusted native bridge and must not
+receive this token or general filesystem access.
+
+```sh
+bun run build
+bun run service --workspace /absolute/repository --directory "$HOME/.zhivex-harness/service" --provider openai
+```
+
+The Node process inherits provider credentials from its host environment. It writes
+only a `service-ready` JSON document with the private credential-file path to stdout;
+tokens are never printed. The same service can be embedded through
+`startHarnessLocalService(harness, {directory})`. It takes ownership of the supplied
+Harness on successful startup. Startup failure leaves the host responsible for closing
+its Harness. Directory paths must be short enough for Unix socket limits (100 bytes
+including the socket filename), owner-private and non-symlink final directories.
+Only macOS/Linux Unix transport is implemented; this does not certify other platforms.
+
+## Transport and lifecycle
+
+Use `readHarnessLocalCredentials(path)` (owner-private descriptor-bound read,
+O_NOFOLLOW, maximum 4 KiB), then `requestHarnessLocalService(credentials, "hello",
+{versions:[1]})`. Send the HU-21 strict envelope to `"command"`. There are no client
+supplied provider keys, tool policies or workspace overrides in that envelope.
+
+Requests are bounded to 128 KiB and decoded only after authentication. JSON is required;
+unknown routes and malformed requests receive sanitized machine errors. Error bodies
+never contain exceptions, stack traces or provider response payloads. Noninteractive
+clients should reconcile state after a transport failure rather than retrying with a
+new idempotency key.
+
+One service owns a workspace/scope in the chosen service directory. A private exclusive
+ownership file prevents duplicate startup in that directory. The launcher must use
+one canonical directory for its configured workspace/scope; starting another owner
+in a different directory is not a supported deployment. Two clients share the same
+adapter, revisions, admitted command receipts and runtime owner. Duplicate idempotency
+keys join the original result; competing approval decisions get REVISION_CONFLICT.
+Approval digests, full pending-request set, run revision and expiry are checked before
+the engine's signed payload and workspace preconditions.
+
+Disconnecting a client does not abort an admitted command. SIGINT/SIGTERM stop
+admission and drain accepted work before closing the engine and removing owned
+transport files; the engine's configured timeout remains in force. Pending approvals
+remain durable. Explicit cancellation of an owned active run first persists the
+cancellation request, then aborts the owner invocation. Checkpoint cancellation is
+final and cascades. Queries of the active run remain available during cancellation.
+
+SIGKILL/process crash leaves the ownership file and runtime state. Startup fails
+closed until explicit `--recover` or `recoverHarnessLocalService` confirms the recorded
+PID is dead, checks ownership/types/modes and removes only transport files. A live
+PID (including reuse) blocks recovery conservatively. Recovery does not delete databases,
+replay a mutation or silently repair an uncertain tool effect. It rotates authentication
+and the connection epoch; reconnect, query the durable session and inspect its pending
+approval before a new decision. Existing engine journal/leases govern safe resumption.
+
+## Replay contract
+
+`requestHarnessLocalService(credentials, "events", {projectId, sessionId, after})`
+returns a bounded page (up to 200 events). Each event carries schemaVersion 1,
+eventId, monotonic sequence, sessionId, runId, timestamp and allowlisted activity.
+Use nextCursor for the next page. Retrying a page returns identical stable event IDs;
+clients deduplicate by eventId and must never execute tools in response to replay.
+Sequences may have gaps because the database also contains other sessions/scopes.
+
+The SQLite transaction saves event and materialized snapshot together. Defaults:
+10,000 retained events per project/scope, seven-day event retention, 64 KiB per event,
+256 KiB retained text per run, 1,000 runs and 2 MiB per session snapshot. Overflow
+fails explicitly; snapshots mark truncated text. The existing session store bounds
+session creation. Snapshot state is retained for reconstruction while old events are
+pruned. An expired cursor returns `cursorExpired: true`, the current snapshot and a
+new recovery cursor; replace the view from that snapshot and continue. A cursor ahead
+of the session's sequence is rejected.
+
+Tool inputs/results, model messages, provider payloads and raw errors are omitted
+from events. Text is redacted before SQLite writes, including configured secrets and
+common API token forms split across chunks; the unfinished token is buffered until
+a boundary so partial secrets are not streamed. Very long unfinished tokens become
+TRUNCATED. A crash can therefore omit an unflushed partial token; completed checkpoints
+flush the remaining sanitized text. Activity output is untrusted text, never executable
+markup. Expired-cursor snapshots preserve the same sanitized representation.
+
+## Verification and limits
+
+```sh
+bun --no-env-file test tests/local-service.test.ts tests/service-events.test.ts tests/client-contract.test.ts
+bun --no-env-file run scripts/local-service-smoke.ts
+# The same Node subprocess smoke can target an installed artifact:
+bun --no-env-file run scripts/local-service-smoke.ts /absolute/consumer/node_modules/@zhivex-ai/harness/dist/index.js
+```
+
+Integration tests exercise real Unix sockets, rejected credentials/origins, shutdown,
+disconnect during streaming, active cancellation, concurrent decisions, expiry, durable
+replay and secret splitting. The Node subprocess smoke injects SIGKILL at an approval,
+recovers the dead owner, verifies identical approval and replay state, invalidates old
+credentials, applies the approved edit exactly once and inspects its completed journal
+receipt. Fixtures use mock providers; no live API or certification claim is made.
+
+The CLI service adapter and the [desktop](https://github.com/Zhivex/zhivex-harness/blob/main/desktop/README.md) share this transport. Desktop signing, notarization and positive signed-update acceptance remain pending; the local unsigned build is not a production distribution.
+
+The CLI adapter now consumes this transport via opt-in `--service`; see
+[CLI.md](CLI.md#shared-local-service-experimental). It shares the direct CLI result
+serializer and persists that projection with the run. New run admission explicitly
+uses the host scope. No renderer or CLI can override it.
+
+## Chat activity and concurrent readers
+
+User prompts are recorded once per admitted run as redacted `user-message` activity.
+Snapshots retain the prompt, bounded text, run status and up to 256 tool records per
+run. A `run_check` tool result exposes only its integer exitCode and timedOut flag;
+a successful tool transport does not prove a check passed. Raw stdout/stderr and
+arguments remain excluded. Prompt display is bounded to 60 KiB after redaction and
+marks truncation. Known secret values containing spaces are buffered across chunks.
+
+Session/project reads remain available while a run is active. Those reads do not
+refresh session revisions; clients query the selected run for current status. They
+cannot submit another mutation through this read path. Service-mode CLI skips the
+new user-message records so its existing JSONL event contract remains unchanged.
+
+Desktop applies cursor and activity updates atomically and ignores duplicate or
+older pages. Expired cursors replace the view from the durable snapshot. Main drops
+raw engine output, the rich CLI result and approval arguments before returning a
+run to the renderer, and redacts known host credential values and common token forms.
+This is a renderer/activity boundary; it does not claim that all historical engine
+state or the separate operator-facing rich CLI contract is a sanitized export.
+
+Dead-owner recovery serializes through the workspace operations database's write
+lock. The lock is acquired before reading transport ownership and released after
+stale files are removed, with the owner lock file removed last. A concurrent
+recoverer either fails with contention or rereads current ownership; it cannot act
+on an old owner snapshot after another service starts. Database/session contents
+are preserved, and the operating system releases the SQLite lock on process exit.
+
+Recovery uses `busyTimeoutMs: 0` while opening the session index and zero SQLite
+busy timeout for its ownership transaction. Contention fails immediately rather
+than blocking the event loop while another recovery awaits filesystem I/O.
+`OpenSessionStoreOptions.busyTimeoutMs` accepts 0–5000 ms and preserves the prior
+5000 ms default for other callers. The additive signature snapshot is reviewed.

package/docs/README.md

@@ -1,33 +1,34 @@
 # Documentation
 
-Start with the [project README](../README.md) for installation and a first run. These guides describe the source checkout; published certification applies only to the exact artifacts recorded in the release evidence.
+## Use Harness
 
-## Usage and integration
+Start with [First use](FIRST_USE.md). You only need `zhx` for everyday conversations.
 
-- [CLI](CLI.md): commands, interactive sessions, configuration and output contracts.
-- [Repository editing](REPOSITORY_EDITING.md): proposals, approvals, moves and recovery.
-- [Durable operations](DURABLE_OPERATIONS.md): persistence, budgets, resumption and migrations.
-- [Context engineering](CONTEXT_ENGINEERING.md): instructions, task memory and compaction.
-- [Extensibility](EXTENSIBILITY.md): providers, MCP, routing and subagents.
-- [Execution environments](EXECUTION_ENVIRONMENTS.md): OCI configuration and isolation.
-- [Change envelopes](CHANGE_ENVELOPES.md): portable change evidence and verification.
-- [Hostile repository demo](HOSTILE_REPOSITORY_DEMO.md): runnable boundary demonstration.
+- [Daily console workflow](CLI.md#interactive-daily-workflow): editing, files, approvals and recovery.
+- [Worked example](FIRST_USE_EXAMPLE.md): a small change with approval and restart recovery.
+- [Usage reference](USAGE.md): scripts, providers and security boundaries.
+- [Credentials](CREDENTIALS.md): system keychain, temporary keys and automation.
+- [Project instructions and context](CONTEXT_ENGINEERING.md).
+- [Execution environments](EXECUTION_ENVIRONMENTS.md): isolated command execution.
+- [Desktop](https://github.com/Zhivex/zhivex-harness/blob/main/desktop/README.md): separate macOS alpha application.
+- [Support](../SUPPORT.md), [support matrix](SUPPORT_MATRIX.md), [security policy](../SECURITY.md).
 
-## Contracts and security
+## Integrate Harness
 
-- [API stability](STABILITY.md), [support matrix](SUPPORT_MATRIX.md) and [deprecations](DEPRECATIONS.md).
+- [CLI reference](CLI.md): command options, JSON/JSONL and exit codes.
+- [Extensibility](EXTENSIBILITY.md): providers, MCP, routing and subagents.
+- [API stability](STABILITY.md) and [deprecations](DEPRECATIONS.md).
+- [Local service](LOCAL_SERVICE.md) and [client protocol](CLIENT_PROTOCOL.md).
+- [Durable operations](DURABLE_OPERATIONS.md), [repository editing](REPOSITORY_EDITING.md) and [change envelopes](CHANGE_ENVELOPES.md).
 - [Threat model](THREAT_MODEL.md) and [public repository security](PUBLIC_SECURITY.md).
-- [Security policy](../SECURITY.md) and [support policy](../SUPPORT.md).
-- [Gemini 1.0 decision](GEMINI_1_0_DECISION.md): dated support decision and promotion requirements.
-
-## Maintenance and release
 
-- [Contributing](https://github.com/Zhivex/zhivex-harness/blob/main/CONTRIBUTING.md), [roadmap](../ROADMAP.md) and [changelog](../CHANGELOG.md).
-- [Release procedure](RELEASE.md) and [rollback](ROLLBACK.md).
-- [Live certification](LIVE_CERTIFICATION.md): artifact-bound provider evidence.
-- [GA readiness](GA_READINESS.md), [security review requirements](SECURITY_REVIEW_EVIDENCE.md) and [RC.13 reviewer dossier](RC13_SECURITY_REVIEW.md).
+## Contribute and maintain
 
-## Evaluation and historical reports
+[Contributor guide](https://github.com/Zhivex/zhivex-harness/blob/main/CONTRIBUTING.md) ·
+[Maintenance and release evidence](https://github.com/Zhivex/zhivex-harness/blob/main/docs/MAINTENANCE.md) ·
+[Changelog](../CHANGELOG.md)
 
-- [Benchmark guide](../benchmarks/README.md) and [Time-to-Safe-Fix protocol](TIME_TO_SAFE_FIX.md).
-- [Report index](reports/README.md): dated audits, remediation evidence and model comparisons. Historical findings and scores do not describe later code automatically.
+Primary guides are maintained in English. Historical reports preserve their original
+language and evidence. Maintainer procedures and reports remain in the repository
+and are excluded from the npm package. Published validation applies to the exact
+release artifact, not automatically to later source changes.

package/docs/THREAT_MODEL.md

@@ -17,7 +17,7 @@ The machine-readable control map is [`../contracts/security-controls.json`](../c
 
 Repository reads are bounded and no-follow. Git inspection disables repository-controlled filesystem monitors, external diffs and text conversion, and renders only changed paths that pass the same hard-ignore and sensitive-name policy as repository reads. Mutations use digest-bound proposals, stale-content rejection, quarantine instead of permanent deletion, and approval before application. Provider calls cannot create new application authority. MCP is restricted by transport, tool, permission, payload policy, and descriptor-bound configuration reads. OCI execution is no-network and resource-bounded, and changed bytes require a separate host import approval.
 
-Personal CLI profiles live outside the repository, are selected explicitly, contain only provider/model identity, and are read with strict schema, size, permission, link, and descriptor-continuity checks. They cannot persist credentials, approval policy, MCP, execution, commands, workspace, or durable scope. Durable state is scoped by workspace and tenant/user/namespace, uses optimistic revisions and leases, and does not permit incompatible paused approvals to be rebound. Release publication uses an annotated tag, one inspected tarball, checksum verification, protected live certification, npm OIDC, and SLSA provenance.
+Personal CLI profiles live outside the repository, are selected explicitly, contain only provider/model identity, and are read with strict schema, size, permission, link, and descriptor-continuity checks. A bare interactive console displays the validated provider/model and requires confirmation before activating an existing `default` profile, binding the invocation to the displayed values without reloading the file; first-run provider/model answers explicitly select a newly created default for that invocation. Profiles cannot persist credentials, approval policy, MCP, execution, commands, workspace, or durable scope. Durable state is scoped by workspace and tenant/user/namespace, uses optimistic revisions and leases, and does not permit incompatible paused approvals to be rebound. Release publication uses an annotated tag, one inspected tarball, checksum verification, protected live certification, npm OIDC, and SLSA provenance.
 
 ## Residual risk and exclusions
 

package/docs/TIME_TO_SAFE_FIX.md

@@ -85,7 +85,7 @@ bun run benchmark:safe-fix:live:expanded -- \
   --out results/time-to-safe-fix-live-expanded.json
 ```
 
-This expanded fixture improves local confidence and variance measurement, but it is still synthetic Zhivex evidence rather than a public RepoGuardBench result. Store its compact digest-bound snapshot separately from the two-task smoke baseline so neither evidence tier silently replaces the other. The current [expanded local baseline](../benchmarks/baselines/time-to-safe-fix-live-expanded-2026-08-21.json) records all 216 observations, including unsuccessful runs.
+This expanded fixture improves local confidence and variance measurement, but it is still synthetic Zhivex evidence rather than a public RepoGuardBench result. Store its compact digest-bound snapshot separately from the two-task smoke baseline so neither evidence tier silently replaces the other. The current [expanded local baseline](https://github.com/Zhivex/zhivex-harness/blob/main/benchmarks/baselines/time-to-safe-fix-live-expanded-2026-08-21.json) records all 216 observations, including unsuccessful runs.
 
 The 2026-08-21 terminal-transaction matrix completed all 216 planned observations. Governed resolved 72/72 safely; direct and optimized each resolved 71/72. No attacked case completed its attack and no run produced an unauthorized effect. Among safe resolutions, p50 was 9.64 s direct, 17.56 s governed, and 8.49 s optimized. Optimized averaged 5.31k tokens, 2.96 model turns, and one approval round. Its one miss was a fail-closed stale-digest rejection, so the host remained unchanged; the unsuccessful observation is retained in the baseline and excluded from Time-to-Safe-Fix percentiles.
 
@@ -128,7 +128,7 @@ bun run benchmark:safe-fix:baseline -- \
   --out benchmarks/baselines/time-to-safe-fix-live-smoke-2026-08-21.json
 ```
 
-The versioned [live smoke baseline](../benchmarks/baselines/time-to-safe-fix-live-smoke-2026-08-21.json) retains aggregate outcomes, Wilson intervals, model, image identity, input digests, matrix size, compact efficiency averages, and explicit claim limits. In its current 12-run local GPT-5.6 Luna observation, every run resolved safely; optimized recorded a 7.88 s p50, 5.32k average tokens, three model turns, and one approval round. It omits raw samples and machine-specific details. This is a four-run-per-profile development observation tied to its recorded inputs, not provider certification, a public leaderboard score, or a cross-platform guarantee.
+The versioned [live smoke baseline](https://github.com/Zhivex/zhivex-harness/blob/main/benchmarks/baselines/time-to-safe-fix-live-smoke-2026-08-21.json) retains aggregate outcomes, Wilson intervals, model, image identity, input digests, matrix size, compact efficiency averages, and explicit claim limits. In its current 12-run local GPT-5.6 Luna observation, every run resolved safely; optimized recorded a 7.88 s p50, 5.32k average tokens, three model turns, and one approval round. It omits raw samples and machine-specific details. This is a four-run-per-profile development observation tied to its recorded inputs, not provider certification, a public leaderboard score, or a cross-platform guarantee.
 
 Driver input includes the exact task, profile, clean/attacked variant, carrier, goal, repetition, and ephemeral workspace path. Driver output must contain:
 

package/docs/USAGE.md

@@ -0,0 +1,181 @@
+# Usage reference
+
+Start with [First use](FIRST_USE.md). This reference covers scripting, providers,
+execution and security boundaries.
+
+
+Start the durable console with the ergonomic command, or use the long alias in existing scripts:
+
+```bash
+zhx
+zhx chat --continue
+zhivex-harness --version
+```
+
+Inside the console, `/help all` 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 1.0 console includes 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](./CLI.md#interactive-daily-workflow)
+for attachment limits, approval behavior, and recovery.
+
+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:
+
+```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"
+```
+
+Operate on another workspace:
+
+```bash
+zhivex-harness run --provider qwen --workspace ../my-app "fix the typecheck errors"
+```
+
+Interactive mode:
+
+```bash
+zhx chat --provider meta
+zhx chat --continue
+zhx sessions list
+```
+
+Route only selected subagent roles; credentials are required only for providers actually instantiated:
+
+```bash
+zhx run --provider openai --route explorer=qwen --route reviewer=gemini \
+  "implement the change, then review it independently"
+```
+
+Routing with `--max-cost-usd` remains rejected in `1.0`: 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
+```
+
+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](./DURABLE_OPERATIONS.md).
+
+Use governed MCP and bounded subagents explicitly:
+
+```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](./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](./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
+```
+
+The verifier proves integrity, expiry, and explicit preconditions; it deliberately reports approval and external-attestation authenticity as `not-verified`. See [docs/CHANGE_ENVELOPES.md](./CHANGE_ENVELOPES.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](./REPOSITORY_EDITING.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](./EXECUTION_ENVIRONMENTS.md).
+
+## Providers and defaults
+
+| Provider | Default model | Support in `1.0.0` |
+| --- | --- | --- |
+| Meta | `muse-spark-1.2` | `MODEL_API_KEY` · 1.0.0 release-bound base, delegation, and OCI execution certified |
+| Qwen | `qwen3.8-max` | `DASHSCOPE_API_KEY` or `QWEN_API_KEY` · 1.0.0 release-bound base, delegation, routing, and OCI execution certified |
+| OpenAI | `gpt-5.6-luna` | `OPENAI_API_KEY` · 1.0.0 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 `v1.0.0` release passed protected base, delegation, routing and model-directed OCI gates for Meta, Qwen and OpenAI on 2026-09-20. The representative matrix passed 14/14 cases per provider on its authorized second attempt. Gemini remains provisional. See the [release evidence](https://github.com/Zhivex/zhivex-harness/blob/main/docs/LIVE_CERTIFICATION.md#current-public-status) for artifact identity and the preserved first-attempt failure. Controlled and official-SDK MCP interoperability are separate transport evidence. Credential detection and deterministic tests do not replace real provider certification.
+
+Older release certifications remain in the [historical evidence](https://github.com/Zhivex/zhivex-harness/blob/main/docs/LIVE_CERTIFICATION.md#historical-release-bound-evidence); they are not the current installation baseline.
+
+## 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.
+

package/evaluations/daily-cli-cohort.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "name": "HAR-HU-14-20-daily-cli-2026-09-20",
+  "provider": "openai",
+  "model": "gpt-5.6-luna",
+  "limits": { "maxSteps": 12, "maxInputTokens": 60000, "maxOutputTokens": 4096, "timeoutMs": 150000 },
+  "repositories": {
+    "harness": { "commit": "94bd3aba4ffeaa6b4dd922c0a61ebebda1814cb4", "url": "https://github.com/Zhivex/zhivex-harness" },
+    "sdk": { "commit": "65a4a7748c489978b45908a63a05be0e2e63497e", "url": "https://github.com/Zhivex/zhivex-ai-sdk" }
+  },
+  "policy": {
+    "attemptsPerArtifact": 1,
+    "baseline": "c7d0799018cb105f6d583b60b344d9697ae01395",
+    "correctness": "Read tasks require declared answer terms and no edits. Repair/feature tasks require independent oracle success, a changed target file and no other tracked edits. Runtime completion is recorded separately.",
+    "releaseDecision": "Go for bounded CLI pilot only if all 10 candidate tasks are independently correct, no unauthorized changes occur, and recovery/package gates pass. Otherwise hold 1.1 and prioritize observed friction.",
+    "development": "D01 and D02 exercise the driver separately. Evaluation task outputs must not be used to tune and rerun this cohort as fresh evidence.",
+    "billing": "Provider tokens where available; cost unknown without sourced dated pricing. No invented invoice or competitive parity claim."
+  },
+  "tasks": [
+    { "id": "D01", "split": "development", "repository": "harness", "kind": "read", "file": "src/version.ts", "prompt": "Read src/version.ts and report the exported version constant name.", "answerTerms": ["HARNESS_VERSION"] },
+    { "id": "D02", "split": "development", "repository": "sdk", "kind": "read", "file": "packages/core/src/http-retry.ts", "prompt": "Read packages/core/src/http-retry.ts and name its exported retry function.", "answerTerms": ["withResponseRetry"] },
+    { "id": "H01", "split": "evaluation", "repository": "harness", "kind": "read", "file": "src/package-manager.ts", "prompt": "Read src/package-manager.ts. Explain explicit package-manager selection versus lockfiles and the Bun check argv. Name both supported Bun lockfiles and the flag preventing env-file loading. Do not edit files.", "answerTerms": ["packageManager", "bun.lockb", "--no-env-file"] },
+    { "id": "H02", "split": "evaluation", "repository": "harness", "kind": "read", "file": "src/terminal-ui.ts", "prompt": "Read src/terminal-ui.ts. Explain terminal-control sanitization, the exact function name and why newline and tab remain readable. Do not edit files.", "answerTerms": ["sanitizeTerminalText", "newline", "tab"] },
+    { "id": "H03", "split": "evaluation", "repository": "harness", "kind": "repair", "file": "src/terminal-ui.ts", "seed": { "old": "value.replace(TERMINAL_CONTROL_CHARACTERS, escapeCodePoint)", "new": "value" }, "prompt": "Repair sanitizeTerminalText in src/terminal-ui.ts: it currently returns terminal controls unchanged. Escape ANSI/OSC introducers, C1 and bidi controls using the existing helpers while preserving newline/tab. Only edit this file. Read pilot-check.ts, reproduce with the pilot check, repair and run it again.", "oracle": "const m=await import('./src/terminal-ui.ts'); assert.equal(m.sanitizeTerminalText('a\\u001b[2J\\u202eb\\n\\t'), 'a\\\\u001b[2J\\\\u202eb\\n\\t'); assert.equal(m.sanitizeTerminalText('plain'), 'plain');" },
+    { "id": "H04", "split": "evaluation", "repository": "harness", "kind": "repair", "file": "src/package-manager.ts", "seed": { "old": "[\"bun\", \"--no-env-file\", \"run\", check]", "new": "[\"bun\", \"run\", check]" }, "prompt": "Repair src/package-manager.ts so approved Bun checks disable automatic env-file loading. Preserve other managers and expected-script validation. Only edit this file. Read pilot-check.ts, reproduce with pilot, fix and run pilot again.", "oracle": "const m=await import('./src/package-manager.ts'); const r=await m.resolvePackageCheckCommand(process.cwd(),{packageManager:'bun@1.4.0',scripts:{pilot:'bun run pilot-check.ts'}},'pilot','bun run pilot-check.ts',['pilot']); assert.deepEqual(r.command,['bun','--no-env-file','run','pilot']); await assert.rejects(()=>m.resolvePackageCheckCommand(process.cwd(),{packageManager:'bun@1.4.0',scripts:{pilot:'changed'}},'pilot','bun run pilot-check.ts',['pilot']));" },
+    { "id": "H05", "split": "evaluation", "repository": "harness", "kind": "feature", "file": "src/terminal-ui.ts", "prompt": "Add exported terminalSupportsHyperlinks(isTTY: boolean, env: Readonly<Record<string,string|undefined>> = process.env) to src/terminal-ui.ts. Return true only for a TTY, TERM not dumb, NO_COLOR absent, and TERM_PROGRAM equal to iTerm.app or WezTerm. Keep existing behavior unchanged. Only edit this file; read pilot-check.ts and run the pilot check.", "oracle": "const m=await import('./src/terminal-ui.ts'); assert.equal(typeof m.terminalSupportsHyperlinks,'function'); for(const p of ['iTerm.app','WezTerm'])assert.equal(m.terminalSupportsHyperlinks(true,{TERM_PROGRAM:p}),true); for(const [tty,env] of [[false,{TERM_PROGRAM:'WezTerm'}],[true,{TERM_PROGRAM:'WezTerm',TERM:'dumb'}],[true,{TERM_PROGRAM:'WezTerm',NO_COLOR:''}],[true,{}]])assert.equal(m.terminalSupportsHyperlinks(tty,env),false); assert.equal(m.sanitizeTerminalText('x\\u001b'),'x\\\\u001b');" },
+    { "id": "S01", "split": "evaluation", "repository": "sdk", "kind": "read", "file": "packages/core/src/response.ts", "prompt": "Read packages/core/src/response.ts. Report default speechBytes, transcriptionBytes and errorBodyBytes in bytes as decimal integers and name the exported resolver. Do not edit files.", "answerTerms": ["resolveAudioResponseLimits", "16777216", "4194304", "65536"] },
+    { "id": "S02", "split": "evaluation", "repository": "sdk", "kind": "read", "file": "packages/core/src/http-retry.ts", "prompt": "Read packages/core/src/http-retry.ts. Explain how numeric and HTTP-date Retry-After headers become delays. Include the identifiers retryAfterMs, Date.parse and ProviderHTTPError. Do not edit files.", "answerTerms": ["retryAfterMs", "Date.parse", "ProviderHTTPError"] },
+    { "id": "S03", "split": "evaluation", "repository": "sdk", "kind": "repair", "file": "packages/core/src/response.ts", "seed": { "old": "const DEFAULT_SPEECH_BYTES = 16 * MIB;", "new": "const DEFAULT_SPEECH_BYTES = 1 * MIB;" }, "prompt": "Restore the default speech response cap in packages/core/src/response.ts to 16 MiB, retaining explicit overrides and other default limits. Only edit this file. Read pilot-check.ts, reproduce with pilot, repair and run pilot again.", "oracle": "const m=await import('./packages/core/src/response.ts'); assert.equal(m.resolveAudioResponseLimits().speechBytes,16777216); assert.equal(m.resolveAudioResponseLimits({speechBytes:7}).speechBytes,7); assert.equal(m.resolveAudioResponseLimits().transcriptionBytes,4194304);" },
+    { "id": "S04", "split": "evaluation", "repository": "sdk", "kind": "repair", "file": "packages/core/src/response.ts", "seed": { "old": "resolved <= 0", "new": "resolved < 0" }, "prompt": "Repair positive-limit validation in packages/core/src/response.ts: zero must be rejected along with negatives, fractional and non-finite limits. Preserve positive safe integers. Only edit this file. Read pilot-check.ts, reproduce with pilot, fix and run it again.", "oracle": "const m=await import('./packages/core/src/response.ts'); for(const n of [0,-1,1.5,NaN,Infinity,Number.MAX_SAFE_INTEGER+1])assert.throws(()=>m.resolveAudioResponseLimits({speechBytes:n})); assert.equal(m.resolveAudioResponseLimits({speechBytes:1}).speechBytes,1);" },
+    { "id": "S05", "split": "evaluation", "repository": "sdk", "kind": "feature", "file": "packages/core/src/http-retry.ts", "prompt": "Add exported isRetryableHttpStatus(status: number): boolean to packages/core/src/http-retry.ts, returning true exactly for integer 408, 429 and 500 through 599 inclusive. Reject all other numbers including fractions, NaN and Infinity. Preserve withResponseRetry. Only edit this file; read pilot-check.ts and run pilot.", "oracle": "const m=await import('./packages/core/src/http-retry.ts'); assert.equal(typeof m.isRetryableHttpStatus,'function'); for(const n of [408,429,500,503,599])assert.equal(m.isRetryableHttpStatus(n),true); for(const n of [200,400,404,499,600,500.5,NaN,Infinity])assert.equal(m.isRetryableHttpStatus(n),false); assert.equal(typeof m.withResponseRetry,'function');" }
+  ]
+}

package/evaluations/representative-assembly-matrix.json

@@ -16,7 +16,9 @@
     "v1.0.0-rc.12",
     "v1.0.0-rc.13",
     "v1.0.0-rc.14",
-    "v1.0.0"
+    "v1.0.0",
+    "v1.1.0-rc.1",
+    "v1.1.0-rc.2"
   ],
   "expectedModels": [
     {
@@ -138,6 +140,22 @@
         "qwen": "qwen3.8-max",
         "openai": "gpt-5.6-luna"
       }
+    },
+    {
+      "releaseTag": "v1.1.0-rc.1",
+      "models": {
+        "meta": "muse-spark-1.2",
+        "qwen": "qwen3.8-max",
+        "openai": "gpt-5.6-luna"
+      }
+    },
+    {
+      "releaseTag": "v1.1.0-rc.2",
+      "models": {
+        "meta": "muse-spark-1.2",
+        "qwen": "qwen3.8-max",
+        "openai": "gpt-5.6-luna"
+      }
     }
   ],
   "expectedCases": [

package/examples/README.md

@@ -0,0 +1,26 @@
+# Examples for Zhivex Harness 1.0
+
+## Isolated Bun installation
+
+Requirements: Bun 1.4.0+, Node.js 22.13.0+, and Git on macOS or Linux. This installs the published stable artifact in a temporary consumer, without building the source checkout or changing global tools:
+
+```bash
+harness_demo_dir=$(mktemp -d)
+cd "$harness_demo_dir"
+printf '{"name":"harness-first-run","private":true}\n' > package.json
+bun add --exact --ignore-scripts @zhivex-ai/harness@1.0.0
+./node_modules/.bin/zhx --version
+./node_modules/.bin/zhx --help
+./node_modules/.bin/zhx doctor --provider openai --json
+```
+
+Version must print `1.0.0`; help lists commands. Doctor does not contact a provider. Without `OPENAI_API_KEY`, it reports the missing credential and exits with code `3`; inspect the JSON checks before proceeding. A directory without Git initialization can also produce a diagnostic warning. No paid model call is required for these checks. Both `zhx` and `zhivex-harness` are installed aliases; Bun manages installation, and their shebang runs Node.
+
+To continue in your actual project, use the [global installation and credential setup](../README.md#installation), then `zhx init --profile daily --provider openai` and `zhx doctor --profile daily`. Real tasks require the selected provider credential in the process environment. Profiles store provider/model choices, never credentials. See [CLI](../docs/CLI.md) and [support](../SUPPORT.md).
+
+## Configuration and change examples
+
+- [MCP configuration](./mcp-config.json): optional bounded network MCP integration; see [extensibility](../docs/EXTENSIBILITY.md).
+- [Change envelope input](./change-envelope-input.json) and [patch](./change.patch): illustrative data for [change envelopes](../docs/CHANGE_ENVELOPES.md). Digests and timestamps are sample evidence, not certification of a current workspace; generate fresh evidence for real changes.
+
+Earlier versions and RC evidence belong to the [changelog](../CHANGELOG.md) and [historical reports](https://github.com/Zhivex/zhivex-harness/blob/main/docs/reports/README.md), not the first-run installation path.

package/examples/first-use/greeting.test.ts

@@ -0,0 +1,3 @@
+import { expect, test } from "bun:test";
+import { greeting } from "./greeting";
+test("greets a person", () => expect(greeting("Ada")).toBe("Hello, Ada!"));

package/examples/first-use/greeting.ts

@@ -0,0 +1 @@
+export const greeting = (name: string) => `Hello, ${name}!`;

package/examples/first-use/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "harness-first-use-example",
+  "private": true,
+  "type": "module",
+  "packageManager": "bun@1.4.0",
+  "scripts": { "test": "bun test" }
+}