@fiftth/fiftth-cli 1.0.1 → 1.1.1

package/.fiftthnexus/orchestrator.ts

@@ -0,0 +1,2304 @@
+import { execFileSync, execSync, spawn } from "child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { basename, dirname, resolve } from "path";
+import { createInterface } from "readline";
+import { fileURLToPath } from "url";
+
+// ---------------------------------------------------------------------------
+// Resolve executable paths (handles Windows PATH gaps for gh CLI)
+// ---------------------------------------------------------------------------
+function resolveExe(name: string, windowsFallbacks: string[] = []): string {
+	try {
+		const found = execSync(
+			process.platform === "win32" ? `where.exe ${name}` : `which ${name}`,
+			{ encoding: "utf-8", stdio: "pipe" },
+		).split("\n")[0]?.trim();
+		if (found) return found;
+	} catch {
+		// not in PATH
+	}
+
+	for (const fallback of windowsFallbacks) {
+		if (existsSync(fallback)) return fallback;
+	}
+
+	return name; // Return bare name; error will surface when it's used
+}
+
+const GH_EXEC = resolveExe("gh", [
+	"C:\\Program Files\\GitHub CLI\\gh.exe",
+	`${process.env.LOCALAPPDATA ?? ""}\\Programs\\GitHub CLI\\gh.exe`,
+	`${process.env.ProgramFiles ?? ""}\\GitHub CLI\\gh.exe`,
+]);
+const ORCHESTRATOR_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+// ---------------------------------------------------------------------------
+// ANSI Colors & Formatting
+// ---------------------------------------------------------------------------
+const c = {
+	reset: "\x1b[0m",
+	bold: "\x1b[1m",
+	dim: "\x1b[2m",
+	red: "\x1b[38;2;224;122;95m",
+	green: "\x1b[38;2;245;241;232m",
+	yellow: "\x1b[38;2;216;181;106m",
+	blue: "\x1b[38;2;122;122;122m",
+	magenta: "\x1b[38;2;200;169;106m",
+	cyan: "\x1b[38;2;200;169;106m",
+	white: "\x1b[37m",
+	bgRed: "\x1b[41m",
+	bgGreen: "\x1b[42m",
+	bgBlue: "\x1b[44m",
+};
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+interface GitHubIssue {
+	number: number;
+	title: string;
+	body: string;
+	labels: { name: string }[];
+	assignees: { login: string }[];
+	state: string;
+	repoFullName: string;
+	repoPath: string;
+	targetBranch: string;
+	selectedPrdNumber: number | null;
+	taskId: string | null;
+	key: string;
+}
+
+interface RepositoryExecutionContext {
+	repoFullName: string;
+	repoPath: string;
+	prdNumber?: number;
+	taskId?: string;
+	targetBranch?: string;
+}
+
+interface RankedIssue extends GitHubIssue {
+	priority: number;
+	dependsOn: number[];
+	isBlocked: boolean;
+	isInProgress: boolean;
+	slug: string;
+	parentPrdNumber: number | null;
+	worktreeKey: string;
+}
+
+interface CLIOptions {
+	mode: "run" | "status" | "cleanup" | "reset";
+	maxParallel: number;
+	model: string;
+	push: boolean;
+	allPrds: boolean;
+	verbose: boolean;
+	worktree: boolean;
+	prd: number | null;
+	repo: string;
+	targetBranch: string;
+	repositoryContexts: RepositoryExecutionContext[];
+	ghToken: string;
+}
+
+type IssueUiState = "queued" | "planning" | "implementing" | "reviewing" | "done" | "failed" | "timed-out";
+
+interface StageResult {
+	success: boolean;
+	output: string;
+	toolCalls: number;
+	writes: number;
+	errorText: string;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DOCKER_IMAGE = "copilot-agent";
+const WORKTREE_DIR = ".worktrees";
+const CONTAINER_PREFIX = "copilot-agent-";
+const AGENT_OUTPUT_DIR = ".agent";
+const ORCHESTRATOR_LABEL = "ai-running-orchestrator";
+const MAX_ITERATIONS = 10;
+
+const REQUIRED_REPOSITORY_LABELS = [
+	{ name: "P0-critical", description: "Critical - execute first", color: "b60205" },
+	{ name: "P1-high", description: "High priority", color: "d93f0b" },
+	{ name: "P2-medium", description: "Medium priority", color: "fbca04" },
+	{ name: "P3-low", description: "Low priority", color: "0e8a16" },
+	{ name: "ai-running-orchestrator", description: "Issue managed by the Copilot orchestrator", color: "1d76db" },
+	{ name: "blocked", description: "Blocked by another issue", color: "e4e669" },
+	{ name: "in-progress", description: "Copilot is working on this", color: "7057ff" },
+	{ name: "donne", description: "Completed by agent - excluded from orchestrator", color: "006b75" },
+] as const;
+
+let currentUiMode: "default" | "run-minimal" | "run-verbose" = "default";
+
+interface RunDashboardState {
+	active: boolean;
+	events: string[];
+	statsLine: string;
+	loadingText: string;
+	opts: CLIOptions | null;
+	liveStates: Map<string, { label: string; state: IssueUiState }>;
+}
+
+const RUN_DASHBOARD_LIMIT = 5;
+
+const runDashboardState: RunDashboardState = {
+	active: false,
+	events: [],
+	statsLine: "",
+	loadingText: "warming nexus status",
+	opts: null,
+	liveStates: new Map(),
+};
+
+const QUIET_RUN_ICONS = new Set([
+	"[gh]",
+	"[docker]",
+	"[list]",
+	"[filter]",
+	"[worktree]",
+	"[reuse]",
+	"[save]",
+	"[commit]",
+	"[diff]",
+	"[hint]",
+	"[label]",
+	"[iter]",
+]);
+
+const IS_INTEGRATED_UI = process.env.FIFTTH_NEXUS_EVENT_STREAM === "true";
+const NEXUS_EVENT_PREFIX = "__FIFTTH_NEXUS_EVENT__";
+const NEXUS_STATE_PREFIX = "__FIFTTH_NEXUS_STATE__";
+
+// Copilot CLI headless server — not needed; SDK auto-starts inside Docker
+
+// Prompt file paths (relative to project root)
+const PROMPT_PLAN = ".fiftthnexus/skills/env-plan-prompt.md";
+const PROMPT_IMPLEMENT = ".fiftthnexus/skills/env-implement-prompt.md";
+const PROMPT_REVIEW = ".fiftthnexus/skills/env-review-prompt.md";
+
+// Dockerfile path (relative to project root)
+const DOCKERFILE_DIR = ".fiftthnexus/actions";
+
+function loadRepositoryContexts(): RepositoryExecutionContext[] {
+	const raw = process.env.FIFTTH_NEXUS_REPOSITORIES;
+	if (!raw) {
+		return [];
+	}
+
+	try {
+		const parsed = JSON.parse(raw) as RepositoryExecutionContext[];
+		return parsed.filter((context) => Boolean(context.repoFullName && context.repoPath));
+	} catch {
+		return [];
+	}
+}
+
+// ---------------------------------------------------------------------------
+// CLI Argument Parser
+// ---------------------------------------------------------------------------
+function parseArgs(): CLIOptions {
+	const args = process.argv.slice(2);
+	const repositoryContexts = loadRepositoryContexts();
+	const opts: CLIOptions = {
+		mode: "run",
+		maxParallel: 3,
+		model: process.env.FIFTTH_DEFAULT_MODEL ?? "gpt-5.4",
+		push: false,
+		allPrds: false,
+		verbose: false,
+		worktree: false,
+		prd: null,
+		repo: repositoryContexts[0]?.repoFullName ?? inferGitHubRepo(),
+		targetBranch: repositoryContexts[0]?.targetBranch ?? "",
+		repositoryContexts,
+		ghToken: "",
+	};
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i]!;
+
+		switch (arg) {
+			case "--status":
+				opts.mode = "status";
+				break;
+			case "--cleanup":
+				opts.mode = "cleanup";
+				break;
+			case "--reset":
+				opts.mode = "reset";
+				break;
+			case "--max-parallel":
+				opts.maxParallel = parseInt(args[++i] ?? "3", 10);
+				break;
+			case "--model":
+				opts.model = args[++i] ?? (process.env.FIFTTH_DEFAULT_MODEL ?? "gpt-5.4");
+				break;
+			case "--push":
+				opts.push = true;
+				break;
+			case "--all-prds":
+				opts.allPrds = true;
+				break;
+			case "--verbose":
+				opts.verbose = true;
+				break;
+			case "--worktree":
+				opts.worktree = true;
+				break;
+			case "--prd": {
+				const parsed = parseInt(args[++i] ?? "", 10);
+				if (Number.isNaN(parsed) || parsed <= 0) {
+					console.error(`${c.red}Invalid --prd value. Use a positive issue number.${c.reset}`);
+					process.exit(1);
+				}
+				opts.prd = parsed;
+				break;
+			}
+			case "--repo":
+				opts.repo = args[++i] ?? opts.repo;
+				break;
+			case "--target-branch":
+				opts.targetBranch = args[++i] ?? "";
+				break;
+			case "--help":
+			case "-h":
+				printHelp();
+				process.exit(0);
+			default:
+				console.error(`${c.red}Unknown argument: ${arg}${c.reset}`);
+				printHelp();
+				process.exit(1);
+		}
+	}
+
+	return opts;
+}
+
+function printHelp(): void {
+	console.log(`
+${c.bold}fiftth nexus${c.reset}
+
+${c.bold}USAGE:${c.reset}
+	npx tsx .fiftthnexus/orchestrator.ts [OPTIONS]
+
+${c.bold}MODES:${c.reset}
+	(default)            Run the orchestrator loop
+	--status             Show current state of issues and containers
+	--cleanup            Remove all worktrees and containers
+	--reset              Reset in-progress/blocked labels on all issues
+
+${c.bold}OPTIONS:${c.reset}
+	--max-parallel <n>   Max containers in parallel (default: 3)
+	--model <name>       Copilot model to use (default: ${process.env.FIFTTH_DEFAULT_MODEL ?? "gpt-5.4"})
+	--prd <n>            Run only issues linked to parent PRD #n
+	--all-prds           Run all eligible PRDs without selection prompt
+	--verbose            Show full container/agent logs
+	--push               Push branches and create PRs
+	--repo <owner/name>  GitHub repository to use (default: inferred from git remote)
+	--worktree           Create the orchestrator branch in a git worktree from --target-branch
+	--target-branch <b>  Base branch used when --worktree is enabled
+
+${c.bold}ENVIRONMENT:${c.reset}
+	(none required - uses gh CLI keyring automatically)
+`);
+}
+
+function stripAnsi(value: string): string {
+	return value.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+function padRight(value: string, width: number): string {
+	const visibleLength = stripAnsi(value).length;
+	if (visibleLength >= width) {
+		return value;
+	}
+
+	return `${value}${" ".repeat(width - visibleLength)}`;
+}
+
+function renderPanelLines(title: string, lines: string[], width?: number): string[] {
+	const safeLines = lines.length > 0 ? lines : [""];
+	const targetWidth = width ?? Math.max(title.length + 4, ...safeLines.map((line) => stripAnsi(line).length)) + 2;
+	const border = `${c.cyan}+${"-".repeat(targetWidth + 2)}+${c.reset}`;
+
+	return [
+		border,
+		`${c.cyan}|${c.reset} ${padRight(`${c.bold}${title}${c.reset}`, targetWidth)} ${c.cyan}|${c.reset}`,
+		border,
+		...safeLines.map((line) => `${c.cyan}|${c.reset} ${padRight(line, targetWidth)} ${c.cyan}|${c.reset}`),
+		border,
+	];
+}
+
+function joinPanelColumns(columns: string[][], gap = 2): string[] {
+	const maxHeight = Math.max(...columns.map((column) => column.length));
+	const widths = columns.map((column) => Math.max(...column.map((line) => stripAnsi(line).length)));
+
+	return Array.from({ length: maxHeight }, (_, index) => columns
+		.map((column, columnIndex) => padRight(column[index] ?? "", widths[columnIndex] ?? 0))
+		.join(" ".repeat(gap)));
+}
+
+function countRunningContainers(): number {
+	try {
+		const output = sh('docker ps --format "{{.Names}}"', { silent: true });
+		if (!output) {
+			return 0;
+		}
+
+		return output.split("\n").filter(Boolean).length;
+	} catch {
+		return 0;
+	}
+}
+
+function formatEventLine(icon: string, msg: string): string {
+	const tone =
+		icon === "[error]" || icon === "[fail]" || icon === "[abort]"
+			? c.red
+			: icon === "[warn]" || icon === "[pause]"
+				? c.yellow
+				: icon === "[ok]" || icon === "[done]"
+					? c.green
+					: c.white;
+	const ts = new Date().toISOString().slice(11, 19);
+	return `${c.dim}${ts}${c.reset} ${tone}${msg}${c.reset}`;
+}
+
+function compactIssueLabel(label: string): string {
+	const match = label.match(/([^/]+\/)?([^#]+)#(\d+)$/);
+	if (!match) {
+		return label;
+	}
+
+	return `${match[2]} #${match[3]}`;
+}
+
+function compactStateLabel(state: IssueUiState): string {
+	switch (state) {
+		case "planning":
+			return "agent planning";
+		case "implementing":
+			return "agent implementing";
+		case "reviewing":
+			return "agent reviewing";
+		case "done":
+			return "done";
+		case "failed":
+			return "failed";
+		case "timed-out":
+			return "timed out";
+		default:
+			return "queued";
+	}
+}
+
+function renderRunDashboard(): string {
+	const opts = runDashboardState.opts;
+	if (!opts) {
+		return "";
+	}
+
+	const contexts = repositoryContextsForRun(opts);
+	const repoLabel = opts.repositoryContexts.length > 0
+		? contexts.length === 1
+			? contexts[0]!.repoFullName
+			: `${contexts.length} repositories`
+		: opts.repo || "(current gh context)";
+	const scopeLabel = opts.repositoryContexts.length > 0
+		? "task-scoped PRDs from checkout"
+		: opts.prd
+			? `PRD #${opts.prd}`
+			: opts.allPrds
+				? "all PRDs"
+				: "select PRD on startup";
+	const activityLines = runDashboardState.events.length > 0
+		? runDashboardState.events
+		: [`${c.dim}Waiting for activity...${c.reset}`];
+	const liveStates = [...runDashboardState.liveStates.values()]
+		.filter((entry) => entry.state === "planning" || entry.state === "implementing" || entry.state === "reviewing" || entry.state === "queued")
+		.slice(0, 6)
+		.map((entry) => `  ${compactIssueLabel(entry.label)}: ${compactStateLabel(entry.state)}`);
+
+	return [
+		"",
+		`${fiftthMark()} ${c.bold}fiftth nexus${c.reset}`,
+		`${c.dim}repo${c.reset} ${repoLabel}`,
+		`${c.dim}scope${c.reset} ${scopeLabel}`,
+		`${c.dim}workspace${c.reset} ${process.env.FIFTTH_WORKSPACE || "(none)"}   ${c.dim}model${c.reset} ${opts.model}   ${c.dim}mode${c.reset} ${opts.worktree ? "worktree" : "literal checkout"}`,
+		`${c.dim}parallel${c.reset} ${opts.worktree ? opts.maxParallel : 1}   ${c.dim}containers${c.reset} ${countRunningContainers()}`,
+		"",
+		`${c.cyan}. . . ....${c.reset} ${runDashboardState.loadingText}`,
+		"",
+		`${c.bold}status${c.reset}`,
+		`${runDashboardState.statsLine || `${c.dim}No pipeline stats yet${c.reset}`}`,
+		"",
+		`${c.bold}active agents${c.reset}`,
+		...(liveStates.length > 0 ? liveStates : [`  ${c.dim}No active agents${c.reset}`]),
+		"",
+		`${c.bold}recent${c.reset}`,
+		...activityLines.map((line) => `  ${line}`),
+		"",
+	].join("\n");
+}
+
+function startRunDashboard(opts: CLIOptions): void {
+	if (!process.stdout.isTTY || !process.stdin.isTTY || currentUiMode !== "run-minimal") {
+		return;
+	}
+
+	runDashboardState.active = true;
+	runDashboardState.opts = opts;
+	runDashboardState.events = [];
+	runDashboardState.statsLine = "warming the orchestration pipeline";
+	runDashboardState.loadingText = "warming nexus status";
+	process.stdout.write("\n");
+	process.stdout.write("\x1b[s");
+	process.stdout.write(renderRunDashboard());
+}
+
+function refreshRunDashboard(): void {
+	if (!runDashboardState.active) {
+		return;
+	}
+
+	process.stdout.write("\x1b[u\x1b[J\x1b[s");
+	process.stdout.write(renderRunDashboard());
+}
+
+function stopRunDashboard(printSnapshot = true): void {
+	if (!runDashboardState.active) {
+		return;
+	}
+
+	const snapshot = renderRunDashboard();
+	runDashboardState.active = false;
+	process.stdout.write("\x1b[u\x1b[J");
+	if (printSnapshot) {
+		console.log(snapshot);
+	}
+}
+
+function inferGitHubRepo(): string {
+	const fromEnv = process.env.GH_REPO ?? process.env.GITHUB_REPOSITORY;
+	if (fromEnv) {
+		return fromEnv;
+	}
+
+	try {
+		const remote = sh("git remote get-url origin", { silent: true });
+		if (!remote) {
+			return "";
+		}
+
+		const httpsMatch = remote.match(/github\.com[/:]([^/]+)\/([^/.]+)(?:\.git)?$/i);
+		if (httpsMatch) {
+			return `${httpsMatch[1]}/${httpsMatch[2]}`;
+		}
+	} catch {
+		// ignore and fallback to empty
+	}
+
+	return "";
+}
+
+// ---------------------------------------------------------------------------
+// Helpers: Shell
+// ---------------------------------------------------------------------------
+function sh(cmd: string, opts?: { cwd?: string; silent?: boolean }): string {
+	try {
+		return execSync(cmd, {
+			encoding: "utf-8",
+			cwd: opts?.cwd,
+			stdio: opts?.silent ? "pipe" : ["pipe", "pipe", "pipe"],
+			maxBuffer: 10 * 1024 * 1024,
+			env: { ...process.env },
+		}).trim();
+	} catch (err: unknown) {
+		if (!opts?.silent) {
+			throw err;
+		}
+		if (err && typeof err === "object" && "stdout" in err) {
+			const stdout = (err as { stdout?: unknown }).stdout;
+			if (stdout && typeof stdout === "object" && "toString" in stdout) {
+				return String((stdout as { toString: () => string }).toString()).trim();
+			}
+		}
+		return "";
+	}
+}
+
+// Environment for gh subprocesses — strips token vars so gh always uses its keyring.
+function ghEnv(): NodeJS.ProcessEnv {
+	const env = { ...process.env };
+	delete env["GH_TOKEN"];
+	delete env["GITHUB_TOKEN"];
+	return env;
+}
+
+function gh(args: string, repo?: string): string {
+	const repoArg = repo ? `-R "${repo}" ` : "";
+	return execSync(`"${GH_EXEC}" ${repoArg}${args}`, {
+		encoding: "utf-8",
+		stdio: ["pipe", "pipe", "pipe"],
+		maxBuffer: 10 * 1024 * 1024,
+		env: ghEnv(),
+	}).trim();
+}
+
+function ghJson<T>(args: string, repo?: string): T {
+	const repoArg = repo ? `-R "${repo}" ` : "";
+	const cmd = `"${GH_EXEC}" ${repoArg}${args}`;
+	let result = "";
+	try {
+		result = execSync(cmd, {
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+			maxBuffer: 10 * 1024 * 1024,
+			env: ghEnv(),
+		}).trim();
+	} catch (err: unknown) {
+		const stderr =
+			err && typeof err === "object" && "stderr" in err
+				? String((err as { stderr: unknown }).stderr ?? "").trim()
+				: "";
+		const stdout =
+			err && typeof err === "object" && "stdout" in err
+				? String((err as { stdout: unknown }).stdout ?? "").trim()
+				: "";
+		if (stderr) {
+			console.error(`${c.red}[gh error]${c.reset} ${stderr}`);
+		}
+		// gh returns exit 1 on empty list in some versions — try stdout
+		if (stdout && stdout.startsWith("[")) {
+			result = stdout;
+		} else {
+			return [] as unknown as T;
+		}
+	}
+	if (!result) {
+		return [] as unknown as T;
+	}
+	try {
+		return JSON.parse(result) as T;
+	} catch {
+		console.error(`${c.red}[gh error]${c.reset} Failed to parse JSON: ${result.slice(0, 200)}`);
+		return [] as unknown as T;
+	}
+}
+
+function docker(args: string): string {
+	return sh(`docker ${args}`);
+}
+
+function parseCommandArgs(command: string): string[] {
+	const args: string[] = [];
+	let current = "";
+	let quote: '"' | "'" | null = null;
+
+	for (let index = 0; index < command.length; index++) {
+		const char = command[index]!;
+
+		if (quote) {
+			if (char === quote) {
+				quote = null;
+				continue;
+			}
+
+			if (char === "\\" && quote === '"' && index + 1 < command.length) {
+				current += command[index + 1]!;
+				index++;
+				continue;
+			}
+
+			current += char;
+			continue;
+		}
+
+		if (char === '"' || char === "'") {
+			quote = char;
+			continue;
+		}
+
+		if (/\s/.test(char)) {
+			if (current) {
+				args.push(current);
+				current = "";
+			}
+			continue;
+		}
+
+		current += char;
+	}
+
+	if (quote) {
+		throw new Error(`Unterminated quote in command: ${command}`);
+	}
+
+	if (current) {
+		args.push(current);
+	}
+
+	return args;
+}
+
+function runDirectiveCommand(command: string, cwd?: string): string {
+	const parsed = parseCommandArgs(command);
+	if (parsed.length === 0) {
+		return "";
+	}
+
+	const [bin, ...args] = parsed;
+	const executable = bin === "gh" ? GH_EXEC : bin;
+	const env = bin === "gh" ? ghEnv() : { ...process.env };
+
+	return execFileSync(executable, args, {
+		encoding: "utf-8",
+		timeout: 30000,
+		maxBuffer: 5 * 1024 * 1024,
+		cwd: cwd ?? process.cwd(),
+		env,
+	}).trim();
+}
+
+function emitIntegratedEvent(icon: string, message: string): void {
+	if (!IS_INTEGRATED_UI) {
+		return;
+	}
+
+	process.stdout.write(`${NEXUS_EVENT_PREFIX}${JSON.stringify({ icon, message })}\n`);
+}
+
+function emitIntegratedState(
+	key: string,
+	label: string,
+	state: IssueUiState,
+	repoFullName?: string,
+	worktreeKey?: string,
+	issueNumber?: number,
+): void {
+	if (!IS_INTEGRATED_UI) {
+		return;
+	}
+
+	process.stdout.write(`${NEXUS_STATE_PREFIX}${JSON.stringify({ key, label, state, repoFullName, worktreeKey, issueNumber })}\n`);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers: Logging
+// ---------------------------------------------------------------------------
+function log(icon: string, msg: string): void {
+	if (IS_INTEGRATED_UI) {
+		emitIntegratedEvent(icon, msg);
+		return;
+	}
+
+	if (currentUiMode === "run-minimal" && QUIET_RUN_ICONS.has(icon)) {
+		return;
+	}
+
+	if (currentUiMode === "run-minimal") {
+		if (runDashboardState.active) {
+			runDashboardState.events = [
+				...runDashboardState.events.slice(-(RUN_DASHBOARD_LIMIT - 1)),
+				formatEventLine(icon, msg),
+			];
+			runDashboardState.loadingText = msg;
+			refreshRunDashboard();
+			return;
+		}
+
+		switch (icon) {
+			case "[error]":
+				console.log(`${c.red}${msg}${c.reset}`);
+				return;
+			case "[warn]":
+			case "[fail]":
+			case "[abort]":
+				console.log(`${c.yellow}${msg}${c.reset}`);
+				return;
+			case "[ok]":
+				console.log(`${c.green}${msg}${c.reset}`);
+				return;
+			default:
+				console.log(msg);
+				return;
+		}
+	}
+
+	const ts = new Date().toISOString().slice(11, 19);
+	console.log(`${c.dim}[${ts}]${c.reset} ${icon} ${msg}`);
+}
+
+function header(text: string): void {
+	const line = "=".repeat(60);
+	console.log(`\n${c.cyan}${line}${c.reset}`);
+	console.log(`${c.cyan}|${c.reset} ${c.bold}${text}${c.reset}`);
+	console.log(`${c.cyan}${line}${c.reset}\n`);
+}
+
+function box(lines: string[]): void {
+	const maxLen = Math.max(...lines.map((l) => l.replace(/\x1b\[[0-9;]*m/g, "").length));
+	const border = "-".repeat(maxLen + 2);
+	console.log(`${c.dim}+${border}+${c.reset}`);
+	for (const line of lines) {
+		const plain = line.replace(/\x1b\[[0-9;]*m/g, "");
+		const pad = " ".repeat(maxLen - plain.length);
+		console.log(`${c.dim}|${c.reset} ${line}${pad} ${c.dim}|${c.reset}`);
+	}
+	console.log(`${c.dim}+${border}+${c.reset}`);
+}
+
+function fiftthMark(color = c.cyan): string {
+	return `${color}■ ■ ■ ■■■■${c.reset}`;
+}
+
+function printRunIntro(opts: CLIOptions): void {
+	if (IS_INTEGRATED_UI) {
+		log("[run]", "nexus dashboard ready");
+		return;
+	}
+
+	if (currentUiMode === "run-minimal") {
+		startRunDashboard(opts);
+		log("[run]", "nexus dashboard ready");
+		return;
+	}
+
+	const contexts = repositoryContextsForRun(opts);
+	const scopedByCheckout = opts.repositoryContexts.length > 0;
+	const repoLabel = scopedByCheckout
+		? contexts.length === 1
+			? contexts[0]!.repoFullName
+			: `${contexts.length} repositories`
+		: opts.repo || "(current gh context)";
+	const scopeLabel = scopedByCheckout
+		? "task-scoped PRDs from checkout"
+		: opts.prd
+			? `PRD #${opts.prd}`
+			: opts.allPrds
+				? "all PRDs"
+				: "select PRD on startup";
+
+	console.log();
+	console.log(`${fiftthMark()} ${c.bold}fiftth nexus${c.reset}`);
+	console.log(`${c.dim}repo${c.reset} ${repoLabel}`);
+	console.log(`${c.dim}scope${c.reset} ${scopeLabel}`);
+	console.log(`${c.dim}mode${c.reset} ${opts.worktree ? "worktree" : "literal checkout"}`);
+	if (opts.targetBranch) {
+		console.log(`${c.dim}target branch${c.reset} ${opts.targetBranch}`);
+	}
+	console.log(`${c.dim}parallel${c.reset} ${opts.worktree ? opts.maxParallel : 1}   ${c.dim}model${c.reset} ${opts.model}   ${c.dim}log${c.reset} ${opts.verbose ? "verbose" : "minimal"}`);
+	console.log();
+}
+
+// ---------------------------------------------------------------------------
+// Helpers: Slug / Names
+// ---------------------------------------------------------------------------
+function slugify(title: string): string {
+	return title
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-|-$/g, "")
+		.slice(0, 40);
+}
+
+function branchName(issue: GitHubIssue): string {
+	const parentPrdNumber = parseParentPrdNumber(issue.body);
+	if (parentPrdNumber !== null) {
+		return `orchestrator/prd-${parentPrdNumber}`;
+	}
+
+	return `orchestrator/issue-${issue.number}-${slugify(issue.title)}`;
+}
+
+function activeBranch(issue: GitHubIssue, opts: CLIOptions): string {
+	if (!opts.worktree && opts.targetBranch) {
+		return opts.targetBranch;
+	}
+
+	return branchName(issue);
+}
+
+function parseTaskIdMetadata(body: string | null): string | null {
+	if (!body) {
+		return null;
+	}
+
+	const match = body.match(/^task-id:\s*(.+)$/im);
+	const taskId = match?.[1]?.trim();
+	return taskId ? taskId : null;
+}
+
+function issueKey(repoFullName: string, issueNumber: number): string {
+	return `${repoFullName}#${issueNumber}`;
+}
+
+function containerName(issue: Pick<GitHubIssue, "repoFullName" | "number">): string {
+	const repoSlug = issue.repoFullName.replace(/[^a-zA-Z0-9]+/g, "-").toLowerCase();
+	return `${CONTAINER_PREFIX}${repoSlug}-${issue.number}`;
+}
+
+function worktreePath(issue: Pick<RankedIssue, "number" | "worktreeKey" | "repoPath">): string {
+	return resolve(issue.repoPath, WORKTREE_DIR, issue.worktreeKey || `issue-${issue.number}`);
+}
+
+function resolveStartPoint(targetBranch: string, repoPath = process.cwd()): string {
+	if (!targetBranch) {
+		return "HEAD";
+	}
+
+	if (sh(`git rev-parse --verify --quiet "refs/heads/${targetBranch}"`, { cwd: repoPath, silent: true })) {
+		return targetBranch;
+	}
+
+	if (sh(`git rev-parse --verify --quiet "refs/remotes/origin/${targetBranch}"`, { cwd: repoPath, silent: true })) {
+		return `origin/${targetBranch}`;
+	}
+
+	throw new Error(`Target branch not found locally or on origin: ${targetBranch}`);
+}
+
+function repositoryContextsForRun(opts: CLIOptions): RepositoryExecutionContext[] {
+	if (opts.repositoryContexts.length > 0) {
+		return opts.repositoryContexts;
+	}
+
+	return [{
+		repoFullName: opts.repo,
+		repoPath: process.cwd(),
+		prdNumber: opts.prd ?? undefined,
+		taskId: undefined,
+		targetBranch: opts.targetBranch,
+	}];
+}
+
+// ---------------------------------------------------------------------------
+// Helpers: Confirmation prompt
+// ---------------------------------------------------------------------------
+async function confirm(message: string): Promise<boolean> {
+	if (process.env.FIFTTH_NEXUS_AUTO_CONFIRM === "true") {
+		return true;
+	}
+
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	return new Promise((resolveAnswer) => {
+		rl.question(`\n${c.yellow}?${c.reset} ${message} ${c.dim}(y/N)${c.reset} `, (answer) => {
+			rl.close();
+			const normalized = answer.trim().toLowerCase();
+			resolveAnswer(normalized === "y" || normalized === "yes");
+		});
+	});
+}
+
+async function pickPrdKey(options: string[]): Promise<string | "all" | null> {
+	const sorted = [...options].sort((a, b) => {
+		const aNum = parseInt(a.replace("prd-", ""), 10);
+		const bNum = parseInt(b.replace("prd-", ""), 10);
+		return aNum - bNum;
+	});
+
+	console.log();
+	console.log(`${c.bold}select a PRD${c.reset}`);
+	for (let i = 0; i < sorted.length; i++) {
+		console.log(`  ${c.cyan}${i + 1}.${c.reset} ${sorted[i]}`);
+	}
+	console.log(`  ${c.cyan}a.${c.reset} all PRDs`);
+	console.log(`  ${c.cyan}q.${c.reset} quit`);
+
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	return new Promise((resolveChoice) => {
+		rl.question(`\n${c.yellow}?${c.reset} Select option: `, (answer) => {
+			rl.close();
+			const normalized = answer.trim().toLowerCase();
+			if (normalized === "a" || normalized === "all") {
+				resolveChoice("all");
+				return;
+			}
+			if (normalized === "q" || normalized === "quit") {
+				resolveChoice(null);
+				return;
+			}
+			const idx = parseInt(normalized, 10);
+			if (Number.isNaN(idx) || idx < 1 || idx > sorted.length) {
+				resolveChoice(null);
+				return;
+			}
+			resolveChoice(sorted[idx - 1]!);
+		});
+	});
+}
+
+function uiStateLabel(state: IssueUiState): string {
+	switch (state) {
+		case "planning":
+			return "fiftth planning";
+		case "implementing":
+			return "fiftth implementing";
+		case "reviewing":
+			return "fiftth reviewing";
+		case "done":
+			return "fiftth done";
+		case "timed-out":
+			return "fiftth timed out";
+		case "failed":
+			return "fiftth failed";
+		default:
+			return "fiftth queued";
+	}
+}
+
+function startLiveTicker(
+	getLine: () => string,
+	intervalMs = 130,
+): { stop: () => void } {
+	const frames = ["■ ■ ■ ■■■■", "■ ■ ■■ ■■■", "■ ■■■■ ■ ■", "■■■■ ■ ■ ■"];
+	let frameIndex = 0;
+	let timer: NodeJS.Timeout | null = null;
+
+	const render = () => {
+		const frame = frames[frameIndex % frames.length]!;
+		frameIndex++;
+		const line = `${c.dim}${frame}${c.reset} ${getLine()}`;
+		process.stdout.write(`\r${line}    `);
+	};
+
+	render();
+	timer = setInterval(render, intervalMs);
+
+	return {
+		stop: () => {
+			if (timer) clearInterval(timer);
+			process.stdout.write("\r\x1b[K");
+		},
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Phase 1: Collect & Parse Issues
+// ---------------------------------------------------------------------------
+function collectIssues(label: string, opts: CLIOptions): GitHubIssue[] {
+	const collected: GitHubIssue[] = [];
+
+	for (const context of repositoryContextsForRun(opts)) {
+		const labelArg = label ? ` --label "${label}"` : "";
+		const issues = ghJson<Array<{
+			number: number;
+			title: string;
+			body: string;
+			labels: { name: string }[];
+			assignees: { login: string }[];
+			state: string;
+		}>>(
+			`issue list${labelArg} --state open --json number,title,body,labels,assignees,state --limit 100`,
+			context.repoFullName,
+		);
+
+		const filtered = issues
+			.filter((issue) => !issue.labels.some((entry) => entry.name === "donne"))
+			.filter((issue) => {
+				if (context.taskId && parseTaskIdMetadata(issue.body) !== context.taskId) {
+					return false;
+				}
+
+				if (typeof context.prdNumber === "number" && parseParentPrdNumber(issue.body) !== context.prdNumber) {
+					return false;
+				}
+
+				return true;
+			})
+			.map((issue) => ({
+				...issue,
+				repoFullName: context.repoFullName,
+				repoPath: context.repoPath,
+				targetBranch: context.targetBranch ?? "",
+				selectedPrdNumber: context.prdNumber ?? null,
+				taskId: context.taskId ?? null,
+				key: issueKey(context.repoFullName, issue.number),
+			}));
+
+		log(
+			"[list]",
+			`Found ${c.bold}${filtered.length}${c.reset} eligible issue(s) in ${c.cyan}${context.repoFullName}${c.reset}`,
+		);
+
+		collected.push(...filtered);
+	}
+
+	return collected;
+}
+
+function parseDependencies(body: string | null): number[] {
+	if (!body) {
+		return [];
+	}
+
+	const deps: number[] = [];
+	const patterns = [/depends[- ]on:\s*#(\d+)/gi, /blocked[- ]by:\s*#(\d+)/gi, /requires:\s*#(\d+)/gi];
+
+	for (const pattern of patterns) {
+		let match: RegExpExecArray | null;
+		while ((match = pattern.exec(body)) !== null) {
+			deps.push(parseInt(match[1]!, 10));
+		}
+	}
+
+	return [...new Set(deps)];
+}
+
+function parseParentPrdNumber(body: string | null): number | null {
+	if (!body) {
+		return null;
+	}
+
+	const match = body.match(/##\s*Parent\s+PRD\s*\r?\n\s*#(\d+)/i) ?? body.match(/parent\s+prd\s*#(\d+)/i);
+	if (!match) {
+		return null;
+	}
+
+	const parsed = parseInt(match[1] ?? "", 10);
+	return Number.isNaN(parsed) ? null : parsed;
+}
+
+function worktreeKeyForIssue(issue: Pick<GitHubIssue, "number" | "body">): string {
+	const parentPrdNumber = parseParentPrdNumber(issue.body);
+	if (parentPrdNumber !== null) {
+		return `prd-${parentPrdNumber}`;
+	}
+
+	return `issue-${issue.number}`;
+}
+
+function parsePriority(labels: { name: string }[]): number {
+	for (const label of labels) {
+		const match = label.name.match(/^P(\d)/);
+		if (match) {
+			return parseInt(match[1]!, 10);
+		}
+	}
+	return 9;
+}
+
+function resolveDepGraph(issues: GitHubIssue[]): RankedIssue[] {
+	const openNumbersByRepo = new Map<string, Set<number>>();
+	for (const issue of issues) {
+		const openNumbers = openNumbersByRepo.get(issue.repoFullName) ?? new Set<number>();
+		openNumbers.add(issue.number);
+		openNumbersByRepo.set(issue.repoFullName, openNumbers);
+	}
+
+	return issues
+		.map((issue): RankedIssue => {
+			const priority = parsePriority(issue.labels);
+			const dependsOn = parseDependencies(issue.body);
+			const openNumbers = openNumbersByRepo.get(issue.repoFullName) ?? new Set<number>();
+			const isBlocked = dependsOn.some((dep) => openNumbers.has(dep));
+			const isInProgress = issue.labels.some((l) => l.name === "in-progress");
+			const slug = slugify(issue.title);
+			const parentPrdNumber = parseParentPrdNumber(issue.body);
+			const worktreeKey = worktreeKeyForIssue(issue);
+
+			return {
+				...issue,
+				priority,
+				dependsOn,
+				isBlocked,
+				isInProgress,
+				slug,
+				parentPrdNumber,
+				worktreeKey,
+			};
+		})
+		.sort((a, b) => {
+			if (a.isInProgress !== b.isInProgress) {
+				return a.isInProgress ? 1 : -1;
+			}
+			if (a.isBlocked !== b.isBlocked) {
+				return a.isBlocked ? 1 : -1;
+			}
+			return a.priority - b.priority;
+		});
+}
+
+// ---------------------------------------------------------------------------
+// Phase 1.5: Validate CLI dependencies
+// ---------------------------------------------------------------------------
+function validateGhCLI(repo: string): string {
+	log("[gh]", `Using gh CLI at: ${c.dim}${GH_EXEC}${c.reset}`);
+
+	// Verify auth and extract the stored token so headless subprocesses can use it.
+	try {
+		// gh auth status exits 0 when logged in (writes to stderr in some versions)
+		execSync(`"${GH_EXEC}" auth status`, {
+			encoding: "utf-8",
+			stdio: "pipe",
+			env: ghEnv(),
+		});
+	} catch (err: unknown) {
+		// Exit code 1 means not logged in
+		const stderr =
+			err && typeof err === "object" && "stderr" in err
+				? String((err as { stderr: unknown }).stderr ?? "")
+				: String(err);
+		console.error(`${c.red}[gh error]${c.reset} gh auth status failed:\n${stderr.trim()}`);
+		console.error(`${c.yellow}Run: gh auth login${c.reset} to authenticate the gh CLI.`);
+		process.exit(1);
+	}
+
+	// Extract token from gh keyring so it can be forwarded to Docker containers.
+	let ghToken = "";
+	try {
+		ghToken = execSync(`"${GH_EXEC}" auth token`, {
+			encoding: "utf-8",
+			stdio: "pipe",
+			env: ghEnv(),
+		}).trim();
+		log("[gh]", `${c.green}Authenticated${c.reset} via gh keyring`);
+	} catch {
+		log("[gh]", `${c.yellow}Could not read token from gh keyring${c.reset}`);
+	}
+
+	if (repo) {
+		log("[gh]", `Target repository: ${c.cyan}${repo}${c.reset}`);
+	}
+
+	return ghToken;
+}
+
+function ensureRepositoryLabels(repo: string): void {
+	for (const label of REQUIRED_REPOSITORY_LABELS) {
+		try {
+			gh(
+				`label create "${label.name}" --description "${label.description}" --color "${label.color}" --force`,
+				repo,
+			);
+		} catch (err: unknown) {
+			const message = err instanceof Error ? err.message : String(err);
+			log("[warn]", `Could not ensure label ${label.name} in ${repo}: ${message}`);
+		}
+	}
+}
+
+function ensureLabelsForRun(opts: CLIOptions): void {
+	for (const context of repositoryContextsForRun(opts)) {
+		ensureRepositoryLabels(context.repoFullName);
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Phase 2: Docker Image
+// ---------------------------------------------------------------------------
+function ensureDockerImage(): void {
+	try {
+		sh(`docker image inspect ${DOCKER_IMAGE}`, { silent: true });
+		log("[docker]", `Docker image "${DOCKER_IMAGE}" found`);
+	} catch {
+		log("[docker]", `Building Docker image "${DOCKER_IMAGE}"...`);
+
+		const dockerDir = resolve(ORCHESTRATOR_ROOT, DOCKERFILE_DIR);
+		const dockerfilePath = resolve(dockerDir, "Dockerfile");
+
+		if (!existsSync(dockerfilePath)) {
+			throw new Error(`Dockerfile not found at ${dockerfilePath}`);
+		}
+
+		docker(`build -t ${DOCKER_IMAGE} ${dockerDir}`);
+		log("[ok]", "Docker image built successfully");
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Phase 3: Worktree Management
+// ---------------------------------------------------------------------------
+function ensureWorktreeDir(repoPath = process.cwd()): void {
+	const dir = resolve(repoPath, WORKTREE_DIR);
+	if (!existsSync(dir)) {
+		mkdirSync(dir, { recursive: true });
+
+		// Add to .gitignore if not present.
+		const gitignorePath = resolve(repoPath, ".gitignore");
+		if (existsSync(gitignorePath)) {
+			const content = readFileSync(gitignorePath, "utf-8");
+			if (!content.includes(WORKTREE_DIR)) {
+				writeFileSync(gitignorePath, `${content.trimEnd()}\n${WORKTREE_DIR}/\n`);
+				log("[gitignore]", `Added ${WORKTREE_DIR}/ to .gitignore`);
+			}
+		}
+	}
+}
+
+function createWorktree(issue: RankedIssue, opts: CLIOptions): string {
+	const wPath = worktreePath(issue);
+	const branch = branchName(issue);
+	const startPoint = resolveStartPoint(issue.targetBranch, issue.repoPath);
+
+	// Prune stale git worktree metadata before checking filesystem paths.
+	sh("git worktree prune", { cwd: issue.repoPath, silent: true });
+
+	// If this branch is already attached to another registered worktree, remove it.
+	// Skip removal if the existing worktree IS the path we intend to reuse (shared PRD).
+	try {
+		const porcelain = sh("git worktree list --porcelain", { cwd: issue.repoPath, silent: true });
+		const blocks = porcelain.split("\n\n").filter(Boolean);
+		for (const block of blocks) {
+			if (!block.includes(`branch refs/heads/${branch}`)) {
+				continue;
+			}
+
+			const worktreeLine = block
+				.split("\n")
+				.find((line) => line.startsWith("worktree "));
+			const registeredPath = worktreeLine?.replace("worktree ", "").trim();
+
+			// If the branch is already on the worktree we want, keep it (PRD reuse).
+			if (registeredPath && resolve(registeredPath) !== resolve(wPath)) {
+				try {
+					sh(`git worktree remove "${registeredPath}" --force`, { silent: true });
+					log("[worktree]", `Removed stale worktree for ${c.green}${branch}${c.reset}`);
+				} catch {
+					// Keep going and let regular branch cleanup handle leftovers.
+				}
+			}
+		}
+	} catch {
+		// Ignore parse/inspection errors.
+	}
+
+	if (existsSync(wPath)) {
+		log("[reuse]", `Worktree already exists for ${c.cyan}${issue.worktreeKey}${c.reset}`);
+		return wPath;
+	}
+
+	// Create branch from current HEAD.
+	try {
+		sh(`git branch -D "${branch}"`, { cwd: issue.repoPath, silent: true });
+	} catch {
+		// Branch does not exist; safe to ignore.
+	}
+
+	sh(`git worktree add "${wPath}" -b "${branch}" "${startPoint}"`, { cwd: issue.repoPath });
+	log("[worktree]", `Created worktree: ${c.dim}${wPath}${c.reset} -> ${c.green}${branch}${c.reset}`);
+
+	return wPath;
+}
+
+function prepareLiteralWorkspace(issue: RankedIssue, opts: CLIOptions): string {
+	const repoPath = issue.repoPath;
+	const branch = activeBranch(issue, opts);
+	const startPoint = resolveStartPoint(branch, repoPath);
+
+	sh(`git checkout -B "${branch}" "${startPoint}"`, { cwd: repoPath });
+	log("[checkout]", `Checked out ${c.green}${branch}${c.reset} from ${c.cyan}${startPoint}${c.reset}`);
+
+	return repoPath;
+}
+
+function prepareWorkspace(issue: RankedIssue, opts: CLIOptions): string {
+	if (opts.worktree) {
+		return createWorktree(issue, opts);
+	}
+
+	return prepareLiteralWorkspace(issue, opts);
+}
+
+function selectBatch(issues: RankedIssue[], maxParallel: number): RankedIssue[] {
+	const selected: RankedIssue[] = [];
+	const activeKeys = new Set<string>();
+
+	for (const issue of issues) {
+		const repoScopedKey = `${issue.repoFullName}:${issue.worktreeKey}`;
+		if (activeKeys.has(repoScopedKey)) {
+			continue;
+		}
+
+		selected.push(issue);
+		activeKeys.add(repoScopedKey);
+
+		if (selected.length >= maxParallel) {
+			break;
+		}
+	}
+
+	return selected;
+}
+
+function selectRunnableBatch(issues: RankedIssue[], opts: CLIOptions): RankedIssue[] {
+	return selectRunnableBatchWithLimit(issues, opts, opts.maxParallel);
+}
+
+function selectRunnableBatchWithLimit(issues: RankedIssue[], opts: CLIOptions, maxParallel: number): RankedIssue[] {
+	if (!opts.worktree) {
+		const selected: RankedIssue[] = [];
+		const activeRepos = new Set<string>();
+
+		for (const issue of issues) {
+			if (activeRepos.has(issue.repoFullName)) {
+				continue;
+			}
+
+			selected.push(issue);
+			activeRepos.add(issue.repoFullName);
+
+			if (selected.length >= maxParallel) {
+				break;
+			}
+		}
+
+		return selected;
+	}
+
+	return selectBatch(issues, maxParallel);
+}
+
+// ---------------------------------------------------------------------------
+// Phase 4: Prompt System
+// ---------------------------------------------------------------------------
+function loadPrompt(filePath: string): string {
+	const fullPath = resolve(ORCHESTRATOR_ROOT, filePath);
+	if (!existsSync(fullPath)) {
+		throw new Error(`Prompt file not found: ${fullPath}`);
+	}
+	return readFileSync(fullPath, "utf-8");
+}
+
+function interpolatePrompt(
+	template: string,
+	issue: RankedIssue,
+	branch: string,
+	extra?: Record<string, string>,
+	cwd?: string,
+): string {
+	let result = template
+		.replace(/\{\{ISSUE_TITLE\}\}/g, issue.title)
+		.replace(/\{\{ISSUE_BODY\}\}/g, issue.body ?? "(no body)")
+		.replace(/\{\{ISSUE_NUMBER\}\}/g, String(issue.number))
+		.replace(/\{\{BRANCH\}\}/g, branch);
+
+	if (extra) {
+		for (const [key, value] of Object.entries(extra)) {
+			result = result.replace(new RegExp(`\\{\\{${key}\\}\\}`, "g"), value);
+		}
+	}
+
+	// Expand shell directives: !`command` → command output
+	// Moved from copilot-agent.mjs to run on host (has git, gh, worktree context)
+	result = result.replace(/!\`([^`]+)\`/g, (_match: string, cmd: string) => {
+		const trimmedCmd = cmd.trim();
+		try {
+			return runDirectiveCommand(trimmedCmd, cwd) || "(no output)";
+		} catch (err: unknown) {
+			const e = err as { stdout?: Buffer | string };
+			return e?.stdout?.toString?.()?.trim?.() || `(command failed: ${trimmedCmd})`;
+		}
+	});
+
+	return result;
+}
+
+function ensureAgentOutputDir(wPath: string): string {
+	const agentDir = resolve(wPath, AGENT_OUTPUT_DIR);
+	if (!existsSync(agentDir)) {
+		mkdirSync(agentDir, { recursive: true });
+	}
+	return agentDir;
+}
+
+function saveStageOutput(wPath: string, filename: string, content: string): void {
+	const agentDir = ensureAgentOutputDir(wPath);
+	const filePath = resolve(agentDir, filename);
+	writeFileSync(filePath, content, "utf-8");
+	log("[save]", `Saved ${c.dim}${AGENT_OUTPUT_DIR}/${filename}${c.reset}`);
+}
+
+// ---------------------------------------------------------------------------
+// Phase 5: Pipeline Stage Runner (Copilot Agent via Docker)
+// ---------------------------------------------------------------------------
+type StageName = "plan" | "implement" | "review";
+const AGENT_STAGE_MARKER = "__FIFTTH_AGENT_STAGE__";
+
+interface IssuePipelineResult {
+	plan: StageResult;
+	implement?: StageResult;
+	review?: StageResult;
+}
+
+function failureStateFor(result: StageResult): IssueUiState {
+	return /timeout/i.test(result.errorText) ? "timed-out" : "failed";
+}
+
+function logSuccessfulStage(issue: RankedIssue, stage: StageName, result: StageResult, wPath: string): void {
+	switch (stage) {
+		case "plan":
+			saveStageOutput(wPath, `plan-${issue.number}.md`, result.output);
+			log("[ok]", `fiftth planning done #${issue.number}`);
+			break;
+		case "implement":
+			saveStageOutput(wPath, `implementation-${issue.number}.md`, result.output);
+			log("[ok]", `fiftth implementing done #${issue.number} (${result.writes} files changed)`);
+			break;
+		case "review":
+			saveStageOutput(wPath, `review-${issue.number}.md`, result.output);
+			log("[ok]", `fiftth reviewing done #${issue.number}`);
+			break;
+	}
+}
+
+function logFailedStage(issue: RankedIssue, stage: StageName, result: StageResult): void {
+	switch (stage) {
+		case "plan":
+			log("[fail]", `fiftth planning failed #${issue.number}`);
+			break;
+		case "implement":
+			log("[fail]", `fiftth implementing failed #${issue.number}`);
+			break;
+		case "review":
+			log("[fail]", `fiftth reviewing failed #${issue.number}`);
+			break;
+	}
+
+	if (result.errorText) {
+		log("[error]", result.errorText);
+	}
+}
+
+function runIssuePipeline(
+	issue: RankedIssue,
+	wPath: string,
+	opts: CLIOptions,
+	onStageStart?: (stage: StageName) => void,
+): Promise<IssuePipelineResult> {
+	const name = `${containerName(issue)}-pipeline`;
+
+	// Kill existing container with same name.
+	try {
+		docker(`rm -f ${name}`);
+	} catch {
+		// Container may not exist.
+	}
+
+	const planTemplate = loadPrompt(PROMPT_PLAN);
+	const implementTemplate = loadPrompt(PROMPT_IMPLEMENT);
+	const reviewTemplate = loadPrompt(PROMPT_REVIEW);
+	const branch = activeBranch(issue, opts);
+
+	const planPrompt = interpolatePrompt(planTemplate, issue, branch, undefined, wPath);
+	const implementPrompt = interpolatePrompt(implementTemplate, issue, branch, undefined, wPath);
+	const reviewPrompt = interpolatePrompt(reviewTemplate, issue, branch, undefined, wPath);
+
+	// Write prompts to files in the worktree so the container can read them.
+	const agentDir = ensureAgentOutputDir(wPath);
+	const planPromptFile = resolve(agentDir, `plan-prompt-${issue.number}.md`);
+	const implementPromptFile = resolve(agentDir, `implement-prompt-${issue.number}.md`);
+	const reviewPromptFile = resolve(agentDir, `review-prompt-${issue.number}.md`);
+	writeFileSync(planPromptFile, planPrompt, "utf-8");
+	writeFileSync(implementPromptFile, implementPrompt, "utf-8");
+	writeFileSync(reviewPromptFile, reviewPrompt, "utf-8");
+
+	// Git env vars for the container to use git inside Docker
+	const mainGitDir = resolve(issue.repoPath, ".git");
+	const worktreeName = issue.worktreeKey || `issue-${issue.number}`;
+	const gitDir = opts.worktree ? `/repo-git/worktrees/${worktreeName}` : "/repo-git";
+
+	return new Promise((resolvePromise) => {
+		const dockerArgs = [
+			"run",
+			"--name",
+			name,
+			"-e",
+			`GITHUB_TOKEN=${opts.ghToken}`,
+			"-e",
+			`GIT_DIR=${gitDir}`,
+			"-e",
+			`GIT_WORK_TREE=/workspace`,
+			"-v",
+			`${wPath}:/workspace`,
+			"-v",
+			`${mainGitDir}:/repo-git`,
+			"-w",
+			"/workspace",
+			DOCKER_IMAGE,
+			"--plan-prompt",
+			`/workspace/${AGENT_OUTPUT_DIR}/plan-prompt-${issue.number}.md`,
+			"--implement-prompt",
+			`/workspace/${AGENT_OUTPUT_DIR}/implement-prompt-${issue.number}.md`,
+			"--review-prompt",
+			`/workspace/${AGENT_OUTPUT_DIR}/review-prompt-${issue.number}.md`,
+			"--model",
+			opts.model,
+		];
+
+		if (opts.verbose) {
+			dockerArgs.push("--verbose");
+		}
+
+		const proc = spawn("docker", dockerArgs, {
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+
+		const stdoutChunks: string[] = [];
+		const stderrLines: string[] = [];
+		const logPrefix = `${c.dim}[#${issue.number}:pipeline]${c.reset}`;
+
+		proc.stdout?.on("data", (data: Buffer) => {
+			const text = data.toString();
+			stdoutChunks.push(text);
+		});
+
+		proc.stderr?.on("data", (data: Buffer) => {
+			const text = data.toString();
+			const lines = text.split("\n").filter(Boolean);
+			for (const line of lines) {
+				const clean = line.replace(/\r/g, "").trim();
+				if (!clean) continue;
+				const markerIndex = clean.indexOf(AGENT_STAGE_MARKER);
+				if (markerIndex >= 0) {
+					const payload = clean.slice(markerIndex + AGENT_STAGE_MARKER.length).trim();
+					const [stageName, eventName] = payload.split(":", 2) as [StageName, string | undefined];
+					if (eventName === "start") {
+						onStageStart?.(stageName);
+					}
+					continue;
+				}
+
+				stderrLines.push(clean);
+
+				if (opts.verbose) {
+					console.log(`${logPrefix} ${clean}`);
+				}
+			}
+		});
+
+		proc.on("close", (code) => {
+			const output = stdoutChunks.join("").trim();
+			const errorText = stderrLines.slice(-12).join("\n");
+			try {
+				docker(`rm -f ${name}`);
+			} catch {
+				// ignore
+			}
+
+			if (!output) {
+				resolvePromise({
+					plan: {
+						success: false,
+						output: "",
+						toolCalls: 0,
+						writes: 0,
+						errorText: errorText || `Pipeline container exited with code ${code ?? "unknown"}.`,
+					},
+				});
+				return;
+			}
+
+			try {
+				resolvePromise(JSON.parse(output) as IssuePipelineResult);
+			} catch {
+				resolvePromise({
+					plan: {
+						success: false,
+						output: output,
+						toolCalls: 0,
+						writes: 0,
+						errorText: errorText || "Failed to parse pipeline output from agent container.",
+					},
+				});
+			}
+		});
+
+		proc.on("error", (err) => {
+			log("[error]", `Failed to start pipeline for #${issue.number}: ${err.message}`);
+			resolvePromise({
+				plan: {
+					success: false,
+					output: "",
+					toolCalls: 0,
+					writes: 0,
+					errorText: err.message,
+				},
+			});
+		});
+	});
+}
+
+function commitOutstandingCodeChanges(issue: RankedIssue, wPath: string): void {
+	try {
+		const uncommitted = sh(`git status --porcelain`, { cwd: wPath, silent: true });
+		const codeChanges = uncommitted
+			.split("\n")
+			.filter((line) => line.trim() && !line.includes(".agent/"));
+		if (codeChanges.length > 0) {
+			log("[commit]", `Agent left ${codeChanges.length} uncommitted file(s) — committing from orchestrator`);
+			sh(`git add -A -- . ':!.agent'`, { cwd: wPath, silent: true });
+			sh(`git commit -m "RALPH: implement #${issue.number}: ${issue.title}"`, { cwd: wPath, silent: true });
+		}
+	} catch {
+		// If commit fails, proceed anyway — there may already be commits.
+	}
+}
+
+function finalizeSuccessfulIssue(issue: RankedIssue, wPath: string, opts: CLIOptions, reviewCompleted: boolean): void {
+	const branch = activeBranch(issue, opts);
+
+	commitOutstandingCodeChanges(issue, wPath);
+
+	if (opts.push) {
+		try {
+			sh(`git push origin ${branch} --force`, { cwd: wPath });
+			log("[push]", `pushed ${branch}`);
+
+			try {
+				const reviewStageLine = reviewCompleted
+					? "- [x] Review"
+					: "- [ ] Review (timed out locally after implementation)";
+				gh(
+					`pr create --head "${branch}" --title "Fix #${issue.number}: ${issue.title}" --body "Closes #${issue.number}\n\nAutomatically generated by the local Docker orchestrator using Copilot SDK.\n\n## Pipeline Stages\n- [x] Plan\n- [x] Implement\n${reviewStageLine}" --fill`,
+					issue.repoFullName,
+				);
+				log("[pr]", `created PR for #${issue.number}`);
+			} catch {
+				log("[warn]", `PR may already exist for #${issue.number}`);
+			}
+		} catch (err) {
+			log("[error]", `Failed to push/create PR for #${issue.number}: ${String(err)}`);
+		}
+	} else {
+		log("[hint]", `Use ${c.cyan}--push${c.reset} to push branch and create PR, or manually:`);
+		log(" ", `cd ${wPath} && git push origin ${branch}`);
+	}
+
+	cleanupIssueLabels(issue.number, issue.repoFullName);
+	markIssueDone(issue.number, issue.repoFullName);
+}
+
+function recoverTimedOutReview(issue: RankedIssue, wPath: string, opts: CLIOptions): boolean {
+	commitOutstandingCodeChanges(issue, wPath);
+
+	log("[warn]", `Review timed out for #${issue.number}, but implementation changes were detected. Finalizing issue to avoid reprocessing loop.`);
+	finalizeSuccessfulIssue(issue, wPath, opts, false);
+	return true;
+}
+
+interface RunningAgentResult {
+	issue: RankedIssue;
+	success: boolean;
+}
+
+function startAgentRun(
+	issue: RankedIssue,
+	opts: CLIOptions,
+	liveStates: Map<string, { label: string; state: IssueUiState }>,
+): Promise<RunningAgentResult> {
+	liveStates.set(issue.key, {
+		label: `${issue.repoFullName}#${issue.number}`,
+		state: "queued",
+	});
+
+	return runAgent(issue, opts, (currentIssueKey, state) => {
+		const previous = liveStates.get(currentIssueKey);
+		const nextLabel = previous?.label ?? currentIssueKey;
+		liveStates.set(currentIssueKey, {
+			label: nextLabel,
+			state,
+		});
+		emitIntegratedState(
+			currentIssueKey,
+			nextLabel,
+			state,
+			issue.repoFullName,
+			issue.worktreeKey,
+			issue.number,
+		);
+		refreshRunDashboard();
+	}).then((success) => ({ issue, success }));
+}
+
+async function waitForNextRunningAgent(
+	runningAgents: Map<string, Promise<RunningAgentResult>>,
+	liveStates: Map<string, { label: string; state: IssueUiState }>,
+	counts: { doneCount: number; failedCount: number },
+	opts: CLIOptions,
+	stats: { prdsOpen: number; unblockedCount: number },
+): Promise<boolean> {
+	const pending = [...runningAgents.values()];
+	if (pending.length === 0) {
+		return false;
+	}
+
+	const ticker = !runDashboardState.active ? startLiveTicker(() => {
+		const activeEntries = [...liveStates.values()]
+			.filter((entry) => entry.state === "planning" || entry.state === "implementing" || entry.state === "reviewing")
+			.slice(0, 2);
+		const active = activeEntries
+			.map((entry) => `${entry.label} ${uiStateLabel(entry.state)}`)
+			.join(" | ");
+		return `prds:${stats.prdsOpen} ready:${stats.unblockedCount} running:${activeEntries.length} done:${counts.doneCount} failed:${counts.failedCount}${active ? ` | ${active}` : ""}`;
+	}) : { stop: () => undefined };
+
+	let result: RunningAgentResult;
+	try {
+		result = await Promise.race(pending);
+	} finally {
+		ticker.stop();
+		if (!runDashboardState.active) {
+			process.stdout.write("\n");
+		}
+	}
+
+	runningAgents.delete(result.issue.key);
+	if (result.success) {
+		if (opts.worktree && !opts.push) {
+			log(
+				"[hint]",
+				`Keeping worktree for ${result.issue.worktreeKey} - review changes at: ${c.dim}${worktreePath(result.issue)}${c.reset}`,
+			);
+		}
+	}
+
+	log("[iter]", `issue ${result.issue.repoFullName}#${result.issue.number}: ${result.success ? "ok" : "fail"}`);
+	return result.success;
+}
+
+// ---------------------------------------------------------------------------
+// Phase 7: Run Agent (3-stage pipeline)
+// ---------------------------------------------------------------------------
+async function runAgent(
+	issue: RankedIssue,
+	opts: CLIOptions,
+	onStateChange?: (currentIssueKey: string, state: IssueUiState) => void,
+): Promise<boolean> {
+	const wPath = prepareWorkspace(issue, opts);
+	onStateChange?.(issue.key, "queued");
+
+	// Mark as in-progress.
+	try {
+		gh(`issue edit ${issue.number} --add-label "in-progress"`, issue.repoFullName);
+	} catch (err: unknown) {
+		const message = err instanceof Error ? err.message : String(err);
+		log("[warn]", `Could not add in-progress label to ${issue.repoFullName}#${issue.number}: ${message}`);
+	}
+
+	log("[start]", `${issue.worktreeKey} -> #${issue.number}`);
+
+	// Stage 1: Plan
+	log("[plan]", `fiftth planning #${issue.number}`);
+	onStateChange?.(issue.key, "planning");
+	const pipelineResult = await runIssuePipeline(issue, wPath, opts, (stage) => {
+		if (stage === "implement") {
+			log("[impl]", `fiftth implementing #${issue.number}`);
+			onStateChange?.(issue.key, "implementing");
+		}
+
+		if (stage === "review") {
+			log("[review]", `fiftth reviewing #${issue.number}`);
+			onStateChange?.(issue.key, "reviewing");
+		}
+	});
+	const planResult = pipelineResult.plan;
+	if (planResult.success) {
+		logSuccessfulStage(issue, "plan", planResult, wPath);
+	}
+	if (!planResult.success) {
+		const failedState = failureStateFor(planResult);
+		onStateChange?.(issue.key, failedState);
+		logFailedStage(issue, "plan", planResult);
+		log("[abort]", `Pipeline aborted at plan stage for #${issue.number}`);
+		afterAgentFailure(issue, issue.repoFullName);
+		return false;
+	}
+
+	// Stage 2: Implement
+	const implResult = pipelineResult.implement;
+	if (implResult?.success) {
+		logSuccessfulStage(issue, "implement", implResult, wPath);
+	}
+	if (!implResult.success) {
+		const failedState = failureStateFor(implResult);
+		onStateChange?.(issue.key, failedState);
+		logFailedStage(issue, "implement", implResult);
+		log("[abort]", `Pipeline aborted at implement stage for #${issue.number}`);
+		afterAgentFailure(issue, issue.repoFullName);
+		return false;
+	}
+
+	// Stage 3: Review
+	const reviewResult = pipelineResult.review;
+	if (reviewResult?.success) {
+		logSuccessfulStage(issue, "review", reviewResult, wPath);
+	}
+	if (!reviewResult.success) {
+		const failedState = failureStateFor(reviewResult);
+		if (failedState === "timed-out" && recoverTimedOutReview(issue, wPath, opts)) {
+			onStateChange?.(issue.key, "done");
+			log("[ok]", `fiftth done #${issue.number} after review timeout fallback`);
+			return true;
+		}
+		onStateChange?.(issue.key, failedState);
+		logFailedStage(issue, "review", reviewResult);
+		log("[abort]", `Pipeline aborted at review stage for #${issue.number}`);
+		afterAgentFailure(issue, issue.repoFullName);
+		return false;
+	}
+
+	onStateChange?.(issue.key, "done");
+	log("[ok]", `fiftth done #${issue.number}`);
+	afterAgentSuccess(issue, wPath, opts);
+	return true;
+}
+
+// ---------------------------------------------------------------------------
+// Phase 8: Post-Agent Handlers
+// ---------------------------------------------------------------------------
+function afterAgentSuccess(issue: RankedIssue, wPath: string, opts: CLIOptions): void {
+	finalizeSuccessfulIssue(issue, wPath, opts, true);
+}
+
+function afterAgentFailure(issue: RankedIssue, repo: string): void {
+	try {
+		gh(`issue edit ${issue.number} --remove-label "in-progress"`, repo);
+	} catch {
+		// ignore
+	}
+}
+
+function cleanupIssueLabels(issueNumber: number, repo: string): void {
+	try {
+		gh(`issue edit ${issueNumber} --remove-label "in-progress"`, repo);
+	} catch {
+		// ignore
+	}
+
+	try {
+		gh(`issue edit ${issueNumber} --remove-label "blocked"`, repo);
+	} catch {
+		// ignore
+	}
+}
+
+function markIssueDone(issueNumber: number, repo: string): void {
+	try {
+		gh(`issue edit ${issueNumber} --add-label "donne"`, repo);
+		log("[label]", `Added ${c.green}donne${c.reset} label to #${issueNumber}`);
+	} catch {
+		log("[warn]", `Could not add 'donne' label to #${issueNumber}`);
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Mode: Status
+// ---------------------------------------------------------------------------
+function showStatus(opts: CLIOptions): void {
+	currentUiMode = "run-minimal";
+	try {
+		const contexts = repositoryContextsForRun(opts);
+		opts.ghToken = validateGhCLI(opts.repo);
+		const issues = collectIssues(ORCHESTRATOR_LABEL, opts);
+
+		console.log();
+		console.log(`${c.bold}fiftth status${c.reset}`);
+		console.log(
+			`${c.dim}repo${c.reset} ${contexts.length === 1 ? contexts[0]!.repoFullName : `${contexts.length} repositories`}`,
+		);
+		console.log(`${c.dim}label${c.reset} ${ORCHESTRATOR_LABEL}`);
+
+		if (issues.length === 0) {
+			console.log();
+			console.log(`${c.green}no issues found${c.reset}`);
+			return;
+		}
+
+		const ranked = resolveDepGraph(issues);
+		printIssueTable(ranked);
+
+		console.log();
+		try {
+			const containers = sh(
+				`docker ps --filter "name=${CONTAINER_PREFIX}" --format "{{.Names}}\t{{.Status}}\t{{.RunningFor}}"`,
+				{ silent: true },
+			);
+
+			if (containers) {
+				console.log(`${c.bold}running containers${c.reset}`);
+				for (const line of containers.split("\n")) {
+					console.log(`  ${line}`);
+				}
+			} else {
+				console.log(`${c.dim}running containers${c.reset} none`);
+			}
+		} catch {
+			console.log(`${c.dim}running containers${c.reset} none`);
+		}
+
+		console.log();
+		try {
+			const orchestratorTrees = contexts.flatMap((context) => {
+				const worktrees = sh("git worktree list", { cwd: context.repoPath, silent: true });
+				return worktrees
+					.split("\n")
+					.filter((line) => line.includes(WORKTREE_DIR))
+					.map((line) => `${context.repoFullName}: ${line}`);
+			});
+
+			if (orchestratorTrees.length > 0) {
+				console.log(`${c.bold}active worktrees${c.reset}`);
+				for (const line of orchestratorTrees) {
+					console.log(`  ${c.dim}${line}${c.reset}`);
+				}
+			} else {
+				console.log(`${c.dim}active worktrees${c.reset} none`);
+			}
+		} catch {
+			console.log(`${c.dim}active worktrees${c.reset} none`);
+		}
+	} finally {
+		currentUiMode = "default";
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Mode: Cleanup
+// ---------------------------------------------------------------------------
+async function cleanup(opts: CLIOptions): Promise<void> {
+	header("CLEANUP");
+	const contexts = repositoryContextsForRun(opts);
+
+	const ok = await confirm("Remove all orchestrator worktrees and containers?");
+	if (!ok) {
+		log("[stop]", "Cancelled.");
+		return;
+	}
+
+	try {
+		const containers = sh(`docker ps -a --filter "name=${CONTAINER_PREFIX}" --format "{{.Names}}"`, {
+			silent: true,
+		});
+		if (containers) {
+			for (const name of containers.split("\n").filter(Boolean)) {
+				try {
+					docker(`rm -f ${name}`);
+					log("[delete]", `Removed container: ${name}`);
+				} catch {
+					// ignore
+				}
+			}
+		}
+	} catch {
+		// no containers
+	}
+
+	for (const context of contexts) {
+		try {
+			const worktrees = sh("git worktree list --porcelain", { cwd: context.repoPath, silent: true });
+			const paths = worktrees
+				.split("\n")
+				.filter((line) => line.startsWith("worktree "))
+				.map((line) => line.replace("worktree ", ""))
+				.filter((worktreePathValue) => worktreePathValue.includes(WORKTREE_DIR));
+
+			for (const wPath of paths) {
+				try {
+					sh(`git worktree remove "${wPath}" --force`, { cwd: context.repoPath });
+					log("[delete]", `Removed worktree: ${context.repoFullName}/${basename(wPath)}`);
+				} catch {
+					// ignore
+				}
+			}
+
+			sh("git worktree prune", { cwd: context.repoPath, silent: true });
+		} catch {
+			// no worktrees for this repo
+		}
+	}
+	log("[ok]", "Cleanup complete");
+}
+
+// ---------------------------------------------------------------------------
+// Mode: Reset Labels
+// ---------------------------------------------------------------------------
+async function resetLabels(opts: CLIOptions): Promise<void> {
+	header("RESET LABELS");
+
+	const issues = collectIssues(ORCHESTRATOR_LABEL, opts);
+	if (issues.length === 0) {
+		log("[ok]", "No issues found.");
+		return;
+	}
+
+	const ok = await confirm(`Remove in-progress/blocked labels from ${issues.length} issues?`);
+	if (!ok) {
+		log("[stop]", "Cancelled.");
+		return;
+	}
+
+	for (const issue of issues) {
+		cleanupIssueLabels(issue.number, issue.repoFullName);
+		log("[reset]", `Reset labels on ${issue.repoFullName}#${issue.number}`);
+	}
+
+	log("[ok]", "All labels reset");
+}
+
+// ---------------------------------------------------------------------------
+// Issue Table
+// ---------------------------------------------------------------------------
+function printIssueTable(ranked: RankedIssue[]): void {
+	const colNum = 6;
+	const colPri = 12;
+	const colStatus = 14;
+	const colDeps = 16;
+	const colTitle = 40;
+
+	const padR = (s: string, len: number) => {
+		const plain = s.replace(/\x1b\[[0-9;]*m/g, "");
+		return s + " ".repeat(Math.max(0, len - plain.length));
+	};
+
+	const headerRow = `${padR("#", colNum)} ${padR("Priority", colPri)} ${padR("Status", colStatus)} ${padR("Deps", colDeps)} ${padR("Title", colTitle)}`;
+	const separator = "-".repeat(colNum + colPri + colStatus + colDeps + colTitle + 4);
+
+	console.log();
+	console.log(`${c.bold}${headerRow}${c.reset}`);
+	console.log(separator);
+
+	for (const issue of ranked) {
+		const num = `#${issue.number}`;
+		const pri = `P${issue.priority}`;
+		const priColor =
+			issue.priority === 0 ? c.red : issue.priority === 1 ? c.yellow : issue.priority === 2 ? c.blue : c.dim;
+
+		let status: string;
+		if (issue.isInProgress) {
+			status = `${c.magenta}in-progress${c.reset}`;
+		} else if (issue.isBlocked) {
+			status = `${c.yellow}blocked${c.reset}`;
+		} else {
+			status = `${c.green}ready${c.reset}`;
+		}
+
+		const deps = issue.dependsOn.length > 0 ? issue.dependsOn.map((d) => `#${d}`).join(", ") : `${c.dim}none${c.reset}`;
+		const title = issue.title.length > colTitle - 2 ? issue.title.slice(0, colTitle - 5) + "..." : issue.title;
+
+		console.log(
+			`${padR(num, colNum)} ${padR(`${priColor}${pri}${c.reset}`, colPri + 9)} ${padR(status, colStatus + 9)} ${padR(deps, colDeps)} ${title}`,
+		);
+	}
+
+	console.log();
+}
+
+// ---------------------------------------------------------------------------
+// Main: Run Loop
+// ---------------------------------------------------------------------------
+async function runLoop(opts: CLIOptions): Promise<void> {
+	// validateGhCLI uses gh keyring — no env tokens needed
+	opts.ghToken = validateGhCLI(opts.repo);
+	currentUiMode = opts.verbose ? "run-verbose" : "run-minimal";
+
+	ensureLabelsForRun(opts);
+	ensureDockerImage();
+	for (const context of repositoryContextsForRun(opts)) {
+		ensureWorktreeDir(context.repoPath);
+	}
+
+	let selectedPrdKeys: Set<string> | null = null;
+	let askedForPrdSelection = false;
+	let doneCount = 0;
+	let failedCount = 0;
+	const liveStates = new Map<string, { label: string; state: IssueUiState }>();
+	const runningAgents = new Map<string, Promise<RunningAgentResult>>();
+	runDashboardState.liveStates = liveStates;
+
+	printRunIntro(opts);
+
+	for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
+		const issues = collectIssues(ORCHESTRATOR_LABEL, opts);
+		if (issues.length === 0) {
+			log("[ok]", "No more orchestrator issues. All done!");
+			break;
+		}
+
+		const rankedAll = resolveDepGraph(issues);
+		const prdKeys = [...new Set(rankedAll.map((i) => i.worktreeKey).filter((k) => k.startsWith("prd-")))];
+
+		if (opts.prd !== null) {
+			selectedPrdKeys = new Set([`prd-${opts.prd}`]);
+			askedForPrdSelection = true;
+		}
+
+		if (
+			opts.repositoryContexts.length === 0 &&
+			!opts.allPrds &&
+			opts.prd === null &&
+			!askedForPrdSelection &&
+			prdKeys.length > 1
+		) {
+			if (runDashboardState.active) {
+				stopRunDashboard(false);
+			}
+			const picked = await pickPrdKey(prdKeys);
+			if (currentUiMode === "run-minimal") {
+				startRunDashboard(opts);
+			}
+			askedForPrdSelection = true;
+			if (picked === null) {
+				log("[stop]", "Cancelled by user.");
+				break;
+			}
+			if (picked !== "all") {
+				selectedPrdKeys = new Set([picked]);
+			}
+		}
+
+		let ranked = rankedAll;
+		if (selectedPrdKeys && selectedPrdKeys.size > 0) {
+			ranked = rankedAll.filter((i) => selectedPrdKeys!.has(i.worktreeKey));
+		}
+
+		if (opts.verbose) {
+			header(`Iteration ${iteration}/${MAX_ITERATIONS}`);
+			printIssueTable(ranked);
+		}
+
+		if (ranked.length === 0) {
+			log("[wait]", "No issues matched current PRD scope.");
+			break;
+		}
+
+		const unblocked = ranked.filter((i) => !i.isBlocked && !i.isInProgress);
+		const blocked = ranked.filter((i) => i.isBlocked);
+		const inProgress = ranked.filter((i) => i.isInProgress);
+		const prdsOpen = new Set(ranked.map((i) => i.worktreeKey).filter((k) => k.startsWith("prd-"))).size;
+
+		runDashboardState.statsLine = `prds:${prdsOpen} ready:${unblocked.length} blocked:${blocked.length} running:${inProgress.length} done:${doneCount} failed:${failedCount}`;
+		refreshRunDashboard();
+		log("[stats]", runDashboardState.statsLine);
+
+		const availableSlots = Math.max(opts.maxParallel - runningAgents.size, 0);
+
+		if (unblocked.length === 0 || availableSlots === 0) {
+			if (runningAgents.size > 0) {
+				log("[wait]", "Waiting for a running issue to free a slot...");
+				await waitForNextRunningAgent(
+					runningAgents,
+					liveStates,
+					{ doneCount, failedCount },
+					opts,
+					{ prdsOpen, unblockedCount: unblocked.length },
+				).then((succeeded) => {
+					if (succeeded) {
+						doneCount += 1;
+					} else {
+						failedCount += 1;
+					}
+				});
+				continue;
+			}
+
+			if (inProgress.length > 0) {
+				log("[wait]", "All remaining issues are blocked or in-progress. Waiting...");
+			} else {
+				log("[pause]", "All issues are blocked. Nothing can proceed.");
+			}
+			break;
+		}
+
+		const batch = selectRunnableBatchWithLimit(unblocked, opts, availableSlots);
+
+		if (batch.length === 0) {
+			if (runningAgents.size > 0) {
+				log("[wait]", "No runnable slot available yet. Waiting for an active issue...");
+				await waitForNextRunningAgent(
+					runningAgents,
+					liveStates,
+					{ doneCount, failedCount },
+					opts,
+					{ prdsOpen, unblockedCount: unblocked.length },
+				).then((succeeded) => {
+					if (succeeded) {
+						doneCount += 1;
+					} else {
+						failedCount += 1;
+					}
+				});
+				continue;
+			}
+
+			log("[pause]", "No runnable issues could be scheduled.");
+			break;
+		}
+
+		log("[run]", `launching ${batch.length} issue(s)`);
+		for (const issue of batch) {
+			runningAgents.set(issue.key, startAgentRun(issue, opts, liveStates));
+		}
+
+		await waitForNextRunningAgent(
+			runningAgents,
+			liveStates,
+			{ doneCount, failedCount },
+			opts,
+			{ prdsOpen, unblockedCount: unblocked.length },
+		).then((succeeded) => {
+			if (succeeded) {
+				doneCount += 1;
+			} else {
+				failedCount += 1;
+			}
+		});
+	}
+
+	while (runningAgents.size > 0) {
+		await waitForNextRunningAgent(
+			runningAgents,
+			liveStates,
+			{ doneCount, failedCount },
+			opts,
+			{ prdsOpen: 0, unblockedCount: 0 },
+		).then((succeeded) => {
+			if (succeeded) {
+				doneCount += 1;
+			} else {
+				failedCount += 1;
+			}
+		});
+	}
+
+	if (!runDashboardState.active) {
+		console.log();
+	}
+	log("[done]", "Orchestrator finished.");
+	stopRunDashboard();
+	currentUiMode = "default";
+}
+
+// ---------------------------------------------------------------------------
+// Entry Point
+// ---------------------------------------------------------------------------
+async function main(): Promise<void> {
+	const opts = parseArgs();
+
+	switch (opts.mode) {
+		case "status":
+			showStatus(opts);
+			break;
+		case "cleanup":
+			await cleanup(opts);
+			break;
+		case "reset":
+			await resetLabels(opts);
+			break;
+		case "run":
+			await runLoop(opts);
+			break;
+	}
+}
+
+main().catch((err) => {
+	console.error(`${c.red}Fatal error:${c.reset}`, err);
+	process.exit(1);
+});
+