pi-cohort 7.6.0 → 7.6.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [7.6.2] - 2026-10-28
+
+### Added
+- Each child session is named `<agent> <run id prefix>[/<index>] from <parent>`, where `<parent>` is the parent session's name or, when unnamed, its id. `/resume`, terminal titles, and live-session rosters now tell children apart instead of listing unnamed sessions. (#32)
+
+## [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.
@@ -165,6 +167,16 @@ Review and delivery workflows live in pi-gauntlet; pi-cohort ships delegation pr
 
 `context: "fork"` starts a child from a real branched session instead of a fresh one, when it needs the parent's history. Cost across the whole subtree - main loop plus every foreground/background/nested child - rolls up into one `Σ$` total in the footer; see [doc/observability.md](doc/observability.md).
 
+Each child session is named `<agent> <run id prefix>[/<index>] from <parent>`, so `/resume`, terminal titles, and live-session rosters can tell children apart:
+
+| Child | Session name |
+|---|---|
+| Single `scout` from a session named `billing reports` | `scout 3f9a2c1e from billing reports` |
+| Third task (index 2) of the same parallel run | `scout 3f9a2c1e/2 from billing reports` |
+| `scout` from an unnamed session | `scout 3f9a2c1e from <parent session id>` |
+
+The run id prefix works as the `id` for `subagent` status, interrupt, and resume; the index is the child `index` for resume. A nested child names its parent child: `worker 7b41d0aa from scout 3f9a2c1e from billing reports`.
+
 Full reference: agent/chain authoring in [doc/agents-and-chains.md](doc/agents-and-chains.md), exact command syntax in [doc/commands.md](doc/commands.md), the raw tool API in [doc/programmatic-api.md](doc/programmatic-api.md).
 
 ## Key concepts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cohort",
-  "version": "7.6.0",
+  "version": "7.6.2",
   "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>;

package/src/runs/background/async-execution.ts

@@ -57,6 +57,8 @@ interface AsyncExecutionContext {
 	parentModel?: string;
 	/** Parent session thinking level, captured at dispatch */
 	parentThinking?: string;
+	/** Parent session display name, or its id when unnamed, captured at dispatch */
+	parentSessionLabel?: string;
 	executionBackend?: string;
 }
 
@@ -632,6 +634,7 @@ export function executeAsyncChain(
 				sessionDir: path.join(sessionRoot ?? path.join(RUN_STATE_ROOT_DIR, "sessions"), `async-${id}`),
 				asyncDir,
 				sessionId: ctx.currentSessionId,
+				parentSessionLabel: ctx.parentSessionLabel,
 				runtime: ctx.runtime,
 				forwardedFlags,
 				worktreeSetupHook,
@@ -846,6 +849,7 @@ export function executeAsyncSingle(
 				sessionDir: path.join(sessionRoot ?? path.join(RUN_STATE_ROOT_DIR, "sessions"), `async-${id}`),
 				asyncDir,
 				sessionId: ctx.currentSessionId,
+				parentSessionLabel: ctx.parentSessionLabel,
 				runtime: ctx.runtime,
 				forwardedFlags,
 				worktreeSetupHook,

package/src/runs/background/subagent-runner.ts

@@ -117,6 +117,7 @@ interface SubagentRunConfig {
 	sessionDir?: string;
 	asyncDir: string;
 	sessionId?: string | null;
+	parentSessionLabel?: string;
 	runtime: PiRuntimeIdentity;
 	forwardedFlags?: string[];
 	worktreeSetupHook?: string;
@@ -625,6 +626,7 @@ export interface SingleStepContext {
 	outputFile: string;
 	runtime: PiRuntimeIdentity;
 	forwardedFlags?: string[];
+	parentSessionLabel?: string;
 	registerInterrupt?: (interrupt: (() => void) | undefined) => void;
 	nestedRoute?: NestedRouteInfo;
 	onAttemptStart?: (attempt: { model?: string; thinking?: string }) => void;
@@ -790,6 +792,7 @@ export async function runSingleStep(
 					runId: ctx.id,
 					childAgentName: step.agent,
 					childIndex: ctx.flatIndex,
+					parentSessionLabel: ctx.parentSessionLabel,
 					parentEventSink: ctx.nestedRoute?.eventSink,
 					parentControlInbox: ctx.nestedRoute?.controlInbox,
 					parentRootRunId: ctx.nestedRoute?.rootRunId,
@@ -936,6 +939,7 @@ export async function runSingleStep(
 			runId: ctx.id,
 			childAgentName: step.agent,
 			childIndex: ctx.flatIndex,
+			parentSessionLabel: ctx.parentSessionLabel,
 			parentEventSink: ctx.nestedRoute?.eventSink,
 			parentControlInbox: ctx.nestedRoute?.controlInbox,
 			parentRootRunId: ctx.nestedRoute?.rootRunId,
@@ -1978,6 +1982,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 					runtime: config.runtime,
 					controlConfig: config.controlConfig,
 					forwardedFlags: config.forwardedFlags,
+					parentSessionLabel: config.parentSessionLabel,
 					executionBackendCoordinator,
 					executionBackendConfig,
 					nestedRoute: config.nestedRoute,
@@ -2268,6 +2273,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 							runtime: config.runtime,
 							controlConfig: config.controlConfig,
 							forwardedFlags: config.forwardedFlags,
+							parentSessionLabel: config.parentSessionLabel,
 							executionBackendCoordinator,
 							executionBackendConfig,
 							nestedRoute: config.nestedRoute,
@@ -2448,6 +2454,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 				runtime: config.runtime,
 				controlConfig: config.controlConfig,
 				forwardedFlags: config.forwardedFlags,
+				parentSessionLabel: config.parentSessionLabel,
 				executionBackendCoordinator,
 				executionBackendConfig,
 				nestedRoute: config.nestedRoute,

package/src/runs/foreground/chain-execution.ts

@@ -9,6 +9,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AgentConfig } from "../../agents/agents.ts";
 import { ChainClarifyComponent, type ChainClarifyResult, type BehaviorOverride } from "./chain-clarify.ts";
 import { parentModelFullId, toModelInfo, type ModelInfo } from "../../shared/model-info.ts";
+import { resolveSessionLabel } from "../../shared/session-identity.ts";
 import {
 	resolveChainTemplates,
 	createChainDir,
@@ -318,6 +319,7 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 				preferredModelProvider: input.ctx.model?.provider,
 				parentModel: parentModelFullId(input.ctx.model),
 				parentThinking: input.ctx.thinkingLevel,
+				parentSessionLabel: resolveSessionLabel(input.ctx.sessionManager),
 				skills: behavior.skills === false ? [] : behavior.skills,
 				structuredOutput: structuredRuntime,
 				acceptance: task.acceptance,
@@ -1161,6 +1163,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					preferredModelProvider: ctx.model?.provider,
 					parentModel: parentModelFullId(ctx.model),
 					parentThinking: ctx.thinkingLevel,
+					parentSessionLabel: resolveSessionLabel(ctx.sessionManager),
 					skills: behavior.skills === false ? [] : behavior.skills,
 					structuredOutput: structuredRuntime,
 					acceptance: seqStep.acceptance,

package/src/runs/foreground/execution.ts

@@ -158,6 +158,7 @@ async function runSingleAttempt(
 		runId: options.runId,
 		childAgentName: agent.name,
 		childIndex: options.index ?? 0,
+		parentSessionLabel: options.parentSessionLabel,
 		parentEventSink: options.nestedRoute?.eventSink,
 		parentControlInbox: options.nestedRoute?.controlInbox,
 		parentRootRunId: options.nestedRoute?.rootRunId,

package/src/runs/foreground/external-single-attempt.ts

@@ -92,6 +92,7 @@ export async function runExternalSingleAttempt(input: RunExternalSingleAttemptIn
 		runId: options.runId,
 		childAgentName: agent.name,
 		childIndex: options.index ?? 0,
+		parentSessionLabel: options.parentSessionLabel,
 		parentEventSink: options.nestedRoute?.eventSink,
 		parentControlInbox: options.nestedRoute?.controlInbox,
 		parentRootRunId: options.nestedRoute?.rootRunId,

package/src/runs/foreground/subagent-executor.ts

@@ -37,7 +37,7 @@ import {
 import { discoverAvailableSkills, normalizeSkillInput } from "../../agents/skills.ts";
 import { executeAsyncChain, executeAsyncSingle, formatAsyncStartedMessage, isAsyncAvailable } from "../background/async-execution.ts";
 import { createForkContextResolver } from "../../shared/fork-context.ts";
-import { resolveCurrentSessionId } from "../../shared/session-identity.ts";
+import { resolveCurrentSessionId, resolveSessionLabel } from "../../shared/session-identity.ts";
 import { formatControlNoticeMessage, resolveControlConfig, shouldNotifyControlEvent } from "../shared/subagent-control.ts";
 import { finalizeSingleOutput, injectSingleOutputInstruction, normalizeTopLevelOutput, resolveParallelTaskOutputPath, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
 import { blockedLine } from "../shared/completion-guard.ts";
@@ -225,6 +225,7 @@ function buildAsyncContext(ctx: ExtensionContext, deps: CallExecutorDeps, cwd: s
 		currentModelProvider: ctx.model?.provider,
 		parentModel: parentModelFullId(ctx.model),
 		parentThinking: ctx.thinkingLevel,
+		parentSessionLabel: resolveSessionLabel(ctx.sessionManager),
 		executionBackend: deps.config.executionBackend,
 	};
 }
@@ -1503,6 +1504,7 @@ async function runForegroundParallelTasks(input: ForegroundParallelRunInput): Pr
 			preferredModelProvider: input.ctx.model?.provider,
 			parentModel: parentModelFullId(input.ctx.model),
 			parentThinking: input.ctx.thinkingLevel,
+			parentSessionLabel: resolveSessionLabel(input.ctx.sessionManager),
 			skills: effectiveSkills === false ? [] : effectiveSkills,
 			acceptance: task.acceptance,
 			acceptanceContext: { mode: "parallel" },
@@ -2064,6 +2066,7 @@ async function runSinglePath(data: ExecutionContextData, deps: CallExecutorDeps)
 		preferredModelProvider: currentProvider,
 		parentModel: parentModelFullId(ctx.model),
 		parentThinking: ctx.thinkingLevel,
+		parentSessionLabel: resolveSessionLabel(ctx.sessionManager),
 		skills: effectiveSkills,
 		acceptance: params.acceptance,
 		acceptanceContext: { mode: "single" },

package/src/runs/shared/pi-args.ts

@@ -45,6 +45,8 @@ interface BuildPiArgsInput {
 	runId?: string;
 	childAgentName?: string;
 	childIndex?: number;
+	/** Parent session display name, or its id when unnamed; names the child session. */
+	parentSessionLabel?: string;
 	parentEventSink?: string;
 	parentControlInbox?: string;
 	parentRootRunId?: string;
@@ -79,6 +81,13 @@ export function applyThinkingSuffix(model: string | undefined, thinking: string
 	return `${model}:${thinking}`;
 }
 
+function childSessionName(input: BuildPiArgsInput): string | undefined {
+	if (!input.childAgentName || !input.runId) return undefined;
+	const index = input.childIndex ? `/${input.childIndex}` : "";
+	const parent = input.parentSessionLabel ? ` from ${input.parentSessionLabel}` : "";
+	return `${input.childAgentName} ${input.runId.slice(0, 8)}${index}${parent}`;
+}
+
 export function buildPiArgs(input: BuildPiArgsInput, fileSystem: BuildPiArgsFileSystem = fs): BuildPiArgsResult {
 	const args = [...input.baseArgs];
 	// Forwarded flags are already name-deduped by deriveForwardedFlags; append only
@@ -100,6 +109,11 @@ export function buildPiArgs(input: BuildPiArgsInput, fileSystem: BuildPiArgsFile
 		}
 	}
 
+	const sessionName = childSessionName(input);
+	if (sessionName) {
+		args.push("--name", sessionName);
+	}
+
 	const modelArg = applyThinkingSuffix(input.model, input.thinking);
 	if (modelArg) {
 		args.push("--model", modelArg);

package/src/shared/session-identity.ts

@@ -3,8 +3,18 @@ interface SessionIdentityManager {
 	getSessionId(): string | null | undefined;
 }
 
+interface SessionLabelManager {
+	getSessionName(): string | undefined;
+	getSessionId(): string;
+}
+
 export function resolveCurrentSessionId(sessionManager: SessionIdentityManager): string {
 	const sessionId = sessionManager.getSessionFile() ?? sessionManager.getSessionId();
 	if (!sessionId) throw new Error("Current session identity is unavailable.");
 	return sessionId;
 }
+
+/** The session's display name, or its id when unnamed. */
+export function resolveSessionLabel(sessionManager: SessionLabelManager): string {
+	return sessionManager.getSessionName() || sessionManager.getSessionId();
+}

package/src/shared/types.ts

@@ -830,6 +830,8 @@ export interface RunSyncOptions {
 	parentModel?: string;
 	/** Parent session thinking level; used when the agent sets no `thinking` */
 	parentThinking?: string;
+	/** Parent session display name, or its id when unnamed; names the child session */
+	parentSessionLabel?: string;
 	/** Skills to inject (overrides agent default if provided) */
 	skills?: string[];
 	structuredOutput?: {