feat: add Pi ready marker and session metadata

CLAUDE.md

@@ -46,6 +46,20 @@ Depth limit is configurable (default 2). Prevents runaway spawning.
 
 Purpose-built messaging via `bun:sqlite` in `.overstory/mail.db`. WAL mode for concurrent access from multiple agents. ~1-5ms per query. Independent of beads (which is too slow for high-frequency polling).
 
+### Agent Environment Variables
+
+Overstory injects these into every managed agent session (set via `buildOverstorySessionEnv`):
+
+| Variable | Description |
+|---|---|
+| `OVERSTORY_SESSION_KIND` | Session role: `standalone`, `orchestrator`, `coordinator`, `lead`, `worker`, `monitor` |
+| `OVERSTORY_AGENT_NAME` | Unique agent name within the run |
+| `OVERSTORY_CAPABILITY` | Agent capability: `builder`, `scout`, `reviewer`, `lead`, `merger` |
+| `OVERSTORY_WORKTREE_PATH` | Absolute path to this agent's git worktree |
+| `OVERSTORY_PROJECT_ROOT` | Absolute path to the target project root |
+| `OVERSTORY_TASK_ID` | Task ID (set when a task is assigned) |
+| `OVERSTORY_PROFILE` | Workflow profile name (set when a profile is resolved) |
+
 ## Directory Structure
 
 ```

docs/runtime-adapters.md

@@ -145,8 +145,8 @@ Notes:
   the exec prompt, since `codex exec` has no `--append-system-prompt` flag.
 - Copilot silently ignores `appendSystemPrompt` and `appendSystemPromptFile` —
   the `copilot` CLI has no equivalent flag.
-- Pi ignores `permissionMode` — security is enforced via guard extensions deployed
-  by `deployConfig()`.
+- Pi ignores `permissionMode` — session policy and readiness are enforced by the
+  project-root `pi-os-eco` extension synced by `deployConfig()`.
 
 ---
 
@@ -215,7 +215,7 @@ export interface HooksDef {
 |---------|-----------------|---------------------|------------|
 | Claude Code | `.claude/CLAUDE.md` | `settings.local.json` PreToolUse hooks | Generated by `hooks-deployer.ts` |
 | Codex | `AGENTS.md` | OS-level sandbox (Seatbelt/Landlock) via `--full-auto` | None — sandbox is implicit |
-| Pi | `.claude/CLAUDE.md` | `.pi/extensions/overstory-guard.ts` TypeScript extension | Generated by `pi-guards.ts` |
+| Pi | `AGENTS.md` | Project-root `pi-os-eco` extension | Synced by `pi.ts` |
 | Copilot | `.github/copilot-instructions.md` | None | No hook mechanism |
 | Cursor | `.cursor/rules/overstory.md` | None | No hook mechanism |
 

src/agents/session-env.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "bun:test";
+import { buildOverstorySessionEnv } from "./session-env.ts";
+
+describe("buildOverstorySessionEnv", () => {
+	test("sets all required fields", () => {
+		expect(
+			buildOverstorySessionEnv({
+				sessionKind: "worker",
+				agentName: "builder-1",
+				capability: "builder",
+				worktreePath: "/tmp/worktree",
+				projectRoot: "/tmp/project",
+			}),
+		).toEqual({
+			OVERSTORY_SESSION_KIND: "worker",
+			OVERSTORY_AGENT_NAME: "builder-1",
+			OVERSTORY_CAPABILITY: "builder",
+			OVERSTORY_WORKTREE_PATH: "/tmp/worktree",
+			OVERSTORY_PROJECT_ROOT: "/tmp/project",
+		});
+	});
+
+	test("omits optional taskId and profile when undefined", () => {
+		const env = buildOverstorySessionEnv({
+			sessionKind: "monitor",
+			agentName: "monitor",
+			capability: "monitor",
+			worktreePath: "/tmp/project",
+			projectRoot: "/tmp/project",
+		});
+
+		expect(env.OVERSTORY_TASK_ID).toBeUndefined();
+		expect(env.OVERSTORY_PROFILE).toBeUndefined();
+	});
+
+	test("includes optional taskId and profile when provided", () => {
+		expect(
+			buildOverstorySessionEnv({
+				sessionKind: "supervisor",
+				agentName: "supervisor-1",
+				capability: "supervisor",
+				worktreePath: "/tmp/project",
+				projectRoot: "/tmp/project",
+				taskId: "task-123",
+				profile: "ov-delivery",
+			}),
+		).toMatchObject({
+			OVERSTORY_SESSION_KIND: "supervisor",
+			OVERSTORY_TASK_ID: "task-123",
+			OVERSTORY_PROFILE: "ov-delivery",
+		});
+	});
+
+	test("overstory keys override colliding baseEnv values", () => {
+		expect(
+			buildOverstorySessionEnv({
+				baseEnv: {
+					OVERSTORY_SESSION_KIND: "standalone",
+					OVERSTORY_AGENT_NAME: "wrong",
+					EXTRA_VAR: "kept",
+				},
+				sessionKind: "coordinator",
+				agentName: "coordinator",
+				capability: "coordinator",
+				worktreePath: "/tmp/project",
+				projectRoot: "/tmp/project",
+			}),
+		).toEqual({
+			OVERSTORY_SESSION_KIND: "coordinator",
+			OVERSTORY_AGENT_NAME: "coordinator",
+			OVERSTORY_CAPABILITY: "coordinator",
+			OVERSTORY_WORKTREE_PATH: "/tmp/project",
+			OVERSTORY_PROJECT_ROOT: "/tmp/project",
+			EXTRA_VAR: "kept",
+		});
+	});
+});

src/agents/session-env.ts

@@ -0,0 +1,14 @@
+import type { OverstorySessionEnvOpts } from "../types.ts";
+
+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";
@@ -475,22 +476,23 @@ export async function startCoordinatorSession(
 		if (await agentDefHandle.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";
@@ -155,20 +156,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";
@@ -919,12 +920,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,
@@ -1005,24 +1009,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.
@@ -1119,10 +1122,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: "supervisor",
+			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));