pi-cohort 7.6.0 → 7.6.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [7.6.1] - 2026-10-26
+
+### Added
+- Execution backends can declare `surfaceEnvironmentPrefixes`; each child attempt gets the launched surface's own values for matching keys instead of the parent's, and inherits none of the parent's matching keys. Before, a child started in a terminal-mux pane carried the parent pane's identity (for example `CMUX_SURFACE_ID`), so mux-aware tools in the child acted on the parent's pane.
+
 ## [7.6.0] - 2026-10-26
 
 ### Breaking

package/README.md

@@ -79,6 +79,8 @@ The descriptor has exactly four fields. `packageJsonUrl` must be an absolute `fi
 
 Cohort serializes only backend names and validated reload descriptors into its detached coordinator - never live backend objects or an environment capsule. The coordinator reloads registrations in their original order before selecting a backend, and every child launch receives its exact resolved `cwd`. Selecting `native` bypasses reload entirely. An explicit backend selection reports that backend's reload failure; `auto` reports any registered reload failure rather than silently changing policy. Once reload succeeds, normal auto-detection still falls back to native when no registered backend is available. Backends registered without `reload` remain usable in the foreground but cannot be reconstructed for a background run.
 
+A backend whose surface sets its own identity variables declares them with `surfaceEnvironmentPrefixes` (for example `["CMUX_"]`). Each child attempt then drops the parent's keys with those prefixes and takes the launched surface's values instead, so mux-aware tools in the child address the child's surface. Prefixes must be nonblank strings.
+
 ## Mental model
 
 Pi is the parent session. A subagent is a focused child Pi session with its own job. When you ask for a subagent, Pi starts the child, gives it the task, and brings the result back. Foreground runs stream in the conversation; background runs keep working and can be checked later.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cohort",
-  "version": "7.6.0",
+  "version": "7.6.1",
   "description": "Delegate Pi work to focused child agents: code review, scouting, implementation, parallel audits, saved chains, and background jobs.",
   "author": "Jacek Juraszek",
   "license": "MIT",

package/src/execution-backend/child-host-controller.ts

@@ -55,7 +55,7 @@ export async function createChildHostController(options: ChildHostControllerOpti
 		let descriptor: number | undefined;
 		try {
 			descriptor = fileSystem.openSync(configPath, "wx", 0o600);
-			fileSystem.writeFileSync(descriptor, JSON.stringify({ protocolVersion: 1, socketPath, runId: options.runId, childId: options.childId }));
+			fileSystem.writeFileSync(descriptor, JSON.stringify({ protocolVersion: 1, socketPath, runId: options.runId, childId: options.childId, surfaceEnvironmentPrefixes: options.backend.surfaceEnvironmentPrefixes ?? [] }));
 		} finally { if (descriptor !== undefined) fileSystem.closeSync(descriptor); }
 
 		let lease: ExecutionBackendLease | undefined;

package/src/execution-backend/child-host-protocol.ts

@@ -6,6 +6,7 @@ export interface ChildHostConfig {
 	readonly socketPath: string;
 	readonly runId: string;
 	readonly childId: string;
+	readonly surfaceEnvironmentPrefixes: readonly string[];
 }
 
 type Correlation = { readonly protocolVersion: 1; readonly runId: string; readonly childId: string };
@@ -35,9 +36,11 @@ function correlation(input: Record<string, unknown>): Correlation {
 
 export function validateChildHostConfig(value: unknown): ChildHostConfig {
 	const input = record(value, "child host config");
-	exact(input, ["protocolVersion", "socketPath", "runId", "childId"]);
+	exact(input, ["protocolVersion", "socketPath", "runId", "childId", "surfaceEnvironmentPrefixes"]);
 	if (input.protocolVersion !== CHILD_HOST_PROTOCOL_VERSION) throw new Error("incompatible child host protocol");
-	return { ...correlation(input), socketPath: text(input.socketPath, "socketPath") };
+	const prefixes = input.surfaceEnvironmentPrefixes;
+	if (!Array.isArray(prefixes)) throw new Error("surfaceEnvironmentPrefixes must be an array");
+	return { ...correlation(input), socketPath: text(input.socketPath, "socketPath"), surfaceEnvironmentPrefixes: prefixes.map(prefix => text(prefix, "surfaceEnvironmentPrefixes entry")) };
 }
 
 export function validateChildHostMessage(value: unknown): ChildHostMessage {

package/src/execution-backend/child-host-runtime.ts

@@ -17,6 +17,13 @@ export function loadChildHostConfig(configPath = process.env[PI_COHORT_CHILD_HOS
 	} finally { if (descriptor !== undefined) fs.closeSync(descriptor); }
 }
 
+function attemptEnvironment(parent: Readonly<Record<string, string>>, surfacePrefixes: readonly string[]): Record<string, string> {
+	const surfaceOwned = (key: string) => surfacePrefixes.some(prefix => key.startsWith(prefix));
+	const environment = Object.fromEntries(Object.entries(parent).filter(([key]) => !surfaceOwned(key)));
+	for (const [key, value] of Object.entries(process.env)) if (value !== undefined && surfaceOwned(key)) environment[key] = value;
+	return environment;
+}
+
 export function runChildHost(config = loadChildHostConfig()): void {
 	const correlation = { protocolVersion: 1 as const, runId: config.runId, childId: config.childId };
 	const socket = net.createConnection(config.socketPath);
@@ -36,7 +43,7 @@ export function runChildHost(config = loadChildHostConfig()): void {
 			}
 			if (message.kind !== "start_attempt" || active || stopping) { socket.destroy(); return; }
 			let child: ChildProcess;
-			try { child = spawn(message.command, [...message.args], { cwd: message.cwd, env: message.environment, shell: false, stdio: "inherit", windowsHide: true }); }
+			try { child = spawn(message.command, [...message.args], { cwd: message.cwd, env: attemptEnvironment(message.environment, config.surfaceEnvironmentPrefixes), shell: false, stdio: "inherit", windowsHide: true }); }
 			catch { send({ ...correlation, kind: "attempt_spawn_error", attemptId: message.attemptId }); continue; }
 			active = { attemptId: message.attemptId, process: child };
 			send({ ...correlation, kind: "attempt_started", attemptId: message.attemptId });

package/src/execution-backend/registry.ts

@@ -54,6 +54,10 @@ function assertBackend(backend: ExecutionBackend): void {
 	for (const method of ["detect", "launch", "reattach", "close"] as const) {
 		if (typeof backend[method] !== "function") throw new Error(`Execution backend ${method} must be a function`);
 	}
+	const prefixes = backend.surfaceEnvironmentPrefixes;
+	if (prefixes !== undefined && (!Array.isArray(prefixes) || prefixes.some(prefix => typeof prefix !== "string" || prefix.trim() === ""))) {
+		throw new Error("Execution backend surfaceEnvironmentPrefixes must be nonblank strings");
+	}
 }
 
 export function registerExecutionBackend(

package/src/execution-backend/types.ts

@@ -77,6 +77,12 @@ export type ExecutionBackendCloseReason = "delivered" | "explicit_cleanup";
 export interface ExecutionBackend {
 	readonly name: string;
 	readonly protocolVersion: typeof EXECUTION_BACKEND_PROTOCOL_VERSION;
+	/**
+	 * Environment-variable prefixes the surface owns, such as a terminal's own
+	 * surface identity. Each attempt gets the launched surface's values for
+	 * matching keys instead of the parent's.
+	 */
+	readonly surfaceEnvironmentPrefixes?: readonly string[];
 	detect(): Promise<ExecutionBackendDetection>;
 	launch(request: ExecutionSurfaceRequest): Promise<ExecutionBackendLease>;
 	reattach(handle: ExecutionSurfaceHandle): Promise<ReattachResult>;