@evo-dev/core 0.0.1-alpha → 0.0.1-alpha.10

package/src/team/index.ts

@@ -0,0 +1,3642 @@
+import { spawn } from "node:child_process";
+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,
+  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 =
+  | "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" }
+  | { type: "fresh" };
+export type TeamSessionMissingDecision = "ask" | "fail" | "recreate" | "resume-latest";
+
+export interface TeamRuntimeCommandResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export interface TeamRuntimeCommandRunner {
+  run(
+    command: string,
+    args: string[],
+    options?: { input?: string },
+  ): Promise<TeamRuntimeCommandResult>;
+}
+
+export interface TmuxRuntimeAdapterOptions {
+  runtimeCommands?: Partial<Record<TeamAgentRuntime, string>>;
+  environment?: Record<string, string | undefined>;
+}
+
+export interface TeamRuntimeAdapter {
+  createRun(input: TeamRuntimeCreateRunInput): Promise<TeamRuntimeAgentHandle>;
+  spawnAgent(input: TeamRuntimeSpawnAgentInput): Promise<TeamRuntimeAgentHandle>;
+  recoverAgent(input: TeamRuntimeRecoverAgentInput): Promise<TeamRuntimeAgentHandle>;
+  sendInput(input: TeamRuntimeSendInputInput): Promise<void>;
+  listPanes(input: TeamRuntimeListPanesInput): Promise<TeamRuntimePaneInfo[]>;
+  stopAgent(input: TeamRuntimeStopAgentInput): Promise<void>;
+  stopRun(input: TeamRuntimeStopRunInput): Promise<void>;
+  formatAttachCommand(input: TeamRuntimeAttachInput): string;
+}
+
+export interface TeamRuntimeCreateRunInput {
+  runId: string;
+  sessionName: string;
+  repoRoot: string;
+  role: ResolvedTeamRole;
+  startupPrompt: string;
+}
+
+export interface TeamRuntimeSpawnAgentInput {
+  runId: string;
+  sessionName: string;
+  repoRoot: string;
+  role: ResolvedTeamRole;
+  startupPrompt: string;
+  targetPaneId?: string;
+}
+
+export interface TeamRuntimeRecoverAgentInput {
+  runId: string;
+  sessionName: string;
+  repoRoot: string;
+  role: ResolvedTeamRole;
+  startupPrompt: string;
+  mode: TeamRuntimeAgentRecoveryMode;
+  targetPaneId?: string;
+}
+
+export interface TeamRuntimeAgentHandle {
+  session: string;
+  window: string;
+  paneId: string;
+  nativeSessionId?: string | null;
+}
+
+export interface TeamRuntimeSendInputInput {
+  session: string;
+  paneId: string;
+  text: string;
+}
+
+export interface TeamRuntimeListPanesInput {
+  session: string;
+}
+
+export interface TeamRuntimePaneInfo {
+  paneId: string;
+}
+
+export interface TeamRuntimeStopRunInput {
+  session: string;
+}
+
+export interface TeamRuntimeStopAgentInput {
+  session: string;
+  paneId: string;
+}
+
+export interface TeamRuntimeAttachInput {
+  session: string;
+  paneId?: string;
+}
+
+export interface TeamRoleRuntimeContextInput {
+  homeDir?: string;
+  runId: string;
+  roleId: string;
+}
+
+export interface TeamRolePermissions {
+  writeMode: TeamWriteMode;
+  canUseTeamsMcp: boolean;
+  canSpawnAgents: boolean;
+  canStopAgents: boolean;
+}
+
+export interface TeamRolePolicy {
+  roleInstancePolicy: "single-per-role";
+  recordTranscript: boolean;
+}
+
+export interface TeamRoleDefinition {
+  version: 1;
+  roleId: string;
+  roleName: string;
+  description: string;
+  runtime: TeamAgentRuntime;
+  model: string | null;
+  thinkingLevel: string | null;
+  prompt: string;
+  permissions: TeamRolePermissions;
+  teamPolicy: TeamRolePolicy;
+  source: "builtin" | "global" | "overlay";
+}
+
+export interface ResolvedTeamRole extends TeamRoleDefinition {
+  sourcePath: string | null;
+  nativeAgent: TeamNativeAgentBinding | null;
+}
+
+export interface TeamNativeAgentBinding {
+  roleId: string;
+  target: TeamAgentRuntime;
+  agentName: string;
+  scope: "global" | "project";
+  projectKey: string | null;
+  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;
+  target: TeamAgentRuntime;
+  agentName: string;
+  updatedAt: string;
+}
+
+export interface TeamRoleBindingConfig {
+  version: 1;
+  updatedAt: string;
+  roles: TeamRoleBindingRecord[];
+}
+
+export interface TeamRoleBindingScopeInput {
+  homeDir?: string;
+  repoRoot?: string;
+  scope: "global" | "project";
+}
+
+export interface TeamRunRecord {
+  version: 1;
+  runId: string;
+  repoRoot: string;
+  status: TeamRunStatus;
+  mainAgentId: string;
+  roleInstancePolicy: "single-per-role";
+  tmux: {
+    session: string;
+  };
+  roles: Record<string, string>;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface TeamAgentRecord {
+  version: 1;
+  agentId: string;
+  roleId: string;
+  roleName: string;
+  runId: string;
+  runtime: TeamAgentRuntime;
+  model: string | null;
+  thinkingLevel: string | null;
+  status: TeamAgentStatus;
+  permissions: TeamRolePermissions;
+  nativeSession: {
+    sessionId: string | null;
+    capturedAt: string | null;
+  };
+  tmux: {
+    session: string;
+    window: string;
+    paneId: string;
+  };
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface TeamMessageRecord {
+  version: 1;
+  messageId: string;
+  runId: string;
+  fromRoleId: string;
+  toRoleId: string;
+  ccRoleIds: string[];
+  type: TeamMessageType;
+  body: string;
+  status: "accepted";
+  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;
+  runId: string;
+  type:
+    | "TeamRunStarted"
+    | "AgentSpawned"
+    | "AgentStopped"
+    | "TeamMessageAccepted"
+    | "TeamMessageDelivered"
+    | "TeamMessageDeliveryFailed"
+    | "TeamMessageWakeupSent"
+    | "AgentNativeSessionRecorded"
+    | "AgentHookStateUpdated"
+    | "AgentRecoveryDecisionRequired"
+    | "AgentRecovered"
+    | "AgentRecreated"
+    | "TeamRunStopped";
+  roleId?: string;
+  agentId?: string;
+  messageId?: string;
+  summary: string;
+  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;
+  now?: Date;
+  mainOverrides?: Partial<{
+    runtime: TeamAgentRuntime;
+    model: string | null;
+    thinkingLevel: string | null;
+  }>;
+  runtimeAdapter?: TeamRuntimeAdapter;
+}
+
+export interface SpawnTeamRoleInput {
+  homeDir?: string;
+  repoRoot: string;
+  runId?: string;
+  roleId: string;
+  now?: Date;
+  runtimeAdapter?: TeamRuntimeAdapter;
+}
+
+export interface StopTeamRoleInput {
+  homeDir?: string;
+  runId?: string;
+  roleId: string;
+  now?: Date;
+  runtimeAdapter?: TeamRuntimeAdapter;
+}
+
+export interface SendTeamMessageInput {
+  homeDir?: string;
+  runId?: string;
+  fromRoleId?: string;
+  toRoleId: string;
+  message: string;
+  type?: TeamMessageType;
+  now?: Date;
+  runtimeAdapter?: TeamRuntimeAdapter;
+}
+
+export interface StopTeamRunInput {
+  homeDir?: string;
+  runId?: string;
+  now?: Date;
+  runtimeAdapter?: TeamRuntimeAdapter;
+}
+
+export interface TeamStatusInput {
+  homeDir?: string;
+  runId?: string;
+}
+
+export interface ListTeamRunsInput {
+  homeDir?: string;
+}
+
+export interface ReconcileTeamRunInput {
+  homeDir?: string;
+  runId?: string;
+  now?: Date;
+  runtimeAdapter?: TeamRuntimeAdapter;
+  notifyMain?: boolean;
+}
+
+export interface ResumeTeamRunInput {
+  homeDir?: string;
+  runId?: string;
+  now?: Date;
+  runtimeAdapter?: TeamRuntimeAdapter;
+  missingSessionDecision?: TeamSessionMissingDecision;
+  notifyMain?: boolean;
+}
+
+export interface RecordTeamAgentNativeSessionInput {
+  homeDir?: string;
+  runId?: string;
+  roleId: string;
+  sessionId: string;
+  now?: Date;
+}
+
+export interface TeamAttachInput {
+  homeDir?: string;
+  runId?: string;
+  roleId?: string;
+  runtimeAdapter?: TeamRuntimeAdapter;
+}
+
+export interface TeamRunStartResult {
+  run: TeamRunRecord;
+  mainAgent: TeamAgentRecord;
+}
+
+export interface TeamRoleSpawnResult {
+  run: TeamRunRecord;
+  agent: TeamAgentRecord;
+  created: boolean;
+}
+
+export interface TeamRoleStopResult {
+  ok: boolean;
+  run?: TeamRunRecord;
+  agent?: TeamAgentRecord;
+  stopped?: boolean;
+  error?: string;
+  message?: string;
+}
+
+export interface TeamRoleLifecycleSpawnResult {
+  ok: boolean;
+  run?: TeamRunRecord;
+  agent?: TeamAgentRecord;
+  created?: boolean;
+  error?: string;
+  message?: string;
+}
+
+export async function listTeamRoleBindings(input: {
+  homeDir?: string;
+  repoRoot?: string;
+}): Promise<TeamNativeAgentBinding[]> {
+  const global = (
+    await readTeamBindingConfig(resolveGlobalTeamBindingPath(input.homeDir))
+  ).roles.map((record) => bindingRecordToNative(record, "global", null));
+  if (input.repoRoot === undefined) return global;
+
+  const projectKey = resolveProjectLogKey(
+    resolveEvoDevPaths(input.homeDir).homeDir,
+    input.repoRoot,
+  );
+  const project = (
+    await readTeamBindingConfig(resolveProjectTeamBindingPath(input.homeDir, projectKey))
+  ).roles.map((record) => bindingRecordToNative(record, "project", projectKey));
+  return mergeTeamRoleBindings(global, project);
+}
+
+export async function setTeamRoleBinding(input: {
+  homeDir?: string;
+  repoRoot?: string;
+  scope: "global" | "project";
+  roleId: string;
+  target: TeamAgentRuntime;
+  agentName: string;
+  now?: Date;
+}): Promise<{ path: string; binding: TeamNativeAgentBinding }> {
+  assertSafeId(input.roleId, "roleId");
+  assertSafeId(input.agentName, "agentName");
+  const { path, projectKey } = resolveTeamBindingWritePath(input);
+  const timestamp = (input.now ?? new Date()).toISOString();
+  const current = await readTeamBindingConfig(path);
+  const nextRecord: TeamRoleBindingRecord = {
+    version: 1,
+    roleId: input.roleId,
+    target: input.target,
+    agentName: input.agentName,
+    updatedAt: timestamp,
+  };
+  const roles = [
+    ...current.roles.filter((record) => record.roleId !== input.roleId),
+    nextRecord,
+  ].sort((left, right) => left.roleId.localeCompare(right.roleId));
+  await writeJson(path, { version: 1, updatedAt: timestamp, roles });
+  return { path, binding: bindingRecordToNative(nextRecord, input.scope, projectKey) };
+}
+
+export async function unsetTeamRoleBinding(input: {
+  homeDir?: string;
+  repoRoot?: string;
+  scope: "global" | "project";
+  roleId: string;
+  now?: Date;
+}): Promise<{ path: string; removed: boolean }> {
+  assertSafeId(input.roleId, "roleId");
+  const { path } = resolveTeamBindingWritePath(input);
+  const current = await readTeamBindingConfig(path);
+  const roles = current.roles.filter((record) => record.roleId !== input.roleId);
+  const removed = roles.length !== current.roles.length;
+  if (removed) {
+    await writeJson(path, {
+      version: 1,
+      updatedAt: (input.now ?? new Date()).toISOString(),
+      roles,
+    });
+  }
+  return { path, removed };
+}
+
+export interface TeamMessageSendResult {
+  ok: boolean;
+  messageId?: string;
+  delivery?: "queued";
+  queuedFor?: string;
+  cc?: string[];
+  error?: string;
+  message?: string;
+}
+
+export interface TeamMessageBrokerOptions {
+  homeDir?: string;
+  runtimeAdapter?: TeamRuntimeAdapter;
+}
+
+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;
+  roleId: string;
+  reason?: string;
+  now?: Date;
+}
+
+export interface TeamMessageBrokerStopInput {
+  runId?: string;
+  fromRoleId?: string;
+  roleId: string;
+  reason?: string;
+  now?: Date;
+}
+
+export interface TeamStatusResult {
+  run: TeamRunRecord | null;
+  agents: TeamAgentRecord[];
+}
+
+export interface TeamRunReconcileResult extends TeamStatusResult {
+  stoppedAgents: TeamAgentRecord[];
+  notifications: TeamMessageSendResult[];
+  runtimeAvailable: boolean;
+}
+
+export interface TeamAgentRecoveryResult {
+  roleId: string;
+  agentId: string;
+  outcome: "reused" | "resumed" | "recreated" | "needs-decision" | "failed";
+  previousPaneId: string;
+  paneId: string | null;
+  nativeSessionId: string | null;
+  reason?: string;
+  decisionOptions?: TeamSessionMissingDecision[];
+}
+
+export interface TeamRunResumeResult extends TeamStatusResult {
+  outcomes: TeamAgentRecoveryResult[];
+  decisionRequired: TeamAgentRecoveryResult[];
+  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 {
+  paths: ReturnType<typeof resolveTeamRunPaths>;
+  createRunDirs(runId: string): Promise<void>;
+  writeRun(run: TeamRunRecord): Promise<void>;
+  readRun(runId: string): Promise<TeamRunRecord>;
+  writeLatestRunId(runId: string): Promise<void>;
+  readLatestRunId(): Promise<string | null>;
+  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 }
+> = {
+  main: {
+    roleName: "Main Conductor",
+    description: "Coordinates the EvoDev team run and owns final synthesis.",
+    prompt:
+      "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 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 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, 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);
+
+  return {
+    paths,
+    async createRunDirs(runId) {
+      await migrateLegacyRunDirIfNeeded(paths, runId);
+      await mkdir(paths.runDir(runId), { recursive: true });
+      await mkdir(paths.agentsDir(runId), { recursive: true });
+    },
+    async writeRun(run) {
+      await this.createRunDirs(run.runId);
+      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) {
+      await mkdir(paths.runsDir, { recursive: true });
+      await writeJson(paths.latestRunPath, { version: 1, runId });
+    },
+    async readLatestRunId() {
+      try {
+        const latest = JSON.parse(await readFile(paths.latestRunPath, "utf8"));
+        if (latest?.version === 1 && typeof latest.runId === "string") return latest.runId;
+        return null;
+      } catch {
+        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) {
+      await this.createRunDirs(agent.runId);
+      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(
+          entries
+            .filter((entry) => entry.endsWith(".json"))
+            .map((entry) =>
+              readFile(join(paths.agentsDir(runId), entry), "utf8").then((raw) =>
+                parseTeamAgentRecord(JSON.parse(raw)),
+              ),
+            ),
+        );
+        return agents.sort((left, right) => left.roleId.localeCompare(right.roleId));
+      } catch {
+        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);
+      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);
+      await appendJsonLine(paths.eventsPath(runId), parseTeamEventRecord(event));
+    },
+  };
+}
+
+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();
+  const createdAt = now.toISOString();
+  const runId = createRunId(input.repoRoot, now);
+  const sessionName = createTmuxSessionName(input.repoRoot, runId);
+  const role = await resolveTeamRole({
+    homeDir: input.homeDir,
+    repoRoot: input.repoRoot,
+    roleId: "main",
+    overrides: input.mainOverrides,
+  });
+  const runtimeAdapter = input.runtimeAdapter ?? createTmuxRuntimeAdapter();
+  const startupPrompt = await createAgentStartupPrompt({
+    homeDir: input.homeDir,
+    runId,
+    repoRoot: input.repoRoot,
+    role,
+    roster: [],
+    now: createdAt,
+  });
+  const handle = await runtimeAdapter.createRun({
+    runId,
+    sessionName,
+    repoRoot: input.repoRoot,
+    role,
+    startupPrompt,
+  });
+  const agent = createAgentRecord({
+    runId,
+    role,
+    handle,
+    now: createdAt,
+  });
+  const run: TeamRunRecord = {
+    version: 1,
+    runId,
+    repoRoot: input.repoRoot,
+    status: "running",
+    mainAgentId: agent.agentId,
+    roleInstancePolicy: "single-per-role",
+    tmux: { session: handle.session },
+    roles: { main: agent.agentId },
+    createdAt,
+    updatedAt: createdAt,
+  };
+
+  await store.writeRun(run);
+  await store.writeAgent(agent);
+  await store.writeLatestRunId(runId);
+  await writeJson(store.paths.tmuxPath(runId), {
+    version: 1,
+    runtime: "tmux",
+    session: handle.session,
+    createdAt,
+    windows: [{ name: handle.window, roles: ["main"] }],
+  });
+  await store.appendEvent(
+    runId,
+    createTeamEvent(runId, "TeamRunStarted", `Started team run ${runId}.`, createdAt, {
+      roleId: "main",
+      agentId: agent.agentId,
+    }),
+  );
+  await writeTeamStatusSnapshot({
+    store,
+    runId,
+    now: createdAt,
+    lastEvent: "TeamRunStarted",
+  });
+
+  return { run, mainAgent: agent };
+}
+
+export async function spawnTeamRole(input: SpawnTeamRoleInput): Promise<TeamRoleSpawnResult> {
+  const store = createTeamRunStore(input.homeDir);
+  const runId = await resolveRequestedRunId(store, input.runId);
+  const run = await store.readRun(runId);
+  if (run.status !== "running") throw new Error(`Team run ${run.runId} is not running.`);
+  const existingAgentId = run.roles[input.roleId];
+  if (existingAgentId !== undefined) {
+    const existing = await store.readAgent(run.runId, input.roleId);
+    if (isActiveTeamAgentStatus(existing.status)) {
+      return { run, agent: existing, created: false };
+    }
+  }
+
+  const now = (input.now ?? new Date()).toISOString();
+  const role = await resolveTeamRole({
+    homeDir: input.homeDir,
+    repoRoot: input.repoRoot,
+    roleId: input.roleId,
+  });
+  const agents = await store.readAgents(run.runId);
+  const mainAgent = agents.find((agent) => agent.roleId === "main");
+  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({
+    runId: run.runId,
+    sessionName: run.tmux.session,
+    repoRoot: run.repoRoot,
+    role,
+    startupPrompt,
+    targetPaneId: mainAgent?.tmux.paneId,
+  });
+  const agent = createAgentRecord({ runId: run.runId, role, handle, now });
+  const updatedRun: TeamRunRecord = {
+    ...run,
+    roles: { ...run.roles, [role.roleId]: agent.agentId },
+    updatedAt: now,
+  };
+
+  await store.writeRun(updatedRun);
+  await store.writeAgent(agent);
+  await store.appendEvent(
+    run.runId,
+    createTeamEvent(run.runId, "AgentSpawned", `Spawned role ${role.roleId}.`, now, {
+      roleId: role.roleId,
+      agentId: agent.agentId,
+    }),
+  );
+  await writeTeamStatusSnapshot({
+    store,
+    runId: run.runId,
+    now,
+    lastEvent: "AgentSpawned",
+  });
+
+  return { run: updatedRun, agent, created: true };
+}
+
+export async function stopTeamRole(input: StopTeamRoleInput): Promise<TeamRoleStopResult> {
+  const store = createTeamRunStore(input.homeDir);
+  const runId = await resolveRequestedRunId(store, input.runId);
+  const run = await store.readRun(runId);
+  if (run.status !== "running") {
+    return {
+      ok: false,
+      error: "team-run-not-running",
+      message: `Team run ${run.runId} is not running.`,
+    };
+  }
+  if (input.roleId === "main") {
+    return {
+      ok: false,
+      error: "cannot-stop-main-role",
+      message: "Use evodev team stop to stop the entire team run instead of stopping main.",
+    };
+  }
+
+  const agentId = run.roles[input.roleId];
+  if (agentId === undefined) {
+    return {
+      ok: false,
+      error: "target-role-not-found",
+      message: `Role ${input.roleId} does not exist in run ${run.runId}.`,
+    };
+  }
+
+  const agent = await store.readAgent(run.runId, input.roleId);
+  if (!isActiveTeamAgentStatus(agent.status)) {
+    return {
+      ok: false,
+      error: "target-role-not-running",
+      message: `Role ${input.roleId} is not running in run ${run.runId}.`,
+    };
+  }
+
+  const now = (input.now ?? new Date()).toISOString();
+  const runtimeAdapter = input.runtimeAdapter ?? createTmuxRuntimeAdapter();
+  await runtimeAdapter.stopAgent({
+    session: agent.tmux.session,
+    paneId: agent.tmux.paneId,
+  });
+  const stoppedAgent: TeamAgentRecord = { ...agent, status: "stopped", updatedAt: now };
+  const updatedRun: TeamRunRecord = { ...run, updatedAt: now };
+  await store.writeRun(updatedRun);
+  await store.writeAgent(stoppedAgent);
+  await store.appendEvent(
+    run.runId,
+    createTeamEvent(run.runId, "AgentStopped", `Stopped role ${input.roleId}.`, now, {
+      roleId: input.roleId,
+      agentId,
+    }),
+  );
+  await writeTeamStatusSnapshot({
+    store,
+    runId: run.runId,
+    now,
+    lastEvent: "AgentStopped",
+  });
+
+  return { ok: true, run: updatedRun, agent: stoppedAgent, stopped: true };
+}
+
+export class TeamMessageBroker {
+  constructor(private readonly options: TeamMessageBrokerOptions = {}) {}
+
+  async listAgents(input: TeamStatusInput = {}): Promise<TeamAgentSummary[]> {
+    return listTeamAgents({ homeDir: this.options.homeDir, runId: input.runId });
+  }
+
+  async send(input: TeamMessageBrokerSendInput): Promise<TeamMessageSendResult> {
+    return sendTeamMessageWithBrokerContext(this.options, input);
+  }
+
+  async spawnRole(input: TeamMessageBrokerSpawnInput): Promise<TeamRoleLifecycleSpawnResult> {
+    return spawnTeamRoleWithBrokerContext(this.options, input);
+  }
+
+  async stopRole(input: TeamMessageBrokerStopInput): Promise<TeamRoleStopResult> {
+    return stopTeamRoleWithBrokerContext(this.options, input);
+  }
+}
+
+export async function sendTeamMessage(input: SendTeamMessageInput): Promise<TeamMessageSendResult> {
+  return new TeamMessageBroker({
+    homeDir: input.homeDir,
+    runtimeAdapter: input.runtimeAdapter,
+  }).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,
+): Promise<TeamMessageSendResult> {
+  const store = createTeamRunStore(options.homeDir);
+  const runId = await resolveRequestedRunId(store, input.runId);
+  const run = await store.readRun(runId);
+  if (run.status !== "running") {
+    return {
+      ok: false,
+      error: "team-run-not-running",
+      message: `Team run ${run.runId} is not running.`,
+    };
+  }
+  const targetAgentId = run.roles[input.toRoleId];
+  if (targetAgentId === undefined) {
+    return {
+      ok: false,
+      error: "target-role-not-found",
+      message: `Role ${input.toRoleId} does not exist in run ${run.runId}.`,
+    };
+  }
+  const target = await store.readAgent(run.runId, input.toRoleId);
+  if (target.status === "failed" || target.status === "unknown") {
+    return {
+      ok: false,
+      error: "target-role-unavailable",
+      message: `Role ${input.toRoleId} is not available in run ${run.runId}.`,
+    };
+  }
+
+  const now = (input.now ?? new Date()).toISOString();
+  const fromRoleId = input.fromRoleId ?? "user";
+  const ccRoleIds =
+    fromRoleId !== "user" && fromRoleId !== "main" && input.toRoleId !== "main" && run.roles.main
+      ? ["main"]
+      : [];
+  const message: TeamMessageRecord = {
+    version: 1,
+    messageId: createMessageId(now),
+    runId: run.runId,
+    fromRoleId,
+    toRoleId: input.toRoleId,
+    ccRoleIds,
+    type: input.type ?? "request",
+    body: input.message,
+    status: "accepted",
+    createdAt: now,
+  };
+
+  await store.appendMessage(run.runId, message);
+  await store.appendEvent(
+    run.runId,
+    createTeamEvent(
+      run.runId,
+      "TeamMessageAccepted",
+      `Accepted message ${message.messageId}.`,
+      now,
+      {
+        messageId: message.messageId,
+      },
+    ),
+  );
+  await schedulePendingTeamMessageDelivery({
+    homeDir: options.homeDir,
+    runId: run.runId,
+    roleId: input.toRoleId,
+    now: new Date(now),
+    runtimeAdapter: options.runtimeAdapter,
+  });
+
+  return {
+    ok: true,
+    messageId: message.messageId,
+    delivery: "queued",
+    queuedFor: input.toRoleId,
+    cc: ccRoleIds,
+  };
+}
+
+async function spawnTeamRoleWithBrokerContext(
+  options: TeamMessageBrokerOptions,
+  input: TeamMessageBrokerSpawnInput,
+): Promise<TeamRoleLifecycleSpawnResult> {
+  const store = createTeamRunStore(options.homeDir);
+  const runId = await resolveRequestedRunId(store, input.runId);
+  const run = await store.readRun(runId);
+
+  try {
+    const result = await spawnTeamRole({
+      homeDir: options.homeDir,
+      repoRoot: run.repoRoot,
+      runId: run.runId,
+      roleId: input.roleId,
+      now: input.now,
+      runtimeAdapter: options.runtimeAdapter,
+    });
+    return { ok: true, run: result.run, agent: result.agent, created: result.created };
+  } catch (error) {
+    return {
+      ok: false,
+      error: "spawn-role-failed",
+      message: describeError(error),
+    };
+  }
+}
+
+async function stopTeamRoleWithBrokerContext(
+  options: TeamMessageBrokerOptions,
+  input: TeamMessageBrokerStopInput,
+): Promise<TeamRoleStopResult> {
+  const store = createTeamRunStore(options.homeDir);
+  const runId = await resolveRequestedRunId(store, input.runId);
+  const run = await store.readRun(runId);
+
+  return stopTeamRole({
+    homeDir: options.homeDir,
+    runId: run.runId,
+    roleId: input.roleId,
+    now: input.now,
+    runtimeAdapter: options.runtimeAdapter,
+  });
+}
+
+async function notifyMainAboutStoppedAgents(input: {
+  homeDir?: string;
+  run: TeamRunRecord;
+  agents: TeamAgentRecord[];
+  stoppedAgents: TeamAgentRecord[];
+  livePaneIds: Set<string>;
+  runtimeAdapter: TeamRuntimeAdapter;
+}): Promise<TeamMessageSendResult[]> {
+  const main = input.agents.find((agent) => agent.roleId === "main");
+  if (
+    main === undefined ||
+    !isActiveTeamAgentStatus(main.status) ||
+    !input.livePaneIds.has(main.tmux.paneId)
+  ) {
+    return [];
+  }
+
+  const broker = new TeamMessageBroker({
+    homeDir: input.homeDir,
+    runtimeAdapter: input.runtimeAdapter,
+  });
+  const notifications: TeamMessageSendResult[] = [];
+  for (const agent of input.stoppedAgents) {
+    if (agent.roleId === "main") continue;
+    notifications.push(
+      await broker.send({
+        runId: input.run.runId,
+        fromRoleId: "evodev",
+        toRoleId: "main",
+        type: "notice",
+        message: `Role ${agent.roleId} pane ${agent.tmux.paneId} closed; marked stopped.`,
+      }),
+    );
+  }
+  return notifications;
+}
+
+async function notifyMainAboutRecovery(input: {
+  homeDir?: string;
+  run: TeamRunRecord;
+  outcomes: TeamAgentRecoveryResult[];
+  agents: TeamAgentRecord[];
+  runtimeAdapter: TeamRuntimeAdapter;
+}): Promise<TeamMessageSendResult[]> {
+  const changedOutcomes = input.outcomes.filter((outcome) => outcome.outcome !== "reused");
+  if (changedOutcomes.length === 0) return [];
+  const main = input.agents.find((agent) => agent.roleId === "main");
+  if (main === undefined || !isActiveTeamAgentStatus(main.status)) return [];
+
+  const lines = changedOutcomes.map((outcome) => {
+    const target =
+      outcome.paneId === null ? "no pane" : `pane ${outcome.previousPaneId} -> ${outcome.paneId}`;
+    return `- ${outcome.roleId}: ${outcome.outcome} (${target})`;
+  });
+  const broker = new TeamMessageBroker({
+    homeDir: input.homeDir,
+    runtimeAdapter: input.runtimeAdapter,
+  });
+  const result = await broker.send({
+    runId: input.run.runId,
+    fromRoleId: "evodev",
+    toRoleId: "main",
+    type: "notice",
+    message: ["EvoDev recovery summary:", ...lines].join("\n"),
+  });
+  return [result];
+}
+
+export async function stopTeamRun(input: StopTeamRunInput): Promise<TeamStatusResult> {
+  const store = createTeamRunStore(input.homeDir);
+  const runId = await resolveRequestedRunId(store, input.runId);
+  const run = await store.readRun(runId);
+  const now = (input.now ?? new Date()).toISOString();
+  const runtimeAdapter = input.runtimeAdapter ?? createTmuxRuntimeAdapter();
+  await runtimeAdapter.stopRun({ session: run.tmux.session });
+  const agents = await store.readAgents(run.runId);
+  const stoppedAgents = agents.map((agent) => ({
+    ...agent,
+    status: "stopped" as const,
+    updatedAt: now,
+  }));
+  const stoppedRun: TeamRunRecord = { ...run, status: "stopped", updatedAt: now };
+  await store.writeRun(stoppedRun);
+  for (const agent of stoppedAgents) {
+    await store.writeAgent(agent);
+  }
+  await store.appendEvent(
+    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 };
+}
+
+export async function getTeamStatus(input: TeamStatusInput = {}): Promise<TeamStatusResult> {
+  const store = createTeamRunStore(input.homeDir);
+  const runId = input.runId ?? (await store.readLatestRunId());
+  if (runId === null) return { run: null, agents: [] };
+  const run = await store.readRun(runId);
+  return { run, agents: await store.readAgents(runId) };
+}
+
+export async function listTeamRuns(input: ListTeamRunsInput = {}): Promise<TeamRunRecord[]> {
+  const store = createTeamRunStore(input.homeDir);
+  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) {
+    if (entry === "latest.json") continue;
+    try {
+      runs.push(await store.readRun(entry));
+    } catch {}
+  }
+  return runs.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+}
+
+export async function reconcileTeamRun(
+  input: ReconcileTeamRunInput = {},
+): Promise<TeamRunReconcileResult> {
+  const store = createTeamRunStore(input.homeDir);
+  const runId = input.runId ?? (await store.readLatestRunId());
+  if (runId === null) {
+    return { run: null, agents: [], stoppedAgents: [], notifications: [], runtimeAvailable: true };
+  }
+
+  const run = await store.readRun(runId);
+  const agents = await store.readAgents(run.runId);
+  if (run.status !== "running") {
+    return { run, agents, stoppedAgents: [], notifications: [], runtimeAvailable: true };
+  }
+
+  const runtimeAdapter = input.runtimeAdapter ?? createTmuxRuntimeAdapter();
+  let livePaneIds: Set<string>;
+  try {
+    livePaneIds = new Set(
+      (await runtimeAdapter.listPanes({ session: run.tmux.session })).map((pane) => pane.paneId),
+    );
+  } catch {
+    livePaneIds = new Set();
+  }
+
+  const now = (input.now ?? new Date()).toISOString();
+  const stoppedAgents = agents
+    .filter((agent) => isActiveTeamAgentStatus(agent.status) && !livePaneIds.has(agent.tmux.paneId))
+    .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 };
+  }
+
+  const stoppedRoleIds = new Set(stoppedAgents.map((agent) => agent.roleId));
+  const updatedAgents = agents.map(
+    (agent) => stoppedAgents.find((stopped) => stopped.roleId === agent.roleId) ?? agent,
+  );
+  const updatedRun: TeamRunRecord = {
+    ...run,
+    status: stoppedRoleIds.has("main") ? "stopped" : run.status,
+    updatedAt: now,
+  };
+
+  await store.writeRun(updatedRun);
+  for (const agent of stoppedAgents) {
+    await store.writeAgent(agent);
+    await store.appendEvent(
+      run.runId,
+      createTeamEvent(run.runId, "AgentStopped", `Detected closed pane for ${agent.roleId}.`, now, {
+        roleId: agent.roleId,
+        agentId: agent.agentId,
+      }),
+    );
+  }
+
+  const notifications =
+    input.notifyMain === false
+      ? []
+      : await notifyMainAboutStoppedAgents({
+          homeDir: input.homeDir,
+          run: updatedRun,
+          agents: updatedAgents,
+          stoppedAgents,
+          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: finalRun,
+    agents: finalAgents,
+    stoppedAgents,
+    notifications,
+    runtimeAvailable: livePaneIds.size > 0,
+  };
+}
+
+export async function recordTeamAgentNativeSession(
+  input: RecordTeamAgentNativeSessionInput,
+): Promise<TeamAgentRecord> {
+  const store = createTeamRunStore(input.homeDir);
+  const runId = await resolveRequestedRunId(store, input.runId);
+  const agent = await store.readAgent(runId, input.roleId);
+  if (agent.nativeSession.sessionId === input.sessionId) return agent;
+  const now = (input.now ?? new Date()).toISOString();
+  const updatedAgent: TeamAgentRecord = {
+    ...agent,
+    nativeSession: {
+      sessionId: input.sessionId,
+      capturedAt: now,
+    },
+    updatedAt: now,
+  };
+
+  await store.writeAgent(updatedAgent);
+  await store.appendEvent(
+    runId,
+    createTeamEvent(
+      runId,
+      "AgentNativeSessionRecorded",
+      `Recorded native session id for ${input.roleId}.`,
+      now,
+      {
+        roleId: input.roleId,
+        agentId: agent.agentId,
+      },
+    ),
+  );
+  await writeTeamStatusSnapshot({
+    store,
+    runId,
+    now,
+    lastEvent: "AgentNativeSessionRecorded",
+  });
+
+  return updatedAgent;
+}
+
+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 agent = await store.readAgent(runId, input.roleId);
+  const now = (input.now ?? new Date()).toISOString();
+  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)) {
+      updatedAgents.push(agent);
+      outcomes.push({
+        roleId: agent.roleId,
+        agentId: agent.agentId,
+        outcome: "reused",
+        previousPaneId: agent.tmux.paneId,
+        paneId: agent.tmux.paneId,
+        nativeSessionId: agent.nativeSession.sessionId,
+      });
+      continue;
+    }
+
+    const role = await resolveRoleForAgentRecovery({
+      homeDir: input.homeDir,
+      repoRoot: run.repoRoot,
+      agent,
+    });
+    const roster = [
+      ...updatedAgents,
+      ...originalAgents.filter((item) => item.roleId !== agent.roleId),
+    ];
+    const startupPrompt = await createAgentStartupPrompt({
+      homeDir: input.homeDir,
+      runId: run.runId,
+      repoRoot: run.repoRoot,
+      role,
+      roster,
+      now,
+    });
+    const recoveryMode = resolveRecoveryMode(agent, decision);
+
+    if (recoveryMode === null) {
+      const stoppedAgent = { ...agent, status: "stopped" as const, updatedAt: now };
+      await store.writeAgent(stoppedAgent);
+      await store.appendEvent(
+        run.runId,
+        createTeamEvent(
+          run.runId,
+          "AgentRecoveryDecisionRequired",
+          `Recovery for ${agent.roleId} requires a session decision.`,
+          now,
+          { roleId: agent.roleId, agentId: agent.agentId },
+        ),
+      );
+      updatedAgents.push(stoppedAgent);
+      outcomes.push({
+        roleId: agent.roleId,
+        agentId: agent.agentId,
+        outcome: decision === "fail" ? "failed" : "needs-decision",
+        previousPaneId: agent.tmux.paneId,
+        paneId: null,
+        nativeSessionId: agent.nativeSession.sessionId,
+        reason:
+          decision === "fail"
+            ? "Native session id is missing and fallback is disabled."
+            : "Native session id is missing. Choose fail, recreate, or resume-latest.",
+        decisionOptions: ["fail", "recreate", "resume-latest"],
+      });
+      continue;
+    }
+
+    try {
+      const handle = await runtimeAdapter.recoverAgent({
+        runId: run.runId,
+        sessionName: run.tmux.session,
+        repoRoot: run.repoRoot,
+        role,
+        startupPrompt,
+        mode: recoveryMode,
+        targetPaneId: updatedAgents.find((item) => item.roleId === "main")?.tmux.paneId,
+      });
+      const recoveredAgent = createRecoveredAgentRecord({
+        existing: agent,
+        role,
+        handle,
+        mode: recoveryMode,
+        now,
+      });
+      updatedRun = {
+        ...updatedRun,
+        roles: { ...updatedRun.roles, [agent.roleId]: recoveredAgent.agentId },
+        updatedAt: now,
+      };
+      await store.writeAgent(recoveredAgent);
+      await store.appendEvent(
+        run.runId,
+        createTeamEvent(
+          run.runId,
+          recoveredAgent.status === "recreated" ? "AgentRecreated" : "AgentRecovered",
+          `${recoveredAgent.status === "recreated" ? "Recreated" : "Recovered"} role ${agent.roleId}.`,
+          now,
+          { roleId: agent.roleId, agentId: recoveredAgent.agentId },
+        ),
+      );
+      updatedAgents.push(recoveredAgent);
+      outcomes.push({
+        roleId: recoveredAgent.roleId,
+        agentId: recoveredAgent.agentId,
+        outcome: recoveredAgent.status === "recreated" ? "recreated" : "resumed",
+        previousPaneId: agent.tmux.paneId,
+        paneId: recoveredAgent.tmux.paneId,
+        nativeSessionId: recoveredAgent.nativeSession.sessionId,
+      });
+    } catch (error) {
+      const stoppedAgent = { ...agent, status: "stopped" as const, updatedAt: now };
+      await store.writeAgent(stoppedAgent);
+      await store.appendEvent(
+        run.runId,
+        createTeamEvent(
+          run.runId,
+          "AgentRecoveryDecisionRequired",
+          `Recovery for ${agent.roleId} failed: ${describeError(error)}`,
+          now,
+          { roleId: agent.roleId, agentId: agent.agentId },
+        ),
+      );
+      updatedAgents.push(stoppedAgent);
+      outcomes.push({
+        roleId: agent.roleId,
+        agentId: agent.agentId,
+        outcome: "needs-decision",
+        previousPaneId: agent.tmux.paneId,
+        paneId: null,
+        nativeSessionId: agent.nativeSession.sessionId,
+        reason: describeError(error),
+        decisionOptions: ["fail", "recreate", "resume-latest"],
+      });
+    }
+  }
+
+  const main = updatedAgents.find((agent) => agent.roleId === "main");
+  updatedRun = {
+    ...updatedRun,
+    status: main !== undefined && isActiveTeamAgentStatus(main.status) ? "running" : "stopped",
+    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 =
+    input.notifyMain === false
+      ? []
+      : await notifyMainAboutRecovery({
+          homeDir: input.homeDir,
+          run: updatedRun,
+          outcomes,
+          agents: updatedAgents,
+          runtimeAdapter,
+        });
+
+  return {
+    run: updatedRun,
+    agents: updatedAgents.sort((left, right) => left.roleId.localeCompare(right.roleId)),
+    outcomes,
+    decisionRequired,
+    notifications,
+  };
+}
+
+export async function getTeamAttachCommand(input: TeamAttachInput = {}): Promise<string> {
+  const store = createTeamRunStore(input.homeDir);
+  const runId = await resolveRequestedRunId(store, input.runId);
+  const run = await store.readRun(runId);
+  const roleId = input.roleId ?? "main";
+  const agent = await store.readAgent(run.runId, roleId);
+  const runtimeAdapter = input.runtimeAdapter ?? createTmuxRuntimeAdapter();
+  return runtimeAdapter.formatAttachCommand({
+    session: run.tmux.session,
+    paneId: agent.tmux.paneId,
+  });
+}
+
+export async function listTeamAgents(input: TeamStatusInput = {}): Promise<TeamAgentSummary[]> {
+  const status = await getTeamStatus(input);
+  return status.agents.map((agent) => ({
+    roleId: agent.roleId,
+    roleName: agent.roleName,
+    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;
+  roleId: string;
+  overrides?: Partial<{
+    runtime: TeamAgentRuntime;
+    model: string | null;
+    thinkingLevel: string | null;
+  }>;
+}): 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`,
+  );
+  const candidate = await readRoleCandidate(globalRolePath, "global");
+  const nativeAgent = await resolveTeamRoleNativeAgentBinding({
+    homeDir: input.homeDir,
+    repoRoot: input.repoRoot,
+    roleId: input.roleId,
+  });
+  const raw =
+    candidate?.value ?? createBuiltInRole(input.roleId, settings.teamRuntime.defaultRuntime);
+  const source = candidate?.source ?? "builtin";
+  const sourcePath = candidate?.path ?? null;
+  const parsed = parseTeamRoleDefinition(raw, {
+    roleId: input.roleId,
+    source,
+    defaultRuntime: settings.teamRuntime.defaultRuntime,
+    defaultModel: settings.teamRuntime.defaultModel,
+    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,
+  };
+}
+
+export function parseTeamRoleDefinition(
+  value: unknown,
+  defaults: {
+    roleId: string;
+    source: TeamRoleDefinition["source"];
+    defaultRuntime: TeamAgentRuntime;
+    defaultModel: string | null;
+    defaultThinkingLevel: string | null;
+    recordTranscript: boolean;
+  },
+): TeamRoleDefinition {
+  const input = isRecord(value) ? value : {};
+  const roleId = optionalString(input.roleId) ?? defaults.roleId;
+  assertSafeId(roleId, "roleId");
+  const runtime = parseRuntime(input.runtime, defaults.defaultRuntime);
+  const isMain = roleId === "main";
+  return {
+    version: 1,
+    roleId,
+    roleName:
+      optionalString(input.roleName) ?? optionalString(input.name) ?? defaultRoleName(roleId),
+    description: optionalString(input.description) ?? `EvoDev ${roleId} role agent.`,
+    runtime,
+    model: optionalNullableString(input.model) ?? defaults.defaultModel,
+    thinkingLevel: optionalNullableString(input.thinkingLevel) ?? defaults.defaultThinkingLevel,
+    prompt: optionalString(input.prompt) ?? defaultRolePrompt(roleId),
+    permissions: parseRolePermissions(input.permissions, isMain),
+    teamPolicy: parseRolePolicy(input.teamPolicy, defaults.recordTranscript),
+    source: defaults.source,
+  };
+}
+
+export function createTmuxRuntimeAdapter(
+  runner: TeamRuntimeCommandRunner = new NodeTeamRuntimeCommandRunner(),
+  options: TmuxRuntimeAdapterOptions = {},
+): TeamRuntimeAdapter {
+  return new TmuxRuntimeAdapter(runner, options);
+}
+
+export class TmuxRuntimeAdapter implements TeamRuntimeAdapter {
+  private messageBufferCounter = 0;
+
+  constructor(
+    private readonly runner: TeamRuntimeCommandRunner,
+    private readonly options: TmuxRuntimeAdapterOptions = {},
+  ) {}
+
+  async createRun(input: TeamRuntimeCreateRunInput): Promise<TeamRuntimeAgentHandle> {
+    const command = buildAgentShellCommand(input.role, input.startupPrompt, {
+      runId: input.runId,
+      repoRoot: input.repoRoot,
+      runtimeCommands: this.options.runtimeCommands,
+      environment: this.options.environment,
+    });
+    await this.runTmux([
+      "new-session",
+      "-d",
+      "-s",
+      input.sessionName,
+      "-n",
+      "main",
+      "-c",
+      input.repoRoot,
+      command,
+    ]);
+    const pane = await this.runTmux([
+      "display-message",
+      "-p",
+      "-t",
+      `${input.sessionName}:main.0`,
+      "#{pane_id}",
+    ]);
+    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> {
+    const window = sanitizeWindowName(input.role.roleId);
+    const command = buildAgentShellCommand(input.role, input.startupPrompt, {
+      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, input.role);
+      return { session: input.sessionName, window: "main", paneId: pane };
+    }
+
+    const pane = await this.runTmux([
+      "new-window",
+      "-d",
+      "-P",
+      "-F",
+      "#{pane_id}",
+      "-t",
+      input.sessionName,
+      "-n",
+      window,
+      "-c",
+      input.repoRoot,
+      command,
+    ]);
+    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> {
+    const window = sanitizeWindowName(input.role.roleId);
+    const command =
+      input.mode.type === "fresh"
+        ? buildAgentShellCommand(input.role, input.startupPrompt, {
+            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", ["-u", "has-session", "-t", input.sessionName]);
+    if (session.exitCode !== 0) {
+      await this.runTmux([
+        "new-session",
+        "-d",
+        "-s",
+        input.sessionName,
+        "-n",
+        window,
+        "-c",
+        input.repoRoot,
+        command,
+      ]);
+      const pane = await this.runTmux([
+        "display-message",
+        "-p",
+        "-t",
+        `${input.sessionName}:${window}.0`,
+        "#{pane_id}",
+      ]);
+      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, input.role);
+      return recoveredHandle(input, "main", pane);
+    }
+
+    const pane = await this.runTmux([
+      "new-window",
+      "-d",
+      "-P",
+      "-F",
+      "#{pane_id}",
+      "-t",
+      input.sessionName,
+      "-n",
+      window,
+      "-c",
+      input.repoRoot,
+      command,
+    ]);
+    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",
+      "-h",
+      "-d",
+      "-P",
+      "-F",
+      "#{pane_id}",
+      "-t",
+      targetPaneId,
+      "-c",
+      repoRoot,
+      command,
+    ]);
+    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> {
+    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", "-s", "-t", input.session, "-F", "#{pane_id}"]);
+    return panes.stdout
+      .split("\n")
+      .map((paneId) => paneId.trim())
+      .filter(Boolean)
+      .map((paneId) => ({ paneId }));
+  }
+
+  async stopAgent(input: TeamRuntimeStopAgentInput): Promise<void> {
+    await this.runTmux(["kill-pane", "-t", input.paneId]);
+  }
+
+  async stopRun(input: TeamRuntimeStopRunInput): Promise<void> {
+    await this.runTmux(["kill-session", "-t", input.session]);
+  }
+
+  formatAttachCommand(input: TeamRuntimeAttachInput): string {
+    return input.paneId === undefined
+      ? `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", ["-u", ...args], options);
+    if (result.exitCode !== 0) {
+      throw new Error(`tmux ${args.join(" ")} failed: ${result.stderr || result.stdout}`);
+    }
+    return result;
+  }
+}
+
+export class NodeTeamRuntimeCommandRunner implements TeamRuntimeCommandRunner {
+  async run(
+    command: string,
+    args: string[],
+    options: { input?: string } = {},
+  ): Promise<TeamRuntimeCommandResult> {
+    return new Promise((resolve, reject) => {
+      const child = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"] });
+      let stdout = "";
+      let stderr = "";
+      child.stdout.setEncoding("utf8");
+      child.stderr.setEncoding("utf8");
+      child.stdout.on("data", (chunk: string) => {
+        stdout += chunk;
+      });
+      child.stderr.on("data", (chunk: string) => {
+        stderr += chunk;
+      });
+      child.once("error", reject);
+      child.once("close", (code) => {
+        resolve({ exitCode: code ?? 1, stdout, stderr });
+      });
+      child.stdin.end(options.input ?? "");
+    });
+  }
+}
+
+function createAgentRecord(input: {
+  runId: string;
+  role: ResolvedTeamRole;
+  handle: TeamRuntimeAgentHandle;
+  now: string;
+}): TeamAgentRecord {
+  const tmux = teamTmuxFromHandle(input.handle);
+  return {
+    version: 1,
+    agentId: createAgentId(input.role.roleId, input.now),
+    roleId: input.role.roleId,
+    roleName: input.role.roleName,
+    runId: input.runId,
+    runtime: input.role.runtime,
+    model: input.role.model,
+    thinkingLevel: input.role.thinkingLevel,
+    status: "running",
+    permissions: input.role.permissions,
+    nativeSession: {
+      sessionId: input.handle.nativeSessionId ?? null,
+      capturedAt:
+        input.handle.nativeSessionId === undefined || input.handle.nativeSessionId === null
+          ? null
+          : input.now,
+    },
+    tmux,
+    createdAt: input.now,
+    updatedAt: input.now,
+  };
+}
+
+function createRecoveredAgentRecord(input: {
+  existing: TeamAgentRecord;
+  role: ResolvedTeamRole;
+  handle: TeamRuntimeAgentHandle;
+  mode: TeamRuntimeAgentRecoveryMode;
+  now: string;
+}): TeamAgentRecord {
+  if (input.mode.type === "fresh") {
+    return {
+      ...createAgentRecord({
+        runId: input.existing.runId,
+        role: input.role,
+        handle: input.handle,
+        now: input.now,
+      }),
+      status: "recreated",
+    };
+  }
+
+  const nativeSessionId =
+    input.handle.nativeSessionId ??
+    (input.mode.type === "resume" ? input.mode.sessionId : input.existing.nativeSession.sessionId);
+
+  return {
+    ...input.existing,
+    roleName: input.role.roleName,
+    runtime: input.role.runtime,
+    model: input.role.model,
+    thinkingLevel: input.role.thinkingLevel,
+    permissions: input.role.permissions,
+    status: "recovering",
+    nativeSession: {
+      sessionId: nativeSessionId,
+      capturedAt:
+        nativeSessionId === null
+          ? null
+          : input.handle.nativeSessionId === undefined
+            ? input.existing.nativeSession.capturedAt
+            : input.now,
+    },
+    tmux: teamTmuxFromHandle(input.handle),
+    updatedAt: input.now,
+  };
+}
+
+function teamTmuxFromHandle(handle: TeamRuntimeAgentHandle): TeamAgentRecord["tmux"] {
+  return {
+    session: handle.session,
+    window: handle.window,
+    paneId: handle.paneId,
+  };
+}
+
+function resolveRecoveryMode(
+  agent: TeamAgentRecord,
+  decision: TeamSessionMissingDecision,
+): TeamRuntimeAgentRecoveryMode | null {
+  if (agent.nativeSession.sessionId !== null) {
+    return { type: "resume", sessionId: agent.nativeSession.sessionId };
+  }
+  if (decision === "recreate") return { type: "fresh" };
+  if (decision === "resume-latest") return { type: "resume-latest" };
+  return null;
+}
+
+async function readLivePaneIds(
+  runtimeAdapter: TeamRuntimeAdapter,
+  session: string,
+): Promise<Set<string>> {
+  try {
+    return new Set((await runtimeAdapter.listPanes({ session })).map((pane) => pane.paneId));
+  } catch {
+    return new Set();
+  }
+}
+
+function sortAgentsForRecovery(agents: TeamAgentRecord[]): TeamAgentRecord[] {
+  return [...agents].sort((left, right) => {
+    if (left.roleId === "main") return -1;
+    if (right.roleId === "main") return 1;
+    return left.roleId.localeCompare(right.roleId);
+  });
+}
+
+async function resolveRoleForAgentRecovery(input: {
+  homeDir?: string;
+  repoRoot: string;
+  agent: TeamAgentRecord;
+}): Promise<ResolvedTeamRole> {
+  const resolved = await resolveTeamRole({
+    homeDir: input.homeDir,
+    repoRoot: input.repoRoot,
+    roleId: input.agent.roleId,
+  });
+  return {
+    ...resolved,
+    roleName: input.agent.roleName,
+    runtime: input.agent.runtime,
+    model: input.agent.model,
+    thinkingLevel: input.agent.thinkingLevel,
+    permissions: input.agent.permissions,
+  };
+}
+
+function createAgentStartupPrompt(input: {
+  homeDir?: string;
+  runId: string;
+  repoRoot: string;
+  role: ResolvedTeamRole;
+  roster: TeamAgentRecord[];
+  now?: string;
+}): Promise<string> {
+  return createScopedTeamStartupContext(input).then((scopedContext) =>
+    renderTeamRoleStartupPrompt({ ...input, scopedContext }),
+  );
+}
+
+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(
+  role: ResolvedTeamRole,
+  startupPrompt: string,
+  context: {
+    runId: string;
+    repoRoot: string;
+    runtimeCommands?: TmuxRuntimeAdapterOptions["runtimeCommands"];
+    environment?: TmuxRuntimeAdapterOptions["environment"];
+  },
+): string {
+  const args =
+    role.runtime === "codex"
+      ? buildCodexArgs(role, startupPrompt)
+      : buildClaudeArgs(role, startupPrompt);
+  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);
+}
+
+function buildAgentResumeShellCommand(
+  role: ResolvedTeamRole,
+  startupPrompt: string,
+  context: {
+    runId: string;
+    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 = 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[],
+  env: Record<string, string>,
+): string {
+  const envEntries = Object.entries(env).map(([key, value]) => `${key}=${shellQuote(value)}`);
+  const commandParts = [runtimeCommand, ...args].map(shellQuote);
+  return [...envEntries, ...commandParts].join(" ");
+}
+
+function resolveRuntimeCommand(
+  runtime: TeamAgentRuntime,
+  runtimeCommands: TmuxRuntimeAdapterOptions["runtimeCommands"],
+): string {
+  return runtimeCommands?.[runtime] ?? runtime;
+}
+
+function buildCodexArgs(role: ResolvedTeamRole, startupPrompt: string): string[] {
+  const args = ["--no-alt-screen"];
+  if (role.model !== null) args.push("--model", role.model);
+  if (shouldPassVisibleStartupPrompt(role)) args.push(startupPrompt);
+  return args;
+}
+
+function buildCodexResumeArgs(
+  role: ResolvedTeamRole,
+  startupPrompt: string,
+  mode: Exclude<TeamRuntimeAgentRecoveryMode, { type: "fresh" }>,
+): string[] {
+  const args = ["--no-alt-screen"];
+  if (role.model !== null) args.push("--model", role.model);
+  args.push("resume");
+  if (mode.type === "resume") {
+    args.push(mode.sessionId);
+  } else {
+    args.push("--last");
+  }
+  if (shouldPassVisibleStartupPrompt(role)) args.push(startupPrompt);
+  return args;
+}
+
+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);
+  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" }>,
+): string[] {
+  const args = [];
+  if (role.model !== null) args.push("--model", role.model);
+  if (role.thinkingLevel !== null) args.push("--effort", role.thinkingLevel);
+  if (mode.type === "resume") {
+    args.push("--resume", mode.sessionId);
+  } else {
+    args.push("--continue");
+  }
+  return args;
+}
+
+function recoveredHandle(
+  input: TeamRuntimeRecoverAgentInput,
+  window: string,
+  paneId: string,
+): TeamRuntimeAgentHandle {
+  return {
+    session: input.sessionName,
+    window,
+    paneId,
+    nativeSessionId: input.mode.type === "resume" ? input.mode.sessionId : null,
+  };
+}
+
+async function readSettingsOrDefault(homeDir?: string) {
+  const settingsPath = resolveEvoDevPaths(homeDir).settingsPath;
+  try {
+    return parseSettings(JSON.parse(await readFile(settingsPath, "utf8")));
+  } catch {
+    return createDefaultSettings();
+  }
+}
+
+async function resolveRequestedRunId(
+  store: TeamRunStore,
+  requestedRunId?: string,
+): Promise<string> {
+  if (requestedRunId !== undefined) return requestedRunId;
+  const latest = await store.readLatestRunId();
+  if (latest === null) throw new Error("No EvoDev team run exists.");
+  return latest;
+}
+
+function createBuiltInRole(roleId: string, runtime: TeamAgentRuntime): unknown {
+  const builtin = BUILT_IN_ROLE_PROMPTS[roleId];
+  return {
+    version: 1,
+    roleId,
+    roleName: builtin?.roleName ?? defaultRoleName(roleId),
+    description: builtin?.description ?? `EvoDev ${roleId} role agent.`,
+    runtime,
+    prompt: builtin?.prompt ?? defaultRolePrompt(roleId),
+  };
+}
+
+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, "repo-write"),
+    canUseTeamsMcp: optionalBoolean(input.canUseTeamsMcp) ?? true,
+    canSpawnAgents: optionalBoolean(input.canSpawnAgents) ?? main,
+    canStopAgents: optionalBoolean(input.canStopAgents) ?? main,
+  };
+}
+
+function parseRolePolicy(value: unknown, recordTranscript: boolean): TeamRolePolicy {
+  const input = isRecord(value) ? value : {};
+  return {
+    roleInstancePolicy: "single-per-role",
+    recordTranscript: optionalBoolean(input.recordTranscript) ?? recordTranscript,
+  };
+}
+
+function parseTeamRunRecord(value: unknown): TeamRunRecord {
+  if (!isRecord(value) || value.version !== 1) throw new Error("Invalid team run record.");
+  const run = value as unknown as TeamRunRecord;
+  assertSafeId(run.runId, "runId");
+  assertString(run.repoRoot, "run.repoRoot");
+  if (!["running", "stopped", "failed"].includes(run.status))
+    throw new Error("Invalid run status.");
+  return run;
+}
+
+function parseTeamAgentRecord(value: unknown): TeamAgentRecord {
+  if (!isRecord(value) || value.version !== 1) throw new Error("Invalid team agent record.");
+  const agent = value as unknown as TeamAgentRecord;
+  assertSafeId(agent.agentId, "agentId");
+  assertSafeId(agent.roleId, "roleId");
+  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 : {};
+  return {
+    ...agent,
+    nativeSession: {
+      sessionId: optionalString(nativeSessionValue.sessionId) ?? null,
+      capturedAt: optionalString(nativeSessionValue.capturedAt) ?? null,
+    },
+  };
+}
+
+function parseTeamMessageRecord(value: unknown): TeamMessageRecord {
+  if (!isRecord(value) || value.version !== 1) throw new Error("Invalid team message record.");
+  const message = value as unknown as TeamMessageRecord;
+  assertSafeId(message.messageId, "messageId");
+  assertSafeId(message.runId, "runId");
+  assertSafeId(message.toRoleId, "toRoleId");
+  assertString(message.body, "message.body");
+  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;
+  assertSafeId(event.eventId, "eventId");
+  assertSafeId(event.runId, "runId");
+  assertString(event.summary, "event.summary");
+  return event;
+}
+
+function parseRuntime(value: unknown, fallback: TeamAgentRuntime): TeamAgentRuntime {
+  if (value === undefined || value === null) return fallback;
+  if (value === "codex" || value === "claude") return value;
+  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))) {
+    return value as TeamWriteMode;
+  }
+  throw new Error("Role writeMode is invalid.");
+}
+
+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 {
+  return `run-${safeSlug(basename(repoRoot) || "repo")}-${timestampId(now)}`;
+}
+
+function createAgentId(roleId: string, now: string): string {
+  return `agent-${roleId}-${timestampId(new Date(now))}`;
+}
+
+function createMessageId(now: string): string {
+  return `msg-${timestampId(new Date(now))}`;
+}
+
+function createEventId(now: string): string {
+  return `evt-${timestampId(new Date(now))}`;
+}
+
+function createTmuxSessionName(repoRoot: string, runId: string): string {
+  return `evodev-${safeSlug(basename(repoRoot) || "repo")}-${runId}`.slice(0, 80);
+}
+
+function createTeamEvent(
+  runId: string,
+  type: TeamEventRecord["type"],
+  summary: string,
+  now: string,
+  refs: Partial<Pick<TeamEventRecord, "roleId" | "agentId" | "messageId">> = {},
+): TeamEventRecord {
+  return { version: 1, eventId: createEventId(now), runId, type, summary, createdAt: now, ...refs };
+}
+
+function timestampId(date: Date): string {
+  return date
+    .toISOString()
+    .replace(/[-:.TZ]/g, "")
+    .slice(0, 17);
+}
+
+function safeSlug(value: string): string {
+  const slug = value.replace(/[^A-Za-z0-9._-]/g, "-").replace(/^-+|-+$/g, "");
+  return slug || "repo";
+}
+
+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(/[-_.]/)
+    .filter(Boolean)
+    .map((part) => part.slice(0, 1).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+function defaultRolePrompt(roleId: string): string {
+  return `You are the ${roleId} role agent for this EvoDev team run. Stay inside your role and communicate through Teams MCP.`;
+}
+
+async function readRoleCandidate(
+  path: string,
+  source: TeamRoleDefinition["source"],
+): Promise<{ value: unknown; path: string; source: TeamRoleDefinition["source"] } | null> {
+  try {
+    const raw = await readFile(path, "utf8");
+    return { value: JSON.parse(raw), path, source };
+  } catch (error) {
+    if (isNotFoundError(error)) return null;
+    throw new Error(`Cannot read team role definition ${path}: ${describeError(error)}`);
+  }
+}
+
+async function resolveTeamRoleNativeAgentBinding(input: {
+  homeDir?: string;
+  repoRoot: string;
+  roleId: string;
+}): Promise<TeamNativeAgentBinding | null> {
+  const bindings = await listTeamRoleBindings({
+    homeDir: input.homeDir,
+    repoRoot: input.repoRoot,
+  });
+  return bindings.find((binding) => binding.roleId === input.roleId) ?? null;
+}
+
+function resolveGlobalTeamBindingPath(homeDir?: string): string {
+  return join(resolveEvoDevPaths(homeDir).rootDir, "team", "roles.json");
+}
+
+function resolveProjectTeamBindingPath(homeDir: string | undefined, projectKey: string): string {
+  return join(resolveEvoDevPaths(homeDir).rootDir, "projects", safeSlug(projectKey), "team.json");
+}
+
+function resolveTeamBindingWritePath(input: {
+  homeDir?: string;
+  repoRoot?: string;
+  scope: "global" | "project";
+}): { path: string; projectKey: string | null } {
+  if (input.scope === "global") {
+    return { path: resolveGlobalTeamBindingPath(input.homeDir), projectKey: null };
+  }
+  if (input.repoRoot === undefined) {
+    throw new Error("Project-scoped team config requires repoRoot.");
+  }
+  const projectKey = resolveProjectLogKey(
+    resolveEvoDevPaths(input.homeDir).homeDir,
+    input.repoRoot,
+  );
+  return {
+    path: resolveProjectTeamBindingPath(input.homeDir, projectKey),
+    projectKey,
+  };
+}
+
+async function readTeamBindingConfig(path: string): Promise<TeamRoleBindingConfig> {
+  try {
+    const raw = await readFile(path, "utf8");
+    return parseTeamBindingConfig(JSON.parse(raw));
+  } catch (error) {
+    if (isNotFoundError(error)) {
+      return { version: 1, updatedAt: "never", roles: [] };
+    }
+    throw error;
+  }
+}
+
+function parseTeamBindingConfig(value: unknown): TeamRoleBindingConfig {
+  if (!isRecord(value) || value.version !== 1) throw new Error("Invalid team binding config.");
+  const updatedAt = optionalString(value.updatedAt) ?? "unknown";
+  const rolesValue = Array.isArray(value.roles) ? value.roles : [];
+  return {
+    version: 1,
+    updatedAt,
+    roles: rolesValue.map(parseTeamBindingRecord),
+  };
+}
+
+function parseTeamBindingRecord(value: unknown): TeamRoleBindingRecord {
+  if (!isRecord(value) || value.version !== 1) {
+    throw new Error("Invalid team binding record.");
+  }
+  const roleId = optionalString(value.roleId);
+  const target = parseRuntime(value.target, "codex");
+  const agentName = optionalString(value.agentName);
+  const updatedAt = optionalString(value.updatedAt) ?? "unknown";
+  if (roleId === undefined) throw new Error("Team binding roleId is required.");
+  if (agentName === undefined) throw new Error("Team binding agentName is required.");
+  assertSafeId(roleId, "roleId");
+  assertSafeId(agentName, "agentName");
+  return { version: 1, roleId, target, agentName, updatedAt };
+}
+
+function bindingRecordToNative(
+  record: TeamRoleBindingRecord,
+  scope: "global" | "project",
+  projectKey: string | null,
+): TeamNativeAgentBinding {
+  return {
+    roleId: record.roleId,
+    target: record.target,
+    agentName: record.agentName,
+    scope,
+    projectKey,
+    updatedAt: record.updatedAt,
+  };
+}
+
+function mergeTeamRoleBindings(
+  global: TeamNativeAgentBinding[],
+  project: TeamNativeAgentBinding[],
+): TeamNativeAgentBinding[] {
+  const byRole = new Map(global.map((binding) => [binding.roleId, binding]));
+  for (const binding of project) byRole.set(binding.roleId, binding);
+  return [...byRole.values()].sort((left, right) => left.roleId.localeCompare(right.roleId));
+}
+
+function isNotFoundError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code?: unknown }).code === "ENOENT"
+  );
+}
+
+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");
+}
+
+async function appendJsonLine(path: string, value: unknown): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  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, `'\\''`)}'`;
+}
+
+function assertSafeId(value: string, path: string): void {
+  if (!SAFE_ROLE_ID_PATTERN.test(value)) throw new Error(`Invalid ${path}; unsafe id.`);
+}
+
+function assertString(value: unknown, path: string): asserts value is string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`Invalid ${path}; expected non-empty string.`);
+  }
+}
+
+function optionalString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function optionalNullableString(value: unknown): string | null | undefined {
+  if (value === null) return null;
+  return optionalString(value);
+}
+
+function optionalBoolean(value: unknown): boolean | undefined {
+  return typeof value === "boolean" ? value : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}