@zhivex-ai/harness 0.5.0

package/docs/EXTENSIBILITY.md

@@ -0,0 +1,136 @@
+# 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.
+
+## Capability gate
+
+Every run requires streaming and callable-tool support by default. Add explicit requirements with repeatable CLI flags:
+
+```bash
+zhivex-harness run \
+  --require-capability tools \
+  --require-capability structured-output \
+  "produce the requested change"
+```
+
+Supported requirement names are `streaming`, `tools`, `structured-output`, `parallel-tools`, `reasoning`, and `web-search`. The instantiated model is inspected before persistence or model execution. An incompatible model fails before entering MCP or subagent discovery. Library callers can use `inspectHarnessModelCapabilities`, `assertHarnessModelCapabilities`, and `selectHarnessModel` for deterministic candidate routing.
+
+Capability acceptance is model-specific. A provider label or compatible endpoint does not imply every model supports the requested contract.
+
+## Declarative MCP configuration
+
+Pass a regular JSON file inside the canonical workspace:
+
+```bash
+zhivex-harness run --mcp-config examples/mcp-config.json "consult the approved documentation tool"
+```
+
+The schema is versioned independently:
+
+```json
+{
+  "schemaVersion": 1,
+  "servers": [
+    {
+      "name": "docs",
+      "transport": "http",
+      "url": "https://mcp.example.com/rpc",
+      "includeTools": ["search_docs", "read_page"],
+      "permissions": ["read", "network"],
+      "headerEnv": { "x-api-key": "DOCS_MCP_API_KEY" },
+      "callToolTimeoutMs": 30000,
+      "maxOutputBytes": 262144
+    }
+  ]
+}
+```
+
+Every server requires a non-empty tool allowlist and permission set. Tool discovery is paginated and bounded. Tool names are prefixed with `<server>_` unless an explicit safe prefix is supplied. Configuration contains environment-variable names rather than credential values; diagnostics and fingerprints never include resolved header values.
+
+The built-in transport supports HTTPS and loopback HTTP. Redirects, URL credentials, unsafe configurable headers, oversized configuration, symlinked configuration, and configuration outside the workspace are rejected. `stdio` is intentionally unavailable because spawning an MCP server is process execution; it remains deferred until the enforced execution environment in `0.6.x`.
+
+Library callers can inject a custom `McpClient`. Trusted read-only annotations are accepted only for an explicitly injected custom transport whose sole declared permission is `read`. HTTP always declares `network` and therefore always pauses for operator approval, even when a server claims a tool is read-only.
+
+## MCP result boundary
+
+MCP descriptions and results are untrusted. The harness:
+
+- bounds discovery pages, discovered tools, time, and response bytes;
+- validates declared input and structured-output schemas through the SDK MCP registry;
+- propagates abort signals, timeout intent, and idempotency keys;
+- rejects common prompt-injection directives before they enter model context;
+- records server permissions and risk in tool metadata;
+- promotes network, write, or external-side-effect calls to durable interrupt approval.
+
+The injection filter is deliberately conservative and may reject legitimate security documentation containing imperative attack text. Use a separate trusted preprocessing boundary if that content must be analyzed; do not disable the harness boundary for an untrusted server.
+
+## Named subagent profiles
+
+Four profiles are enabled by default:
+
+| Profile | Purpose | Tools |
+| --- | --- | --- |
+| `explorer` | Repository discovery and evidence | Read-only workspace inspection |
+| `implementer` | One bounded implementation task | Workspace tools; mutations remain approval-gated |
+| `tester` | Focused verification | Read-only inspection plus approved Bun checks |
+| `reviewer` | Independent correctness/security review | Read-only diff and audit inspection |
+
+Select an explicit subset with repeatable flags:
+
+```bash
+zhivex-harness run \
+  --subagent explorer \
+  --subagent reviewer \
+  "analyze the persistence boundary"
+```
+
+The parent receives `delegate_explorer`, `delegate_implementer`, `delegate_tester`, and `delegate_reviewer` tools for the enabled profiles. Delegation is model-directed only when the parent invokes one of these tools. A child inherits the canonical workspace, durable scope, store, memory, cancellation boundary, approval policy, and telemetry observer. Each child has its own harness fingerprint, lease, state limit, timeout, step/tool/error/token budget, and run ID.
+
+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.
+
+## 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.
+
+The child enforces its independent budget with `includeChildRuns: false`. The parent budget retains `includeChildRuns: true`, so child consumption also counts against the aggregate ceiling. Token ceilings are enforced after each provider step to avoid reserving the entire parent allowance again after a child has consumed tokens; measured usage can cross a ceiling by one provider step.
+
+Use cascade cancellation to finalize a parent and every persisted child:
+
+```bash
+zhivex-harness runs cancel <parentRunId> --cascade --final --reason "superseded"
+```
+
+## Application-owned parallel review
+
+`review` runs deterministic application-owned parallel review instead of asking a model to decide the topology:
+
+```bash
+zhivex-harness review \
+  --reviewer explorer \
+  --reviewer reviewer \
+  --json \
+  "review the durable approval boundary"
+```
+
+Only the read-only `explorer` and `reviewer` profiles are accepted. The default concurrency ceiling is two and the hard maximum is four. Each member is a durable child with a shared group parent identifier. A member failure is reported without silently discarding the other independent result.
+
+## Progress and JSON
+
+Human terminal mode reports child start and finish telemetry. `run-result` JSON includes capability evidence, configured MCP server names, enabled profiles, child run IDs/status/usage, promoted approval identity, and the aggregate budget. `review-group` JSON includes the group ID and one bounded result per member. `runs inspect` adds the redacted hierarchical trace while continuing to omit raw messages, tool inputs/outputs, approval arguments, metadata, and full output text.
+
+## Migration from 0.4.x
+
+- Configuration schema `2` becomes schema `3`; remove a pinned `schemaVersion: 2` or migrate it to `3` after reviewing capability, MCP, and subagent defaults.
+- Named subagents are enabled by default. Pass an empty `subagentProfiles` array from the library, or set `ZHIVEX_HARNESS_SUBAGENTS=` for a parent-only run.
+- The harness fingerprint now includes required capabilities, child policy, profile selection, and normalized MCP configuration. A paused `0.4.x` run with an existing fingerprint must be completed with the `0.4.x` binary; it is not silently rebound to `0.5.x`.
+- Existing scoped SQLite data remains readable. No database rewrite is required.
+- MCP configuration must be placed inside the workspace and must not contain raw secrets.
+
+## Known limits
+
+- The built-in MCP transport implements bounded JSON-RPC over Streamable HTTP response forms; it does not support OAuth discovery, server-initiated sampling, roots, subscriptions, elicitation, or arbitrary SSE reconnection.
+- MCP prompt-injection detection is a safety filter, not a proof that remote content is trustworthy.
+- Parallel review groups have a durable shared parent identifier, but the group itself is not a standalone persisted agent state.
+- Subagents share the host process and workspace. They are policy boundaries, not OS isolation.
+- Generic shell, `stdio` MCP, containers, network namespaces, and remote workers remain `0.6.x` scope.
+- Provider-specific orchestration behavior requires date-bound live certification and is separate from deterministic implementation evidence.

package/docs/LIVE_CERTIFICATION.md

@@ -0,0 +1,117 @@
+# 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.
+
+## What it proves
+
+For each selected provider, the smoke:
+
+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.
+
+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.
+
+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.
+
+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`.
+
+## Run it
+
+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:
+
+```bash
+ZHIVEX_HARNESS_LIVE=1 bun run scripts/live-provider-smoke.ts
+```
+
+The default gate requires and tests Meta, Qwen, and OpenAI. To certify one provider while diagnosing an upstream or account issue:
+
+```bash
+ZHIVEX_HARNESS_LIVE=1 \
+ZHIVEX_HARNESS_LIVE_PROVIDERS=qwen \
+bun run scripts/live-provider-smoke.ts
+```
+
+Optional model overrides are:
+
+- `ZHIVEX_HARNESS_LIVE_META_MODEL`
+- `ZHIVEX_HARNESS_LIVE_QWEN_MODEL`
+- `ZHIVEX_HARNESS_LIVE_OPENAI_MODEL`
+
+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.
+
+The separate `0.5.x` delegation matrix uses the same opt-in, provider selection, credentials, and model overrides:
+
+```bash
+ZHIVEX_HARNESS_LIVE=1 bun run smoke:live:orchestration
+```
+
+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.
+
+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.
+
+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.
+
+## 0.4.0 private-milestone evidence
+
+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.
+
+| 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-17T13:05:05.542Z` 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.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.

package/docs/RELEASE.md

@@ -0,0 +1,107 @@
+# Release process
+
+`@zhivex-ai/harness@0.5.0` is configured as a public npm package, 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. Creating a tag alone does not publish anything.
+
+## Deterministic gates
+
+From a clean checkout on `main`:
+
+```bash
+bun install --frozen-lockfile --ignore-scripts
+bun run release:check
+git diff --check
+git status --short
+```
+
+`bun run release:check` performs documentation validation, typechecking, deterministic tests, the golden evaluation gate, a dependency-externalized build, package-content validation, clean tarball installation, direct binary execution, public import, SQLite restart/resume, redacted inspection, exactly-once side-effect verification, dependency audit, untrusted lifecycle-script inspection, dry-run packing, and release metadata validation.
+
+CI repeats the deterministic and installed-package gates on Linux and macOS. Build output is ignored and must not create tracked changes.
+
+## Live gate
+
+Provider behavior is certified separately because it is credential-, account-, model-, endpoint-, and date-dependent:
+
+```bash
+ZHIVEX_HARNESS_LIVE=1 bun run scripts/live-provider-smoke.ts
+ZHIVEX_HARNESS_LIVE=1 bun run smoke:live:orchestration
+```
+
+The base reviewed-edit gate and the separate `0.5.x` delegation gate must pass for every provider in the supported release matrix. Integrated provisional providers are reported separately and must not be described as certified. `bun run check` also runs the controlled loopback Streamable HTTP MCP interoperability gate; third-party server claims remain separate. See [LIVE_CERTIFICATION.md](./LIVE_CERTIFICATION.md).
+
+## Exact artifact gate
+
+The release workflow performs this sequence across an unprivileged validation job and a protected publication job:
+
+1. check out an existing annotated `v<package-version>` tag with complete history;
+2. prove that the tag resolves to `main`, the worktree is clean, and the version is absent from npm;
+3. run the complete Bun release gate;
+4. create one tarball with `bun pm pack --ignore-scripts`;
+5. allow only the documented package roots, verify the packed manifest, and write `SHA512SUMS`;
+6. install that same tarball in an isolated consumer and execute its CLI and public API;
+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.
+
+For a local artifact rehearsal after the source gate:
+
+```bash
+mkdir -p release-artifacts
+bun pm pack --filename release-artifacts/zhivex-ai-harness-0.5.0.tgz --ignore-scripts
+bun run artifact:check -- release-artifacts/zhivex-ai-harness-0.5.0.tgz
+bun run smoke:artifact -- release-artifacts/zhivex-ai-harness-0.5.0.tgz
+```
+
+`release-artifacts/`, `.npmrc`, `.env`, source tests, Git metadata, and local run state are excluded from the package.
+
+## External prerequisites
+
+Before the first dispatch:
+
+- make `Zhivex/zhivex-harness` 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 can create public packages in the `@zhivex-ai` scope; and
+- verify `@zhivex-ai/harness` is still unclaimed.
+
+The package does not yet exist on npm, and npm requires a package to exist before Trusted Publishing can be configured. For `0.5.0` only, create a temporary granular npm token with the minimum available organization scope, store it as `NPM_TOKEN` in the protected `npm` environment, and remove it immediately after the first successful publication. The workflow still publishes from GitHub Actions with `--provenance`.
+
+After `0.5.0` exists:
+
+1. configure its npm Trusted Publisher as organization `Zhivex`, repository `zhivex-harness`, workflow `release.yml`, environment `npm`, allowed action `npm publish`;
+2. set package publishing access to require 2FA and disallow tokens;
+3. delete the GitHub `NPM_TOKEN` secret and revoke the temporary token; and
+4. use OIDC-only workflow publication for every later version.
+
+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.5.0 -m "Release v0.5.0"
+git push origin v0.5.0
+gh workflow run release.yml \
+  -f tag=v0.5.0 \
+  -f channel=latest \
+  -f confirm_publication=true
+```
+
+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.
+
+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.
+
+## Publication stop conditions
+
+Do not dispatch or approve publication when any of these is true:
+
+- the repository is not public, the tag is not annotated, the tagged commit is not on `main`, or the worktree used to create it was dirty;
+- deterministic, installed-artifact, required live-provider, or release-artifact evidence failed;
+- package scope ownership, 2FA, the intended `public` access level, or the protected environment is unclear;
+- the inspected package contents and the to-be-published artifact are not the same file;
+- the package version already exists in npm;
+- the temporary first-release credential is broader or longer-lived than necessary;
+- Trusted Publishing is expected but its repository, workflow filename, environment, or allowed action disagrees with the workflow; or
+- version, changelog, tag, registry metadata, source commit, integrity, or provenance disagree.
+
+Current npm requirements should be revalidated against the official [Trusted Publishing guide](https://docs.npmjs.com/trusted-publishers/), [provenance guide](https://docs.npmjs.com/generating-provenance-statements/), and [Bun packaging documentation](https://bun.com/docs/pm/cli/publish) before any registry mutation.

package/docs/REPOSITORY_EDITING.md

@@ -0,0 +1,118 @@
+# Trusted repository editing
+
+Zhivex Harness `0.3.x` adds conflict-safe multi-file editing while preserving the `0.2.x` workspace boundary. Discovery is read-only. Every mutation requires interrupt approval, validates the content the operator reviewed, and produces an audit entry.
+
+## Safety model
+
+Repository editing does not grant arbitrary shell access or Git write access. The harness never stages, commits, resets, pushes, or permanently deletes a file on behalf of the model.
+
+The following rules apply to every operation:
+
+- paths are workspace-relative and must remain inside the canonical workspace;
+- symbolic-link escapes and special files are rejected;
+- hierarchical `.gitignore` files, `.zhivex-harnessignore`, built-in build/state exclusions, and hard secret exclusions are applied during discovery;
+- hard secret exclusions such as `.env`, `.npmrc`, private keys, Git internals, and harness state cannot be re-enabled by an ignore rule;
+- output, file size, page size, check, and execution-time limits remain bounded;
+- writes, moves, quarantine operations, restores, and checks require an interruptible approval.
+
+These controls prevent silent workspace drift; they do not isolate the host. Run autonomous work in a disposable workspace or enforced environment.
+
+## Discovery and digests
+
+`list_files` and `search_files` return deterministic pages. Each response includes `truncated` and, when another page exists, an opaque `nextCursor`. Supply that cursor unchanged to request the next page. A cursor is bound to the original operation and parameters; it must not be edited or reused for a different path, query, case-sensitivity setting, or page size.
+
+Listed files and every search match include a content digest. `read_file` also returns the digest of the complete file, even when only a line range was requested. Digests are the concurrency contract for later edits: reading content and then editing it without carrying the observed digest does not provide stale-workspace protection.
+
+Ignore rules affect discovery, not direct authorization. A direct request for a hard-protected path still fails. An ignored ordinary source file can only be addressed when the workspace policy explicitly permits the direct operation.
+
+## Propose and apply
+
+Multi-file edits use two phases:
+
+1. `propose_edits` receives the intended final content for every target plus the digest observed during inspection. Use `expectedDigest: null` only when the target must not exist.
+2. The proposal result identifies the canonical proposal and summarizes every target without modifying the workspace.
+3. `apply_patch` repeats the reviewed changes and proposal identifier. The harness verifies the canonical proposal, rechecks every precondition, and pauses for approval before writing.
+4. If any target was created, removed, replaced, or otherwise changed after inspection, the complete apply is rejected as stale before publishing the proposed changes.
+
+Successful file replacement uses same-directory staging and atomic per-file publication. Every target is preflighted before publication begins, existing file modes are preserved, and a new file receives the harness default regular-file mode. If later publication fails, the harness attempts to roll back the already-published targets and reports the failure. The patch result contains the proposal identifier and one mutation audit entry per changed path.
+
+Structured editing documents use schema version `1`:
+
+| Tool | `kind` | Payload |
+| --- | --- | --- |
+| `propose_edits` | `edit-proposal` | `proposalId`, `digestAlgorithm`, and redacted change summaries. |
+| `apply_patch` | `patch-result` | Workspace mutation result. |
+| `move_file` | `move-result` | Workspace move result. |
+| `quarantine_file` | `quarantine-result` | Workspace quarantine result and recovery identifier. |
+| `restore_file` | `restore-result` | Workspace restore result. |
+| `mutation_audit` | `mutation-audit` | Mutation audit entries for this harness instance. |
+| `git_diff` | `workspace-diff` | Status, diff evidence, and mutation audit entries. |
+
+The proposal document never returns file contents. Its `proposalId` binds the normalized paths, expected digests, resulting content digests, and byte counts that were reviewed.
+
+`expectedDigest` is not an optional optimization. It distinguishes three cases:
+
+| Value | Required precondition |
+| --- | --- |
+| Existing file digest | The regular file must still contain exactly the inspected bytes. |
+| `null` | The path must still be absent. |
+| Missing field | Invalid mutation request. |
+
+The harness does not merge conflicting edits. Reinspect the file, review the new content, and create a new proposal.
+
+The terminal prints the complete `apply_patch` approval arguments rather than truncating them, including when a paused run is resumed. This is intentionally more verbose than other approvals: approving a patch confirms the exact final contents shown. `--yes` bypasses interactive review and should only be used in a disposable or isolated workspace.
+
+## Move, quarantine, and restore
+
+`move_file` requires the current source digest and a destination that does not already exist. It preserves the regular-file mode and records both paths. It does not invoke `git mv`; Git detects the resulting rename from repository contents.
+
+`quarantine_file` requires the current digest and moves the file into harness-owned state. The result includes a `quarantineId` used for recovery. The model has no permanent-delete tool.
+
+`restore_file` accepts a quarantine identifier and an optional workspace destination. Restore is conflict-safe: it never overwrites an existing destination, and an optional expected digest can bind the operation to the quarantined bytes the operator reviewed. A successful restore is recorded independently from the quarantine operation.
+
+Quarantine is a recovery boundary, not a backup system. Retention and permanent cleanup remain operator responsibilities. Do not manually edit quarantine manifests or payloads while a run is active.
+
+## Checks
+
+Checks remain explicit package scripts executed through Bun. `test`, `typecheck`, `lint`, and `build` are the default allowlist. `--allow-check` and `ZHIVEX_HARNESS_ALLOWED_CHECKS` replace that default with an explicit set of declared package-script names; they do not accept command text. The requested script text must still exactly match the current `package.json`; a changed script fails closed.
+
+Checks do not load the workspace `.env` automatically. A non-zero exit, timeout, or truncated output is recorded as returned evidence and must not be summarized as a successful validation.
+
+## Git inspection and final summary
+
+`git_diff` is read-only and reports the repository status, unstaged diff, and staged diff as separate results, including renamed, deleted, and untracked paths. `mutation_audit` returns the harness mutation history for the current workspace process.
+
+Every mutation audit entry includes an identifier, operation, affected path, timestamp, and the available before/after digest evidence. Move and restore operations may include a destination; quarantine-related entries may include a quarantine identifier.
+
+Before completion, an editing run should report:
+
+- files inspected and whether discovery was truncated;
+- proposal and mutation results;
+- stale conflicts or denied approvals;
+- checks executed with their exit status;
+- final staged, unstaged, renamed, deleted, and untracked state;
+- quarantine identifiers that the operator may need for recovery.
+
+Audit entries document harness operations. They do not prove that another process did not modify the repository, so the final Git inspection remains required.
+
+## Migration from 0.2.x
+
+`0.3.0` is a pre-1.0 minor release and deliberately tightens mutation contracts:
+
+- replace overwrite-oriented editing with inspect plus digest-bound proposal/apply for multi-file changes;
+- consume paginated discovery until `nextCursor` is absent instead of assuming one list/search result is complete;
+- configure the allowed check subset explicitly when the default set is too broad;
+- use quarantine and restore instead of deleting or manually moving a file out of the workspace;
+- include mutation audit evidence and the expanded Git status in final summaries.
+
+Existing source files need no migration. Existing Git state is not modified during upgrade. Persisted `0.2.x` runs should be completed with the version that created them before beginning `0.3.x` editing work; do not assume a paused approval created under an older tool schema can be resumed after upgrading.
+
+The new quarantine and audit state is harness-owned and must remain excluded from model discovery and Git. Back up any recovery payloads that must outlive the local retention window before cleaning harness state.
+
+## Known limits
+
+- Atomic publication protects each file and failed batches use best-effort rollback; the workspace is not a database transaction across power loss, rollback failure, or external concurrent processes.
+- Git rename detection is heuristic and may display a delete plus add for heavily rewritten content.
+- Ignore evaluation and filesystem behavior can differ by platform; Linux and macOS fixtures are required release gates.
+- Quarantine does not replace version control or an external backup.
+- Checks execute with the local process permissions. Enforced shell and filesystem isolation is planned for `0.6.0`.

package/evaluations/golden-expectations.json

@@ -0,0 +1,40 @@
+{
+  "schemaVersion": 1,
+  "cases": [
+    {
+      "name": "analysis-only",
+      "status": "completed",
+      "toolCalls": []
+    },
+    {
+      "name": "edit-and-test",
+      "status": "completed",
+      "toolCalls": ["propose_edits", "apply_patch", "run_check"]
+    },
+    {
+      "name": "denied-approval",
+      "status": "failed",
+      "toolCalls": ["propose_edits", "apply_patch"]
+    },
+    {
+      "name": "failure-recovery",
+      "status": "completed",
+      "toolCalls": ["propose_edits", "apply_patch"]
+    },
+    {
+      "name": "provider-switch",
+      "status": "completed",
+      "toolCalls": []
+    },
+    {
+      "name": "governed-mcp",
+      "status": "completed",
+      "toolCalls": ["remote_lookup"]
+    },
+    {
+      "name": "bounded-subagent",
+      "status": "completed",
+      "toolCalls": ["delegate_reviewer"]
+    }
+  ]
+}

package/examples/mcp-config.json

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": 1,
+  "servers": [
+    {
+      "name": "docs",
+      "transport": "http",
+      "url": "https://mcp.example.com/rpc",
+      "includeTools": ["search_docs", "read_page"],
+      "permissions": ["read", "network"],
+      "headerEnv": {
+        "x-api-key": "DOCS_MCP_API_KEY"
+      },
+      "callToolTimeoutMs": 30000,
+      "maxOutputBytes": 262144
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@zhivex-ai/harness",
+  "version": "0.5.0",
+  "description": "Provider-portable coding agent harness powered by Zhivex AI SDK.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zhivex/zhivex-harness.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Zhivex/zhivex-harness/issues"
+  },
+  "homepage": "https://github.com/Zhivex/zhivex-harness#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "coding-agent",
+    "harness",
+    "zhivex"
+  ],
+  "bin": {
+    "zhivex-harness": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "SUPPORT.md",
+    "LICENSE",
+    "docs",
+    "evaluations",
+    "examples"
+  ],
+  "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 && tsc --emitDeclarationOnly",
+    "prepack": "bun run build",
+    "docs:check": "bun run scripts/check-docs.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "evaluate": "bun run scripts/evaluate.ts",
+    "smoke:package": "bun run build && bun run scripts/package-smoke.ts",
+    "smoke:artifact": "bun run scripts/package-smoke.ts",
+    "smoke:mcp": "bun run scripts/mcp-interoperability-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",
+    "artifact:check": "bun run scripts/check-release-artifact.ts",
+    "pack:inspect": "bun run build && bun pm pack --dry-run --ignore-scripts",
+    "check": "bun run docs:check && bun run typecheck && bun test && bun run evaluate && bun run smoke:mcp && bun run smoke:package",
+    "release:check": "bun run check && bun audit && bun pm untrusted && bun run pack:inspect && bun run scripts/check-release-readiness.ts",
+    "release:status": "bun run scripts/check-registry-release-status.ts",
+    "release:verify": "bun run scripts/verify-registry-release.ts"
+  },
+  "dependencies": {
+    "@zhivex-ai/agents": "1.2.0",
+    "@zhivex-ai/core": "1.5.0",
+    "@zhivex-ai/meta": "0.2.1",
+    "@zhivex-ai/openai": "0.9.4",
+    "@zhivex-ai/qwen": "0.10.1",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.14",
+    "typescript": "6.0.3"
+  },
+  "engines": {
+    "bun": ">=1.3.7"
+  },
+  "packageManager": "bun@1.3.7"
+}