@on-par/factory-cli 0.9.7-next.5 → 0.9.7-next.7

package/dist/cli/index.js

@@ -1,21 +1,21 @@
 import { fileURLToPath } from 'node:url';
 // packages/cli/src/cli/index.ts — CLI entry point: factory <command> [options]
 import { exec as execCb, execSync } from 'node:child_process';
-import { randomUUID } from 'node:crypto';
 import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { createRequire } from 'node:module';
 import { arch, hostname as osHostname, release, platform, userInfo } from 'node:os';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { promisify, styleText } from 'node:util';
 import { INVALID_BRANCH_PREFIX_MESSAGE, resolveBranchPrefixOption } from './branch-prefix.js';
-import { acquirePortLease, aggregateCosts, appendKpiHistoryLine, applyRepoConfig, buildPhase, checkPhase, clearProxyState, computeHealthKpis, ConstitutionLoader, createDefaultWorkSourceRegistry, createLogger, createLaneProxy, defaultFindPortListeners, describeEffectiveConfig, detectPostMergeDefects, diagnoseModels, probeDeclaredHarnesses, estimateTrailingSpend, fetchDefectSources, fetchHumanEventSources, fetchSubscriptionUsage, formatUsageReport, getConstitutionsDir, getFactoryPaths, GITHUB_ISSUE_SOURCE, hasUnresolvedPark, InvalidArtifactsDirError, InvalidWorkRequestInputError, InvalidWorkspaceError, inspectPortLeases, isCommandAvailable, isProxyRunning, kpiBranchPrefixes, KNOWN_HARNESS_IDS, kpisToHistoryRecord, laneBaseUrl, laneEnv, laneHostLabel, loadFactoryConfig, loadFactoryConfigForRepo, loadModelsConfig, loadRepoConfig, loadRoutesConfig, LOCAL_BRIEF_SOURCE, joinClassifierOutcomes, mergeClassifierOutcomes, parseClassifierOutcomes, summarizeClassifierOutcomes, formatClassifierReport, mergedPrRefs, ModelRegistry, ModelRouter, parkReasonFor, parseKpiHistory, parseQueue, planPhase, provisionLaneContainer, readEvents, readPortLeases, readQueue, readUsage, reapOrphanProcesses, reapStalePortLeases, reconstructKpiEvents, recordLeasePgid, releasePortLease, renderKpiReport, renderKpiTrend, resolveCodexDisabled, resolveDefectWindowDays, resolveSizeGateMode, parseSizeGateMode, parseMaxSlices, SIZE_GATE_MODES, resolveEffectiveBuildRoute, resolveEffectiveModelPins, resolveLaneBreakerThreshold, resolveEnvironmentProxy, resolveArtifactsDir, resolveLocalOnlyPolicy, resolveMergePolicy, resolveProcessGroupGraceMs, resolveSandboxPolicy, resolveSkipCI, resolveTimeouts, resolveUsageCap, resolveWatchdogPolicy, runAutoIngest, shipPhase, formatCostTotal, validateQueue, watchUsage, writeLocalRunReport, writeProxyState, } from '@on-par/factory-core';
-import { acquirePidFile, createCheckResumeStore, findSlicePlanComment, recordSliceMerged, upsertSlicePlanComment, withSliceState, DEFAULT_GARDEN_MAX_CLUSTERS, DEFAULT_GARDEN_SINCE, capGardenClusters, clusterGarden, dedupGardenClusters, filterGardenOnlyNew, filterGardenWindow, markGardenTrackingUnknown, parseGardenDuration, readHarvestEvents, renderGardenJson, renderGardenReport, laneWorktreePath, migrateRepoConfigToYaml, REPO_CONFIG_YAML_HEADER, claudeConfigDirOverride, claudeKeychainService, cleanupWorktree, createDaemonLogSink, factoryBranchIssue, factoryBranchPrefixes, createDockerEngine, createFactorydServer, createRunRuntime, createShipExecutor, createGithubQueue, createLocalSmallDryRun, createOctokitFilingClient, createOctokitGreenPrClient, createOctokitQueueClient, daemonRuntimePaths, defaultRegistryPath, ensureDir, FACTORY_RUNTIME_CONFIG_KEYS, findUnmergedGreenPrs, formatGcReport, gitFetch, listMicroVms, listOrphanContainers, logCost, logEvent, microVmName, planQueueMigration, readCosts, readGithubQueueSnapshot, reapLaneWorktree, reapOrphanContainers, reapOrphanMicroVm, releaseRuntimeFiles, releaseStaleClaims, resolveBranchPrefix, resolveEffectiveConfig, worktreeSandboxFor, resolveExperimental, resolveLocalOnly, resolvePrClassifierPolicy, resolveRunUsageHarness, resolveReviewFloorRules, RunLockHeldError, runOvernightQueue, parseRemoteSlug, setupWorktree, shellEscape, listBuiltInCheckers, slugify, sweepWorktrees, watchChecks, withAdmissionGuard, withFileLock, withGitLock, withRunLock, wrapCommandInSandbox, writePortFile, buildTriagePrompt, normalizeTriageQueue, parseTriageCandidates, codexChatgptSessionState, hasClaudeLoginEvidence, claudeStoredSessionState, localAuthFailureSinceLogin, recordLocalAuthFailure, hasOpencodeLoginEvidence, } from '@on-par/factory-core/internal';
+import { acquirePortLease, aggregateCosts, appendKpiHistoryLine, applyRepoConfig, buildPhase, checkPhase, clearProxyState, computeHealthKpis, ConstitutionLoader, createDefaultWorkSourceRegistry, createLogger, createLaneProxy, defaultFindPortListeners, describeEffectiveConfig, detectPostMergeDefects, diagnoseModels, probeDeclaredHarnesses, estimateTrailingSpend, fetchDefectSources, fetchHumanEventSources, fetchSubscriptionUsage, formatUsageReport, getConstitutionsDir, getFactoryPaths, GITHUB_ISSUE_SOURCE, hasUnresolvedPark, InvalidArtifactsDirError, InvalidWorkRequestInputError, InvalidWorkspaceError, isCommandAvailable, isProxyRunning, kpiBranchPrefixes, kpisToHistoryRecord, laneBaseUrl, laneEnv, laneHostLabel, loadFactoryConfigForRepo, loadModelsConfig, loadRepoConfig, loadRoutesConfig, LOCAL_BRIEF_SOURCE, joinClassifierOutcomes, mergeClassifierOutcomes, parseClassifierOutcomes, summarizeClassifierOutcomes, formatClassifierReport, mergedPrRefs, ModelRegistry, ModelRouter, parkReasonFor, parseKpiHistory, parseQueue, planPhase, readEvents, readPortLeases, readQueue, readUsage, reapOrphanProcesses, reconstructKpiEvents, recordLeasePgid, releasePortLease, renderKpiReport, renderKpiTrend, resolveDefectWindowDays, parseSizeGateMode, parseMaxSlices, SIZE_GATE_MODES, resolveEffectiveModelPins, resolveEnvironmentProxy, resolveArtifactsDir, resolveLocalOnlyPolicy, resolveMergePolicy, resolveSandboxPolicy, resolveSkipCI, resolveTimeouts, resolveUsageCap, resolveWatchdogPolicy, runAutoIngest, shipPhase, formatCostTotal, validateQueue, watchUsage, writeLocalRunReport, writeProxyState, } from '@on-par/factory-core';
+import { acquirePidFile, createCheckResumeStore, findSlicePlanComment, upsertSlicePlanComment, withSliceState, DEFAULT_GARDEN_MAX_CLUSTERS, DEFAULT_GARDEN_SINCE, capGardenClusters, clusterGarden, dedupGardenClusters, filterGardenOnlyNew, filterGardenWindow, markGardenTrackingUnknown, parseGardenDuration, readHarvestEvents, renderGardenJson, renderGardenReport, laneWorktreePath, migrateRepoConfigToYaml, REPO_CONFIG_YAML_HEADER, claudeConfigDirOverride, claudeKeychainService, cleanupWorktree, createDaemonLogSink, factoryBranchIssue, factoryBranchPrefixes, createFactorydServer, createRunRuntime, createShipExecutor, createGithubQueue, createLocalSmallDryRun, createOctokitFilingClient, createOctokitGreenPrClient, createOctokitQueueClient, daemonRuntimePaths, defaultRegistryPath, ensureDir, FACTORY_RUNTIME_CONFIG_KEYS, findUnmergedGreenPrs, formatGcReport, gitFetch, listMicroVms, listOrphanContainers, logCost, logEvent, planQueueMigration, readCosts, readGithubQueueSnapshot, reapLaneWorktree, reapOrphanContainers, reapOrphanMicroVm, releaseRuntimeFiles, releaseStaleClaims, resolveBranchPrefix, resolveEffectiveConfig, worktreeSandboxFor, resolveExperimental, resolveLocalOnly, resolvePrClassifierPolicy, resolveReviewFloorRules, RunLockHeldError, runOvernightQueue, parseRemoteSlug, setupWorktree, shellEscape, listBuiltInCheckers, sweepWorktrees, watchChecks, withFileLock, withGitLock, withRunLock, writePortFile, buildTriagePrompt, normalizeTriageQueue, parseTriageCandidates, recordLocalAuthFailure, } from '@on-par/factory-core/internal';
 import { runTui } from '@on-par/factory-tui';
 import { admissionStateReaderFor, runQueueReconcile } from './admission.js';
 import { cmdClassifierBacktest, ClassifierBacktestInputError, } from './classifier-backtest.js';
-import { findOpenPRForIssue, landIssue, waitForMerge } from './land.js';
+import { findOpenPRForIssue, landIssue } from './land.js';
 import { AwaitingReviewError, CiFailedError, CiUnverifiedError, getPullRequestLandState, LandConflictError, LandFailureError, MergeGatedError, } from './land-pr.js';
 import { setLandRuntime } from './land-runtime.js';
+import { cmdRun } from './run.js';
 import { shipIssue } from './ship.js';
 import { cmdStatus } from './status.js';
 import { cmdSupervise } from './supervise.js';
@@ -34,7 +34,7 @@ import { buildUsageJson } from './usage-json.js';
 import { parseResetIssues, runReset } from './reset.js';
 import { cmdDaemonLogs, cmdDaemonStart, cmdDaemonStatus, cmdDaemonStop, createAutoUpdateDeps, DaemonCtlError, detectInstall, loadDaemonFileConfig, recoverStaleDrain, resolveFactorydConfig, runAutoUpdateLoop, } from './daemon.js';
 import { checkForUpdate, cmdSelfUpdateCheck } from './self-update.js';
-import { analyzeEventLog, claudeKeychainCheck, doctorFailed, eventLogCheck, formatClaimReconcileReport, formatContainerReconcileReport, formatDoctorChecks, formatMicroVmReconcileReport, formatReconcileReport, formatWorktreeReconcileReport, declaredHarnessChecks, hasSandboxRuntime, leaseChecks, keychainPreflightError, orphanContainerChecks, configLintChecks, modelsRegistryChecks, orphanMicroVmChecks, runDoctorChecks, sandboxAuthSkipDetail, reconcileAgentAuthChecks, repoCommandHarnesses, sandboxClaudeAuthChecks, unmergedGreenPrChecks, } from './doctor.js';
+import { cmdDoctor } from './doctor.js';
 import { DOCS_URL, formatOverview, availableAgentClis, missingAgentCliMessage, missingTokenMessage, notInitializedMessage, } from './first-run.js';
 import { cmdHostedSmoke } from './hosted.js';
 import { cmdHostedQueue } from './hosted-queue.js';
@@ -48,11 +48,8 @@ import { selectOctokit } from './github-stub.js';
 import { createFactoryOctokit } from './octokit.js';
 import { DeepCheckError, createDeepModelRunner, runIssueCheck } from './ready-check.js';
 import { childRunSucceeded, formatChildRunSummary, runChildrenInOrder } from './run-children.js';
-import { createBaseHoldGate, formatBaseHoldCleared, writeBaseHold } from './base-hold.js';
-import { readRunFlagOverrides, writeRunFlagOverrides } from './run-flags.js';
-import { distFreshnessProbe, runStalenessGuard } from './staleness.js';
-import { readStopFileStatus, stopSentinelCheck, stopSentinelRunSkipMessage } from './stop-sentinel.js';
-import { checkSweepHeartbeat, defaultSweepHeartbeatDeps, sweepHeartbeatCheck } from './sweep-heartbeat.js';
+import { readRunFlagOverrides } from './run-flags.js';
+import { runStalenessGuard } from './staleness.js';
 const DEFAULT_CONFIG_LOADERS = {
     loadModelsConfig,
     loadRoutesConfig,
@@ -2518,194 +2515,9 @@ function usageFlagOverrides(opts, threshold) {
         pollSeconds: opts.usagePoll === undefined ? undefined : Number(opts.usagePoll),
     };
 }
-async function cmdRun(opts = {}) {
-    const repoRoot = await getRepoRoot();
-    const paths = getFactoryPaths(repoRoot);
-    const branchPrefix = branchPrefixOrExit(opts.branchPrefix);
-    return withRepoRunLock(paths, 'factory run', async () => {
-        const stopStatus = readStopFileStatus(paths);
-        if (stopStatus.present) {
-            const msg = stopSentinelRunSkipMessage(stopStatus);
-            console.log(styleText('yellow', `!! ${msg}`));
-            logEvent(paths.events, 'stopped', 'all', msg);
-            return;
-        }
-        writeRunFlagOverrides(paths.runFlags, { autoMerge: opts.autoMerge, prClassifier: opts.prClassifier });
-        const ghRepo = await getGitHubRepo();
-        const factoryConfig = configLoaders.loadFactoryConfigForRepo(paths.config);
-        const keychainErr = keychainPreflightError(probeClaudeKeychain());
-        if (keychainErr) {
-            logEvent(paths.events, 'environment_warning', 'all', keychainErr);
-            throw new Error(keychainErr);
-        }
-        await runAutoWorktreeGc(repoRoot, paths, ghRepo, 'all');
-        const { lanes, diagnostics } = await planRunLanes({
-            localQueue: opts.localQueue === true,
-            readLocalQueue: () => (existsSync(paths.queue) ? readFileSync(paths.queue, 'utf-8') : null),
-            queue: () => {
-                const [owner, repo] = ghRepo.split('/');
-                const octokit = getOctokit();
-                return createGithubQueue({
-                    client: createOctokitQueueClient(octokit),
-                    owner,
-                    repo,
-                    preflight: withAdmissionGuard({
-                        reader: admissionStateReaderFor(paths.state),
-                        preflight: (issue) => preflightQueuedIssue(issue, createQueuePreflightOps(octokit, owner, repo, {
-                            autoMergeStack: resolveSizeGateMode(factoryConfig) === 'stack' &&
-                                resolveMergePolicy(factoryConfig, process.env, { auto: opts.autoMerge }).auto,
-                        })),
-                        onConflict: (issue, verdict) => {
-                            const line = `#${issue} refused — ${verdict.reason} | repair: ${verdict.repair}`;
-                            console.error(styleText('yellow', `factory: ${line}`));
-                            logEvent(paths.events, 'queue_admission_conflict', String(issue), line);
-                        },
-                    }),
-                });
-            },
-        });
-        warnQueueDiagnostics(diagnostics);
-        let knobs;
-        let laneBreakerThreshold;
-        try {
-            knobs = resolveUsageKnobs(process.env, configLoaders.loadRepoConfig(repoRoot), usageFlagOverrides(opts, 'stopAt'));
-            laneBreakerThreshold = resolveLaneBreakerThreshold(configLoaders.loadRepoConfig(repoRoot));
-        }
-        catch (err) {
-            throw new CliExitError(`factory: ${err.message}`, 2);
-        }
-        if (knobs.watchSource === 'flag') {
-            const detail = `usage watchdog ${knobs.watch ? 'enabled' : 'disabled'} by ${usageWatchSourceLabel(knobs.watchSource, knobs.watch)}`;
-            console.log(`[factory] run: ${detail}`);
-            logEvent(paths.events, 'watchdog', 'all', detail);
-        }
-        if (knobs.stopAtSource === 'flag') {
-            const detail = 'usage watchdog threshold set by flag: --usage-threshold';
-            console.log(`[factory] run: ${detail}`);
-            logEvent(paths.events, 'watchdog', 'all', detail);
-        }
-        if (knobs.pollSource === 'flag') {
-            const detail = 'usage watchdog poll set by flag: --usage-poll';
-            console.log(`[factory] run: ${detail}`);
-            logEvent(paths.events, 'watchdog', 'all', detail);
-        }
-        let watchdogHarness;
-        if (knobs.watch) {
-            try {
-                const repoConfig = configLoaders.loadRepoConfig(repoRoot);
-                const registry = new coreOps.ModelRegistry(applyRepoConfig(configLoaders.loadModelsConfig(), repoConfig));
-                const pins = configLoaders.resolveEffectiveModelPins(registry, repoConfig, process.env);
-                const build = resolveEffectiveBuildRoute(registry, repoConfig, pins);
-                watchdogHarness = resolveRunUsageHarness({
-                    buildRoute: build.route,
-                    buildRouteSource: build.source,
-                    planHarnesses: [pins.plan, pins.planFallback]
-                        .filter((m) => !!m)
-                        .map((m) => registry.getHarnessId(m)),
-                    codexDisabled: resolveCodexDisabled(repoConfig),
-                    localOnly: resolveLocalOnly(),
-                });
-            }
-            catch {
-                watchdogHarness = undefined; // unresolvable config keeps today's Claude gating
-            }
-        }
-        const controller = new AbortController();
-        const watchdog = knobs.watch
-            ? coreOps
-                .watchUsage({
-                cap: knobs.cap,
-                stopAt: knobs.stopAt,
-                pollMs: knobs.pollMs,
-                stopFile: paths.stop,
-                eventsFile: paths.events,
-                signal: controller.signal,
-                estimator: knobs.estimator,
-                ...(watchdogHarness ? { harness: watchdogHarness } : {}),
-            })
-                .catch((err) => {
-                // a watchdog crash must never take down the run
-                logEvent(paths.events, 'warn', '-', `usage watchdog crashed: ${err.message}`);
-            })
-            : Promise.resolve();
-        const { proxy } = await startLaneProxy(paths, resolveEnvironmentProxy(factoryConfig));
-        const workspaceBackend = factoryConfig.workspace?.backend ?? 'host';
-        const runId = randomUUID();
-        const containerEngine = workspaceBackend === 'disposable-docker' ? createDockerEngine({}) : undefined;
-        try {
-            // Run lanes in parallel
-            const pids = [];
-            for (const planned of lanes) {
-                logEvent(paths.events, 'lane-start', '-', `lane '${planned.lane}' started${planned.issues.length ? ` (${planned.issues.length} issues)` : ''}`, { lane: planned.lane });
-                if (containerEngine) {
-                    const provision = await provisionLaneContainer(containerEngine, workspaceBackend, runId, slugify(planned.lane), ghRepo);
-                    if (provision.attempted && !provision.created) {
-                        logEvent(paths.events, 'warn', '-', `disposable-docker container creation failed for lane '${planned.lane}': ${provision.error}`, { lane: planned.lane });
-                    }
-                    else if (provision.attempted && provision.created && provision.workspaceCloned === false) {
-                        logEvent(paths.events, 'warn', '-', `disposable-docker workspace clone failed for lane '${planned.lane}': ${provision.workspaceError}`, { lane: planned.lane });
-                    }
-                }
-                pids.push(runLane(planned.lane, planned.issues, repoRoot, ghRepo, paths, {
-                    ...planned.deps,
-                    laneBreakerThreshold,
-                    baseHoldGate: opts.localQueue === true
-                        ? undefined
-                        : createBaseHoldGate({
-                            file: paths.baseHold,
-                            repo: ghRepo,
-                            onCleared: (c) => logEvent(paths.events, 'base-hold-cleared', planned.lane, formatBaseHoldCleared(c), {
-                                lane: planned.lane,
-                            }),
-                            git: (cmd) => shellOps.exec(cmd, { cwd: repoRoot }).then((r) => r.stdout),
-                            listCheckRuns: (ref) => {
-                                const [owner, repoName] = ghRepo.split('/');
-                                return createOctokitGreenPrClient(getOctokit()).listCheckRuns({ owner, repo: repoName, ref });
-                            },
-                        }),
-                    commentIssue: async (issue, body) => {
-                        const [owner, repoName] = ghRepo.split('/');
-                        await getOctokit().rest.issues.createComment({ owner, repo: repoName, issue_number: issue, body });
-                    },
-                    ship: (issue, o, c) => shipIssue(issue, { ...o, branchPrefix, prClassifier: opts.prClassifier }, c),
-                    sweepFinished: (issue) => sweepBetweenLaneIssues(issue, planned.lane, repoRoot, ghRepo, paths).then(() => { }),
-                    reapWorktree: (issue) => reapParkedLaneWorktree(issue, repoRoot, ghRepo, paths, opts.branchPrefix === undefined ? undefined : branchPrefix),
-                    recordStackMerge: (issue, prNumber) => recordSliceMerged({ octokit: getOctokit(), repo: ghRepo, issue, prNumber }).then(() => { }),
-                    waitMerge: (issue, branch, root, gh, p, d = {}) => waitForMerge(issue, branch, root, gh, p, { ...d, mergeOverrides: { auto: opts.autoMerge } }),
-                }));
-            }
-            await Promise.allSettled(pids);
-            controller.abort();
-            await watchdog;
-            logEvent(paths.events, 'run-done', 'all', 'all lanes finished');
-        }
-        finally {
-            if (proxy) {
-                await proxy.stop();
-                clearProxyState(paths.proxyState);
-            }
-        }
-        if (lanes.length > 0) {
-            try {
-                const events = existsSync(paths.events) ? readEvents(paths.events) : [];
-                const costs = existsSync(paths.costs) ? internalOps.readCosts(paths.costs) : [];
-                const recon = await reconstructHumanEventsForKpis(events, branchPrefix);
-                const kpis = computeHealthKpis(recon.events, costs);
-                await appendKpiSnapshot(paths, repoRoot, kpis, { partial: recon.partial });
-                if (recon.partial) {
-                    logEvent(paths.events, 'warn', 'all', `kpi snapshot partial: GitHub human-event reconstruction failed: ${recon.error}`);
-                }
-                logEvent(paths.events, 'kpi-snapshot', 'all', `KPI snapshot appended to ${paths.kpiHistory}`);
-            }
-            catch (err) {
-                logEvent(paths.events, 'warn', 'all', `kpi snapshot failed: ${err.message}`);
-            }
-        }
-    });
-}
 /** Wraps cmdRun so an empty queue is a no-op (not a throw) while auto-ingest is enabled and watching. */
 export function createSuperviseRunQueue(paths, ingestCfg, deps = {}) {
-    const { cmdRunFn = cmdRun, readQueueFile = () => (existsSync(paths.queue) ? readFileSync(paths.queue, 'utf-8') : ''), pendingCount = async () => parseQueue(readQueueFile()).entries.length, emitEvent = logEvent, } = deps;
+    const { cmdRunFn = runRun, readQueueFile = () => (existsSync(paths.queue) ? readFileSync(paths.queue, 'utf-8') : ''), pendingCount = async () => parseQueue(readQueueFile()).entries.length, emitEvent = logEvent, } = deps;
     return async () => {
         if ((await pendingCount()) === 0 && ingestCfg.enabled) {
             emitEvent(paths.events, 'idle', 'auto', 'queue empty — waiting for ready issues');
@@ -2938,234 +2750,6 @@ export async function planRunLanes(input) {
         diagnostics: [],
     };
 }
-/** How often an in-flight issue's claim lease is refreshed (#1500). Well inside the
- *  15-minute default lease (github-queue.ts's DEFAULT_CLAIM_LEASE_MS) so a normal poll
- *  cadence never lets the lease lapse mid-ship. */
-const HEARTBEAT_INTERVAL_MS = 5 * 60 * 1000;
-/** Runs `work` while periodically calling `heartbeat(issue)` so a long-running ship or
- *  merge wait keeps this claimant's lease fresh. A heartbeat failure is swallowed — losing
- *  one refresh must never abort the work it is protecting. */
-async function withHeartbeat(issue, heartbeat, work) {
-    if (!heartbeat)
-        return work();
-    const timer = setInterval(() => {
-        heartbeat(issue).catch(() => { });
-    }, HEARTBEAT_INTERVAL_MS);
-    try {
-        return await work();
-    }
-    finally {
-        clearInterval(timer);
-    }
-}
-export function renderLanePausedComment(payload) {
-    const checks = payload.failingChecks.length
-        ? payload.failingChecks.map((c) => `\`${c}\``).join(', ')
-        : 'none recorded';
-    return [
-        `Lane '${payload.lane}' is paused: this issue and #${payload.firstIssue} parked with the same failure signature, so the factory stopped claiming issues on this lane.`,
-        `Shared failing checks: ${checks}`,
-        `To resume: fix the shared failure (often on the base branch), then re-run \`factory run\` to resume lane '${payload.lane}'.`,
-        `Failure signature: \`${payload.signature}\``,
-    ].join('\n\n');
-}
-export async function runLane(lane, issues, repoRoot, ghRepo, paths, deps = {}) {
-    const { ship = shipIssue, waitMerge = waitForMerge, recordStackMerge = async () => { }, pathExists = existsSync, emitEvent = logEvent, claimNext = async () => null, releaseIssue = async () => { }, heartbeat, reapWorktree = async () => { }, sweepFinished = async () => { }, countRemaining, baseHoldGate, laneBreakerThreshold = 0, commentIssue = async () => { }, } = deps;
-    let streak = null;
-    let merged = 0;
-    let awaitingReview = 0;
-    let skipped = 0;
-    let decomposed = 0;
-    let parked = 0;
-    const buildClaim = (issue) => ({ issue, decision: { kind: 'build' } });
-    const pending = issues.map(buildClaim);
-    const seen = new Set(issues);
-    // Truthful park-time remaining count (#1222): local pending plus the lane's still-queued
-    // remote issues. Fail-closed — a count lookup may never change the message beyond the
-    // local truth, and never lane flow.
-    const remainingAfter = async (index) => {
-        const local = pending.length - index - 1;
-        if (!countRemaining)
-            return local;
-        try {
-            return local + (await countRemaining());
-        }
-        catch {
-            return local;
-        }
-    };
-    // Every terminal outcome releases the claim, then gives finished worktrees a GC pass before
-    // the lane moves on (#1757). The pass is fail-closed and must never change lane flow.
-    const settle = async (issue, outcome) => {
-        await releaseIssue(issue, outcome);
-        await sweepFinished(issue).catch(() => { });
-    };
-    for (let i = 0;; i++) {
-        if (i >= pending.length) {
-            // A persisted base hold on the unchanged origin/main SHA means the base is still broken
-            // (#2349): claiming would just cycle an issue again, so stop this lane without claiming.
-            const gate = baseHoldGate ? await baseHoldGate().catch(() => ({ kind: 'claim' })) : null;
-            if (gate?.kind === 'hold') {
-                emitEvent(paths.events, 'warn', lane, `lane '${lane}' not claiming: base hold on ${gate.hold.baseSha.slice(0, 8)} (${gate.hold.failingChecks.join(', ')}) — origin/main unchanged and its CI is not green`, { lane });
-                return;
-            }
-            const claimed = await claimNext();
-            if (claimed === null)
-                break;
-            seen.add(claimed.issue);
-            pending.push(claimed);
-        }
-        const { issue, decision } = pending[i];
-        if (pathExists(paths.stop)) {
-            emitEvent(paths.events, 'stopped', issue, 'STOP file present', { lane });
-            await releaseIssue(issue, 'queued');
-            return;
-        }
-        if (decision.kind === 'park') {
-            emitEvent(paths.events, 'escalate', issue, decision.reason, { lane });
-            emitEvent(paths.events, 'parked', issue, `issue #${issue} parked (${decision.reason}); lane '${lane}' continuing, ${await remainingAfter(i)} issue(s) remaining`, { lane });
-            // A preflight-parked issue may still have a stale worktree from a prior run; the reap
-            // is fail-closed and must never change lane flow.
-            await reapWorktree(issue).catch(() => { });
-            await settle(issue, 'parked');
-            parked++;
-            streak = null;
-            continue;
-        }
-        const layer = decision.kind === 'adopt' ? decision.stackLayer : undefined;
-        try {
-            const sliceOutcome = {};
-            const branch = decision.kind === 'adopt'
-                ? decision.branch
-                : await withHeartbeat(issue, heartbeat, () => ship(issue, {}, {
-                    repoRoot,
-                    ghRepo,
-                    paths,
-                    lane,
-                    onOutcome: (o) => {
-                        sliceOutcome.value = o;
-                    },
-                }));
-            const shipped = sliceOutcome.value;
-            if (shipped?.state === 'ready' && shipped.slice && shipped.slice.index < shipped.slice.count) {
-                // ADR-0147: a non-final slice's PR is open; hand the issue back for the next slice
-                // instead of waiting for the merge.
-                awaitingReview++;
-                streak = null;
-                await settle(issue, 'queued');
-                continue;
-            }
-            if (layer) {
-                // ADR-0161: land exactly this layer's branch, record it, and re-queue for the next layer.
-                await withHeartbeat(issue, heartbeat, () => waitMerge(issue, branch, repoRoot, ghRepo, paths, { landBranch: branch }));
-                await recordStackMerge(issue, layer.prNumber).catch((err) => emitEvent(paths.events, 'warn', issue, `slice ${layer.index}/${layer.count} merged but recording it failed: ${errorDetail(err)}`, { lane }));
-                merged++;
-                streak = null;
-                await settle(issue, layer.index < layer.count ? 'queued' : 'done');
-                continue;
-            }
-            await withHeartbeat(issue, heartbeat, () => waitMerge(issue, branch, repoRoot, ghRepo, paths));
-            merged++;
-            streak = null;
-            await settle(issue, 'done');
-        }
-        catch (err) {
-            if (err instanceof AwaitingReviewError) {
-                // The land path already emitted the awaiting-review event and cleaned the
-                // worktree — this is a clean outcome, not a park; move to the next issue.
-                awaitingReview++;
-                streak = null;
-                await settle(issue, layer && layer.index < layer.count ? 'queued' : 'done');
-                continue;
-            }
-            if (err instanceof IssueSkippedError) {
-                // shipIssue already emitted skipped-already-closed; nothing was attempted.
-                skipped++;
-                await settle(issue, 'done');
-                continue;
-            }
-            if (err instanceof IssueDecomposedError) {
-                // shipIssue already rewrote the queue — splice the children in after the
-                // current issue so this same lane run ships them, deduping ones already queued.
-                const fresh = err.childIssues.filter((n) => !seen.has(n));
-                for (const n of fresh)
-                    seen.add(n);
-                pending.splice(i + 1, 0, ...fresh.map(buildClaim));
-                decomposed++;
-                emitEvent(paths.events, 'decompose_filed', issue, `lane '${lane}' continuing with ${fresh.length} child issue(s) in place of #${issue}`, { lane });
-                await settle(issue, 'done');
-                continue;
-            }
-            if (err instanceof LaneEnvironmentPauseError) {
-                // The base is broken, not the issue (#1928): release to queued (never parked),
-                // pause the lane whatever laneBreakerThreshold is, and stop claiming.
-                streak = null;
-                // A preserved build is kept for `factory resume --from check` (#2564).
-                if (!err.buildPreserved)
-                    await reapWorktree(issue).catch(() => { });
-                await settle(issue, 'queued');
-                // Persist the hold so a restarted supervisor remembers the broken base (#2348);
-                // best-effort, never allowed to change lane flow.
-                try {
-                    writeBaseHold(paths.baseHold, {
-                        repo: ghRepo,
-                        baseSha: err.baseSha,
-                        failingChecks: err.failingChecks,
-                        since: new Date().toISOString(),
-                    });
-                }
-                catch { }
-                const payload = {
-                    lane,
-                    signature: err.failureSignature ?? '',
-                    failingChecks: err.failingChecks,
-                    firstIssue: issue,
-                    secondIssue: issue,
-                    cause: 'environment',
-                    baseSha: err.baseSha,
-                };
-                emitEvent(paths.events, 'lane-paused', lane, `lane '${lane}' paused: #${issue} failed only on checkers that also fail on base ${err.baseSha.slice(0, 8)} (${err.failingChecks.join(', ')}); #${issue} released to queued`, { lane, lanePaused: payload });
-                return;
-            }
-            const reason = parkReasonFor(err);
-            // Terminal reason events (escalate/timeout/fail/conflict) are emitted exactly
-            // once by the layer that detects the failure — shipIssue for pipeline failures,
-            // the land path for merge failures. runLane owns only lane-lifecycle events
-            // (stopped/parked/lane-done), so injected ship functions never change ownership.
-            const signature = err instanceof LaneParkError ? err.failureSignature : undefined;
-            const checks = err instanceof LaneParkError ? (err.failingChecks ?? []) : [];
-            if (!signature)
-                streak = null;
-            else if (streak && streak.signature === signature)
-                streak.count++;
-            else
-                streak = { signature, firstIssue: issue, failingChecks: checks, count: 1 };
-            const tripped = laneBreakerThreshold > 0 && streak !== null && streak.count >= laneBreakerThreshold;
-            emitEvent(paths.events, 'parked', issue, `issue #${issue} parked (${reason}); ${tripped ? `lane '${lane}' paused (lane breaker)` : `lane '${lane}' continuing`}, ${await remainingAfter(i)} issue(s) remaining`, { lane });
-            // Remove the parked lane's own worktree so a parked issue stops leaving a sibling
-            // checkout behind (#1007); fail-closed and never allowed to change lane flow.
-            await reapWorktree(issue).catch(() => { });
-            await settle(issue, 'parked');
-            parked++;
-            if (tripped && streak) {
-                const { signature: tripSignature, firstIssue, failingChecks: firstChecks } = streak;
-                const payload = {
-                    lane,
-                    signature: tripSignature,
-                    failingChecks: checks.filter((c) => firstChecks.includes(c)),
-                    firstIssue,
-                    secondIssue: issue,
-                };
-                emitEvent(paths.events, 'lane-paused', lane, `lane '${lane}' paused: #${payload.firstIssue} and #${payload.secondIssue} parked with the same failure signature (${payload.failingChecks.join(', ') || 'no failing checks'})`, { lane, lanePaused: payload });
-                // Tell the developer on GitHub why the lane stopped (#1919); fail-closed, never changes lane flow.
-                await commentIssue(payload.secondIssue, renderLanePausedComment(payload)).catch(() => { });
-                return;
-            }
-            continue;
-        }
-    }
-    emitEvent(paths.events, 'lane-done', lane, `lane complete (${merged} merged, ${awaitingReview} awaiting review, ${skipped} skipped, ${decomposed} decomposed, ${parked} parked)`, { lane });
-}
 /** The target issue was already resolved before the run started — a clean skip,
  *  not a park. Callers advance to the next queue entry. (#681) */
 export class IssueSkippedError extends Error {
@@ -3388,220 +2972,6 @@ function probeClaudeKeychain() {
         return { status: 'unreadable', inTmux: !!process.env.TMUX, ...profile };
     }
 }
-async function cmdDoctor(opts = {}) {
-    let repoRoot;
-    try {
-        repoRoot = shellOps
-            .execSync('git rev-parse --show-toplevel', {
-            timeout: 10_000,
-            stdio: ['ignore', 'pipe', 'ignore'],
-        })
-            .trim();
-    }
-    catch {
-        repoRoot = null;
-    }
-    const checks = runDoctorChecks({
-        commandAvailable: coreOps.isCommandAvailable,
-        envPresent: (key) => !!process.env[key],
-        tryExec: (cmd, opts) => {
-            try {
-                return shellOps
-                    .execSync(cmd, {
-                    timeout: opts?.timeoutMs ?? 10_000,
-                    stdio: ['ignore', 'pipe', 'ignore'],
-                    ...(opts?.env ? { env: { ...process.env, ...opts.env } } : {}),
-                })
-                    .trim();
-            }
-            catch {
-                return null;
-            }
-        },
-        pathExists: existsSync,
-        distFreshness: distFreshnessProbe(import.meta.url),
-        codexSessionState: () => codexChatgptSessionState(),
-        claudeLoggedIn: () => hasClaudeLoginEvidence({
-            exec: (file, args) => {
-                shellOps.execSync([file, ...args].map(shellEscape).join(' '), { timeout: 10_000, stdio: 'ignore' });
-            },
-            fileExists: existsSync,
-        }),
-        claudeSessionState: () => claudeStoredSessionState(),
-        localAuthFailure: (agent) => localAuthFailureSinceLogin(agent),
-        opencodeLoggedIn: () => hasOpencodeLoginEvidence(),
-        commandHarnesses: () => repoRoot === null
-            ? []
-            : repoCommandHarnesses(configLoaders.loadModelsConfig().harnesses, configLoaders.loadRepoConfig(repoRoot)?.models?.registry),
-    });
-    // Only with --probe-inference: these send a real prompt (uses quota). Plain doctor makes no inference call.
-    if (opts.probeInference) {
-        const CLAUDE_AUTH_PROBE = 'claude -p "reply with exactly: ok"';
-        const probeExec = (cmd) => {
-            try {
-                return shellOps.execSync(cmd, { timeout: 120_000, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-            }
-            catch {
-                return null;
-            }
-        };
-        let host = 'skipped';
-        let hostDetail = 'skipped: claude CLI not on PATH';
-        if (coreOps.isCommandAvailable('claude')) {
-            host = probeExec(CLAUDE_AUTH_PROBE) === null ? 'failed' : 'ok';
-            hostDetail = host === 'ok' ? 'claude -p succeeded on the host' : 'claude -p failed on the host';
-        }
-        let sandboxed = 'skipped';
-        let sandboxDetail = 'skipped: host claude auth was not verified';
-        const runtimeAvailable = hasSandboxRuntime(process.platform, (cmd) => isCommandAvailableViaShell(shellOps, cmd));
-        const skip = sandboxAuthSkipDetail({ runtimeAvailable, hostOk: host === 'ok', inRepo: repoRoot !== null });
-        if (skip !== null) {
-            sandboxDetail = skip;
-        }
-        else if (repoRoot !== null) {
-            const policy = resolveSandboxPolicy(configLoaders.loadFactoryConfigForRepo(getFactoryPaths(repoRoot).config).sandbox, {
-                worktree: repoRoot,
-                repoRoot,
-                isAvailable: (cmd) => isCommandAvailableViaShell(shellOps, cmd),
-            });
-            if (!policy) {
-                sandboxDetail = 'skipped: sandbox disabled by config or FACTORY_SANDBOX';
-            }
-            else if (policy.runtime === 'none') {
-                sandboxDetail = 'skipped: no sandbox runtime (sandbox-exec/firejail) on this host';
-            }
-            else if (policy.runtime === 'docker-sandbox') {
-                sandboxDetail = 'skipped: docker-sandbox containment is the microVM, not command wrapping (#653)';
-            }
-            else {
-                sandboxed = probeExec(wrapCommandInSandbox(CLAUDE_AUTH_PROBE, policy)) === null ? 'failed' : 'ok';
-                sandboxDetail =
-                    sandboxed === 'ok'
-                        ? `claude -p succeeded under ${policy.runtime}`
-                        : `claude -p failed under ${policy.runtime} (local_auth)`;
-            }
-        }
-        checks.push(...sandboxClaudeAuthChecks({ host, sandboxed, hostDetail, sandboxDetail }));
-    }
-    checks.push(claudeKeychainCheck(probeClaudeKeychain()));
-    checks.splice(0, checks.length, ...reconcileAgentAuthChecks(checks));
-    if (repoRoot !== null) {
-        const paths = getFactoryPaths(repoRoot);
-        let factoryConfig;
-        try {
-            factoryConfig = configLoaders.loadFactoryConfigForRepo(paths.config);
-        }
-        catch {
-            factoryConfig = loadFactoryConfig(); // schema errors are reported by the config row (#2611)
-        }
-        const health = await inspectPortLeases({ registryFile: paths.ports });
-        checks.push(...leaseChecks(health.map(toLeaseRow)));
-        const dockerAvailable = coreOps.isCommandAvailable('docker');
-        const orphanContainers = dockerAvailable ? await internalOps.listOrphanContainers().catch(() => []) : [];
-        checks.push(...orphanContainerChecks(orphanContainers.map((c) => c.name)));
-        const sbxAvailable = coreOps.isCommandAvailable('sbx');
-        const activeVmNames = new Set(health.filter((h) => h.alive).map((h) => microVmName(h.lease.worktreeId)));
-        const orphanVmNames = sbxAvailable ? (await internalOps.listMicroVms()).filter((n) => !activeVmNames.has(n)) : [];
-        checks.push(...orphanMicroVmChecks(orphanVmNames));
-        const sweepStatus = checkSweepHeartbeat(factoryConfig.sweep, process.env, defaultSweepHeartbeatDeps());
-        const sweepCheck = sweepHeartbeatCheck(sweepStatus);
-        if (sweepCheck)
-            checks.push(sweepCheck);
-        checks.push(stopSentinelCheck(readStopFileStatus(paths)));
-        const eventsContent = existsSync(paths.events) ? readFileSync(paths.events, 'utf-8') : null;
-        checks.push(eventLogCheck(eventsContent === null ? null : analyzeEventLog(eventsContent)));
-        let constitution = null;
-        let loadError;
-        try {
-            constitution = new ConstitutionLoader().loadRepoConstitution(repoRoot, factoryConfig.paths?.constitution);
-        }
-        catch (err) {
-            loadError = `cannot parse constitution: ${err instanceof Error ? err.message : String(err)}`;
-        }
-        checks.push(...configLintChecks({ constitution, configFile: repoConfigFileFor(repoRoot, paths.config) }, loadError));
-        try {
-            const declared = Object.keys(configLoaders.loadModelsConfig().harnesses ?? {});
-            checks.push(...modelsRegistryChecks(paths.config, configLoaders.loadRepoConfig(repoRoot)?.models?.registry, [
-                ...KNOWN_HARNESS_IDS,
-                ...declared,
-            ]));
-        }
-        catch {
-            // malformed config is reported by the load paths / `factory models --doctor`; doctor keeps going
-        }
-        let harnessProbes = [];
-        try {
-            const registry = new coreOps.ModelRegistry(applyRepoConfig(configLoaders.loadModelsConfig(), configLoaders.loadRepoConfig(repoRoot)));
-            harnessProbes = coreOps.probeDeclaredHarnesses(registry);
-        }
-        catch {
-            // models config problems are reported by `factory models --doctor`; doctor keeps going
-        }
-        checks.push(...declaredHarnessChecks(harnessProbes));
-        // Full run-lifecycle reap (#998): dead-run worktrees and their branches. Uses the same
-        // GitHub evidence and the same lock pairing as `factory worktree gc` (cmdWorktreeGc) —
-        // a merged or closed PR is what makes a worktree reapable.
-        const ghRepo = await getGitHubRepo().catch(() => undefined);
-        const octokit = ghRepo && hasGitHubToken() ? getOctokit() : undefined;
-        // Green-and-ready PRs with no merge (#1000). Report only — doctor never lands a PR.
-        checks.push(...unmergedGreenPrChecks(await scanGreenPrs(ghRepo, octokit)));
-        if (opts.reconcile) {
-            if (orphanContainers.length > 0) {
-                const reapedContainers = await internalOps.reapOrphanContainers(orphanContainers);
-                console.log(formatContainerReconcileReport(reapedContainers));
-            }
-            if (orphanVmNames.length > 0) {
-                const reapedVms = await Promise.all(orphanVmNames.map((name) => internalOps.reapOrphanMicroVm(name)));
-                console.log(formatMicroVmReconcileReport(reapedVms));
-            }
-            const reaped = await reapStalePortLeases({ registryFile: paths.ports, lockDir: paths.portsLock });
-            console.log(formatReconcileReport(reaped));
-            if (reaped.length > 0) {
-                const graceMs = resolveProcessGroupGraceMs(factoryConfig);
-                const orphanEvents = await coreOps.reapOrphanProcesses({ reaped, graceMs });
-                for (const e of orphanEvents) {
-                    console.log(`reconcile: ${e.action === 'killed' ? 'killed' : 'found'} pid ${e.pid} (pgid ${e.pgid}, ${e.command}) squatting port ${e.port} of dead lane ${e.worktreeId}${e.action === 'reported' ? '; not factory-started, left running' : ''}`);
-                }
-            }
-            try {
-                const gcLog = (type, msg) => logEvent(paths.events, type, '-', msg);
-                const gcSandbox = gcWorktreeSandbox(factoryConfig.sandbox, repoRoot);
-                const report = await withGitLock(repoRoot, () => withFileLock(paths.gitLock, () => internalOps.sweepWorktrees({
-                    repoRoot,
-                    ttlDays: factoryConfig.worktree.gcTtlDays,
-                    repo: ghRepo,
-                    branchPrefix: resolveBranchPrefix(),
-                }, { log: gcLog, octokit, sandbox: gcSandbox })));
-                console.log(formatWorktreeReconcileReport(report.removed));
-            }
-            catch (err) {
-                console.log(`reconcile: worktree sweep failed: ${err?.message ?? String(err)}`);
-            }
-            // Stale claim reap (#999): factory:in-progress claims naming a dead local pid go back to
-            // factory:queued so the next run can claim them with no manual label surgery.
-            try {
-                if (ghRepo && octokit) {
-                    const [owner, repoName] = ghRepo.split('/');
-                    const released = await internalOps.releaseStaleClaims({
-                        client: createOctokitQueueClient(octokit),
-                        owner,
-                        repo: repoName,
-                    });
-                    console.log(formatClaimReconcileReport(released));
-                }
-                else {
-                    console.log('reconcile: skipping stale claims: no GitHub repo or token');
-                }
-            }
-            catch (err) {
-                console.log(`reconcile: stale claim release failed: ${err?.message ?? String(err)}`);
-            }
-        }
-    }
-    console.log(formatDoctorChecks(checks, { inRepo: repoRoot !== null }));
-    if (doctorFailed(checks))
-        process.exit(1);
-}
 /** Appends one event to the events log without echoing it to stdout (stop/resume --json must print only JSON). */
 function logEventQuietly(eventsFile, type, msg) {
     createLogger(eventsFile, { issue: '-' }, { out: { write: () => true } }).warn(type, msg);
@@ -3726,7 +3096,7 @@ function runSupervise(opts) {
         superviseLoop,
         createSuperviseRunQueue,
         createIngestHook,
-        cmdRun: (o) => cmdRun(o),
+        cmdRun: (o) => runRun(o),
         CliExitError,
     });
 }
@@ -3746,12 +3116,59 @@ function runStatus(opts = {}) {
         CliExitError,
     });
 }
+/** `factory run` (#2800): the handler lives in ./run.ts; this binds its runtime. */
+function runRun(opts = {}) {
+    return cmdRun(opts, {
+        configLoaders,
+        coreOps,
+        shellOps,
+        readCosts: internalOps.readCosts,
+        getRepoRoot: () => getRepoRoot(),
+        getGitHubRepo: () => getGitHubRepo(),
+        getOctokit: () => getOctokit(),
+        branchPrefixOrExit,
+        withRepoRunLock,
+        runAutoWorktreeGc,
+        planRunLanes,
+        preflightQueuedIssue,
+        createQueuePreflightOps,
+        warnQueueDiagnostics,
+        resolveUsageKnobs,
+        usageFlagOverrides,
+        usageWatchSourceLabel,
+        probeClaudeKeychain,
+        startLaneProxy,
+        sweepBetweenLaneIssues,
+        reapParkedLaneWorktree,
+        reconstructHumanEventsForKpis,
+        appendKpiSnapshot,
+        CliExitError,
+    });
+}
+/** `factory doctor` (#2799): the handler lives in ./doctor.ts; this binds its runtime. */
+function runDoctor(opts = {}) {
+    return cmdDoctor(opts, {
+        shellOps,
+        coreOps,
+        internalOps,
+        configLoaders,
+        getGitHubRepo: () => getGitHubRepo(),
+        getOctokit: () => getOctokit(),
+        hasGitHubToken: () => hasGitHubToken(),
+        scanGreenPrs,
+        probeClaudeKeychain,
+        toLeaseRow,
+        gcWorktreeSandbox,
+        repoConfigFileFor,
+        isCommandAvailableViaShell,
+    });
+}
 export const PROGRAM_HANDLERS = {
     cmdInit,
     cmdMigrate,
     cmdConstitution,
     cmdModels,
-    cmdDoctor,
+    cmdDoctor: runDoctor,
     cmdCost,
     cmdUsage,
     cmdStatus: runStatus,
@@ -3783,7 +3200,7 @@ export const PROGRAM_HANDLERS = {
     cmdLocalSmallOvernight,
     cmdLand,
     cmdResumeApproved,
-    cmdRun,
+    cmdRun: runRun,
     cmdProxy,
     cmdFactoryd,
     cmdDaemonStart,