@evo-dev/core 0.0.1-alpha.1 → 0.0.1-alpha.11

package/src/team/index.ts

@@ -1,15 +1,39 @@
 import { spawn } from "node:child_process";
-import { appendFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
-import { basename, dirname, join } from "node:path";
+import { appendFile, cp, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { resolveEvoDevPaths } from "../config/paths.ts";
-import { createDefaultSettings, parseSettings } from "../config/settings.ts";
+import {
+  createDefaultSettings,
+  parseSettings,
+  readRuntimeInjectionSettings,
+} from "../config/settings.ts";
+import {
+  createScopedKnowledgeContextPack,
+  formatScopedKnowledgePromptBlock,
+  hasContextInjectionReceipt,
+  writeContextInjectionReceipt,
+} from "../evolution/knowledge/index.ts";
 import { resolveProjectLogKey } from "../runtime-logs/index.ts";
+import { renderTeamRoleStartupPrompt } from "./prompts.ts";
 
 export type TeamAgentRuntime = "codex" | "claude";
-export type TeamAgentStatus = "running" | "recovering" | "recreated" | "stopped" | "failed";
+export type TeamAgentStatus =
+  | "starting"
+  | "running"
+  | "busy"
+  | "idle"
+  | "waiting-input"
+  | "recovering"
+  | "recreated"
+  | "stopped"
+  | "exited"
+  | "needs-user-attention"
+  | "failed"
+  | "unknown";
 export type TeamRunStatus = "running" | "stopped" | "failed";
 export type TeamWriteMode = "read-only" | "repo-write" | "worktree-write" | "disabled";
 export type TeamMessageType = "request" | "result" | "issue" | "notice";
+export type TeamMessageDeliveryState = "pending" | "claimed" | "wakeup-sent" | "failed";
 export type TeamRuntimeAgentRecoveryMode =
   | { type: "resume"; sessionId: string }
   | { type: "resume-latest" }
@@ -32,6 +56,7 @@ export interface TeamRuntimeCommandRunner {
 
 export interface TmuxRuntimeAdapterOptions {
   runtimeCommands?: Partial<Record<TeamAgentRuntime, string>>;
+  environment?: Record<string, string | undefined>;
 }
 
 export interface TeamRuntimeAdapter {
@@ -107,6 +132,12 @@ export interface TeamRuntimeAttachInput {
   paneId?: string;
 }
 
+export interface TeamRoleRuntimeContextInput {
+  homeDir?: string;
+  runId: string;
+  roleId: string;
+}
+
 export interface TeamRolePermissions {
   writeMode: TeamWriteMode;
   canUseTeamsMcp: boolean;
@@ -130,7 +161,7 @@ export interface TeamRoleDefinition {
   prompt: string;
   permissions: TeamRolePermissions;
   teamPolicy: TeamRolePolicy;
-  source: "builtin" | "global";
+  source: "builtin" | "global" | "overlay";
 }
 
 export interface ResolvedTeamRole extends TeamRoleDefinition {
@@ -147,6 +178,59 @@ export interface TeamNativeAgentBinding {
   updatedAt: string;
 }
 
+export type TeamOverlaySource = "repo" | "global" | "builtin";
+
+export interface TeamDefinition {
+  version: 1;
+  name: string;
+  description: string;
+  agents: Record<string, string>;
+  body: string;
+}
+
+export interface TeamOverlayResolution {
+  source: TeamOverlaySource;
+  teamPath: string | null;
+  definition: TeamDefinition;
+}
+
+export interface TeamAgentReference {
+  roleId: string;
+  reference: string;
+  sourcePath: string;
+  scope: "repo" | "global";
+}
+
+export interface TeamOverlayAgentSummary {
+  roleId: string;
+  name: string;
+  description: string;
+  sourcePath: string;
+}
+
+export interface TeamAgentDefinition {
+  roleId: string;
+  name: string;
+  description: string;
+  runtime: TeamAgentRuntime | null;
+  model: string | null;
+  thinkingLevel: string | null;
+  writeMode: TeamWriteMode | null;
+  skills: string[];
+  sourcePath: string;
+  markdown: string;
+}
+
+export interface DefaultTeamOverlayFileResult {
+  sourcePath: string;
+  targetPath: string;
+  written: boolean;
+}
+
+export interface EnsureDefaultTeamOverlayResult {
+  files: DefaultTeamOverlayFileResult[];
+}
+
 export interface TeamRoleBindingRecord {
   version: 1;
   roleId: string;
@@ -219,6 +303,18 @@ export interface TeamMessageRecord {
   createdAt: string;
 }
 
+export interface TeamPendingMessageRecord extends TeamMessageRecord {
+  deliveryState: TeamMessageDeliveryState;
+  attemptCount: number;
+  lastAttemptAt: string | null;
+}
+
+export interface TeamMessageListFile {
+  version: 1;
+  updatedAt: string | null;
+  messages: TeamPendingMessageRecord[];
+}
+
 export interface TeamEventRecord {
   version: 1;
   eventId: string;
@@ -230,7 +326,9 @@ export interface TeamEventRecord {
     | "TeamMessageAccepted"
     | "TeamMessageDelivered"
     | "TeamMessageDeliveryFailed"
+    | "TeamMessageWakeupSent"
     | "AgentNativeSessionRecorded"
+    | "AgentHookStateUpdated"
     | "AgentRecoveryDecisionRequired"
     | "AgentRecovered"
     | "AgentRecreated"
@@ -242,6 +340,29 @@ export interface TeamEventRecord {
   createdAt: string;
 }
 
+export interface TeamRunStatusSnapshot {
+  version: 1;
+  runId: string;
+  repoRoot: string;
+  runStatus: TeamRunStatus;
+  tmux: {
+    session: string;
+  };
+  agents: Array<{
+    roleId: string;
+    agentId: string;
+    roleName: string;
+    runtime: TeamAgentRuntime;
+    status: TeamAgentStatus;
+    paneId: string;
+    window: string;
+    nativeSessionId: string | null;
+    updatedAt: string;
+  }>;
+  lastEvent: string | null;
+  updatedAt: string;
+}
+
 export interface StartTeamRunInput {
   homeDir?: string;
   repoRoot: string;
@@ -432,7 +553,8 @@ export async function unsetTeamRoleBinding(input: {
 export interface TeamMessageSendResult {
   ok: boolean;
   messageId?: string;
-  deliveredTo?: string;
+  delivery?: "queued";
+  queuedFor?: string;
   cc?: string[];
   error?: string;
   message?: string;
@@ -444,6 +566,29 @@ export interface TeamMessageBrokerOptions {
 }
 
 export type TeamMessageBrokerSendInput = Omit<SendTeamMessageInput, "homeDir" | "runtimeAdapter">;
+export interface ReadPendingTeamMessagesInput {
+  homeDir?: string;
+  runId: string;
+  roleId: string;
+  limit?: number;
+}
+
+export interface MarkTeamMessagesDeliveredInput {
+  homeDir?: string;
+  runId: string;
+  roleId: string;
+  messageIds: string[];
+  now?: Date;
+}
+
+export interface UpdateTeamAgentHookStateInput {
+  homeDir?: string;
+  runId: string;
+  roleId: string;
+  hookEvent: string;
+  now?: Date;
+}
+
 export interface TeamMessageBrokerSpawnInput {
   runId?: string;
   fromRoleId?: string;
@@ -488,12 +633,21 @@ export interface TeamRunResumeResult extends TeamStatusResult {
   notifications: TeamMessageSendResult[];
 }
 
+export interface TeamMessageDeliveryScheduleResult {
+  wokenRoleIds: string[];
+  recoveredRoleIds: string[];
+  needsUserAttentionRoleIds: string[];
+  warnings: string[];
+}
+
 export interface TeamAgentSummary {
   roleId: string;
   roleName: string;
   status: TeamAgentStatus;
   runtime: TeamAgentRuntime;
   canReceiveMessages: boolean;
+  isIdle: boolean;
+  isMidTurn: boolean;
 }
 
 export interface TeamRunStore {
@@ -506,11 +660,24 @@ export interface TeamRunStore {
   writeAgent(agent: TeamAgentRecord): Promise<void>;
   readAgent(runId: string, roleId: string): Promise<TeamAgentRecord>;
   readAgents(runId: string): Promise<TeamAgentRecord[]>;
+  readMessages(runId: string): Promise<TeamMessageRecord[]>;
+  readEvents(runId: string): Promise<TeamEventRecord[]>;
+  readMessageList(runId: string): Promise<TeamPendingMessageRecord[]>;
+  writeMessageList(
+    runId: string,
+    messages: TeamPendingMessageRecord[],
+    updatedAt: string,
+  ): Promise<void>;
+  writeStatus(runId: string, snapshot: TeamRunStatusSnapshot): Promise<void>;
   appendMessage(runId: string, message: TeamMessageRecord): Promise<void>;
   appendEvent(runId: string, event: TeamEventRecord): Promise<void>;
 }
 
 const SAFE_ROLE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+export const TEAM_INTERNAL_WAKE_SIGNAL = [
+  "[EvoDev internal wake signal]",
+  "No user request is included in this message. Continue only from EvoDev team inbox messages injected by hooks.",
+].join("\n");
 const BUILT_IN_ROLE_PROMPTS: Record<
   string,
   { roleName: string; description: string; prompt: string }
@@ -519,27 +686,43 @@ const BUILT_IN_ROLE_PROMPTS: Record<
     roleName: "Main Conductor",
     description: "Coordinates the EvoDev team run and owns final synthesis.",
     prompt:
-      "You are the main conductor for this EvoDev team run. Coordinate role agents, keep decisions explicit, and synthesize final outcomes.",
+      "You are the main conductor for this EvoDev team run. Decide whether the user request actually needs team execution. If it does, plan required role agents, role assignments, dependencies, and runnable batches before spawning roles. Coordinate role agents, keep decisions explicit, and synthesize final outcomes. Once work is delegated to role agents, do not perform implementation, testing, or review details yourself.",
   },
   reviewer: {
     roleName: "Code Reviewer",
     description: "Reviews implementation quality, risks, and regressions.",
     prompt:
-      "You are the code reviewer for this EvoDev team run. Review changes and report concrete findings.",
+      "You are the code reviewer for this EvoDev team run. Review assigned changes and report concrete findings to the role that can act on them; notify main only when coordination or final synthesis is needed.",
   },
   tester: {
     roleName: "Test Engineer",
     description: "Verifies behavior and identifies test gaps.",
     prompt:
-      "You are the test engineer for this EvoDev team run. Run or recommend focused verification and report gaps.",
+      "You are the test engineer for this EvoDev team run. Run or recommend focused verification and report gaps to the implementing role when they need action; notify main only when coordination or final synthesis is needed.",
   },
   executor: {
     roleName: "Implementation Executor",
     description: "Implements scoped changes assigned by main.",
     prompt:
-      "You are the implementation executor for this EvoDev team run. Keep changes scoped and report verification evidence.",
+      "You are the implementation executor for this EvoDev team run. Keep changes scoped, avoid taking conductor decisions, and report changed files plus verification evidence.",
   },
 };
+const BUILT_IN_TEAM_DEFINITION: TeamDefinition = {
+  version: 1,
+  name: "builtin-minimal-team",
+  description: "Built-in minimal EvoDev team fallback.",
+  agents: {
+    executor: "builtin:executor",
+    reviewer: "builtin:reviewer",
+    tester: "builtin:tester",
+  },
+  body: [
+    "# Built-in Minimal Team",
+    "",
+    "Use role agents only when delegation improves correctness, coverage, safety, or latency.",
+    "Spawn roles on demand and send self-contained assignments through Teams MCP.",
+  ].join("\n"),
+};
 
 export function createTeamRunStore(homeDir?: string): TeamRunStore {
   const paths = resolveTeamRunPaths(homeDir);
@@ -547,6 +730,7 @@ export function createTeamRunStore(homeDir?: string): TeamRunStore {
   return {
     paths,
     async createRunDirs(runId) {
+      await migrateLegacyRunDirIfNeeded(paths, runId);
       await mkdir(paths.runDir(runId), { recursive: true });
       await mkdir(paths.agentsDir(runId), { recursive: true });
     },
@@ -555,6 +739,7 @@ export function createTeamRunStore(homeDir?: string): TeamRunStore {
       await writeJson(paths.runPath(run.runId), parseTeamRunRecord(run));
     },
     async readRun(runId) {
+      await migrateLegacyRunDirIfNeeded(paths, runId);
       return parseTeamRunRecord(JSON.parse(await readFile(paths.runPath(runId), "utf8")));
     },
     async writeLatestRunId(runId) {
@@ -567,7 +752,17 @@ export function createTeamRunStore(homeDir?: string): TeamRunStore {
         if (latest?.version === 1 && typeof latest.runId === "string") return latest.runId;
         return null;
       } catch {
-        return null;
+        try {
+          const latest = JSON.parse(await readFile(paths.legacyLatestRunPath, "utf8"));
+          if (latest?.version === 1 && typeof latest.runId === "string") {
+            await migrateLegacyRunDirIfNeeded(paths, latest.runId);
+            await this.writeLatestRunId(latest.runId);
+            return latest.runId;
+          }
+          return null;
+        } catch {
+          return null;
+        }
       }
     },
     async writeAgent(agent) {
@@ -575,11 +770,13 @@ export function createTeamRunStore(homeDir?: string): TeamRunStore {
       await writeJson(paths.agentPath(agent.runId, agent.roleId), parseTeamAgentRecord(agent));
     },
     async readAgent(runId, roleId) {
+      await migrateLegacyRunDirIfNeeded(paths, runId);
       return parseTeamAgentRecord(
         JSON.parse(await readFile(paths.agentPath(runId, roleId), "utf8")),
       );
     },
     async readAgents(runId) {
+      await migrateLegacyRunDirIfNeeded(paths, runId);
       try {
         const entries = await readdir(paths.agentsDir(runId));
         const agents = await Promise.all(
@@ -596,9 +793,51 @@ export function createTeamRunStore(homeDir?: string): TeamRunStore {
         return [];
       }
     },
+    async readMessages(runId) {
+      await migrateLegacyRunDirIfNeeded(paths, runId);
+      return readJsonLines(paths.messagesPath(runId), parseTeamMessageRecord);
+    },
+    async readEvents(runId) {
+      await migrateLegacyRunDirIfNeeded(paths, runId);
+      return readJsonLines(paths.eventsPath(runId), parseTeamEventRecord);
+    },
+    async readMessageList(runId) {
+      await migrateLegacyRunDirIfNeeded(paths, runId);
+      try {
+        const file = parseTeamMessageListFile(
+          JSON.parse(await readFile(paths.messageListPath(runId), "utf8")),
+        );
+        return file.messages;
+      } catch (error) {
+        if (isNotFoundError(error)) return [];
+        throw error;
+      }
+    },
+    async writeMessageList(runId, messages, updatedAt) {
+      await this.createRunDirs(runId);
+      await writeJson(paths.messageListPath(runId), {
+        version: 1,
+        updatedAt,
+        messages: messages.map(parseTeamPendingMessageRecord),
+      });
+    },
+    async writeStatus(runId, snapshot) {
+      await this.createRunDirs(runId);
+      await writeJson(paths.statusPath(runId), snapshot);
+    },
     async appendMessage(runId, message) {
       await this.createRunDirs(runId);
-      await appendJsonLine(paths.messagesPath(runId), parseTeamMessageRecord(message));
+      const parsed = parseTeamMessageRecord(message);
+      await appendJsonLine(paths.messagesPath(runId), parsed);
+      const pending = await this.readMessageList(runId);
+      await this.writeMessageList(
+        runId,
+        [
+          ...pending.filter((item) => item.messageId !== parsed.messageId),
+          createPendingMessageRecord(parsed),
+        ],
+        parsed.createdAt,
+      );
     },
     async appendEvent(runId, event) {
       await this.createRunDirs(runId);
@@ -609,23 +848,84 @@ export function createTeamRunStore(homeDir?: string): TeamRunStore {
 
 export function resolveTeamRunPaths(homeDir?: string) {
   const paths = resolveEvoDevPaths(homeDir);
+  const legacyRunsDir = join(paths.rootDir, "runs");
   return {
     rootDir: paths.rootDir,
     roleAgentsDir: paths.roleAgentsDir,
     teamsDir: paths.teamsDir,
     runsDir: paths.runsDir,
+    legacyRunsDir,
     latestRunPath: paths.latestRunPath,
+    legacyLatestRunPath: join(legacyRunsDir, "latest.json"),
     runDir: (runId: string) => join(paths.runsDir, runId),
+    legacyRunDir: (runId: string) => join(legacyRunsDir, runId),
     runPath: (runId: string) => join(paths.runsDir, runId, "run.json"),
+    legacyRunPath: (runId: string) => join(legacyRunsDir, runId, "run.json"),
     tmuxPath: (runId: string) => join(paths.runsDir, runId, "tmux.json"),
+    legacyTmuxPath: (runId: string) => join(legacyRunsDir, runId, "tmux.json"),
     agentsDir: (runId: string) => join(paths.runsDir, runId, "agents"),
+    legacyAgentsDir: (runId: string) => join(legacyRunsDir, runId, "agents"),
     agentPath: (runId: string, roleId: string) =>
       join(paths.runsDir, runId, "agents", `${roleId}.json`),
+    legacyAgentPath: (runId: string, roleId: string) =>
+      join(legacyRunsDir, runId, "agents", `${roleId}.json`),
     messagesPath: (runId: string) => join(paths.runsDir, runId, "messages.jsonl"),
+    legacyMessagesPath: (runId: string) => join(legacyRunsDir, runId, "messages.jsonl"),
     eventsPath: (runId: string) => join(paths.runsDir, runId, "events.jsonl"),
+    legacyEventsPath: (runId: string) => join(legacyRunsDir, runId, "events.jsonl"),
+    statusPath: (runId: string) => join(paths.runsDir, runId, "status.json"),
+    messageListPath: (runId: string) => join(paths.runsDir, runId, "message-list.json"),
   };
 }
 
+async function migrateLegacyRunDirIfNeeded(
+  paths: ReturnType<typeof resolveTeamRunPaths>,
+  runId: string,
+): Promise<void> {
+  const nextDir = paths.runDir(runId);
+  if (await pathExists(nextDir)) return;
+  const legacyDir = paths.legacyRunDir(runId);
+  if (!(await pathExists(legacyDir))) return;
+  await mkdir(dirname(nextDir), { recursive: true });
+  await cp(legacyDir, nextDir, { recursive: true, errorOnExist: false, force: false });
+}
+
+async function writeTeamStatusSnapshot(input: {
+  store: TeamRunStore;
+  runId: string;
+  now: string;
+  lastEvent?: string | null;
+}): Promise<TeamRunStatusSnapshot | null> {
+  try {
+    const run = await input.store.readRun(input.runId);
+    const agents = await input.store.readAgents(run.runId);
+    const snapshot: TeamRunStatusSnapshot = {
+      version: 1,
+      runId: run.runId,
+      repoRoot: run.repoRoot,
+      runStatus: run.status,
+      tmux: { session: run.tmux.session },
+      agents: agents.map((agent) => ({
+        roleId: agent.roleId,
+        agentId: agent.agentId,
+        roleName: agent.roleName,
+        runtime: agent.runtime,
+        status: agent.status,
+        paneId: agent.tmux.paneId,
+        window: agent.tmux.window,
+        nativeSessionId: agent.nativeSession.sessionId,
+        updatedAt: agent.updatedAt,
+      })),
+      lastEvent: input.lastEvent ?? null,
+      updatedAt: input.now,
+    };
+    await input.store.writeStatus(run.runId, snapshot);
+    return snapshot;
+  } catch {
+    return null;
+  }
+}
+
 export async function startTeamRun(input: StartTeamRunInput): Promise<TeamRunStartResult> {
   const store = createTeamRunStore(input.homeDir);
   const now = input.now ?? new Date();
@@ -639,11 +939,13 @@ export async function startTeamRun(input: StartTeamRunInput): Promise<TeamRunSta
     overrides: input.mainOverrides,
   });
   const runtimeAdapter = input.runtimeAdapter ?? createTmuxRuntimeAdapter();
-  const startupPrompt = createAgentStartupPrompt({
+  const startupPrompt = await createAgentStartupPrompt({
+    homeDir: input.homeDir,
     runId,
     repoRoot: input.repoRoot,
     role,
     roster: [],
+    now: createdAt,
   });
   const handle = await runtimeAdapter.createRun({
     runId,
@@ -688,6 +990,12 @@ export async function startTeamRun(input: StartTeamRunInput): Promise<TeamRunSta
       agentId: agent.agentId,
     }),
   );
+  await writeTeamStatusSnapshot({
+    store,
+    runId,
+    now: createdAt,
+    lastEvent: "TeamRunStarted",
+  });
 
   return { run, mainAgent: agent };
 }
@@ -713,11 +1021,13 @@ export async function spawnTeamRole(input: SpawnTeamRoleInput): Promise<TeamRole
   });
   const agents = await store.readAgents(run.runId);
   const mainAgent = agents.find((agent) => agent.roleId === "main");
-  const startupPrompt = createAgentStartupPrompt({
+  const startupPrompt = await createAgentStartupPrompt({
+    homeDir: input.homeDir,
     runId: run.runId,
     repoRoot: run.repoRoot,
     role,
     roster: agents,
+    now,
   });
   const runtimeAdapter = input.runtimeAdapter ?? createTmuxRuntimeAdapter();
   const handle = await runtimeAdapter.spawnAgent({
@@ -744,6 +1054,12 @@ export async function spawnTeamRole(input: SpawnTeamRoleInput): Promise<TeamRole
       agentId: agent.agentId,
     }),
   );
+  await writeTeamStatusSnapshot({
+    store,
+    runId: run.runId,
+    now,
+    lastEvent: "AgentSpawned",
+  });
 
   return { run: updatedRun, agent, created: true };
 }
@@ -802,6 +1118,12 @@ export async function stopTeamRole(input: StopTeamRoleInput): Promise<TeamRoleSt
       agentId,
     }),
   );
+  await writeTeamStatusSnapshot({
+    store,
+    runId: run.runId,
+    now,
+    lastEvent: "AgentStopped",
+  });
 
   return { ok: true, run: updatedRun, agent: stoppedAgent, stopped: true };
 }
@@ -833,6 +1155,166 @@ export async function sendTeamMessage(input: SendTeamMessageInput): Promise<Team
   }).send(input);
 }
 
+export async function readPendingTeamMessagesForRole(
+  input: ReadPendingTeamMessagesInput,
+): Promise<TeamMessageRecord[]> {
+  const store = createTeamRunStore(input.homeDir);
+  const messages = await store.readMessageList(input.runId);
+  const pending = messages.filter(
+    (message) => message.toRoleId === input.roleId && message.deliveryState !== "failed",
+  );
+  return pending.slice(0, input.limit ?? 5);
+}
+
+export async function markTeamMessagesDelivered(
+  input: MarkTeamMessagesDeliveredInput,
+): Promise<void> {
+  if (input.messageIds.length === 0) return;
+  const store = createTeamRunStore(input.homeDir);
+  const now = (input.now ?? new Date()).toISOString();
+  const delivered = new Set(input.messageIds);
+  const pending = await store.readMessageList(input.runId);
+  await store.writeMessageList(
+    input.runId,
+    pending.filter((message) => !delivered.has(message.messageId)),
+    now,
+  );
+  for (const messageId of input.messageIds) {
+    assertSafeId(messageId, "messageId");
+    await store.appendEvent(
+      input.runId,
+      createTeamEvent(input.runId, "TeamMessageDelivered", `Delivered message ${messageId}.`, now, {
+        roleId: input.roleId,
+        messageId,
+      }),
+    );
+  }
+}
+
+export async function schedulePendingTeamMessageDelivery(input: {
+  homeDir?: string;
+  runId?: string;
+  roleId?: string;
+  now?: Date;
+  runtimeAdapter?: TeamRuntimeAdapter;
+}): Promise<TeamMessageDeliveryScheduleResult> {
+  const store = createTeamRunStore(input.homeDir);
+  const runId = await resolveRequestedRunId(store, input.runId);
+  const run = await store.readRun(runId);
+  const pending = await store.readMessageList(run.runId);
+  const targetRoleIds = new Set(
+    pending
+      .filter((message) => input.roleId === undefined || message.toRoleId === input.roleId)
+      .map((message) => message.toRoleId),
+  );
+  const result: TeamMessageDeliveryScheduleResult = {
+    wokenRoleIds: [],
+    recoveredRoleIds: [],
+    needsUserAttentionRoleIds: [],
+    warnings: [],
+  };
+  if (targetRoleIds.size === 0) return result;
+
+  const runtimeAdapter = input.runtimeAdapter ?? createTmuxRuntimeAdapter();
+  const livePaneIds = await readLivePaneIds(runtimeAdapter, run.tmux.session);
+  const now = (input.now ?? new Date()).toISOString();
+
+  for (const roleId of targetRoleIds) {
+    const agent = await store.readAgent(run.runId, roleId).catch(() => null);
+    if (agent === null) continue;
+
+    if (
+      agent.roleId === "main" &&
+      (run.status !== "running" || !isActiveTeamAgentStatus(agent.status))
+    ) {
+      const updated: TeamAgentRecord = {
+        ...agent,
+        status: "needs-user-attention",
+        updatedAt: now,
+      };
+      await store.writeAgent(updated);
+      await writeTeamStatusSnapshot({
+        store,
+        runId: run.runId,
+        now,
+        lastEvent: "AgentNeedsUserAttention",
+      });
+      result.needsUserAttentionRoleIds.push(roleId);
+      continue;
+    }
+
+    if (run.status !== "running") continue;
+
+    if (!isActiveTeamAgentStatus(agent.status)) {
+      const resumed = await resumeTeamRun({
+        homeDir: input.homeDir,
+        runId: run.runId,
+        now: new Date(now),
+        runtimeAdapter,
+        missingSessionDecision: "recreate",
+        notifyMain: false,
+      });
+      const recovered = resumed.outcomes.find(
+        (outcome) =>
+          outcome.roleId === roleId &&
+          (outcome.outcome === "resumed" || outcome.outcome === "recreated"),
+      );
+      if (recovered !== undefined) result.recoveredRoleIds.push(roleId);
+      else result.warnings.push(`Role ${roleId} could not be automatically recovered.`);
+      continue;
+    }
+
+    if (isIdleTeamAgentStatus(agent.status) && livePaneIds.has(agent.tmux.paneId)) {
+      await runtimeAdapter.sendInput({
+        session: agent.tmux.session,
+        paneId: agent.tmux.paneId,
+        text: TEAM_INTERNAL_WAKE_SIGNAL,
+      });
+      await markPendingMessagesWakeupSent({
+        store,
+        runId: run.runId,
+        roleId,
+        now,
+      });
+      result.wokenRoleIds.push(roleId);
+    }
+  }
+
+  return result;
+}
+
+async function markPendingMessagesWakeupSent(input: {
+  store: TeamRunStore;
+  runId: string;
+  roleId: string;
+  now: string;
+}): Promise<void> {
+  const pending = await input.store.readMessageList(input.runId);
+  const updated = pending.map((message) =>
+    message.toRoleId === input.roleId
+      ? {
+          ...message,
+          deliveryState: "wakeup-sent" as const,
+          attemptCount: message.attemptCount + 1,
+          lastAttemptAt: input.now,
+        }
+      : message,
+  );
+  await input.store.writeMessageList(input.runId, updated, input.now);
+  for (const message of updated.filter((item) => item.toRoleId === input.roleId)) {
+    await input.store.appendEvent(
+      input.runId,
+      createTeamEvent(
+        input.runId,
+        "TeamMessageWakeupSent",
+        `Sent wake signal for message ${message.messageId}.`,
+        input.now,
+        { roleId: input.roleId, messageId: message.messageId },
+      ),
+    );
+  }
+}
+
 async function sendTeamMessageWithBrokerContext(
   options: TeamMessageBrokerOptions,
   input: TeamMessageBrokerSendInput,
@@ -856,11 +1338,11 @@ async function sendTeamMessageWithBrokerContext(
     };
   }
   const target = await store.readAgent(run.runId, input.toRoleId);
-  if (!isActiveTeamAgentStatus(target.status)) {
+  if (target.status === "failed" || target.status === "unknown") {
     return {
       ok: false,
-      error: "target-role-not-running",
-      message: `Role ${input.toRoleId} is not running in run ${run.runId}.`,
+      error: "target-role-unavailable",
+      message: `Role ${input.toRoleId} is not available in run ${run.runId}.`,
     };
   }
 
@@ -896,58 +1378,21 @@ async function sendTeamMessageWithBrokerContext(
       },
     ),
   );
+  await schedulePendingTeamMessageDelivery({
+    homeDir: options.homeDir,
+    runId: run.runId,
+    roleId: input.toRoleId,
+    now: new Date(now),
+    runtimeAdapter: options.runtimeAdapter,
+  });
 
-  const runtimeAdapter = options.runtimeAdapter ?? createTmuxRuntimeAdapter();
-  try {
-    await runtimeAdapter.sendInput({
-      session: target.tmux.session,
-      paneId: target.tmux.paneId,
-      text: formatDeliveredTeamMessage(message, false),
-    });
-    for (const ccRoleId of ccRoleIds) {
-      const cc = await store.readAgent(run.runId, ccRoleId);
-      if (isActiveTeamAgentStatus(cc.status)) {
-        await runtimeAdapter.sendInput({
-          session: cc.tmux.session,
-          paneId: cc.tmux.paneId,
-          text: formatDeliveredTeamMessage(message, true),
-        });
-      }
-    }
-    await store.appendEvent(
-      run.runId,
-      createTeamEvent(
-        run.runId,
-        "TeamMessageDelivered",
-        `Delivered message ${message.messageId} to ${input.toRoleId}.`,
-        now,
-        { roleId: input.toRoleId, agentId: targetAgentId, messageId: message.messageId },
-      ),
-    );
-    return {
-      ok: true,
-      messageId: message.messageId,
-      deliveredTo: input.toRoleId,
-      cc: ccRoleIds,
-    };
-  } catch (error) {
-    await store.appendEvent(
-      run.runId,
-      createTeamEvent(
-        run.runId,
-        "TeamMessageDeliveryFailed",
-        `Failed to deliver message ${message.messageId}: ${describeError(error)}`,
-        now,
-        { roleId: input.toRoleId, agentId: targetAgentId, messageId: message.messageId },
-      ),
-    );
-    return {
-      ok: false,
-      messageId: message.messageId,
-      error: "delivery-failed",
-      message: describeError(error),
-    };
-  }
+  return {
+    ok: true,
+    messageId: message.messageId,
+    delivery: "queued",
+    queuedFor: input.toRoleId,
+    cc: ccRoleIds,
+  };
 }
 
 async function spawnTeamRoleWithBrokerContext(
@@ -1084,6 +1529,12 @@ export async function stopTeamRun(input: StopTeamRunInput): Promise<TeamStatusRe
     run.runId,
     createTeamEvent(run.runId, "TeamRunStopped", `Stopped team run ${run.runId}.`, now),
   );
+  await writeTeamStatusSnapshot({
+    store,
+    runId: run.runId,
+    now,
+    lastEvent: "TeamRunStopped",
+  });
   return { run: stoppedRun, agents: stoppedAgents };
 }
 
@@ -1097,12 +1548,13 @@ export async function getTeamStatus(input: TeamStatusInput = {}): Promise<TeamSt
 
 export async function listTeamRuns(input: ListTeamRunsInput = {}): Promise<TeamRunRecord[]> {
   const store = createTeamRunStore(input.homeDir);
-  let entries: string[];
-  try {
-    entries = await readdir(store.paths.runsDir);
-  } catch (error) {
-    if (isNotFoundError(error)) return [];
-    throw error;
+  const entries = new Set<string>();
+  for (const runsDir of [store.paths.runsDir, store.paths.legacyRunsDir]) {
+    try {
+      for (const entry of await readdir(runsDir)) entries.add(entry);
+    } catch (error) {
+      if (!isNotFoundError(error)) throw error;
+    }
   }
   const runs: TeamRunRecord[] = [];
   for (const entry of entries) {
@@ -1145,6 +1597,18 @@ export async function reconcileTeamRun(
     .map((agent) => ({ ...agent, status: "stopped" as const, updatedAt: now }));
 
   if (stoppedAgents.length === 0) {
+    await schedulePendingTeamMessageDelivery({
+      homeDir: input.homeDir,
+      runId: run.runId,
+      now: new Date(now),
+      runtimeAdapter,
+    });
+    await writeTeamStatusSnapshot({
+      store,
+      runId: run.runId,
+      now,
+      lastEvent: "TeamReconciled",
+    });
     return { run, agents, stoppedAgents: [], notifications: [], runtimeAvailable: true };
   }
 
@@ -1181,10 +1645,24 @@ export async function reconcileTeamRun(
           livePaneIds,
           runtimeAdapter,
         });
+  await schedulePendingTeamMessageDelivery({
+    homeDir: input.homeDir,
+    runId: run.runId,
+    now: new Date(now),
+    runtimeAdapter,
+  });
+  await writeTeamStatusSnapshot({
+    store,
+    runId: run.runId,
+    now,
+    lastEvent: "TeamReconciled",
+  });
+  const finalRun = await store.readRun(run.runId);
+  const finalAgents = await store.readAgents(run.runId);
 
   return {
-    run: updatedRun,
-    agents: updatedAgents,
+    run: finalRun,
+    agents: finalAgents,
     stoppedAgents,
     notifications,
     runtimeAvailable: livePaneIds.size > 0,
@@ -1222,22 +1700,89 @@ export async function recordTeamAgentNativeSession(
       },
     ),
   );
+  await writeTeamStatusSnapshot({
+    store,
+    runId,
+    now,
+    lastEvent: "AgentNativeSessionRecorded",
+  });
 
   return updatedAgent;
 }
 
-export async function resumeTeamRun(input: ResumeTeamRunInput = {}): Promise<TeamRunResumeResult> {
+export async function updateTeamAgentHookState(
+  input: UpdateTeamAgentHookStateInput,
+): Promise<{ agent: TeamAgentRecord; statusPath: string; agentPath: string }> {
   const store = createTeamRunStore(input.homeDir);
   const runId = await resolveRequestedRunId(store, input.runId);
-  const run = await store.readRun(runId);
-  const runtimeAdapter = input.runtimeAdapter ?? createTmuxRuntimeAdapter();
+  const agent = await store.readAgent(runId, input.roleId);
   const now = (input.now ?? new Date()).toISOString();
-  const decision = input.missingSessionDecision ?? "ask";
-  const originalAgents = sortAgentsForRecovery(await store.readAgents(run.runId));
-  const livePaneIds = await readLivePaneIds(runtimeAdapter, run.tmux.session);
-  const outcomes: TeamAgentRecoveryResult[] = [];
-  const updatedAgents: TeamAgentRecord[] = [];
-  let updatedRun: TeamRunRecord = { ...run, status: "running", updatedAt: now };
+  const nextStatus = teamAgentStatusForHookEvent(input.hookEvent, agent.status);
+  const updatedAgent: TeamAgentRecord =
+    nextStatus === agent.status
+      ? { ...agent, updatedAt: now }
+      : {
+          ...agent,
+          status: nextStatus,
+          updatedAt: now,
+        };
+  await store.writeAgent(updatedAgent);
+  await store.appendEvent(
+    runId,
+    createTeamEvent(
+      runId,
+      "AgentHookStateUpdated",
+      `Updated ${input.roleId} hook state after ${input.hookEvent}.`,
+      now,
+      { roleId: input.roleId, agentId: updatedAgent.agentId },
+    ),
+  );
+  await writeTeamStatusSnapshot({
+    store,
+    runId,
+    now,
+    lastEvent: input.hookEvent,
+  });
+  return {
+    agent: updatedAgent,
+    statusPath: store.paths.statusPath(runId),
+    agentPath: store.paths.agentPath(runId, input.roleId),
+  };
+}
+
+export async function createTeamRoleRuntimeContext(
+  input: TeamRoleRuntimeContextInput,
+): Promise<string> {
+  const store = createTeamRunStore(input.homeDir);
+  const run = await store.readRun(input.runId);
+  const agent = await store.readAgent(run.runId, input.roleId);
+  const agents = await store.readAgents(run.runId);
+  const role = await resolveRoleForAgentRecovery({
+    homeDir: input.homeDir,
+    repoRoot: run.repoRoot,
+    agent,
+  });
+  return createAgentStartupPrompt({
+    homeDir: input.homeDir,
+    runId: run.runId,
+    repoRoot: run.repoRoot,
+    role,
+    roster: agents,
+  });
+}
+
+export async function resumeTeamRun(input: ResumeTeamRunInput = {}): Promise<TeamRunResumeResult> {
+  const store = createTeamRunStore(input.homeDir);
+  const runId = await resolveRequestedRunId(store, input.runId);
+  const run = await store.readRun(runId);
+  const runtimeAdapter = input.runtimeAdapter ?? createTmuxRuntimeAdapter();
+  const now = (input.now ?? new Date()).toISOString();
+  const decision = input.missingSessionDecision ?? "ask";
+  const originalAgents = sortAgentsForRecovery(await store.readAgents(run.runId));
+  const livePaneIds = await readLivePaneIds(runtimeAdapter, run.tmux.session);
+  const outcomes: TeamAgentRecoveryResult[] = [];
+  const updatedAgents: TeamAgentRecord[] = [];
+  let updatedRun: TeamRunRecord = { ...run, status: "running", updatedAt: now };
 
   for (const agent of originalAgents) {
     if (isActiveTeamAgentStatus(agent.status) && livePaneIds.has(agent.tmux.paneId)) {
@@ -1262,11 +1807,13 @@ export async function resumeTeamRun(input: ResumeTeamRunInput = {}): Promise<Tea
       ...updatedAgents,
       ...originalAgents.filter((item) => item.roleId !== agent.roleId),
     ];
-    const startupPrompt = createAgentStartupPrompt({
+    const startupPrompt = await createAgentStartupPrompt({
+      homeDir: input.homeDir,
       runId: run.runId,
       repoRoot: run.repoRoot,
       role,
       roster,
+      now,
     });
     const recoveryMode = resolveRecoveryMode(agent, decision);
 
@@ -1376,6 +1923,12 @@ export async function resumeTeamRun(input: ResumeTeamRunInput = {}): Promise<Tea
     updatedAt: now,
   };
   await store.writeRun(updatedRun);
+  await writeTeamStatusSnapshot({
+    store,
+    runId: run.runId,
+    now,
+    lastEvent: "TeamRunResumed",
+  });
 
   const decisionRequired = outcomes.filter((outcome) => outcome.outcome === "needs-decision");
   const notifications =
@@ -1419,9 +1972,221 @@ export async function listTeamAgents(input: TeamStatusInput = {}): Promise<TeamA
     status: agent.status,
     runtime: agent.runtime,
     canReceiveMessages: isActiveTeamAgentStatus(agent.status),
+    isIdle: isIdleTeamAgentStatus(agent.status),
+    isMidTurn: isMidTurnTeamAgentStatus(agent.status),
   }));
 }
 
+export async function resolveTeamOverlay(input: {
+  homeDir?: string;
+  repoRoot: string;
+}): Promise<TeamOverlayResolution> {
+  const repoTeamPath = join(input.repoRoot, ".evodev", "team", "team.md");
+  if (await pathExists(repoTeamPath)) {
+    return {
+      source: "repo",
+      teamPath: repoTeamPath,
+      definition: parseTeamDefinitionMarkdown(await readFile(repoTeamPath, "utf8")),
+    };
+  }
+
+  const globalTeamPath = resolveGlobalTeamMarkdownPath(input.homeDir);
+  if (await pathExists(globalTeamPath)) {
+    return {
+      source: "global",
+      teamPath: globalTeamPath,
+      definition: parseTeamDefinitionMarkdown(await readFile(globalTeamPath, "utf8")),
+    };
+  }
+
+  return {
+    source: "builtin",
+    teamPath: null,
+    definition: BUILT_IN_TEAM_DEFINITION,
+  };
+}
+
+export async function ensureDefaultTeamOverlay(input: {
+  homeDir?: string;
+  assetsRootDir: string;
+}): Promise<EnsureDefaultTeamOverlayResult> {
+  const assets = await listDefaultTeamOverlayAssets(input.assetsRootDir);
+  const paths = resolveEvoDevPaths(input.homeDir);
+  const files: DefaultTeamOverlayFileResult[] = [];
+
+  for (const asset of assets) {
+    const targetPath =
+      asset.kind === "team"
+        ? join(paths.rootDir, "team", "team.md")
+        : join(paths.rootDir, "team", "agents", asset.name);
+    const content = await readFile(asset.sourcePath, "utf8");
+    files.push({
+      sourcePath: asset.sourcePath,
+      targetPath,
+      written: await writeTextFileIfMissing(targetPath, content),
+    });
+  }
+
+  return { files };
+}
+
+export function parseTeamDefinitionMarkdown(content: string): TeamDefinition {
+  const markdown = parseMarkdownWithFrontmatter(content);
+  const frontmatter = markdown.frontmatter;
+  const version = frontmatter.version;
+  if (version !== 1) throw new Error("team.md frontmatter version must be 1.");
+  const agents = parseTeamDefinitionAgents(frontmatter.agents);
+
+  return {
+    version: 1,
+    name: optionalString(frontmatter.name) ?? "evodev-team",
+    description: optionalString(frontmatter.description) ?? "EvoDev team overlay.",
+    agents,
+    body: markdown.body.trim(),
+  };
+}
+
+export function resolveTeamAgentReference(input: {
+  homeDir?: string;
+  repoRoot: string;
+  roleId: string;
+  reference: string;
+}): TeamAgentReference {
+  assertSafeId(input.roleId, "roleId");
+  const reference = input.reference.trim();
+  if (reference.startsWith("global:")) {
+    const name = reference.slice("global:".length);
+    assertSafeId(name, "global agent name");
+    return {
+      roleId: input.roleId,
+      reference,
+      sourcePath: join(resolveEvoDevPaths(input.homeDir).rootDir, "team", "agents", `${name}.md`),
+      scope: "global",
+    };
+  }
+
+  if (reference.includes(":")) {
+    throw new Error(`Unsupported team agent reference for ${input.roleId}: ${reference}`);
+  }
+  if (isAbsolute(reference)) {
+    throw new Error(`Team agent path for ${input.roleId} must be repo-relative.`);
+  }
+  const sourcePath = resolve(input.repoRoot, reference);
+  const relativePath = relative(input.repoRoot, sourcePath);
+  if (
+    relativePath === "" ||
+    relativePath.startsWith("..") ||
+    isAbsolute(relativePath) ||
+    extname(sourcePath) !== ".md"
+  ) {
+    throw new Error(`Team agent path for ${input.roleId} must be a repo-local Markdown file.`);
+  }
+
+  return {
+    roleId: input.roleId,
+    reference,
+    sourcePath,
+    scope: "repo",
+  };
+}
+
+export async function readTeamAgentSummary(input: {
+  homeDir?: string;
+  repoRoot: string;
+  roleId: string;
+  reference: string;
+}): Promise<TeamOverlayAgentSummary> {
+  const reference = resolveTeamAgentReference(input);
+  const markdown = await readTeamAgentMarkdown(reference);
+  const parsed = parseMarkdownWithFrontmatter(markdown);
+  return {
+    roleId: input.roleId,
+    name: optionalString(parsed.frontmatter.name) ?? defaultRoleName(input.roleId),
+    description:
+      optionalString(parsed.frontmatter.description) ?? `EvoDev ${input.roleId} role agent.`,
+    sourcePath: reference.sourcePath,
+  };
+}
+
+export async function readTeamAgentDefinition(input: {
+  homeDir?: string;
+  repoRoot: string;
+  roleId: string;
+  reference: string;
+}): Promise<TeamAgentDefinition> {
+  const reference = resolveTeamAgentReference(input);
+  const markdown = await readTeamAgentMarkdown(reference);
+  const parsed = parseMarkdownWithFrontmatter(markdown);
+  const evodev = isRecord(parsed.frontmatter.evodev) ? parsed.frontmatter.evodev : {};
+  return {
+    roleId: input.roleId,
+    name: optionalString(parsed.frontmatter.name) ?? defaultRoleName(input.roleId),
+    description:
+      optionalString(parsed.frontmatter.description) ?? `EvoDev ${input.roleId} role agent.`,
+    runtime: optionalRuntime(evodev.runtime),
+    model: optionalNullableString(parsed.frontmatter.model) ?? null,
+    thinkingLevel:
+      optionalNullableString(evodev.thinking) ??
+      optionalNullableString(evodev.thinkingLevel) ??
+      null,
+    writeMode: optionalWriteMode(evodev.writeMode),
+    skills: parseStringList(evodev.skills),
+    sourcePath: reference.sourcePath,
+    markdown,
+  };
+}
+
+export async function renderMainTeamOverlayContext(input: {
+  homeDir?: string;
+  repoRoot: string;
+  overlay?: TeamOverlayResolution;
+}): Promise<string> {
+  const overlay = input.overlay ?? (await resolveTeamOverlay(input));
+  const summaries = await readTeamOverlayAgentSummaries({
+    homeDir: input.homeDir,
+    repoRoot: input.repoRoot,
+    overlay,
+  });
+  const roleLines =
+    summaries.length === 0
+      ? ["- none declared"]
+      : summaries.map((summary) => `- ${summary.roleId}: ${summary.name} - ${summary.description}`);
+  const source =
+    overlay.teamPath === null
+      ? `${overlay.source} fallback`
+      : `${overlay.source}: ${overlay.teamPath}`;
+
+  return [
+    "EvoDev team overlay:",
+    `Team: ${overlay.definition.name}`,
+    `Description: ${overlay.definition.description}`,
+    `Source: ${source}`,
+    "",
+    "Team strategy:",
+    overlay.definition.body || "(none)",
+    "",
+    "Declared role agents:",
+    ...roleLines,
+    "",
+    "Overlay rules:",
+    "- Declared role agents are spawned only on demand.",
+    "- Delegate by role id; role agent Markdown is loaded only inside the spawned role.",
+  ].join("\n");
+}
+
+export function renderRoleAgentDefinitionContext(input: {
+  definition: TeamAgentDefinition;
+}): string {
+  return [
+    "EvoDev role agent Markdown definition:",
+    `Source path: ${input.definition.sourcePath}`,
+    "Use this Markdown as the role-specific operating definition for this role only.",
+    "<evodev-agent-markdown>",
+    input.definition.markdown.trimEnd(),
+    "</evodev-agent-markdown>",
+  ].join("\n");
+}
+
 export async function resolveTeamRole(input: {
   homeDir?: string;
   repoRoot: string;
@@ -1434,6 +2199,37 @@ export async function resolveTeamRole(input: {
 }): Promise<ResolvedTeamRole> {
   assertSafeId(input.roleId, "roleId");
   const settings = await readSettingsOrDefault(input.homeDir);
+  const overlay = await resolveTeamOverlay({ homeDir: input.homeDir, repoRoot: input.repoRoot });
+  if (overlay.source !== "builtin" && input.roleId !== "main") {
+    const reference = overlay.definition.agents[input.roleId];
+    if (reference === undefined) {
+      throw new Error(
+        `Role ${input.roleId} is not declared in team overlay ${overlay.teamPath ?? overlay.source}.`,
+      );
+    }
+    const agent = await readTeamAgentDefinition({
+      homeDir: input.homeDir,
+      repoRoot: input.repoRoot,
+      roleId: input.roleId,
+      reference,
+    });
+    return {
+      version: 1,
+      roleId: input.roleId,
+      roleName: agent.name,
+      description: agent.description,
+      runtime: agent.runtime ?? settings.teamRuntime.defaultRuntime,
+      model: agent.model ?? settings.teamRuntime.defaultModel,
+      thinkingLevel: agent.thinkingLevel ?? settings.teamRuntime.defaultThinkingLevel,
+      prompt: renderRoleAgentDefinitionContext({ definition: agent }),
+      permissions: parseRolePermissions({ writeMode: agent.writeMode ?? undefined }, false),
+      teamPolicy: parseRolePolicy(undefined, settings.teamRuntime.recordTranscript),
+      source: "overlay",
+      sourcePath: agent.sourcePath,
+      nativeAgent: null,
+    };
+  }
+
   const globalRolePath = join(
     resolveEvoDevPaths(input.homeDir).roleAgentsDir,
     `${input.roleId}.json`,
@@ -1456,12 +2252,24 @@ export async function resolveTeamRole(input: {
     defaultThinkingLevel: settings.teamRuntime.defaultThinkingLevel,
     recordTranscript: settings.teamRuntime.recordTranscript,
   });
+  const prompt =
+    input.roleId === "main"
+      ? appendPromptBlock(
+          parsed.prompt,
+          await renderMainTeamOverlayContext({
+            homeDir: input.homeDir,
+            repoRoot: input.repoRoot,
+            overlay,
+          }),
+        )
+      : parsed.prompt;
 
   return {
     ...parsed,
     runtime: input.overrides?.runtime ?? nativeAgent?.target ?? parsed.runtime,
     model: input.overrides?.model ?? parsed.model,
     thinkingLevel: input.overrides?.thinkingLevel ?? parsed.thinkingLevel,
+    prompt,
     sourcePath,
     nativeAgent,
   };
@@ -1507,6 +2315,8 @@ export function createTmuxRuntimeAdapter(
 }
 
 export class TmuxRuntimeAdapter implements TeamRuntimeAdapter {
+  private messageBufferCounter = 0;
+
   constructor(
     private readonly runner: TeamRuntimeCommandRunner,
     private readonly options: TmuxRuntimeAdapterOptions = {},
@@ -1517,6 +2327,7 @@ export class TmuxRuntimeAdapter implements TeamRuntimeAdapter {
       runId: input.runId,
       repoRoot: input.repoRoot,
       runtimeCommands: this.options.runtimeCommands,
+      environment: this.options.environment,
     });
     await this.runTmux([
       "new-session",
@@ -1536,7 +2347,10 @@ export class TmuxRuntimeAdapter implements TeamRuntimeAdapter {
       `${input.sessionName}:main.0`,
       "#{pane_id}",
     ]);
-    return { session: input.sessionName, window: "main", paneId: pane.stdout.trim() };
+    const paneId = pane.stdout.trim();
+    await this.configureTeamWindow(`${input.sessionName}:main`);
+    await this.setPaneTitle(paneId, input.role);
+    return { session: input.sessionName, window: "main", paneId };
   }
 
   async spawnAgent(input: TeamRuntimeSpawnAgentInput): Promise<TeamRuntimeAgentHandle> {
@@ -1545,9 +2359,10 @@ export class TmuxRuntimeAdapter implements TeamRuntimeAdapter {
       runId: input.runId,
       repoRoot: input.repoRoot,
       runtimeCommands: this.options.runtimeCommands,
+      environment: this.options.environment,
     });
     if (input.targetPaneId !== undefined) {
-      const pane = await this.splitPane(input.targetPaneId, input.repoRoot, command);
+      const pane = await this.splitPane(input.targetPaneId, input.repoRoot, command, input.role);
       return { session: input.sessionName, window: "main", paneId: pane };
     }
 
@@ -1565,7 +2380,10 @@ export class TmuxRuntimeAdapter implements TeamRuntimeAdapter {
       input.repoRoot,
       command,
     ]);
-    return { session: input.sessionName, window, paneId: pane.stdout.trim() };
+    const paneId = pane.stdout.trim();
+    await this.configureTeamWindow(`${input.sessionName}:${window}`);
+    await this.setPaneTitle(paneId, input.role);
+    return { session: input.sessionName, window, paneId };
   }
 
   async recoverAgent(input: TeamRuntimeRecoverAgentInput): Promise<TeamRuntimeAgentHandle> {
@@ -1576,14 +2394,16 @@ export class TmuxRuntimeAdapter implements TeamRuntimeAdapter {
             runId: input.runId,
             repoRoot: input.repoRoot,
             runtimeCommands: this.options.runtimeCommands,
+            environment: this.options.environment,
           })
         : buildAgentResumeShellCommand(input.role, input.startupPrompt, {
             runId: input.runId,
             repoRoot: input.repoRoot,
             mode: input.mode,
             runtimeCommands: this.options.runtimeCommands,
+            environment: this.options.environment,
           });
-    const session = await this.runner.run("tmux", ["has-session", "-t", input.sessionName]);
+    const session = await this.runner.run("tmux", ["-u", "has-session", "-t", input.sessionName]);
     if (session.exitCode !== 0) {
       await this.runTmux([
         "new-session",
@@ -1603,11 +2423,14 @@ export class TmuxRuntimeAdapter implements TeamRuntimeAdapter {
         `${input.sessionName}:${window}.0`,
         "#{pane_id}",
       ]);
-      return recoveredHandle(input, window, pane.stdout.trim());
+      const paneId = pane.stdout.trim();
+      await this.configureTeamWindow(`${input.sessionName}:${window}`);
+      await this.setPaneTitle(paneId, input.role);
+      return recoveredHandle(input, window, paneId);
     }
 
     if (input.targetPaneId !== undefined && input.role.roleId !== "main") {
-      const pane = await this.splitPane(input.targetPaneId, input.repoRoot, command);
+      const pane = await this.splitPane(input.targetPaneId, input.repoRoot, command, input.role);
       return recoveredHandle(input, "main", pane);
     }
 
@@ -1625,13 +2448,17 @@ export class TmuxRuntimeAdapter implements TeamRuntimeAdapter {
       input.repoRoot,
       command,
     ]);
-    return recoveredHandle(input, window, pane.stdout.trim());
+    const paneId = pane.stdout.trim();
+    await this.configureTeamWindow(`${input.sessionName}:${window}`);
+    await this.setPaneTitle(paneId, input.role);
+    return recoveredHandle(input, window, paneId);
   }
 
   private async splitPane(
     targetPaneId: string,
     repoRoot: string,
     command: string,
+    role: ResolvedTeamRole,
   ): Promise<string> {
     const pane = await this.runTmux([
       "split-window",
@@ -1646,18 +2473,43 @@ export class TmuxRuntimeAdapter implements TeamRuntimeAdapter {
       repoRoot,
       command,
     ]);
-    await this.runTmux(["select-layout", "-t", targetPaneId, "tiled"]);
-    return pane.stdout.trim();
+    const paneId = pane.stdout.trim();
+    await this.configureTeamWindow(targetPaneId);
+    await this.setPaneTitle(paneId, role);
+    await this.runTmux(["select-layout", "-t", targetPaneId, "main-vertical"]);
+    return paneId;
+  }
+
+  private async configureTeamWindow(target: string): Promise<void> {
+    await this.runTmux(["set-option", "-w", "-t", target, "pane-border-status", "top"]);
+    await this.runTmux([
+      "set-option",
+      "-w",
+      "-t",
+      target,
+      "pane-border-format",
+      "[#{pane_index}] #{pane_title}",
+    ]);
+  }
+
+  private async setPaneTitle(paneId: string, role: ResolvedTeamRole): Promise<void> {
+    await this.runTmux(["select-pane", "-t", paneId, "-T", formatTeamPaneTitle(role)]);
   }
 
   async sendInput(input: TeamRuntimeSendInputInput): Promise<void> {
-    await this.runTmux(["set-buffer", "-b", "evodev-message", input.text]);
-    await this.runTmux(["paste-buffer", "-d", "-b", "evodev-message", "-t", input.paneId]);
-    await this.runTmux(["send-keys", "-t", input.paneId, "Enter"]);
+    const bufferName = `evodev-message-${Date.now()}-${this.messageBufferCounter++}`;
+    await this.runTmux(["set-buffer", "-b", bufferName, input.text]);
+    try {
+      await this.runTmux(["paste-buffer", "-d", "-p", "-r", "-b", bufferName, "-t", input.paneId]);
+    } catch (error) {
+      await this.runner.run("tmux", ["-u", "delete-buffer", "-b", bufferName]);
+      throw error;
+    }
+    await this.runTmux(["send-keys", "-t", input.paneId, "C-m"]);
   }
 
   async listPanes(input: TeamRuntimeListPanesInput): Promise<TeamRuntimePaneInfo[]> {
-    const panes = await this.runTmux(["list-panes", "-t", input.session, "-F", "#{pane_id}"]);
+    const panes = await this.runTmux(["list-panes", "-s", "-t", input.session, "-F", "#{pane_id}"]);
     return panes.stdout
       .split("\n")
       .map((paneId) => paneId.trim())
@@ -1675,15 +2527,15 @@ export class TmuxRuntimeAdapter implements TeamRuntimeAdapter {
 
   formatAttachCommand(input: TeamRuntimeAttachInput): string {
     return input.paneId === undefined
-      ? `tmux attach-session -t ${input.session}`
-      : `tmux attach-session -t ${input.session} \\; select-pane -t ${input.paneId}`;
+      ? `tmux -u attach-session -t ${input.session}`
+      : `tmux -u attach-session -t ${input.session} \\; select-pane -t ${input.paneId}`;
   }
 
   private async runTmux(
     args: string[],
     options?: { input?: string },
   ): Promise<TeamRuntimeCommandResult> {
-    const result = await this.runner.run("tmux", args, options);
+    const result = await this.runner.run("tmux", ["-u", ...args], options);
     if (result.exitCode !== 0) {
       throw new Error(`tmux ${args.join(" ")} failed: ${result.stderr || result.stdout}`);
     }
@@ -1854,84 +2706,50 @@ async function resolveRoleForAgentRecovery(input: {
 }
 
 function createAgentStartupPrompt(input: {
+  homeDir?: string;
   runId: string;
   repoRoot: string;
   role: ResolvedTeamRole;
   roster: TeamAgentRecord[];
-}): string {
-  const roster =
-    input.roster.length === 0
-      ? "- main: starting"
-      : input.roster
-          .map((agent) => `- ${agent.roleId}: ${agent.status} (${agent.roleName})`)
-          .join("\n");
-  return [
-    "You are an EvoDev managed role agent.",
-    `Team run: ${input.runId}`,
-    `Repository: ${input.repoRoot}`,
-    `Role id: ${input.role.roleId}`,
-    `Role name: ${input.role.roleName}`,
-    `Runtime: ${input.role.runtime}`,
-    input.role.nativeAgent === null
-      ? "Native Code Agent binding: none"
-      : `Native Code Agent binding: ${input.role.nativeAgent.target}/${input.role.nativeAgent.agentName} (${input.role.nativeAgent.scope})`,
-    `Model: ${input.role.model ?? "default"}`,
-    `Thinking level: ${input.role.thinkingLevel ?? "default"}`,
-    `Write mode: ${input.role.permissions.writeMode}`,
-    `Transcript recording: ${input.role.teamPolicy.recordTranscript ? "enabled" : "disabled"}`,
-    "",
-    "Current known agents:",
-    roster,
-    "",
-    "EvoDev team runtime control contract:",
-    "This run is already inside the EvoDev-managed team runtime.",
-    "For EvoDev role-agent lifecycle, use the current EvoDev run control plane.",
-    "Unprefixed user requests such as 'start the team', 'execute team', 'create agents', or 'spawn roles' mean: use the current EvoDev run control plane.",
-    "Do not answer those requests with only a role plan when a role agent should be created.",
-    "",
-    "Use Teams MCP as the primary control plane:",
-    "- list_agents: discover current EvoDev role agents.",
-    "- spawn_role: create or reuse exactly one EvoDev role agent.",
-    "- send_message: communicate through the EvoDev broker.",
-    "- stop_role: stop a role agent when allowed.",
-    "If Teams MCP is unavailable, fall back to the EvoDev CLI from this repository:",
-    "- evodev team spawn --role <roleId>",
-    "- evodev team send --to <roleId> --message <text>",
-    "- evodev team status",
-    "Teams MCP defaults are inherited from the environment:",
-    `EVODEV_TEAM_RUN_ID=${input.runId}`,
-    `EVODEV_TEAM_ROLE_ID=${input.role.roleId}`,
-    "When calling Teams MCP tools, let the MCP server-bound environment identify this run and role.",
-    "Do not operate tmux directly for role lifecycle; let EvoDev create and track panes.",
-    "Any server-bound role may request role lifecycle changes; EvoDev records and tracks panes but does not use role policy to stop execution.",
-    input.role.roleId === "main"
-      ? "As main, when the user approves team execution, pick the needed role ids, call spawn_role or evodev team spawn for each role, verify with list_agents/status, then send role-specific assignments."
-      : "As a non-main role, prefer coordinating with main through send_message, but lifecycle tools remain advisory and non-gating.",
-    input.role.nativeAgent === null
-      ? "No native Code Agent agent is bound to this role."
-      : `Use the bound native Code Agent agent name '${input.role.nativeAgent.agentName}' as role context when the runtime supports named agents; EvoDev does not load or transform the native agent file.`,
-    "Cross-agent messages are copied to main.",
-    "",
-    input.role.prompt,
-  ].join("\n");
+  now?: string;
+}): Promise<string> {
+  return createScopedTeamStartupContext(input).then((scopedContext) =>
+    renderTeamRoleStartupPrompt({ ...input, scopedContext }),
+  );
 }
 
-function formatDeliveredTeamMessage(message: TeamMessageRecord, cc: boolean): string {
-  const header = cc ? "[EvoDev team cc]" : "[EvoDev team message]";
-  const footer = cc ? "[/EvoDev team cc]" : "[/EvoDev team message]";
-  return [
-    header,
-    `from: ${message.fromRoleId}`,
-    `to: ${message.toRoleId}`,
-    `type: ${message.type}`,
-    `messageId: ${message.messageId}`,
-    cc ? "" : `cc: ${message.ccRoleIds.join(",") || "none"}`,
-    "",
-    message.body,
-    footer,
-  ]
-    .filter((line) => line !== "")
-    .join("\n");
+async function createScopedTeamStartupContext(input: {
+  homeDir?: string;
+  runId: string;
+  repoRoot: string;
+  role: ResolvedTeamRole;
+  now?: string;
+}): Promise<string | null> {
+  if (input.role.roleId === "main") return null;
+  const homeDir = resolveEvoDevPaths(input.homeDir).homeDir;
+  const settings = await readRuntimeInjectionSettings(homeDir);
+  if (!settings.runtimeInjection) return null;
+
+  const pack = await createScopedKnowledgeContextPack({
+    homeDir,
+    projectKey: resolveProjectLogKey(homeDir, input.repoRoot),
+    roleId: input.role.roleId,
+  });
+  if (pack === null) return null;
+
+  const sessionKey = `team-${input.runId}-${input.role.roleId}`;
+  if (await hasContextInjectionReceipt({ homeDir, sessionKey, contextPackId: pack.id })) {
+    return null;
+  }
+  await writeContextInjectionReceipt({
+    homeDir,
+    sessionKey,
+    pack,
+    trigger: "team-startup",
+    hookEventId: null,
+    injectedAt: input.now,
+  });
+  return formatScopedKnowledgePromptBlock(pack);
 }
 
 function buildAgentShellCommand(
@@ -1941,17 +2759,18 @@ function buildAgentShellCommand(
     runId: string;
     repoRoot: string;
     runtimeCommands?: TmuxRuntimeAdapterOptions["runtimeCommands"];
+    environment?: TmuxRuntimeAdapterOptions["environment"];
   },
 ): string {
   const args =
     role.runtime === "codex"
       ? buildCodexArgs(role, startupPrompt)
       : buildClaudeArgs(role, startupPrompt);
-  const env = {
+  const env = createAgentLaunchEnvironment(context.environment, {
     EVODEV_TEAM_RUN_ID: context.runId,
     EVODEV_TEAM_ROLE_ID: role.roleId,
     EVODEV_TEAM_REPO_ROOT: context.repoRoot,
-  };
+  });
   return buildAgentCommand(resolveRuntimeCommand(role.runtime, context.runtimeCommands), args, env);
 }
 
@@ -1963,21 +2782,48 @@ function buildAgentResumeShellCommand(
     repoRoot: string;
     mode: Exclude<TeamRuntimeAgentRecoveryMode, { type: "fresh" }>;
     runtimeCommands?: TmuxRuntimeAdapterOptions["runtimeCommands"];
+    environment?: TmuxRuntimeAdapterOptions["environment"];
   },
 ): string {
   const args =
     role.runtime === "codex"
       ? buildCodexResumeArgs(role, startupPrompt, context.mode)
       : buildClaudeResumeArgs(role, context.mode);
-  const env = {
+  const env = createAgentLaunchEnvironment(context.environment, {
     EVODEV_TEAM_RUN_ID: context.runId,
     EVODEV_TEAM_ROLE_ID: role.roleId,
     EVODEV_TEAM_REPO_ROOT: context.repoRoot,
     EVODEV_TEAM_RECOVERY: "1",
-  };
+  });
   return buildAgentCommand(resolveRuntimeCommand(role.runtime, context.runtimeCommands), args, env);
 }
 
+function createAgentLaunchEnvironment(
+  source: Record<string, string | undefined> | undefined,
+  evodev: Record<string, string>,
+): Record<string, string> {
+  return {
+    ...selectLocaleEnvironment(source ?? process.env),
+    ...evodev,
+  };
+}
+
+function selectLocaleEnvironment(
+  source: Record<string, string | undefined>,
+): Record<string, string> {
+  const selected: Record<string, string> = {};
+  for (const key of Object.keys(source).sort()) {
+    const value = source[key];
+    if (value === undefined || !isLocaleEnvironmentKey(key)) continue;
+    selected[key] = value;
+  }
+  return selected;
+}
+
+function isLocaleEnvironmentKey(key: string): boolean {
+  return key === "LANG" || key === "LANGUAGE" || key === "LC_ALL" || /^LC_[A-Z0-9_]+$/.test(key);
+}
+
 function buildAgentCommand(
   runtimeCommand: string,
   args: string[],
@@ -1998,7 +2844,7 @@ function resolveRuntimeCommand(
 function buildCodexArgs(role: ResolvedTeamRole, startupPrompt: string): string[] {
   const args = ["--no-alt-screen"];
   if (role.model !== null) args.push("--model", role.model);
-  args.push(startupPrompt);
+  if (shouldPassVisibleStartupPrompt(role)) args.push(startupPrompt);
   return args;
 }
 
@@ -2015,7 +2861,7 @@ function buildCodexResumeArgs(
   } else {
     args.push("--last");
   }
-  args.push(startupPrompt);
+  if (shouldPassVisibleStartupPrompt(role)) args.push(startupPrompt);
   return args;
 }
 
@@ -2023,10 +2869,14 @@ function buildClaudeArgs(role: ResolvedTeamRole, startupPrompt: string): string[
   const args = [];
   if (role.model !== null) args.push("--model", role.model);
   if (role.thinkingLevel !== null) args.push("--effort", role.thinkingLevel);
-  args.push(startupPrompt);
+  if (shouldPassVisibleStartupPrompt(role)) args.push(startupPrompt);
   return args;
 }
 
+function shouldPassVisibleStartupPrompt(role: ResolvedTeamRole): boolean {
+  return role.roleId !== "main";
+}
+
 function buildClaudeResumeArgs(
   role: ResolvedTeamRole,
   mode: Exclude<TeamRuntimeAgentRecoveryMode, { type: "fresh" }>,
@@ -2086,10 +2936,243 @@ function createBuiltInRole(roleId: string, runtime: TeamAgentRuntime): unknown {
   };
 }
 
+async function readTeamOverlayAgentSummaries(input: {
+  homeDir?: string;
+  repoRoot: string;
+  overlay: TeamOverlayResolution;
+}): Promise<TeamOverlayAgentSummary[]> {
+  const entries = Object.entries(input.overlay.definition.agents);
+  if (input.overlay.source === "builtin") {
+    return entries.map(([roleId]) => {
+      const builtin = BUILT_IN_ROLE_PROMPTS[roleId];
+      return {
+        roleId,
+        name: builtin?.roleName ?? defaultRoleName(roleId),
+        description: builtin?.description ?? `EvoDev ${roleId} role agent.`,
+        sourcePath: "builtin",
+      };
+    });
+  }
+
+  return Promise.all(
+    entries.map(([roleId, reference]) =>
+      readTeamAgentSummary({
+        homeDir: input.homeDir,
+        repoRoot: input.repoRoot,
+        roleId,
+        reference,
+      }),
+    ),
+  );
+}
+
+async function listDefaultTeamOverlayAssets(
+  assetsRootDir: string,
+): Promise<
+  Array<
+    | { kind: "team"; sourcePath: string; name: "team.md" }
+    | { kind: "agent"; sourcePath: string; name: string }
+  >
+> {
+  const teamPath = join(assetsRootDir, "team", "team.md");
+  const agentsDir = join(assetsRootDir, "team", "agents");
+  await assertReadableFile(teamPath, "Default team asset");
+
+  let entries: Array<{ name: string; isFile(): boolean }>;
+  try {
+    entries = (await readdir(agentsDir, { withFileTypes: true })) as Array<{
+      name: string;
+      isFile(): boolean;
+    }>;
+  } catch (error) {
+    throw new Error(
+      `Cannot read default team agents directory ${agentsDir}: ${describeError(error)}`,
+    );
+  }
+
+  const agentFiles = entries
+    .filter((entry) => entry.isFile() && extname(entry.name) === ".md")
+    .map((entry) => entry.name)
+    .sort();
+  if (agentFiles.length === 0) {
+    throw new Error(`Default team agents directory has no Markdown files: ${agentsDir}`);
+  }
+
+  return [
+    { kind: "team", sourcePath: teamPath, name: "team.md" },
+    ...agentFiles.map((name) => ({
+      kind: "agent" as const,
+      sourcePath: join(agentsDir, name),
+      name,
+    })),
+  ];
+}
+
+async function assertReadableFile(path: string, label: string): Promise<void> {
+  try {
+    const info = await stat(path);
+    if (!info.isFile()) throw new Error("not a file");
+  } catch (error) {
+    throw new Error(`${label} is not readable at ${path}: ${describeError(error)}`);
+  }
+}
+
+async function writeTextFileIfMissing(path: string, content: string): Promise<boolean> {
+  try {
+    await readFile(path, "utf8");
+    return false;
+  } catch (error) {
+    if (!isNotFoundError(error)) {
+      throw new Error(`Cannot inspect ${path}: ${describeError(error)}`);
+    }
+  }
+
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, content.endsWith("\n") ? content : `${content}\n`, "utf8");
+  return true;
+}
+
+function parseTeamDefinitionAgents(value: unknown): Record<string, string> {
+  if (value === undefined) return {};
+  if (!isRecord(value)) throw new Error("team.md agents must be a role-id map.");
+  const agents: Record<string, string> = {};
+  for (const [roleId, reference] of Object.entries(value)) {
+    assertSafeId(roleId, "team.md agents roleId");
+    if (typeof reference !== "string" || reference.trim() === "") {
+      throw new Error(`team.md agent reference for ${roleId} must be a non-empty string.`);
+    }
+    agents[roleId] = reference.trim();
+  }
+  return agents;
+}
+
+async function readTeamAgentMarkdown(reference: TeamAgentReference): Promise<string> {
+  if (extname(reference.sourcePath) !== ".md") {
+    throw new Error(`Team agent file for ${reference.roleId} must be Markdown.`);
+  }
+  try {
+    return await readFile(reference.sourcePath, "utf8");
+  } catch (error) {
+    if (isNotFoundError(error)) {
+      throw new Error(`Team agent file not found for ${reference.roleId}: ${reference.sourcePath}`);
+    }
+    throw new Error(
+      `Cannot read team agent file for ${reference.roleId}: ${reference.sourcePath}: ${describeError(
+        error,
+      )}`,
+    );
+  }
+}
+
+function parseMarkdownWithFrontmatter(content: string): {
+  frontmatter: Record<string, unknown>;
+  body: string;
+} {
+  const text = content.startsWith("\uFEFF") ? content.slice(1) : content;
+  const lines = text.split(/\r?\n/);
+  if (lines[0]?.trim() !== "---") return { frontmatter: {}, body: text };
+  const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+  if (end < 0) throw new Error("Markdown frontmatter is not closed.");
+  return {
+    frontmatter: parseSimpleYaml(lines.slice(1, end).join("\n")),
+    body: lines.slice(end + 1).join("\n"),
+  };
+}
+
+function parseSimpleYaml(content: string): Record<string, unknown> {
+  const root: Record<string, unknown> = {};
+  const stack: Array<{ indent: number; value: Record<string, unknown> | unknown[] }> = [
+    { indent: -1, value: root },
+  ];
+  const lines = content.split(/\r?\n/);
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const rawLine = lines[index] ?? "";
+    if (rawLine.trim() === "" || rawLine.trimStart().startsWith("#")) continue;
+    const indent = rawLine.match(/^ */)?.[0].length ?? 0;
+    const trimmed = rawLine.trim();
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) stack.pop();
+    const parent = stack[stack.length - 1].value;
+
+    if (trimmed.startsWith("- ")) {
+      if (!Array.isArray(parent)) throw new Error("Invalid YAML list item placement.");
+      parent.push(parseYamlScalar(trimmed.slice(2).trim()));
+      continue;
+    }
+
+    const separator = trimmed.indexOf(":");
+    if (separator <= 0) throw new Error(`Invalid YAML line: ${trimmed}`);
+    const key = trimmed.slice(0, separator).trim();
+    const rawValue = trimmed.slice(separator + 1).trim();
+    if (!isRecord(parent)) throw new Error(`Invalid YAML parent for key ${key}.`);
+
+    if (rawValue === "") {
+      const next = findNextYamlContentLine(lines, index + 1);
+      const value: Record<string, unknown> | unknown[] =
+        next !== null && next.indent > indent && next.trimmed.startsWith("- ") ? [] : {};
+      parent[key] = value;
+      stack.push({ indent, value });
+      continue;
+    }
+
+    parent[key] = parseYamlScalar(rawValue);
+  }
+
+  return root;
+}
+
+function findNextYamlContentLine(
+  lines: string[],
+  start: number,
+): { indent: number; trimmed: string } | null {
+  for (let index = start; index < lines.length; index += 1) {
+    const line = lines[index] ?? "";
+    if (line.trim() === "" || line.trimStart().startsWith("#")) continue;
+    return {
+      indent: line.match(/^ */)?.[0].length ?? 0,
+      trimmed: line.trim(),
+    };
+  }
+  return null;
+}
+
+function parseYamlScalar(value: string): unknown {
+  if (value === "") return "";
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (value === "null" || value === "~") return null;
+  if (/^-?\d+(\.\d+)?$/.test(value)) return Number(value);
+  if (value.startsWith("[") && value.endsWith("]")) {
+    const inner = value.slice(1, -1).trim();
+    if (inner === "") return [];
+    return inner.split(",").map((item) => parseYamlScalar(item.trim()));
+  }
+  if (value.startsWith('"') && value.endsWith('"')) {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value.slice(1, -1);
+    }
+  }
+  if (value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1).replace(/''/g, "'");
+  }
+  return value;
+}
+
+function appendPromptBlock(prompt: string, block: string): string {
+  if (block.trim() === "") return prompt;
+  return `${prompt.trimEnd()}\n\n${block.trim()}`;
+}
+
+function resolveGlobalTeamMarkdownPath(homeDir?: string): string {
+  return join(resolveEvoDevPaths(homeDir).rootDir, "team", "team.md");
+}
+
 function parseRolePermissions(value: unknown, main: boolean): TeamRolePermissions {
   const input = isRecord(value) ? value : {};
   return {
-    writeMode: parseWriteMode(input.writeMode, main ? "repo-write" : "read-only"),
+    writeMode: parseWriteMode(input.writeMode, "repo-write"),
     canUseTeamsMcp: optionalBoolean(input.canUseTeamsMcp) ?? true,
     canSpawnAgents: optionalBoolean(input.canSpawnAgents) ?? main,
     canStopAgents: optionalBoolean(input.canStopAgents) ?? main,
@@ -2119,7 +3202,22 @@ function parseTeamAgentRecord(value: unknown): TeamAgentRecord {
   const agent = value as unknown as TeamAgentRecord;
   assertSafeId(agent.agentId, "agentId");
   assertSafeId(agent.roleId, "roleId");
-  if (!["running", "recovering", "recreated", "stopped", "failed"].includes(agent.status)) {
+  if (
+    ![
+      "starting",
+      "running",
+      "busy",
+      "idle",
+      "waiting-input",
+      "recovering",
+      "recreated",
+      "stopped",
+      "exited",
+      "needs-user-attention",
+      "failed",
+      "unknown",
+    ].includes(agent.status)
+  ) {
     throw new Error("Invalid agent status.");
   }
   const nativeSessionValue = isRecord(value.nativeSession) ? value.nativeSession : {};
@@ -2142,6 +3240,48 @@ function parseTeamMessageRecord(value: unknown): TeamMessageRecord {
   return message;
 }
 
+function createPendingMessageRecord(message: TeamMessageRecord): TeamPendingMessageRecord {
+  return {
+    ...message,
+    deliveryState: "pending",
+    attemptCount: 0,
+    lastAttemptAt: null,
+  };
+}
+
+function parseTeamPendingMessageRecord(value: unknown): TeamPendingMessageRecord {
+  const message = parseTeamMessageRecord(value);
+  const input = value as Partial<TeamPendingMessageRecord>;
+  const deliveryState =
+    input.deliveryState === "pending" ||
+    input.deliveryState === "claimed" ||
+    input.deliveryState === "wakeup-sent" ||
+    input.deliveryState === "failed"
+      ? input.deliveryState
+      : "pending";
+  return {
+    ...message,
+    deliveryState,
+    attemptCount:
+      typeof input.attemptCount === "number" && Number.isInteger(input.attemptCount)
+        ? input.attemptCount
+        : 0,
+    lastAttemptAt: optionalString(input.lastAttemptAt) ?? null,
+  };
+}
+
+function parseTeamMessageListFile(value: unknown): TeamMessageListFile {
+  if (!isRecord(value) || value.version !== 1) throw new Error("Invalid team message list.");
+  const messages = Array.isArray(value.messages)
+    ? value.messages.map(parseTeamPendingMessageRecord)
+    : [];
+  return {
+    version: 1,
+    updatedAt: optionalString(value.updatedAt) ?? null,
+    messages,
+  };
+}
+
 function parseTeamEventRecord(value: unknown): TeamEventRecord {
   if (!isRecord(value) || value.version !== 1) throw new Error("Invalid team event record.");
   const event = value as unknown as TeamEventRecord;
@@ -2157,6 +3297,12 @@ function parseRuntime(value: unknown, fallback: TeamAgentRuntime): TeamAgentRunt
   throw new Error("Role runtime must be codex or claude.");
 }
 
+function optionalRuntime(value: unknown): TeamAgentRuntime | null {
+  if (value === undefined || value === null) return null;
+  if (value === "codex" || value === "claude") return value;
+  throw new Error("Role evodev.runtime must be codex or claude.");
+}
+
 function parseWriteMode(value: unknown, fallback: TeamWriteMode): TeamWriteMode {
   if (value === undefined || value === null) return fallback;
   if (["read-only", "repo-write", "worktree-write", "disabled"].includes(String(value))) {
@@ -2165,8 +3311,55 @@ function parseWriteMode(value: unknown, fallback: TeamWriteMode): TeamWriteMode
   throw new Error("Role writeMode is invalid.");
 }
 
-function isActiveTeamAgentStatus(status: TeamAgentStatus): boolean {
-  return status === "running" || status === "recovering" || status === "recreated";
+function optionalWriteMode(value: unknown): TeamWriteMode | null {
+  if (value === undefined || value === null) return null;
+  return parseWriteMode(value, "repo-write");
+}
+
+function parseStringList(value: unknown): string[] {
+  if (value === undefined || value === null) return [];
+  if (typeof value === "string" && value.trim() !== "") return [value.trim()];
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === "string" && item.trim() !== "");
+}
+
+export function isActiveTeamAgentStatus(status: TeamAgentStatus): boolean {
+  return (
+    status === "starting" ||
+    status === "running" ||
+    status === "busy" ||
+    status === "idle" ||
+    status === "waiting-input" ||
+    status === "recovering" ||
+    status === "recreated"
+  );
+}
+
+export function isIdleTeamAgentStatus(status: TeamAgentStatus): boolean {
+  return status === "idle" || status === "waiting-input";
+}
+
+export function isMidTurnTeamAgentStatus(status: TeamAgentStatus): boolean {
+  return status === "busy";
+}
+
+function teamAgentStatusForHookEvent(
+  hookEvent: string,
+  fallback: TeamAgentStatus,
+): TeamAgentStatus {
+  if (hookEvent === "PreToolUse") return "busy";
+  if (
+    hookEvent === "Stop" ||
+    hookEvent === "TeammateIdle" ||
+    hookEvent === "SubagentStop" ||
+    hookEvent === "TaskCompleted"
+  ) {
+    return "idle";
+  }
+  if (hookEvent === "SessionStart" || hookEvent === "UserPromptSubmit") return "running";
+  if (hookEvent === "PostToolUse" || hookEvent === "PostToolUseFailure") return "running";
+  if (hookEvent === "SessionEnd") return "waiting-input";
+  return fallback;
 }
 
 function createRunId(repoRoot: string, now: Date): string {
@@ -2215,6 +3408,34 @@ function sanitizeWindowName(value: string): string {
   return safeSlug(value).slice(0, 30) || "agent";
 }
 
+function formatTeamPaneTitle(role: ResolvedTeamRole): string {
+  const label = role.roleName === role.roleId ? role.roleId : `${role.roleName} [${role.roleId}]`;
+  const title = normalizeTmuxPaneTitle(label);
+  return title.slice(0, 80) || role.roleId;
+}
+
+function normalizeTmuxPaneTitle(value: string): string {
+  let normalized = "";
+  let pendingSpace = false;
+
+  for (const char of value) {
+    const code = char.charCodeAt(0);
+    const isControl = code < 32 || code === 127;
+    if (isControl || char.trim() === "") {
+      pendingSpace = normalized.length > 0;
+      continue;
+    }
+
+    if (pendingSpace) {
+      normalized += " ";
+      pendingSpace = false;
+    }
+    normalized += char;
+  }
+
+  return normalized;
+}
+
 function defaultRoleName(roleId: string): string {
   return roleId
     .split(/[-_.]/)
@@ -2352,6 +3573,16 @@ function isNotFoundError(error: unknown): boolean {
   );
 }
 
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (isNotFoundError(error)) return false;
+    throw error;
+  }
+}
+
 async function writeJson(path: string, value: unknown): Promise<void> {
   await mkdir(dirname(path), { recursive: true });
   await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
@@ -2362,6 +3593,19 @@ async function appendJsonLine(path: string, value: unknown): Promise<void> {
   await appendFile(path, `${JSON.stringify(value)}\n`, "utf8");
 }
 
+async function readJsonLines<T>(path: string, parse: (value: unknown) => T): Promise<T[]> {
+  try {
+    const text = await readFile(path, "utf8");
+    return text
+      .split("\n")
+      .filter((line) => line.trim() !== "")
+      .map((line) => parse(JSON.parse(line)));
+  } catch (error) {
+    if (isNotFoundError(error)) return [];
+    throw error;
+  }
+}
+
 function shellQuote(value: string): string {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }