@zhivex-ai/harness 1.2.0 → 1.3.0-rc.7

package/docs/ENGINE_API.md

@@ -0,0 +1,319 @@
+# Engine API and Code integration
+
+This checkout adds terminal-independent package entrypoints for
+Harness 1.3.0-rc.7. They are not present in the previously published Harness 1.2.0.
+Publication is pending the protected workflow; use the documented
+local candidate smoke to validate these bytes. Do not install registry 1.2.0 and
+expect the new entrypoints to exist.
+
+## Entry points
+
+| Import | Use | Runtime |
+| --- | --- | --- |
+| `@zhivex-ai/harness/engine` | Configuration, execution, policies, approvals, tools, stores, providers and historical non-terminal library APIs | Node |
+| `@zhivex-ai/harness/protocol` | Wire request schemas, client types and JSON/event serialization | Browser or Node |
+| `@zhivex-ai/harness/client` | In-process client adapter, result projection and durable continuation helpers | Node |
+| `@zhivex-ai/harness/service` | Authenticated local service, recovery and activity events | Node |
+| `@zhivex-ai/harness/acp` | Experimental text-session ACP adapter and stream transport | Node |
+| `@zhivex-ai/harness/code-support` | Named host helpers used by Code, including a read-only SQLite diagnostic projection | Node |
+| `@zhivex-ai/harness/models` | Beta catalog schemas, bundled metadata, model selection and display helpers; no host loading | Browser or Node |
+| `@zhivex-ai/harness/mcp/stdio/v1` | Experimental host admission, isolated MCP sessions, recovery and reconciliation; see [host flow](MCP_STDIO.md) | Node or Bun |
+| `@zhivex-ai/harness/desktop/v1/state` | Versioned host-only snapshot, validation, safe-file-read and lease handoff operations for Desktop updates | Node |
+
+[`contracts/engine-api.json`](../contracts/engine-api.json) enumerates every named
+export and its stability tier. Existing aliases keep their root tier. New helpers
+have their explicitly recorded tier; importing through a new subpath does not
+upgrade an experimental API. The historical root export and its stable signature
+baseline remain supported. Host-loading JSON document schemas are available from
+`/engine`, not the browser protocol entrypoint.
+
+Imports do not open a terminal, start a service, create a Harness instance or
+prompt for credentials. Hosts explicitly construct and close the runtime, supply
+credentials/model instances, resolve approvals and choose their storage policy.
+Importing the engine does not itself execute a task or grant permissions.
+
+The `/models` subpath is an **unpublished addition after RC3**, introduced for
+HAR-HU-39. It is present in local candidate tarballs from this checkout, not the
+previously deployed RC3 bytes. Its six runtime exports and two types are listed
+in `contracts/engine-api.json`. It performs no file access, credential resolution,
+provider requests or process startup. Remote catalog loading remains host-owned.
+Installed-package smoke compiles the public subpath for a browser and checks its
+exports and type declarations in a clean consumer. Desktop migration and packaged
+app acceptance are recorded separately in the repository-only report `docs/reports/HAR_HU_39_2026-09-29.md`.
+
+```ts
+import { createHarness } from "@zhivex-ai/harness/engine";
+import { createHarnessClientAdapter } from "@zhivex-ai/harness/client";
+
+const harness = await createHarness({
+  workspace: "/absolute/path/to/project",
+  provider: "openai",
+  model: "your-supported-model"
+});
+const client = await createHarnessClientAdapter(harness);
+try {
+  // Dispatch requests using the documented client protocol and explicit approvals.
+  // Keep the host alive for the work it starts; close only when it is finished.
+} finally {
+  client.close();
+  await harness.close();
+}
+```
+
+See [the client protocol](CLIENT_PROTOCOL.md), [local service](LOCAL_SERVICE.md)
+and [durable operations](DURABLE_OPERATIONS.md) for execution, approval and recovery
+semantics. Persistence and approval fingerprints are shared across clients;
+switching presentation does not migrate state or authorize new effects.
+
+## Terminal product
+
+`packages/code` is the independently built terminal product. Its current version
+is `0.1.0-rc.2`, prepared for independent publication to `next` with the exact
+engine dependency `@zhivex-ai/harness@1.3.0-rc.7`. Publication remains gated by
+reviewed main, CI and registry evidence in the [Code release procedure](CODE_RELEASE.md).
+Code imports declared package APIs, never Harness source paths. Its build leaves
+Harness external.
+
+Code owns `zhivex-code`. Harness 1.x continues to own `zhx`, `zhivex-harness` and
+`zhx-acp`, preserving commands, flags, exit codes, JSON contracts and state paths.
+The Code version/help identify the terminal product; engine diagnostics continue
+to identify Harness. The historical CLI stays a Harness compatibility snapshot,
+without a Harness dependency on Code. Desktop now consumes installed engine,
+protocol, service, models and versioned host contracts; it does not import the
+old internal source bridges.
+
+Node >=22.13.0 is the runtime requirement. Bun builds and tests the source but is
+not required to install or run the JavaScript tarballs. Consumer projects retain
+their own package manager and lockfile.
+
+## Contributor validation
+
+The local candidate also adds `/desktop/v1/state`, an explicitly versioned
+integration contract for trusted Desktop main/worker processes. New names are
+experimental; aliases of historical names retain their existing tiers. Exact
+exports are recorded in `contracts/engine-api.json`. This is not a general SQL
+interface: `SqliteDatabase`, arbitrary queries and migrations are not exported.
+
+`createHostDatabaseSnapshot`, `verifyHostDatabaseSnapshot` and
+`verifyHostDatabaseState` own whole-database checks, WAL snapshots and receipt
+validation. Desktop remains responsible for closing admission, stopping workers,
+coordinating multiple projects, and verifying the application before restoration.
+Snapshot callers supply host-controlled paths. Existing `DESKTOP_*` error codes
+are preserved. The 128 MiB limit, private permissions, no-follow reads, all-scope
+idle checks and logical backup validation are unchanged.
+
+The additional file-read/path validators serve updater artifact verification and
+do not authorize writes. `SqliteAccessLease` and its acquire/adopt/descriptor
+operations retain the macOS cooperative lock protocol. Inherited lease adoption
+requires the trusted native handoff helper; it is never a renderer IPC operation.
+Different copies of the package must not exchange lease objects. Installed smoke
+verifies that engine and state entrypoints in one installation share ownership.
+Compatibility with older clients that do not participate in this locking
+protocol is not implied.
+
+The new subpaths are unpublished local additions after the deployed RC3.
+Desktop migration and packaged acceptance are documented in
+the repository-only report `docs/reports/HAR_HU_39_2026-09-29.md`. Its dependency is pinned to the
+candidate version and checked for required contracts/artifact identity; this does
+not claim compatibility with the earlier published RC3 bytes or a broader range.
+
+```sh
+bun run dev:code
+bun run typecheck:code
+bun run test:code
+bun run architecture:check
+bun run contract:check
+bun run smoke:engine-code
+```
+
+The smoke packs the current Harness candidate without changing its version. The
+release workflow supplies the exact tarball via `HARNESS_CODE_HARNESS_ARTIFACT`;
+its bytes are copied, never repacked. The report identifies hashes, installed
+versions and observed results. Node execution uses a restricted PATH excluding
+Bun. Local fixtures exercise approval, persistence and restart, Code execution
+and cancellation without live keys. Each manager has independent Harness-first
+and Code-first consumers. Every installation step exercises the manager-created
+launchers; final checks reject overlapping binary ownership, a reverse Code
+dependency and unresolved local/workspace dependency references. Tarball overrides
+use consistent relative paths to preserve Yarn Classic launchers across installs.
+This is deterministic installed evidence,
+not provider certification or a registry release. Historical HU37/38 reports
+used temporary 1.3.0-dev.0 metadata; those reports do not certify RC1.
+
+`dev:code` explicitly links the built local Harness for contributor tests; it
+preserves an existing dependency and is never run by package installation.
+Installed acceptance uses tarballs instead of that link. The CI workflow defines
+the same four-manager check on Node 22.13.0 and Node 24; a workflow definition is
+not evidence that remote CI has run.
+
+For a historical version boundary, run
+`bun run smoke:state-upgrade /absolute/old-harness.tgz /absolute/candidate-harness.tgz incompatible`.
+This installs both supplied artifacts in separate consumers and creates a pending
+approval with the historical root API. The candidate must explain its incompatible
+Harness identity without model calls, file effects or changes to the pending run.
+The historical runtime must then complete that run with explicit approval. Artifact
+hashes and observed versions are retained in the report. This test does not rewrite
+fingerprints, certify an automatic migration or verify registry provenance.
+Use `compatible` instead to require an unchanged binding and candidate completion
+after explicit approval. Both modes preserve historical session metadata across
+candidate and historical reopen. Distinct tarball bytes are required, and the
+caller chooses the expected outcome before execution; a rejected compatible case
+is a failure, not silently reclassified as success.
+Set `HARNESS_COMPAT_RUNTIME=/absolute/path/to/node` to select the runtime for
+both installed consumers; set it to `bun` to verify Bun runtime separately from
+Bun package installation. Reports record the selected executable and observed
+runtime version. The installer remains Bun regardless of the selected runtime.
+
+`bun run smoke:global-code /absolute/harness.tgz /absolute/code.tgz` tests both
+global installation orders with Bun in separate temporary global and binary
+directories. It checks the manager-created launchers after each install, exact
+resolved engine bytes, and deterministic CLI execution with Node and no Bun in
+runtime PATH. These prefixed installs do not modify the operator's global tools.
+Global locations use Bun's documented `BUN_INSTALL_GLOBAL_DIR` and
+`BUN_INSTALL_BIN` controls (see [Bun configuration](https://bun.com/docs/runtime/bunfig)).
+The default mode certifies Bun global installation; local manager coverage remains a
+separate matrix and neither test establishes registry publication or provenance.
+An optional third argument supplies a historical Harness tarball. Each temporary
+prefix first installs it and verifies legacy help/version, then tests both orders
+of candidate Harness and Code installation. Legacy launchers are checked after
+every step, including when Code is installed before upgrading Harness. The
+candidate override is explicit; this is local artifact acceptance, not evidence
+of registry dependency resolution or a historical Code release.
+`HARNESS_GLOBAL_MANAGER=npm` selects isolated npm global prefixes. This mode
+retains the exact-engine assertion and records failures per order. npm global
+may resolve Code's pinned Harness from the registry instead of reusing a locally
+installed tarball with the same version; such a result does not certify the local
+candidate. Reports retain both orders and exit nonzero if either fails.
+Set `HARNESS_GLOBAL_REGISTRY_FIXTURE=1` for npm candidate acceptance: a read-only
+loopback registry child serves the supplied Harness tarball unchanged, including
+its SHA-512 integrity, and redirects other package requests to the public registry.
+The child closes after the smoke. Reports label this `loopback-exact-candidate`,
+distinct from default registry resolution; passing it does not erase a failed
+default-registry attempt or certify publication/provenance.
+Global acceptance also supports `HARNESS_GLOBAL_MANAGER=pnpm` (11.x) and `yarn`
+(Classic 1.x), with `SMOKE_PNPM_PATH`/`SMOKE_YARN_PATH` selecting the executables.
+Both use isolated package/bin directories and explicit temporary registry config.
+pnpm's separate global installation roots are inspected individually. Shell
+utilities needed by generated launchers remain available; Bun is absent from the
+runtime PATH. These modes should use the exact-candidate registry fixture.
+
+The architecture gate follows transitive imports, re-exports and type references
+from the engine surfaces, rejecting CLI/Desktop/Code dependencies and computed
+module loads. Code has separate checks for public-package imports and manifest/bin
+ownership. Stable root declaration signatures are checked without regenerating
+the baseline to accommodate this extraction.
+
+Publishing Code requires a compatible Harness release, authenticated scope/name
+verification and the release compatibility gates in
+[ADR 0001](https://github.com/Zhivex/zhivex-harness/blob/main/docs/adr/0001-harness-code-public-boundary.md).
+Local packing does not establish npm permissions or public availability.
+## Experimental task acceptance contracts
+
+`runHarness(host, input, { taskAcceptance })` accepts application-owned requirements
+for a new run. The strict `taskAcceptanceContractSchema` is exported from `/engine`.
+It binds exact file paths, required check argv/backend/approval policy, and human
+review requirements that remain `pending`. It does not introduce arbitrary shell
+scripts or grant tool permissions. `compileTaskAcceptanceContract` provides the
+canonical digest; compilation alone does not validate the workspace or authorize
+execution. Runtime admission additionally validates the real workspace and host.
+
+```ts
+import {
+  taskAcceptanceContractSchema, runHarness,
+  inspectHarnessTaskAcceptance, reviseHarnessTaskAcceptance
+} from '@zhivex-ai/harness/engine';
+
+const contract = taskAcceptanceContractSchema.parse({
+  schemaVersion: 1,
+  taskId: 'repair-parser',
+  allowedWritePaths: ['src/parser.ts', 'tests/parser.test.ts'],
+  protectedFiles: ['package.json'],
+  requiredChecks: [{
+    id: 'test', kind: 'package-script', script: 'test', expectedScript: 'bun test',
+    command: 'bun', args: ['--no-env-file', 'run', 'test'], purpose: 'Parser regression',
+    execution: { backend: 'none', approval: 'required' }
+  }],
+  humanReview: [{ id: 'readability', requirement: 'Review readability', status: 'pending' }]
+});
+const result = await runHarness(host, { prompt: 'Repair the parser' }, { taskAcceptance: contract });
+const ledger = await inspectHarnessTaskAcceptance(host, result.state.runId);
+// After an operator approves changed requirements, while the run is stopped:
+const state = await host.store.load(result.state.runId, host.config.scope);
+await reviseHarnessTaskAcceptance(host, {
+  runId: result.state.runId,
+  expectedRunRevision: state!.revision!,
+  expectedContractRevision: ledger!.revisions.at(-1)!.revision,
+  contract: { ...contract, humanReview: [{ id: 'readability', requirement: 'Review revised behavior', status: 'pending' }] }
+});
+```
+
+The package example requires a Bun-declared manifest with the exact `test` script,
+an allowlisted `test` check, and a `run_check` tool. OCI argv checks use
+`kind: 'argv'` and `execution: { backend: 'oci', approval: 'required', network: 'none' }`;
+their executable must be in the host allowlist. File paths are exact, not globs.
+Contracts are limited to 64 KiB and 32 checks. Revision history is bounded to
+16 revisions/1 MiB; capacity errors never silently discard prior requirements.
+
+Inspection reads the host's durable store. Revision uses both run and contract
+revisions for compare-and-swap, rejects active runs, and invalidates acceptance
+evidence. Reload the state before resuming after a revision. Contract metadata
+cannot be supplied through run input; the optional third argument is the trusted
+application boundary. Runs with contracts use the host's configured scope.
+Resumes use the stored contract, and `read_task` exposes its current revision even
+after compaction. Existing runs without a contract keep their previous behavior.
+
+For OCI execution, imports enforce the exact allowed paths and protected files,
+then require every declared check to succeed against the same contract revision,
+run, environment, patch and complete snapshot bytes. Altering a package script
+or changing the snapshot invalidates verification. Recovery reconciles check
+receipts against the durable tool journal; ambiguous or interrupted effects are
+not replayed automatically.
+
+The host-owned `zhivexTaskAcceptanceEvidenceV1` metadata adds acceptance outcomes
+without changing SDK run statuses or `ChangeEnvelope` v1. Active work is `pending`;
+terminal work without sufficient delivery evidence is `incomplete`; failed runs
+or scope violations are `failed`. A completed run with a normal stop becomes
+`verified` only after a confirmed import and a final inspection of delivered host
+files and snapshot bytes. Required human review produces `pending_review` instead.
+Model prose cannot supply this evidence. The `none` backend does not receive OCI
+acceptance guarantees. Recovered import metadata is diagnostic evidence only until
+its delivery can be confirmed; it cannot alone restore a verified outcome.
+
+### Portable governance projection (Experimental)
+
+`exportHarnessGovernanceReport(store, scope, runId, options?)` reads durable runs
+and journals into `HarnessGovernanceReport`. Validate portable JSON with
+`harnessGovernanceReportSchema`; `renderHarnessGovernanceMarkdown(report)` renders
+its bounded summary. `options.changeEnvelopes` accepts up to 32 existing v1
+objects; `options.now` fixes the verification timestamp for reproducible exports.
+Neither patch bytes nor producer authenticity are certified by an envelope digest.
+
+Optional `options.session` is `{ id, index, history? }`: `index.get` and
+`history.replay` must already be bound to the same workspace/scope as the run
+store. The root must belong to the selected session. No current application policy
+is substituted for missing historical evidence. Recorded child acceptance remains
+separate from semantic review; exporting does not rerun child validation or tools.
+See the CLI portable report documentation for redaction, retention and limits.
+
+## Request context and measurements
+
+The default engine advertises a smaller common tool catalog. `discover_tools`
+loads additional authorized schemas on demand; it does not change executors,
+permissions, approval requirements or execution boundaries. Applications that
+supply `toolNames` without `discover_tools` retain a fully advertised explicit
+catalog. An explicit `toolChoice` keeps that authorized tool advertised.
+
+Large successful check, search, dependency and diff results can appear as bounded
+excerpts with a `resultId`. `read_tool_result` retrieves 4,000-character slices of
+the original evidence from the current durable run. Originals remain unchanged;
+unknown references and references from another run are rejected. If no durable
+source exists, the engine sends the original result instead of an unreadable
+reference. A partial excerpt is not proof that an omitted error or match does
+not exist. Mutation receipts and tool failures remain intact.
+
+The optional `runHarness(..., { onDiagnostics })` callback includes
+`requestMeasurements`: numeric context sizes, estimated input tokens, reported
+input/output/cache tokens and terminal completion for the current invocation.
+It retains at most 128 requests plus an omitted count and contains no prompt or
+result text. Missing usage is null, including an interrupted paid request; these
+measurements do not claim invoice accuracy or provider tokenizer equivalence.

package/docs/EXTENSIBILITY.md

@@ -8,7 +8,7 @@ Built-in registrations are Meta, Qwen, OpenAI, and Gemini. Each registration own
 
 Library callers can use `DEFAULT_PROVIDER_REGISTRY`, `BUILTIN_PROVIDER_REGISTRATIONS`, `createProviderRegistry`, or `DEFAULT_PROVIDER_REGISTRY.extend(...)`, then pass the registry to `resolveHarnessConfig`, `createProviderModel`, provider diagnostics, or `createHarness({ providerRegistry })`. Registration IDs, environment-variable names, defaults, diagnostics, and factories are validated before they become selectable.
 
-The coordinated stable SDK batch pins `@zhivex-ai/agents@1.10.1`, `@zhivex-ai/core@1.26.0`, `@zhivex-ai/meta@0.2.8`, `@zhivex-ai/qwen@0.16.2`, `@zhivex-ai/openai@0.13.6`, and `@zhivex-ai/gemini@0.12.3`. Qwen 0.16.2 types malformed Responses tool arguments and malformed SSE events; Core 1.26.0 satisfies its published dependency range. These exact versions are pinned in the lockfile. Stable SDK publication does not replace Harness release-bound certification. Qwen `0.11.x` normalizes missing, placeholder, and continuation tool-call identifiers inside the adapter; Harness retains its deterministic provider-boundary normalizer as defense in depth until the exact candidate passes the complete release-bound representative matrix. A Core override keeps one runtime contract identity across every adapter, while Core `1.13.0` corrects compaction usage accounting and interaction-group retention. OpenAI `0.11.2` preserves synthetic assistant history in Responses, so the harness no longer requires its compaction transport or accounting workarounds.
+The coordinated stable SDK batch pins `@zhivex-ai/agents@1.10.2`, `@zhivex-ai/core@1.28.0`, `@zhivex-ai/meta@0.2.8`, `@zhivex-ai/qwen@0.16.3`, `@zhivex-ai/openai@0.13.7`, and `@zhivex-ai/gemini@0.13.0`. Qwen 0.16.2 types malformed Responses tool arguments and malformed SSE events; Core 1.28.0 satisfies its published dependency range. These exact versions are pinned in the lockfile. Stable SDK publication does not replace Harness release-bound certification. Qwen `0.11.x` normalizes missing, placeholder, and continuation tool-call identifiers inside the adapter; Harness retains its deterministic provider-boundary normalizer as defense in depth until the exact candidate passes the complete release-bound representative matrix. A Core override keeps one runtime contract identity across every adapter, while Core `1.13.0` corrects compaction usage accounting and interaction-group retention. OpenAI `0.11.2` preserves synthetic assistant history in Responses, so the harness no longer requires its compaction transport or accounting workarounds.
 
 OpenAI is based on the GPT-5.6 family: `gpt-5.6-luna` is the default, with `gpt-5.6-terra` and `gpt-5.6-sol` available through `--model`. Availability remains organization-dependent while the upstream family is in limited preview, and the adapter uses the Responses API by default.
 
@@ -75,7 +75,7 @@ The schema is versioned independently:
 
 Every server requires a non-empty tool or exact-resource 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. Credential variables must use the dedicated `ZHIVEX_MCP_*` namespace, and HTTP authentication is limited to the canonical `authorization` and `x-api-key` headers so a workspace file cannot select unrelated process credentials or arbitrary outbound headers.
 
-The legacy built-in transport supports HTTPS and loopback HTTP; the opt-in SDK transport requires HTTPS. 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`.
+The legacy built-in transport supports HTTPS and loopback HTTP; the opt-in SDK transport requires HTTPS. 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; the proposed admission and isolated-stream contract is documented in [ADR 0002](adr/0002-isolated-mcp-stdio.md). This design does not enable the transport.
 
 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.
 
@@ -175,9 +175,52 @@ child must perform a successful allowed read and return `requiredOutput`; the pa
 without completed, accepted children for all configured contracts. The token
 checks a protocol condition, not the semantic correctness of the review.
 
+An opt-in experimental `resultContract` replaces marker acceptance with versioned
+JSON evidence for reviewer/explorer contracts:
+
+```ts
+resultContract: {
+  schemaVersion: 1,
+  requiredReadPaths: ["target.txt"],
+  humanReviewRequired: true,
+  maxCorrections: 0
+}
+```
+
+Required paths must be a subset of `allowedReadPaths`. The result contains
+`schemaVersion`, `taskId`, `status`, `inspectedFiles` and `findings`. Each inspected
+file declares its digest and evidence entries with `toolCallId`, `startLine` and
+`endLine`; findings reference those successful reads by path and call ID. Required
+files need complete line coverage from receipts with the same digest. Clipped
+lines, gaps, invented IDs, tool errors and invalid JSON cannot satisfy the
+contract. Results are bounded to 64 KiB, 32 files and 32 findings.
+
+The parent independently validates the durable child state and records
+`zhivexDelegationAcceptanceV1` evaluations containing child status, contract
+acceptance and semantic review status separately. An accepted schema and evidence
+coverage never certify the semantic correctness of findings. This option adds no
+write tools or arbitrary delegation authority.
+
+`maxCorrections` allows zero to two feedback attempts for invalid structured
+results. Each attempt remains in the same child run and consumes ordinary SDK
+steps, tokens and an internal feedback tool call; existing limits can stop it
+earlier. The model still sees only `read_file`. Invalid candidates remain in the
+durable history as data, and exhausted attempts fail acceptance. No tool or path
+permission is broadened for a correction.
+
+Installed deterministic acceptance is available with
+`bun run scripts/delegation-result-installed-smoke.ts <tarball> <node-path>`.
+The shared HU44 cohort covers fabricated evidence, incomplete reads, tool errors,
+invalid results, bounded correction, cancellation and durable reopen. It does not
+certify a provider route. For the separate live orchestration gate, set
+`ZHIVEX_HARNESS_LIVE_STRUCTURED_DELEGATION=1` alongside the normal live opt-in and
+installed-artifact runtime settings. That mode checks structured acceptance and
+pending semantic review before and after reopening; legacy marker certification
+remains the default. Missing credentials or failed calls are not successful gates.
+
 Contracts are copied at construction and bound into parent/child fingerprints;
 resuming under a different contract is rejected. This mode retains SDK child
-linkage, usage, cancellation and persistence. It does not retry invalid proposals
+linkage, usage, cancellation and persistence. Legacy marker contracts do not retry invalid proposals
 or increase a budget automatically. Callers without contracts keep the existing
 general-purpose delegation API, including approval-gated mutation profiles; the
 contract guarantees do not apply to that legacy mode. CLI configuration does not

package/docs/FIRST_USE.md

@@ -1,13 +1,13 @@
 # First use
 
-This guide targets the prepared `1.2.0` stable release. Installation commands become available after protected publication to npm `latest`.
+This guide targets the prepared `1.3.0-rc.7` candidate. Installation commands become available after protected publication to npm `next`; stable users can keep npm `latest`.
 
 ## Install and start
 
 Install Node.js 22.13.0 or newer and Git. Then:
 
 ```sh
-npm install -g @zhivex-ai/harness@1.2.0
+npm install -g @zhivex-ai/harness@1.3.0-rc.7
 cd /path/to/your/project
 zhx
 ```
@@ -82,16 +82,16 @@ For command execution, configure [OCI isolation](EXECUTION_ENVIRONMENTS.md).
 With Bun 1.4.0 or newer and a supported Node runtime:
 
 ```sh
-bun add --global @zhivex-ai/harness@1.2.0
+bun add --global @zhivex-ai/harness@1.3.0-rc.7
 zhx
 ```
 
 For a disposable version/help/environment check without a global installation:
 
 ```sh
-bunx @zhivex-ai/harness@1.2.0 --version
-bunx @zhivex-ai/harness@1.2.0 --help
-bunx @zhivex-ai/harness@1.2.0 doctor
+bunx @zhivex-ai/harness@1.3.0-rc.7 --version
+bunx @zhivex-ai/harness@1.3.0-rc.7 --help
+bunx @zhivex-ai/harness@1.3.0-rc.7 doctor
 ```
 
 For source development, use the [contributor guide](https://github.com/Zhivex/zhivex-harness/blob/main/CONTRIBUTING.md).

package/docs/LOCAL_SERVICE.md

@@ -140,3 +140,16 @@ 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.
+
+Policy-enabled hosts append sanitized `policy-decision` activity through the same
+session event channel. These records describe policy evaluation before entering
+the tool executor, including rule IDs, reason, approval/review requirements, digest
+and backend. They are not execution receipts and cannot authorize an action.
+Reasons are bounded and carry `reasonTruncated` when shortened. Replay pages expose
+`hasMore`; `policyEvidenceIncomplete` remains true after retention removes evidence,
+even after the client adopts the recovery cursor or the service reopens its store.
+
+The decision `phase` distinguishes `approval-request` from `tool-entry`. A pending
+approval emits the former before the tool executor is entered. Baseline decisions
+without an additional policy are observable too; an allow evaluation does not
+bypass the tool's own permission checks or certify successful execution.

package/docs/MCP_STDIO.md

@@ -0,0 +1,20 @@
+# Isolated MCP stdio for trusted hosts
+
+`@zhivex-ai/harness/mcp/stdio/v1` is an **experimental**, Node/Bun host-only entry point. It requires a local Docker daemon and previously provisioned immutable images. It does not enable `stdio` in workspace MCP JSON or ACP configuration. Never construct host policy, authorization callbacks, secret resolvers or host identity from model output or repository instructions.
+
+The host owns the flow:
+
+1. Open the canonical workspace and SQLite persistence using the root `Workspace`, `resolveHarnessConfig` and `openHarnessPersistence` APIs. Choose a scoped run ID before launching.
+2. Call `prepareMcpWorkspaceSnapshot(workspace, maxWorkspaceBytes)`. Review the snapshot digest, explicit tool allowlist, permissions, image digest, command, literal environment, secret references and limits in a `McpStdioLaunchProposal`. Host authority must constrain every resource limit.
+3. Create `createMcpStdioAdmissionAuthority({ policyVersion, maximumLimits, authorize })`. Its authorization callback receives the reviewed proposal; require your explicit operator/policy decision. `admit(proposal)` returns a short-lived, one-use receipt bound to the exact proposal.
+4. Call `launchIsolatedMcpSession` with authority, receipt, proposal, snapshot, authenticated scope, immutable provisioner image ID, host secret resolver and `journal: { store, runId, scope, hostId }`. It recovers prior dead-owner resources before launch and refuses unresolved live/foreign resources. `hostId` must be a stable identity owned by the host, not the repository.
+5. Pass the returned `hostSession` as `isolatedMcpSession` to `createHarness`, with the same store, canonical workspace and scope. Call `runHarness` with the admitted run ID. Every MCP call requires interrupt approval, including tools claiming to be read-only. Closing the harness closes the isolated session.
+6. To resume a persisted approval after closing the host, reopen SQLite, create and admit a new session with the same reviewed proposal/snapshot, recreate the harness, and resume the saved state. Proposal changes invalidate the old approval. Secret values are resolved afresh by the trusted host.
+
+A host can use `recoverDockerMcpResources({ store, runId, scope, hostId })` on startup without starting a new server. Recovery only considers persisted names and matching scope/host/daemon/images/labels. It refuses live or inaccessible owner PIDs and confirms resource absence before recording closure. Docker administrative access remains a trusted boundary.
+
+Timeout, cancellation or loss of an execution acknowledgement leaves an uncertain outcome and blocks further MCP calls in that run. After cleanup and external inspection, `createMcpReconciliationAuthority` lets the host authorize a decision bound to call ID, expected revision, confirmed effect/no-effect and evidence digest. The previous outcome remains in the audit record. The original call key never becomes replayable. A new call still needs a new session admission and tool approval. This API supplies policy hooks, not a human review interface.
+
+The snapshot is private and size-bounded. It does not mount the host workspace; changes inside it do not automatically return to the host. No host fallback or outbound network is granted. JSON Schema regex/reference features outside the supported bounded subset fail discovery. The entry point deliberately omits raw launch clients, arbitrary Docker execution and host capability issuers.
+
+See [the isolation decision](adr/0002-isolated-mcp-stdio.md) and [API stability](STABILITY.md). Local candidate verification is distinct from registry publication.

package/docs/README.md

@@ -8,6 +8,7 @@ Start with [First use](FIRST_USE.md). You only need `zhx` for everyday conversat
 - [Worked example](FIRST_USE_EXAMPLE.md): a small change with approval and restart recovery.
 - [Usage reference](USAGE.md): scripts, providers and security boundaries.
 - [Model catalog administration](MODEL_CATALOG.md): shared CLI/Desktop recommendations and remote distribution.
+- [Anthropic direct API](ANTHROPIC.md): provisional setup and continuity contract.
 - [Credentials](CREDENTIALS.md): system keychain, temporary keys and automation.
 - [Project instructions and context](CONTEXT_ENGINEERING.md).
 - [Execution environments](EXECUTION_ENVIRONMENTS.md): isolated command execution.
@@ -16,6 +17,9 @@ Start with [First use](FIRST_USE.md). You only need `zhx` for everyday conversat
 
 ## Integrate Harness
 
+- [Engine API and Code integration](ENGINE_API.md): terminal-independent imports and local candidate validation.
+- [Code release procedure](CODE_RELEASE.md): independent RC publication, exact artifact, bootstrap provenance and Trusted Publishing.
+
 - [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).
@@ -26,6 +30,8 @@ Start with [First use](FIRST_USE.md). You only need `zhx` for everyday conversat
 
 ## Contribute and maintain
 
+- [Harness/Code boundary proposal (ADR 0001)](https://github.com/Zhivex/zhivex-harness/blob/main/docs/adr/0001-harness-code-public-boundary.md): ownership, public APIs and the proposed 1.x transition.
+
 [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)

package/docs/STABILITY.md

@@ -1,5 +1,11 @@
 # API stability
 
+The additive [engine entrypoints](ENGINE_API.md) are enumerated in
+[`../contracts/engine-api.json`](../contracts/engine-api.json). Aliases preserve
+their existing root tiers; newly exposed helpers have explicit tiers. The root
+compatibility surface remains unchanged. These entrypoints are source changes
+for the planned 1.3 line, not APIs available in the registry 1.2.0 package.
+
 [`../contracts/public-api.json`](../contracts/public-api.json) is the machine-checked 1.0 baseline for the package root, binaries, CLI commands/subcommands, exit codes, and document schemas. Every runtime and type export is present in the snapshot and belongs to exactly one explicit tier. Exports listed as stable form the intended 1.x compatibility surface; Time-to-Safe-Fix exports are experimental; the explicitly listed beta exports may evolve under the policy below.
 
 [`../contracts/stable-api-signatures.json`](../contracts/stable-api-signatures.json) binds every Stable runtime and type export to a reproducible SHA-256 signature derived from emitted TypeScript declarations. Each signature includes the local declaration dependency closure, so a Beta helper type cannot change the effective signature of a Stable API unnoticed. `bun run contract:check` regenerates declarations in a temporary directory and fails on drift; `bun run contract:signatures:update` is only for a reviewed compatible baseline update or the next major version. The installed-package smoke repeats the comparison against the exact tarball declarations.
@@ -10,6 +16,8 @@ The schema-1 observational parsers preserve unknown additive fields and distingu
 
 Beta APIs may change in a minor with changelog and migration guidance. Experimental APIs may change without a deprecation window and must not be the sole supported route for a stable operation. Human-readable terminal text and error messages are not contracts; command identity, exit codes, structured document schemas, and `HarnessError.code/category/retryable` are.
 
-The semantic compactor, compaction recommendations, declarative tool policy, progress monitor, ACP text-session adapter, and workspace checkpoint restoration APIs are experimental. ACP implements the documented text-session subset; it does not claim full editor interoperability. Deterministic compaction and the existing client protocol remain available. See [ACP limitations](ACP.md), [context behavior](CONTEXT_ENGINEERING.md), and [checkpoint constraints](WORKSPACE_CHECKPOINTS.md).
+The host-only `/mcp/stdio/v1` entry point and `CreateHarnessOptions.isolatedMcpSession` option are experimental additive capabilities. Workspace MCP configuration does not enable stdio; see [host admission and lifecycle](MCP_STDIO.md).
+
+The semantic compactor, compaction recommendations, declarative tool policy (including `toolPolicyFile` and `--tool-policy`), progress monitor, ACP text-session adapter, and workspace checkpoint restoration APIs are experimental. ACP implements the documented text-session subset; it does not claim full editor interoperability. Deterministic compaction and the existing client protocol remain available. See [tool policy semantics](TOOL_POLICY.md), [ACP limitations](ACP.md), [context behavior](CONTEXT_ENGINEERING.md), and [checkpoint constraints](WORKSPACE_CHECKPOINTS.md).
 
 Before `1.0.0-rc.1`, maintainers classified every current runtime and type export as stable, beta, or experimental. The gate rejects unreviewed additions, removals, omissions, and membership in more than one tier so future stability changes remain deliberate. Root aliases remain available during 1.x; any future beta subpath must be additive until the next major release.

package/docs/SUPPORT_MATRIX.md

@@ -10,7 +10,7 @@ The machine-readable source is [`support-matrix.json`](./support-matrix.json). `
 | OCI | Docker on Linux | — | Podman | managed remote sandbox |
 | Target package manager | npm | Bun | pnpm, Yarn | — |
 | MCP | bounded Streamable HTTP | — | broader remote implementations | stdio |
-| Provider | Meta `muse-spark-1.2`, Qwen `qwen3.8-max`, OpenAI `gpt-5.6-luna` | — | Gemini | undocumented providers |
+| Provider | Meta `muse-spark-1.2`, Qwen `qwen3.8-max`, OpenAI `gpt-5.6-luna` | — | Gemini, Anthropic, Vertex (ADC) | undocumented providers |
 
 Provider evidence is release-, account-, endpoint-, model-, and date-bound. A provider is supported for a release only when the exact candidate passes base, orchestration, routing, and model-directed execution gates. The table does not imply upstream feature parity.
 

package/docs/TOOL_POLICY.md

@@ -0,0 +1,81 @@
+# Trusted tool policy (experimental)
+
+An application can pass `toolPolicyFile` to `createHarness`. The CLI accepts
+`--tool-policy /absolute/private/policy.json` for run, chat, review and resume.
+The local service host accepts the same flag at startup. Service clients cannot
+supply it: policy belongs to the process constructing the runtime.
+
+```json
+{
+  "schemaVersion": 1,
+  "rules": [
+    {
+      "id": "protect-private-file",
+      "tools": ["read_file", "read_files"],
+      "paths": ["private.txt"],
+      "decision": "deny",
+      "reason": "This file is outside the task scope"
+    }
+  ]
+}
+```
+
+Choose the file explicitly outside the workspace and its containing repository.
+The loader does not read policy instructions from AGENTS.md, skills, model output,
+environment variables or client requests. It requires a regular file owned by the
+current user, private permissions such as `0600`, one hard link, no symlink in the
+path, valid UTF-8, a strict schema and at most 128 KiB. Unknown fields, versions
+and unavailable tool names are errors. Never place secrets in rule reasons.
+
+Rules use exact tool and workspace-relative file names, without wildcards.
+The strongest matching decision wins: deny, then ask_user, then allow. Allow
+does not grant filesystem permissions or remove an existing approval. ask_user
+uses the current approval mechanism, including its configured automatic mode;
+it does not independently require a human. Human-only review is separate work.
+
+Built-in file resolvers cover read_file, read_files, propose_edits, apply_patch,
+apply_reviewed_edits, apply_reviewed_replacement, move_file and quarantine_file.
+Move rules inspect both endpoints; multi-file tools inspect every target.
+Path-scoped rules for other tools fail at construction because shell commands,
+directory queries and opaque restore IDs do not enumerate exact affected files.
+Use a tool-wide rule when appropriate. A rule on one named tool does not restrict
+other tools that could access the same data; this is an additional control, not
+a replacement for the workspace permission boundary or sandbox.
+
+File policies use `builtin-exact-files-v1`. Existing application-supplied policy
+objects retain their explicit custom resolver interface; do not combine that
+interface with toolPolicyFile. The policy and resolver version affect the durable
+runtime fingerprint inherited by children. An already-open runtime keeps its
+compiled policy when the file changes. Restart to load a change; incompatible
+durable runs must not be resumed under the replacement policy. CLI resume requires
+the operator to supply the policy again; the saved run does not authorize reading
+an arbitrary policy path.
+
+This capability remains experimental and has no effect when omitted. Local test
+results and installed-package acceptance are tracked separately in the HU52 report.
+
+HU53 adds an experimental opt-in `explicitReview: { "schemaVersion": 1 }` at
+the policy root. It requires host-issued review evidence for all positive approval
+resolutions and affects the policy digest. It does not add approval requirements
+to otherwise unrestricted tools. Automatic resolution cannot satisfy it. Client
+channels without compatible review evidence receive EXPLICIT_REVIEW_REQUIRED and
+leave the operation pending. The local CLI in ask mode displays a complete bounded
+payload and issues host evidence after explicit confirmation, without cached session
+grants. With this policy, `resume --approve` also requires interactive review;
+noninteractive invocation remains pending. Desktop accepts the operator-owned
+policy through its `--tool-policy` startup argument. Its main process consumes a
+bounded, expiring review ticket and sends the exact decision to the runtime through
+their private process channel. The renderer cannot issue review evidence, and the
+public HTTP command endpoint cannot use this private channel. Ordinary service
+clients must leave positive approvals pending under this policy.
+Local review evidence is not corporate identity and does not protect against a
+compromised host process.
+
+Approval history records the decision origin before effects: interactive for a
+local answer, automatic for automatic modes or reused session grants, application
+for ordinary API/protocol decisions, and unknown for historical records without
+provenance. Each row includes its channel and the host policy digest when present.
+Origin describes how the decision entered the host; an interactive label alone
+is not evidence of the complete review required by explicitReview. Without that
+option, recording provenance does not impose its five-minute review deadline.
+An incompatible runtime fingerprint is rejected before recording approval intent.