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

package/src/team/index.ts

@@ -0,0 +1,2398 @@
+import { spawn } from "node:child_process";
+import { appendFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { resolveEvoDevPaths } from "../config/paths.ts";
+import { createDefaultSettings, parseSettings } from "../config/settings.ts";
+import { resolveProjectLogKey } from "../runtime-logs/index.ts";
+
+export type TeamAgentRuntime = "codex" | "claude";
+export type TeamAgentStatus = "running" | "recovering" | "recreated" | "stopped" | "failed";
+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 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>>;
+}
+
+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 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";
+}
+
+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 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 TeamEventRecord {
+  version: 1;
+  eventId: string;
+  runId: string;
+  type:
+    | "TeamRunStarted"
+    | "AgentSpawned"
+    | "AgentStopped"
+    | "TeamMessageAccepted"
+    | "TeamMessageDelivered"
+    | "TeamMessageDeliveryFailed"
+    | "AgentNativeSessionRecorded"
+    | "AgentRecoveryDecisionRequired"
+    | "AgentRecovered"
+    | "AgentRecreated"
+    | "TeamRunStopped";
+  roleId?: string;
+  agentId?: string;
+  messageId?: string;
+  summary: string;
+  createdAt: 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;
+  deliveredTo?: string;
+  cc?: string[];
+  error?: string;
+  message?: string;
+}
+
+export interface TeamMessageBrokerOptions {
+  homeDir?: string;
+  runtimeAdapter?: TeamRuntimeAdapter;
+}
+
+export type TeamMessageBrokerSendInput = Omit<SendTeamMessageInput, "homeDir" | "runtimeAdapter">;
+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 TeamAgentSummary {
+  roleId: string;
+  roleName: string;
+  status: TeamAgentStatus;
+  runtime: TeamAgentRuntime;
+  canReceiveMessages: 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[]>;
+  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}$/;
+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. Coordinate role agents, keep decisions explicit, and synthesize final outcomes.",
+  },
+  reviewer: {
+    roleName: "Code Reviewer",
+    description: "Reviews implementation quality, risks, and regressions.",
+    prompt:
+      "You are the code reviewer for this EvoDev team run. Review changes and report concrete findings.",
+  },
+  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.",
+  },
+  executor: {
+    roleName: "Implementation Executor",
+    description: "Implements scoped changes assigned by main.",
+    prompt:
+      "You are the implementation executor for this EvoDev team run. Keep changes scoped and report verification evidence.",
+  },
+};
+
+export function createTeamRunStore(homeDir?: string): TeamRunStore {
+  const paths = resolveTeamRunPaths(homeDir);
+
+  return {
+    paths,
+    async createRunDirs(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) {
+      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 {
+        return null;
+      }
+    },
+    async writeAgent(agent) {
+      await this.createRunDirs(agent.runId);
+      await writeJson(paths.agentPath(agent.runId, agent.roleId), parseTeamAgentRecord(agent));
+    },
+    async readAgent(runId, roleId) {
+      return parseTeamAgentRecord(
+        JSON.parse(await readFile(paths.agentPath(runId, roleId), "utf8")),
+      );
+    },
+    async readAgents(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 appendMessage(runId, message) {
+      await this.createRunDirs(runId);
+      await appendJsonLine(paths.messagesPath(runId), parseTeamMessageRecord(message));
+    },
+    async appendEvent(runId, event) {
+      await this.createRunDirs(runId);
+      await appendJsonLine(paths.eventsPath(runId), parseTeamEventRecord(event));
+    },
+  };
+}
+
+export function resolveTeamRunPaths(homeDir?: string) {
+  const paths = resolveEvoDevPaths(homeDir);
+  return {
+    rootDir: paths.rootDir,
+    roleAgentsDir: paths.roleAgentsDir,
+    teamsDir: paths.teamsDir,
+    runsDir: paths.runsDir,
+    latestRunPath: paths.latestRunPath,
+    runDir: (runId: string) => join(paths.runsDir, runId),
+    runPath: (runId: string) => join(paths.runsDir, runId, "run.json"),
+    tmuxPath: (runId: string) => join(paths.runsDir, runId, "tmux.json"),
+    agentsDir: (runId: string) => join(paths.runsDir, runId, "agents"),
+    agentPath: (runId: string, roleId: string) =>
+      join(paths.runsDir, runId, "agents", `${roleId}.json`),
+    messagesPath: (runId: string) => join(paths.runsDir, runId, "messages.jsonl"),
+    eventsPath: (runId: string) => join(paths.runsDir, runId, "events.jsonl"),
+  };
+}
+
+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 = createAgentStartupPrompt({
+    runId,
+    repoRoot: input.repoRoot,
+    role,
+    roster: [],
+  });
+  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,
+    }),
+  );
+
+  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 = createAgentStartupPrompt({
+    runId: run.runId,
+    repoRoot: run.repoRoot,
+    role,
+    roster: agents,
+  });
+  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,
+    }),
+  );
+
+  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,
+    }),
+  );
+
+  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);
+}
+
+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 (!isActiveTeamAgentStatus(target.status)) {
+    return {
+      ok: false,
+      error: "target-role-not-running",
+      message: `Role ${input.toRoleId} is not running 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,
+      },
+    ),
+  );
+
+  const runtimeAdapter = options.runtimeAdapter ?? createTmuxRuntimeAdapter();
+  try {
+    await runtimeAdapter.sendInput({
+      session: target.tmux.session,
+      paneId: target.tmux.paneId,
+      text: formatDeliveredTeamMessage(message, false),
+    });
+    for (const ccRoleId of ccRoleIds) {
+      const cc = await store.readAgent(run.runId, ccRoleId);
+      if (isActiveTeamAgentStatus(cc.status)) {
+        await runtimeAdapter.sendInput({
+          session: cc.tmux.session,
+          paneId: cc.tmux.paneId,
+          text: formatDeliveredTeamMessage(message, true),
+        });
+      }
+    }
+    await store.appendEvent(
+      run.runId,
+      createTeamEvent(
+        run.runId,
+        "TeamMessageDelivered",
+        `Delivered message ${message.messageId} to ${input.toRoleId}.`,
+        now,
+        { roleId: input.toRoleId, agentId: targetAgentId, messageId: message.messageId },
+      ),
+    );
+    return {
+      ok: true,
+      messageId: message.messageId,
+      deliveredTo: input.toRoleId,
+      cc: ccRoleIds,
+    };
+  } catch (error) {
+    await store.appendEvent(
+      run.runId,
+      createTeamEvent(
+        run.runId,
+        "TeamMessageDeliveryFailed",
+        `Failed to deliver message ${message.messageId}: ${describeError(error)}`,
+        now,
+        { roleId: input.toRoleId, agentId: targetAgentId, messageId: message.messageId },
+      ),
+    );
+    return {
+      ok: false,
+      messageId: message.messageId,
+      error: "delivery-failed",
+      message: describeError(error),
+    };
+  }
+}
+
+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),
+  );
+  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);
+  let entries: string[];
+  try {
+    entries = await readdir(store.paths.runsDir);
+  } catch (error) {
+    if (isNotFoundError(error)) return [];
+    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) {
+    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,
+        });
+
+  return {
+    run: updatedRun,
+    agents: updatedAgents,
+    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,
+      },
+    ),
+  );
+
+  return updatedAgent;
+}
+
+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 = createAgentStartupPrompt({
+      runId: run.runId,
+      repoRoot: run.repoRoot,
+      role,
+      roster,
+    });
+    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);
+
+  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),
+  }));
+}
+
+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 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,
+  });
+
+  return {
+    ...parsed,
+    runtime: input.overrides?.runtime ?? nativeAgent?.target ?? parsed.runtime,
+    model: input.overrides?.model ?? parsed.model,
+    thinkingLevel: input.overrides?.thinkingLevel ?? parsed.thinkingLevel,
+    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 {
+  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,
+    });
+    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}",
+    ]);
+    return { session: input.sessionName, window: "main", paneId: pane.stdout.trim() };
+  }
+
+  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,
+    });
+    if (input.targetPaneId !== undefined) {
+      const pane = await this.splitPane(input.targetPaneId, input.repoRoot, command);
+      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,
+    ]);
+    return { session: input.sessionName, window, paneId: pane.stdout.trim() };
+  }
+
+  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,
+          })
+        : buildAgentResumeShellCommand(input.role, input.startupPrompt, {
+            runId: input.runId,
+            repoRoot: input.repoRoot,
+            mode: input.mode,
+            runtimeCommands: this.options.runtimeCommands,
+          });
+    const session = await this.runner.run("tmux", ["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}",
+      ]);
+      return recoveredHandle(input, window, pane.stdout.trim());
+    }
+
+    if (input.targetPaneId !== undefined && input.role.roleId !== "main") {
+      const pane = await this.splitPane(input.targetPaneId, input.repoRoot, command);
+      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,
+    ]);
+    return recoveredHandle(input, window, pane.stdout.trim());
+  }
+
+  private async splitPane(
+    targetPaneId: string,
+    repoRoot: string,
+    command: string,
+  ): Promise<string> {
+    const pane = await this.runTmux([
+      "split-window",
+      "-h",
+      "-d",
+      "-P",
+      "-F",
+      "#{pane_id}",
+      "-t",
+      targetPaneId,
+      "-c",
+      repoRoot,
+      command,
+    ]);
+    await this.runTmux(["select-layout", "-t", targetPaneId, "tiled"]);
+    return pane.stdout.trim();
+  }
+
+  async sendInput(input: TeamRuntimeSendInputInput): Promise<void> {
+    await this.runTmux(["set-buffer", "-b", "evodev-message", input.text]);
+    await this.runTmux(["paste-buffer", "-d", "-b", "evodev-message", "-t", input.paneId]);
+    await this.runTmux(["send-keys", "-t", input.paneId, "Enter"]);
+  }
+
+  async listPanes(input: TeamRuntimeListPanesInput): Promise<TeamRuntimePaneInfo[]> {
+    const panes = await this.runTmux(["list-panes", "-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 attach-session -t ${input.session}`
+      : `tmux attach-session -t ${input.session} \\; select-pane -t ${input.paneId}`;
+  }
+
+  private async runTmux(
+    args: string[],
+    options?: { input?: string },
+  ): Promise<TeamRuntimeCommandResult> {
+    const result = await this.runner.run("tmux", args, options);
+    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: {
+  runId: string;
+  repoRoot: string;
+  role: ResolvedTeamRole;
+  roster: TeamAgentRecord[];
+}): string {
+  const roster =
+    input.roster.length === 0
+      ? "- main: starting"
+      : input.roster
+          .map((agent) => `- ${agent.roleId}: ${agent.status} (${agent.roleName})`)
+          .join("\n");
+  return [
+    "You are an EvoDev managed role agent.",
+    `Team run: ${input.runId}`,
+    `Repository: ${input.repoRoot}`,
+    `Role id: ${input.role.roleId}`,
+    `Role name: ${input.role.roleName}`,
+    `Runtime: ${input.role.runtime}`,
+    input.role.nativeAgent === null
+      ? "Native Code Agent binding: none"
+      : `Native Code Agent binding: ${input.role.nativeAgent.target}/${input.role.nativeAgent.agentName} (${input.role.nativeAgent.scope})`,
+    `Model: ${input.role.model ?? "default"}`,
+    `Thinking level: ${input.role.thinkingLevel ?? "default"}`,
+    `Write mode: ${input.role.permissions.writeMode}`,
+    `Transcript recording: ${input.role.teamPolicy.recordTranscript ? "enabled" : "disabled"}`,
+    "",
+    "Current known agents:",
+    roster,
+    "",
+    "EvoDev team runtime control contract:",
+    "This run is already inside the EvoDev-managed team runtime.",
+    "For EvoDev role-agent lifecycle, use the current EvoDev run control plane.",
+    "Unprefixed user requests such as 'start the team', 'execute team', 'create agents', or 'spawn roles' mean: use the current EvoDev run control plane.",
+    "Do not answer those requests with only a role plan when a role agent should be created.",
+    "",
+    "Use Teams MCP as the primary control plane:",
+    "- list_agents: discover current EvoDev role agents.",
+    "- spawn_role: create or reuse exactly one EvoDev role agent.",
+    "- send_message: communicate through the EvoDev broker.",
+    "- stop_role: stop a role agent when allowed.",
+    "If Teams MCP is unavailable, fall back to the EvoDev CLI from this repository:",
+    "- evodev team spawn --role <roleId>",
+    "- evodev team send --to <roleId> --message <text>",
+    "- evodev team status",
+    "Teams MCP defaults are inherited from the environment:",
+    `EVODEV_TEAM_RUN_ID=${input.runId}`,
+    `EVODEV_TEAM_ROLE_ID=${input.role.roleId}`,
+    "When calling Teams MCP tools, let the MCP server-bound environment identify this run and role.",
+    "Do not operate tmux directly for role lifecycle; let EvoDev create and track panes.",
+    "Any server-bound role may request role lifecycle changes; EvoDev records and tracks panes but does not use role policy to stop execution.",
+    input.role.roleId === "main"
+      ? "As main, when the user approves team execution, pick the needed role ids, call spawn_role or evodev team spawn for each role, verify with list_agents/status, then send role-specific assignments."
+      : "As a non-main role, prefer coordinating with main through send_message, but lifecycle tools remain advisory and non-gating.",
+    input.role.nativeAgent === null
+      ? "No native Code Agent agent is bound to this role."
+      : `Use the bound native Code Agent agent name '${input.role.nativeAgent.agentName}' as role context when the runtime supports named agents; EvoDev does not load or transform the native agent file.`,
+    "Cross-agent messages are copied to main.",
+    "",
+    input.role.prompt,
+  ].join("\n");
+}
+
+function formatDeliveredTeamMessage(message: TeamMessageRecord, cc: boolean): string {
+  const header = cc ? "[EvoDev team cc]" : "[EvoDev team message]";
+  const footer = cc ? "[/EvoDev team cc]" : "[/EvoDev team message]";
+  return [
+    header,
+    `from: ${message.fromRoleId}`,
+    `to: ${message.toRoleId}`,
+    `type: ${message.type}`,
+    `messageId: ${message.messageId}`,
+    cc ? "" : `cc: ${message.ccRoleIds.join(",") || "none"}`,
+    "",
+    message.body,
+    footer,
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
+function buildAgentShellCommand(
+  role: ResolvedTeamRole,
+  startupPrompt: string,
+  context: {
+    runId: string;
+    repoRoot: string;
+    runtimeCommands?: TmuxRuntimeAdapterOptions["runtimeCommands"];
+  },
+): string {
+  const args =
+    role.runtime === "codex"
+      ? buildCodexArgs(role, startupPrompt)
+      : buildClaudeArgs(role, startupPrompt);
+  const env = {
+    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"];
+  },
+): string {
+  const args =
+    role.runtime === "codex"
+      ? buildCodexResumeArgs(role, startupPrompt, context.mode)
+      : buildClaudeResumeArgs(role, context.mode);
+  const env = {
+    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 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);
+  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");
+  }
+  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);
+  args.push(startupPrompt);
+  return args;
+}
+
+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),
+  };
+}
+
+function parseRolePermissions(value: unknown, main: boolean): TeamRolePermissions {
+  const input = isRecord(value) ? value : {};
+  return {
+    writeMode: parseWriteMode(input.writeMode, main ? "repo-write" : "read-only"),
+    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 (!["running", "recovering", "recreated", "stopped", "failed"].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 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 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 isActiveTeamAgentStatus(status: TeamAgentStatus): boolean {
+  return status === "running" || status === "recovering" || status === "recreated";
+}
+
+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 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 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");
+}
+
+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);
+}