@zhivex-ai/harness 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,132 @@
+# Changelog
+
+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.
+
+## 0.5.0 - 2026-08-17
+
+### Added
+
+- Model capability inspection, fail-fast requirements, and deterministic candidate selection before MCP or agent execution.
+- Schema-versioned declarative MCP configuration with explicit server/tool allowlists, permissions, environment-backed headers, bounded discovery, timeouts, and output-size ceilings.
+- A bounded HTTPS/loopback-HTTP MCP JSON-RPC client plus injectable custom clients for library consumers.
+- Named `explorer`, `implementer`, `tester`, and `reviewer` subagent profiles with independent durable budgets, leases, fingerprints, and inherited workspace/scope policy.
+- Application-owned parallel read-only review groups through the `review` CLI command and `runHarnessReviewGroup` library API.
+- Hierarchical child progress, approval identity, usage, cost/budget aggregation, and redacted run-tree inspection.
+- An opt-in Meta/Qwen/OpenAI live orchestration matrix that verifies exact reviewer delegation, child persistence, SQLite reopen, hierarchy, and aggregate usage independently from the legacy reviewed-edit gate.
+- Public npm metadata, security and support policies, exact-tarball inspection and installation gates, and a confirmation-gated GitHub Actions release workflow with npm provenance.
+
+### Changed
+
+- Resolved configuration uses schema version `3` and binds required capabilities, normalized MCP configuration, enabled profiles, and child policy into the harness fingerprint.
+- Parent and child token guards enforce aggregate durable usage after each provider step, avoiding double reservation after a child consumes budget.
+- The deterministic evaluation gate adds governed MCP and bounded-subagent scenarios.
+
+### Migration
+
+- Review schema-version-pinned configuration and replace `schemaVersion: 2` with `3`; existing scoped SQLite data needs no database rewrite.
+- Named subagents are enabled by default. Pass `subagentProfiles: []` or set an empty `ZHIVEX_HARNESS_SUBAGENTS` value for a parent-only library run.
+- Complete fingerprinted paused `0.4.x` runs with the `0.4.x` binary. They are not silently rebound to the new MCP, capability, approval, or child-policy contract.
+- Keep MCP JSON configuration inside the canonical workspace and store only environment-variable names, never credential values.
+
+### Security
+
+- Network MCP calls always require durable interrupt approval, regardless of remote read-only annotations.
+- MCP configuration rejects symlinks, workspace escapes, URL credentials, insecure non-loopback HTTP, unsafe headers, duplicate prefixes, and missing allowlists/permissions.
+- MCP discovery and results fail closed on malformed schemas, prompt-injection directives, timeout, cancellation, and oversized output.
+- Parallel review accepts only the read-only explorer/reviewer profiles; generic shell and `stdio` MCP remain unavailable until enforced execution environments.
+
+## 0.4.0 - 2026-08-17 (private checkpoint)
+
+### Added
+
+- Scoped SQLite run and memory persistence as the default local operations store, including leases, compare-and-swap revisions, idempotency claims, and an exactly-once tool journal.
+- `runs list`, `runs inspect`, `runs export`, `runs cancel`, and `runs cleanup` operator commands with schema-versioned JSON output.
+- Step, wall-clock, tool-call, tool-error, input-token, output-token, total-token, and optional user-priced cost budgets.
+- Deterministic bounded context compaction, production trace collection, redacted snapshots, traces, ledgers, and tool-journal inspection.
+- A five-scenario golden evaluation gate covering analysis, edits and checks, denied approval, restart recovery, and provider portability.
+
+### Changed
+
+- Resolved configuration uses schema version `2`, includes an explicit durable scope, and defaults to the `sqlite` backend.
+- Tool permissions, production safety policy, redaction, budget termination, durable memory, and harness/approval fingerprints are bound into every run.
+- The installed-package smoke now proves SQLite restart recovery, exactly-once mutation journaling, redacted inspection, and the packaged golden baseline.
+
+### Migration
+
+- On first default local/workspace-scope open, legacy `0.3.x` file-backed runs are copied into the scoped backend and marked with `metadata.migratedFrom: "0.3-file-store"`; source files are retained for rollback. Custom scopes require intentional library migration.
+- Use `--store file` or `ZHIVEX_HARNESS_STORE=file` only as a temporary compatibility path. New runs default to `<state-dir>/operations.sqlite`.
+- Scope is part of durable identity. Use the same `--tenant`, `--user`, and `--namespace` values when listing, inspecting, exporting, cancelling, cleaning, or resuming a run.
+- Resume rejects a mismatched workspace, provider/model, tool contract, approval policy, or harness fingerprint. Legacy paused runs receive the current binding only through the explicit resume path.
+- Cost enforcement is enabled only when `--max-cost-usd` and input and/or output pricing are supplied; pricing is operator-provided and measured usage may cross the ceiling by one provider step.
+
+### Security
+
+- Operational exports omit raw messages, tool inputs/outputs, approval arguments, metadata, and full output text, and apply secret/email redaction.
+- SQLite files are required to be regular non-symlink files and are created with owner-only permissions inside an owner-only state directory.
+- Cleanup defaults to terminal states and requires an explicit cutoff; cancellation defaults to a cooperative request unless `--final` is supplied.
+
+## 0.3.0 - 2026-08-16 (private checkpoint)
+
+### Added
+
+- Deterministic cursor pagination for file discovery and literal search, with SHA-256 content digests carried through inspection.
+- Digest-bound multi-file proposals and conflict-safe patch application with mutation audit evidence.
+- Approved file moves plus recoverable quarantine and restore operations; no permanent-delete model tool.
+- Expanded read-only Git inspection for staged, unstaged, renamed, deleted, and untracked paths.
+- A configurable explicit Bun package-script allowlist.
+- Real Git repository fixtures covering inspect/edit/validate/diff, stale conflicts, rename, quarantine recovery, untracked files, failed checks, and final summaries.
+
+### Changed
+
+- Repository discovery respects Git and harness-specific ignore rules while keeping secret and state exclusions non-overridable.
+- File replacement is published atomically, preserves existing modes, and rejects content changed after inspection.
+- Repository-editing tools require reviewed content digests and emit before/after evidence.
+- Upgraded `@zhivex-ai/meta` to `0.2.1`; Meta Chat streaming now preserves fragmented tool arguments and passed four consecutive proposal/approval/restart live gates.
+- Live certification now exercises the contractual `propose_edits` then `apply_patch` sequence for every provider.
+- The manual live-certification workflow defaults to the complete certified Meta, Qwen, and OpenAI matrix, with a documentation gate that rejects support-matrix drift.
+
+### Migration
+
+- Consume `nextCursor` until absent instead of treating a truncated list or search result as complete.
+- Replace overwrite-oriented multi-file flows with `propose_edits` followed by approved `apply_patch` using the observed digest for every existing target and `null` for a target that must be new.
+- Complete paused `0.2.x` approvals with the version that created them before upgrading; persisted approvals are not promised to migrate across tool-schema changes.
+- Replace deletion workflows with `quarantine_file` and retain the returned identifier when later recovery may be required.
+
+### Security
+
+- Stale create/update/move/quarantine/restore requests fail before overwriting newer workspace content.
+- Direct secret access, symlink escapes, special files, arbitrary host shell, Git writes, and permanent deletion remain unavailable.
+
+## 0.2.0 - 2026-08-16
+
+### Added
+
+- Public package metadata and MIT licensing.
+- A single runtime version source for the CLI and agent metadata.
+- Versioned JSON output contracts and documented exit codes.
+- A local `doctor` command that checks the runtime, workspace, Git, scripts, providers, and state directory without exposing credentials.
+- Linux and macOS CI, installed-tarball smoke coverage, negative security regressions, and opt-in live-provider certification.
+
+### Changed
+
+- Package builds externalize declared dependencies instead of embedding the complete SDK in both entry points.
+- New files are created with exclusive semantics to prevent concurrent non-overwrite calls from silently replacing one another.
+
+### Migration
+
+- `providers --json` now returns `{ schemaVersion: 1, kind: "providers", providers: [...] }` instead of a bare array.
+- JSON run results now include `schemaVersion: 1` and `kind: "run-result"`.
+- Invalid CLI usage exits with code `2`; a blocking `doctor` report exits with code `3`.
+- State directories that target a workspace/filesystem root, protected workspace path, regular file, or symbolic link are rejected before the run store is created.
+
+### Security
+
+- Added regression coverage for protected state paths, special files, nested symlink escapes, concurrent creation, bounded output, timeout cleanup, and denied approvals.
+
+## 0.1.0 - 2026-08-16
+
+### Added
+
+- Initial provider-portable coding harness MVP for Meta, Qwen, and OpenAI.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zhivex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,211 @@
+# Zhivex Harness
+
+Zhivex Harness is a Bun-first coding-agent harness portable across Meta, Qwen, and OpenAI, built on the Stable `@zhivex-ai/agents` runtime.
+
+The model provides capability; the harness provides repository context, narrow tools, limits, approvals, durable state, diagnostics, and verification. Every provider uses the same agent loop and local-tool contract.
+
+Version `0.5.0` is a publication-ready extensibility-and-orchestration candidate. The package manifest and protected release workflow are ready, but the immutable npm publication has not been executed. Public availability begins only after the repository and npm prerequisites in the [release guide](./docs/RELEASE.md) are completed and a maintainer explicitly dispatches the workflow. See [ROADMAP.md](./ROADMAP.md), [CHANGELOG.md](./CHANGELOG.md), the [extensibility guide](./docs/EXTENSIBILITY.md), the [durable-operations guide](./docs/DURABLE_OPERATIONS.md), and the [trusted-editing contract](./docs/REPOSITORY_EDITING.md).
+
+## What 0.5 includes
+
+- one-shot execution and interactive chat;
+- provider and model selection through the CLI;
+- versioned configuration and JSON output contracts;
+- a local `doctor` command that diagnoses Bun, workspace, Git, scripts, state, credentials, endpoints, and provider capabilities without making provider requests or exposing secret values;
+- deterministic, cursor-paginated workspace listing and search with SHA-256 content digests;
+- reviewed multi-file proposals and approved atomic application with stale-content rejection;
+- approved moves plus recoverable quarantine and restore operations;
+- an explicit, configurable allowlist of declared `package.json` checks executed through Bun;
+- read-only inspection of staged, unstaged, renamed, deleted, and untracked Git state;
+- per-process mutation audit evidence and a final diff summary;
+- scoped SQLite run/memory state, idempotency, approval resumption, leases, and exactly-once tool journals;
+- run list, redacted inspect/export, cancellation, and retention cleanup commands;
+- production safety policy plus step, time, tool, token, and optional operator-priced cost budgets;
+- bounded context compaction with durable records and a deterministic golden evaluation gate;
+- fail-fast model capability requirements and deterministic library-side candidate selection;
+- governed MCP over bounded HTTPS/loopback HTTP with explicit server/tool allowlists, permissions, timeouts, approvals, output limits, and environment-backed credentials;
+- named explorer, implementer, tester, and reviewer subagents with independent durable budgets and promoted approvals;
+- deterministic application-owned parallel read-only review groups with child progress, hierarchy, usage, and cost evidence;
+- protection against path traversal, symlink escapes, unsafe state targets, secret-file reads, special files, concurrent non-overwrite races, and unbounded output;
+- Linux/macOS CI, installed-tarball smoke coverage, and opt-in live-provider certification.
+
+It does not include arbitrary shell access, `stdio` MCP, permanent deletion, Git writes, a desktop UI, OS isolation, or a managed sandbox. Tools and subagents run inside the workspace with the permissions of the local process.
+
+## Requirements
+
+- Bun 1.3.7 or newer.
+- Git for repository status and diff inspection.
+- At least one supported provider credential for real model execution.
+
+## Installation
+
+After `0.5.0` is published to npm:
+
+```bash
+bun add @zhivex-ai/harness
+bunx zhivex-harness --version
+```
+
+Until then, run the source checkout:
+
+```bash
+bun install --frozen-lockfile
+cp .env.example .env
+bun run dev --version
+```
+
+Configure only the providers you plan to use:
+
+```dotenv
+OPENAI_API_KEY=...
+MODEL_API_KEY=...
+DASHSCOPE_API_KEY=...
+```
+
+`MODEL_API_KEY` is used by the Meta Model API. Qwen also accepts `QWEN_API_KEY`; `DASHSCOPE_API_KEY` takes precedence.
+
+## Diagnose the environment
+
+`doctor` is local and does not contact provider endpoints:
+
+```bash
+zhivex-harness doctor
+zhivex-harness doctor --provider qwen --json
+```
+
+For a source checkout, replace `zhivex-harness` with `bun run dev`.
+
+## Usage
+
+Show providers and detected configuration without printing secrets:
+
+```bash
+zhivex-harness providers
+zhivex-harness 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"
+```
+
+Operate on another workspace:
+
+```bash
+zhivex-harness run --provider qwen --workspace ../my-app "fix the typecheck errors"
+```
+
+Interactive mode:
+
+```bash
+zhivex-harness chat --provider meta
+```
+
+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](./docs/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](./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"
+```
+
+The JSON shapes and exit codes are documented in [docs/CLI.md](./docs/CLI.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).
+
+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"
+```
+
+## Providers and defaults
+
+| Provider | Default model | Current support |
+| --- | --- | --- |
+| Meta | `muse-spark-1.2` | `MODEL_API_KEY` · 0.4 runtime and 0.5 delegation certified |
+| Qwen | `qwen3.8-max` | `DASHSCOPE_API_KEY` or `QWEN_API_KEY` · 0.4 runtime and 0.5 delegation certified |
+| OpenAI | `gpt-5.4` | `OPENAI_API_KEY` · 0.4 runtime and 0.5 delegation certified |
+
+Override any model with `--model`. Optional provider overrides are `META_BASE_URL`, `QWEN_BASE_URL`, `QWEN_WORKSPACE_ID`, `QWEN_REGION`, and `OPENAI_BASE_URL`.
+
+Meta, Qwen, and OpenAI completed the 0.4 proposal, scoped-SQLite approval, process restart, and exactly-once patch gate on 2026-08-17. They also completed the separate 0.5 model-directed reviewer-delegation, child persistence, SQLite reopen, hierarchy, and aggregate-usage gate at `2026-08-17T02:21:45.553Z`. Controlled Streamable HTTP MCP interoperability over a real loopback server passed at `2026-08-17T13:05:05.542Z`; third-party server compatibility is not implied. Provider capability claims are date-bound by the [live certification gate](./docs/LIVE_CERTIFICATION.md); credential detection and deterministic tests do not replace real provider evidence.
+
+## 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.
+
+These controls reduce risk but do not provide strong isolation. Use a dedicated container or microVM and a disposable workspace for autonomous execution.
+
+## Development
+
+```bash
+bun run typecheck
+bun test
+bun run build
+bun run evaluate
+bun run smoke:package
+bun run pack:inspect
+bun run check
+```
+
+The live gate is opt-in and billable:
+
+```bash
+ZHIVEX_HARNESS_LIVE=1 bun run scripts/live-provider-smoke.ts
+```

package/ROADMAP.md

@@ -0,0 +1,239 @@
+# Zhivex Harness Roadmap
+
+- Status: active
+- Baseline date: 2026-08-16
+
+This roadmap takes the harness from its `0.1.0` MVP to a stable CLI and library contract. The `0.2.0` source baseline is tagged locally, `0.3.0` and `0.4.0` are private checkpoints, and `0.5.0` is a publication-ready extensibility-and-orchestration candidate. Registry publication remains a separate explicit operation. Releases are ordered by dependency and safety risk, not by calendar date. A version ships only when its exit criteria are satisfied.
+
+## Planning principles
+
+- Make the harness distributable and observable before expanding its side-effect surface.
+- Keep provider portability in the harness and provider-specific behavior behind capability checks.
+- Reuse Stable `@zhivex-ai/agents` runtime contracts for safety, durability, tracing, evaluation, subagents, and execution environments.
+- Keep generic shell execution behind an enforced container or remote-worker boundary.
+- Treat local, installed-package, live-provider, and published-artifact evidence as separate gates.
+- Keep the CLI Bun-first. JavaScript and TypeScript project checks continue to run through Bun.
+
+## Historical baseline: 0.2.0
+
+The tagged source baseline provides:
+
+- one-shot and interactive execution;
+- Meta, Qwen, and OpenAI model adapters;
+- bounded repository listing, literal search, file reads, file writes, and exact replacement;
+- approved `test`, `typecheck`, `lint`, and `build` scripts;
+- read-only Git status and unstaged diff;
+- durable file-backed runs and approval resume;
+- path traversal, external symlink, secret-file, size, output, step, and timeout guards.
+
+The deterministic baseline, TypeScript typechecking, dependency-externalized build, package inspection, and installed-tarball smoke are implemented. The package is configured for a first public release with MIT metadata, CI, changelog, CLI/config schema versioning, `doctor`, and negative security regressions. All three provider credentials are configured locally without being exposed by diagnostics. Live certification is date-bound and recorded separately; publication and provenance remain external release operations.
+
+The release candidate keeps `@zhivex-ai/core@1.5.0`. Although `1.6.0` is published, the installed `agents@1.2.0` and provider adapters still resolve their compatible runtime to `1.5.0`; upgrading only the direct dependency produced duplicate core types. The `1.6.0` move is deferred until the agents/providers batch can be installed and certified against one runtime version.
+
+## Release sequence
+
+| Version | Theme | Primary outcome | Status | Relative size |
+| --- | --- | --- | --- | --- |
+| `0.2.0` | Releasable foundation | A versioned, installable, diagnosable CLI | Local release baseline | M |
+| `0.3.0` | Trusted repository editing | Reviewable and recoverable multi-file changes | Private checkpoint | M |
+| `0.4.0` | Durable operations | Inspectable, budgeted, cancellable, evaluable runs | Private checkpoint | L |
+| `0.5.0` | Extensibility and orchestration | Governed MCP and bounded multi-agent work | Publication-ready candidate | L |
+| `0.6.0` | Enforced execution | Shell and checks inside a real isolation boundary | Planned | XL |
+| `1.0.0` | Stable contract | Supported compatibility and release guarantees | Planned | L |
+
+Relative size is for sequencing only; dates require a capacity decision.
+
+## 0.2.0 — Releasable foundation (release candidate)
+
+Goal: make the existing narrow harness safe to install, automate, diagnose, and release without broadening its write or command surface.
+
+Scope:
+
+- Add license, repository, issue tracker, `publishConfig`, changelog, release notes, and an explicit public/private publication decision.
+- Replace duplicated version literals in `package.json`, agent metadata, and CLI output with one generated or imported version source.
+- Define versioned config and JSON output schemas, documented exit codes, and a compatibility policy for `0.x`.
+- Add `doctor` for Bun version, workspace, Git, scripts, provider capability, credential presence, state-directory permissions, and endpoint diagnostics without printing secrets.
+- Add CI for typecheck, tests, build, CLI smoke, and package-content inspection on Linux and macOS.
+- Pack the tarball, install it into a clean fixture, and exercise `--help`, `--version`, `providers`, one mock run, and approval resume through the installed binary.
+- Add negative security tests for state paths, special files, nested symlinks, race-sensitive writes, output truncation, timeout cleanup, and denied approvals.
+- Add an opt-in live gate for Meta, Qwen, and OpenAI: forced local tool call, approval pause, process restart, resume, and exactly-once side effect.
+
+Exit criteria:
+
+- `bun run check` and the installed-tarball smoke pass from a clean checkout.
+- CI is required on the default branch and produces no tracked build artifacts.
+- Config, JSON output, exit codes, and security boundaries are documented.
+- Every advertised provider passes the live gate, or is explicitly marked uncertified and excluded from the supported matrix.
+- Publishing remains a separate, intentional operation after artifact inspection.
+
+## 0.3.0 — Trusted repository editing
+
+Goal: let the agent make realistic multi-file changes while every mutation remains bounded, reviewable, conflict-safe, and recoverable.
+
+Status: validated private candidate. It is not configured for registry publication. Contract and migration details live in [docs/REPOSITORY_EDITING.md](./docs/REPOSITORY_EDITING.md).
+
+Scope:
+
+- Respect hierarchical `.gitignore` files plus `.zhivex-harnessignore` while preserving hard secret exclusions.
+- Add paginated file discovery and search with deterministic ordering and explicit truncation cursors.
+- Add a patch proposal/apply flow with expected-content digests, atomic writes, file-mode preservation, and stale-workspace rejection.
+- Extend Git inspection to staged, unstaged, renamed, deleted, and untracked files without exposing Git writes.
+- Add approved move and recoverable delete operations. Deletions go to a harness-owned quarantine with an explicit restore path; permanent deletion is not a model tool.
+- Make the check allowlist configurable but explicit. Do not add arbitrary in-process shell execution.
+- Add fixture-repository end-to-end tests covering multi-file edits, conflicts, restore, formatting, failed checks, and final diff review.
+
+Exit criteria:
+
+- No write can silently overwrite content changed after the model inspected it.
+- Every mutation produces a before/after audit record and appears in the final diff summary.
+- Delete/restore and interrupted atomic-write tests pass on supported platforms.
+- Real repository fixtures prove a complete inspect, edit, validate, and summarize loop.
+
+Required release evidence:
+
+- focused workspace and fixture-repository tests pass on Linux and macOS;
+- pagination is deterministic and cursors reject incompatible reuse;
+- a stale precondition leaves every proposed target unchanged;
+- move, quarantine, restore, failed check, and final Git/audit summaries are exercised from a real Git repository;
+- migration and safety boundaries are documented without claiming host isolation or permanent deletion;
+- `0.3.0` remains private until an explicit publication decision is made.
+
+Validation snapshot (2026-08-16):
+
+- the trusted-editing implementation is merged into `main`;
+- deterministic, installed-package, and package-inspection CI gates pass on Linux and macOS;
+- the date-bound Meta, Qwen, and OpenAI proposal/approval/restart matrix is recorded in [docs/LIVE_CERTIFICATION.md](./docs/LIVE_CERTIFICATION.md);
+- publication, registry integrity, and provenance have not been attempted or claimed.
+
+## 0.4.0 — Durable operations and evaluation
+
+Goal: make runs supportable over time instead of only executable from one terminal.
+
+Status: validated private candidate. Operations and migration details live in [docs/DURABLE_OPERATIONS.md](./docs/DURABLE_OPERATIONS.md).
+
+Scope:
+
+- Adopt the Stable production safety policy, explicit permission metadata, budget guards, and redacted telemetry from `@zhivex-ai/agents`.
+- Add run list, inspect, cancel, resume, retention, and cleanup commands with machine-readable output.
+- Add idempotency keys, scope, durable cancellation, tool-journal evidence, and SQLite as the default concurrent local store; retain file-store migration support.
+- Add token, step, wall-clock, tool-call, and optional cost budgets with clear termination reasons.
+- Add bounded memory and context compaction with durable compaction records.
+- Export redacted snapshots, traces, tool audit records, and run ledgers.
+- Add deterministic evaluation fixtures and golden traces for analysis-only, edit-and-test, denied-approval, failure-recovery, and provider-switch scenarios.
+- Add an evaluation regression gate for success, safety, tool use, latency, and cost budgets.
+
+Exit criteria:
+
+- Restart, duplicate request, concurrent resume, cancellation, expired work, and retention tests pass without repeated side effects.
+- State migration from `0.3.x` is tested and documented.
+- Golden fixtures are deterministic and the regression gate runs in CI.
+- Exported operational artifacts are redacted by default and schema-versioned.
+
+Validation snapshot (2026-08-17):
+
+- deterministic tests, the five-case golden evaluation gate, typecheck, docs, build, and installed-tarball smoke pass;
+- migration, idempotency, concurrent ownership, expired-lease recovery, cancellation, retention, Qwen token enforcement, and export redaction have regression coverage;
+- Meta, Qwen, and OpenAI passed the scoped-SQLite approval/restart/exactly-once live matrix;
+- registry publication, provenance, tag creation, commit, and push have not been attempted or claimed.
+
+## 0.5.0 — Extensibility and orchestration
+
+Goal: support larger tasks through governed external tools and bounded delegation without weakening workspace policy.
+
+Status: publication-ready candidate. Configuration, migration, MCP, and orchestration contracts live in [docs/EXTENSIBILITY.md](./docs/EXTENSIBILITY.md); registry publication remains pending an explicit maintainer dispatch and the external prerequisites in [docs/RELEASE.md](./docs/RELEASE.md).
+
+Scope:
+
+- Add capability-based provider/model selection and reject unsupported requested capabilities before a run begins.
+- Add declarative MCP server configuration with server/tool allowlists, permission metadata, timeouts, output limits, and approval policies.
+- Start with read-only MCP tools; network or write-like MCP tools always require explicit approval and durable audit evidence.
+- Add named subagent profiles such as explorer, implementer, tester, and reviewer using Stable SDK subagent and handoff contracts.
+- Give child runs independent step/token/time budgets while inheriting workspace, secret, approval, and execution-environment policies.
+- Add deterministic application-owned parallel review through agent groups; reserve model-directed delegation for true subagent cases.
+- Surface child progress, promoted approvals, hierarchy, and cost in streaming and JSON output.
+
+Exit criteria:
+
+- An unconfigured or capability-incompatible model cannot enter an MCP or subagent flow.
+- Child approval pause/resume, cancellation propagation, exactly-once recovery, hierarchy traces, and aggregate budgets pass end-to-end tests.
+- MCP prompt injection and oversized/malformed result tests fail safely.
+- Provider-specific limitations are recorded in a live support matrix.
+
+Validation snapshot (2026-08-17 UTC):
+
+- deterministic tests, the seven-case golden evaluation gate, typecheck, docs, build, dependency audit, dry-run package inspection, and installed-tarball smoke pass;
+- malformed MCP, HTTP handshake/session, injection/output bounds, approval/restart, child mutation exactly-once, cancellation, scoped hierarchy, aggregate budget, and parallel review have regression coverage;
+- controlled Streamable HTTP MCP interoperability passed over a real loopback server with session negotiation, JSON and SSE responses, tool discovery, bounded execution, and forced network approval at `2026-08-17T13:05:05.542Z`;
+- Meta `muse-spark-1.2`, Qwen `qwen3.8-max`, and OpenAI `gpt-5.4` passed the separate model-directed reviewer delegation, child persistence, SQLite reopen, hierarchy, and aggregate-usage matrix at `2026-08-17T02:21:45.553Z`;
+- exact-artifact and publication controls are prepared, while registry publication, provenance, tag creation, and push have not been attempted or claimed.
+
+## 0.6.0 — Enforced execution environments
+
+Goal: introduce shell-class capabilities only when the declared filesystem, process, network, and resource controls are real.
+
+Scope:
+
+- Implement the SDK execution-environment contract for a local OCI/container backend, with an adapter boundary for future remote workers.
+- Bind run resume to the environment manifest, workspace identity, image digest, policy version, and harness fingerprint.
+- Execute approved shell and package checks only inside the acquired environment; keep in-process generic shell unavailable.
+- Default to no network, bounded CPU/memory/process/time/output, a non-root user, and an ephemeral workspace snapshot.
+- Export a patch/artifact from the snapshot and require a separate approval before applying it to the host workspace.
+- Add image lifecycle, orphan cleanup, cancellation, crash recovery, and auditable environment acquisition/release.
+- Document Docker/OCI prerequisites and the weaker fallback behavior when enforced execution is unavailable.
+
+Exit criteria:
+
+- Escape, network-denial, resource-exhaustion, fork-bomb, secret-mount, changed-fingerprint resume, cancellation, and orphan-cleanup tests pass.
+- Host workspace changes occur only through the approved patch import path.
+- Installed-artifact and live-provider tests exercise the enforced backend.
+- The product is described as a local enforced runner, not a managed sandbox service.
+
+## 1.0.0 — Stable CLI and library contract
+
+Goal: freeze a supportable public contract after the pre-1.0 safety and operational surfaces have been exercised in real repositories.
+
+Scope:
+
+- Stabilize CLI commands, config schema, JSON/event schemas, library exports, state migrations, and error taxonomy.
+- Publish a support matrix for Bun, operating systems, Git, container backend, providers, models, MCP modes, and store backends.
+- Guarantee tested migration from the final two `0.x` state/config formats or provide an explicit export/import tool.
+- Complete threat model, security review, dependency audit, provenance, integrity, and rollback documentation.
+- Run a representative repository evaluation matrix across every supported provider and publish date-bound evidence.
+- Add full installation, operations, policy, MCP, isolation, troubleshooting, migration, and release documentation.
+- Require release candidates before `latest`; no direct `0.6.x` to untested GA promotion.
+
+Exit criteria:
+
+- Two release candidates complete without a contract-breaking defect.
+- Clean-machine install, installed-tarball, migration, evaluation, live-provider, and enforced-environment gates pass.
+- Versioned artifacts, checksums/provenance, tag, changelog, and published package metadata agree with the source commit.
+- No open critical/high security finding and no undocumented unsupported provider path.
+
+## Cross-release definition of done
+
+Every version must include:
+
+- unit, integration, failure-path, and security regression tests proportional to the changed surface;
+- typecheck, build, source CLI smoke, packed-artifact inspection, and installed CLI smoke;
+- documentation and changelog entries for behavior, config, state, and compatibility changes;
+- a migration note for every persisted-state or user-facing schema change;
+- provider live certification when provider behavior, tools, approvals, or streaming changes;
+- explicit separation of local proof, installed-artifact proof, live proof, and publication proof;
+- a clean worktree and reproducible Bun lockfile before the release commit.
+
+## Explicit non-goals through 1.0
+
+- A desktop IDE or hosted operator UI.
+- A Zhivex-managed remote sandbox service or hosted control plane.
+- Automatic Git commit, push, pull request creation, deployment, or publication.
+- Unapproved permanent deletion or arbitrary host shell execution.
+- Claiming provider parity where upstream capabilities differ.
+
+These can become separate post-1.0 tracks after the CLI/runtime contract and security model are stable.
+
+## Immediate next actions
+
+1. Dogfood governed MCP and bounded delegation on representative repositories before freezing the contract.
+2. Validate additional third-party Streamable HTTP servers without broadening the transport or trust claims.
+3. Make the repository public, enable private vulnerability reporting, protect the `npm` environment, and verify `@zhivex-ai` scope rights before dispatching publication.
+4. Bootstrap the first npm version through the protected workflow, configure `release.yml` as the package Trusted Publisher, revoke the temporary bootstrap token, and verify registry integrity/provenance against the tagged commit.

package/SECURITY.md

@@ -0,0 +1,23 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are provided for the latest published `0.5.x` version. Pre-release source snapshots and older private checkpoints are not supported release channels.
+
+## Reporting a vulnerability
+
+Do not open a public issue for a suspected vulnerability. Use [GitHub private vulnerability reporting](https://github.com/Zhivex/zhivex-harness/security/advisories/new) and include:
+
+- the affected version and operating system;
+- a minimal reproduction or proof of concept;
+- the expected and observed security boundary;
+- the practical impact; and
+- any suggested mitigation.
+
+Private vulnerability reporting must be enabled before the repository is made public. If that channel is unavailable, do not disclose exploit details in a public issue.
+
+## Scope
+
+Reports are in scope when they affect packaged runtime code, workspace or state isolation, approval enforcement, secret handling, MCP boundaries, provider communication, dependency integrity, or the build and release pipeline.
+
+The absence of an OS sandbox is a documented product boundary rather than a vulnerability by itself. The harness does not expose generic host shell or permanent-delete model tools.

package/SUPPORT.md

@@ -0,0 +1,21 @@
+# Support
+
+Zhivex Harness `0.5.x` is a pre-1.0 CLI and TypeScript library for Bun. Observable contracts may change in a later minor release when the change and migration path are documented in [CHANGELOG.md](./CHANGELOG.md).
+
+## Supported baseline
+
+- Bun `1.3.7` or newer;
+- macOS and Linux, as exercised by CI;
+- Git workspaces;
+- 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.5.x` patch receives routine fixes. Live provider evidence is account-, model-, endpoint-, and date-dependent; see [docs/LIVE_CERTIFICATION.md](./docs/LIVE_CERTIFICATION.md).
+
+## Support channels
+
+Use [GitHub Issues](https://github.com/Zhivex/zhivex-harness/issues) for reproducible bugs and feature requests. For vulnerabilities, follow [SECURITY.md](./SECURITY.md) and do not post exploit details publicly.
+
+## Explicit limits
+
+The harness does not promise arbitrary shell access, `stdio` MCP, permanent deletion, Windows support, a managed sandbox, a desktop UI, or exact feature parity between upstream providers. Tools run with the permissions of the local harness process unless an application supplies a stronger execution environment.