@gajae-code/coding-agent 0.18.12 → 0.19.0

package/src/sdk/broker/broker.ts

@@ -117,7 +117,7 @@ import {
 } from "./managed-task-dag";
 import { reconcileRunningManagedVerification, verifyManagedTaskAttempt } from "./managed-task-verification";
 import { createMasterCapabilityVerifier, readEndpoint } from "./master-capability";
-import { isProcessIncarnation } from "./process-incarnation";
+import { isProcessIncarnation, observeProcessIncarnation } from "./process-incarnation";
 import { sdkInternalRuntimeImage } from "./runtime";
 import {
 	type IndexedSession,
@@ -165,6 +165,21 @@ export interface BrokerSettings {
 	masterCapabilityVerifier?: MasterCapabilityVerifier;
 	/** Grace before an orphaned spawn child closes; schema-bounded in production. */
 	masterOrphanGraceMs?: number;
+	/**
+	 * Grace before a broker nobody is left to use exits on its own. The clock only
+	 * runs while the index proves no live session host and no open spawn authority,
+	 * so a broker whose client died without closing exits instead of holding its
+	 * port, its publication, and its lock for the life of the machine.
+	 */
+	abandonedGraceMs?: number;
+	/**
+	 * Whether this broker may end itself once nobody is left to use it. Only the
+	 * detached autostart entry point enables this: an operator-supervised
+	 * `gjc sdk broker run` service owns its own lifetime, and its supervisor reads an
+	 * owned-root completion as a clean exit, so self-reaping would quietly retire a
+	 * service that was meant to keep serving.
+	 */
+	reapWhenAbandoned?: boolean;
 	/** Host model resolver override for lifecycle tests and embedders. */
 	resolveModelPin?: SdkHostModelResolver;
 	/**
@@ -202,6 +217,8 @@ type ResolvedBrokerSettings = {
 	spawnSubstrateProvider?: SpawnSubstrateProvider;
 	spawnPromptLayer?: SpawnPromptLayer;
 	masterOrphanGraceMs: number;
+	abandonedGraceMs: number;
+	reapWhenAbandoned: boolean;
 	restartRequestId?: string;
 };
 export function resolveBrokerPackageGeneration(): string {
@@ -227,6 +244,7 @@ function modelResolutionCwd(input: Record<string, unknown>): string | undefined
 
 export type BrokerErrorCode =
 	| "idempotency_conflict"
+	| "legacy_lifecycle_ambiguous"
 	| "terminal_uncertain"
 	| "broker_restarting"
 	| "unavailable"
@@ -623,6 +641,7 @@ const SPAWN_HOST_REGISTRATION_TIMEOUT_MS = 10_000;
 const SPAWN_HOST_REGISTRATION_POLL_MS = 50;
 const SPAWN_PROMPT_EXCHANGE_TIMEOUT_MS = 10_000;
 const MASTER_ORPHAN_GRACE_DEFAULT_MS = 120_000;
+const BROKER_ABANDONED_GRACE_DEFAULT_MS = 120_000;
 const MANAGED_CLOSE_WAIT_MS = 10_000;
 
 function settlesWithin(promise: Promise<unknown>, timeoutMs: number): Promise<boolean> {
@@ -1602,6 +1621,7 @@ const brokerLockReclaimHooksForTest = new WeakMap<
 	{ beforeQuarantine?: () => Promise<void>; onContended?: () => void }
 >();
 const livenessGraceOverridesForTest = new WeakMap<Broker, number>();
+const abandonedGraceOverridesForTest = new WeakMap<Broker, number>();
 const heartbeatStallOverridesForTest = new WeakMap<Broker, PromiseWithResolvers<void>>();
 const managedCloseWaitOverridesForTest = new WeakMap<Broker, number>();
 
@@ -1644,6 +1664,8 @@ export class Broker {
 	#publishedAt: bigint | null = null;
 	#startedAt: bigint | null = null;
 	#watchInFlight = false;
+	#abandonedAt: number | null = null;
+	#abandonedReapInFlight = false;
 	#checkpointInFlight = false;
 	#stopping = false;
 	#transport: BrokerTransport | null = null;
@@ -1683,6 +1705,8 @@ export class Broker {
 			spawnSubstrateProvider: settings.spawnSubstrateProvider,
 			spawnPromptLayer: settings.spawnPromptLayer,
 			masterOrphanGraceMs: settings.masterOrphanGraceMs ?? MASTER_ORPHAN_GRACE_DEFAULT_MS,
+			abandonedGraceMs: settings.abandonedGraceMs ?? BROKER_ABANDONED_GRACE_DEFAULT_MS,
+			reapWhenAbandoned: settings.reapWhenAbandoned === true,
 			...(settings.restartRequestId === undefined ? {} : { restartRequestId: settings.restartRequestId }),
 		};
 		this.index = new SessionIndex(settings.agentDir);
@@ -3656,6 +3680,96 @@ export class Broker {
 		await this.#reapSpawnOrphans();
 	}
 
+	/**
+	 * Grace before an idle broker exits. The clock starts only after the index has
+	 * already stopped proving any host live, so this grace is time on top of that
+	 * freshness window, never a substitute for it.
+	 */
+	#abandonedGraceMs(): number {
+		return abandonedGraceOverridesForTest.get(this) ?? this.settings.abandonedGraceMs;
+	}
+
+	/**
+	 * What the index proves about the hosts using this agent directory. Liveness is
+	 * judged on read -- fresh checkpoint, live pid, matching incarnation -- so a host
+	 * that died without closing stops proving it without help. A row that is not live
+	 * is absence only once the OS confirms the process is gone: an inconclusive
+	 * reading is never death proof on any platform, and a pid that still exists but
+	 * cannot be matched to the recorded incarnation leaves the host undecided.
+	 */
+	async #sessionHostLiveness(): Promise<"live" | "absent" | "unknown"> {
+		try {
+			await this.index.refreshIfChanged();
+		} catch (error) {
+			logger.warn(`sdk broker: abandonment probe could not read the session index: ${String(error)}`);
+			return "unknown";
+		}
+		for (const row of this.index.listSessionIdentities()) {
+			if (row.endpointGeneration <= 0) continue;
+			if (row.live) return "live";
+			// The tri-state observer keeps positive absence separate from every
+			// inconclusive outcome, which is the difference between reaping a broker and
+			// killing one out from under a host this platform simply cannot confirm.
+			const observed = observeProcessIncarnation(row.pid);
+			if (observed.status === "unknown") return "unknown";
+			if (observed.status === "absent") continue;
+			const recorded = row.hostIncarnation ?? row.processIncarnation;
+			if (recorded === undefined) return "unknown";
+			if (observed.incarnation === recorded) return "live";
+			// The pid names another process now: the host that registered it is gone.
+		}
+		return "absent";
+	}
+
+	/** Whether any client currently holds a transport connection to this broker. */
+	#hasAttachedClient(): boolean {
+		return (this.#transport?.clientCount ?? 0) > 0;
+	}
+
+	/** Whether this broker still owns a spawn authority it must keep serving. */
+	#hasOpenSpawnAuthority(): boolean {
+		const store = this.#spawnAuthority;
+		if (!store) return false;
+		for (const claim of store.claims()) {
+			const authority = store.authority(claim.lifecycleIdentity);
+			if (authority && (authority.closeState === "active" || authority.closeState === "close_requested"))
+				return true;
+		}
+		return false;
+	}
+
+	/**
+	 * Ends a broker nobody is left to use. A client that dies without closing leaves
+	 * no live session host behind, and nothing else reaps this process: without this
+	 * pass it would hold its port, its publication, and its lock until the machine
+	 * reboots. The clock only runs while absence is confirmed and no client holds a
+	 * connection, and any live host, attached client, open authority, or undecided
+	 * reading disarms it, so a slow reattach never races the grace. Brokers an
+	 * operator supervises never reap themselves at all.
+	 */
+	async #reapSelfIfAbandoned(): Promise<void> {
+		if (!this.settings.reapWhenAbandoned) return;
+		if (this.#stopping || this.#completionTask !== null || this.#fenceReason !== null) return;
+		if (this.#abandonedReapInFlight) return;
+		this.#abandonedReapInFlight = true;
+		try {
+			const liveness = await this.#sessionHostLiveness();
+			const now = Date.now();
+			if (liveness !== "absent" || this.#hasAttachedClient() || this.#hasOpenSpawnAuthority()) {
+				this.#abandonedAt = null;
+				return;
+			}
+			if (this.#abandonedAt === null) {
+				this.#abandonedAt = now;
+				return;
+			}
+			if (now - this.#abandonedAt < this.#abandonedGraceMs()) return;
+			await this.#complete(this.#provenOwnedRoot() ? "owned-root" : "lost-root", "abandoned");
+		} finally {
+			this.#abandonedReapInFlight = false;
+		}
+	}
+
 	async #reapSpawnOrphans(): Promise<void> {
 		if (this.#spawnReapInFlight || this.#stopping) return;
 		this.#spawnReapInFlight = true;
@@ -4005,6 +4119,11 @@ export class Broker {
 		this.#ownedLockIncarnation = undefined;
 		this.#watchInFlight = false;
 		this.#checkpointInFlight = false;
+		// A restarted instance is a new generation: it holds none of the state the
+		// previous one stopped with, so the abandonment clock it armed (and any reap
+		// still unwinding) must not survive into the generation clients reconnect to.
+		this.#abandonedAt = null;
+		this.#abandonedReapInFlight = false;
 		this.#throwIfStartupAborted();
 		await Promise.all([this.ledger.assertSupportedStateVersions(), readBrokerDiscovery(this.settings.agentDir)]);
 		this.#throwIfStartupAborted();
@@ -4178,6 +4297,7 @@ export class Broker {
 			this.#heartbeatTimer = setInterval(() => {
 				void this.#watchPublication();
 				void this.#reapSpawnOrphans();
+				void this.#reapSelfIfAbandoned();
 			}, cadenceMs);
 			if (this.#startupPostPublicationDelayMs > 0) await Bun.sleep(this.#startupPostPublicationDelayMs);
 			// This process is now the independently verified successor: its own
@@ -4227,6 +4347,10 @@ export class Broker {
 			this.discovery?.ownerId === this.#owner
 		);
 	}
+	/** Whether this broker completed its initial retained discovery publication. */
+	get hasPublishedDiscovery(): boolean {
+		return this.#publishedAt !== null;
+	}
 	get completion(): Promise<void> {
 		return this.#completion;
 	}
@@ -5348,7 +5472,7 @@ export class Broker {
 						},
 					)
 				) {
-					return error("idempotency_conflict", "legacy lifecycle request has an ambiguous target");
+					return error("legacy_lifecycle_ambiguous", "legacy lifecycle request has an ambiguous target");
 				}
 			}
 		}
@@ -5424,6 +5548,9 @@ export class Broker {
 			const begun = await this.ledger.begin(identity, requestHash, metadata);
 			if (begun.kind === "replay") {
 				const replay = begun.entry.response as BrokerResponse;
+				// Proven errors are immutable even when their response carries cleanup
+				// metadata. Only unproven cleanup outcomes may execute again.
+				if (begun.entry.state === "terminal_error") return replay;
 				const cleanup = cleanupFromResponse(replay) ?? reconstructedDeleteCleanup;
 				if (!cleanup) {
 					if (
@@ -5468,7 +5595,7 @@ export class Broker {
 				const outcome = await executeLifecycle(this, operation, input, identity, cleanup);
 				const response = outcome.response;
 				const storedResponse = credentialFreeLifecycleResponse(response) as BrokerResponse;
-				await this.ledger.transition(identity, lifecycleResponseState(response), {
+				const recorded = await this.ledger.transition(identity, lifecycleResponseState(response), {
 					...(operation === "session.delete" &&
 					typeof input.sessionId === "string" &&
 					lifecycleResponseState(response) === "terminal_uncertain" &&
@@ -5480,6 +5607,10 @@ export class Broker {
 					...(outcome.durableEffects ? { durableEffects: outcome.durableEffects } : {}),
 					...(outcome.startupFailure ? { startupFailure: outcome.startupFailure } : {}),
 				});
+				// A late transition may have proven a terminal result already. The ledger
+				// preserves that row; return it instead of the freshly computed response.
+				if (recorded.state === "terminal_error" && recorded.response !== undefined)
+					return recorded.response as BrokerResponse;
 				return response;
 			}
 			if (begun.kind === "idempotency_conflict")
@@ -5492,7 +5623,7 @@ export class Broker {
 				const outcome = await executeLifecycle(this, operation, input, identity, cleanup);
 				const response = outcome.response;
 				const storedResponse = credentialFreeLifecycleResponse(response) as BrokerResponse;
-				await this.ledger.transition(identity, lifecycleResponseState(response), {
+				const recorded = await this.ledger.transition(identity, lifecycleResponseState(response), {
 					...(pendingCleanupSessionId(response) ? { intendedSessionId: pendingCleanupSessionId(response) } : {}),
 					...(operation === "session.delete" &&
 					typeof input.sessionId === "string" &&
@@ -5505,6 +5636,8 @@ export class Broker {
 					...(outcome.durableEffects ? { durableEffects: outcome.durableEffects } : {}),
 					...(outcome.startupFailure ? { startupFailure: outcome.startupFailure } : {}),
 				});
+				if (recorded.state === "terminal_error" && recorded.response !== undefined)
+					return recorded.response as BrokerResponse;
 				return response;
 			}
 			if (begun.kind === "in_progress") return error("broker_restarting", "lifecycle operation is in progress");
@@ -5601,6 +5734,12 @@ export function setBrokerLockReclaimHooksForTest(
 	else brokerLockReclaimHooksForTest.set(broker, hooks);
 }
 
+/** Test-only hook for shortening the bounded abandonment grace. */
+export function setAbandonedGraceForTest(broker: Broker, graceMs: number | undefined): void {
+	if (graceMs === undefined) abandonedGraceOverridesForTest.delete(broker);
+	else abandonedGraceOverridesForTest.set(broker, graceMs);
+}
+
 /** Test-only hook for shortening the bounded liveness deadline. */
 export function setLivenessGraceForTest(broker: Broker, graceMs: number | undefined): void {
 	if (graceMs === undefined) livenessGraceOverridesForTest.delete(broker);

package/src/sdk/broker/ensure.ts

@@ -4,6 +4,7 @@ import type { FileHandle } from "node:fs/promises";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import path from "node:path";
+import { type ProjectEnvSnapshot, projectEnvSnapshot } from "@gajae-code/utils/env-file";
 import { nativeProcessBindings } from "@gajae-code/utils/native-process";
 import packageJson from "../../../package.json" with { type: "json" };
 import {
@@ -12,6 +13,7 @@ import {
 	type FileLockOptions,
 	withFileLock,
 } from "../../config/file-lock";
+import { trustedCoordinatorEnv } from "../../gjc-runtime/sidecar-bootstrap-env";
 import { SdkClient, SdkClientError } from "../client/client";
 import { type BrokerStartupExitRecord, clearBrokerStartupExitRecord, readBrokerStartupExitRecord } from "./broker-exit";
 import {
@@ -726,13 +728,64 @@ export interface BrokerStartupLockOptions {
 	onContended?: () => void;
 }
 
+const BROKER_TEST_SIGNAL_DIR_ENV = "GJC_SDK_TEST_BROKER_SIGNAL_DIR";
+/** Bound the project dotenv read. A FIFO or a larger file is incomplete and rejected. */
+const BROKER_SIGNAL_DOTENV_MAX_BYTES = 64 * 1024;
+
+/**
+ * Dotenv from the cwd that first loaded this module. `launch --worktree` changes
+ * cwd after Bun has already copied that file into `process.env`.
+ */
+const startupBrokerSignalSnapshot = projectEnvSnapshot(process.cwd(), {
+	maxFileBytes: BROKER_SIGNAL_DOTENV_MAX_BYTES,
+});
+
+function brokerSignalSnapshots(override?: readonly ProjectEnvSnapshot[]): readonly ProjectEnvSnapshot[] {
+	if (override) return override;
+	return [
+		projectEnvSnapshot(process.cwd(), { maxFileBytes: BROKER_SIGNAL_DOTENV_MAX_BYTES }),
+		startupBrokerSignalSnapshot,
+	];
+}
+
+/**
+ * Operator environment only. A directory declared by the project dotenv is
+ * ignored so startup cannot create a path the repository chose.
+ * No signal value means no later dotenv read, so an unused seam cannot stall startup.
+ * An incomplete startup or cwd snapshot rejects the value.
+ */
+function trustedBrokerTestSignalDirectory(
+	env: NodeJS.ProcessEnv,
+	snapshots?: readonly ProjectEnvSnapshot[],
+): string | undefined {
+	const raw = env[BROKER_TEST_SIGNAL_DIR_ENV];
+	if (!raw) return undefined;
+	let accepted: string | undefined;
+	for (const snapshot of brokerSignalSnapshots(snapshots)) {
+		if (snapshot.incomplete) return undefined;
+		const trusted = trustedCoordinatorEnv(BROKER_TEST_SIGNAL_DIR_ENV, env, snapshot);
+		if (trusted === undefined) return undefined;
+		accepted = trusted;
+	}
+	return accepted;
+}
+
+/** Drop a project-dotenv signal directory. Keep a trusted directory as the value that was accepted. */
+function scrubUntrustedBrokerTestSignalDirectory(environment: NodeJS.ProcessEnv): void {
+	const trusted = trustedBrokerTestSignalDirectory(environment);
+	for (const name of Object.keys(environment)) {
+		if (name.toUpperCase() === BROKER_TEST_SIGNAL_DIR_ENV) delete environment[name];
+	}
+	if (trusted !== undefined) environment[BROKER_TEST_SIGNAL_DIR_ENV] = trusted;
+}
+
 /**
  * Test-only phase observation for detached broker startup regressions. The
- * signal is opt-in through the child environment and never affects broker
- * ownership or error handling when the test seam is absent.
+ * directory is opt-in through a trusted operator environment and never affects
+ * broker ownership or error handling when the seam is absent.
  */
 export async function emitBrokerStartupTestSignal(signal: string): Promise<void> {
-	const directory = process.env.GJC_SDK_TEST_BROKER_SIGNAL_DIR;
+	const directory = trustedBrokerTestSignalDirectory(process.env);
 	if (!directory || !/^[a-z0-9-]+$/.test(signal)) return;
 	try {
 		await fs.mkdir(directory, { recursive: true, mode: 0o700 });
@@ -1203,11 +1256,11 @@ function registerBrokerOwner(
 					handoff = undefined;
 				} else if (publishedDiscovery) {
 					try {
-						await shutdownPublishedBrokerViaRpc(
-							agentDir,
+						await shutdownBrokerViaRpc(
 							publishedDiscovery,
 							Date.now() +
 								Math.max(BROKER_DISCOVERY_BUDGET.staleRetirementMs, timing.gracefulMs + timing.killVerifyMs),
+							agentDir,
 						);
 					} catch (error) {
 						if (process.platform === "darwin" && expectedBrokerPid !== child.pid) throw error;
@@ -1270,6 +1323,7 @@ function brokerSpawnEnvironment(command: SdkInternalSpawnCommand, override?: Nod
 		delete environment.PI_COMPILED;
 		delete environment.GJC_COMPILED;
 	}
+	scrubUntrustedBrokerTestSignalDirectory(environment);
 	return environment;
 }
 
@@ -1343,9 +1397,15 @@ async function shutdownPublishedBrokerViaRpc(
 		else await waitForBrokerIdentityGone(discovery, deadline);
 		return;
 	}
+	await shutdownBrokerViaRpc(current, deadline, agentDir);
+}
+
+/** Stop a broker whose authenticated discovery was retained by its local owner. */
+async function shutdownBrokerViaRpc(discovery: BrokerDiscovery, deadline: number, agentDir: string): Promise<void> {
+	if (brokerIdentityIsGone(discovery)) return;
 	const remainingMs = deadline - ensureBrokerTiming.now();
 	if (remainingMs <= 0) throw new Error("SDK broker shutdown deadline elapsed before RPC connection.");
-	const client = await SdkClient.connect(current.url, current.token, {
+	const client = await SdkClient.connect(discovery.url, discovery.token, {
 		timeoutMs: Math.max(1, Math.min(2_000, remainingMs)),
 	});
 	try {
@@ -1954,6 +2014,14 @@ export function signalDetachedBrokerProcessForTest(
 ): boolean {
 	return signalDetachedBrokerProcess(pid, brokerIncarnation, signal, platform);
 }
+/** Test hook: the signal directory accepted from this environment and snapshot. */
+export function trustedBrokerSignalDirectoryForTest(
+	env: NodeJS.ProcessEnv,
+	snapshot: ProjectEnvSnapshot | readonly ProjectEnvSnapshot[],
+): string | undefined {
+	const snapshots = Array.isArray(snapshot) ? snapshot : [snapshot];
+	return trustedBrokerTestSignalDirectory(env, snapshots);
+}
 /** Test hook: resolves the complete broker environment without spawning. */
 export function brokerSpawnEnvironmentForTest(
 	command: SdkInternalSpawnCommand,

package/src/sdk/broker/hop.ts

@@ -7,9 +7,18 @@ import type { Process } from "@gajae-code/natives";
 import { nativeProcessBindings } from "@gajae-code/utils/native-process";
 import type { BrokerHopMessage } from "./ensure";
 
+/** Handoff protocol frames written to the trampoline's stdin. */
 export const BROKER_HANDOFF_ACKNOWLEDGEMENT = "GJC_BROKER_HANDOFF_ACK\n";
 export const BROKER_HANDOFF_COMMIT = "GJC_BROKER_HANDOFF_COMMIT\n";
 export const BROKER_HANDOFF_ABORT = "GJC_BROKER_HANDOFF_ABORT\n";
+/**
+ * Backstop for a retained trampoline whose parent never sends a decision. It must
+ * outlive the parent's own broker discovery deadline (which is derived from the
+ * publication budget and can double across a guarded retry), otherwise the
+ * trampoline reaps the broker first and the parent misreports its own discovery
+ * timeout as an "exited before discovery" startup failure.
+ */
+export const BROKER_HANDOFF_DECISION_TIMEOUT_MS = 120_000;
 
 /**
  * Windows broker hop: spawns the real broker with detached:true and reports its pid.
@@ -165,7 +174,10 @@ export function waitForBrokerHandoffAcknowledgement(input: stream.Readable): Pro
 }
 
 /** Wait for a validated identity ACK followed by the parent's publication decision. */
-export function waitForBrokerHandoffDecision(input: stream.Readable, timeoutMs = 30_000): Promise<"commit" | "abort"> {
+export function waitForBrokerHandoffDecision(
+	input: stream.Readable,
+	timeoutMs = BROKER_HANDOFF_DECISION_TIMEOUT_MS,
+): Promise<"commit" | "abort"> {
 	const decision = Promise.withResolvers<"commit" | "abort">();
 	let received = "";
 	let settled = false;

package/src/sdk/broker/lifecycle-ledger.ts

@@ -968,6 +968,9 @@ export class LifecycleLedger {
 		return this.#mutate(async () => {
 			const previous = this.#byIdentity.get(identity);
 			if (!previous) throw new Error("Unknown lifecycle identity");
+			// Match replay validation: proven terminal records admit no successor.
+			// A late failure must not append a row that will be quarantined on reopen.
+			if (terminal(previous.state)) return previous;
 			const next = {
 				...previous,
 				...fields,

package/src/sdk/broker/lifecycle.ts

@@ -951,6 +951,14 @@ type SessionLaunch = {
 	modelId?: string;
 	modelPreset?: string;
 	mcpServers?: SessionLifecycleMcpServer[];
+	/**
+	 * Per-session environment for the hosted session (#6735). Applied to the
+	 * session host's spawn environment (and therefore inherited by its Bash
+	 * executor) on top of the broker's own environment, after `unsetEnv` has
+	 * removed inherited names. Broker-reserved `GJC_*` names are rejected.
+	 */
+	env?: Record<string, string>;
+	unsetEnv?: string[];
 	/** Coordinator namespace dir; broker computes the state file path from launch.id (#2549). */
 	coordinatorStateDir?: string;
 	coordinatorSessionId?: string;
@@ -963,6 +971,85 @@ type SessionLaunch = {
 };
 
 const CREDENTIAL_NAME_PATTERN = /(?:token|secret|password|credential|api[_-]?key|auth|cookie)/iu;
+const SESSION_ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+const SESSION_ENV_MAX_ENTRIES = 256;
+const SESSION_ENV_MAX_VALUE_LENGTH = 131_072;
+
+function isSessionEnvName(name: unknown): name is string {
+	return (
+		typeof name === "string" &&
+		name.length <= 256 &&
+		SESSION_ENV_NAME_PATTERN.test(name) &&
+		// GJC_* carries broker-issued launch authority (request, effect marker,
+		// state root, coordinator correlation); a caller must not shadow it.
+		!name.toUpperCase().startsWith("GJC_")
+	);
+}
+
+const sessionEnvKey = (name: string): string => (process.platform === "win32" ? name.toUpperCase() : name);
+
+/**
+ * Validates the optional per-session `env`/`unsetEnv` pair (#6735). Returns
+ * null when either is malformed so the caller fails the launch closed.
+ */
+export function lifecycleSessionEnv(input: {
+	env?: unknown;
+	unsetEnv?: unknown;
+}): { env?: Record<string, string>; unsetEnv?: string[] } | null {
+	let env: Record<string, string> | undefined;
+	if (input.env !== undefined) {
+		if (input.env === null || typeof input.env !== "object" || Array.isArray(input.env)) return null;
+		const entries = Object.entries(input.env as Record<string, unknown>);
+		if (entries.length > SESSION_ENV_MAX_ENTRIES) return null;
+		const seen = new Set<string>();
+		for (const [name, value] of entries) {
+			if (
+				!isSessionEnvName(name) ||
+				typeof value !== "string" ||
+				value.length > SESSION_ENV_MAX_VALUE_LENGTH ||
+				value.includes("\0") ||
+				seen.has(sessionEnvKey(name))
+			)
+				return null;
+			seen.add(sessionEnvKey(name));
+		}
+		env = Object.fromEntries(entries) as Record<string, string>;
+	}
+	let unsetEnv: string[] | undefined;
+	if (input.unsetEnv !== undefined) {
+		if (!Array.isArray(input.unsetEnv) || input.unsetEnv.length > SESSION_ENV_MAX_ENTRIES) return null;
+		const keys = new Set<string>();
+		for (const name of input.unsetEnv) {
+			if (!isSessionEnvName(name) || keys.has(sessionEnvKey(name))) return null;
+			keys.add(sessionEnvKey(name));
+		}
+		// Setting and unsetting the same name is contradictory, not a precedence question.
+		if (env && Object.keys(env).some(name => keys.has(sessionEnvKey(name)))) return null;
+		unsetEnv = [...(input.unsetEnv as string[])];
+	}
+	return { ...(env ? { env } : {}), ...(unsetEnv ? { unsetEnv } : {}) };
+}
+
+/**
+ * Composes the inherited part of a lifecycle session host's environment:
+ * drops the process-local master capability, every `unsetEnv` name, and any
+ * inherited name an explicit per-session `env` entry replaces (case-folded on
+ * Windows so `Path` and `PATH` never both reach the child), then layers the
+ * per-session `env` on top. Broker-issued `GJC_*` keys are applied after this.
+ */
+export function lifecycleSessionHostBaseEnv(
+	inherited: NodeJS.ProcessEnv | Readonly<Record<string, string | undefined>>,
+	launch: { env?: Readonly<Record<string, string>>; unsetEnv?: readonly string[] },
+): Record<string, string> {
+	const removed = new Set([...(launch.unsetEnv ?? []), ...Object.keys(launch.env ?? {})].map(sessionEnvKey));
+	// Valid names like `__proto__` must remain own environment entries.
+	const base = Object.create(null) as Record<string, string>;
+	for (const [name, value] of Object.entries(inherited)) {
+		if (name === "GJC_MASTER_CAPABILITY" || typeof value !== "string" || removed.has(sessionEnvKey(name))) continue;
+		base[name] = value;
+	}
+	return { ...base, ...launch.env };
+}
 
 function lifecycleLaunchKnownSecrets(launch: SessionLaunch): string[] {
 	const secrets = [
@@ -985,6 +1072,9 @@ function lifecycleLaunchKnownSecrets(launch: SessionLaunch): string[] {
 				.filter(([name, value]) => value && CREDENTIAL_NAME_PATTERN.test(name))
 				.map(([, value]) => value);
 		}),
+		...Object.entries(launch.env ?? {})
+			.filter(([name, value]) => value && CREDENTIAL_NAME_PATTERN.test(name))
+			.map(([, value]) => value),
 	];
 	return [...new Set(secrets.filter(secret => typeof secret === "string" && secret.length > 0))];
 }
@@ -5998,6 +6088,12 @@ async function launchInput(
 	if (input.mcpServers !== undefined && !isSessionLifecycleMcpServers(input.mcpServers))
 		return fail("invalid_input", "mcpServers must contain unique valid stdio, HTTP, or SSE server definitions.");
 	const mcpServers = input.mcpServers as SessionLifecycleMcpServer[] | undefined;
+	const sessionEnv = lifecycleSessionEnv(input);
+	if (!sessionEnv)
+		return fail(
+			"invalid_input",
+			"env must map valid non-GJC_ variable names to strings, and unsetEnv must list distinct valid names not also set in env.",
+		);
 
 	/**
 	 * Prepared readiness is an explicit creation-only intent. Only the two exact
@@ -6047,6 +6143,7 @@ async function launchInput(
 			modelId,
 			modelPreset,
 			mcpServers,
+			...sessionEnv,
 			worktree,
 			worktreePlan,
 			...(readiness ? { readiness } : {}),
@@ -6070,6 +6167,7 @@ async function launchInput(
 			sessionIdentity: saved.identity,
 			modelPreset,
 			mcpServers,
+			...sessionEnv,
 			worktree,
 			worktreePlan,
 			...(coordinatorStateDir ? { coordinatorStateDir } : {}),
@@ -6104,6 +6202,7 @@ async function launchInput(
 		modelId,
 		modelPreset,
 		mcpServers,
+		...sessionEnv,
 		worktree,
 		worktreePlan,
 		...(coordinatorStateDir ? { coordinatorStateDir } : {}),
@@ -7160,12 +7259,9 @@ async function executeLifecycleResponse(
 					stdio: ["ignore", "ignore", childStderrSink?.drainer.stdin ?? "ignore"],
 					env: {
 						// Master capability is process-local to direct Bash children and must
-						// never cross a broker lifecycle launch boundary.
-						...Object.fromEntries(
-							Object.entries("kind" in cmd ? cmd.env : process.env).filter(
-								([key]) => key !== "GJC_MASTER_CAPABILITY",
-							),
-						),
+						// never cross a broker lifecycle launch boundary. Per-session env
+						// (#6735) is layered here, below the broker-issued GJC_* keys.
+						...lifecycleSessionHostBaseEnv("kind" in cmd ? cmd.env : process.env, launch),
 						GJC_AGENT_DIR: broker.settings.agentDir,
 						GJC_CODING_AGENT_DIR: broker.settings.agentDir,
 						GJC_SESSION_ID: launch.id,