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

package/dist/workspace/path-policy.d.ts

@@ -0,0 +1,4 @@
+/** Shared lexical exclusions for workspace access and acceptance preflight. */
+export declare const HARD_IGNORES: Set<string>;
+export declare const isSensitiveName: (name: string) => boolean;
+export declare const isHardIgnored: (relativePath: string) => boolean;

package/dist/zhx.js

@@ -1,10 +1,8 @@
 #!/usr/bin/env node
 import {
+  HARNESS_VERSION,
   shortCliHelp
-} from "./cli-entry-b1mfvmxe.js";
-import {
-  HARNESS_VERSION
-} from "./cli-entry-64pdp3k5.js";
+} from "./cli-entry-ev76ezcd.js";
 import {
   __require
 } from "./cli-entry-1bx83sw4.js";
@@ -18,6 +16,6 @@ if (argv.length === 1 && ["--version", "-v", "version"].includes(argv[0])) {
   process.stdout.write(`${shortCliHelp(HARNESS_VERSION)}
 `);
 } else {
-  const { runCli } = await import("./cli-3jmy4h5h.js");
+  const { runCli } = await import("./cli-t7hrhayq.js");
   await runCli(argv);
 }

package/docs/ACP.md

@@ -2,7 +2,7 @@
 
 The harness provides an experimental Agent Client Protocol v1 **subset** for an editor or other local client: initialization, new sessions, text prompts, one-time permissions and cancellation. It runs over JSON-RPC 2.0, one JSON message per line on stdio.
 
-This is not full ACP conformance. In particular, ACP requires support for client-supplied stdio MCP servers; this adapter rejects them. Test compatibility with your editor before relying on it. The negotiation response marks the subset in `_meta.zhivex`.
+This is not full ACP conformance. Client-supplied stdio MCP servers require the explicit host integration below; the default CLI rejects them. Test compatibility with your editor before relying on it. The negotiation response marks the subset in `_meta.zhivex` and advertises `clientMcp` only when a host admission provider is attached.
 
 ## Launch
 
@@ -41,7 +41,7 @@ Only one prompt executes at a time per connection. Other simultaneous prompts re
 
 - Host owns the workspace, provider, model, credentials, policies and tools. `session/new.cwd` must match the configured workspace.
 - Text prompts only; no image, audio or embedded resources.
-- No client-provided MCP servers, client filesystem operations or client terminals.
+- Client stdio MCP only through explicit host rules and OCI admission. HTTP/SSE MCP, client filesystem operations and client terminals are unsupported.
 - No session load/resume, model switching, modes, or authentication protocol. Durable sessions remain accessible through existing harness interfaces.
 - Frames are limited to 1 MiB, prompts to 64 KiB, concurrent protocol handlers to 64 and sessions to 256 per connection. Oversized frames or handler floods terminate the connection and cancel work.
 - A transport connection should belong to a single trusted local client. This is not an unauthenticated network service.
@@ -52,4 +52,16 @@ Create the existing `createHarnessClientAdapter(harness)`, then call `createAcpC
 
 `serveAcpStdio(adapter, { workspace, input, output })` supplies framing and permission-response correlation for Node readable/writable streams.
 
+### Client MCP with host admission
+
+The experimental `@zhivex-ai/harness/acp` export `createAcpMcpHost` composes the durable adapter and per-run isolated MCP lifecycle. Supply `harness` options with explicit tenant/user identity, `rules: AcpMcpHostRule[]`, an admission `authority`, immutable `provisionerImageId`, `hostId` and `resolveSecret`. Admission authorities come from `@zhivex-ai/harness/mcp/stdio/v1`; see [isolated MCP](MCP_STDIO.md).
+
+Each rule matches a client's exact name, absolute command and arguments, and maps them to a host-owned OCI launch proposal. Image, executable, limits and tool allowlist belong to the host. `environmentBindings` explicitly maps client variables to admitted `ZHIVEX_MCP_*` names; their values are treated as sensitive. Configuration from the workspace cannot create these rules or grant admission.
+
+Pass the returned `adapter`, `workspace` and `mcpSessionProvider` to `serveAcpStdio`, or to `createAcpConnection` with your transport callbacks. Always await `host.close()` in a `finally` block after transport shutdown. The provider is bound to that adapter; another adapter or a fabricated provider is rejected.
+
+Registration is per ACP session. Before every run and approval continuation, the host snapshots the workspace, obtains fresh admission and starts the mapped servers in isolated Docker containers. Up to eight servers share the run while retaining independent receipts and tool namespaces. Tool effects still require client permission; admitting a server does not approve its tools. A partial startup failure closes previously started members. Cancellation while admission is pending prevents a late approval from launching a process.
+
+Client descriptors live only in the host's memory and expire when it closes. This integration does not enable ACP session loading across restarts. A restarted client must create a new session. Durable effect journals and resource recovery still protect against uncertain outcomes; cancellation cannot undo effects already committed.
+
 Protocol references: [initialization](https://agentclientprotocol.com/protocol/v1/initialization), [session setup](https://agentclientprotocol.com/protocol/v1/session-setup), [prompt lifecycle and cancellation](https://agentclientprotocol.com/protocol/v1/prompt-turn), [permissions](https://agentclientprotocol.com/protocol/v1/tool-calls).

package/docs/ANTHROPIC.md

@@ -0,0 +1,33 @@
+# Anthropic direct API (provisional)
+
+HAR-HU-41 adds `anthropic` through `@zhivex-ai/anthropic@0.12.4`. CLI and
+Desktop use the same registry and curated catalogue. Set `ANTHROPIC_API_KEY` or
+use the client's secure credential setup. Diagnostics expose presence and endpoint
+validity only. `ANTHROPIC_BASE_URL` is optional and must be a trusted HTTPS API base including `/v1` (default `https://api.anthropic.com/v1`).
+An unset, empty or whitespace-only endpoint uses that explicit default, without
+inheriting another endpoint from the host process environment. The CLI does not
+send a stored key to an overridden endpoint without setup consent.
+OAuth, Vertex and Bedrock are separate routes and are not enabled by this integration.
+
+```sh
+zhx run --provider anthropic --model claude-sonnet-5 "Inspect this repository"
+```
+
+The default is an explicit catalogue choice, not a discovery or account-access
+claim. Other curated choices are `claude-haiku-4-5` and `claude-opus-5-5`; an explicit
+model ID can be supplied. IDs were checked against [Anthropic's model overview](https://platform.claude.com/docs/en/models/overview)
+on 2026-09-28. All entries remain unverified in Harness; limits/pricing remain
+unknown until curated evidence is added. A missing/unavailable model is an error,
+not an automatic fallback.
+
+Harness reconstructs the SDK 0.12.4 thinking/signature SSE deltas into bounded signed blocks before durable history. Orphan, unsigned and oversized blocks fail closed.
+The integration retains signed provider-specific continuation content, tool call IDs and
+receipts, input/output usage, typed HTTP errors and abort signals. Contract tests
+exercise both generation and streaming without live requests. Adding the route
+with its default endpoint preserves the existing registry transport fingerprint;
+changing its endpoint changes the binding and prevents stale durable resumes.
+
+Anthropic remains **provisional** pending HAR-HU-45's installed-artifact live
+certification. The [common task suite](https://github.com/Zhivex/zhivex-harness/blob/main/docs/TASK_ACCEPTANCE.md) is available for that
+campaign; local mocks do not certify the provider. No new release is published by
+this implementation.

package/docs/CLI.md

@@ -663,3 +663,135 @@ Activity shows phase and total elapsed time. Preparing edits, waiting for approv
 applied file changes and verification are distinct states. `/diff` reviews workspace
 changes, including changes outside the current run; file receipts identify mutations
 recorded by this harness.
+## Trusted tool policy
+
+For an additional host-owned tool policy, use `--tool-policy <absolute-policy.json>`
+on run, chat, review or resume. The policy is experimental and must be outside the
+repository with private ownership/permissions. See [tool policy semantics](TOOL_POLICY.md).
+Clients using `--service` cannot supply this option; configure the service host.
+
+## Reviewed workspace checkpoints
+
+Use `zhx checkpoints capture <sessionId> <turnId> <path> [paths...]` to capture
+explicit files at an existing terminal conversation turn. Discover turn IDs with
+`zhx sessions inspect <sessionId>`. Capture stores the current contents; it does
+not reconstruct historical file versions. Checkpoints cover only the selected
+existing UTF-8 text files, at most 20 files of 64 KiB each. Creation, deletion,
+binary files and permission rollback are excluded. This is not a full snapshot.
+
+Capture is opt-in at the idle boundary between turns: wait for all source runs
+to terminate, select the files, capture, and only then start the next task or
+external edit. Capture does not start a run or authorize changes. If capture
+fails, no checkpoint was established; resolve the error before proceeding with
+work that needs a recovery point. There is no automatic capture on each turn.
+The stored manifest records the selected paths, digests, contents and modes;
+inspection reports file sizes, coverage and unsupported current files.
+
+```sh
+zhx checkpoints list <sessionId>
+zhx checkpoints inspect <checkpointId>
+zhx checkpoints prepare <checkpointId>
+zhx checkpoints review <operationId>
+# After reviewing the exact before/after diff:
+zhx checkpoints apply <operationId> <reviewedProposalId>
+```
+
+Preparation binds the current file digests without changing files. Apply requires
+the exact proposal identifier printed in the review; `--yes` cannot replace it.
+The digest is an identity check, not proof of human review. Read the diff before
+invoking apply. Subsequent file or permission changes cause a conflict. Missing,
+protected, binary or oversized files are shown as unavailable and are not recreated.
+
+Apply preserves the original conversation and returns its derivative. On an
+interactive terminal it opens that derivative in the console. With `--json`, it
+returns a versioned document containing the derivative session; noninteractive
+text output prints the command to open it later. These commands use local state
+without constructing a model or requiring provider credentials. Use the same
+`--workspace`, `--state-dir`, `--tenant`, `--user` and `--namespace` as the source.
+They currently do not support `--service`.
+
+After an interruption, list the source session's checkpoints and review the saved
+operation. Repeating apply for a completed operation returns the existing derivative.
+If its stage is `forking`, inspect the source's child conversations and reconcile
+the exact child titled `restore:<operationId>` using
+`zhx checkpoints recover <operationId> <existingForkSessionId>`. Recovery does not
+apply files; review and apply separately. Partial filesystem changes or a conflicting
+base require manual recovery and are never silently overwritten.
+
+### Checkpoint capacity and reviewed removal
+
+`zhx checkpoints storage` reports the current workspace/scope policy and capacity.
+The limit is 100 combined checkpoint and restore records, at most 2 MiB per
+serialized record. A capture uses one slot; preparing a restore uses another.
+Updating an existing restore can finish at capacity. There is no automatic
+eviction: a full store rejects new records while preserving existing evidence.
+Serialized bytes are logical record sizes, not SQLite file size or free disk space.
+
+Free slots by explicitly reviewing exact IDs; no age-based or implicit selection
+is performed. List a session to find its checkpoint and restore IDs. A checkpoint
+referenced by any retained restore cannot be removed. Pending restore evidence
+cannot be removed, even when the store is full. Completed restore records can be
+selected explicitly together with their checkpoint, after all references have
+been resolved.
+
+```sh
+zhx checkpoints storage
+zhx checkpoints prune-review checkpoint:<checkpointId> restore:<completedRestoreId>
+# Read the records, scope and counts in the review, then reuse that exact selection:
+zhx checkpoints prune-apply <reviewedPlanId> checkpoint:<checkpointId> restore:<completedRestoreId>
+```
+
+The review writes nothing and works at capacity. Apply requires the returned
+SHA-256 plan identity and checks the entire scoped inventory again in a SQLite
+transaction. Any inventory change requires a new review. A failed deletion rolls
+back the whole selection. Removal is permanent for those stored records; it does
+not delete workspace files, conversations or the restored derivative. The plan
+hash checks identity; it is not proof that a person reviewed the selection.
+
+State export preserves retained captures and completed restore records and
+refuses pending restore authority. Export/import never prune to fit capacity.
+Import accepts an empty destination or an identical prior import, not a merge
+with changed checkpoint history. These administrative retention commands run
+locally; Desktop can continue using the same retained checkpoints afterward.
+
+### Inspect the configured policy
+
+`zhx policy --json` returns the versioned `policy-inspection` document for a locally
+constructed host. It accepts the host's runtime settings, including `--tool-policy`.
+`zhx policy --service <credentials.json> --json` queries the existing host instead;
+runtime overrides are rejected in service mode. Omit `--json` for a readable
+summary. Neither form starts an agent run or authorizes a pending approval.
+The local form uses normal host initialization; the service form does not create
+a session. Backend and limits describe configuration, not successful OCI execution.
+
+`run`, `resume`, and local `chat` display policy explanations on stderr in text mode.
+In chat, `/approve` shows the explanation and opens complete review when the host
+requires it, including after restarting a pending conversation. The run/resume JSON
+final document includes `policyEvidence` scoped to the current invocation: at most
+64 events and 256 KiB, with `observed` and `truncated` indicating omitted evidence.
+JSONL emits policy decisions as versioned `run-event` records in the same sequence
+as other events. A service-backed run uses the same event projection and bounded
+final evidence. These observations do not replace durable tool execution receipts.
+
+### Portable governance report (Experimental)
+
+`zhx runs report <runId> [envelope.json] [--session <sessionId>] [--json]`
+exports a bounded projection from durable runs and their journals. Default output
+is Markdown; `--json` emits strict versioned `harness-governance-report` JSON.
+The existing `runs export` inspection format is unchanged. The command does not
+construct a provider, execute tools, resume runs, or inspect current workspace
+bytes. The optional envelope file is read as bounded regular-file JSON.
+
+Session selection verifies that the root run belongs to that session and includes
+retained policy decisions. Activity replay applies the existing retention policy;
+expired or truncated history is explicitly incomplete. The report excludes
+prompts, arguments, outputs, free-form errors and arbitrary metadata. Identifiers
+and paths become domain-separated hash references: pseudonyms, not anonymity.
+
+Execution completion, recorded delivery and pending semantic review are separate.
+Missing usage stays null; partial usage is labelled incomplete; costs are estimates,
+not invoices. The exporter version is not evidence of the execution artifact.
+An envelope link matches the recorded patch identifier; envelope integrity and
+expiry are checked separately. Patch bytes and producer authenticity remain
+unverified. No envelope v1 fields are added. Concurrent source changes and hard
+capacity limits reject export; bounded tree/history truncation is reported.

package/docs/CLIENT_PROTOCOL.md

@@ -85,6 +85,38 @@ or a replacement for the engine's signed approval validation.
 | run.get | projectId, sessionId, runId | run | NOT_FOUND |
 | approval.resolve | projectId, sessionId, runId, expectedRevision, idempotencyKey, decisions | run | APPROVAL_MISMATCH |
 | run.cancel | projectId, sessionId, runId, expectedRevision, idempotencyKey | run | REVISION_CONFLICT |
+| checkpoint.list | projectId, sessionId | checkpoints | NOT_FOUND |
+| checkpoint.inspect | projectId, sessionId, checkpointId | checkpoint | NOT_FOUND |
+| checkpoint.capture | projectId, sessionId, expectedRevision, idempotencyKey, turnId, paths | checkpoint | EXECUTION_FAILED |
+| restore.prepare | projectId, sessionId, checkpointId, expectedRevision, idempotencyKey, expected (path/digest map) | restore | REVISION_CONFLICT |
+| restore.get | projectId, sessionId, operationId | restore | NOT_FOUND |
+| restore.apply | projectId, sessionId, operationId, expectedRevision, idempotencyKey, reviewedProposalId | restore | EXECUTION_FAILED |
+| restore.recoverFork | projectId, sessionId, operationId, expectedRevision, idempotencyKey, forkSessionId | restore | EXECUTION_FAILED |
+
+Checkpoint mutations use the source session revision. Checkpoint/restore IDs must
+belong to that session and the host workspace/scope. Capture requires an existing
+terminal turn and explicit paths (at most twenty existing text files, 64 KiB each).
+Inspection reports unavailable files and mode conflicts and explicitly excludes
+creation, deletion, binary files, mode rollback and full workspace snapshots.
+
+Prepare uses the exact digests observed during inspection and returns the prepared
+operation plus a diff. Clients must show that diff and obtain explicit review before
+sending its `reviewedProposalId` to apply. A digest identifies content; it is not proof
+of a human decision. Hosts must enforce their UI review boundary. The Desktop generic
+command IPC does not accept apply/recover requests; its dedicated review flow is required.
+Local CLI checkpoint commands use the same engine API. Desktop exposes checkpoint
+review through dedicated host-issued tickets; generic IPC cannot apply or reconcile
+a restore. The CLI does not yet route checkpoint commands through `--service`.
+
+Restore responses contain operation metadata and an available/unavailable preview,
+without duplicating the captured contents. Successful apply includes the derivative
+session to open and preserves the original. Listing includes interrupted and completed
+operations. After reconnecting, query the same operation before resuming: completion
+is durable and applying again returns the existing derivative. An uncertain fork must
+be reconciled with its exact existing child ID via `restore.recoverFork`; this does not
+apply files or authorize a subsequent restore. Stale contents, missing files, mode
+changes and partial filesystem outcomes fail closed. Apply/recovery also reject source
+conversations with unfinished durable runs.
 
 Session documents contain sessionId, revision, optional title and ordered runId/status
 references. Lists use the existing bounded session store (default 50; no pagination
@@ -210,3 +242,16 @@ The local-service constructor optionally accepts a trusted `approvalNow` clock.
 It is not a client command or IPC capability. Desktop expiry tests advance only
 the service clock to prove server-side rejection while the review receipt remains
 unexpired in the main process.
+
+### Experimental policy inspection
+
+`policy.get` takes only `projectId` and returns `{ kind: "policy", policy }`.
+The versioned policy document is the same host snapshot returned by
+`inspectHarnessPolicy` from `@zhivex-ai/harness/engine`. It contains configuration,
+not proof of tool or OCI execution. Clients cannot supply policy overrides in
+this command. The read remains available while mutation admission is paused or
+a run is active, and does not create a session, authorize an approval or execute
+a tool. Rule paths and host filesystem locations are omitted.
+While a host-prepared runtime is active, the query reflects that runtime. Before
+preparation and after release it reflects the base host; decision events retain
+the digest and backend of the runtime that evaluated them.

package/docs/CODE_RELEASE.md

@@ -0,0 +1,93 @@
+# Code release procedure
+
+Code is released independently of Harness. The initial candidate is
+`@zhivex-ai/code@0.1.0-rc.2`, with the sole binary `zhivex-code`, npm tag `next`,
+and the exact dependency `@zhivex-ai/harness@1.3.0-rc.7`. Harness must first be
+published and verified through its protected release workflow. This document
+records preparation, not successful publication.
+
+## Release preparation
+
+1. Merge the Code release PR after required review and successful checks.
+2. Wait for the latest `ci.yml` and `codeql.yml` **push runs on main** to succeed
+   for the exact commit. Keep the Code manifest, version and engine pin unchanged
+   after selecting that commit.
+3. From a clean checkout of that main commit, create an annotated
+   `code-v0.1.0-rc.2` tag and push it. Never move or overwrite release tags.
+4. Dispatch `release-code.yml` **at that tag**, with input `tag` matching it and
+   `mode=bootstrap`. Dispatching main while supplying a different tag is rejected.
+
+```sh
+gh workflow run release-code.yml --ref code-v0.1.0-rc.2 \
+  -f tag=code-v0.1.0-rc.2 -f mode=bootstrap -f confirm_publication=false
+```
+
+The workflow validates tag identity, main ancestry, exact CI/CodeQL, Code source
+and package boundaries. It downloads the pinned Harness version from npm and
+verifies its integrity; missing publication or provenance stops the release.
+It builds Code once, inspects package contents, installs it against the actual
+registry dependency without overrides, and tests the retained Code and Harness
+artifacts with npm, pnpm, Yarn and Bun. The paired matrix uses explicit engine
+artifact overrides; the separate standalone installation proves npm resolution.
+This does not claim every future engine version or installation order is certified.
+
+The workflow generates genuine npm/Sigstore provenance using pinned npm 11.6.1
+inside the GitHub-hosted build job. It retains `code.tgz`, `code.sigstore.json`,
+`SHA512SUMS`, and installed acceptance in `code-release-<full-source-sha>`.
+Bootstrap mode **does not publish**. No npm token is copied into GitHub.
+
+## First publication
+
+npm requires the package to exist before configuring its trusted publisher;
+staged publishing also requires an existing package. An authenticated scope
+owner performs the first publication using the successful workflow's retained
+artifact and provenance bundle. Do not rebuild the tarball locally.
+
+Download the artifact from the exact successful run, then verify it in a clean
+checkout of its annotated Code tag. `CODE_EXPECTED_SHA` must be that tag's full
+commit SHA. Install npm 11.6.1 into an isolated tools directory and set
+`CODE_PROVENANCE_NPM_ROOT` to its `node_modules/npm` directory.
+
+```sh
+(cd release-code-artifacts && shasum -a 512 -c SHA512SUMS)
+bun run scripts/code-release.ts inspect release-code-artifacts/code.tgz
+CODE_EXPECTED_SHA="$(git rev-list -n 1 code-v0.1.0-rc.2)" \
+  node scripts/code-bootstrap-provenance.cjs verify \
+  release-code-artifacts/code.tgz release-code-artifacts/code.sigstore.json
+node "$CODE_PROVENANCE_NPM_ROOT/bin/npm-cli.js" publish \
+  ./release-code-artifacts/code.tgz --ignore-scripts --access public \
+  --tag next --provenance-file ./release-code-artifacts/code.sigstore.json
+bun run scripts/code-release.ts verify release-code-artifacts/code.tgz
+```
+
+The provenance verifier checks the Sigstore signature, GitHub issuer, exact
+workflow/tag identity, source commit and tarball digest. Complete any npm 2FA
+challenge directly; do not put a one-time code into documentation or logs. If npm
+accepts publication but verification fails, inspect registry state and retry
+verification with the same retained bytes. An existing different digest is a
+hard failure; never attempt to replace that version.
+
+## Subsequent releases with Trusted Publishing
+
+In npm package settings, configure GitHub Actions with organization `Zhivex`,
+repository `zhivex-harness`, workflow filename `release-code.yml`, and environment
+`npm`. Enable the allowed action `npm publish`; the OIDC job uses direct
+publishing after GitHub approval, not `npm stage publish`. Preserve the GitHub
+environment's required human approval. Then prepare a
+new Code RC/version and annotated tag through the same PR and main CI process.
+Dispatch its tag with `mode=oidc` and `confirm_publication=true`.
+
+All Code tags share one workflow concurrency group. Before publishing, the
+registry gate also rejects moving `next` back to an older RC, including when
+GitHub schedules queued workflows out of order.
+
+The publish job downloads the validated artifact without rebuilding it,
+rechecks identity and digest after protected approval, and uses npm OIDC plus
+provenance. It verifies registry tarball bytes, the `next` distribution tag and
+SLSA source/workflow identity. A successful dispatch or tag is not publication;
+only successful registry verification confirms the release. When a run has
+already published, rerun only the failed publish job to retain original bytes.
+
+Official references: [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/),
+[npm provenance](https://docs.npmjs.com/generating-provenance-statements/), and
+[npm staged publishing](https://docs.npmjs.com/staged-publishing/).