@backburner/cli 0.1.0

package/dist/src/cli/commands/tui.js

@@ -0,0 +1,187 @@
+import * as path from "node:path";
+import { loadConfig } from "../../config/loader.js";
+import { StateStore } from "../../state/loader.js";
+import { defaultBackburnerManagementRoot, defaultBackburnerOutputsRoot, resolveOutputsLogsRoot, resolveOutputsStateRoot } from "../../utils/paths.js";
+import { RuntimeStatusTracker, TuiScreen } from "../tui/index.js";
+import { readIntervalMs, readOptionalStringFlag, readStringFlag } from "../options.js";
+import { runCli } from "./run.js";
+export function shouldUseRuntimeStatusScreen(rest) {
+    return Boolean(process.stdout.isTTY &&
+        process.stdin.isTTY &&
+        !rest.includes("--headless") &&
+        !rest.includes("--once"));
+}
+export class SerializedCycleRunner {
+    runCycleFn;
+    scheduleNextCycleFn;
+    onRunningChange;
+    running = false;
+    refreshRequested = false;
+    stopped = false;
+    timer;
+    constructor(runCycleFn, scheduleNextCycleFn, onRunningChange) {
+        this.runCycleFn = runCycleFn;
+        this.scheduleNextCycleFn = scheduleNextCycleFn;
+        this.onRunningChange = onRunningChange;
+    }
+    clearTimer() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+    }
+    async run(reason) {
+        if (this.running) {
+            if (reason === "manual") {
+                this.refreshRequested = true;
+            }
+            return;
+        }
+        // A real cycle is starting, so any pending scheduled wakeup is stale.
+        this.clearTimer();
+        this.running = true;
+        if (this.onRunningChange)
+            this.onRunningChange(true, reason);
+        try {
+            await this.runCycleFn();
+        }
+        finally {
+            this.running = false;
+            if (this.onRunningChange)
+                this.onRunningChange(false, reason);
+            if (this.stopped)
+                return;
+            if (this.refreshRequested) {
+                this.refreshRequested = false;
+                void this.run("manual");
+                return;
+            }
+            this.scheduleNextCycleFn();
+        }
+    }
+    stop() {
+        this.stopped = true;
+        this.clearTimer();
+    }
+    setTimer(timer) {
+        this.clearTimer();
+        this.timer = timer;
+    }
+    isStopped() {
+        return this.stopped;
+    }
+}
+export async function runInteractiveTui(argv) {
+    const rest = argv.filter((arg) => arg !== "run");
+    const managementDir = path.resolve(readStringFlag(rest, "--management-dir", defaultBackburnerManagementRoot()));
+    let repoCount = 0;
+    let initialConfig = null;
+    try {
+        initialConfig = await loadConfig(managementDir);
+        repoCount = initialConfig.repos.filter((r) => r.enabled).length;
+    }
+    catch {
+        // Config load error will be captured in runCycle
+    }
+    const tracker = new RuntimeStatusTracker(repoCount);
+    if (initialConfig) {
+        tracker.setConfigs(initialConfig.mcps, initialConfig.capabilities, initialConfig.maxConcurrentAgents);
+    }
+    const intervalMs = readIntervalMs(rest);
+    tracker.setIntervalMs(intervalMs);
+    // Load initial state for the explorer immediately on start
+    try {
+        const outputsDir = path.resolve(readOptionalStringFlag(rest, "--outputs-dir") ?? defaultBackburnerOutputsRoot());
+        const stateDir = path.resolve(resolveOutputsStateRoot(outputsDir));
+        const logDir = path.resolve(resolveOutputsLogsRoot(outputsDir));
+        const stateStore = new StateStore({ stateDir, executionDir: logDir });
+        const state = await stateStore.load();
+        tracker.setState(state);
+    }
+    catch {
+        // Ignore initial state load errors
+    }
+    const runCycle = async () => {
+        const silentLogger = {
+            info: () => { },
+            warn: () => { },
+            error: () => { }
+        };
+        try {
+            const currentCycleNo = tracker.getModel().cycleNo === "—" ? 1 : Number(tracker.getModel().cycleNo) + 1;
+            const summary = await runCli(["run", ...rest], {
+                statusTracker: tracker,
+                logger: silentLogger,
+                cycleNo: currentCycleNo
+            });
+            const outputsDir = path.resolve(readOptionalStringFlag(rest, "--outputs-dir") ?? defaultBackburnerOutputsRoot());
+            const stateDir = path.resolve(resolveOutputsStateRoot(outputsDir));
+            const logDir = path.resolve(resolveOutputsLogsRoot(outputsDir));
+            const stateStore = new StateStore({ stateDir, executionDir: logDir });
+            const state = await stateStore.load();
+            try {
+                const config = await loadConfig(managementDir);
+                tracker.setConfigs(config.mcps, config.capabilities, config.maxConcurrentAgents);
+                tracker.setConfigReloadError(null);
+            }
+            catch (err) {
+                tracker.setConfigReloadError(err);
+            }
+            tracker.onCycleSuccess(summary, state);
+        }
+        catch (error) {
+            tracker.onCycleFailure(error);
+        }
+    };
+    let screen;
+    let runner;
+    const scheduleNextCycle = () => {
+        if (runner.isStopped())
+            return;
+        tracker.setNextCycleAt(Date.now() + intervalMs);
+        const timer = setTimeout(() => {
+            void runner.run("scheduled");
+        }, intervalMs);
+        runner.setTimer(timer);
+    };
+    const shutdown = () => {
+        runner.stop();
+        screen.exit();
+    };
+    const onQuit = () => {
+        shutdown();
+        process.exit(0);
+    };
+    screen = new TuiScreen(tracker, async () => {
+        await runner.run("manual");
+    }, onQuit);
+    runner = new SerializedCycleRunner(runCycle, scheduleNextCycle, (running, reason) => {
+        if (running) {
+            tracker.setNextCycleAt(0);
+        }
+        if (reason === "manual") {
+            screen.setRefreshing(running);
+        }
+    });
+    const sigintHandler = () => {
+        shutdown();
+        process.exit(130);
+    };
+    const sigtermHandler = () => {
+        shutdown();
+        process.exit(143);
+    };
+    process.once("SIGINT", sigintHandler);
+    process.once("SIGTERM", sigtermHandler);
+    try {
+        screen.start();
+        void runner.run("initial");
+        // Keep process alive
+        await new Promise(() => { });
+    }
+    finally {
+        process.off("SIGINT", sigintHandler);
+        process.off("SIGTERM", sigtermHandler);
+        shutdown();
+    }
+}

package/dist/src/cli/dispatcher.js

@@ -0,0 +1,51 @@
+import { formatRunSummary } from "./output.js";
+import { CliUsageError } from "./errors.js";
+import { runBrokerCli } from "./commands/broker.js";
+import { runBrokerSmokeCli } from "./commands/broker-smoke.js";
+import { runInitCommand } from "./commands/init.js";
+import { runJournalCli } from "./commands/journal.js";
+import { runCli } from "./commands/run.js";
+import { runLoopCli } from "./commands/run-loop.js";
+import { runInteractiveTui, shouldUseRuntimeStatusScreen } from "./commands/tui.js";
+const usage = 'Expected command: backburner run [--code-root <path>] [--management-dir <path>] [--outputs-dir <path>] [--log-dir <path>] [--broker-port <port>] [--headless] [--once] | run-loop ... | broker ... | broker-smoke ... | init [--code-root <path>] [--management-dir <path>] [--outputs-dir <path>] [--log-dir <path>] [--workspaces-dir <path>] [--yes] | journal [--outputs-dir <path>] [--repo <id>] [--workstream <id>] [--issue <n>] [--pr <n>] [--since <ISO>] [--last <n>] [--json] [--verbose]';
+export async function main(argv = process.argv.slice(2)) {
+    const [command, ...rest] = argv;
+    if (command === "--help" || command === "-h" || command === "help") {
+        process.stdout.write(`${usage}\n`);
+        return;
+    }
+    if (command === "run") {
+        if (shouldUseRuntimeStatusScreen(rest)) {
+            await runInteractiveTui([command, ...rest]);
+            return;
+        }
+        const summary = await runCli([command, ...rest]);
+        process.stdout.write(formatRunSummary(summary));
+        return;
+    }
+    if (command === "run-loop") {
+        if (shouldUseRuntimeStatusScreen(rest)) {
+            await runInteractiveTui(["run", ...rest]);
+            return;
+        }
+        await runLoopCli([command, ...rest]);
+        return;
+    }
+    if (command === "broker") {
+        await runBrokerCli(rest);
+        return;
+    }
+    if (command === "broker-smoke") {
+        await runBrokerSmokeCli(rest);
+        return;
+    }
+    if (command === "init") {
+        await runInitCommand(rest);
+        return;
+    }
+    if (command === "journal") {
+        await runJournalCli(rest);
+        return;
+    }
+    throw new CliUsageError(usage);
+}

package/dist/src/cli/errors.js

@@ -0,0 +1,2 @@
+export class CliUsageError extends Error {
+}

package/dist/src/cli/init.js

@@ -0,0 +1,92 @@
+import * as path from "node:path";
+import { ExecFileCommandRunner } from "../utils/command-runner.js";
+import { defaultBackburnerCodeRoot, defaultBackburnerManagementRoot, defaultBackburnerOutputsRoot, defaultWorkspacesRootForCodeRoot } from "../utils/paths.js";
+import { OnboardingEngine } from "../onboarding/engine.js";
+import { NodeReadlinePrompter, NonInteractivePrompter } from "../onboarding/prompt.js";
+import { WelcomeStep } from "../onboarding/steps/welcome.js";
+import { CheckRequirementsStep } from "../onboarding/steps/check-requirements.js";
+import { CheckGitHubAuthStep } from "../onboarding/steps/check-github-auth.js";
+import { DiscoverReposStep } from "../onboarding/steps/discover-repos.js";
+import { SelectReposStep } from "../onboarding/steps/select-repos.js";
+import { ConfigurePathsStep } from "../onboarding/steps/configure-paths.js";
+import { DiscoverProvidersStep } from "../onboarding/steps/discover-providers.js";
+import { ConfigureModelsStep } from "../onboarding/steps/configure-models.js";
+import { GenerateConfigStep } from "../onboarding/steps/generate-config.js";
+import { ReadinessValidationStep } from "../onboarding/steps/readiness-validation.js";
+import { ShowSummaryStep } from "../onboarding/steps/show-summary.js";
+export async function runInitCli(argv) {
+    const codeRoot = readStringFlag(argv, "--code-root") ?? defaultBackburnerCodeRoot();
+    const managementDir = readStringFlag(argv, "--management-dir");
+    const outputsDir = readStringFlag(argv, "--outputs-dir");
+    const logDir = readStringFlag(argv, "--log-dir");
+    const workspacesDir = readStringFlag(argv, "--workspaces-dir");
+    const nonInteractive = argv.includes("--yes") || argv.includes("-y");
+    const result = await runInit({
+        codeRoot,
+        ...(managementDir !== undefined ? { managementDir } : {}),
+        ...(outputsDir !== undefined ? { outputsDir } : {}),
+        ...(logDir !== undefined ? { logDir } : {}),
+        ...(workspacesDir !== undefined ? { workspacesDir } : {}),
+        nonInteractive
+    });
+    // Let the summary print first, then signal failure via exit code.
+    if (result.overallStatus === "failed" || result.overallStatus === "requiresUserAction") {
+        process.exitCode = 1;
+    }
+}
+export async function runInit(options) {
+    const commandRunner = new ExecFileCommandRunner();
+    const { codeRoot, nonInteractive = false } = options;
+    const resolvedCodeRoot = path.resolve(codeRoot);
+    const resolvedOutputsDir = path.resolve(options.outputsDir ?? defaultBackburnerOutputsRoot());
+    const ctx = {
+        codeRoot: resolvedCodeRoot,
+        managementDir: path.resolve(options.managementDir ?? defaultBackburnerManagementRoot()),
+        outputsDir: resolvedOutputsDir,
+        logDir: path.resolve(options.logDir ?? path.join(resolvedOutputsDir, "logs")),
+        workspacesDir: path.resolve(options.workspacesDir ?? defaultWorkspacesRootForCodeRoot(resolvedCodeRoot)),
+        discoveredRepos: [],
+        selectedRepos: [],
+        discoveredProviders: [],
+        warnings: [],
+        stepResults: new Map()
+    };
+    const steps = [
+        new WelcomeStep(),
+        new CheckRequirementsStep(commandRunner),
+        new CheckGitHubAuthStep(commandRunner),
+        new DiscoverReposStep(commandRunner, ctx.codeRoot),
+        new SelectReposStep(),
+        new ConfigurePathsStep(),
+        new DiscoverProvidersStep(commandRunner),
+        new ConfigureModelsStep(),
+        new GenerateConfigStep(),
+        new ReadinessValidationStep(commandRunner),
+        new ShowSummaryStep()
+    ];
+    let prompter;
+    let interactivePrompter;
+    if (nonInteractive) {
+        prompter = new NonInteractivePrompter();
+    }
+    else {
+        interactivePrompter = new NodeReadlinePrompter();
+        prompter = interactivePrompter;
+    }
+    const engine = new OnboardingEngine(steps, prompter);
+    try {
+        return await engine.run(ctx);
+    }
+    finally {
+        interactivePrompter?.close();
+    }
+}
+function readStringFlag(argv, flag) {
+    const index = argv.indexOf(flag);
+    if (index < 0)
+        return undefined;
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith("--"))
+        return undefined;
+    return value;
+}

package/dist/src/cli/options.js

@@ -0,0 +1,86 @@
+import { CliUsageError } from "./errors.js";
+export const DEFAULT_GITHUB_BROKER_PORT = 4444;
+export const DEFAULT_RUN_LOOP_INTERVAL_MS = 5 * 60 * 1000;
+export function readStringFlag(argv, flag, fallback) {
+    const index = argv.indexOf(flag);
+    if (index === -1) {
+        return fallback;
+    }
+    const value = argv[index + 1];
+    if (!value) {
+        throw new CliUsageError(`Missing value for ${flag}`);
+    }
+    return value;
+}
+export function readOptionalStringFlag(argv, flag) {
+    const index = argv.indexOf(flag);
+    if (index === -1) {
+        return undefined;
+    }
+    const value = argv[index + 1];
+    if (!value) {
+        throw new CliUsageError(`Missing value for ${flag}`);
+    }
+    return value;
+}
+export function readNumberFlag(argv, flag, fallback) {
+    const value = readOptionalStringFlag(argv, flag);
+    if (value === undefined) {
+        return fallback;
+    }
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new CliUsageError(`${flag} must be a non-negative integer`);
+    }
+    return parsed;
+}
+export function readIntervalMs(argv) {
+    const seconds = readOptionalNumberFlag(argv, "--interval-seconds");
+    const minutes = readOptionalNumberFlag(argv, "--interval-minutes");
+    if (seconds !== undefined && minutes !== undefined) {
+        throw new CliUsageError("Use only one of --interval-seconds or --interval-minutes");
+    }
+    if (seconds !== undefined) {
+        return seconds * 1000;
+    }
+    if (minutes !== undefined) {
+        return minutes * 60 * 1000;
+    }
+    return DEFAULT_RUN_LOOP_INTERVAL_MS;
+}
+export function readOptionalNumberFlag(argv, flag) {
+    const value = readOptionalStringFlag(argv, flag);
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new CliUsageError(`${flag} must be a positive integer`);
+    }
+    return parsed;
+}
+export async function delayWithAbort(ms, signal) {
+    if (signal.aborted) {
+        throw createAbortError();
+    }
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", onAbort);
+            reject(createAbortError());
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+export function createAbortError() {
+    const error = new Error("Aborted");
+    error.name = "AbortError";
+    return error;
+}
+export function isAbortError(error) {
+    return error instanceof Error && error.name === "AbortError";
+}

package/dist/src/cli/output.js

@@ -0,0 +1,231 @@
+import { recommendBranchSyncAction } from "../workstreams/branch-sync.js";
+import { buildPacketLifecycleWorkstreamReport, formatPacketLifecycleReport } from "../workstreams/packet-lifecycle-report.js";
+export function formatRunSummary(summary) {
+    const lines = [
+        `Orchestrator run ${summary.failedRepoCount > 0 || summary.failedTaskCount > 0 ? "finished with failures" : "completed successfully"}.`,
+        `Code root: ${summary.codeRoot}`,
+        `Management dir: ${summary.managementDir}`,
+        `Outputs dir: ${summary.outputsDir}`,
+        `State dir: ${summary.stateDir}`,
+        `Log dir: ${summary.logDir}`,
+        `Time: ${summary.startedAt} -> ${summary.completedAt}`,
+        `Repos: ${summary.repoCount} enabled, ${summary.syncedRepoCount} synced, ${summary.failedRepoCount} failed sync, ${summary.scannedRepoCount} scanned, ${summary.partiallyScannedRepoCount} partial scan, ${summary.failedScanRepoCount} failed scan`,
+        `Entities: ${summary.issueCount} issues, ${summary.pullRequestCount} PRs, ${summary.commentCount} comments`,
+        `Tasks: ${summary.taskCount} tracked, ${summary.pendingTaskCount} pending, ${summary.completedTaskCount} completed, ${summary.failedTaskCount} failed`,
+        `Product discovery: ${summary.productDiscoveryCount ?? 0}`,
+        `Product specification: ${summary.productSpecificationCount ?? 0}`,
+        `Waiting for product approval: ${summary.waitingForProductApprovalCount ?? 0}`,
+        `Executions: ${summary.executionCount}`,
+        "",
+        "GitOps:",
+        `- Management: ${formatManagementGitOps(summary.managementGitOps)}`,
+        `- Outputs: ${formatOutputsGitOps(summary.outputsGitOps)}`,
+        "",
+        "Repo results:"
+    ];
+    for (const result of summary.results) {
+        lines.push(formatRepoResult(result));
+    }
+    if (summary.pullRequestBaseClassifications.length > 0) {
+        lines.push("");
+        lines.push("Pull request base classifications:");
+        for (const classification of summary.pullRequestBaseClassifications) {
+            if (classification.kind === "top_level") {
+                lines.push(`- ${classification.repoSlug} PR #${classification.pullRequestNumber} targets default branch \`${classification.defaultBranch}\`.`);
+            }
+            else {
+                lines.push(`- ${classification.repoSlug} PR #${classification.pullRequestNumber} targets non-default parent branch \`${classification.baseBranch}\`; repo default branch is \`${classification.defaultBranch}\`.`);
+            }
+        }
+    }
+    if (summary.packetPullRequestCandidates.length > 0) {
+        lines.push("");
+        lines.push("Packet PR candidates:");
+        for (const candidate of summary.packetPullRequestCandidates) {
+            if (candidate.status === "matched_parent_workstream") {
+                lines.push(`- ${candidate.repoSlug} PR #${candidate.pullRequestNumber} targets parent branch \`${candidate.baseBranch}\` and is attached to workstream \`${candidate.parentWorkstreamId}\`.`);
+            }
+            else {
+                lines.push(`- ${candidate.repoSlug} PR #${candidate.pullRequestNumber} targets non-default parent branch \`${candidate.baseBranch}\` but no active parent workstream was found.`);
+            }
+        }
+    }
+    if (summary.parentBranchSyncPreflights.length > 0) {
+        lines.push("");
+        lines.push("Parent branch sync preflights:");
+        for (const item of summary.parentBranchSyncPreflights) {
+            const preflight = item.preflight;
+            const parentPr = preflight.parentPrNumber !== undefined ? `#${preflight.parentPrNumber}` : "unknown";
+            lines.push(`- ${preflight.workstreamId}: sync \`${preflight.parentIntegrationBranch}\` from \`${preflight.defaultBranch}\` after wave ${preflight.currentWaveIndex} before wave ${preflight.nextWaveIndex}`);
+            lines.push(`  status: ${formatBranchSyncComparison(item)}`);
+            lines.push(`  recommendation: ${formatBranchSyncRecommendation(item)}`);
+            lines.push(`  parent PR: ${parentPr}`);
+            lines.push(`  completed packets: ${formatPacketIds(preflight.completedPacketIds)}`);
+            lines.push(`  pending future packets: ${formatPacketIds(preflight.pendingFuturePacketIds)}`);
+        }
+    }
+    const nextWaveReadyPreflights = collectNextWaveReadyPreflights(summary);
+    if (nextWaveReadyPreflights.length > 0) {
+        lines.push("");
+        lines.push("Next wave readiness:");
+        for (const item of nextWaveReadyPreflights) {
+            lines.push(...formatNextWaveReadyPreflight(item));
+        }
+    }
+    if (summary.packetPlans.length > 0) {
+        lines.push("");
+        lines.push("Multi-wave packet lifecycle:");
+        for (const plan of summary.packetPlans) {
+            const report = buildPacketLifecycleWorkstreamReport({
+                workstream: {
+                    id: plan.workstreamId,
+                    repoKey: plan.repoKey,
+                    integration: plan.parentPrNumber ? { branchName: "unknown", prNumber: plan.parentPrNumber } : undefined,
+                    packetPlan: {
+                        status: plan.status,
+                        packets: Object.fromEntries(plan.waves.flatMap(w => w.packets).map(p => [p.id, p])),
+                        waves: plan.waves.map(w => w.packetIds),
+                        currentWaveIndex: plan.currentWaveIndex
+                    }
+                },
+                packetPrsCreatedThisRun: summary.packetPrsCreatedThisRun,
+                waveAdvancementsThisRun: summary.packetWaveAdvancementsThisRun,
+                blockedThisRun: summary.packetWaveBlockedThisRun,
+                parentBranchSyncPreflights: summary.parentBranchSyncPreflights.map(p => ({
+                    preflight: p.preflight,
+                    branchSyncComparison: p.branchSyncComparison,
+                    branchSyncComparisonSkippedReason: p.branchSyncComparisonSkippedReason
+                }))
+            });
+            if (report) {
+                lines.push(formatPacketLifecycleReport(report));
+                lines.push("");
+            }
+        }
+    }
+    if (summary.packetPlans.length > 0) {
+        lines.push("");
+        lines.push("Packet plans:");
+        for (const plan of summary.packetPlans) {
+            const waveInfo = plan.currentWaveIndex !== undefined ? `, current wave ${plan.currentWaveIndex}` : "";
+            lines.push(`- ${plan.workstreamId} status ${plan.status}, ${plan.packetCount} packets, ${plan.waveCount} waves${waveInfo}`);
+            plan.waves.forEach((wave, index) => {
+                lines.push(`  wave ${index}: ${wave.packetIds.join(", ")}`);
+            });
+        }
+    }
+    const failedTasks = summary.tasks.filter((task) => task.status === "failed");
+    if (failedTasks.length > 0) {
+        lines.push("");
+        lines.push("Failed tasks:");
+        for (const task of failedTasks) {
+            lines.push(`- ${task.repoSlug} ${task.kind}: ${task.summary}`);
+        }
+    }
+    const scanFailures = collectScanFailures(summary.results);
+    if (scanFailures.length > 0) {
+        lines.push("");
+        lines.push("Scan failures:");
+        for (const failure of scanFailures) {
+            lines.push(`- ${failure.repoSlug} ${failure.step} (${failure.scope}): ${failure.message}`);
+        }
+    }
+    lines.push("");
+    lines.push(`Generated state: ${summary.stateDir}/{repos,issues,prs,comments,tasks,worktrees,workstreams,attention}.json`);
+    lines.push(`Execution log: ${summary.logDir}/{executions.json,artifacts/<execution-id>/...}`);
+    return `${lines.join("\n")}\n`;
+}
+function formatRepoResult(result) {
+    const parts = [`- ${result.repoSlug}`];
+    parts.push(result.status === "synced" ? "sync ok" : "sync failed");
+    if (result.githubScan) {
+        parts.push(`scan ${result.githubScan.status}`);
+    }
+    if (result.status === "failed" && result.error?.message) {
+        parts.push(result.error.message);
+    }
+    else if (result.githubScan?.failures[0]?.message) {
+        parts.push(result.githubScan.failures[0].message);
+    }
+    return parts.join(" | ");
+}
+function collectScanFailures(results) {
+    return results.flatMap((result) => result.githubScan?.failures ?? []);
+}
+function formatPacketIds(ids) {
+    return ids.length > 0 ? ids.join(", ") : "(none)";
+}
+function formatBranchSyncRecommendation(item) {
+    const recommendation = recommendBranchSyncAction(item.branchSyncComparison, item.branchSyncComparisonSkippedReason);
+    const nextWaveIndex = item.preflight.nextWaveIndex;
+    switch (recommendation) {
+        case "ready_to_advance":
+            return "parent branch is up to date with default; next wave may proceed";
+        case "sync_parent_from_default":
+            return `sync parent from default before starting wave ${nextWaveIndex}`;
+        case "manual_conflict_aware_sync_required":
+            return `parent and default diverged; perform conflict-aware sync before starting wave ${nextWaveIndex}`;
+        case "blocked_missing_ref":
+            return "blocked; inspect missing local branch refs before continuing";
+        case "blocked_unknown":
+            return "blocked; branch sync status is unavailable or unknown";
+    }
+}
+function formatBranchSyncComparison(item) {
+    if (item.branchSyncComparisonSkippedReason === "missing_local_path") {
+        return "unavailable (missing local repo path)";
+    }
+    const comparison = item.branchSyncComparison;
+    if (!comparison) {
+        return "unavailable";
+    }
+    const hasCounts = comparison.parentBehindCount !== undefined && comparison.parentAheadCount !== undefined;
+    return hasCounts
+        ? `${comparison.status} (behind ${comparison.parentBehindCount}, ahead ${comparison.parentAheadCount})`
+        : comparison.status;
+}
+function collectNextWaveReadyPreflights(summary) {
+    return summary.parentBranchSyncPreflights.filter((item) => recommendBranchSyncAction(item.branchSyncComparison, item.branchSyncComparisonSkippedReason) === "ready_to_advance");
+}
+function formatNextWaveReadyPreflight(item) {
+    const preflight = item.preflight;
+    const parentPr = preflight.parentPrNumber !== undefined ? `#${preflight.parentPrNumber}` : "unknown";
+    return [
+        `- ${preflight.workstreamId}: wave ${preflight.nextWaveIndex} is ready to prepare`,
+        `  parent branch: ${preflight.parentIntegrationBranch}`,
+        `  default branch: ${preflight.defaultBranch}`,
+        `  parent PR: ${parentPr}`,
+        `  completed packets: ${formatPacketIds(preflight.completedPacketIds)}`,
+        `  pending future packets: ${formatPacketIds(preflight.pendingFuturePacketIds)}`
+    ];
+}
+function formatManagementGitOps(result) {
+    if (!result) {
+        return "unknown";
+    }
+    switch (result.status) {
+        case "skipped_not_git":
+            return "skipped (not a Git worktree)";
+        case "pulled":
+            return "pulled with fast-forward-only update";
+        default:
+            return "unknown";
+    }
+}
+function formatOutputsGitOps(result) {
+    if (!result) {
+        return "unknown";
+    }
+    switch (result.status) {
+        case "skipped_not_git":
+            return "skipped (not a Git worktree)";
+        case "clean_before_run":
+            return "clean before run; failed to finalize (check logs)";
+        case "no_changes":
+            return "clean before run; no generated changes";
+        case "pushed":
+            return `clean before run; committed and pushed ${result.commitSha}`;
+        default:
+            return "unknown";
+    }
+}