// gentle-pi.review-relay/v1 — the Pi host relay handshake (gentle-pi#311 P4,
// provider side gentle-ai#3249/#3254).
//
// gentle-ai admits `pi` as a host-mediated runtime identity only when the
// launcher that relays the invocation declares this exact contract through
// this exact environment variable. Any other value (or none) keeps Pi
// fail-closed at admission, before any repository, target, or authority work.
// That refusal is correct provider behavior and is never worked around here;
// the single central gentle-ai process runner injects this declaration on
// every invocation the extension makes.
//
// Both values are compiled constants: the contract identity is versioned by
// release, never by configuration.

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: NodeJS.ProcessEnv): boolean {
	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;
}