@zhivex-ai/harness 1.3.0-rc.3 → 1.3.0

package/docs/ENGINE_API.md

@@ -1,8 +1,8 @@
 # Engine API and Code integration
 
 This checkout adds terminal-independent package entrypoints for
-Harness 1.3.0-rc.3. They are not present in the previously published Harness 1.2.0.
-Publication is pending the protected workflow; use the documented
+Harness 1.3.0 (prepared for `latest`). They are not present in the previously published Harness 1.2.0.
+Stable 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.
 
@@ -16,6 +16,9 @@ expect the new entrypoints to exist.
 | `@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
@@ -29,6 +32,15 @@ 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 beta `/models` subpath was introduced after RC3 for HAR-HU-39 and is
+published in RC7. Stable 1.3.0 retains its beta tier; previous RC3 bytes do not
+contain it. 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";
@@ -56,8 +68,8 @@ 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.1`, prepared for independent publication to `next` with the exact
-engine dependency `@zhivex-ai/harness@1.3.0-rc.3`. Publication remains gated by
+is `0.1.0`, prepared for independent publication to `latest` with the exact
+engine dependency `@zhivex-ai/harness@1.3.0`. 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.
@@ -66,8 +78,9 @@ Code owns `zhivex-code`. Harness 1.x continues to own `zhx`, `zhivex-harness` an
 `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 keeps its existing internal bridge
-until HAR-HU-39 migrates it separately.
+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
@@ -75,6 +88,36 @@ 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 were introduced after RC3 and are published in RC7. Stable
+1.3.0 retains their declared tiers.
+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
+exact prepared engine 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
@@ -89,7 +132,12 @@ 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. This is deterministic installed evidence,
+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.
 
@@ -99,6 +147,57 @@ 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
@@ -109,3 +208,113 @@ 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.3.0-rc.3` candidate. Installation commands become available after protected publication to npm `next`; stable users can keep npm `latest`.
+This guide targets the prepared stable `1.3.0` release. These exact-version commands become available after protected publication to npm `latest`; currently latest resolves to 1.2.0.
 
 ## Install and start
 
 Install Node.js 22.13.0 or newer and Git. Then:
 
 ```sh
-npm install -g @zhivex-ai/harness@1.3.0-rc.3
+npm install -g @zhivex-ai/harness@1.3.0
 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.3.0-rc.3
+bun add --global @zhivex-ai/harness@1.3.0
 zhx
 ```
 
 For a disposable version/help/environment check without a global installation:
 
 ```sh
-bunx @zhivex-ai/harness@1.3.0-rc.3 --version
-bunx @zhivex-ai/harness@1.3.0-rc.3 --help
-bunx @zhivex-ai/harness@1.3.0-rc.3 doctor
+bunx @zhivex-ai/harness@1.3.0 --version
+bunx @zhivex-ai/harness@1.3.0 --help
+bunx @zhivex-ai/harness@1.3.0 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.

package/docs/STABILITY.md

@@ -4,7 +4,7 @@ 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.
+for the prepared 1.3.0 release and are available in the published RC7; they are absent from registry 1.2.0. Stable package numbering does not upgrade any export tier.
 
 [`../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.
 
@@ -16,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.

package/docs/VERTEX.md

@@ -0,0 +1,50 @@
+# Google Cloud Vertex AI (provisional)
+
+Vertex is a separate provider (`vertex`), using Google Cloud Application Default
+Credentials (ADC). A Gemini API key does not configure this route. The bundled
+`gemini-3.7-flash` selection is unverified; its pinned SDK requires `global`.
+Use a model enabled for your project and location. No live certification,
+pricing or context limits are inferred from the Gemini direct API.
+
+## Configuration
+
+Configure ADC on the host using your organization's Google Cloud workflow.
+Local application-default credentials, an explicit ADC credential file, and
+attached cloud identities are resolved by `google-auth-library`. Tokens are
+cached and renewed by that library, not stored in Harness sessions or Keychain.
+
+Set `GOOGLE_CLOUD_PROJECT` and `VERTEX_LOCATION` explicitly in the launching
+environment. Set `GOOGLE_APPLICATION_CREDENTIALS` to an ADC file if required by
+your deployment. Otherwise the host's standard ADC discovery applies. Harness
+does not edit credential files or run a login flow. Static `VERTEX_ACCESS_TOKEN`,
+`GOOGLE_ACCESS_TOKEN`, `VERTEX_API_KEY` and `GOOGLE_API_KEY` do not override ADC.
+Custom Vertex endpoints are not supported by this integration.
+
+Select `vertex` through the CLI provider selector or `--provider vertex`, then
+choose your model. The CLI credentials screen explains ADC instead of asking for
+an API key. In Desktop, launch the app with the same environment and select
+Google Cloud Vertex AI in the model selector. The credentials screen checks
+route configuration and can request an ADC token; it does not store/delete ADC.
+Restart Desktop after changing its project or location.
+
+Configuration presence is not an authentication or model-access check. ADC
+renewal and generation can still fail due to expired grants, missing credentials,
+IAM, model/region availability, quota or service errors. The ADC button only
+checks token acquisition; it does not certify model access or issue generation.
+
+## Durable execution and diagnostics
+
+Project, location and the explicit ADC-file path are hashed into the durable
+transport binding. A changed route cannot approve a run created on another route.
+Token renewal does not change the binding. Account changes behind the same ADC
+file remain governed by Google Cloud IAM; Harness does not fingerprint tokens.
+Unconfigured Vertex does not change existing provider transport bindings.
+
+Errors expose bounded categories for authentication, permission, unavailable
+model/route, rate limit and server failures. Raw Google payloads, token values,
+credential paths and service-account identities are not retained in errors.
+
+The integration pins `@zhivex-ai/vertex@1.1.2` with Core 1.26.0 and
+`google-auth-library@11.0.2`. Deterministic tests exercise the installed SDK's
+transport, streaming, signed continuation, approval/reopen and route mismatch.
+They are not evidence of a live project, renewable ADC or IAM authorization.