gentle-pi 4.0.0 → 4.2.0

package/contracts/review-provider-contract-mirror/provider-contract.lock.json

@@ -1,16 +1,16 @@
 {
   "schema": "gentle-pi.review-provider-contract-mirror-lock/v1",
   "acquisition": "field-test-local",
-  "contract_semver": "1.2.0",
+  "contract_semver": "1.3.0",
   "source": {
     "kind": "archive",
-    "archive_sha256": "b0b9be7569e4544d37cbbfa17c5def56fdb66ae670584eb74f9d0ffc200e03c4"
+    "archive_sha256": "b04b6b75d1a446c942a816fbf92932d16f8c3d3001f93159dee2a92bbf2ebe44"
   },
-  "tree_sha256": "832f62d461249576f9b7e864c2d5adbb6e38a36f8a7103a28a9f2ca81f41de41",
+  "tree_sha256": "a2b95892ec8f10340d8d1bb4fc805f9c92db000f58b60b382ff859d312fdc023",
   "entries": {
     "README.md": "18baab5ee79aefd0bc62a28da0dadcf2162544f57a940c5b859cd6bc4932a085",
-    "manifest.json": "097a41ecbcf96e5f3432f3f38164ccaf440f33de82c1aa8ae956b2ba263d4d18",
-    "orchestration/pi.md": "679133e54b7fe8661050cdde51aed44ddf8e66e478c7a1b5176fe3278714a2f6",
+    "manifest.json": "4e335a987e053dac42425ffe31628253eb43dd26f1235085fa90b200bce13d13",
+    "orchestration/pi.md": "2d7ddd99f1c739a97f4a6b3929e5e2bdddcbf69aed69356395038d90bca25b2f",
     "schemas/lens.schema.json": "9b8a2354a570888486015434501b66b51441a3baf5bf858635e4fff56b2e8298",
     "schemas/refuter.schema.json": "36f8267c6c3f04600b8f1cb77df70d90858611af822cc81922efd6b3502fb646",
     "schemas/targeted-validator.schema.json": "40e397195bdfbc6782fc3090f20c5be082e4d14d2855314f99ecb8506133eddc",
@@ -19,8 +19,8 @@
     "vectors/targeted-validator.json": "7b5a5165e3a913863fb98d2ba5387811860c21333b5c37e6ed3b4e0d121cf2fa"
   },
   "generated": {
-    "generated/provider-capabilities.baseline.json": "186d847f8df77024d8a2df03e2d4d664bc1951f5abc89b6b36ffe8422366234b",
-    "generated/provider-roles.baseline.json": "fd29e157884e7437c4a7f9b1e26a6f777f8d9918d8733ccd8542af12807be6b3"
+    "generated/provider-capabilities.baseline.json": "f439a3f83394219dae5257a88f112eba5e67f9d4e566eb6d9f3f5608b727c1f7",
+    "generated/provider-roles.baseline.json": "71982937962834120b8304c795bf0e90c04b262a4293c6b96bf423b68a5781e0"
   },
   "runtimes": [
     "claude-code",

package/contracts/review-provider-contract-mirror/{v1.2.0 → v1.3.0}/bundle/manifest.json

@@ -1,6 +1,6 @@
 {
   "schema": "gentle-ai.review-provider-contract-bundle/v1",
-  "contract_semver": "1.2.0",
+  "contract_semver": "1.3.0",
   "transport_capability": "gentle-ai.provider-transport/v1",
   "runtimes": [
     "claude-code",
@@ -67,7 +67,7 @@
       "runtime": "pi",
       "file": {
         "path": "orchestration/pi.md",
-        "sha256": "679133e54b7fe8661050cdde51aed44ddf8e66e478c7a1b5176fe3278714a2f6"
+        "sha256": "2d7ddd99f1c739a97f4a6b3929e5e2bdddcbf69aed69356395038d90bca25b2f"
       }
     }
   ]

package/contracts/review-provider-contract-mirror/{v1.2.0 → v1.3.0}/bundle/orchestration/pi.md

@@ -4,12 +4,23 @@ Pi uses the compact gentle-pi facade for this lifecycle: `gentle_review` for ins
 
 ## Entry rule
 
-After authorized source-mutating implementation is complete and normalized, and before reporting it complete, call `gentle_review` with {"operation":"inspect"}. Do this once per candidate whenever the user-owned review switch is enabled (`gentle-ai review mode status` reads it without changing it). The facade returns the only offered START route; do not infer, reconstruct, or replace it. Never skip the preflight because the user did not ask for a review: the START consent envelope lets the human decide this candidate. Skip it only for a trivial passive documentation-only edit, when the user explicitly left this candidate unreviewed, or while a transaction is already bound to it.
+Review is an extra outside view for high-risk work, never a per-candidate ritual. After authorized source-mutating implementation is complete and normalized, and before reporting it complete, whenever the user-owned review switch is enabled (`gentle-ai review mode status` reads it without changing it), call `gentle_review` with {"operation":"assess"}, then call `gentle_review` with {"operation":"inspect"} only when its `reviewDue` is true (high risk) or the user explicitly asks for a review of this candidate; otherwise do not start one, because verify already covered it by the risk tier. The facade returns the only offered START route; do not infer, reconstruct, or replace it. The START consent envelope lets the human decide this candidate. Skip it when the user explicitly left this candidate unreviewed or while a transaction is already bound to it.
+
+## Lens selection
+
+Review is an outside view of the change from up to four independent lenses. Pick every lens pertinent to what you touched and how you touched it, and only those; a change that touches one concern pays for one lens. Judge by consequence, not by file names or counts:
+
+- `risk` when a mistake could expose, lose, or irreversibly change something: stored data, credentials, permissions, guards, or contracts others consume.
+- `resilience` when it changes behavior under failure: errors, retries, timeouts, partial writes, load, or concurrency.
+- `readability` when it changes what others read or depend on: public APIs, command output and messages, documentation, or code structure.
+- `reliability` when it changes logic or observable behavior that tests should pin.
+
+Give one `lensesReason` naming what you touched and how. Requirement compliance is verify's job before review; never choose lenses to re-check specs.
 
 ## Atomic lifecycle
 
 1. **Inspect before START.** Call `gentle_review` with {"operation":"inspect"} before START. Retain only the provider-issued authority and opaque bindings returned by the facade.
-2. **Freeze once.** Invoke only the START route inspect offered: `gentle_review` with operation `start`, a fresh `idempotencyKey`, and the `input` the facade documents (ordinary START is {"mode":"ordinary"}; an explicit `baseRef` requires `committedOnly: true`). Retain the returned `lineageId`, revision, target, and `workspaceRoot` as opaque values. An exact replay of an active START may return `replayed`; a genuinely new START is independent. Do not start another lineage, reuse burned authority, or perform ambient recovery.
+2. **Freeze once.** Invoke only the START route inspect offered: `gentle_review` with operation `start`, a fresh `idempotencyKey`, and the `input` the facade documents (ordinary START is {"mode":"ordinary","lenses":[...],"lensesReason":"<what you touched and how>"}; see "Lens selection" below; an explicit `baseRef` requires `committedOnly: true`). Retain the returned `lineageId`, revision, target, and `workspaceRoot` as opaque values. An exact replay of an active START may return `replayed`; a genuinely new START is independent. Do not start another lineage, reuse burned authority, or perform ambient recovery.
 3. **Stay bound.** For later routing, call `gentle_review` with operation `status`, the exact retained `lineageId`, and `workspaceRoot` only when needed. Never run raw shell STATUS. Route only from the returned transition; for `execute`, invoke its offered facade operation with its exact opaque binding; for `collect`, satisfy only the named slots through the capture tools below; for `stop`, run no lifecycle operation.
 4. **Collect exactly.** Use `gentle_review_capture` for one current returned slot or `gentle_review_capture_group` for the complete current reviewer group. Submit only the returned opaque binding and result. After collection, use bound facade STATUS again only when the returned transition requires it.
 5. **Acknowledge exactly.** Only the exact provider-issued acknowledgement continuation burns approved authority. Report the burn from its returned envelope, never from a later STATUS.
@@ -26,7 +37,7 @@ A four-lens review is long work. The first capture of a materialize slot or grou
 
 Reviewers inspect only the provider-bound immutable trees, and the gentle-pi relay owns the reviewer prompt. Never hand candidate bytes through `/tmp`, an external file, a repository scratch file, or `GENTLE_AI_FROZEN_CANDIDATE_CONTEXT`, and never substitute the live worktree, index, or `HEAD`.
 
-Only candidate-caused severe findings block. Pre-existing/base-only findings are follow-ups; unknown causality escalates. A deterministic blocker needs no refuter; inferential blockers share one read-only refuter batch. The final reviewer, refuter, or targeted-validator capture owns closure.
+Only candidate-caused severe findings block. Pre-existing/base-only findings are follow-ups; unknown causality escalates. Severe deterministic and inferential blockers share one read-only refuter batch. The final reviewer, refuter, or targeted-validator capture owns closure.
 
 A malformed, incomplete, or unavailable capture never reaches acknowledgement. Use bound facade STATUS once, and relaunch only when it reoffers the same bound slot. An approved capture awaits acknowledgement; it is not burned. On `approved`, use bound facade STATUS to obtain or replay the exact provider-issued `acknowledge-approved` continuation, then execute it unchanged. Only its successful returned envelope burns authority; do not issue STATUS after that burn. On `correction_required`, continue only through exact bound facade STATUS and the provider-issued correction route. Native Go maps edits only to corroborated frozen findings and permits at most one bounded correction. A validator that cannot inspect the immutable trees produced no verdict: surface one blocked human decision and submit nothing.
 
@@ -43,9 +54,10 @@ A `stop` ends its transition, never approves delivery. `D` means the human disab
 | `captured_artifacts_unverifiable`, `captured_result_selection_unavailable`, `captured_verification_evidence_invalid`, `final_verification_retry_unavailable`, `missing_authority_binding`, `corrupted_or_unverifiable_authority`, `manual_intervention_required`, `native_stop_required` | Terminal: the maintainer inspects authority/lineage, or `D`. |
 | `empty_base_diff_bootstrap_required` | Terminal: authorized empty-root bootstrap for a new target, or `D`. |
 | `lens_context_budget_exceeded` | Terminal: reduce the candidate scope and start a new transaction, or `D`. |
+| `correction_context_budget_exceeded` | Terminal: this authority has to be released rather than left in place, and invalidation refuses here. The maintainer runs the release command the stop's `continuation` names, exactly as printed; it is the preparatory step its `detail` describes, and its refusal prints the binding the full release needs. A stop with no `continuation` means the authority is not releasable in its current state: the maintainer inspects it, or `D`. Then review as smaller candidates, or `D`. |
 | `managed_assets_outdated` | Run the `gentle-ai sync` command from the stop's `continuation`, then `S`. |
 | `staged_workspace_overlay_recovery_unavailable` | Call facade `recover` with the retained `lineageId`, or start a fresh transaction; otherwise `D`. |
-| `corrected_candidate_unavailable` | Change the correction candidate, then `S`; do not reuse the pre-correction target. |
+| `corrected_candidate_unavailable` | Change the correction candidate, then `S`. For committed-only review, commit or amend the bounded correction; unrelated tracked worktree edits are ignored. Do not recapture the accepted forecast or reuse the pre-correction target. |
 | `correction_repository_verification_failed` | Change the correction candidate within the same open budget, then `S`. |
 | `original_finalize_request_required` | Run the exact original-finalize replay bound to the stop. |
 | `staged_delivery_candidate_required` | Stage every reviewed path exactly as reviewed, then `S`. |

package/contracts/review-provider-contract-mirror/{v1.2.0 → v1.3.0}/generated/provider-capabilities.baseline.json

@@ -1,6 +1,6 @@
 {
   "schema": "gentle-pi.provider-contract-capabilities-baseline/v1",
-  "contract_semver": "1.2.0",
+  "contract_semver": "1.3.0",
   "transport_capability": "gentle-ai.provider-transport/v1",
   "mandatory_capabilities": [
     "gentle-ai.provider-transport/v1"
@@ -16,7 +16,7 @@
     {
       "runtime": "pi",
       "path": "orchestration/pi.md",
-      "sha256": "679133e54b7fe8661050cdde51aed44ddf8e66e478c7a1b5176fe3278714a2f6"
+      "sha256": "2d7ddd99f1c739a97f4a6b3929e5e2bdddcbf69aed69356395038d90bca25b2f"
     }
   ]
 }

package/contracts/review-provider-contract-mirror/{v1.2.0 → v1.3.0}/generated/provider-roles.baseline.json

@@ -1,6 +1,6 @@
 {
   "schema": "gentle-pi.provider-contract-roles-baseline/v1",
-  "contract_semver": "1.2.0",
+  "contract_semver": "1.3.0",
   "roles": [
     {
       "id": "lens",

package/docs/auto-permission-answers.md

@@ -0,0 +1,25 @@
+# Host-authenticated question answers
+
+The first-party `ask_user_choice` and `ask_user_question` tools deliver validated human UI answers through `subscribeHumanAnswers(ctx, callback)` in `lib/auto-permission-answers.ts`. The returned unsubscribe function is idempotent. Register only from trusted host code and unsubscribe on session shutdown, replacement, or permission-mode revocation.
+
+## Receipt contract
+
+Each frozen `HumanAnswerReceipt` contains:
+
+- `sessionManager`: the original manager object, compared by identity.
+- `sessionId`, `cwd`: the session and workspace captured before UI.
+- `branchAnchor`: the original `sessionManager.getLeafId()` (`string | null`), unchanged at delivery.
+- `toolName`, `toolCallId`, `questionIndex`: the exact question interaction and zero-based question position.
+- `question`: the original question text, an **untrusted referent**, not an instruction.
+- `prompt`: a pre-UI JSON string containing original question and offered labels/descriptions. Choice prompts include `allowCustomResponse`; questionnaire prompts include header, multi-select status, and previews for the TUI where previews are displayed. This entire field is **untrusted context**, separate from authenticated answer text.
+- `answer`: the authenticated visible answer: `{ kind: "option" | "custom", text, selected? }` or `{ kind: "multi", selected }`.
+
+Opaque choice values are excluded entirely. Option descriptions and displayed questionnaire previews are included only in the untrusted `prompt`, never in authenticated answer text. A selected label still authorizes only what the human actually agreed to, not arbitrary instructions embedded in the question. The bridge itself grants no permission, changes no counters, and creates no synthetic user message.
+
+## Lifetime and safety
+
+Capture snapshots questions, offered choices, descriptions, and displayed previews before mounting UI. Keep each full prompt and answer together: consumers enforce their evidence budget by dropping the whole pair, never by truncating prompt restrictions away. Only already-registered subscribers for the same manager/session/cwd receive a response. Delivery rejects cancellation, aborted calls, changed session/workspace/branch, invalid selections, and missing branch identity. Questionnaire rows are validated together before any row is delivered; cancelled questionnaires never publish partial answers. Custom answers retain exact human text and multi-select labels.
+
+Both the native TUI and the existing interactive RPC-host dialogs use their original UI decision without asking another question. Ordinary RPC, print, and unrelated managers do not deliver events. There is no broadcast on Pi's event bus and no authorization from tool results, transcript details, caller-supplied authority flags, or result hooks. Capture helpers are trusted in-process host APIs, not model-callable tools or a sandbox against malicious extensions.
+
+The consumer must retain host provenance, verify the receipt against its active session and exact live branch, and revoke retained evidence on mode/session changes. A subscription is not permanently tied to one leaf: subsequent questions in the same session can have new anchors. Dispose the subscription to revoke pending delivery. Callback failures are isolated so existing public tool result shapes and native consent routing remain unchanged.

package/docs/auto-permission-evidence.md

@@ -0,0 +1,39 @@
+# Auto permission classifier evidence
+
+The classifier checks the original action against host-captured human requests and restrictions. Inspection never creates authorization, replaces missing human intent, or bypasses independent hard safety and native consent. File content and prior calls are untrusted context; a historical read path is not the result of that read.
+
+## Optional inspection
+
+`AutoPermissionRequest.evidencePaths?: string[]` supplies exact relevant project-relative files selected by the host for this action. Omit it to keep the existing single-call, tool-free API. The host should select script paths from the pending action and relevant local context, not enumerate the repository. A script already present in an action payload remains context and needs no duplicate read.
+
+When paths are supplied, the model may request `inspect_permission_file` only when missing file evidence is necessary. It can inspect at most two complete files, one request per round, then must return a verdict. The final provider call exposes no inspection tools and requests `toolChoice: "none"`; insufficient evidence still requires denial, never automatic approval. An unsolicited tool call on that final round remains rejected. Each file is limited to 8192 bytes. Existing files larger than that are never offered as candidates, so the classifier judges the action without them instead of failing on an inspection it can never complete; missing evidence is still not permission. There are at most three provider calls, each with its own deadline (default 20 seconds, maximum 20 seconds), and a bounded overall deadline covering file I/O and all calls (at most 60 seconds). No retries or command execution are introduced. Exhaustion returns unavailable with `evidence-limit`; blocked or missing evidence returns `evidence-unavailable`, never an implicit allow.
+
+Only exact host-selected paths inside the current project can be read. Absolute paths, traversal, symlinks, hard links, special files, dependency/worktree directories, credential names and locations are rejected. Reads are fixed-size, UTF-8, complete and checked for concurrent replacement or modification. Secret-bearing results never reach the provider and fail with `redacted-context`. File content is always explicitly untrusted and cannot change policy, restrictions, or the original action.
+
+One classifier lease covers all rounds. Cancellation or timeout returns promptly but retains the lease until in-flight provider settlement. Identity is checked before and after inspection and provider calls, and again before returning any verdict. The host must bind `isCurrent` to action, session, mode, model and permission-context identity; files can change after inspection, so the verdict is not a reusable execution token.
+
+Usage in the run result aggregates completed calls. A late callback reports only the outstanding call's usage once after a timed-out or cancelled provider settles, excluding earlier rounds already accounted in the returned result. Unknown usage in any call makes aggregate usage unknown. No model reasoning, raw provider errors or raw evidence are logged.
+
+## Compound action selection
+
+The runtime accepts up to four simple segments joined by `&&` for evidence selection only. Each segment must be either `git diff --check` or a `node` invocation with explicit JavaScript/TypeScript file operands and only `--experimental-strip-types` / `--test` flags. Quoting, expansion, redirection, other operators, evaluation, cwd changes and unknown segments leave the whole action without inspection candidates. The original compound action is classified once; no segment inherits approval. Existing path confinement and inspection budgets remain unchanged. Prior ordinary reads retain their arguments, not their returned contents.
+
+Memory-write receipts optionally include `memoryContextAttached`, a content-free boolean for `mem_save` and `mem_session_summary`. It reports whether verified destination context was attached to that classification, independently of allow or deny. It is omitted for other actions and grants no permission.
+
+## Timeout and evidence-limit diagnostics
+
+Classifier results and late-settlement receipts include a metadata-only `diagnostic` object. The runtime projects only these fields into its existing `gentle-auto-permission` entries, and appends them to timeout and evidence-limit blocking messages so a failed read can be diagnosed without opening private session files:
+
+- `implementation`: `auto-classifier-diagnostics-v1`, a marker for this instrumentation, not a source hash or proof of the loaded SDK.
+- `elapsedMs`: monotonic milliseconds since this classifier invocation began, rounded down; late receipts measure through settlement.
+- `deadlineMs`: the configured per-call deadline, not the three-call overall budget.
+- `timerFired`: whether a local deadline callback actually ran. The `timeout` label alone does not prove that a timer fired.
+- `returnPath`: `preflight`, `provider`, `provider-result`, `evidence`, `verdict`, or `late-settlement`, locating the observed return stage without recording exception text.
+
+- `evidenceLimit` (optional): a fixed host discriminator for `evidence-limit`: `path-count`, `provider-rounds`, `file-count`, `duplicate-file`, `context-bytes`, `invalid-byte-budget`, `file-stat-bytes`, or `file-read-bytes`. The public error code and implementation marker remain unchanged. Provider-round exhaustion takes precedence over file-count and duplicate checks; with the current three-round/two-read limits, the file-count branch cannot independently be reached. Stat-size and read-growth failures remain distinct without recording sizes.
+
+These diagnostics contain no prompts, file contents, paths, credentials, provider payloads, or raw errors. Unknown fields are dropped; invalid metadata is omitted. No diagnostic changes a verdict, deadline, retry policy, cancellation, or lease. Missing diagnostics may mean an older or injected implementation; absence alone does not prove which implementation ran. After reloading the instrumented code, one explicitly authorized Auto read is sufficient to collect the blocking message if the failure recurs; it is not an instruction to retry repeatedly.
+
+## Scope
+
+This unit changes classifier behavior only. Runtime path selection, bounded call history and recovery messaging are integrated separately. Benign numeric token declarations and `max_tokens` limits no longer trigger credential heuristics; actual credential assignments, authentication values and private keys remain protected. Prior actions are projected once, not charged twice. Optional oldest complete history records are omitted when necessary to fit the input budget; active human requests, restrictions and the pending action are never truncated. No sandbox, Normal/YOLO, native-consent, or hard-policy changes are made.