planr 1.10.0-alpha.7 → 1.10.0-alpha.9

package/docs/ARCHITECTURE.md

@@ -61,7 +61,7 @@ Every live worker decision is a typed work packet:
 
 - `kind: "outcome"` is ordinary maker work; `mode: "finding_repair"` returns named findings to the same responsible maker and ReviewGate without creating a fix item.
 - `kind: "review_gate"` is independently leased checker work. Attempts and findings remain children of that gate, never graph items.
-- `kind: "verification"` is a fresh verifier lease over a frozen canonical source digest. Product source is read-only; trusted Evidence can commit only through the source-checked Evidence transaction.
+- `kind: "verification"` is a coordinator-owned verifier lease over a frozen canonical source digest. Product source is read-only; trusted Evidence can commit only through the source-checked Evidence transaction. The coordinator calls `evidence verify` without another model.
 - Releasing verification is an application-owned transition: the item lease, FeatureRun verifier role, and verification budget reconcile atomically back to `source_frozen`. `pick release --repair <reference>` additionally invalidates the frozen candidate and routes a fresh repair batch to the recorded maker; the failed verifier lease is never resumed.
 - An accepted material checkpoint is source-bound after any product or admission repair. Repair settlement preserves the prior attempt, reopens the same gate with the active freeze revision/digest and repair-obligation lineage, and leaves verification unleaseable until a fresh independent acceptance of that exact binding.
 - `kind: "hold"` is an admission or capability stop. A driver must report its classification and next action; it cannot reinterpret the hold as permission to replace the maker, weaken verification, or open an ad hoc review.
@@ -117,10 +117,10 @@ The frozen product contract lives in `docs/contracts/EVAL_CONTRACT_V1.md` until
 
 Planr remains a single crate for V1 because:
 
-- there is one deployable binary and no separate service or reusable library boundary;
+- one crate owns the CLI and its optional companion executables;
 - the current behavior contract is tighter when CLI, MCP, HTTP, storage, and docs ship together;
 - module-level ownership gives the needed architecture separation without duplicating Cargo settings or release packaging;
-- npm, release, and external consumer tests assume one native binary named `planr`.
+- npm, release, and external consumer tests treat `planr` as the product entry point. They also package provider-specific companion executables when Planr ships them.
 
 A Cargo workspace was tried and reverted: it produced anemic crates whose only job was being a layer, plus re-export shims in the binary. A workspace should be introduced only after a concrete deployable, reuse, compilation, or team ownership boundary exists and package/release scripts are updated in the same change.
 

package/docs/RELEASE.md

@@ -202,6 +202,7 @@ cat dist/planr-*/SHA256SUMS
 The artifact contains:
 
 - `planr`
+- `planr-browser-harness-adapter`
 - `scripts/host-capability-experiment.mjs`
 - `scripts/host-capability-runtime/v1/schemas/*.schema.json`
 - `scripts/planr-host-capability-validator`
@@ -228,6 +229,8 @@ npm pack --dry-run
 The package must include:
 
 - `npm/bin/planr.js`
+- `npm/bin/planr-browser-harness-adapter.js`
+- `npm/bin/native-launcher.js`
 - `scripts/host-capability-experiment.mjs`
 - `scripts/host-capability-runtime/v1/schemas/*.schema.json`
 - `scripts/planr-host-capability-validator`
@@ -237,7 +240,7 @@ The package must include:
 - `README.md`
 - `LICENSE.md`
 
-`npm/native/` platform binaries exist only in the `npm-publish` CI job; the local dry-run does not include them.
+`npm/native/` platform binaries exist only in the `npm-publish` CI job. The published package includes `planr`, `planr-browser-harness-adapter`, and `planr-host-capability-validator` for each platform. The local dry-run does not include these binaries.
 
 ## Install Smoke
 

package/docs/SWITCHLOOM_COMPATIBILITY.md

@@ -1,46 +1,14 @@
-# Switchloom Compatibility
+# Archived Switchloom v0.3.2 Compatibility Evidence
 
-This report records Planr-side compatibility evidence for the exact public `switchloom@0.3.2` package. It is intentionally narrow: Planr verifies the package identity, repository-local declaration boundary, and its own consumption/proof semantics. It does not turn Switchloom internals, generated semantic role names, routes, doctor output, or runtime telemetry into a future contract.
+This document records a historical compatibility check performed for the external `switchloom@0.3.2` package. It is not a current Planr release gate or a promise about future Switchloom artifacts, routes, role names, host telemetry, or lifecycle behavior.
 
-## Exact v0.3.2 Behavior Verified
+The historical check established only that the pinned v0.3.2 package could generate repository-local `.planr/agents.toml` and `.planr/policy.toml` declarations that the Planr version at that time consumed successfully. The accompanying one-off cross-product oracle has been removed from Planr.
 
-- Public npm metadata for `switchloom@0.3.2` resolved from the npm registry:
-  - `dist.integrity`: `sha512-g96AZIFKXpG1toAO+Gri1sjD8q0SxFxtRSLAcRcSVRGDCZ/dUtERepsOB+cSHHH7hUsT0jSKZYPfNqiLvfKk9Q==`
-  - `dist.shasum`: `d7d72c74ac3ecd5a3e355edd8e297284cba04403`
-  - `dist.tarball`: `https://registry.npmjs.org/switchloom/-/switchloom-0.3.2.tgz`
-- `npm pack switchloom@0.3.2 --pack-destination /private/tmp --json` returned a 9-entry package with the expected native binaries, wrapper, provenance file, README, license, and package manifest.
-- The packed tarball at `/private/tmp/switchloom-0.3.2.tgz` had SHA256 `0c04e94fc4372845edf395b3ea51139b8a4b46f34404940e06b3f4ec3ce22d20`.
-- The reviewed oracle contract expects the v0.3.2 Planr integration bundle `balanced-codex-openai@1.0.0+2.0.0`, bundle SHA256 `bf48f502080ff444ccb67bc4eeacc9391e77dbf5f0f8f277814e9abc2443e6c8`, 10 managed artifacts, 7 Codex-native roles, and 5 Planr work-type routes.
-- Repository docs now document the safe external operator flow with explicit `switchloom@0.3.2` commands, no normal-guidance `apply --yes`, and a caveat that the v0.3.2 tagged README preserves stale `0.3.1` examples.
-- The immutable live oracle used isolated source clone `/private/tmp/planr-switchloom-source.6gbzx2/source` and completed with `SWITCHLOOM_SOURCE_ROOT=/private/tmp/planr-switchloom-source.6gbzx2/source SWITCHLOOM_TARBALL=/private/tmp/switchloom-0.3.2.tgz PLANR_ORACLE_TEMP_PARENT=/private/tmp npm run verify:switchloom-cross-product`, exit 0. The live root is `/private/tmp/planr-switchloom-cross-product-Lbluca`, with oracle receipt `/private/tmp/planr-switchloom-cross-product-Lbluca/oracle-receipt.json`.
-- The retained replay of the same root and isolated source clone exited 0 and wrote `/private/tmp/planr-switchloom-cross-product-Lbluca/replay-receipt.json`. Replay first asserts the current source fingerprint matches the retained live receipt, then separately verifies the source remains unchanged during replay.
-- The live and replay receipts bind the same Switchloom source fingerprint before and after each mode: HEAD `8ff05776085d3175211e080143c513c5173abaa4`, clean status SHA256 `e3b0c442...`, inventory SHA256 `790de1be...`, file-hash SHA256 `97a26b12...`, and 303 paths. The maintainer's original sibling Switchloom worktree was not modified for this proof.
-- The successful live oracle proves exact package tarball SHA256 `0c04e94fc4372845edf395b3ea51139b8a4b46f34404940e06b3f4ec3ce22d20`, bundle SHA256 `bf48f502080ff444ccb67bc4eeacc9391e77dbf5f0f8f277814e9abc2443e6c8`, 7 profiles, 5 routes, 10 managed artifacts, Planr declaration consumption, Planr audit, uninstall and unrouted Planr behavior, no-auth fail-closed behavior, requested-only rejection, global sentinel preservation, and routing ownership.
-- The successful live oracle proves separate native maker and reviewer execution: maker `model_routing_terra_high` on `gpt-5.6-terra` with high effort, reviewer `model_routing_sol_high` on `gpt-5.6-sol` with high effort. Hidden spawn messages are intentionally opaque; the proof is exact successful parent `agent_type`, `task_name`, and `fork_turns` metadata correlated with matching direct child role rollouts, repo-local skill reads, and item-specific Planr evidence. It does not claim plaintext hidden-message recovery.
-- One malformed parent `spawn_agent` attempt in the retained live root was retained as a diagnostic and not counted as a successful spawn. The oracle still requires exactly two successful routed spawns and still rejects default, wrong-role, missing-role, or extra successful child execution.
-- A separate fresh root, `/private/tmp/planr-switchloom-cross-product-gHtZQI`, was correctly rejected: Codex claimed `spawn_agent` was unavailable and directly handled the work, producing 0 successful routed spawns. That run is negative evidence for host stochastic failure detection, not a passing compatibility run.
+Planr's stable boundary remains:
 
-## Stable Planr Boundary
+- Planr works without Switchloom or routing declarations.
+- Planr treats profiles, routes, model names, efforts, and fallbacks as provider-neutral repository data.
+- Requested routing metadata is not effective execution proof.
+- External tools own their install, compilation, generated host files, reload requirements, and uninstall lifecycle.
 
-- Planr Core is provider-neutral. It reads `.planr/agents.toml`, `.planr/policy.toml`, and route-audit evidence, but does not install, invoke, compile, apply, or uninstall Switchloom output.
-- `.planr/agents.toml` profiles, routes, model names, efforts, role names, and fallback chains are opaque data to Planr. Planr may place requested routing data in pick packets, but requested-only values are not effective execution proof.
-- `--profile` records the profile a worker reports for a run. Genuine runtime proof belongs in route-audit evidence that separates requested, host-resolved, and effective dimensions.
-- Missing effective host evidence remains explicitly unavailable. Planr must not infer it from generated declarations, policy files, or worker claims.
-- External lifecycle remains external: Switchloom owns compile, apply, generated host roles, host reload requirements, and uninstall. Planr validates its own consumption with `planr agents check` and records evidence through logs/reviews.
-- Planr works without routing declarations. After an external uninstall, unrouted Planr fallback behavior remains the stable Core contract.
-
-## Not Guaranteed For Future Switchloom Work
-
-Future Switchloom work, including thread `019f8a71-5b6c-7c41-9850-7050516fcee4`, may change semantic role names, route names, doctor output, generated artifacts, runtime telemetry, and host-specific evidence shape. Planr must not contract those as stable.
-
-The stable compatibility promise is limited to Planr's boundary: consume provider-neutral declarations when present, keep requested values separate from effective evidence, reject requested-only metadata as proof, avoid owning external lifecycle, and continue operating when routing files are absent.
-
-Any future mismatch in package identity, generated artifacts, Planr declaration parsing, route-audit semantics, host evidence, source-worktree mutation, or security posture should become a new finding and responsible-maker repair rather than an optimistic compatibility claim.
-
-## Verification Notes
-
-- Rust formatting, clippy, full serial cargo tests, e2e, eval-contract, and routing-ownership tests passed when run outside the sandbox where HTTP/process tests are permitted.
-- Docs reference generation, typecheck, reference verification, maintenance verification, and Node 22 production build passed. Node 26 production docs builds hung in the optimized Next build phase and were terminated; the Node 22 build is the relevant repository runtime.
-- npm package dry-run passed using a temp npm cache because the user npm cache contains root-owned files.
-- Privacy checks passed. The docs app Next.js runtime was upgraded from `16.2.10` to `16.2.11` in `apps/docs/package.json` and `pnpm-lock.yaml`; the lockfile change is limited to Next core/env/SWC and mechanically recalculated peer snapshots. `npm run security:check` passed with BetterLeaks reporting no leaks and Trivy reporting 0 vulnerabilities for both `Cargo.lock` and `pnpm-lock.yaml`.
-- The immutable source clone proof supersedes earlier retained-replay-only evidence. Earlier concurrent external mutation and missing-receipt attempts were treated as real failures and are not counted as passing evidence.
+For current Switchloom behavior, consult the external project and its versioned documentation. Any future compatibility claim requires a new bounded check owned by that integration; Planr does not retain a permanent package-specific oracle.

package/docs/contracts/BROWSER_HARNESS_ADAPTER_V1.md

@@ -0,0 +1,75 @@
+# Browser Harness adapter v1
+
+Status: frozen for `planr-browser-harness-adapter` v1.
+
+This reference defines Planr's first process adapter for the external
+`browser-harness` tool. The adapter implements
+`EVIDENCE_ADAPTER_PROTOCOL_V1.md`. Planr Core does not depend on this adapter.
+
+## Capability
+
+The adapter supports `com.planr.web.dom_state` observations with the payload
+schema `schema://com.planr.web.dom_state.v1`.
+
+Each requirement uses these fields:
+
+- `subject`: A CSS selector for the observed element.
+- `expected.text`: The exact trimmed `textContent`, if text is required.
+- `expected.visible`: The required rendered visibility, if visibility is
+  required.
+- `state_transitions`: A shared array of click actions for the batch. Each
+  action has `action = "click"`, an accessibility `role`, and an accessibility
+  `name`.
+
+All requirements in one batch must use the same transition array and the same
+optional execution method. The adapter rejects arbitrary actions, arbitrary
+JavaScript, mixed methods, and unsupported observation types before it starts
+the browser tool.
+
+## Execution
+
+An availability probe runs `browser-harness --version`. A real Evidence run
+starts `browser-harness` once and sends one generated Python program over
+stdin. The program completes these steps in one browser session:
+
+1. Open the bound HTTP or HTTPS target.
+2. Find each click target in the accessibility tree by its role and name.
+3. Click the center of the target's CDP box model.
+4. Read each DOM postcondition until it passes or the five-second observation
+   window ends.
+5. Return one structured result for the full requirement batch.
+6. Close the tab.
+
+The generated program inserts requirement data only as JSON. A requirement
+cannot add executable Python or JavaScript.
+
+## Result
+
+Each `actual` object contains:
+
+```json
+{
+  "schema_ref": "schema://com.planr.web.dom_state.v1",
+  "selector": "#status",
+  "text": "B",
+  "visible": true
+}
+```
+
+Planr Core validates this object against the registered JSON Schema. Core then
+evaluates the requirement's `expected` predicate.
+
+If every requirement selects the `browser-harness` agent skill, the adapter
+also returns the matching supervised invocation record. This record is adapter
+output. It becomes trusted only after Planr validates the observed process and
+all sealed bindings.
+
+## Capture policy
+
+The v1 success path disables Browser Harness recordings. The generated program
+does not call screenshot, recording, or trace helpers. The structured DOM
+observation is the retained proof for a non-visual criterion.
+
+The adapter does not advertise a visual observation type. Planr therefore
+rejects it during capability matching for a visual requirement. A recording or
+screenshot cannot upgrade `com.planr.web.dom_state` into visual Evidence.

package/docs/contracts/EVIDENCE_ADAPTER_PROTOCOL_V1.md

@@ -0,0 +1,98 @@
+# Evidence adapter protocol v1
+
+Status: frozen for the `planr.evidence.adapter-request.v1` request and the
+`planr.structured_observation_results.v2` result.
+
+This reference defines the process protocol between Planr Core and a registered
+Evidence adapter. It extends `EVIDENCE_CONTRACT_V1.md`. It does not change the
+Evidence domain schema.
+
+## Trust ownership
+
+Planr Core creates the adapter request, starts the registered process, and
+validates the result. The adapter reports observations. It cannot assign
+provenance, decide coverage, or close work.
+
+Planr treats adapter output as untrusted input until all execution and binding
+checks pass. A valid JSON result without a Planr-observed process execution
+cannot create trusted Evidence.
+
+## Process transport
+
+Planr starts the adapter with bounded time, stdout, and stderr limits. Planr
+writes one JSON request to stdin and then closes stdin. The adapter writes one
+JSON result to stdout.
+
+An availability probe starts the same executable with closed, empty stdin. The
+adapter can use that invocation to check runtime availability. A probe result
+cannot satisfy an Evidence requirement.
+
+Planr reserves the `PLANR_EVIDENCE_` environment variable namespace. An adapter
+request does not use environment variables for target, environment, or contract
+bindings.
+
+## `planr.evidence.adapter-request.v1`
+
+The request has these fields:
+
+- `schema_version`: `planr.evidence.adapter-request.v1`.
+- `request_id`: A new Planr-assigned ID for this process execution.
+- `request_digest`: The SHA-256 canonical JSON digest of the request without
+  `request_digest`.
+- `obligation_id` and `criterion_id`: The exact Evidence obligation identity.
+- `requirements`: The selected `ObservationRequirement` objects. The array
+  includes each subject, expected value, target, payload schema, and optional
+  execution method.
+- `target` and `environment`: The runtime bindings selected by Planr.
+- `fixture_disclosure`: The fixture and mock disclosure admitted by policy.
+- `assurance_policy`: The policy that controls required capture strength.
+- `result_contract`: The registered outer result schema binding.
+- `execution_contract_digest`: The digest of the registered process contract.
+- `execution_binding`: The sealed run-index subset and its requirement IDs.
+- `retry`: The exact attempt number, maximum attempts, and predecessor IDs.
+
+The request contains no provider-specific fields. A Browser Harness, native
+browser, Playwright, mobile, desktop, game-engine, API, or CLI adapter receives
+the same request shape.
+
+## `planr.structured_observation_results.v2`
+
+A structured adapter result has these required fields:
+
+- `schema_version`: `planr.structured_observation_results.v2`.
+- `request_id` and `request_digest`: Exact copies from the current request.
+- `target`, `observed_target`, and `environment`: The declared and observed
+  runtime identity.
+- `execution_contract_digest`: An exact copy from the current request.
+- `fixture_disclosure`: The actual fixture and mock use.
+- `observations`: One result for every selected requirement and no other
+  results.
+
+Each observation contains only `requirement_id`, `type`, and `actual`. The
+`actual` object names its payload schema. Planr validates the object against the
+registered JSON Schema and evaluates the expected predicate.
+
+If a requirement selects an agent skill as its execution method, the result
+also includes the structured `agent_skill` invocation record required by the
+Evidence domain contract. The supervised adapter creates this record. Agent or
+user JSON cannot submit it through another trusted path.
+
+Adapters can include diagnostic top-level fields. Diagnostics do not affect
+provenance or coverage.
+
+## Failure behavior
+
+Planr rejects the result if the process fails or if any required binding does
+not match. This includes a stale request ID, a stale request digest, a wrong
+target, a wrong environment, a wrong execution contract, missing observations,
+extra observations, a schema mismatch, and an unsatisfied expected predicate.
+
+Planr records the failed attempt. Planr does not create a trusted passing
+receipt from that result.
+
+## Version transition
+
+`planr.structured_observation_results.v2` replaces
+`planr.structured_observation_results.v1`. Planr does not keep a second trusted
+compatibility path. Adapter manifests and policy registrations must use the v2
+schema reference and artifact name.

package/docs/contracts/EVIDENCE_CONTRACT_V1.md

@@ -21,10 +21,101 @@ Evidence Contract v1 is Planr's local-first contract for proving acceptance crit
 - Route Audit remains the owner of requested, resolved, and effective routing evidence. Evidence may consume a mapped provenance view, but it must not copy requested route declarations into effective execution proof.
 - Agent Profiles, model-routing capability classes, usage-policy capability classes, MCP protocol capabilities, and context tags are dispatch or protocol metadata. They are not verification capability instances and do not prove runtime availability.
 - Planr logs remain narrative and supporting records. A `kind = verification` log is a claim that can be referenced, but it never satisfies a binding observation.
-- A repository without a binding Evidence policy and without binding plan obligations is explicitly non-binding. A binding plan is `binding_unsatisfied` unless its authoritative active obligations match the declared build-plan criterion set exactly: zero, partial, duplicate, or undeclared bindings all fail closed. Planr returns a hold before leasing or creating a FeatureRun, persists a capability hold when an existing run reaches readiness, rejects coverage settlement, closure, final review, and stop activation, and never substitutes logs or an empty receipt lineage.
+- A repository without a binding Evidence policy and without binding plan obligations is explicitly non-binding. A binding plan is `binding_unsatisfied` unless its authoritative active obligations match the declared build-plan criterion set exactly: zero, partial, duplicate, or undeclared bindings all fail closed. Planr returns a hold before leasing or creating a FeatureRun, persists a capability hold when an existing run reaches readiness, rejects coverage settlement, closure, and stop activation, and never substitutes logs or an empty receipt lineage.
 - Migration is the sole obligation-materialization path. It is explicit, plan-scoped, previewable, idempotent, and accepts only an exact declared criterion binding set before materializing ordinary immutable `ProofObligation` rows. It must not rewrite plans, logs, reviews, artifacts, or historical claims.
 - Planr artifacts remain files or references with digests. An artifact alone is not trusted evidence unless a trusted receipt binds it to the source revision, target, environment, execution identity, observation results, and policy.
 
+## Binding Execution Orchestration
+
+The normal public success path is one plan-scoped `evidence verify` broker call. The caller identity
+must differ from the responsible maker. Planr uses that identity for the verifier lease, readiness
+admission, adapter execution, coverage evaluation, and FeatureRun settlement. A coordinator or host
+must not spawn another model to perform this mechanical Evidence phase. The lower-level readiness
+and run services remain diagnostic and application primitives; they do not define a second trusted
+workflow.
+
+Before verification admission, FeatureRun source freeze is legal only when no open ordinary
+implementation outcome remains. Planned `code`, `fix`, `docs`, and `test` share the one domain-owned
+maker-compatible classification. An active source-frozen run that still has open ordinary work and
+has no verifier admission, Evidence attempt, or receipt for its immutable freeze is retired only by
+the typed `premature-source-freeze` transition. Retirement preserves the freeze and all Evidence
+history, releases active ordinary leases, and creates no successor. The repository-owned no-model
+`com.planr.premature_freeze.lifecycle.v1` capability is reserved for the final frozen-source HARDEN
+observation; registering it does not execute or satisfy that observation during BUILD.
+
+An active Verification FeatureRun whose current admission is absent or unequal across the active
+plan/run/revision, freeze, verifier worker/generation, optional item, or admitted/sealed run-index
+digest is retired only by the typed `inconsistent-verification` transition. A current item whose
+status or worker does not match the verifier lease is
+`verification_item_ownership_conflict`. Exact equality rejects retirement. One immediate
+optimistic transaction invalidates but preserves the freeze, ends or preserves-ended the referenced
+batch, releases exact roles, Verification reservations, and the exact observed optional item state,
+preserves every prior Evidence/history identity, emits one typed event, and creates no successor.
+Repetition reads that event and writes nothing. The
+repository-owned `com.planr.inconsistent_verification.retirement.v1` capability is registered during
+BUILD but first executes only after HARDEN supplies the exact focused invariant.
+
+`planr.evidence.run-index.v2` is the sole executable run-index shape. Readiness consumes canonical
+authoritative obligation rows and seals exactly one run for every distinct canonical target within
+each obligation. A run names one `obligation_id`, one target, and sorted non-empty unique
+`requirement_ids`. For each obligation, admission recomputes the target partition and requires the
+run subsets to be disjoint and to form the exact union of authoritative observation requirement
+IDs. Requirements from different obligations never share a run.
+
+Execution, structured and ordinary result validation, receipt observation construction, retry
+predecessor validation, independence, hermetic reuse, and persisted attempt/receipt lineage bind
+only the selected requirement subset plus the sealed source, policy, target, capability,
+environment, execution contract, and run-index digest. Extra, missing, duplicate, foreign-target,
+or cross-subset data fails before trusted receipt persistence. `evidence/coverage` remains the sole
+coverage and closure owner; a run-index result is not a coverage verdict.
+
+A multi-target obligation that would execute a `non_repeatable_one_shot` capability fails readiness
+before launch or durable allowance claim. Host capture consumes the same sealed target/subset
+contract as process execution and owns no first-observation or all-targets-equal policy.
+
+Pre-receipt admission failure persists no attempt, receipt, coverage verdict, or ProductFinding.
+One explicit optimistic plan/run/freeze/revision-scoped FeatureRun repair request has a closed
+reason enum and conditional seal binding. Pre-seal `readiness-blocked` and
+`run-index-seal-failed` require `run_index_digest` to be absent; post-seal pre-receipt
+`sealed-run-rejected` and `capability-admission-failed` require the exact admitted digest. A failed
+readiness lease transaction rolls back before Planr persists its durable capability hold and
+diagnostic, so no unusable verifier lease is committed to create repair context. The repair
+invalidates the active freeze, releases verifier ownership and any present verification-item
+lease, restores the original maker at the next lease generation, starts one repair batch, emits one
+repair event, and projects an optional `verification_item_id`. Post-receipt `product_failed` and
+terminal one-shot exhaustion remain their existing distinct lifecycles.
+
+Satisfied plan coverage settles the active FeatureRun by exact verifier lease generation, active
+immutable freeze, and accepted trusted receipt lineage whose source binding exactly equals that
+freeze. A verification map item is a zero-or-one projection. If one item is picked or running under
+the verifier, settlement closes and logs it in the same transaction; if none exists, settlement
+performs zero item/log mutations. A ready unleased verification item remains fail-closed. The
+transition always reconciles the verification budget wall, applies `VerificationPassed` to
+`Complete` when no ordinary work remains (or `Implementation` if ordinary work reopened),
+persists/releases roles through the canonical repository transaction, and emits one event shape
+with nullable `item_id` and `log_id`. Binding coverage settlement returns `next_action: none` on
+completion and creates no final ReviewGate. `planr plan final-review` is a non-binding-plan flow.
+
+Terminal `non_repeatable_one_shot` exhaustion is also zero-or-one item inside the trusted
+attempt/receipt transaction. Attempt/receipt persistence, budget reconciliation, FeatureRun
+cancellation, and verifier release always commit atomically; item failure/logging occurs only when
+one active projection is present, and ready-unleased remains fail-closed.
+
+Post-receipt ProductFinding repair remains distinct from pre-receipt admission repair. The
+application resolves the verification map item as an optional current plan-path projection for
+routing, maker work packets, settlement, idempotent replay, selective-replay handoff, and verifier
+release. Absence performs no item mutation; only a present eligible item is updated. Durable
+ProductRepair settlement persists invalidation/run/maker/selective-obligation/settlement/freeze
+lineage and no item identity. The lifecycle does not reclassify the outcome or create a receipt.
+
+This is a hard cut: run-index v1, first-observation target inference, all-targets-equal checks,
+item-keyed `pick release --repair`, item-required repair, persisted repair-item identity,
+settlement, final-review, and exhaustion ownership, readers, aliases, fallbacks, shims, and runtime
+compatibility do not exist.
+Completed trusted Evidence v1 receipts remain coverage records because coverage is independent of
+run-index orchestration; unexecuted v1 run indexes and in-flight retry lineage lacking the v2
+execution binding are not translated or inferred.
+
 ## Versioning And Compatibility
 
 - `schema_version` for all v1 objects is `evidence.contract.v1`.
@@ -92,7 +183,10 @@ Required fields:
 
 - `id`, `schema_version`, `version`, `adapter_kind`, `adapter_digest`.
 - Supported surfaces, observation type/schema/digest triples, interactions, artifacts, runtime targets, provenance path, permissions, costs, determinism, repeatability, independence, blind spots, and availability probe contract.
-- When a capability explicitly declares `repeatability = non_repeatable_one_shot`, Planr derives `max_attempts = 1`; any conflicting caller declaration is rejected before launch. Before the adapter can spawn, Planr atomically claims one durable allowance scoped to the active FeatureRun source freeze. That claim survives process, receipt, or settlement failure, so every later fresh initial, retry, or concurrent contender for the freeze is rejected without spawning. Its committed non-passing attempt (`attempt_index + 1 = max_attempts`), including `product_failed`, atomically exhausts that FeatureRun verification allowance with the attempt and receipt. Planr records `verification_attempts_exhausted`, releases the verifier lease, exposes no next verification action, and does not create a product-finding repair or replay path. Missing or other repeatability values never infer one-shot behavior.
+- When a capability explicitly declares `repeatability = non_repeatable_one_shot`, Planr derives `max_attempts = 1`; any conflicting caller declaration is rejected before launch. Before the adapter can spawn, Planr atomically claims one durable allowance scoped to the active FeatureRun source freeze. That claim survives process, receipt, or settlement failure, so every later fresh initial, retry, or concurrent contender for the freeze is rejected without spawning. Its committed non-passing attempt (`attempt_index + 1 = max_attempts`), including `product_failed`, atomically exhausts that FeatureRun verification allowance with the attempt and receipt. Planr records `verification_attempts_exhausted`, releases the verifier lease, exposes no next verification action, and does not create a product-finding repair or replay path. A projected verification item is optional: when active it is failed/logged atomically; when absent there is no item/log mutation; when ready but unleased the transaction fails closed. Missing or other repeatability values never infer one-shot behavior.
+- Every other capability also defaults to `max_attempts = 1`. A manifest may explicitly admit a larger bounded value only for a repeatable execution contract. Planr never starts a second attempt merely because a verifier or environment failure was returned; a later execution requires a fresh canonical invocation after the reported external state has materially changed.
+- A fresh canonical invocation may append a superseding admission for the same exact active source freeze only when the previously admitted run-index digest already has both a durable Evidence attempt and receipt. The previous admission and execution history remain immutable. A conflicting admission with no execution receipt is pre-receipt state and remains rejected; it cannot bypass Verification Admission Repair.
+- When source is stale after such a receipt, one canonical broker invocation may perform exactly one observed refresh: invalidate and preserve the old freeze and receipt bindings, release the exact verifier lease, freeze the current source, reacquire verification, and seal again. The broker does not repeat this transition if the replacement source becomes stale.
 - Process adapters declare a closed `availability_probe.kind = process` contract with executable name, arguments, optional working directory, timeout, stdout/stderr byte limits, and the payload schema binding for emitted observations.
 
 A manifest is a claim about what a method can observe. It is not proof that the method is available now.

package/docs/contracts/schemas/com.planr.web.dom_state.v1.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "schema://com.planr.web.dom_state.v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_ref",
+    "selector",
+    "text",
+    "visible"
+  ],
+  "properties": {
+    "schema_ref": {
+      "const": "schema://com.planr.web.dom_state.v1"
+    },
+    "selector": {
+      "type": "string",
+      "minLength": 1
+    },
+    "text": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "visible": {
+      "type": "boolean"
+    }
+  }
+}

package/docs/fixtures/mcp-contract.json

@@ -35,6 +35,7 @@
     "planr_pick_stale",
     "planr_run_restart",
     "planr_run_resolve_budget_hold",
+    "planr_run_repair_verification_admission",
     "planr_recover_sweep",
     "planr_approval_request",
     "planr_approval_approve",
@@ -54,11 +55,12 @@
     "planr_evidence_capability_show",
     "planr_evidence_run",
     "planr_evidence_import",
+    "planr_evidence_host_capture_admit",
     "planr_evidence_host_capture_import",
-    "planr_evidence_host_capture_run",
     "planr_evidence_attempts",
     "planr_evidence_receipts",
     "planr_evidence_coverage",
+    "planr_evidence_verify",
     "planr_evidence_explain",
     "planr_evidence_readiness",
     "planr_evidence_recover_settlement",
@@ -75,6 +77,7 @@
     "planr_review_ingest",
     "planr_review_evidence",
     "planr_review_gate_close",
+    "planr_review_gate_release",
     "planr_review_findings_resolve",
     "planr_close_item",
     "planr_context_create",

package/npm/bin/native-launcher.js

@@ -0,0 +1,67 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(here, "..", "..");
+
+function platformTarget() {
+  const osName = { darwin: "darwin", linux: "linux" }[os.platform()];
+  const arch = { arm64: "arm64", x64: "x86_64" }[os.arch()];
+  if (!osName || !arch) return null;
+  return `${osName}-${arch}`;
+}
+
+function repositoryBuildCandidates(binaryName) {
+  if (!fs.existsSync(path.join(packageRoot, "Cargo.toml"))) return [];
+  const metadata = spawnSync(
+    "cargo",
+    ["metadata", "--no-deps", "--format-version", "1"],
+    { cwd: packageRoot, encoding: "utf8" },
+  );
+  if (metadata.status !== 0) return [];
+  try {
+    const targetDirectory = JSON.parse(metadata.stdout).target_directory;
+    if (typeof targetDirectory !== "string" || targetDirectory.length === 0) return [];
+    return [
+      path.join(targetDirectory, "release", binaryName),
+      path.join(targetDirectory, "debug", binaryName),
+    ];
+  } catch {
+    return [];
+  }
+}
+
+export function runNative({ binaryName, overrideEnvironment, productName }) {
+  const target = platformTarget();
+  const packagedCandidates = [
+    process.env[overrideEnvironment],
+    target && path.join(here, "..", "native", target, binaryName),
+  ].filter(Boolean);
+  const binary = packagedCandidates.find(candidate => fs.existsSync(candidate))
+    ?? repositoryBuildCandidates(binaryName).find(candidate => fs.existsSync(candidate));
+
+  if (!binary) {
+    if (!target) {
+      console.error(`${productName} has no native binary for ${os.platform()}-${os.arch()}.`);
+      console.error("Supported platforms: darwin-arm64, darwin-x86_64, linux-x86_64, linux-arm64.");
+    } else {
+      console.error(`${productName} native binary was not found.`);
+      console.error(`Build it with: cargo build --release --bin ${binaryName}`);
+      console.error(`Or set ${overrideEnvironment}=/absolute/path/to/${binaryName}`);
+    }
+    process.exit(127);
+  }
+
+  const result = spawnSync(binary, process.argv.slice(2), {
+    stdio: "inherit",
+    env: process.env,
+  });
+  if (result.error) {
+    console.error(result.error.message);
+    process.exit(1);
+  }
+  process.exit(result.status ?? 0);
+}

package/npm/bin/planr-browser-harness-adapter.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { runNative } from "./native-launcher.js";
+
+runNative({
+  binaryName: "planr-browser-harness-adapter",
+  overrideEnvironment: "PLANR_BROWSER_HARNESS_ADAPTER_BIN",
+  productName: "Planr Browser Harness adapter",
+});

package/npm/bin/planr.js

@@ -1,54 +1,8 @@
 #!/usr/bin/env node
-import { spawnSync } from "node:child_process";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { runNative } from "./native-launcher.js";
 
-const here = path.dirname(fileURLToPath(import.meta.url));
-const packageRoot = path.resolve(here, "..", "..");
-
-function platformTarget() {
-  const osName = { darwin: "darwin", linux: "linux" }[os.platform()];
-  const arch = { arm64: "arm64", x64: "x86_64" }[os.arch()];
-  if (!osName || !arch) {
-    return null;
-  }
-  return `${osName}-${arch}`;
-}
-
-const target = platformTarget();
-const candidates = [
-  process.env.PLANR_NATIVE_BIN,
-  // Published package: per-platform binaries bundled at release time.
-  target && path.join(here, "..", "native", target, "planr"),
-  // Repository checkout: local cargo builds.
-  path.join(packageRoot, "target", "release", "planr"),
-  path.join(packageRoot, "target", "debug", "planr"),
-].filter(Boolean);
-
-const binary = candidates.find(candidate => fs.existsSync(candidate));
-
-if (!binary) {
-  if (!target) {
-    console.error(`Planr has no native binary for ${os.platform()}-${os.arch()}.`);
-    console.error("Supported platforms: darwin-arm64, darwin-x86_64, linux-x86_64, linux-arm64.");
-  } else {
-    console.error("Planr native binary was not found.");
-    console.error("Build it with: cargo build --release");
-    console.error("Or set PLANR_NATIVE_BIN=/absolute/path/to/planr");
-  }
-  process.exit(127);
-}
-
-const result = spawnSync(binary, process.argv.slice(2), {
-  stdio: "inherit",
-  env: process.env,
+runNative({
+  binaryName: "planr",
+  overrideEnvironment: "PLANR_NATIVE_BIN",
+  productName: "Planr",
 });
-
-if (result.error) {
-  console.error(result.error.message);
-  process.exit(1);
-}
-
-process.exit(result.status ?? 0);