feat: add Pi ready marker and session metadata

src/agents/session-env.ts

@@ -0,0 +1,30 @@
+export type OverstorySessionKind =
+	| "standalone"
+	| "orchestrator"
+	| "coordinator"
+	| "monitor"
+	| "worker";
+
+export interface OverstorySessionEnvOpts {
+	baseEnv?: Record<string, string>;
+	sessionKind: OverstorySessionKind;
+	agentName: string;
+	capability: string;
+	worktreePath: string;
+	projectRoot: string;
+	taskId?: string;
+	profile?: string;
+}
+
+export function buildOverstorySessionEnv(opts: OverstorySessionEnvOpts): Record<string, string> {
+	return {
+		...(opts.baseEnv ?? {}),
+		OVERSTORY_SESSION_KIND: opts.sessionKind,
+		OVERSTORY_AGENT_NAME: opts.agentName,
+		OVERSTORY_CAPABILITY: opts.capability,
+		OVERSTORY_WORKTREE_PATH: opts.worktreePath,
+		OVERSTORY_PROJECT_ROOT: opts.projectRoot,
+		...(opts.taskId !== undefined ? { OVERSTORY_TASK_ID: opts.taskId } : {}),
+		...(opts.profile !== undefined ? { OVERSTORY_PROFILE: opts.profile } : {}),
+	};
+}

src/commands/coordinator.ts

@@ -17,6 +17,7 @@ import { join } from "node:path";
 import { Command } from "commander";
 import { createIdentity, loadIdentity } from "../agents/identity.ts";
 import { createManifestLoader, resolveModel } from "../agents/manifest.ts";
+import { buildOverstorySessionEnv } from "../agents/session-env.ts";
 import { loadConfig } from "../config.ts";
 import { AgentError, ValidationError } from "../errors.ts";
 import { jsonOutput } from "../json.ts";
@@ -441,22 +442,23 @@ export async function startCoordinatorSession(
 		if (await agentDefFile.exists()) {
 			appendSystemPromptFile = agentDefPath;
 		}
+		const sessionEnv = buildOverstorySessionEnv({
+			baseEnv: runtime.buildEnv(resolvedModel),
+			sessionKind: "coordinator",
+			agentName: coordinatorName,
+			capability: "coordinator",
+			worktreePath: projectRoot,
+			projectRoot,
+			...(profileFlag ? { profile: profileFlag } : {}),
+		});
 		const spawnCmd = runtime.buildSpawnCommand({
 			model: resolvedModel.model,
 			permissionMode: "bypass",
 			cwd: projectRoot,
 			appendSystemPromptFile,
-			env: {
-				...runtime.buildEnv(resolvedModel),
-				OVERSTORY_AGENT_NAME: coordinatorName,
-				...(profileFlag ? { OVERSTORY_PROFILE: profileFlag } : {}),
-			},
-		});
-		const pid = await tmux.createSession(tmuxSession, projectRoot, spawnCmd, {
-			...runtime.buildEnv(resolvedModel),
-			OVERSTORY_AGENT_NAME: coordinatorName,
-			...(profileFlag ? { OVERSTORY_PROFILE: profileFlag } : {}),
+			env: sessionEnv,
 		});
+		const pid = await tmux.createSession(tmuxSession, projectRoot, spawnCmd, sessionEnv);
 
 		// Create a run for this coordinator session BEFORE recording the session,
 		// so the session can reference the run ID from the start.

src/commands/monitor.ts

@@ -18,6 +18,7 @@ import { join } from "node:path";
 import { Command } from "commander";
 import { createIdentity, loadIdentity } from "../agents/identity.ts";
 import { createManifestLoader, resolveModel } from "../agents/manifest.ts";
+import { buildOverstorySessionEnv } from "../agents/session-env.ts";
 import { loadConfig } from "../config.ts";
 import { AgentError, ValidationError } from "../errors.ts";
 import { jsonOutput } from "../json.ts";
@@ -149,20 +150,22 @@ async function startMonitor(opts: { json: boolean; attach: boolean }): Promise<v
 		if (await agentDefFile.exists()) {
 			appendSystemPromptFile = agentDefPath;
 		}
+		const sessionEnv = buildOverstorySessionEnv({
+			baseEnv: runtime.buildEnv(resolvedModel),
+			sessionKind: "monitor",
+			agentName: MONITOR_NAME,
+			capability: "monitor",
+			worktreePath: projectRoot,
+			projectRoot,
+		});
 		const spawnCmd = runtime.buildSpawnCommand({
 			model: resolvedModel.model,
 			permissionMode: "bypass",
 			cwd: projectRoot,
 			appendSystemPromptFile,
-			env: {
-				...runtime.buildEnv(resolvedModel),
-				OVERSTORY_AGENT_NAME: MONITOR_NAME,
-			},
-		});
-		const pid = await createSession(tmuxSession, projectRoot, spawnCmd, {
-			...runtime.buildEnv(resolvedModel),
-			OVERSTORY_AGENT_NAME: MONITOR_NAME,
+			env: sessionEnv,
 		});
+		const pid = await createSession(tmuxSession, projectRoot, spawnCmd, sessionEnv);
 
 		// Record session BEFORE sending the beacon so that hook-triggered
 		// updateLastActivity() can find the entry and transition booting->working.

src/commands/sling.ts

@@ -24,6 +24,7 @@ import { join, resolve } from "node:path";
 import { createIdentity, loadIdentity } from "../agents/identity.ts";
 import { createManifestLoader, resolveModel } from "../agents/manifest.ts";
 import { writeOverlay } from "../agents/overlay.ts";
+import { buildOverstorySessionEnv } from "../agents/session-env.ts";
 import { createCanopyClient } from "../canopy/client.ts";
 import { loadConfig } from "../config.ts";
 import { AgentError, HierarchyError, ValidationError } from "../errors.ts";
@@ -914,12 +915,15 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 
 			// 11c. Spawn: headless runtimes bypass tmux entirely; tmux path is unchanged.
 			if (runtime.headless === true && runtime.buildDirectSpawn) {
-				const directEnv = {
-					...runtime.buildEnv(resolvedModel),
-					OVERSTORY_AGENT_NAME: name,
-					OVERSTORY_WORKTREE_PATH: worktreePath,
-					OVERSTORY_TASK_ID: taskId,
-				};
+				const directEnv = buildOverstorySessionEnv({
+					baseEnv: runtime.buildEnv(resolvedModel),
+					sessionKind: "worker",
+					agentName: name,
+					capability,
+					worktreePath,
+					projectRoot: config.project.root,
+					taskId,
+				});
 				const argv = runtime.buildDirectSpawn({
 					cwd: worktreePath,
 					env: directEnv,
@@ -1000,24 +1004,23 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 
 				// 12. Create tmux session running claude in interactive mode
 				const tmuxSessionName = `overstory-${config.project.name}-${name}`;
+				const sessionEnv = buildOverstorySessionEnv({
+					baseEnv: runtime.buildEnv(resolvedModel),
+					sessionKind: "worker",
+					agentName: name,
+					capability,
+					worktreePath,
+					projectRoot: config.project.root,
+					taskId,
+				});
 				const spawnCmd = runtime.buildSpawnCommand({
 					model: resolvedModel.model,
 					permissionMode: "bypass",
 					cwd: worktreePath,
 					sharedWritableDirs: getSharedWritableDirs(config.project.root, capability),
-					env: {
-						...runtime.buildEnv(resolvedModel),
-						OVERSTORY_AGENT_NAME: name,
-						OVERSTORY_WORKTREE_PATH: worktreePath,
-						OVERSTORY_TASK_ID: taskId,
-					},
-				});
-				const pid = await createSession(tmuxSessionName, worktreePath, spawnCmd, {
-					...runtime.buildEnv(resolvedModel),
-					OVERSTORY_AGENT_NAME: name,
-					OVERSTORY_WORKTREE_PATH: worktreePath,
-					OVERSTORY_TASK_ID: taskId,
+					env: sessionEnv,
 				});
+				const pid = await createSession(tmuxSessionName, worktreePath, spawnCmd, sessionEnv);
 
 				// 13. Record session BEFORE sending the beacon so that hook-triggered
 				// updateLastActivity() can find the entry and transition booting->working.
@@ -1114,10 +1117,8 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 				// the beacon text entirely (overstory-3271).
 				//
 				// Skipped for runtimes that return false from requiresBeaconVerification().
-				// Pi's TUI idle and processing states are indistinguishable via detectReady
-				// (both show "pi v..." header and the token-usage status bar), so the loop
-				// would incorrectly conclude the beacon was not received and spam duplicate
-				// startup messages.
+				// Pi uses an explicit extension-owned ready marker instead, so this loop
+				// would only resend duplicate startup messages there.
 				const needsVerification =
 					!runtime.requiresBeaconVerification || runtime.requiresBeaconVerification();
 				if (needsVerification) {

src/commands/supervisor.ts

@@ -17,6 +17,7 @@ import { join } from "node:path";
 import { Command } from "commander";
 import { createIdentity, loadIdentity } from "../agents/identity.ts";
 import { createManifestLoader, resolveModel } from "../agents/manifest.ts";
+import { buildOverstorySessionEnv } from "../agents/session-env.ts";
 import { loadConfig } from "../config.ts";
 import { AgentError, ValidationError } from "../errors.ts";
 import { jsonOutput } from "../json.ts";
@@ -177,22 +178,23 @@ async function startSupervisor(opts: {
 		if (await agentDefFile.exists()) {
 			appendSystemPromptFile = agentDefPath;
 		}
+		const sessionEnv = buildOverstorySessionEnv({
+			baseEnv: runtime.buildEnv(resolvedModel),
+			sessionKind: "coordinator",
+			agentName: opts.name,
+			capability: "supervisor",
+			worktreePath: projectRoot,
+			projectRoot,
+			taskId: opts.task,
+		});
 		const spawnCmd = runtime.buildSpawnCommand({
 			model: resolvedModel.model,
 			permissionMode: "bypass",
 			cwd: projectRoot,
 			appendSystemPromptFile,
-			env: {
-				...runtime.buildEnv(resolvedModel),
-				OVERSTORY_AGENT_NAME: opts.name,
-				OVERSTORY_TASK_ID: opts.task,
-			},
-		});
-		const pid = await createSession(tmuxSession, projectRoot, spawnCmd, {
-			...runtime.buildEnv(resolvedModel),
-			OVERSTORY_AGENT_NAME: opts.name,
-			OVERSTORY_TASK_ID: opts.task,
+			env: sessionEnv,
 		});
+		const pid = await createSession(tmuxSession, projectRoot, spawnCmd, sessionEnv);
 
 		// Wait for Claude Code TUI to render before sending input
 		await waitForTuiReady(tmuxSession, (content) => runtime.detectReady(content));