gentle-pi 2.4.0 → 2.6.0

package/lib/review-risk-assessment.ts

@@ -0,0 +1,339 @@
+// gentle-pi#662: pure decoding, tier mapping, and verification-plan logic for
+// the native read-only `gentle-ai review assess` command (gentle-ai#4295).
+// Kept independent of the native review CLI wrapper (`lib/native-review-cli.ts`)
+// so the decoder and the verificationPlan table can be unit-tested without a
+// child process, and so the parent tool and the delegation asset agree on one
+// deterministic mapping.
+//
+// Native reference (gentle-ai#4295, landing in parallel with this change):
+// `gentle-ai review assess --cwd <repo> [--base-ref <ref> --committed-only] --json`
+// prints `{"schema":"gentle-ai.review-assessment/v1","risk":"passive|medium|high",
+// "reasons":[{"code":"…","path":"…","detail":"…"}],"changed_paths":1,
+// "changed_lines":1,"candidate":{"kind":"current-changes|base-diff","base_ref":"…"}}`.
+// 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
+// any other decode/process failure) fail closed the same way -- see
+// `verificationTierForUnassessable` below.
+
+export const REVIEW_ASSESSMENT_SCHEMA = "gentle-ai.review-assessment/v1" as const;
+
+export const REVIEW_ASSESSMENT_RISK = {
+	PASSIVE: "passive",
+	MEDIUM: "medium",
+	HIGH: "high",
+} as const;
+export type ReviewAssessmentRisk = (typeof REVIEW_ASSESSMENT_RISK)[keyof typeof REVIEW_ASSESSMENT_RISK];
+
+export const REVIEW_ASSESSMENT_CANDIDATE_KIND = {
+	CURRENT_CHANGES: "current-changes",
+	BASE_DIFF: "base-diff",
+} as const;
+export type ReviewAssessmentCandidateKind = (typeof REVIEW_ASSESSMENT_CANDIDATE_KIND)[keyof typeof REVIEW_ASSESSMENT_CANDIDATE_KIND];
+
+export interface ReviewAssessmentReason {
+	readonly code: string;
+	readonly path: string;
+	readonly detail: string;
+}
+
+export interface ReviewAssessmentCandidate {
+	readonly kind: ReviewAssessmentCandidateKind;
+	readonly baseRef: string | undefined;
+}
+
+export interface ReviewAssessmentV1 {
+	readonly schema: typeof REVIEW_ASSESSMENT_SCHEMA;
+	readonly risk: ReviewAssessmentRisk;
+	readonly reasons: readonly ReviewAssessmentReason[];
+	readonly changedPaths: number;
+	readonly changedLines: number;
+	readonly candidate: ReviewAssessmentCandidate;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function decodeReason(value: unknown): ReviewAssessmentReason {
+	if (!isRecord(value)) throw new TypeError("review assessment reason must be an object");
+	const { code, path, detail } = value;
+	if (typeof code !== "string" || code.length === 0) throw new TypeError("review assessment reason.code must be a non-empty string");
+	if (typeof path !== "string") throw new TypeError("review assessment reason.path must be a string");
+	if (typeof detail !== "string") throw new TypeError("review assessment reason.detail must be a string");
+	return Object.freeze({ code, path, detail });
+}
+
+function decodeCandidate(value: unknown): ReviewAssessmentCandidate {
+	if (!isRecord(value)) throw new TypeError("review assessment candidate must be an object");
+	const { kind, base_ref: baseRef } = value;
+	if (kind !== REVIEW_ASSESSMENT_CANDIDATE_KIND.CURRENT_CHANGES && kind !== REVIEW_ASSESSMENT_CANDIDATE_KIND.BASE_DIFF) {
+		throw new TypeError("review assessment candidate.kind must be current-changes or base-diff");
+	}
+	if (baseRef !== undefined && (typeof baseRef !== "string" || baseRef.length === 0)) {
+		throw new TypeError("review assessment candidate.base_ref must be a non-empty string when present");
+	}
+	return Object.freeze({ kind, baseRef: baseRef as string | undefined });
+}
+
+/**
+ * Decodes and validates one `gentle-ai.review-assessment/v1` envelope. Rejects
+ * any other schema, an unrecognized risk value, or a malformed shape -- the
+ * native review CLI wrapper turns a thrown error here into the same
+ * schema-incompatible failure it already produces for every other decoded
+ * native response.
+ */
+export function decodeReviewAssessmentV1(value: unknown): ReviewAssessmentV1 {
+	if (!isRecord(value)) throw new TypeError("review assessment must be an object");
+	if (value.schema !== REVIEW_ASSESSMENT_SCHEMA) throw new TypeError(`review assessment schema must be ${REVIEW_ASSESSMENT_SCHEMA}`);
+	const { risk, reasons, changed_paths: changedPaths, changed_lines: changedLines, candidate } = value;
+	if (risk !== REVIEW_ASSESSMENT_RISK.PASSIVE && risk !== REVIEW_ASSESSMENT_RISK.MEDIUM && risk !== REVIEW_ASSESSMENT_RISK.HIGH) {
+		throw new TypeError("review assessment risk must be passive, medium, or high");
+	}
+	if (!Array.isArray(reasons)) throw new TypeError("review assessment reasons must be an array");
+	if (!Number.isSafeInteger(changedPaths) || (changedPaths as number) < 0) throw new TypeError("review assessment changed_paths must be a non-negative integer");
+	if (!Number.isSafeInteger(changedLines) || (changedLines as number) < 0) throw new TypeError("review assessment changed_lines must be a non-negative integer");
+	return Object.freeze({
+		schema: REVIEW_ASSESSMENT_SCHEMA,
+		risk,
+		reasons: Object.freeze(reasons.map(decodeReason)),
+		changedPaths: changedPaths as number,
+		changedLines: changedLines as number,
+		candidate: decodeCandidate(candidate),
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Verification-plan tiering (gentle-pi#662).
+// ---------------------------------------------------------------------------
+
+export const VERIFICATION_TIER = {
+	PASSIVE: "passive",
+	MEDIUM: "medium",
+	HIGH: "high",
+	UNASSESSABLE: "unassessable",
+} as const;
+export type VerificationTier = (typeof VERIFICATION_TIER)[keyof typeof VERIFICATION_TIER];
+
+export const RDD_LINE = {
+	ON: "on",
+	OFF: "off",
+	UNKNOWN: "unknown",
+} as const;
+export type RddLine = (typeof RDD_LINE)[keyof typeof RDD_LINE];
+
+export const WRITER_PROFILE = {
+	SMALL: "small",
+	LARGE: "large",
+} as const;
+export type WriterProfile = (typeof WRITER_PROFILE)[keyof typeof WRITER_PROFILE];
+
+// gentle-pi#668: whether the native review actually reached a terminal
+// outcome for the current candidate. The `on` branch of `verificationPlan`
+// (the writer self-verifies, the native review is the independent check, no
+// separate verifier) holds only for `CLOSED` -- a human decline for this
+// candidate, a clone-local RDD disable, a refused START/STATUS, or any other
+// non-terminal outcome falls back to the exact same risk-gated path as `off`.
+// `UNKNOWN` is the fail-closed default for an omitted outcome: never treated
+// as `CLOSED`.
+export const NATIVE_REVIEW_OUTCOME = {
+	CLOSED: "closed",
+	DECLINED: "declined",
+	UNAVAILABLE: "unavailable",
+	UNKNOWN: "unknown",
+} as const;
+export type NativeReviewOutcome = (typeof NATIVE_REVIEW_OUTCOME)[keyof typeof NATIVE_REVIEW_OUTCOME];
+
+export interface VerificationPlanInput {
+	readonly rddLine: RddLine;
+	readonly risk: VerificationTier;
+	readonly writerProfile: WriterProfile;
+	/**
+	 * Native review outcome for the current candidate. Only consulted when
+	 * `rddLine` is `"on"`; `"off"`/`"unknown"` lines ignore it entirely.
+	 * Omitted resolves to `NATIVE_REVIEW_OUTCOME.UNKNOWN` (gentle-pi#668).
+	 */
+	readonly nativeReviewOutcome?: NativeReviewOutcome;
+}
+
+export interface VerificationPlan {
+	readonly writerSelfVerification: boolean;
+	readonly structuralReadbackOnly: boolean;
+	readonly independentVerifier: boolean;
+	readonly reason: string;
+}
+
+/**
+ * Builds the risk-gated verification plan shared by the `off`/`unknown` RDD
+ * lines and by an `on` line whose native review did not close for this
+ * candidate (gentle-pi#668). `gatePrefix` supplies the sentence fragment
+ * naming which branch fired, up to and including the word "and"; the
+ * tier-specific clause is appended after it.
+ */
+function riskGatedPlan(gatePrefix: string, risk: VerificationTier, writerProfile: WriterProfile): VerificationPlan {
+	if (risk === VERIFICATION_TIER.PASSIVE) {
+		return Object.freeze({
+			writerSelfVerification: false,
+			structuralReadbackOnly: true,
+			independentVerifier: false,
+			reason: `${gatePrefix} the native assessment reports passive risk: a structural readback by the parent is the complete check, with no separate verifier and no tests.`,
+		});
+	}
+
+	if (risk === VERIFICATION_TIER.MEDIUM) {
+		const smallModelBias = writerProfile === WRITER_PROFILE.SMALL;
+		return Object.freeze({
+			writerSelfVerification: true,
+			structuralReadbackOnly: false,
+			independentVerifier: smallModelBias,
+			reason: smallModelBias
+				? `${gatePrefix} the native assessment reports medium risk, but the small-model bias raises it one tier to high for verification purposes: the writer self-verifies and a separate independent verifier also runs.`
+				: `${gatePrefix} the native assessment reports medium risk with a large writer profile: the writer's self-verification stands and no separate verifier is required.`,
+		});
+	}
+
+	// high or unassessable.
+	return Object.freeze({
+		writerSelfVerification: true,
+		structuralReadbackOnly: false,
+		independentVerifier: true,
+		reason: risk === VERIFICATION_TIER.UNASSESSABLE
+			? `${gatePrefix} the native risk assessment could not be produced, so the candidate is treated as high risk: the writer self-verifies and a separate independent verifier always runs.`
+			: `${gatePrefix} the native assessment reports high risk: the writer self-verifies and a separate independent verifier always runs.`,
+	});
+}
+
+// Names why an `on` line falls back to the risk-gated path, for every
+// non-closed native review outcome (gentle-pi#668). `UNKNOWN` covers both an
+// omitted outcome and a caller-supplied one this decoder does not
+// recognize -- both fail closed the same way.
+function nonClosedOutcomeClause(outcome: NativeReviewOutcome): string {
+	switch (outcome) {
+		case NATIVE_REVIEW_OUTCOME.DECLINED:
+			return "the native review was declined for this candidate";
+		case NATIVE_REVIEW_OUTCOME.UNAVAILABLE:
+			return "the native review is unavailable for this candidate";
+		default:
+			return "the native review outcome for this candidate is unknown";
+	}
+}
+
+/**
+ * Computes who verifies a delegated writer's change, exactly as
+ * gentle-pi#662/#668 specify:
+ *
+ * - `rdd: "on"` AND the native review reached `NATIVE_REVIEW_OUTCOME.CLOSED`
+ *   for this candidate: the writer self-verifies and no independent verifier
+ *   runs, because the closed native review is the check -- except `passive`,
+ *   which gets a structural readback by the parent instead.
+ * - `rdd: "on"` with any other outcome (`declined`, `unavailable`, or the
+ *   fail-closed `unknown` default for an omitted/unrecognized outcome): the
+ *   `on` branch never held for this candidate, so the risk-gated path below
+ *   applies exactly as `off` -- declining a review is candidate-scoped and
+ *   never lowers the bar below the RDD-off path.
+ * - `rdd: "off"` or `"unknown"` (both gate identically, so an unknown RDD line
+ *   never lowers a tier relative to `off`; `nativeReviewOutcome` is ignored
+ *   entirely on these lines):
+ *   - `passive`: structural readback by the parent only; no verifier, no
+ *     tests.
+ *   - `medium`: the writer self-verifies; a separate independent verifier
+ *     runs only when `writerProfile` is `"small"` -- the small-model bias
+ *     raises the tier by one for verification purposes (medium -> high). An
+ *     unknown or omitted writer profile resolves to `"small"` before it
+ *     reaches this function (see `resolveWriterProfile`), so an unrecognized
+ *     profile never lowers a tier below what a known small model would get.
+ *   - `high` or `unassessable` (a failed or unrecognized native assessment is
+ *     always treated as high): the writer self-verifies and an independent
+ *     verifier always runs.
+ */
+export function verificationPlan(input: VerificationPlanInput): VerificationPlan {
+	const { rddLine, risk, writerProfile } = input;
+
+	if (rddLine === RDD_LINE.ON) {
+		const outcome = input.nativeReviewOutcome ?? NATIVE_REVIEW_OUTCOME.UNKNOWN;
+		if (outcome === NATIVE_REVIEW_OUTCOME.CLOSED) {
+			if (risk === VERIFICATION_TIER.PASSIVE) {
+				return Object.freeze({
+					writerSelfVerification: false,
+					structuralReadbackOnly: true,
+					independentVerifier: false,
+					reason: "receipt-driven development is on and the native review closed for this candidate; the assessment also reports passive risk: a structural readback by the parent replaces both the writer's self-verification and any separate verifier.",
+				});
+			}
+			return Object.freeze({
+				writerSelfVerification: true,
+				structuralReadbackOnly: false,
+				independentVerifier: false,
+				reason: "receipt-driven development is on and the native review closed for this candidate: the writer's self-verification is the record and the closed native review was the independent check the writer cannot influence, so no separate verifier is required.",
+			});
+		}
+		// The on branch holds only while the native review reaches a terminal
+		// outcome for this candidate. Anything else -- declined, unavailable, or
+		// unknown -- falls back to the exact same risk-gated path as off.
+		return riskGatedPlan(
+			`receipt-driven development is on, but ${nonClosedOutcomeClause(outcome)}, so the risk-gated path applies exactly as receipt-driven development off, and`,
+			risk,
+			writerProfile,
+		);
+	}
+
+	// rddLine is "off" or "unknown" here -- both gate on the native risk
+	// assessment identically, so an unknown RDD line never lowers a tier, and
+	// neither line ever consults nativeReviewOutcome.
+	return riskGatedPlan(`receipt-driven development is ${rddLine} and`, risk, writerProfile);
+}
+
+// ---------------------------------------------------------------------------
+// Small-writer-profile predicate (gentle-pi#662).
+// ---------------------------------------------------------------------------
+
+/**
+ * The minimal shape of `lib/agents-config.ts`'s `ResolvedProfile` this
+ * predicate needs: the resolved model reference and its resolved effort
+ * (`ResolvedProfile.thinking`, one of `ThinkingLevel`).
+ */
+export interface WriterModelProfileLike {
+	readonly model?: { readonly id: string } | undefined;
+	readonly thinking?: string | undefined;
+}
+
+// Matches `mini` only as a whole token of the model id -- delimited by the
+// string start/end or one of `-_./:` or whitespace -- never a bare substring.
+// `gpt-5.4-mini`, `o4-mini`, `openai/gpt-5.4-mini`, `claude-mini`, and
+// `mini-high` all match; `gemini`, `gemini-2.5-pro`, and `gemini-2.5-flash`
+// do not, because their `mini` is preceded by `ge`, not a delimiter.
+const SMALL_MODEL_ID_TOKEN = /(?:^|[-_./:\s])mini(?:$|[-_./:\s])/i;
+
+/**
+ * A writer profile counts as a "small model" for the medium-risk bias when:
+ * - its resolved effort is `low`, or
+ * - its resolved model id carries `mini` as a whole token (see
+ *   `SMALL_MODEL_ID_TOKEN`), or
+ * - it carries NO signal at all -- no profile object, or a profile with
+ *   neither a model id nor a resolved effort. An unknown or omitted writer
+ *   profile fails closed to small rather than defaulting to large, so a
+ *   caller that cannot resolve the writer's profile never gets a weaker
+ *   verification plan than a known small model would (gentle-pi#662).
+ *
+ * A profile that carries a model id or an effort, just not a matching one
+ * (for example `{model: {id: "claude-sonnet-5"}, thinking: "high"}`), is
+ * "known large" and returns `false` -- fail-closed applies only to a truly
+ * unknown/omitted profile, not to an explicitly resolved large one.
+ */
+export function isSmallWriterProfile(profile: WriterModelProfileLike | undefined): boolean {
+	if (profile === undefined) return true;
+	if (profile.thinking === "low") return true;
+	const modelId = profile.model?.id;
+	if (typeof modelId === "string") return SMALL_MODEL_ID_TOKEN.test(modelId);
+	// No model id was resolved. Fail closed to small only when effort is also
+	// unknown -- there is no signal at all to call this a known large model.
+	return profile.thinking === undefined;
+}
+
+/**
+ * Maps a resolved writer profile to the `writerProfile` input `verificationPlan`
+ * expects. An unknown or omitted profile never lowers a tier: it resolves to
+ * `"small"`, exactly like `isSmallWriterProfile` (gentle-pi#662).
+ */
+export function resolveWriterProfile(profile: WriterModelProfileLike | undefined): WriterProfile {
+	return isSmallWriterProfile(profile) ? WRITER_PROFILE.SMALL : WRITER_PROFILE.LARGE;
+}

package/lib/review-session-standing-permission-ipc.ts

@@ -0,0 +1,309 @@
+import { Socket } from "node:net";
+import type { Readable, Writable } from "node:stream";
+
+// This is a deliberately tiny parent-owned channel for package-launched Pi
+// children. It carries only a one-shot authorization question and answer; no
+// review candidate, consent binding, provider vector, or session authority is
+// serialized across the process boundary.
+
+const REQUEST_TYPE = "standing-review-permission-request";
+const RESPONSE_TYPE = "standing-review-permission-response";
+const MAX_LINE_BYTES = 4096;
+const DEFAULT_MAX_REQUESTS = 16;
+export const CHILD_STANDING_REVIEW_PERMISSION_REGISTRY_SCHEMA = "gentle-pi.child-standing-review-permission/v1";
+export const CHILD_STANDING_REVIEW_PERMISSION_REGISTRY_SYMBOL = Symbol.for(CHILD_STANDING_REVIEW_PERMISSION_REGISTRY_SCHEMA);
+export const CHILD_STANDING_REVIEW_PERMISSION_CLIENT_SCHEMA = "gentle-pi.child-standing-review-permission-client/v1";
+
+export interface ChildStandingReviewPermissionClientHandle {
+	readonly schema: typeof CHILD_STANDING_REVIEW_PERMISSION_CLIENT_SCHEMA;
+	requestAuthorization(repositoryIdentity: string): Promise<boolean>;
+	close(): void;
+}
+
+interface ChildPermissionRegistry {
+	readonly schema: typeof CHILD_STANDING_REVIEW_PERMISSION_REGISTRY_SCHEMA;
+	client: ChildStandingReviewPermissionClientHandle | undefined;
+	owner: symbol | undefined;
+	terminal: boolean;
+}
+
+type GlobalRegistry = Record<symbol, unknown>;
+
+function isChildPermissionClient(value: unknown): value is ChildStandingReviewPermissionClientHandle {
+	return typeof value === "object" && value !== null &&
+		(value as { schema?: unknown }).schema === CHILD_STANDING_REVIEW_PERMISSION_CLIENT_SCHEMA &&
+		typeof (value as { requestAuthorization?: unknown }).requestAuthorization === "function" &&
+		typeof (value as { close?: unknown }).close === "function";
+}
+
+function childPermissionRegistry(): ChildPermissionRegistry | undefined {
+	const globalRegistry = globalThis as GlobalRegistry;
+	const current = globalRegistry[CHILD_STANDING_REVIEW_PERMISSION_REGISTRY_SYMBOL];
+	if (current === undefined) {
+		const created: ChildPermissionRegistry = { schema: CHILD_STANDING_REVIEW_PERMISSION_REGISTRY_SCHEMA, client: undefined, owner: undefined, terminal: false };
+		globalRegistry[CHILD_STANDING_REVIEW_PERMISSION_REGISTRY_SYMBOL] = created;
+		return created;
+	}
+	if (
+		typeof current !== "object" || current === null ||
+		(current as { schema?: unknown }).schema !== CHILD_STANDING_REVIEW_PERMISSION_REGISTRY_SCHEMA ||
+		typeof (current as { terminal?: unknown }).terminal !== "boolean" ||
+		!((current as { client?: unknown }).client === undefined || isChildPermissionClient((current as { client?: unknown }).client)) ||
+		!((current as { owner?: unknown }).owner === undefined || typeof (current as { owner?: unknown }).owner === "symbol")
+	) return undefined;
+	return current as ChildPermissionRegistry;
+}
+
+export interface StandingReviewPermissionChannel {
+	readonly readable: Readable;
+	readonly writable: Writable;
+}
+
+interface Request {
+	type: typeof REQUEST_TYPE;
+	id: string;
+	repositoryIdentity: string;
+}
+
+interface Response {
+	type: typeof RESPONSE_TYPE;
+	id: string;
+	granted: boolean;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function request(value: unknown): Request | undefined {
+	if (
+		!isRecord(value) ||
+		Object.keys(value).length !== 3 ||
+		value.type !== REQUEST_TYPE ||
+		typeof value.id !== "string" || value.id.length === 0 || value.id.length > 128 ||
+		typeof value.repositoryIdentity !== "string" || !/^sha256:[0-9a-f]{64}$/.test(value.repositoryIdentity)
+	) return undefined;
+	return { type: REQUEST_TYPE, id: value.id, repositoryIdentity: value.repositoryIdentity };
+}
+
+function response(value: unknown): Response | undefined {
+	if (!isRecord(value) || value.type !== RESPONSE_TYPE || typeof value.id !== "string" || typeof value.granted !== "boolean") return undefined;
+	return { type: RESPONSE_TYPE, id: value.id, granted: value.granted };
+}
+
+function attachJsonLines(stream: Readable, onValue: (value: unknown) => void): () => void {
+	let buffer = "";
+	const onData = (chunk: Buffer | string) => {
+		buffer += chunk.toString();
+		if (buffer.length > MAX_LINE_BYTES) {
+			buffer = "";
+			return;
+		}
+		const lines = buffer.split("\n");
+		buffer = lines.pop() ?? "";
+		for (const raw of lines) {
+			const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+			if (line.length === 0 || Buffer.byteLength(line) > MAX_LINE_BYTES) continue;
+			try { onValue(JSON.parse(line)); } catch { /* Malformed child traffic is denied by silence. */ }
+		}
+	};
+	stream.on("data", onData);
+	return () => stream.off("data", onData);
+}
+
+function write(channel: Writable, value: Response | Request): boolean {
+	try {
+		return channel.write(`${JSON.stringify(value)}\n`);
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * The parent binds this broker to one live AgentRunner task. Every request
+ * calls `authorize` again, so replacement, revocation, cancellation, and a
+ * dead parent session fail closed without trusting child environment state.
+ */
+export class ParentStandingReviewPermissionBroker {
+	private closed = false;
+	private acceptedRequests = 0;
+	private readonly channel: StandingReviewPermissionChannel;
+	private readonly detach: () => void;
+	private readonly authorize: (repositoryIdentity: string) => Promise<boolean> | boolean;
+	private readonly maxRequests: number;
+	private readonly onChannelTerminal = () => this.close();
+
+	constructor(channel: StandingReviewPermissionChannel, authorize: (repositoryIdentity: string) => Promise<boolean> | boolean, options: { maxRequests?: number } = {}) {
+		this.channel = channel;
+		this.authorize = authorize;
+		this.maxRequests = Number.isSafeInteger(options.maxRequests) && options.maxRequests! > 0 ? options.maxRequests! : DEFAULT_MAX_REQUESTS;
+		// These listeners deliberately outlive detach(): late pipe errors can arrive
+		// after close and must stay confined to this task's broker.
+		channel.readable.on("error", this.onChannelTerminal);
+		channel.readable.on("close", this.onChannelTerminal);
+		channel.readable.on("end", this.onChannelTerminal);
+		channel.writable.on("error", this.onChannelTerminal);
+		channel.writable.on("close", this.onChannelTerminal);
+		this.detach = attachJsonLines(channel.readable, (value) => {
+			const incoming = request(value);
+			if (incoming === undefined || this.closed) return;
+			if (this.acceptedRequests >= this.maxRequests) {
+				this.respond({ type: RESPONSE_TYPE, id: incoming.id, granted: false });
+				return;
+			}
+			this.acceptedRequests += 1;
+			void Promise.resolve(this.authorize(incoming.repositoryIdentity))
+				.then((granted) => {
+					this.respond({ type: RESPONSE_TYPE, id: incoming.id, granted: granted === true });
+				})
+				.catch(() => {
+					this.respond({ type: RESPONSE_TYPE, id: incoming.id, granted: false });
+				});
+		});
+	}
+
+	close(): void {
+		if (this.closed) return;
+		this.closed = true;
+		this.detach();
+	}
+
+	private respond(value: Response): void {
+		if (this.closed || this.channel.writable.destroyed || this.channel.writable.writableEnded) return;
+		try {
+			this.channel.writable.write(`${JSON.stringify(value)}\n`, (error) => {
+				if (error !== undefined && error !== null) this.close();
+			});
+		} catch {
+			this.close();
+		}
+	}
+}
+
+function configuredChildPermissionRegistry(processEnv: NodeJS.ProcessEnv): ChildPermissionRegistry | undefined {
+	if (processEnv.GENTLE_PI_AGENTS_CHILD !== "1" || processEnv.GENTLE_PI_AGENTS_PARENT_PERMISSION_FD !== "3") return undefined;
+	return childPermissionRegistry();
+}
+
+function registryClient(state: ChildPermissionRegistry): ChildStandingReviewPermissionClientHandle | undefined {
+	if (state.terminal) return undefined;
+	if (state.client !== undefined) return state.client;
+	try {
+		// Node exposes stdin/out/err but not a process.stdio array. The package
+		// runner creates fd 3 as an inherited duplex pipe; wrap it once for this
+		// process and let reload closures share the same reader and request state.
+		const stream = new Socket({ fd: 3, readable: true, writable: true });
+		let record: ChildStandingReviewPermissionClientHandle | undefined;
+		const client = new ChildStandingReviewPermissionClient({ readable: stream, writable: stream }, {}, () => {
+			state.terminal = true;
+			if (state.client === record) state.client = undefined;
+		});
+		record = {
+			schema: CHILD_STANDING_REVIEW_PERMISSION_CLIENT_SCHEMA,
+			requestAuthorization: (repositoryIdentity) => client.requestAuthorization(repositoryIdentity),
+			close: () => client.close(),
+		};
+		state.client = record;
+		return record;
+	} catch {
+		// An absent or incompatible inherited descriptor is never authorization.
+		return undefined;
+	}
+}
+
+/** The child can ask only whether its parent currently permits a replay. */
+export function createChildStandingReviewPermissionClient(
+	processEnv: NodeJS.ProcessEnv = process.env,
+): ChildStandingReviewPermissionClientHandle | undefined {
+	const state = configuredChildPermissionRegistry(processEnv);
+	return state === undefined ? undefined : registryClient(state);
+}
+
+export interface ChildStandingReviewPermissionLease {
+	readonly client: ChildStandingReviewPermissionClientHandle | undefined;
+	closeIfCurrent(): void;
+}
+
+/** A replacement extension becomes the sole terminal owner of the shared fd3 client. */
+export function acquireChildStandingReviewPermissionClient(
+	processEnv: NodeJS.ProcessEnv = process.env,
+): ChildStandingReviewPermissionLease | undefined {
+	const state = configuredChildPermissionRegistry(processEnv);
+	if (state === undefined) return undefined;
+	const client = registryClient(state);
+	if (client === undefined) return { client: undefined, closeIfCurrent() {} };
+	const owner = Symbol("child-standing-review-permission-owner");
+	state.owner = owner;
+	return {
+		client,
+		closeIfCurrent() {
+			if (state.owner !== owner) return;
+			state.owner = undefined;
+			client.close();
+		},
+	};
+}
+
+export class ChildStandingReviewPermissionClient {
+	private closed = false;
+	private nextId = 0;
+	private pending: { id: string; resolve: (granted: boolean) => void; cancel: () => void } | undefined;
+	private readonly detach: () => void;
+	private readonly onClosed = () => {
+		this.closed = true;
+		this.failPending();
+		this.onTerminal();
+	};
+	private readonly channel: StandingReviewPermissionChannel;
+	private readonly options: { timeoutMs?: number };
+	private readonly onTerminal: () => void;
+
+	constructor(channel: StandingReviewPermissionChannel, options: { timeoutMs?: number } = {}, onTerminal: () => void = () => {}) {
+		this.channel = channel;
+		this.options = options;
+		this.onTerminal = onTerminal;
+		this.detach = attachJsonLines(channel.readable, (value) => {
+			const incoming = response(value);
+			const pending = this.pending;
+			if (incoming === undefined || pending === undefined || incoming.id !== pending.id) return;
+			this.pending = undefined;
+			pending.cancel();
+			pending.resolve(incoming.granted);
+		});
+		channel.readable.once("close", this.onClosed);
+		channel.readable.once("end", this.onClosed);
+		channel.readable.once("error", this.onClosed);
+	}
+
+	requestAuthorization(repositoryIdentity: string): Promise<boolean> {
+		if (this.closed || this.pending !== undefined || !/^sha256:[0-9a-f]{64}$/.test(repositoryIdentity)) return Promise.resolve(false);
+		this.nextId += 1;
+		const id = `p${this.nextId}`;
+		return new Promise((resolve) => {
+			const timeout = setTimeout(() => this.failPending(), this.options.timeoutMs ?? 5_000);
+			timeout.unref?.();
+			this.pending = { id, resolve, cancel: () => clearTimeout(timeout) };
+			if (!write(this.channel.writable, { type: REQUEST_TYPE, id, repositoryIdentity })) this.failPending();
+		});
+	}
+
+	close(): void {
+		if (this.closed) return;
+		this.closed = true;
+		this.detach();
+		this.channel.readable.off("close", this.onClosed);
+		this.channel.readable.off("end", this.onClosed);
+		this.channel.readable.off("error", this.onClosed);
+		this.failPending();
+		this.onTerminal();
+		try { this.channel.readable.destroy(); } catch { /* Closing an unavailable child fd is best effort. */ }
+	}
+
+	private failPending(): void {
+		const pending = this.pending;
+		if (pending === undefined) return;
+		this.pending = undefined;
+		pending.cancel();
+		pending.resolve(false);
+	}
+}