gentle-pi 2.4.0 → 2.5.0

package/lib/telemetry-trigger.ts

@@ -0,0 +1,151 @@
+import { spawn as nodeSpawn } from "node:child_process";
+
+// gentle-ai#4309 owns anonymous usage telemetry end to end: install and
+// heartbeat events, the notice, every kill switch, and the wire contract.
+// gentle-pi#677 only nudges the local binary once per process, best-effort,
+// and never surfaces the outcome to the user. This module is the pure,
+// testable core of that nudge (`shouldTriggerTelemetry`,
+// `spawnTelemetryTrigger`) plus the decode helper the foreground
+// `/gentle:telemetry` slash command uses to relay `<op> --json` output
+// (`decodeTelemetryTriggerDecision`).
+
+export const TELEMETRY_TRIGGER_KILL_TIMEOUT_MS = 3_000;
+
+export const TELEMETRY_TRIGGER_CONTRACT = "gentle-ai.telemetry-trigger/v1";
+
+export const TELEMETRY_TRIGGER_DECISIONS = [
+	"enrolled",
+	"sent_install",
+	"sent_heartbeat",
+	"rate_limited",
+	"backoff",
+	"disabled",
+] as const;
+export type TelemetryTriggerDecision = (typeof TELEMETRY_TRIGGER_DECISIONS)[number];
+
+export interface TelemetryTriggerDecisionV1 {
+	schema: typeof TELEMETRY_TRIGGER_CONTRACT;
+	decision: TelemetryTriggerDecision;
+	source: string;
+}
+
+/**
+ * Decodes `gentle-ai telemetry trigger --json` stdout. An older binary
+ * without the verb prints `unknown telemetry command` and exits non-zero, so
+ * its stdout never parses as JSON here; that -- along with malformed JSON, a
+ * mismatched schema, an unrecognized decision, or a missing/non-string
+ * source -- means "nothing to do" and returns undefined rather than
+ * throwing.
+ */
+export function decodeTelemetryTriggerDecision(stdout: string): TelemetryTriggerDecisionV1 | undefined {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(stdout);
+	} catch {
+		return undefined;
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined;
+	const record = parsed as Record<string, unknown>;
+	if (record.schema !== TELEMETRY_TRIGGER_CONTRACT) return undefined;
+	if (typeof record.decision !== "string") return undefined;
+	if (!(TELEMETRY_TRIGGER_DECISIONS as readonly string[]).includes(record.decision)) return undefined;
+	if (typeof record.source !== "string" || record.source.length === 0) return undefined;
+	return {
+		schema: TELEMETRY_TRIGGER_CONTRACT,
+		decision: record.decision as TelemetryTriggerDecision,
+		source: record.source,
+	};
+}
+
+export type TelemetryKillSwitchReason = "do-not-track" | "telemetry-disabled" | "ci";
+
+function telemetryKillSwitchReason(env: Readonly<Record<string, string | undefined>>): TelemetryKillSwitchReason | undefined {
+	if (env.DO_NOT_TRACK === "1") return "do-not-track";
+	if (env.GENTLE_AI_TELEMETRY === "0") return "telemetry-disabled";
+	if (env.CI === "true") return "ci";
+	return undefined;
+}
+
+/**
+ * True unless one of Gentle Pi's own kill switches is set
+ * (`DO_NOT_TRACK=1`, `GENTLE_AI_TELEMETRY=0`, or `CI=true`). The binary
+ * enforces its own opt-out and rate limiting independently; this predicate
+ * only decides whether Gentle Pi spawns the trigger at all.
+ */
+export function shouldTriggerTelemetry(env: Readonly<Record<string, string | undefined>>): boolean {
+	return telemetryKillSwitchReason(env) === undefined;
+}
+
+// A minimal structural subset of node:child_process's ChildProcess, mirroring
+// the ChildLike/Spawn seam already used by lib/agents-runner.ts: narrow
+// enough that tests can stub it without touching a real process.
+export interface TelemetryTriggerChildLike {
+	unref(): unknown;
+	kill(signal?: NodeJS.Signals | number): boolean;
+	on(event: "error", listener: (error: Error) => void): unknown;
+}
+
+export interface TelemetryTriggerSpawnOptions {
+	cwd: string;
+	env: NodeJS.ProcessEnv;
+	detached: boolean;
+	stdio: "ignore";
+}
+
+export type TelemetryTriggerSpawn = (
+	command: string,
+	args: readonly string[],
+	options: TelemetryTriggerSpawnOptions,
+) => TelemetryTriggerChildLike;
+
+export interface SpawnTelemetryTriggerOptions {
+	executable: string;
+	cwd: string;
+	env: NodeJS.ProcessEnv;
+	spawn?: TelemetryTriggerSpawn;
+}
+
+export type TelemetryTriggerReason = "spawned" | "spawn-error" | TelemetryKillSwitchReason;
+
+export interface TelemetryTriggerResult {
+	spawned: boolean;
+	reason: TelemetryTriggerReason;
+}
+
+/**
+ * Nudges `<executable> telemetry trigger --json`, detached and
+ * fire-and-forget. Never throws, never awaits the child's exit, and never
+ * blocks session start: a missing binary, an old binary without the verb, or
+ * a spawn failure all just report `{ spawned: false, ... }`. A 3 s timer
+ * kills a runaway child; the timer is unref'd so it can never keep the host
+ * process alive on its own, matching the detached child's own `unref()`.
+ */
+export function spawnTelemetryTrigger(options: SpawnTelemetryTriggerOptions): TelemetryTriggerResult {
+	const killSwitch = telemetryKillSwitchReason(options.env);
+	if (killSwitch !== undefined) return { spawned: false, reason: killSwitch };
+	const spawnImpl = options.spawn ?? (nodeSpawn as unknown as TelemetryTriggerSpawn);
+	try {
+		const child = spawnImpl(options.executable, ["telemetry", "trigger", "--json"], {
+			cwd: options.cwd,
+			env: options.env,
+			detached: true,
+			stdio: "ignore",
+		});
+		child.on("error", () => {
+			// Fire-and-forget: a spawn-time or runtime child error never surfaces
+			// to the caller and never affects session start.
+		});
+		const killTimer = setTimeout(() => {
+			try {
+				child.kill();
+			} catch {
+				// Best effort only; the child may already have exited.
+			}
+		}, TELEMETRY_TRIGGER_KILL_TIMEOUT_MS);
+		killTimer.unref?.();
+		child.unref();
+		return { spawned: true, reason: "spawned" };
+	} catch {
+		return { spawned: false, reason: "spawn-error" };
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gentle-pi",
-	"version": "2.4.0",
+	"version": "2.5.0",
 	"description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
 	"license": "MIT",
 	"type": "module",
@@ -66,11 +66,11 @@
 		]
 	},
 	"dependencies": {
-		"@earendil-works/pi-tui": "*",
+		"@earendil-works/pi-tui": "0.85.1",
 		"@heyhuynhgiabuu/pi-pretty": "0.6.14"
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-coding-agent": ">=0.85.1",
 		"typebox": "*"
 	},
 	"peerDependenciesMeta": {
@@ -79,7 +79,7 @@
 		}
 	},
 	"devDependencies": {
-		"@earendil-works/pi-coding-agent": "*"
+		"@earendil-works/pi-coding-agent": "0.85.1"
 	},
 	"packageManager": "pnpm@11.1.1"
 }

package/runtime/native-review-cli.mjs

@@ -6,6 +6,7 @@ import { dirname, isAbsolute, join, posix, win32 } from "node:path";
 import { promisify } from "node:util";
 import { PackageLocalGentleAiBinaryMissingError, resolveGentleAiBinary } from "./gentle-ai-binary.mjs";
 import { GENTLE_PI_REVIEW_RELAY_CONTRACT, GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV } from "./review-relay-contract.mjs";
+import { decodeReviewAssessmentV1,                         } from "./review-risk-assessment.mjs";
 import {
 	REVIEW_INTEGRATION_CONTRACT,
 	decodeReviewAcknowledgedV1,
@@ -60,6 +61,7 @@ export const NATIVE_REVIEW_OPERATION = {
 	RECONCILE_AUTHORITY: "review/reconcile-authority",
 	REPAIR_LEGACY_ALIAS: "review/repair-legacy-alias",
 	MODE: "review/mode",
+	ASSESS: "review/assess",
 	REPAIR: "review/repair",
 	CAPTURE_RESULT: "review/capture-result",
 	CAPTURE_CORRECTION_PLAN: "review/capture-correction-plan",
@@ -112,6 +114,11 @@ export const NATIVE_REVIEW_ERROR_CODE = {
 
 
 
+
+
+
+
+
 export const NATIVE_REVIEW_MODE_OPERATION = {
 	STATUS: "status",
 	ENABLE: "enable",
@@ -152,6 +159,17 @@ export const NATIVE_REVIEW_MODE_SCOPE = {
 
 
 
+// Read-only risk assessment request (gentle-pi#662). `baseRef` requires
+// explicit `committedOnly` acknowledgement, exactly like Native START's
+// baseRef/committedOnly pairing, because both select a committed range
+// instead of the ambient working tree.
+
+
+
+
+
+
+
 
 
 
@@ -305,7 +323,6 @@ export const NATIVE_REVIEW_LEGACY_ALIAS_REPAIR = {
 
 
 
-
 
 
 /** Raw audited native record; Pi relays it verbatim and never reinterprets it. */
@@ -499,7 +516,12 @@ export const NATIVE_REVIEW_AUTHORITY_ENTRY_VERSION = {
 }         ;
 
 
-export const NATIVE_REVIEW_AUTHORITY_ENTRY_STATUS = NATIVE_REVIEW_AUTHORITY_STATUS;
+export const NATIVE_REVIEW_AUTHORITY_ENTRY_STATUS = {
+	...NATIVE_REVIEW_AUTHORITY_STATUS,
+	INCOMPLETE_STORE_ENTRY: "incomplete-store-entry",
+	HISTORICAL_PRE_RECEIPT: "historical-pre-receipt",
+	INVALIDATED: "invalidated",
+}         ;
 
 
 export const NATIVE_REVIEW_LOCK_STATUS = {
@@ -570,6 +592,11 @@ export const NATIVE_REVIEW_RECOVERY_DISPOSITION = {
 
 
 
+
+
+
+
+
 
 
 
@@ -805,6 +832,18 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// consumes did not change between 2.5.0 and 2.6.0, so the columns match
 	// the 2.5.0 row.
 	"2.6.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 }),
+	// Ground-truthed against the published v2.7.0 binary installed from its
+	// signed archive: `review capabilities` on the v2 lane still advertises
+	// capabilities/v2.5 (protocol minor 5) and answers status/v7, consent/v3,
+	// and the `start/v4` continuation, all of which the decoders already read.
+	// `review mode status --json` still answers `gentle-ai.rdd-mode-status/v1`
+	// and `review validate --gate pre-commit` still answers
+	// `gentle-ai.review-gate-result/v1` carrying `delivery`, both verified
+	// against the binary. riskEvidence and hint stay dark for the same reason
+	// they have on every row since 2.2.0: still not proven to reach the
+	// negotiated START path Pi reads. The closed fields Pi consumes did not
+	// change between 2.6.0 and 2.7.0, so the columns match the 2.6.0 row.
+	"2.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 }),
 });
 
 
@@ -1047,8 +1086,15 @@ function decodeNativeReviewRecovery(value         )                       {
 		...(recovery.maintainer_authorization === undefined ? {} : { maintainerAuthorization: requiredString(recovery.maintainer_authorization) }),
 	};
 }
+function decodeNativeReviewDiscardedWorkSummary(value         )                                   {
+	const discardedWork = exactObject(value, ["captured_lens_results", "findings_present"]);
+	return {
+		capturedLensResults: stringArray(discardedWork.captured_lens_results),
+		findingsPresent: booleanValue(discardedWork.findings_present),
+	};
+}
 function decodeNativeReviewStatusEntry(value         )                             {
-	const entry = exactObject(value, ["version", "path", "status", "problems"], ["lineage_id", "state", "revision", "snapshot_identity", "chain_identity", "recovery"]);
+	const entry = exactObject(value, ["version", "path", "status", "problems"], ["lineage_id", "state", "revision", "snapshot_identity", "chain_identity", "recovery", "discarded_work"]);
 	return {
 		version: enumString(entry.version, Object.values(NATIVE_REVIEW_AUTHORITY_ENTRY_VERSION))                                     ,
 		...(entry.lineage_id === undefined ? {} : { lineageId: requiredString(entry.lineage_id) }),
@@ -1059,6 +1105,7 @@ function decodeNativeReviewStatusEntry(value         )
 		...(entry.snapshot_identity === undefined ? {} : { snapshotIdentity: sha256Identity(entry.snapshot_identity) }),
 		...(entry.chain_identity === undefined ? {} : { chainIdentity: requiredString(entry.chain_identity) }),
 		...(entry.recovery === undefined ? {} : { recovery: decodeNativeReviewRecovery(entry.recovery) }),
+		...(entry.discarded_work === undefined ? {} : { discardedWork: decodeNativeReviewDiscardedWorkSummary(entry.discarded_work) }),
 		problems: stringArray(entry.problems),
 	};
 }
@@ -1373,9 +1420,7 @@ class NativeReviewPlainCli {
 			if (!isCanonicalProcessString(value)) throw new TypeError(`Native ABANDON ${name} must be a non-empty, trimmed, NUL-free string`);
 		}
 		if (!Array.isArray(request.capturedLensResults) || request.capturedLensResults.some((entry) => !isCanonicalProcessString(entry))) throw new TypeError("Native ABANDON capturedLensResults must be an array of non-empty, trimmed, NUL-free strings");
-		for (const [name, value] of [["findingsPresent", request.findingsPresent], ["evidenceRecordsPresent", request.evidenceRecordsPresent]]         ) {
-			if (typeof value !== "boolean") throw new TypeError(`Native ABANDON ${name} must be a boolean`);
-		}
+		if (typeof request.findingsPresent !== "boolean") throw new TypeError("Native ABANDON findingsPresent must be a boolean");
 		if (request.maintainerAuthorization !== nativeReviewAbandonAuthorization(request)) throw new TypeError("Native ABANDON maintainerAuthorization must match the exact lineage, revision, snapshot, reason, discarded-work, and actor binding");
 		const execution = await this.execute(NATIVE_REVIEW_OPERATION.ABANDON, request.cwd, [
 			"review", "abandon", "--cwd", request.cwd,
@@ -1464,7 +1509,11 @@ class NativeReviewPlainCli {
 	}
 }
 
-export function nativeReviewAbandonAuthorization(request                                                                                                                                                                                   )         {
+export function nativeReviewAbandonAuthorization(request                                                                                                                                                        )         {
+	// gentle-ai 0ed9225f removed evidence records from the discarded-work summary,
+	// so the native v2 gate verifies an exact eight-line binding (schema, lineage,
+	// revision, snapshot_identity, reason, captured_lens_results, findings_present,
+	// actor) — there is no evidence_records_present line to derive or relay.
 	return [
 		"gentle-ai.review-abandon-authorization/v2",
 		`lineage=${request.lineage}`,
@@ -1473,7 +1522,6 @@ export function nativeReviewAbandonAuthorization(request
 		`reason=${request.reason}`,
 		`captured_lens_results=${request.capturedLensResults.join(",")}`,
 		`findings_present=${request.findingsPresent}`,
-		`evidence_records_present=${request.evidenceRecordsPresent}`,
 		`actor=${request.actor.trim()}`,
 	].join("\n");
 }
@@ -1596,14 +1644,20 @@ function splitNativeConsentInvocation(invocation        )                    {
 	let quote                       ;
 	let escaping = false;
 	let started = false;
-	for (const character of invocation.trim()) {
+	const source = invocation.trim();
+	for (let index = 0; index < source.length; index += 1) {
+		const character = source[index] ;
 		if (escaping) {
 			current += character;
 			escaping = false;
 			started = true;
 			continue;
 		}
-		if (character === "\\" && quote !== "'") {
+		// Provider invocations are not shell commands. Keep every path backslash
+		// verbatim, including quoted UNC and drive-root paths. Outside quotes,
+		// only a backslash before whitespace joins a space-containing token.
+		const next = source[index + 1];
+		if (character === "\\" && quote === undefined && next !== undefined && /\s/.test(next)) {
 			escaping = true;
 			started = true;
 			continue;
@@ -1694,7 +1748,9 @@ function consentInvocationArguments(request                                  )
 	if (words[0] !== "gentle-ai" || words[1] !== "review" || words[2] !== "start") throw new NativeReviewConsentBindingError("consent-invocation-not-start", "Native consent invocation is not a provider review START");
 	const arguments_ = words.slice(1);
 	if (exactConsentOption(arguments_, "--contract") !== REVIEW_INTEGRATION_CONTRACT) throw new NativeReviewConsentBindingError("consent-invocation-contract-changed", "Native consent invocation contract changed");
-	if (exactConsentOption(arguments_, "--cwd") !== request.cwd) throw new NativeReviewConsentBindingError("consent-invocation-cwd-changed", "Native consent invocation repository binding changed");
+	const providerCwd = exactConsentOption(arguments_, "--cwd");
+	const requestedCwd = normalizeNativeReviewCwd(request.cwd);
+	if (normalizeNativeReviewCwd(providerCwd) !== requestedCwd) throw new NativeReviewConsentBindingError("consent-invocation-cwd-changed", "Native consent invocation repository binding changed");
 	if (exactConsentOption(arguments_, "--target") !== request.consent.targetIdentity) throw new NativeReviewConsentBindingError("consent-invocation-target-changed", "Native consent invocation target binding changed");
 	if (exactConsentOption(arguments_, "--projection") !== request.consent.projection) throw new NativeReviewConsentBindingError("consent-invocation-projection-changed", "Native consent invocation projection binding changed");
 	const lineageId = optionalConsentLineageOption(arguments_);
@@ -2194,6 +2250,26 @@ export class NativeReviewCliV216                            {
 		return decode(NATIVE_REVIEW_OPERATION.MODE, mutating, () => decodeNativeReviewMode(execution.body, request.operation));
 	}
 
+	// Read-only risk assessment (gentle-ai#4295, gentle-pi#662). Never mutates;
+	// an older binary without the verb, or any other process/decode failure,
+	// rejects -- callers (the `gentle_review` tool's `assess` operation) fail
+	// closed to `high`.
+	async assess(request                           )                              {
+		if (request.baseRef !== undefined && !isCanonicalProcessString(request.baseRef)) throw new TypeError("Native ASSESS baseRef must be a non-empty, trimmed, NUL-free string");
+		if (request.baseRef !== undefined && request.committedOnly !== true) throw new TypeError("Native ASSESS baseRef requires explicit committedOnly acknowledgement");
+		if (request.baseRef === undefined && request.committedOnly !== undefined) throw new TypeError("Native ASSESS committedOnly requires an explicit baseRef");
+		const cwd = await canonicalNativeReviewCwd(request.cwd);
+		const execution = await this.invoke(
+			NATIVE_REVIEW_OPERATION.ASSESS,
+			cwd,
+			["review", "assess", "--cwd", cwd, ...(request.baseRef === undefined ? [] : ["--base-ref", request.baseRef, "--committed-only"]), "--json"],
+			false,
+			request.signal,
+			this.executablePath(NATIVE_REVIEW_OPERATION.ASSESS, false),
+		);
+		return decode(NATIVE_REVIEW_OPERATION.ASSESS, false, () => decodeReviewAssessmentV1(execution.body));
+	}
+
 	// Recovery commands are version-gated plain CLI operations outside the
 	// negotiated integration-v1 contract, exactly like reviewStatus.
 	reclaim(request                            )                                      {

package/runtime/review-integration-v2.mjs

@@ -80,7 +80,10 @@ const RISK_LEVELS = ["low", "medium", "high"]         ;
 const REVIEW_LENSES = ["review-risk", "review-resilience", "review-readability", "review-reliability"]         ;
 const RISK_REASON_CODES = ["configuration_change", "empty_content", "executable_change", "executable_mode", "hot_path", "large_change", "non_executable_only", "process_boundary", "process_scan_limit", "service_token", "shell_source"]         ;
 const RISK_SIGNALS = ["auth", "update", "security", "payments", "permissions", "shell_process"]         ;
-const STATUS_ACTIONS = ["start", "recover", "maintainer_action", "select_lineage", "repair_authority", "stop"]         ;
+// "collect" and "execute" are the v2 envelope's projection of a live
+// transaction whose next_transition is mandatory: the root action names the
+// transition kind instead of reading as a terminal stop.
+const STATUS_ACTIONS = ["start", "recover", "maintainer_action", "select_lineage", "repair_authority", "stop", "collect", "execute"]         ;
 const RECEIPT_STATUSES = ["expected_missing", "present", "publication_pending", "not_applicable"]         ;
 
 export const REVIEW_STATUS_ACTION_DISPOSITION = {
@@ -404,6 +407,8 @@ const REPOSITORY_CONTEXT_OUTCOMES = ["applied", "pending", "blocked_conflict", "
 
 
 
+
+
 
 
 
@@ -546,6 +551,18 @@ export const REVIEW_PROVIDER_ROLE_CAPTURE_OPERATIONS = Object.freeze(Object.valu
 
 
 
+// gentle-pi#627: the exact `gentle-ai sync` invocation that resolves a stale
+// managed-asset set (STATUS next_transition stop, and START's preflight
+// failure envelope both carry this same shape).
+
+
+
+
+
+
+
+
+
 
 
 
@@ -706,6 +723,8 @@ const FAILURE_CAUSE_CATEGORIES = ["inventory_io_or_layout", "lock_ambiguous", "r
 
 
 
+
+
 
 
 
@@ -1640,8 +1659,11 @@ function decodeCollectInput(value         , label        , v5         , v6
 	}
 
 	if (captureOperation === "review.capture-result") {
-		if (input.artifact_subject === undefined || input.base_tree === undefined || input.candidate_tree === undefined || input.changed_path_manifest === undefined) {
-			throw new TypeError(`${label} requires artifact_subject, base_tree, candidate_tree, and changed_path_manifest`);
+		// changed_path_manifest is optional here: the artifact subject's
+		// changed_path_manifest_sha256 already binds the frozen manifest, and
+		// gentle-ai stops inlining one copy per lens (gentle-ai#3922).
+		if (input.artifact_subject === undefined || input.base_tree === undefined || input.candidate_tree === undefined) {
+			throw new TypeError(`${label} requires artifact_subject, base_tree, and candidate_tree`);
 		}
 		if (schema !== "https://gentle-ai.dev/schema/review/reviewer/v1") throw new TypeError(`${label}.schema must be https://gentle-ai.dev/schema/review/reviewer/v1`);
 	} else if (input.artifact_subject !== undefined || input.base_tree !== undefined || input.candidate_tree !== undefined || input.changed_path_manifest !== undefined) {
@@ -1674,12 +1696,32 @@ function decodeCollectInput(value         , label        , v5         , v6
 	};
 }
 
+// gentle-pi#627: gentle-ai's managed-assets continuation (STATUS next_transition
+// stop reason_code=managed_assets_outdated, and START's preflight failure
+// envelope) names the exact `gentle-ai sync` invocation that resolves a stale
+// managed-asset set without abandoning the frozen candidate. Decoded verbatim
+// from internal/cli/review_operation_contract.go's ReviewManagedAssetsContinuation.
+export function decodeReviewManagedAssetsContinuationV1(value         , label        )                                    {
+	const body = exactRecord(value, label, ["operation", "command"], ["agent", "stale_assets"]);
+	const operation = enumeration(body.operation, ["sync"]         , `${label}.operation`);
+	const command = nonempty(body.command, `${label}.command`);
+	const agent = body.agent === undefined ? undefined : nonempty(body.agent, `${label}.agent`);
+	const staleAssets = body.stale_assets === undefined ? undefined : stringArray(body.stale_assets, `${label}.stale_assets`, { minimum: 1 });
+	return { operation, command, ...(agent === undefined ? {} : { agent }), ...(staleAssets === undefined ? {} : { staleAssets }) };
+}
+
 export function decodeReviewNextTransitionV3(value         , options                                 = {})                         {
 	const v6 = options.v6 === true;
 	const v5 = options.v5 === true || v6;
-	const transition = exactRecord(value, "next_transition", ["kind", "reason_code"], ["execute", "collect", ...(v5 ? ["correction_request"] : [])]);
+	const transition = exactRecord(value, "next_transition", ["kind", "reason_code"], ["execute", "collect", ...(v5 ? ["correction_request"] : []), "continuation"]);
 	const kind = enumeration(transition.kind, ["execute", "collect", "stop"]         , "next_transition.kind");
 	const reasonCode = text(transition.reason_code, "next_transition.reason_code", { minimum: 1, pattern: /^[a-z0-9_]+$/ });
+	const continuation = transition.continuation === undefined ? undefined : decodeReviewManagedAssetsContinuationV1(transition.continuation, "next_transition.continuation");
+	// gentle-pi#627: continuation is optional on every status version an older
+	// gentle-ai may emit a managed_assets_outdated stop with no continuation at
+	// all, and decode must not refuse the whole envelope for that. When present
+	// it is only valid on a stop with this exact reason_code.
+	if (continuation !== undefined && !(kind === "stop" && reasonCode === "managed_assets_outdated")) throw new TypeError("next_transition.continuation is only valid for a stop transition with reason_code managed_assets_outdated");
 
 	// status/v5: the bounded correction plan request rides exactly its two
 	// reason codes and never any other (vendored status-v5.schema.json).
@@ -1729,7 +1771,7 @@ export function decodeReviewNextTransitionV3(value         , options
 		return { kind, reasonCode, collect: { inputs }, ...(correctionRequest === undefined ? {} : { correctionRequest }) };
 	}
 	if (transition.execute !== undefined || transition.collect !== undefined) throw new TypeError("next_transition stop cannot carry a transition");
-	return { kind, reasonCode, ...(correctionRequest === undefined ? {} : { correctionRequest }) };
+	return { kind, reasonCode, ...(correctionRequest === undefined ? {} : { correctionRequest }), ...(continuation === undefined ? {} : { continuation }) };
 }
 
 // ---------------------------------------------------------------------------
@@ -1818,11 +1860,12 @@ export function decodeReviewStatusV3(value         )                 {
 
 	let frozen                                  ;
 	if (body.frozen !== undefined) {
-		const source = exactRecord(body.frozen, "status.frozen", ["tier", "original_changed_lines", "correction_budget"]);
+		const source = exactRecord(body.frozen, "status.frozen", ["tier", "original_changed_lines", "correction_budget"], ["changed_path_manifest_sha256"]);
 		frozen = {
 			tier: enumeration(source.tier, RISK_LEVELS, "status.frozen.tier"),
 			originalChangedLines: integer(source.original_changed_lines, "status.frozen.original_changed_lines"),
 			correctionBudget: integer(source.correction_budget, "status.frozen.correction_budget", 0, 200),
+			...(source.changed_path_manifest_sha256 === undefined ? {} : { changedPathManifestSha256: sha256(source.changed_path_manifest_sha256, "status.frozen.changed_path_manifest_sha256") }),
 		};
 	}
 	if (authority?.version === REVIEW_AUTHORITY_VERSION.COMPACT_V2 && frozen === undefined) throw new TypeError("compact-v2 status requires frozen metadata");
@@ -2049,9 +2092,10 @@ function decodeFailureContext(value         , label        )
 export function decodeReviewFailureV2(value         )                  {
 	const body = exactRecord(value, "failure", [
 		"schema", "contract", "operation", "phase", "code", "message", "mutation_outcome", "authority_applicability", "retry_safe", "replayability", "required_inputs", "next_action",
-	], ["lineage_id", "request_digest", "progress_identity", "cause_category", "cause", "context"]);
+	], ["lineage_id", "request_digest", "progress_identity", "cause_category", "cause", "context", "continuation"]);
 	requireIdentity(body, "gentle-ai.review-integration.failure/v2");
 	const operation = enumeration(body.operation, FAILURE_OPERATIONS, "failure.operation");
+	const code = text(body.code, "failure.code", { pattern: /^[a-z0-9]+(?:_[a-z0-9]+)*$/ });
 
 	if (body.progress_identity !== undefined) {
 		if (body.lineage_id === undefined || body.request_digest === undefined) throw new TypeError("failure.progress_identity requires lineage_id and request_digest");
@@ -2060,13 +2104,18 @@ export function decodeReviewFailureV2(value         )                  {
 	if (body.request_digest !== undefined && operation === REVIEW_INTEGRATION_OPERATION.REPAIR && body.progress_identity === undefined) {
 		throw new TypeError("failure.request_digest with review.repair requires progress_identity");
 	}
+	// gentle-pi#627: continuation is optional on every version — an older
+	// gentle-ai may emit managed_assets_outdated with no continuation, and
+	// decode must not refuse the whole envelope for that. When present it is
+	// only valid on this exact code.
+	if (body.continuation !== undefined && code !== "managed_assets_outdated") throw new TypeError("failure.continuation is only valid for code managed_assets_outdated");
 
 	return {
 		schema: "gentle-ai.review-integration.failure/v2",
 		contract: REVIEW_INTEGRATION_CONTRACT,
 		operation,
 		phase: enumeration(body.phase, ["preflight", "pre_native", "native_running", "native_committed", "reconciliation"]         , "failure.phase"),
-		code: text(body.code, "failure.code", { pattern: /^[a-z0-9]+(?:_[a-z0-9]+)*$/ }),
+		code,
 		message: text(body.message, "failure.message", { minimum: 1, maximum: 240, pattern: /^[^\r\n]+$/ }),
 		mutationOutcome: enumeration(body.mutation_outcome, Object.values(REVIEW_MUTATION_OUTCOME), "failure.mutation_outcome"),
 		authorityApplicability: enumeration(body.authority_applicability, Object.values(REVIEW_AUTHORITY_APPLICABILITY), "failure.authority_applicability"),
@@ -2080,6 +2129,7 @@ export function decodeReviewFailureV2(value         )                  {
 		...(body.cause_category === undefined ? {} : { causeCategory: text(body.cause_category, "failure.cause_category", { minimum: 1, pattern: /^[a-z0-9]+(?:_[a-z0-9]+)*$/ }) }),
 		...(body.cause === undefined ? {} : { cause: text(body.cause, "failure.cause", { minimum: 1, maximum: 4000, pattern: /^[^\r\n]+$/ }) }),
 		...(body.context === undefined ? {} : { context: decodeFailureContext(body.context, "failure.context") }),
+		...(body.continuation === undefined ? {} : { continuation: decodeReviewManagedAssetsContinuationV1(body.continuation, "failure.continuation") }),
 		raw: body,
 	};
 }

package/runtime/review-relay-contract.mjs

@@ -15,3 +15,14 @@
 
 export const GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV = "GENTLE_PI_REVIEW_RELAY_CONTRACT";
 export const GENTLE_PI_REVIEW_RELAY_CONTRACT = "gentle-pi.review-relay/v1";
+
+// The host is this extension: every process the session starts (pi's shell
+// tools, Gentle Agents children) runs under it, so the handshake belongs in
+// the session environment too, not only in the extension's own invocations.
+// Without it the first `gentle-ai review status --agent pi` typed in the
+// session shell fails closed (gentle-pi#550). Returns whether anything changed.
+export function declareReviewRelayHandshake(env                   )          {
+	if (env[GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV] === GENTLE_PI_REVIEW_RELAY_CONTRACT) return false;
+	env[GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV] = GENTLE_PI_REVIEW_RELAY_CONTRACT;
+	return true;
+}