gentle-pi 2.3.0 → 2.5.0

package/contracts/review-provider-contract-mirror/v1.2.0/bundle/manifest.json

@@ -0,0 +1,74 @@
+{
+  "schema": "gentle-ai.review-provider-contract-bundle/v1",
+  "contract_semver": "1.2.0",
+  "transport_capability": "gentle-ai.provider-transport/v1",
+  "runtimes": [
+    "claude-code",
+    "codex",
+    "opencode",
+    "pi"
+  ],
+  "readme": {
+    "path": "README.md",
+    "sha256": "18baab5ee79aefd0bc62a28da0dadcf2162544f57a940c5b859cd6bc4932a085"
+  },
+  "roles": [
+    {
+      "id": "lens",
+      "request_schema_id": "gentle-ai.review-lens-context/v1",
+      "result_schema_id": "https://gentle-ai.dev/schema/review/reviewer/v1",
+      "required_capabilities": [
+        "gentle-ai.provider-transport/v1"
+      ],
+      "schema": {
+        "path": "schemas/lens.schema.json",
+        "sha256": "ffef79cfb763333282285ff5c795a32b5a88d840b4a8d125ce012188b04cffe1"
+      },
+      "vector": {
+        "path": "vectors/lens.json",
+        "sha256": "7ef0b08404645eeb5dba92aba5f8e4780667b6ec775f43ed8547ff9f2a7148c8"
+      }
+    },
+    {
+      "id": "refuter",
+      "request_schema_id": "gentle-ai.review-provider-refuter-request/v1",
+      "result_schema_id": "https://gentle-ai.dev/schema/review/refuter/v1",
+      "required_capabilities": [
+        "gentle-ai.provider-transport/v1"
+      ],
+      "schema": {
+        "path": "schemas/refuter.schema.json",
+        "sha256": "36f8267c6c3f04600b8f1cb77df70d90858611af822cc81922efd6b3502fb646"
+      },
+      "vector": {
+        "path": "vectors/refuter.json",
+        "sha256": "f42d71906e49c4191660b2da7e70f01f1778b23d32089005bd2d7ae9cbb73039"
+      }
+    },
+    {
+      "id": "targeted-validator",
+      "request_schema_id": "gentle-ai.review-targeted-validation-request/v1",
+      "result_schema_id": "https://gentle-ai.dev/schema/review/validator/v1",
+      "required_capabilities": [
+        "gentle-ai.provider-transport/v1"
+      ],
+      "schema": {
+        "path": "schemas/targeted-validator.schema.json",
+        "sha256": "6a8d7b331ec6f000366017e39e0476511c3b032649c42abfe865c1e9c956510e"
+      },
+      "vector": {
+        "path": "vectors/targeted-validator.json",
+        "sha256": "7b5a5165e3a913863fb98d2ba5387811860c21333b5c37e6ed3b4e0d121cf2fa"
+      }
+    }
+  ],
+  "orchestration": [
+    {
+      "runtime": "pi",
+      "file": {
+        "path": "orchestration/pi.md",
+        "sha256": "69c51944081ccff09d1cee5e24eb3a14b7b911a2e734cef8f8ea94a15b9f9d4c"
+      }
+    }
+  ]
+}

package/contracts/review-provider-contract-mirror/v1.2.0/bundle/orchestration/pi.md

@@ -0,0 +1,53 @@
+# Native Compact Review Orchestration
+
+Pi uses the compact gentle-pi facade for this lifecycle: `gentle_review` for inspect, START, consent, bound STATUS, and acknowledgement; `gentle_review_capture` and `gentle_review_capture_group` for collection. Provider-issued authority and every opaque binding are authoritative; prompt prose never creates authority or decides delivery.
+
+## 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.
+
+## 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.
+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.
+
+Pi never reconstructs lineage, target, revision, repository context, lens, order, or commands. It never appends, removes, parses, or rebuilds provider-issued opaque bindings. Go owns repository binding, frozen evidence, provider context, validation, admission, correction scope, and closure.
+
+## Consent and forecast
+
+If START returns the typed `gentle-ai.review-integration.consent/v3` envelope, relay it as a Lossless Blocking Prompt. Global RDD enabled permits review; it never grants consent for this candidate. For medium/high candidates, faithfully translate the headline, reason, `value`, risk evidence, choice labels, every choice `effect`, and the off-path note while preserving original groups/order, selection mode, allowed-answer domain, answer tokens, and the `consentBinding`. Project `value` as benefits and every `effect` as consequences. Do not translate machine answer tokens (`granted`, `declined`). Submit exactly the human's choice through `gentle_review` with operation `answer-consent` and the exact `consentBinding`; a decline is candidate-scoped and is not the kill switch.
+
+A four-lens review is long work. The first capture of a materialize slot or group returns a `forecast` and runs nothing: relay it losslessly in the user's language, preserving every step's order and fields (`step`, `kind`, `reason_code`, `description`) and the horizon, then resubmit the same exact binding with `reviewerRunAcknowledged: true`. Forecast is informational; route only from the returned transition.
+
+## Capture and correction
+
+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.
+
+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.
+
+### Cross-repository lifecycle root
+
+A session in repository A may review an explicitly selected nested target in unrelated repository B only after explicit user authorization. Pass the selected path as `workspaceRoot`; Go resolves it to the canonical B worktree root, and the facade retains it. Keep that `workspaceRoot` on every later facade call for the lineage, from inspect through acknowledgement, and do not fall back to A. The same lineage text in A and B is independent; exact acknowledgement burns B only.
+
+### Continue after a stop reason code
+
+A `stop` ends its transition, never approves delivery. `D` means the human disables the review switch for this clone with `gentle-ai review mode disable --scope clone`; ordinary policy then decides delivery. `S` means re-query bound facade STATUS with the retained `lineageId` and `workspaceRoot`.
+
+| Reason codes | Continuation |
+| --- | --- |
+| `captured_artifacts_unverifiable`, `captured_result_selection_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`. |
+| `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. |
+| `recovery_scope_unchanged` | Change the target identity, then retry the facade `recover` route the stop returned. |
+| `rdd_disabled` | `--scope clone` only clears a clone-local off; the human runs `gentle-ai review mode enable --scope global`, then `S`. |
+
+## Delivery follows ordinary repository policy
+
+After exact acknowledgement burns terminal `approved` authority, the review lifecycle stops. Commit, push, PR, and release remain separate human decisions under ordinary repository policy. A review outcome is informational and never authorizes delivery.

package/contracts/review-provider-contract-mirror/v1.2.0/bundle/schemas/targeted-validator.schema.json

@@ -0,0 +1 @@
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://gentle-ai.dev/schema/review/validator/v1","title":"Gentle AI targeted validator result","type":"object","additionalProperties":false,"required":["targeted_validation_request_hash","correction_target_identity","original_criteria","correction_regression","follow_ups"],"properties":{"targeted_validation_request_hash":{"$ref":"#/$defs/sha256"},"correction_target_identity":{"$ref":"#/$defs/sha256"},"original_criteria":{"$ref":"#/$defs/check"},"correction_regression":{"$ref":"#/$defs/check"},"follow_ups":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["observation","proof_refs"],"properties":{"observation":{"type":"string"},"proof_refs":{"type":"array","minItems":1,"items":{"type":"string","pattern":"\\S"}}}}}},"$defs":{"sha256":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"},"check":{"type":"object","additionalProperties":false,"required":["passed","evidence"],"properties":{"passed":{"type":"boolean","description":"true means the named check passed; false means the named check failed."},"evidence":{"type":"array","minItems":1,"items":{"type":"string"}}}}},"examples":[{"targeted_validation_request_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","correction_target_identity":"sha256:1111111111111111111111111111111111111111111111111111111111111111","original_criteria":{"passed":true,"evidence":["acceptance test passed"]},"correction_regression":{"passed":true,"evidence":["regression test passed"]},"follow_ups":[]}]}

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

@@ -1,6 +1,6 @@
 {
   "schema": "gentle-pi.provider-contract-capabilities-baseline/v1",
-  "contract_semver": "1.1.0",
+  "contract_semver": "1.2.0",
   "transport_capability": "gentle-ai.provider-transport/v1",
   "mandatory_capabilities": [
     "gentle-ai.provider-transport/v1"
@@ -11,5 +11,12 @@
     "opencode",
     "pi"
   ],
-  "pi_registered": true
+  "pi_registered": true,
+  "orchestration": [
+    {
+      "runtime": "pi",
+      "path": "orchestration/pi.md",
+      "sha256": "69c51944081ccff09d1cee5e24eb3a14b7b911a2e734cef8f8ea94a15b9f9d4c"
+    }
+  ]
 }

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

@@ -1,6 +1,6 @@
 {
   "schema": "gentle-pi.provider-contract-roles-baseline/v1",
-  "contract_semver": "1.1.0",
+  "contract_semver": "1.2.0",
   "roles": [
     {
       "id": "lens",
@@ -34,7 +34,7 @@
         "gentle-ai.provider-transport/v1"
       ],
       "schema_path": "schemas/targeted-validator.schema.json",
-      "schema_sha256": "58f5efca0fb8089a51e998d5cf07209528a6b6e3782246b34ee1e825132063a8",
+      "schema_sha256": "6a8d7b331ec6f000366017e39e0476511c3b032649c42abfe865c1e9c956510e",
       "vector_path": "vectors/targeted-validator.json",
       "vector_sha256": "7b5a5165e3a913863fb98d2ba5387811860c21333b5c37e6ed3b4e0d121cf2fa"
     }

package/docs/delegated-verification.md

@@ -0,0 +1,25 @@
+# Delegated verification
+
+How the Gentle Pi orchestrator decides who verifies a bounded writer's work. The always-on parent prompt renders a `Receipt-driven development: on|off|unknown` line; the delegation overlay (`assets/orchestrator-delegation.md`, trigger 5) keys the verification rule on it. This page is package-owned; `docs/review-integration.md` mirrors the Gentle AI contract and must stay byte-identical to it.
+
+## Receipt-driven development on
+
+The bounded writer runs the exact commands the parent lists under `## Verification`, in the foreground, and reports each as `<command>: <observed result>`. That report is the verification of record and the native review is the independent check. `gentle-ai-verify` is on-demand: a `partial` or `blocked` writer, an expensive or external check the parent wants on a cheaper profile, or a parent spot check.
+
+This `on` path holds only while the native review actually reaches a terminal outcome for the current candidate (gentle-pi#668). A human decline of the consent envelope for this candidate (candidate-scoped, never the RDD kill switch), a clone-local RDD disable discovered mid-flow, or a refused START/STATUS all mean the review never ran, so the parent falls back to the exact risk-gated path below, as if RDD were `off` -- declining a review never lowers the bar below the RDD-off path. `gentle_review`'s `assess` operation accepts an optional `nativeReviewOutcome` (`closed`, `declined`, `unavailable`, or `unknown`) so the caller can state this directly. `closed` is never auto-derived: only a caller that itself just acknowledged the approved review for this exact candidate may pass it, right after that acknowledgement. When `nativeReviewOutcome` is omitted, `assess` only ever tries to auto-derive `declined`/`unavailable`, and only for the exact candidate the event was bound to -- keyed by that candidate's own target identity, never by repository alone, so one candidate's recorded outcome can never leak into a different candidate's `assess` call in the same clone. A missing or mismatched identity fails closed to `unknown`, verified exactly like `off`. The result's `outcome_source` (`explicit`, `derived`, or `unknown`) states which of these produced the value, so a stale or missing derivation is visible rather than silently indistinguishable from a real `unknown`.
+
+## Receipt-driven development off or unknown (gentle-pi#662)
+
+The host exposes one read-only native operation: `gentle-ai review assess --cwd <repo> [--base-ref <ref> --committed-only] --json` (gentle-ai#4295). It is decoded by `lib/review-risk-assessment.ts` and wired through `lib/native-review-cli.ts` exactly like the existing `reviewMode` STATUS reader -- a bounded subprocess with a typed decode, never a mutation. A non-zero exit, a failure envelope, or an older binary without the verb all fail closed to `high` risk.
+
+The `gentle_review` tool's `assess` operation (`extensions/gentle-ai.ts`) combines that assessment with the rendered `Receipt-driven development:` line to decide whether a delegated writer's change needs a separate `gentle-ai-verify` run, following this tier table:
+
+| Native risk tier | Verification when RDD is `off`/`unknown` |
+| --- | --- |
+| passive | structural readback by the parent; no separate verifier, no tests |
+| medium | writer self-verification stands; a separate `gentle-ai-verify` run is added only when the writer profile is a small model (mini or low effort) |
+| high | writer self-verification plus a separate `gentle-ai-verify` run, always |
+| unknown / assess failed | treated as high |
+
+When RDD is `on` and the native review closed for this candidate, the writer's own self-verification is the record and the closed native review is the independent check, except a passive-risk change, which still gets a structural readback instead; any other `nativeReviewOutcome` under `on` follows this same tier table instead (gentle-pi#668). The small-model bias raises the medium tier to high for verification purposes only; an unknown RDD line never lowers a tier below `off`. The parent's own spot check (re-running one reported command before delivery) stays required in every tier.
+

package/docs/review-integration.md

@@ -25,7 +25,7 @@ A typed Pi transport refusal fails closed. The coordinator reports the refusal w
 
 ## Dynamic contract delivery
 
-Package static assets intentionally omit lifecycle instructions, candidate routing, recovery procedures, receipt semantics, and any delivery-gate or delivery-authorization behavior. Gentle AI injects the current runtime-specific review contract through generated Pi APPEND_SYSTEM composition. The host follows only that generated review contract. When it is absent or the runtime is unsupported, Gentle Pi does not invent a fallback; delivery remains ordinary repository policy.
+Package static assets intentionally omit lifecycle instructions, candidate routing, recovery procedures, receipt semantics, and any delivery-gate or delivery-authorization behavior. Since Gentle AI stopped generating Pi APPEND_SYSTEM composition, Gentle Pi mirrors the provider contract bundle's `orchestration/pi.md` review execution contract locally (`contracts/review-provider-contract-mirror/`) and injects that verified, mirrored text into the primary session's system prompt at session start. Gentle AI writes nothing into the Pi system prompt; the host follows only that mirrored contract. When the mirrored contract is absent or unreadable, Gentle Pi does not invent a fallback; delivery remains ordinary repository policy.
 
 ## Integration constraints
 

package/docs/telemetry.md

@@ -0,0 +1,38 @@
+# Telemetry
+
+`gentle-pi` does not collect anything itself. [`gentle-ai`](https://github.com/Gentleman-Programming/gentle-ai) (issue [#4309](https://github.com/Gentleman-Programming/gentle-ai/issues/4309)) owns anonymous usage telemetry end to end: install and heartbeat events, the exact fields sent, rate limiting, and every opt-out. See gentle-ai's own README/docs for that contract. Gentle Pi's only involvement is a best-effort nudge that asks the local binary to act.
+
+## What Gentle Pi does
+
+On activation of a primary session (never for a named agent or an SDD phase executor), Gentle Pi resolves the package-local `gentle-ai` binary (honoring a registered dev-binary override, same as every other native call) and spawns:
+
+```text
+gentle-ai telemetry trigger --json
+```
+
+- detached, with stdout/stderr discarded (`stdio: "ignore"`);
+- a 3 s deadline: a runaway process is killed, but Gentle Pi never waits for it to exit;
+- at most once per process, regardless of how many sessions or sub-agents run afterward.
+
+Rate limiting, enrollment, and every opt-out live entirely in `gentle-ai`; calling the trigger once per session start is safe by construction. A missing binary, an older binary without the `telemetry` verb (which prints `unknown telemetry command` and exits non-zero), or a spawn failure are all treated as "nothing to do" and never affect activation or surface an error to the user.
+
+Install counts for `gentle-pi` and `gentle-engram` come from npm download statistics; neither package emits an install event of its own.
+
+## The trigger contract
+
+`gentle-ai telemetry trigger --json` always exits `0` and prints one line of JSON:
+
+```json
+{"schema":"gentle-ai.telemetry-trigger/v1","decision":"enrolled|sent_install|sent_heartbeat|rate_limited|backoff|disabled","source":"<deciding source>"}
+```
+
+`gentle-ai telemetry status|enable|disable|preview [--json]` exist for the opt-out flow; `status --json` prints `gentle-ai.telemetry-status/v1`. Gentle Pi's `/gentle:telemetry` slash command runs these in the foreground (bounded to 5 s) through the same binary resolver and relays the result.
+
+## Opting out
+
+Any of the following disables the nudge or the underlying telemetry:
+
+- `/gentle:telemetry disable` — asks the local `gentle-ai` binary to disable telemetry. `/gentle:telemetry status` and `/gentle:telemetry preview` inspect it without leaving Pi.
+- `DO_NOT_TRACK=1` — Gentle Pi does not spawn the trigger at all; `gentle-ai` also honors this standard independently.
+- `GENTLE_AI_TELEMETRY=0` — same effect, `gentle-ai`'s own environment switch.
+- `CI=true` — Gentle Pi does not spawn the trigger in automated/CI runs, since they are not a real usage signal.

package/extensions/ask-user-choice.ts

@@ -1,7 +1,9 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { DynamicBorder } from "@earendil-works/pi-coding-agent";
-import { Container, type SelectItem, SelectList, Text } from "@earendil-works/pi-tui";
+import { Text } from "@earendil-works/pi-tui";
 import { type Static, Type } from "typebox";
+import { NativeChoiceList } from "../lib/native-choice-list.ts";
+import { createNativeFullscreenInteraction } from "../lib/native-fullscreen-interaction.ts";
 
 const CHOICE_TOOL_NAME = "ask_user_choice";
 const ASK_USER_CHOICE_BLOCKED_EVENT = "gentle-pi:ask-user-choice:blocked";
@@ -72,41 +74,45 @@ export default function askUserChoice(pi: ExtensionAPI): void {
 				throw new Error("ask_user_choice is unavailable outside the interactive TUI");
 			}
 
-			const items: SelectItem[] = params.options.map((option) => ({
-				value: option.value,
+			const items = params.options.map((option, index) => ({
+				id: `choice-${index}`,
 				label: option.label,
 				description: option.description,
 			}));
 			let selection: ChoiceSelection | undefined;
 			try {
 				pi.events.emit(ASK_USER_CHOICE_BLOCKED_EVENT, { active: true });
-				selection = await ctx.ui.custom<ChoiceSelection | undefined>((tui, theme, _keybindings, done) => {
-					const container = new Container();
-					container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
-					container.addChild(new Text(theme.fg("accent", theme.bold(params.question)), 1, 0));
-					const list = new SelectList(items, items.length, {
+				selection = await ctx.ui.custom<ChoiceSelection | undefined>((tui, theme, keybindings, done) => {
+					const list = new NativeChoiceList(items, {
 						selectedPrefix: (text) => theme.fg("accent", text),
 						selectedText: (text) => theme.fg("accent", text),
 						description: (text) => theme.fg("muted", text),
-						scrollInfo: (text) => theme.fg("dim", text),
-						noMatch: (text) => theme.fg("warning", text),
+						hoverBackground: (text) => theme.bg("toolPendingBg", text),
+					}, keybindings);
+					const container = createNativeFullscreenInteraction({
+						keyboardTarget: list,
+						requestRender: () => tui.requestRender(),
+						mouseObserver: list.createMouseObserver(() => tui.requestRender()),
 					});
+					let completed = false;
+					const finish = (result: ChoiceSelection | undefined) => {
+						if (completed) return;
+						completed = true;
+						list.setDisabled(true);
+						done(result);
+					};
 					list.onSelect = (item) => {
 						const index = items.indexOf(item);
-						done({ value: item.value, label: item.label, index: index + 1 });
+						const option = params.options[index];
+						if (option) finish({ value: option.value, label: option.label, index: index + 1 });
 					};
-					list.onCancel = () => done(undefined);
+					list.onCancel = () => finish(undefined);
+					container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
+					container.addChild(new Text(theme.fg("accent", theme.bold(params.question)), 1, 0));
 					container.addChild(list);
 					container.addChild(new Text(theme.fg("dim", "↑↓ navigate • Enter select • Esc cancel"), 1, 0));
 					container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
-					return {
-						render: (width) => container.render(width),
-						invalidate: () => container.invalidate(),
-						handleInput: (data) => {
-							list.handleInput(data);
-							tui.requestRender();
-						},
-					};
+					return container;
 				});
 			} finally {
 				pi.events.emit(ASK_USER_CHOICE_BLOCKED_EVENT, { active: false });

package/extensions/codegraph-tools.ts

@@ -1,7 +1,7 @@
 import { execFile, execFileSync } from "node:child_process";
-import { lstatSync, realpathSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { promisify } from "node:util";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
@@ -177,13 +177,102 @@ function codeGraphFailureMessage(status: CodeGraphStatus): string {
 		: `CodeGraph failed to run. ${FALLBACK_INSTRUCTIONS}`;
 }
 
+function isEnoent(error: unknown): boolean {
+	return (
+		typeof error === "object" &&
+		error !== null &&
+		"code" in error &&
+		(error as { code?: unknown }).code === "ENOENT"
+	);
+}
+
+/** Find `codegraph.cmd` shims in Windows PATH order. */
+function* codeGraphCmdPathsOnPath(): Iterable<string> {
+	const pathEnv = process.env.Path ?? process.env.PATH ?? "";
+	for (const entry of pathEnv.split(";")) {
+		const dir = entry.length >= 2 && entry.startsWith('"') && entry.endsWith('"')
+			? entry.slice(1, -1)
+			: entry;
+		if (!dir) continue;
+		const candidate = join(dir, "codegraph.cmd");
+		if (existsSync(candidate)) yield candidate;
+	}
+}
+
+/**
+ * Resolve the actual JS entry of the `@colbymchenry/codegraph` package from the
+ * npm global bin dir (sibling of the `codegraph.cmd` shim) and run it with the
+ * current Node executable. No shell involvement, so args are never interpreted.
+ */
+export function codeGraphNodeScript(cmdPath: string): string | undefined {
+	const binDir = dirname(cmdPath);
+	const pkgRoot = join(binDir, "node_modules", "@colbymchenry", "codegraph");
+	const pkgJsonPath = join(pkgRoot, "package.json");
+	if (!existsSync(pkgJsonPath)) return undefined;
+	try {
+		const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf8")) as { bin?: unknown };
+		const bin = pkg.bin;
+		const target =
+			typeof bin === "string"
+				? bin
+				: bin &&
+						typeof bin === "object" &&
+						"codegraph" in bin &&
+						typeof (bin as Record<string, unknown>).codegraph === "string"
+					? (bin as Record<string, string>).codegraph
+					: undefined;
+		if (typeof target !== "string" || !target) return undefined;
+		const script = join(pkgRoot, target);
+		return statSync(script).isFile() ? script : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function* codeGraphNodeScriptsOnPath(): Iterable<string> {
+	for (const cmdPath of codeGraphCmdPathsOnPath()) {
+		const script = codeGraphNodeScript(cmdPath);
+		if (script) yield script;
+	}
+}
+
+/** Resolve the first valid CodeGraph npm entry point in Windows PATH order. */
+export function findCodeGraphNodeScriptOnPath(): string | undefined {
+	return codeGraphNodeScriptsOnPath().next().value;
+}
+
 const runCodeGraphCommand: CodeGraphRunner = async (args, options) => {
-	const result = await execFileAsync("codegraph", [...args], {
+	const runOptions = {
 		cwd: options.cwd,
 		signal: options.signal,
 		maxBuffer: options.maxBuffer,
-	});
-	return { stdout: result.stdout, stderr: result.stderr };
+	};
+	let unavailableError: unknown;
+
+	try {
+		const result = await execFileAsync("codegraph", [...args], runOptions);
+		return { stdout: result.stdout, stderr: result.stderr };
+	} catch (error) {
+		// Windows npm installs only shims (codegraph.cmd/.ps1 and a shell script)
+		// with no codegraph.exe, so plain execFile (CreateProcess, no shell)
+		// always fails with ENOENT even when the shim is on PATH.
+		if (process.platform !== "win32" || !isEnoent(error)) throw error;
+		unavailableError = error;
+	}
+
+	// Resolve the real package script from each npm global bin directory in PATH
+	// order and run it through the current Node executable. This remains
+	// shell-free, so argument boundaries are never interpreted by a shell.
+	for (const script of codeGraphNodeScriptsOnPath()) {
+		try {
+			const result = await execFileAsync(process.execPath, [script, ...args], runOptions);
+			return { stdout: result.stdout, stderr: result.stderr };
+		} catch (innerError) {
+			if (!isEnoent(innerError)) throw innerError;
+		}
+	}
+
+	throw unavailableError;
 };
 
 export function createCodeGraphTool(runner: CodeGraphRunner = runCodeGraphCommand) {