feat(runtime): pin published gentle-ai v4.0.0

docs/gentle-shell.md

@@ -15,7 +15,7 @@ The [v2.6.0 release](https://github.com/Gentleman-Programming/gentle-pi/releases
 - The Agents List and Details views preserve the orchestrator/session hierarchy and completion, abort, and lost-exit history. Parent-child queries and notifications have an explicit handoff path, while model, effort, and usage stay observable per task.
 - Named `/gentle:profiles` atomically route the orchestrator separately from packaged and review roles; see the [technical reference](readme-reference.md#agent-model-profiles) for the profile model.
 
-The source checkout prepares `gentle-pi` `3.7.0` with a package-local Gentle AI `v3.7.0` pin; this does not imply that the package release has been published.
+The source checkout prepares `gentle-pi` `3.7.0` with a package-local Gentle AI `v4.0.0` pin; this does not imply that the package release has been published.
 
 ## Shell interactions and runtime behavior
 

docs/readme-reference.md

@@ -114,7 +114,7 @@ This is guidance through existing tools, not a new CLI, phase, state engine, or
 | **Skill creation workflow**    | Provides the `gentle-ai-skill-creator`/`gentle-ai-skill-improver` skills, `/skill-creation` prompt, and packaged style guide for LLM-first skills. |
 | **Delivery skills**            | Includes issue-first PRs, chained PRs, work-unit commits, cognitive docs, comment writing, and Judgment Day review.                           |
 | **Bounded native review**      | Freezes one candidate, dispatches only controller-selected lenses, and records native authority. Review outcomes are informational; delivery follows ordinary repository policy. |
-| **Verified native runtime**    | The current source checkout provisions the exact package-local Gentle AI v3.7.0 runtime: signed, SHA-256-pinned release archives on Darwin/Linux and a Go SumDB-verified source build on Windows x64/arm64. It validates package-local integrity and rejects PATH, global, sibling, symlink, and mode fallbacks. |
+| **Verified native runtime**    | The current source checkout provisions the exact package-local Gentle AI v4.0.0 runtime: signed, SHA-256-pinned release archives on Darwin/Linux and a Go SumDB-verified source build on Windows x64/arm64. It validates package-local integrity and rejects PATH, global, sibling, symlink, and mode fallbacks. |
 | **Runtime safety**             | Blocks destructive shell commands, asks for confirmation for sensitive operations, and blocks direct read/write/edit access to sensitive paths. |
 
 ## Native pointer regions
@@ -171,7 +171,7 @@ This installs the current npm release; select an explicit version if you need a
 
 ### Source checkout
 
-This checkout declares `gentle-pi` `3.7.0` with a package-local Gentle AI `v3.7.0` pin. Checkout metadata alone is not proof of npm publication; verify the registry version and its release workflow.
+This checkout declares `gentle-pi` `3.7.0` with a package-local Gentle AI `v4.0.0` pin. Checkout metadata alone is not proof of npm publication; verify the registry version and its release workflow.
 
 ### Pi compatibility
 
@@ -198,7 +198,7 @@ pi install npm:gentle-pi@3.5.1
 
 RDD remains opt-in. Enable it only through an explicit user decision with `/gentle:review-mode enable`; `status` lets you inspect the mode without changing it. The `.git/gentle-ai/candidate-views` parent must sit on a filesystem that honors private POSIX modes (or equivalent Windows ACLs); WSL DrvFS mounts without metadata can reject START before lineage creation.
 
-The source checkout's RDD integration installs Gentle AI only into its private `.gentle-ai/` directory. Darwin and Linux use pinned release assets with asset and executable SHA-256 verification (signed archives for source pin `v3.7.0`; raw prerelease binaries only under a prerelease pin). Windows x64 and arm64 build the exact `v3.7.0` source tag with a local Go 1.25.10+ toolchain, a sealed Go environment, `GOTOOLCHAIN=local`, and `GOSUMDB=sum.golang.org`; it does not download Go automatically. Windows provenance is Go-toolchain plus SumDB evidence and postinstall tamper detection, **not** Authenticode or protection against a malicious joint binary-and-manifest replacement. Package-private locks coordinate cooperative concurrent or crashed installers; their tombstones fail closed. A malicious same-user process with write access to package-private `node_modules` is outside that protocol because it can already replace package code, binary, or manifest, and portable Node has no pathname-delete CAS. It never uses `PATH` or a global `gentle-ai` installation. For development or offline installs only, set `GENTLE_PI_SKIP_GENTLE_AI_INSTALL=1`; native review operations then fail closed with an actionable `package-local-binary-missing` error. To recover explicitly, if `GENTLE_PI_SKIP_GENTLE_AI_INSTALL` is set, remove or unset it before changing to the installed `gentle-pi` package directory. Then run `node scripts/install-gentle-ai.mjs`. This invokes the package-owned installer without relying on a global binary or npm configuration change. A missing binary can result from skipped lifecycle scripts, but does not prove that lifecycle scripts were disabled.
+The source checkout's RDD integration installs Gentle AI only into its private `.gentle-ai/` directory. Darwin and Linux use pinned release assets with asset and executable SHA-256 verification (signed archives for source pin `v4.0.0`; raw prerelease binaries only under a prerelease pin). Windows x64 and arm64 build the exact `v4.0.0` source tag with a local Go 1.25.10+ toolchain, a sealed Go environment, `GOTOOLCHAIN=local`, and `GOSUMDB=sum.golang.org`; it does not download Go automatically. Windows provenance is Go-toolchain plus SumDB evidence and postinstall tamper detection, **not** Authenticode or protection against a malicious joint binary-and-manifest replacement. Package-private locks coordinate cooperative concurrent or crashed installers; their tombstones fail closed. A malicious same-user process with write access to package-private `node_modules` is outside that protocol because it can already replace package code, binary, or manifest, and portable Node has no pathname-delete CAS. It never uses `PATH` or a global `gentle-ai` installation. For development or offline installs only, set `GENTLE_PI_SKIP_GENTLE_AI_INSTALL=1`; native review operations then fail closed with an actionable `package-local-binary-missing` error. To recover explicitly, if `GENTLE_PI_SKIP_GENTLE_AI_INSTALL` is set, remove or unset it before changing to the installed `gentle-pi` package directory. Then run `node scripts/install-gentle-ai.mjs`. This invokes the package-owned installer without relying on a global binary or npm configuration change. A missing binary can result from skipped lifecycle scripts, but does not prove that lifecycle scripts were disabled.
 
 Recommended companion packages, into the standalone `gentle-shell` home:
 
@@ -517,7 +517,7 @@ flowchart TD
 
 VALIDATE is informational. Commit, push, PR, and release commands follow ordinary repository policy; RDD never authorizes, rewrites, consumes review state for, or blocks them. Dangerous-command safety and destructive-review consent remain independent.
 
-For the source checkout, native contract pairing is exact: this adapter resolves only the integrity-verified package-local Gentle AI v3.7.0 executable, independently hashes it, then negotiates `gentle-ai.review-integration/v2` outside the repository. Capabilities are cached by that executable digest. Every START, target status, FINALIZE, and validate request passes the same contract identifier. Negotiated envelopes decode exactly against the vendored schemas; `recover` routes only the provider-selected `action_disposition`, and optional additions require a future compatible schema/minor that the provider explicitly advertises and the consumer negotiates.
+For the source checkout, native contract pairing is exact: this adapter resolves only the integrity-verified package-local Gentle AI v4.0.0 executable, independently hashes it, then negotiates `gentle-ai.review-integration/v2` outside the repository. Capabilities are cached by that executable digest. Every START, target status, FINALIZE, and validate request passes the same contract identifier. Negotiated envelopes decode exactly against the vendored schemas; `recover` routes only the provider-selected `action_disposition`, and optional additions require a future compatible schema/minor that the provider explicitly advertises and the consumer negotiates.
 
 Contract `/v2` replaces the Base64 `candidate_diff` reviewer transport of `/v1` with immutable `base_tree`/`candidate_tree` plus an ordered `changed_path_manifest` and never an inline patch. `gentle-pi` negotiates `/v2` only, with no dual-lane fallback; the cutover landed as one atomic commit against gentle-ai v2.2.2 (tracked by the `migrate-review-integration-v2` change), and the `/v1` schemas stay packaged because the `/v2` schemas `$ref` into their fragments. This provider contract version is unrelated to Pi's own internal "compact-v2" review-authority naming used below — the shared digit is coincidental, not a version pairing.
 
@@ -527,7 +527,7 @@ Candidate views materialize tracked Git symlinks from their frozen blobs even wh
 
 On POSIX, if START rejects a group- or world-accessible `.git/gentle-ai/candidate-views` parent, Pi reports `candidate-owner-parent-privacy` before native START. When a sanitized probe shows the filesystem cannot represent private POSIX modes (for example WSL DrvFS mounts without `metadata`), Pi instead reports `candidate-owner-parent-chmod-ineffective` with guidance to move the Git common directory to a POSIX-metadata filesystem or enable metadata support. Inspect that parent's ownership and permissions and correct them out of band before retrying; Pi does not change them automatically. Other owner-preparation failures retain a generic diagnostic rather than exposing filesystem errors.
 
-Once the source checkout's pinned gentle-ai runtime (currently v3.7.0) has written review authority, rollback MUST preserve every native store and receipt and MUST NOT run a downgraded binary against that repository. Disable the Pi route or roll forward to a compatible authority-aware release instead; deleting authority data or reinstalling an older binary is not a rollback path.
+Once the source checkout's pinned gentle-ai runtime (currently v4.0.0) has written review authority, rollback MUST preserve every native store and receipt and MUST NOT run a downgraded binary against that repository. Disable the Pi route or roll forward to a compatible authority-aware release instead; deleting authority data or reinstalling an older binary is not a rollback path.
 
 ### FINALIZE wrapper input
 

lib/native-review-cli.ts

@@ -1027,6 +1027,13 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// 547b68e172cc87aa297309d61624e5fc2c24d407a494b53eeb5a2b053904352c
 	// at contract 1.2.0. No new negotiated capability is asserted.
 	"3.7.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// v4.0.0 repeats 3.7.0: the published provider-contract tar remains SHA-256
+	// 547b68e172cc87aa297309d61624e5fc2c24d407a494b53eeb5a2b053904352c
+	// at contract 1.2.0, and the published binary still advertises
+	// capabilities/v2.6 under review-integration/v2. The Go module path moved
+	// to /v4 without a review-integration/v2 change. No new negotiated
+	// capability is asserted.
+	"4.0.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
 });
 
 export interface NativeReviewProcessDiagnostics {

lib/review-risk-assessment.ts

@@ -13,7 +13,7 @@
 // gentle-pi#1175: the native v2 `assess.schema.json` requires only `code` on a
 // reason (`path`/`detail` are optional) and adds `candidate.consumed`,
 // `review_due`, `review_due_reason`, and an opaque `next_transition`. Older
-// binaries (for example the pinned gentle-ai v3.7.0) predate those fields, so
+// binaries (for example gentle-ai v3.7.0) predate those fields, so
 // they decode as optional and stay absent rather than being defaulted.
 // A non-zero exit or a failure envelope means the candidate could not be
 // assessed; hosts treat that as `high`. Older binaries without the verb (or

odd/tasks/pin-gentle-ai-4.0.0-release.md

@@ -0,0 +1,35 @@
+# Pin Gentle AI v4.0.0 and release Gentle Shell
+
+Repository-relative locator: `odd/tasks/pin-gentle-ai-4.0.0-release.md`.
+
+## Objective and rationale
+Release Gentle Shell with the newly published Gentle AI v4.0.0 instead of its v3.7.0 pin, shipping the merged Pi 1.0.0 support (#1642). Approved issue: https://github.com/Gentleman-Programming/gentle-shell/issues/1643. Upstream: https://github.com/Gentleman-Programming/gentle-ai/releases/tag/v4.0.0.
+
+## Scope and constraints
+- Branch `feat/pin-gentle-ai-4.0.0`, starting from `main` `afb45498`.
+- Authorized: GitHub repositories Gentleman-Programming/gentle-ai (reads) and Gentleman-Programming/gentle-shell (issue, PR, merge, tag, release, `publish.yml`) through the configured `gh` CLI session over HTTPS. No ambient SSH, no local npm publication, no retagging.
+- Pin only published signed v4.0.0 assets and the SumDB Windows source; regenerate derived runtime modules, never hand-edit generated files.
+- Delivery: ask-on-risk. Forecast 200–300 authored lines for T1 (generated runtime excluded); single PR expected.
+
+## Verified upstream evidence (parent)
+- `checksums.txt` verifies all four archives and the provider contract tarball.
+- Archive SHA-256: darwin_amd64 `b5b74f22b38ec3339b38e8c68f797dc76ff12ed6580826a6e425d5c718da80c1`, darwin_arm64 `d2159caf6d68f367b18830ece6af71ef26963d5f5320d7df6a794773f45cc7e9`, linux_amd64 `5f4417cf29c969c86da4799942fd673368840901be1bb09c779a12d7ed6096ea`, linux_arm64 `1383b040c95cfc69206660d73c21907b14ad70ab913f410917c54f43d3147e57`.
+- Extracted `gentle-ai` binary SHA-256: darwin_amd64 `d4a5b16ff70e65331e17a62356941bb0c75ecb9dbe3a0d98a6b54cfbd76cd6b0`, darwin_arm64 `18a9f7fae55d85c95684b6d512a4a148d0cb24a856325f72573c34caf65159eb`, linux_amd64 `50ba217b5138c1a9c7d5bf2f79931b1bb89b89c4cf650dcd7ee037657c88158d`, linux_arm64 `6703704f0c4a5b70c36fbdc44db641e810871cab16bc28040d06aa1d10704ad3`.
+- Windows source: `go mod download -json github.com/gentleman-programming/gentle-ai/v4@v4.0.0` (GOSUMDB=sum.golang.org) → Sum `h1:pZ/XZ2Pk3U9lgXigOTY62zlxxFOHnc9CjQhLgaV/Hfc=`, tag commit `ff77164d4f56f1665b22fb6fac51c2ccbb769400`; `go.mod` declares `github.com/gentleman-programming/gentle-ai/v4`.
+- Published linux_amd64 binary reports `gentle-ai 4.0.0`; `review capabilities` returns contract `gentle-ai.review-integration/v2`, schema `capabilities/v2.6` → no new capability identity.
+- Provider contract tarball `gentle-ai-review-provider-contract-1.2.0.tar.gz` SHA-256 `547b68e172cc87aa297309d61624e5fc2c24d407a494b53eeb5a2b053904352c` (unchanged from 3.7.0).
+- Contract diff v3.7.0..v4.0.0: review-integration v2 unchanged; v1 recover fixtures drop four fields; sdd-integration consent schema/fixture removed; telemetry adds `conductor` agent.
+
+## Tasks
+- [ ] T1 — Pin published Gentle AI v4.0.0: installer version, archive/binary digests, Windows `/v4` module path + SumDB checksum, `NATIVE_CLI_CONTRACTS` 4.0.0 row, `/v4` paths in the ODD routing mirror script, regenerated runtime, pin-specific tests and docs. Route: delegated writer (multi-file write + preparation triggers). Risk: high (installer/process boundary) → writer self-checks + independent verifier. Acceptance: RED/GREEN observed; `pnpm test`, `check:runtime-modules`, `verify-package-files`, packed runner against real assets pass; work-unit commit.
+- [ ] T2 — PR linked to #1643, merge after required checks, bump package version, tag from exact `main`, GitHub release with canonical notes, `publish.yml` from `main`, verify npm. Route: release coordination.
+
+## Progress
+- Issue #1643 created with `enhancement`, `type:chore`, `status:approved` (read back).
+- Release version decided by the user: gentle-pi 4.0.0 (mirrors the pinned Gentle AI major.minor, as 3.7.0 did).
+- T1 delegated to one writer (route: delegated; multi-file write + preparation triggers). Writer completed: RED `published Gentle AI v4.0.0 is the installer pin` failed (`3.7.0` vs `4.0.0`), GREEN 1/1; focused 5 files 219 pass / 0 fail / 7 skip; `pnpm test` 4570 / 4526 pass / 0 fail / 44 skip (10 extra skips gate on a local `.gentle-ai/v4.0.0` binary not yet installed); runtime modules regenerated and match (8); `verify-package-files` passed (69 byte-pinned contracts); packed runner passed against real published v4.0.0 assets (gentle-pi 3.7.0 + Gentle AI 4.0.0); typecheck 187 / no regressions; diff check clean. 14 files +112/−88 incl. 2 generated runtime modules.
+- Parent spot check: every archive/binary digest, SumDB Sum, tag commit and `/v4` module path appears exactly once in the installer; no `/v3` literal remains outside a historical comment; installer + contract tests 68/68 pass.
+- Risk: high (installer/process boundary) → independent verifier runs after the T1 commit, including the local v4.0.0 binary install to remove the gated skips.
+
+## Next step
+Delegate T1.

runtime/native-review-cli.mjs

@@ -1028,6 +1028,13 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// 547b68e172cc87aa297309d61624e5fc2c24d407a494b53eeb5a2b053904352c
 	// at contract 1.2.0. No new negotiated capability is asserted.
 	"3.7.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// v4.0.0 repeats 3.7.0: the published provider-contract tar remains SHA-256
+	// 547b68e172cc87aa297309d61624e5fc2c24d407a494b53eeb5a2b053904352c
+	// at contract 1.2.0, and the published binary still advertises
+	// capabilities/v2.6 under review-integration/v2. The Go module path moved
+	// to /v4 without a review-integration/v2 change. No new negotiated
+	// capability is asserted.
+	"4.0.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
 });
 
 

runtime/review-risk-assessment.mjs

@@ -14,7 +14,7 @@
 // gentle-pi#1175: the native v2 `assess.schema.json` requires only `code` on a
 // reason (`path`/`detail` are optional) and adds `candidate.consumed`,
 // `review_due`, `review_due_reason`, and an opaque `next_transition`. Older
-// binaries (for example the pinned gentle-ai v3.7.0) predate those fields, so
+// binaries (for example gentle-ai v3.7.0) predate those fields, so
 // they decode as optional and stay absent rather than being defaulted.
 // A non-zero exit or a failure envelope means the candidate could not be
 // assessed; hosts treat that as `high`. Older binaries without the verb (or