@on-par/factory-cli 0.0.0-stage → 0.9.0

package/dist/cli/index.js

@@ -0,0 +1,4801 @@
+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, 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, relative, resolve } from 'node:path';
+import { promisify, styleText } from 'node:util';
+import { BRANCH_PREFIX_MATCH_OPTION_DESCRIPTION, BRANCH_PREFIX_OPTION_DESCRIPTION, INVALID_BRANCH_PREFIX_MESSAGE, resolveBranchPrefixOption, } from './branch-prefix.js';
+import { acquirePortLease, aggregateCosts, appendKpiHistoryLine, applyRepoConfig, buildPhase, checkPhase, clearProxyState, closedWorkSkipReason, computeHealthKpis, ConstitutionLoader, createDefaultWorkSourceRegistry, createFileApprovalGate, createLogger, createLaneProxy, defaultFindPortListeners, describeEffectiveConfig, detectPostMergeDefects, diagnoseModels, drainSteering, estimateTrailingSpend, fetchDefectSources, fetchHumanEventSources, fetchSubscriptionUsage, formatKpiLines, formatUsageReport, getConstitutionsDir, getFactoryPaths, GITHUB_ISSUE_SOURCE, hasUnresolvedPark, InvalidArtifactsDirError, InvalidWorkRequestInputError, InvalidWorkspaceError, inspectPortLeases, isCommandAvailable, isProxyRunning, kpisToHistoryRecord, laneBaseUrl, laneEnv, LaneFileGuard, laneHostLabel, listQueuedSteering, loadFactoryConfigForRepo, loadModelsConfig, loadRepoConfig, loadRoutesConfig, LOCAL_BRIEF_SOURCE, localOnlyWorkspace, joinClassifierOutcomes, mergeClassifierOutcomes, parseClassifierOutcomes, summarizeClassifierOutcomes, formatClassifierReport, mergedPrRefs, ModelRegistry, ModelRouter, parkReasonFor, parseKpiHistory, parseQueue, partitionLocalQueueByActivity, phaseSnapshotFile, planPhase, provisionLaneContainer, ProviderBreaker, readEvents, readPortLeases, readQueue, readUsage, reapOrphanProcesses, reapStalePortLeases, reconstructHumanEvents, recordLeasePgid, releasePortLease, renderKpiReport, renderKpiTrend, resolveAutoFailover, resolveCodexDisabled, resolveDefectWindowDays, resolveBuildPublish, resolveSizeGateMode, parseSizeGateMode, parseMaxSlices, resolveSizeGateMaxSlices, SIZE_GATE_MODES, resolveDesignRegressionBlock, resolveEffectiveModelPins, resolveEfficiencyPolicy, resolveLaneBreakerThreshold, resolveEnvironmentPorts, resolveEnvironmentProxy, resolveArtifactsDir, resolveIngestConfig, resolveLocalOnlyPolicy, resolveMergePolicy, resolvePlanApproval, resolveProcessGroupGraceMs, resolveSandboxPolicy, resolveSkipCI, resolveTimeouts, resolveUsageCap, resolveWatchdogPolicy, ReworkHistory, rewriteQueueForDecomposition, runAutoIngest, runIssue, shipPhase, summarizeEvent, formatCostTotal, touchLastEvent, touchRunActivity, validateQueue, watchUsage, worktreeWorkspace, writeBenchmarkArtifacts, writeLocalRunReport, writePhaseSnapshot, writeProxyState, } from '@on-par/factory-core';
+import { acquirePidFile, currentSlice, egressSummaryMessage, findSlicePlanComment, upsertSlicePlanComment, withSliceState, DEFAULT_GARDEN_MAX_CLUSTERS, DEFAULT_GARDEN_SINCE, capGardenClusters, clusterGarden, dedupGardenClusters, filterGardenOnlyNew, filterGardenWindow, markGardenTrackingUnknown, parseGardenDuration, readHarvestEvents, renderGardenJson, renderGardenReport, formatWorktreeLocation, laneWorktreePath, resolveWorktreeRoot, migrateRepoConfigToYaml, REPO_CONFIG_YAML_HEADER, branchFor, claudeConfigDirOverride, claudeKeychainService, cleanupWorktree, createDaemonLogSink, factoryBranchIssue, factoryBranchPrefixes, getIssueTitle, LEGACY_BRANCH_PREFIX, createDockerEngine, createFactorydServer, createRunRuntime, createShipExecutor, createGithubQueue, createLocalSmallDryRun, createOctokitFilingClient, createOctokitGreenPrClient, createOctokitQueueClient, daemonRuntimePaths, DEFAULT_FACTORYD_PORT, ensureDir, FACTORY_RUNTIME_CONFIG_KEYS, findUnmergedGreenPrs, formatGcReport, gitFetch, isAutoMergeBlocked, listMicroVms, listOrphanContainers, logCost, logEvent, microVmName, planQueueMigration, readCosts, readGithubQueueSnapshot, reapLaneWorktree, reapOrphanContainers, reapOrphanMicroVm, releaseRuntimeFiles, releaseStaleClaims, resolveBranchPrefix, resolveEffectiveConfig, worktreeSandboxFor, resolveExperimental, resolveFilingPolicy, resolveLocalOnly, resolvePrClassifierPolicy, resolveReviewFloorRules, RunLockHeldError, runOvernightQueue, findOpenPR, setupWorktree, shellEscape, shouldProxyEgress, slugify, startEgressProxy, sweepWorktrees, watchChecks, withAdmissionGuard, withFileLock, withGitLock, withRunLock, wrapCommandInSandbox, writePortFile, } from '@on-par/factory-core/internal';
+import { runTui } from '@on-par/factory-tui';
+import { Command } from 'commander';
+import { admissionStateReaderFor, runQueueReconcile } from './admission.js';
+import { cmdClassifierBacktest, ClassifierBacktestInputError, } from './classifier-backtest.js';
+import { runQueueClear } from './queue-clear.js';
+import { buildCostJson } from './cost-json.js';
+import { buildQueueAddJson } from './queue-add-json.js';
+import { buildQueueListJson } from './queue-list.js';
+import { runUnpark, UnparkError } from './unpark.js';
+import { buildRunsJson, parseRunsLimit } from './runs.js';
+import { buildRunDiffstatJson, NoRunError, parseDiffstatIssue } from './runs-diffstat.js';
+import { buildStatusJson } from './status-json.js';
+import { buildStopResumeJson } from './stop-resume-json.js';
+import { buildUsageJson } from './usage-json.js';
+import { parseResetIssues, runReset } from './reset.js';
+import { cmdDaemonLogs, cmdDaemonStart, cmdDaemonStatus, cmdDaemonStop, DaemonCtlError, resolveFactorydConfig, } from './daemon.js';
+import { analyzeEventLog, claudeKeychainCheck, doctorFailed, eventLogCheck, formatClaimReconcileReport, formatContainerReconcileReport, formatDoctorChecks, formatMicroVmReconcileReport, formatReconcileReport, formatWorktreeReconcileReport, leaseChecks, keychainPreflightError, orphanContainerChecks, orphanMicroVmChecks, runDoctorChecks, sandboxClaudeAuthChecks, unmergedGreenPrChecks, } from './doctor.js';
+import { DOCS_URL, formatOverview, missingClaudeCliMessage, missingTokenMessage, notInitializedMessage, } from './first-run.js';
+import { cmdHostedSmoke } from './hosted.js';
+import { cmdHostedQueue } from './hosted-queue.js';
+import { cmdHostedRunner } from './hosted-runner.js';
+import { resolveFactoryCheckoutCommit, runFilingPreview } from './filing.js';
+import { buildFeedbackDeps, runFeedback } from './feedback.js';
+import { ensureFactoryExcluded, writeSampleQueue } from './init-files.js';
+import { cmdLogs } from './logs.js';
+import { applyHelpGroups } from './help-groups.js';
+import { mergeScopeNotice } from './merge-scope.js';
+import { createFactoryOctokit, formatDeprecation } from './octokit.js';
+import { DeepCheckError, createDeepModelRunner, runIssueCheck } from './ready-check.js';
+import { childRunSucceeded, formatChildRunSummary, runChildrenInOrder } from './run-children.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, formatSweepHeartbeatStatusLine, sweepHeartbeatCheck, } from './sweep-heartbeat.js';
+const DEFAULT_CONFIG_LOADERS = {
+    loadModelsConfig,
+    loadRoutesConfig,
+    loadFactoryConfigForRepo,
+    loadRepoConfig,
+    resolveTimeouts,
+    resolveSkipCI,
+    getConstitutionsDir,
+    resolveEffectiveModelPins,
+};
+/** Loaders for the current main() invocation; DEFAULT_CONFIG_LOADERS outside main(). */
+let configLoaders = DEFAULT_CONFIG_LOADERS;
+/** Per-field `??` so an explicit `undefined` override falls back instead of replacing the default. */
+function resolveConfigLoaders(overrides, base = configLoaders) {
+    return {
+        loadModelsConfig: overrides.loadModelsConfig ?? base.loadModelsConfig,
+        loadRoutesConfig: overrides.loadRoutesConfig ?? base.loadRoutesConfig,
+        loadFactoryConfigForRepo: overrides.loadFactoryConfigForRepo ?? base.loadFactoryConfigForRepo,
+        loadRepoConfig: overrides.loadRepoConfig ?? base.loadRepoConfig,
+        resolveTimeouts: overrides.resolveTimeouts ?? base.resolveTimeouts,
+        resolveSkipCI: overrides.resolveSkipCI ?? base.resolveSkipCI,
+        getConstitutionsDir: overrides.getConstitutionsDir ?? base.getConstitutionsDir,
+        resolveEffectiveModelPins: overrides.resolveEffectiveModelPins ?? base.resolveEffectiveModelPins,
+    };
+}
+const DEFAULT_GIT_OPS = { setupWorktree, cleanupWorktree, gitFetch };
+/** Git worktree/fetch ops for the current main() or cmdLand invocation; DEFAULT_GIT_OPS outside them. */
+let gitOps = DEFAULT_GIT_OPS;
+/** Per-field `??` so an explicit `undefined` override falls back instead of replacing the default. */
+function resolveGitOps(overrides, base = gitOps) {
+    return {
+        setupWorktree: overrides.setupWorktree ?? base.setupWorktree,
+        cleanupWorktree: overrides.cleanupWorktree ?? base.cleanupWorktree,
+        gitFetch: overrides.gitFetch ?? base.gitFetch,
+    };
+}
+const DEFAULT_INTERNAL_OPS = {
+    watchChecks,
+    createLocalSmallDryRun,
+    readCosts,
+    sweepWorktrees,
+    releaseStaleClaims,
+    findUnmergedGreenPrs,
+    listOrphanContainers,
+    reapOrphanContainers,
+    listMicroVms,
+    reapOrphanMicroVm,
+    formatGcReport,
+};
+/** factory-core/internal ops for the current main() or cmdLand invocation; DEFAULT_INTERNAL_OPS outside them. */
+let internalOps = DEFAULT_INTERNAL_OPS;
+/** Per-field `??` so an explicit `undefined` override falls back instead of replacing the default. */
+function resolveInternalOps(overrides, base = internalOps) {
+    return {
+        watchChecks: overrides.watchChecks ?? base.watchChecks,
+        createLocalSmallDryRun: overrides.createLocalSmallDryRun ?? base.createLocalSmallDryRun,
+        readCosts: overrides.readCosts ?? base.readCosts,
+        sweepWorktrees: overrides.sweepWorktrees ?? base.sweepWorktrees,
+        releaseStaleClaims: overrides.releaseStaleClaims ?? base.releaseStaleClaims,
+        findUnmergedGreenPrs: overrides.findUnmergedGreenPrs ?? base.findUnmergedGreenPrs,
+        listOrphanContainers: overrides.listOrphanContainers ?? base.listOrphanContainers,
+        reapOrphanContainers: overrides.reapOrphanContainers ?? base.reapOrphanContainers,
+        listMicroVms: overrides.listMicroVms ?? base.listMicroVms,
+        reapOrphanMicroVm: overrides.reapOrphanMicroVm ?? base.reapOrphanMicroVm,
+        formatGcReport: overrides.formatGcReport ?? base.formatGcReport,
+    };
+}
+const promisifiedExec = promisify(execCb);
+const DEFAULT_SHELL_OPS = {
+    exec: async (command, options) => {
+        const { stdout, stderr } = await promisifiedExec(command, { ...options, encoding: 'utf-8' });
+        return { stdout, stderr };
+    },
+    execSync: (command, options) => String(execSync(command, { ...options, encoding: 'utf-8' })),
+};
+/** Shell exec seams for the current main() or cmdLand invocation; DEFAULT_SHELL_OPS outside them. */
+let shellOps = DEFAULT_SHELL_OPS;
+/** Per-field `??` so an explicit `undefined` override falls back instead of replacing the default. */
+function resolveShellOps(overrides, base = shellOps) {
+    return {
+        exec: overrides.exec ?? base.exec,
+        execSync: overrides.execSync ?? base.execSync,
+    };
+}
+const DEFAULT_CORE_OPS = {
+    ModelRouter,
+    ConstitutionLoader,
+    ModelRegistry,
+    isCommandAvailable,
+    defaultFindPortListeners,
+    reapOrphanProcesses,
+    estimateTrailingSpend,
+    formatUsageReport,
+    watchUsage,
+    fetchSubscriptionUsage,
+    diagnoseModels,
+    writeLocalRunReport,
+};
+/** factory-core classes/ops for the current main() invocation; DEFAULT_CORE_OPS outside it. */
+let coreOps = DEFAULT_CORE_OPS;
+/** Per-field `??` so an explicit `undefined` override falls back instead of replacing the default. */
+function resolveCoreOps(overrides, base = coreOps) {
+    return {
+        ModelRouter: overrides.ModelRouter ?? base.ModelRouter,
+        ConstitutionLoader: overrides.ConstitutionLoader ?? base.ConstitutionLoader,
+        ModelRegistry: overrides.ModelRegistry ?? base.ModelRegistry,
+        isCommandAvailable: overrides.isCommandAvailable ?? base.isCommandAvailable,
+        defaultFindPortListeners: overrides.defaultFindPortListeners ?? base.defaultFindPortListeners,
+        reapOrphanProcesses: overrides.reapOrphanProcesses ?? base.reapOrphanProcesses,
+        estimateTrailingSpend: overrides.estimateTrailingSpend ?? base.estimateTrailingSpend,
+        formatUsageReport: overrides.formatUsageReport ?? base.formatUsageReport,
+        watchUsage: overrides.watchUsage ?? base.watchUsage,
+        fetchSubscriptionUsage: overrides.fetchSubscriptionUsage ?? base.fetchSubscriptionUsage,
+        diagnoseModels: overrides.diagnoseModels ?? base.diagnoseModels,
+        writeLocalRunReport: overrides.writeLocalRunReport ?? base.writeLocalRunReport,
+    };
+}
+const DEFAULT_PHASE_OPS = { planPhase, buildPhase, checkPhase, shipPhase };
+/** factory-core phases for the current main() invocation; DEFAULT_PHASE_OPS outside it. */
+let phaseOps = DEFAULT_PHASE_OPS;
+/** Per-field `??` so an explicit `undefined` override falls back instead of replacing the default. */
+function resolvePhaseOps(overrides, base = phaseOps) {
+    return {
+        planPhase: overrides.planPhase ?? base.planPhase,
+        buildPhase: overrides.buildPhase ?? base.buildPhase,
+        checkPhase: overrides.checkPhase ?? base.checkPhase,
+        shipPhase: overrides.shipPhase ?? base.shipPhase,
+    };
+}
+export const PREREQUISITES_TEXT = `Prerequisites:
+  - Claude Code CLI installed and authenticated (Claude subscription): https://claude.com/claude-code
+  - GitHub CLI authenticated: gh auth login
+  - GITHUB_TOKEN or GH_TOKEN set (falls back to \`gh auth token\`)
+Run inside a git repository with a GitHub remote.
+`;
+/** Printed after the command list in `factory --help`: the env vars operators reach for most. */
+export const HELP_FOOTER_TEXT = `
+Common environment variables:
+  FACTORY_MERGE=1                     Squash-merge eligible PRs (--auto-merge / --no-auto-merge win)
+  FACTORY_MERGE_ADMIN=1               Merge with GitHub admin bypass of unmet requirements
+  FACTORY_SKIP_CI=1                   Do not wait for CI before merging
+  FACTORY_SANDBOX=0                   Disable the containment sandbox for agent runs (dangerous)
+  FACTORY_PLAN_MODEL=<id>             Pick the PLAN model
+  FACTORY_BUILD_MODEL=<id>            Pick the BUILD model
+  FACTORY_STOP_AT=<fraction>          Usage fraction (0-1] at which work pauses
+  FACTORY_RESUME_AT=<fraction>        Usage fraction (0-1] at which paused work resumes
+  FACTORY_ALLOW_STALE=1               Run even when the built CLI is older than its source
+Every config key, its default, and its env var: docs/config.example.yaml
+
+Run \`factory <command> --help\` for a command's options.
+Docs: ${DOCS_URL}`;
+// ---------- helpers ----------
+/** PATH probe via the injectable shell seam (mirrors core isCommandAvailable). */
+function isCommandAvailableViaShell(shell, cmd) {
+    try {
+        shell.execSync(`command -v ${cmd} 2>/dev/null`, { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function getRepoRoot(shell = shellOps) {
+    try {
+        const { stdout } = await shell.exec('git rev-parse --show-toplevel');
+        return stdout.trim();
+    }
+    catch {
+        throw new CliExitError('factory: not inside a git repository', 2);
+    }
+}
+async function getGitHubRepo(shell = shellOps) {
+    try {
+        const { stdout } = await shell.exec('gh repo view --json nameWithOwner --jq .nameWithOwner');
+        return stdout.trim();
+    }
+    catch {
+        throw new CliExitError('factory: no GitHub remote detected (gh repo view failed)', 2);
+    }
+}
+/** Env token first, then one `gh auth token` subprocess (≤5 s). `undefined` when neither yields one. */
+function resolveGitHubToken(shell = shellOps) {
+    let token = process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN;
+    if (!token) {
+        try {
+            const out = shell.execSync('gh auth token', { timeout: 5_000 });
+            token = out.trim() || undefined;
+        }
+        catch { }
+    }
+    return token;
+}
+/** Octokit factory for the current main() or cmdLand invocation (CliDeps.octokit); unset outside them. */
+let octokitFactory;
+function getOctokit(shell = shellOps, options) {
+    return octokitFactory ? octokitFactory() : createFactoryOctokit(resolveGitHubToken(shell), options);
+}
+export function errorDetail(err) {
+    const e = err;
+    const stderr = typeof e?.stderr === 'string' ? e.stderr.trim() : '';
+    if (stderr)
+        return stderr;
+    if (typeof e?.message === 'string' && e.message)
+        return e.message;
+    return String(err);
+}
+export function hasGitHubToken(env = process.env, tryToken) {
+    if (env.GITHUB_TOKEN || env.GH_TOKEN)
+        return true;
+    try {
+        const out = (tryToken ?? (() => shellOps.execSync('gh auth token', { timeout: 5_000 })))();
+        return out.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------- commands ----------
+/** The minimal, pin-free repo config `factory init` writes. No model pins → routing
+ *  stays on packaged defaults (policy=auto). YAML (header comment + `version: 2`) by default;
+ *  `'json'` gives two-space JSON + trailing newline for repos that already use config.json.
+ *  Every available key is documented in docs/config.example.jsonc. */
+export function buildInitConfig(format = 'yaml') {
+    if (format === 'json')
+        return JSON.stringify({ version: 2 }, null, 2) + '\n';
+    return REPO_CONFIG_YAML_HEADER + 'version: 2\n';
+}
+/** Write content once without a check-then-act race. Callers choose whether an
+ * existing file is preserved or overwritten. */
+function writeIfAbsent(path, content, label, force = false) {
+    if (force) {
+        writeFileSync(path, content);
+        console.log(styleText('green', `Wrote ${path}`));
+        return;
+    }
+    try {
+        writeFileSync(path, content, { flag: 'wx' });
+        console.log(styleText('green', `Wrote ${path}`));
+    }
+    catch (err) {
+        if (err.code === 'EEXIST') {
+            console.log(styleText('yellow', `${label} exists — leaving as-is (use --force to overwrite)`));
+            return;
+        }
+        throw err;
+    }
+}
+/** One-line onboarding reachability summary, e.g. "policy=auto, 3/7 models reachable". */
+export function formatInitReachability(diagnoses) {
+    const reachable = diagnoses.filter((d) => d.reachable).length;
+    return `policy=auto, ${reachable}/${diagnoses.length} models reachable`;
+}
+async function cmdInit(opts = {}) {
+    const repoRoot = await getRepoRoot();
+    // init itself never calls GitHub, so a missing token is a warning here; ship/run still need one.
+    if (!hasGitHubToken()) {
+        console.error(styleText('yellow', `factory: warning: ${missingTokenMessage()}`));
+    }
+    const paths = getFactoryPaths(repoRoot);
+    ensureDir(paths.root);
+    ensureDir(paths.logs);
+    ensureDir(paths.plans);
+    // Add .factory/ to git exclude
+    ensureFactoryExcluded(resolve(repoRoot, '.git/info/exclude'));
+    // Create sample queue if not exists
+    writeSampleQueue(paths.queue);
+    // Write onboarding files. Idempotent: never clobber an existing file unless --force.
+    const force = opts.force === true;
+    // A fresh repo gets config.yaml; an existing config keeps its own format (--force never switches it).
+    const configPath = existsSync(paths.config) ? paths.config : resolve(paths.root, 'config.yaml');
+    const constitutionPath = resolve(paths.root, 'constitution.md');
+    const gitignorePath = resolve(paths.root, '.gitignore');
+    writeIfAbsent(configPath, buildInitConfig(configPath.endsWith('.json') ? 'json' : 'yaml'), `.factory/${basename(configPath)}`, force);
+    // Constitution scaffold: repo directory basename fills <product-name>/<Product>.
+    const repoName = basename(repoRoot);
+    const template = readFileSync(resolve(configLoaders.getConstitutionsDir(), '_template.md'), 'utf-8');
+    writeIfAbsent(constitutionPath, scaffoldConstitution(template, repoName), '.factory/constitution.md', force);
+    writeIfAbsent(gitignorePath, 'state/\n', '.factory/.gitignore', force);
+    // Doctor-style validation (policy=auto, N models reachable) — informational, never fails init.
+    const modelsConfig = applyRepoConfig(configLoaders.loadModelsConfig(), configLoaders.loadRepoConfig(repoRoot));
+    const registry = new coreOps.ModelRegistry(modelsConfig);
+    const diagnoses = coreOps.diagnoseModels(registry, {}, resolveExperimental(), resolveLocalOnly());
+    console.log(formatInitReachability(diagnoses));
+    if (!hasReachableWorker(diagnoses)) {
+        console.log(styleText('yellow', 'No worker model reachable yet — see `factory doctor` and `factory models --doctor`.'));
+    }
+    console.log(styleText('green', `Initialized ${paths.root}`));
+    console.log(`Next: factory constitution --product <name>, then factory triage`);
+}
+/** Rewrite a checkout's legacy `.factory/` inputs and runtime files to the v2
+ * layout. Every write is idempotent so it is safe to run this more than once. */
+export async function runMigrate(repoRoot, opts = {}) {
+    const dryRun = opts.dryRun === true;
+    const paths = getFactoryPaths(repoRoot);
+    if (opts.toYaml) {
+        let result;
+        try {
+            result = (opts.migrateToYaml ?? migrateRepoConfigToYaml)(paths.root, { dryRun });
+        }
+        catch (err) {
+            throw new CliExitError(`factory: ${err.message}`, 1);
+        }
+        switch (result.status) {
+            case 'migrated':
+                console.log('converted .factory/config.json to .factory/config.yaml');
+                return;
+            case 'would-migrate':
+                console.log('would convert .factory/config.json to .factory/config.yaml');
+                return;
+            case 'already-yaml':
+                console.log(`config already YAML (${basename(result.path)}) — nothing to convert`);
+                return;
+            case 'no-config':
+                console.log('no .factory/config.json — nothing to convert');
+                return;
+            case 'round-trip-failed':
+                throw new CliExitError(`factory: config.yaml did not round-trip (${result.reason}); kept .factory/config.json`, 1);
+        }
+    }
+    const isRuntimePath = (path) => {
+        const fromState = relative(paths.state, path);
+        return fromState !== '' && !fromState.startsWith('..') && !resolve(paths.state, fromState).startsWith('..');
+    };
+    if (!dryRun)
+        mkdirSync(paths.state, { recursive: true });
+    const transientLocks = new Set(['merge.lock', 'git.lock', 'run.lock']);
+    for (const path of Object.values(paths)) {
+        if (!isRuntimePath(path) || transientLocks.has(basename(path)))
+            continue;
+        const legacyPath = resolve(paths.root, basename(path));
+        if (!existsSync(legacyPath) || existsSync(path))
+            continue;
+        if (dryRun) {
+            console.log(`would move ${legacyPath} to ${path}`);
+        }
+        else {
+            renameSync(legacyPath, path);
+            console.log(`moved ${legacyPath} to ${path}`);
+        }
+    }
+    let rawConfig;
+    try {
+        rawConfig = JSON.parse(readFileSync(paths.config, 'utf-8'));
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+    if (!rawConfig) {
+        console.log('no .factory/config.json — nothing to rewrite');
+    }
+    else if (rawConfig.version === 2) {
+        console.log('config.json already v2');
+    }
+    else {
+        const v2 = configLoaders.loadRepoConfig(repoRoot);
+        if (!v2)
+            throw new Error(`Expected ${paths.config} to exist`);
+        const { $schema: _schema, version: _version, ...rest } = v2;
+        // loadRepoConfig only returns the model-routing namespace; carry the runtime-policy
+        // keys (sweep, run, timeouts, ...) over verbatim so the rewrite does not drop them.
+        const source = rawConfig;
+        const runtime = Object.fromEntries(FACTORY_RUNTIME_CONFIG_KEYS.filter((key) => key in source).map((key) => [key, source[key]]));
+        const content = JSON.stringify({
+            ...(typeof rawConfig.$schema === 'string' ? { $schema: rawConfig.$schema } : {}),
+            version: 2,
+            ...rest,
+            ...runtime,
+        }, null, 2) + '\n';
+        if (dryRun) {
+            console.log('would rewrite .factory/config.json to v2');
+        }
+        else {
+            writeFileSync(paths.config, content);
+            console.log('rewrote .factory/config.json to v2');
+        }
+    }
+    const constitutionPath = resolve(paths.root, 'constitution.md');
+    if (!existsSync(constitutionPath)) {
+        const product = readActiveProduct(paths.product);
+        const productConstitution = product ? resolve(configLoaders.getConstitutionsDir(), `${product}.md`) : undefined;
+        const content = productConstitution && existsSync(productConstitution)
+            ? readFileSync(productConstitution, 'utf-8')
+            : scaffoldConstitution(readFileSync(resolve(configLoaders.getConstitutionsDir(), '_template.md'), 'utf-8'), basename(repoRoot));
+        if (dryRun) {
+            console.log('would write .factory/constitution.md');
+        }
+        else {
+            writeIfAbsent(constitutionPath, content, '.factory/constitution.md');
+        }
+    }
+    else {
+        console.log('constitution.md already exists');
+    }
+    const gitignorePath = resolve(paths.root, '.gitignore');
+    if (!existsSync(gitignorePath)) {
+        if (dryRun) {
+            console.log('would write .factory/.gitignore');
+        }
+        else {
+            writeIfAbsent(gitignorePath, 'state/\n', '.factory/.gitignore');
+        }
+    }
+    else {
+        console.log('.gitignore already exists');
+    }
+    console.log(dryRun ? 'Migration preview complete.' : 'Migrated .factory/ to the v2 layout.');
+    console.log('Verify: factory status');
+}
+async function cmdMigrate(opts = {}) {
+    await runMigrate(await getRepoRoot(), opts);
+}
+export class InvalidProductNameError extends Error {
+}
+/** Expected user-facing CLI failure. Thrown by command helpers; only main() maps it to a process exit code. */
+export class CliExitError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'CliExitError';
+    }
+}
+/** Parse a CLI <issue> argument. Throws CliExitError(2) before any git/GitHub work runs. */
+export function parseIssueArg(raw) {
+    const trimmed = raw.trim();
+    if (!/^\d+$/.test(trimmed) || Number(trimmed) < 1) {
+        throw new CliExitError(`factory: invalid issue argument '${raw}' — expected a positive integer issue number`, 2);
+    }
+    return Number(trimmed);
+}
+/** Run `factory feedback` and print the filed issue; validation errors become exit-2 CliExitErrors. */
+export async function runFeedbackCommand(prUrl, opts, deps, log = console.log) {
+    try {
+        const result = await runFeedback(prUrl, opts, deps);
+        log(`Filed ${result.repo}#${result.issueNumber}`);
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.startsWith('factory feedback:'))
+            throw new CliExitError(err.message, 2);
+        throw err;
+    }
+}
+export async function cmdFeedback(prUrl, opts) {
+    const paths = getFactoryPaths(await getRepoRoot());
+    const prefix = opts.branchPrefix === undefined ? resolveBranchPrefix() : branchPrefixOrExit(opts.branchPrefix);
+    await runFeedbackCommand(prUrl, opts, buildFeedbackDeps(getOctokit(), paths, prefix, createOctokitFilingClient));
+}
+async function resolveFactoryCommit() {
+    return resolveFactoryCheckoutCommit(dirname(fileURLToPath(import.meta.url)), async (cmd, cwd) => (await shellOps.exec(cmd, { cwd })).stdout);
+}
+export async function cmdFilingPreview(runId, opts) {
+    const paths = getFactoryPaths(await getRepoRoot());
+    const prefix = opts.branchPrefix === undefined ? resolveBranchPrefix() : branchPrefixOrExit(opts.branchPrefix);
+    const found = await runFilingPreview(runId, {
+        out: process.stdout,
+        err: process.stderr,
+        eventsFile: paths.events,
+        runsDir: daemonRuntimePaths().runsDir,
+        factoryVersion: getCliVersion(),
+        factoryCommit: resolveFactoryCommit,
+        os: `${platform()} ${release()} ${arch()}`,
+        nodeVersion: process.version,
+        usernames: [userInfo().username],
+        hostnames: [osHostname()],
+        branchPrefix: prefix,
+    });
+    if (!found)
+        throw new CliExitError(`no failure evidence found for run ${runId}`, 2);
+}
+function branchPrefixOrExit(raw) {
+    const prefix = resolveBranchPrefixOption(raw);
+    if (prefix === null)
+        throw new CliExitError(INVALID_BRANCH_PREFIX_MESSAGE, 2);
+    return prefix;
+}
+function sizeGateOrExit(raw) {
+    if (raw === undefined)
+        return undefined;
+    const mode = parseSizeGateMode(raw);
+    if (mode === undefined) {
+        throw new CliExitError(`factory: invalid --size-gate '${raw}' — expected one of: ${SIZE_GATE_MODES.join(', ')}`, 2);
+    }
+    return mode;
+}
+function maxSlicesOrExit(raw) {
+    if (raw === undefined)
+        return undefined;
+    const n = parseMaxSlices(raw);
+    if (n === undefined) {
+        throw new CliExitError(`factory: invalid --max-slices '${raw}' — expected a whole number from 1 to 20`, 2);
+    }
+    return n;
+}
+/** Deterministic run number for a brief, derived from its content digest.
+ *  Reserved 9,000,000+ range keeps brief branches/worktrees clear of real issue numbers. */
+function briefRunNumber(sha256Hex) {
+    return 9_000_000 + (Number.parseInt(sha256Hex.slice(0, 8), 16) % 1_000_000);
+}
+// Product names become a filename in the constitutions dir; keep them to a safe,
+// listable charset. Leading '_' is reserved (listProducts hides `_*.md`).
+export function assertValidProduct(product) {
+    if (!/^[a-z0-9][a-z0-9._-]*$/i.test(product)) {
+        throw new InvalidProductNameError(`invalid product name '${product}': use letters, digits, '.', '_' or '-' and do not start with '_' or '.'`);
+    }
+}
+/**
+ * Read the active product name from the `.factory/product` file.
+ * Returns the trimmed content, or undefined when the file is missing
+ * or contains only whitespace.
+ */
+export function readActiveProduct(productPath, deps = {}) {
+    const { fileExists = existsSync, readFile = (p) => readFileSync(p, 'utf-8') } = deps;
+    if (!fileExists(productPath))
+        return undefined;
+    const product = readFile(productPath).trim();
+    return product || undefined;
+}
+/** Extract the template's ```markdown skeleton and fill in the product name. */
+export function scaffoldConstitution(template, product) {
+    const match = template.match(/```markdown\n([\s\S]*?)```/);
+    if (!match) {
+        throw new Error('constitution template is missing its ```markdown skeleton block');
+    }
+    const skeleton = match[1].replace(/\s+$/, '') + '\n';
+    const display = product
+        .split(/[-_]/)
+        .filter(Boolean)
+        .map((w) => w[0].toUpperCase() + w.slice(1))
+        .join(' ');
+    return skeleton.replaceAll('<product-name>', JSON.stringify(product)).replaceAll('<Product>', display);
+}
+export async function cmdConstitution(opts, deps = {}) {
+    const loader = new (resolveCoreOps(deps).ConstitutionLoader)();
+    if (typeof opts.init === 'string' || opts.init === true) {
+        const product = typeof opts.init === 'string' ? opts.init : undefined;
+        if (product !== undefined) {
+            try {
+                assertValidProduct(product);
+            }
+            catch (err) {
+                if (err instanceof InvalidProductNameError) {
+                    throw new CliExitError(err.message, 2);
+                }
+                throw err;
+            }
+        }
+        const repoRoot = await getRepoRoot();
+        const paths = getFactoryPaths(repoRoot);
+        ensureDir(paths.root);
+        const constitutionPath = resolve(paths.root, 'constitution.md');
+        if (existsSync(constitutionPath) && !opts.force) {
+            throw new CliExitError('.factory/constitution.md already exists — use --force to overwrite', 1);
+        }
+        const template = readFileSync(resolve(configLoaders.getConstitutionsDir(), '_template.md'), 'utf-8');
+        const content = scaffoldConstitution(template, product ?? basename(repoRoot));
+        writeIfAbsent(constitutionPath, content, '.factory/constitution.md', opts.force);
+        console.log(`Next: factory constitution --product ${product ?? basename(repoRoot)}`);
+        return;
+    }
+    if (opts.list) {
+        const products = loader.listProducts();
+        for (const p of products)
+            console.log(`  ${p}`);
+        return;
+    }
+    if (opts.product) {
+        const products = loader.listProducts();
+        if (!products.includes(opts.product)) {
+            throw new CliExitError(`No constitution '${opts.product}' found. Available products: ${products.join(', ')}`, 1);
+        }
+        const repoRoot = await getRepoRoot();
+        const paths = getFactoryPaths(repoRoot);
+        ensureDir(paths.root);
+        const constitutionPath = resolve(paths.root, 'constitution.md');
+        if (existsSync(constitutionPath) && !opts.force) {
+            throw new CliExitError('.factory/constitution.md already exists — use --force to overwrite', 1);
+        }
+        const content = readFileSync(resolve(configLoaders.getConstitutionsDir(), `${opts.product}.md`), 'utf-8');
+        writeIfAbsent(constitutionPath, content, '.factory/constitution.md', opts.force);
+        ensureDir(paths.state);
+        writeFileSync(paths.product, opts.product);
+        console.log(styleText('green', `Active product: ${opts.product}`));
+        return;
+    }
+    throw new CliExitError('usage: factory constitution --init <product> | --list | --product <name>', 2);
+}
+export function formatDoctorReport(diagnoses) {
+    const lines = [styleText('bold', '\n== Model Doctor ==')];
+    for (const d of diagnoses) {
+        const icon = d.reachable ? styleText('green', '✅') : styleText('red', '❌');
+        const tiers = d.tiers.join('/');
+        lines.push(`  ${icon} ${d.model} provider=${d.provider} tier=${tiers} — ${d.reason}`);
+    }
+    return lines.join('\n');
+}
+export function hasReachableWorker(diagnoses) {
+    return diagnoses.some((d) => d.reachable && (d.tiers.includes('worker') || d.tiers.includes('worker_fallback')));
+}
+function ollamaModelSet() {
+    try {
+        const out = shellOps.execSync('ollama list', { timeout: 10_000 });
+        return new Set(out
+            .split('\n')
+            .slice(1)
+            .map((line) => line.trim().split(/\s+/)[0])
+            .filter(Boolean));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function cmdModels(opts = {}) {
+    const repoRoot = await getRepoRoot();
+    const modelsConfig = applyRepoConfig(configLoaders.loadModelsConfig(), configLoaders.loadRepoConfig(repoRoot));
+    const registry = new coreOps.ModelRegistry(modelsConfig);
+    const allowExperimental = resolveExperimental();
+    const localOnly = resolveLocalOnly();
+    if (opts.doctor) {
+        const ollamaModels = ollamaModelSet();
+        const diagnoses = coreOps.diagnoseModels(registry, {
+            ollamaModelPresent: ollamaModels ? (model) => ollamaModels.has(model) : undefined,
+        }, allowExperimental, localOnly);
+        console.log(formatDoctorReport(diagnoses));
+        if (!hasReachableWorker(diagnoses)) {
+            throw new CliExitError('factory: no worker model is reachable — fix the reasons above before running a queue', 1);
+        }
+        return;
+    }
+    console.log(styleText('bold', '\n== Available Models =='));
+    for (const m of registry.list()) {
+        const tiers = registry.getTiers(m).join('/');
+        const est = registry.estimateCost(m, 1_000_000, 1_000_000);
+        const cost = est === null ? 'unpriced' : `$${est.toFixed(2)}/M`;
+        const gated = registry.isExperimental(m) && !allowExperimental;
+        const avail = !gated && registry.isAvailable(m) ? styleText('green', '✅') : styleText('red', '❌');
+        const tag = registry.isExperimental(m) ? styleText('yellow', ' [experimental]') : '';
+        console.log(`  ${avail} ${m} tier=${tiers} ${cost}${tag}`);
+    }
+    console.log(styleText('bold', '\n== Tiers =='));
+    for (const tier of ['boss', 'worker', 'checker', 'triage']) {
+        const models = registry.getModelsInTier(tier);
+        console.log(`  ${tier}: ${models.join(' ')}`);
+    }
+}
+async function cmdCost(opts = {}) {
+    const repoRoot = await getRepoRoot();
+    const paths = getFactoryPaths(repoRoot);
+    if (opts.json) {
+        let jsonCosts;
+        try {
+            jsonCosts = internalOps.readCosts(paths.costs);
+        }
+        catch (err) {
+            throw new CliExitError(`factory: cost failed — ${errorDetail(err)}`, 1);
+        }
+        console.log(JSON.stringify(buildCostJson(jsonCosts, opts.issue)));
+        return;
+    }
+    const costs = internalOps.readCosts(paths.costs);
+    if (opts.issue) {
+        const filtered = costs.filter((c) => c.issue === String(opts.issue));
+        if (filtered.length === 0) {
+            console.log(`no cost data for issue ${opts.issue}`);
+            return;
+        }
+        console.log(styleText('bold', `== Costs for issue ${opts.issue} ==`));
+        for (const c of filtered) {
+            console.log(`  ${c.task} ${c.model} ${c.cost === null || c.cost === undefined ? 'unknown' : `$${c.cost.toFixed(4)}`}${c.failoverReason ? ` [failover: ${c.failoverReason}]` : ''}`);
+        }
+        const t = aggregateCosts(filtered).total;
+        console.log('  ---');
+        console.log(`  Total: ${formatCostTotal(t.cost, t.unpricedCount)}`);
+        return;
+    }
+    if (costs.length === 0) {
+        console.log('no cost data yet');
+        return;
+    }
+    const byModel = new Map();
+    for (const c of costs) {
+        const e = byModel.get(c.model) ?? { tasks: 0, priced: 0, pricedCount: 0, unpriced: 0, failovers: 0 };
+        e.tasks++;
+        if (c.unpriced === true || c.cost === null || c.cost === undefined)
+            e.unpriced++;
+        else {
+            e.priced += c.cost;
+            e.pricedCount++;
+        }
+        if (c.failoverReason)
+            e.failovers++;
+        byModel.set(c.model, e);
+    }
+    console.log(styleText('bold', '== Cost Summary =='));
+    for (const [model, { tasks, priced, pricedCount, unpriced, failovers }] of byModel) {
+        const failoverSuffix = failovers > 0 ? ` (${failovers} failover${failovers === 1 ? '' : 's'})` : '';
+        const modelCost = formatCostTotal(pricedCount === 0 && unpriced > 0 ? null : priced, unpriced);
+        console.log(`  ${model}: ${tasks} tasks, ${modelCost}${failoverSuffix}`);
+    }
+    const grand = aggregateCosts(costs).total;
+    console.log('  ---');
+    console.log(`  Total: ${formatCostTotal(grand.cost, grand.unpricedCount)}`);
+}
+async function cmdCheck(issueRaw, opts) {
+    const issueNum = parseIssueArg(issueRaw);
+    const ghRepo = await getGitHubRepo();
+    const [owner, repoName] = ghRepo.split('/');
+    let runModel;
+    if (opts.deep) {
+        const repoRoot = await getRepoRoot();
+        const repoConfig = configLoaders.loadRepoConfig(repoRoot);
+        const effective = resolveEffectiveConfig(repoConfig);
+        const router = new coreOps.ModelRouter(applyRepoConfig(configLoaders.loadModelsConfig(), repoConfig), configLoaders.loadRoutesConfig(), false, undefined, effective.allowExperimental, effective.localOnly);
+        runModel = createDeepModelRunner(router, repoRoot);
+    }
+    let report;
+    try {
+        report = await runIssueCheck(issueNum, opts, {
+            runModel,
+            getIssue: async (n) => {
+                const { data } = await getOctokit().rest.issues.get({ owner, repo: repoName, issue_number: n });
+                return { title: data.title, body: data.body ?? null };
+            },
+            getIssueState: async (n) => {
+                const { data } = await getOctokit().rest.issues.get({ owner, repo: repoName, issue_number: n });
+                return data.state === 'closed' ? 'closed' : 'open';
+            },
+            log: (line) => console.log(line),
+        });
+    }
+    catch (err) {
+        if (err instanceof DeepCheckError)
+            throw new CliExitError(`factory: --deep failed — ${err.message}`, 2);
+        throw err;
+    }
+    if (report.exitCode === 1) {
+        throw new CliExitError(`factory: issue #${issueNum} is not factory-ready — ${report.reasons.join('; ')}`, 1);
+    }
+    if (report.exitCode === 3) {
+        throw new CliExitError(`factory: issue #${issueNum} would split — ${report.size.reason}`, 3);
+    }
+}
+async function currentCommitSha() {
+    try {
+        const { stdout } = await shellOps.exec('git rev-parse HEAD');
+        return stdout.trim();
+    }
+    catch {
+        return null;
+    }
+}
+function resolvedModelTiers(repoRoot, stateRoot) {
+    const modelsConfig = applyRepoConfig(configLoaders.loadModelsConfig(), configLoaders.loadRepoConfig(repoRoot, stateRoot));
+    return modelsConfig.tiers ?? {};
+}
+function readTextFileOrEmpty(path) {
+    try {
+        return readFileSync(path, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return '';
+        throw err;
+    }
+}
+async function appendKpiSnapshot(paths, repoRoot, kpis) {
+    const record = kpisToHistoryRecord(kpis, new Date().toISOString().slice(0, 10), {
+        commitSha: await currentCommitSha(),
+        models: resolvedModelTiers(repoRoot, paths.root),
+    });
+    const updated = appendKpiHistoryLine(readTextFileOrEmpty(paths.kpiHistory), record);
+    ensureDir(paths.state);
+    writeFileSync(paths.kpiHistory, updated);
+    return { record, history: parseKpiHistory(updated) };
+}
+function persistClassifierOutcomes(paths, events, sources, opts) {
+    const records = joinClassifierOutcomes(events, sources, opts);
+    if (records.length === 0)
+        return;
+    const updated = mergeClassifierOutcomes(readTextFileOrEmpty(paths.classifierOutcomes), records);
+    ensureDir(paths.state);
+    writeFileSync(paths.classifierOutcomes, updated);
+}
+async function cmdClassifierReport(opts = {}) {
+    const repoRoot = await getRepoRoot();
+    const paths = getFactoryPaths(repoRoot);
+    const report = summarizeClassifierOutcomes(parseClassifierOutcomes(readTextFileOrEmpty(paths.classifierOutcomes)));
+    if (opts.json) {
+        console.log(JSON.stringify(report));
+        return;
+    }
+    for (const line of formatClassifierReport(report))
+        console.log(line);
+}
+async function cmdClassifierBacktestEntry(opts) {
+    const branchPrefix = branchPrefixOrExit(opts.branchPrefix);
+    const repoRoot = await getRepoRoot();
+    const paths = getFactoryPaths(repoRoot);
+    const [owner, repo] = (await getGitHubRepo()).split('/');
+    const repoConfig = configLoaders.loadRepoConfig(repoRoot);
+    const effective = resolveEffectiveConfig(repoConfig);
+    const router = new coreOps.ModelRouter(applyRepoConfig(configLoaders.loadModelsConfig(), repoConfig), configLoaders.loadRoutesConfig(), false, undefined, effective.allowExperimental, effective.localOnly);
+    try {
+        await cmdClassifierBacktest({ ...opts, branchPrefix }, {
+            repoRoot,
+            paths,
+            owner,
+            repo,
+            octokit: getOctokit(),
+            router,
+            rules: resolveReviewFloorRules(repoConfig),
+            modelPin: repoConfig?.models?.pins?.classifier,
+            windowDays: resolveDefectWindowDays(configLoaders.loadFactoryConfigForRepo(paths.config)),
+            exec: (cmd) => shellOps.exec(cmd, { cwd: repoRoot }),
+            readFile: (path) => readFileSync(path, 'utf-8'),
+            appendFile: (path, text) => appendFileSync(path, text),
+            ensureDir,
+            readEvents: (path) => (existsSync(path) ? readEvents(path) : []),
+            now: () => new Date().toISOString(),
+            log: (line) => console.log(line),
+        });
+    }
+    catch (err) {
+        if (err instanceof ClassifierBacktestInputError)
+            throw new CliExitError(err.message, 2);
+        throw err;
+    }
+}
+/** Read-only GitHub search dedup (#2102); on any error every cluster is marked tracking unknown (#2103). */
+async function annotateGardenClusters(clusters) {
+    const warn = (err) => console.error(`factory garden: issue search unavailable, tracking unknown: ${errorDetail(err)}`);
+    try {
+        const [owner, repo] = (await getGitHubRepo()).split('/');
+        if (!owner || !repo)
+            throw new Error('cannot resolve the GitHub repository');
+        return await dedupGardenClusters(clusters, {
+            client: createOctokitFilingClient(getOctokit()),
+            owner,
+            repo,
+            onSearchError: warn,
+        });
+    }
+    catch (err) {
+        warn(err);
+        return markGardenTrackingUnknown(clusters);
+    }
+}
+async function cmdGarden(opts = {}) {
+    if (!opts.report) {
+        console.error('factory garden: pass --report (the only mode in this release)');
+        process.exit(1);
+    }
+    const since = opts.since ?? DEFAULT_GARDEN_SINCE;
+    const windowMs = parseGardenDuration(since);
+    if (windowMs === undefined) {
+        console.error(`factory garden: --since must look like 7d, 36h or 2w (got ${since})`);
+        process.exit(1);
+    }
+    const maxRaw = opts.maxClusters ?? String(DEFAULT_GARDEN_MAX_CLUSTERS);
+    if (!/^\d+$/.test(maxRaw) || Number(maxRaw) < 1) {
+        console.error(`factory garden: --max-clusters must be a positive integer (got ${maxRaw})`);
+        process.exit(1);
+    }
+    const maxClusters = Number(maxRaw);
+    const repoRoot = await getRepoRoot();
+    const paths = getFactoryPaths(repoRoot);
+    const events = filterGardenWindow(readHarvestEvents([paths.events]), windowMs, new Date());
+    const clusters = capGardenClusters(clusterGarden(events), maxClusters);
+    const annotated = clusters.length === 0 ? clusters : await annotateGardenClusters(clusters);
+    const shown = opts.onlyNew ? filterGardenOnlyNew(annotated) : annotated;
+    const text = opts.json ? renderGardenJson(shown, { since, maxClusters }) : renderGardenReport(shown).join('\n');
+    if (opts.out) {
+        try {
+            writeFileSync(opts.out, `${text}\n`);
+        }
+        catch (err) {
+            console.error(`factory garden: cannot write ${opts.out}: ${err.message}`);
+            process.exit(1);
+        }
+        console.error(`factory garden: wrote report to ${opts.out}`);
+        return;
+    }
+    if (opts.json)
+        console.log(text);
+    else
+        for (const line of text.split('\n'))
+            console.log(line);
+}
+async function cmdKpis(opts = {}) {
+    const branchPrefix = branchPrefixOrExit(opts.branchPrefix);
+    const repoRoot = await getRepoRoot();
+    const paths = getFactoryPaths(repoRoot);
+    const events = existsSync(paths.events) ? readEvents(paths.events) : [];
+    const costs = existsSync(paths.costs) ? internalOps.readCosts(paths.costs) : [];
+    let allEvents = events;
+    let prSources = [];
+    let owner = '';
+    let repoName = '';
+    try {
+        const ghRepo = await getGitHubRepo();
+        [owner, repoName] = ghRepo.split('/');
+        const issues = new Set(events.map((e) => e.issue).filter((i) => /^\d+$/.test(i)));
+        prSources = await fetchHumanEventSources(getOctokit(), owner, repoName, issues, branchPrefix);
+        allEvents = [...events, ...reconstructHumanEvents(prSources, events)];
+    }
+    catch (err) {
+        console.error(styleText('yellow', `factory: GitHub human-event reconstruction unavailable (${err?.message ?? err}) — KPIs use the local log only`));
+    }
+    if (prSources.length > 0) {
+        try {
+            const windowDays = resolveDefectWindowDays(configLoaders.loadFactoryConfigForRepo(paths.config));
+            const now = new Date().toISOString();
+            const merged = mergedPrRefs(prSources);
+            const sources = await fetchDefectSources(getOctokit(), owner, repoName, merged, { now, windowDays });
+            allEvents = [...allEvents, ...detectPostMergeDefects(sources, allEvents, { now, windowDays })];
+            try {
+                persistClassifierOutcomes(paths, allEvents, prSources, { now, windowDays });
+            }
+            catch (err) {
+                console.error(styleText('yellow', `factory: classifier outcomes not recorded (${err?.message ?? err})`));
+            }
+        }
+        catch (err) {
+            console.error(styleText('yellow', `factory: post-merge defect signals unavailable (${err?.message ?? err}) — postMergeDefectRate omitted from this snapshot`));
+        }
+    }
+    const kpis = computeHealthKpis(allEvents, costs);
+    let history;
+    try {
+        ({ history } = await appendKpiSnapshot(paths, repoRoot, kpis));
+    }
+    catch (err) {
+        console.error(styleText('yellow', `factory: KPI snapshot failed (${err?.message ?? err}) — showing the report without persisting a new snapshot`));
+        const existing = readTextFileOrEmpty(paths.kpiHistory);
+        history = existing ? parseKpiHistory(existing) : [];
+    }
+    console.log(renderKpiReport(kpis));
+    console.log(renderKpiTrend(history));
+}
+export function resolveUsageKnobs(env = process.env, repoConfig = null, overrides = {}) {
+    const { cap } = resolveUsageCap(repoConfig, env);
+    const watchdog = resolveWatchdogPolicy(repoConfig, env, overrides);
+    return {
+        cap,
+        stopAt: watchdog.stopAt,
+        resumeAt: watchdog.resumeAt,
+        pollMs: watchdog.pollMs,
+        watch: watchdog.watch,
+        estimator: watchdog.estimator,
+        watchSource: watchdog.sources.watch,
+        stopAtSource: watchdog.sources.stopAt,
+        resumeAtSource: watchdog.sources.resumeAt,
+        pollSource: watchdog.sources.pollMs,
+    };
+}
+/** Human-readable name for whatever decided the usage-watch gate, used in the `factory run`
+ *  and `factory supervise` logs so an explicit operator override is always attributable (#1404). */
+export function usageWatchSourceLabel(source, watch) {
+    switch (source) {
+        case 'flag':
+            return watch ? 'flag: --usage-watch' : 'flag: --no-usage-watch';
+        case 'repo':
+            return '.factory/config.json: budget.watchdog.watch';
+        case 'env':
+            return 'env: FACTORY_USAGE_WATCH';
+        default:
+            return 'default';
+    }
+}
+export async function cmdUsage(deps = {}, opts = {}) {
+    const ops = resolveCoreOps(deps);
+    const repoRoot = await getRepoRoot(resolveShellOps(deps));
+    let knobs;
+    try {
+        knobs = resolveUsageKnobs(process.env, configLoaders.loadRepoConfig(repoRoot));
+    }
+    catch (err) {
+        throw new CliExitError(`factory: ${err.message}`, 2);
+    }
+    if (opts.json) {
+        const subscription = await ops.fetchSubscriptionUsage();
+        let estimate;
+        try {
+            const spend = ops.estimateTrailingSpend();
+            estimate = Number.isFinite(spend) ? spend : null;
+        }
+        catch {
+            estimate = null;
+        }
+        console.log(JSON.stringify(buildUsageJson(subscription, estimate, knobs.cap)));
+        return;
+    }
+    const subscriptionPromise = ops.fetchSubscriptionUsage();
+    const spend = ops.estimateTrailingSpend();
+    const heuristicLine = ops.formatUsageReport(spend, knobs.cap);
+    const subscription = await subscriptionPromise;
+    if (subscription !== null) {
+        const resets = subscription.fiveHourResetsAt ? `, resets ${subscription.fiveHourResetsAt}` : '';
+        console.log(`5h subscription usage: ${Math.round(subscription.fiveHourUtilization)}% of plan limit${resets}`);
+        console.log(`heuristic list-price estimate: ${heuristicLine}`);
+    }
+    else {
+        console.log(styleText('yellow', `factory: real subscription usage unavailable — falling back to a rough list-price proxy, not the real subscription limit`));
+        console.log(heuristicLine);
+    }
+}
+function warnQueueDiagnostics(diagnostics) {
+    for (const d of diagnostics) {
+        console.error(styleText('yellow', `factory: queue ${d.message} — skipped`));
+    }
+}
+/** Formats the time since `lastActivityAt` as a short duration (e.g. `3m`) for the
+ *  `factory status` `== Active ==` section's `[phase, <age> ago]` display (#1343). An
+ *  active claim's heartbeat is always within DEFAULT_QUEUE_ACTIVITY_STALE_THRESHOLD_MS
+ *  (15m), so minutes is the only unit that ever shows. */
+function formatClaimAge(lastActivityAt, now) {
+    const ageMs = Math.max(0, now - Date.parse(lastActivityAt));
+    const minutes = Math.floor(ageMs / 60_000);
+    return minutes < 1 ? '<1m' : `${minutes}m`;
+}
+export async function cmdStatus(opts = {}) {
+    if (opts.json) {
+        // `--kpis` is deliberately ignored here: the JSON shape is fixed (#1101).
+        const repoRoot = await getRepoRoot();
+        const paths = getFactoryPaths(repoRoot);
+        if (!existsSync(paths.root))
+            throw new CliExitError(`factory: ${notInitializedMessage()}`, 2);
+        const ghRepo = await getGitHubRepo();
+        let active = [];
+        if (existsSync(paths.queue)) {
+            const { entries, diagnostics } = parseQueue(readFileSync(paths.queue, 'utf-8'));
+            if (entries.length > 0)
+                ({ active } = await partitionLocalQueueByActivity(entries, paths.runs));
+            warnQueueDiagnostics(diagnostics);
+        }
+        console.log(JSON.stringify(buildStatusJson({
+            repo: ghRepo,
+            product: readActiveProduct(paths.product) ?? null,
+            stop: existsSync(paths.stop),
+            breakers: await new ProviderBreaker(paths.breaker).list(),
+            active,
+            now: Date.now(),
+        })));
+        return;
+    }
+    const repoRoot = await getRepoRoot();
+    const ghRepo = await getGitHubRepo();
+    const paths = getFactoryPaths(repoRoot);
+    const repoConfig = configLoaders.loadRepoConfig(repoRoot);
+    const modelsConfig = applyRepoConfig(configLoaders.loadModelsConfig(), repoConfig);
+    const routesConfig = configLoaders.loadRoutesConfig();
+    const effective = resolveEffectiveConfig(repoConfig);
+    const router = new coreOps.ModelRouter(modelsConfig, routesConfig, false, undefined, effective.allowExperimental, effective.localOnly);
+    const product = readActiveProduct(paths.product) ?? '(none)';
+    console.log(styleText('bold', `== ${ghRepo} ==`));
+    console.log(`Product: ${product}`);
+    const worktreeParent = configLoaders.loadFactoryConfigForRepo(paths.config).worktree.parent;
+    console.log(formatWorktreeLocation(resolveWorktreeRoot({ repoRoot, parent: worktreeParent, repo: ghRepo }), worktreeParent));
+    console.log(styleText('bold', '\n== Active =='));
+    if (existsSync(paths.queue)) {
+        const { entries, diagnostics } = parseQueue(readFileSync(paths.queue, 'utf-8'));
+        if (entries.length > 0) {
+            const { active, staleCount } = await partitionLocalQueueByActivity(entries, paths.runs);
+            if (active.length === 0) {
+                console.log('  (idle — no active claims)');
+            }
+            else {
+                const now = Date.now();
+                for (const e of active) {
+                    console.log(`  ${e.lane} ${e.issue}  [${e.phase}, ${formatClaimAge(e.lastActivityAt, now)} ago]`);
+                }
+            }
+            if (staleCount > 0) {
+                console.log(`  (${staleCount} stale entr${staleCount === 1 ? 'y' : 'ies'} hidden — no recent activity)`);
+            }
+        }
+        else if (diagnostics.length === 0) {
+            console.log('  (idle — no active claims)');
+        }
+        warnQueueDiagnostics(diagnostics);
+    }
+    else {
+        console.log('  (no queue file)');
+    }
+    console.log(styleText('bold', '\n== Queue =='));
+    if (!hasGitHubToken()) {
+        console.log('  (no GitHub token — run `gh auth login`)');
+    }
+    else {
+        const [owner, repoName] = ghRepo.split('/');
+        const githubQueue = createGithubQueue({ client: createOctokitQueueClient(getOctokit()), owner, repo: repoName });
+        try {
+            const lanes = await githubQueue.lanes();
+            let printed = false;
+            for (const lane of lanes) {
+                const issues = await githubQueue.list(lane);
+                for (const issue of issues) {
+                    console.log(`  ${lane} #${issue}`);
+                    printed = true;
+                }
+            }
+            if (!printed) {
+                console.log('  (no claimable work)');
+            }
+        }
+        catch (err) {
+            console.log(`  (queue lookup failed — ${errorDetail(err)})`);
+        }
+    }
+    console.log(styleText('bold', '\n== Health =='));
+    if (opts.kpis) {
+        console.log(styleText('bold', '\n  Effective config:'));
+        for (const line of describeEffectiveConfig({
+            router,
+            repo: repoConfig,
+            repoConfigPath: '.factory/config.json',
+            mergePolicy: resolveMergePolicy(configLoaders.loadFactoryConfigForRepo(paths.config), process.env, {
+                auto: readRunFlagOverrides(paths.runFlags).autoMerge,
+            }),
+            prClassifier: resolvePrClassifierPolicy(configLoaders.loadFactoryConfigForRepo(paths.config), process.env, {
+                classifier: readRunFlagOverrides(paths.runFlags).prClassifier,
+            }),
+        })) {
+            console.log(`    ${line}`);
+        }
+    }
+    else {
+        console.log('\n  (Effective config and KPIs hidden — run `factory status --kpis` to view)');
+    }
+    console.log(styleText('bold', '\n  Provider breaker:'));
+    const openBreakers = await new ProviderBreaker(paths.breaker).list();
+    if (openBreakers.length === 0) {
+        console.log('    (closed)');
+    }
+    else {
+        for (const b of openBreakers) {
+            console.log(`    ${b.provider}: OPEN (${b.reason}) — ${Math.ceil(b.remainingMs / 60_000)}m remaining`);
+        }
+    }
+    console.log(styleText('bold', '\n  Sweep heartbeat:'));
+    const sweepStatus = checkSweepHeartbeat(configLoaders.loadFactoryConfigForRepo(paths.config).sweep, process.env, defaultSweepHeartbeatDeps());
+    console.log(`    ${formatSweepHeartbeatStatusLine(sweepStatus)}`);
+    console.log(styleText('bold', '\n  Last Events:'));
+    if (existsSync(paths.events)) {
+        const events = readFileSync(paths.events, 'utf-8').trim().split('\n').slice(-12);
+        for (const e of events) {
+            try {
+                const ev = JSON.parse(e);
+                console.log(`    ${ev.type} #${ev.issue}: ${ev.msg}`);
+            }
+            catch { }
+        }
+    }
+    else {
+        console.log('    (none)');
+    }
+    if (opts.kpis) {
+        console.log(styleText('bold', '\n  KPIs:'));
+        const kpiEvents = existsSync(paths.events) ? readEvents(paths.events) : [];
+        const kpiCosts = existsSync(paths.costs) ? internalOps.readCosts(paths.costs) : [];
+        for (const line of formatKpiLines(computeHealthKpis(kpiEvents, kpiCosts))) {
+            console.log(`    ${line}`);
+        }
+    }
+    if (existsSync(paths.stop)) {
+        console.log(styleText('red', '\n!! STOP file present — factory halting between issues'));
+    }
+}
+/** GitHub is polled far less often than local files: a queue changes on the order of minutes. */
+const TUI_GITHUB_QUEUE_POLL_MS = 30_000;
+/** The Queue tab's backlog source for `factory tui` (#1362). Mirrors `factory run`: GitHub Issues
+ *  by default, the local queue file only under `--local-queue`. Never throws at build time — a
+ *  missing repo or token becomes a snapshot error the tab renders, so the TUI still starts.
+ *
+ *  The token is resolved here, before Ink takes the terminal, so the `gh auth token` subprocess
+ *  never runs inside the first poll. Octokit is built at most once and only on the GitHub path;
+ *  when no token is present at startup, each poll re-resolves it so a `gh auth login` in another
+ *  terminal is picked up without restarting the TUI. */
+export function tuiQueueReader(input) {
+    // Capture the invocation's shell and octokit seams: read() polls after main() has restored the module default.
+    const shell = shellOps;
+    const injectedOctokit = octokitFactory;
+    const defaultOctokit = injectedOctokit ? () => injectedOctokit() : createFactoryOctokit;
+    const { token: resolveToken = () => resolveGitHubToken(shell), octokit = defaultOctokit } = input;
+    if (input.localQueue) {
+        return { source: 'local file', read: () => readQueue(input.queueFile, input.queueProposedFile) };
+    }
+    if (input.repo === undefined) {
+        return {
+            source: 'GitHub',
+            pollMs: TUI_GITHUB_QUEUE_POLL_MS,
+            read: async () => ({ entries: [], error: 'repo detection failed — run inside a GitHub-backed checkout' }),
+        };
+    }
+    const [owner, repoName] = input.repo.split('/');
+    const clientFor = (token) => token === undefined ? undefined : createOctokitQueueClient(octokit(token));
+    let client = clientFor(resolveToken());
+    return {
+        source: 'GitHub',
+        pollMs: TUI_GITHUB_QUEUE_POLL_MS,
+        read: async () => {
+            client ??= clientFor(resolveToken());
+            if (client === undefined)
+                return { entries: [], error: 'no GitHub token — run `gh auth login`' };
+            return readGithubQueueSnapshot({ client, owner, repo: repoName });
+        },
+    };
+}
+async function cmdTui(opts = {}, runTuiImpl = runTui) {
+    const repoRoot = await getRepoRoot();
+    const paths = getFactoryPaths(repoRoot);
+    let repo;
+    try {
+        repo = await getGitHubRepo();
+    }
+    catch {
+        // header just omits the repo
+    }
+    const repoConfig = configLoaders.loadRepoConfig(repoRoot);
+    const modelsConfig = applyRepoConfig(configLoaders.loadModelsConfig(), repoConfig);
+    const routesConfig = configLoaders.loadRoutesConfig();
+    const effective = resolveEffectiveConfig(repoConfig);
+    const router = new coreOps.ModelRouter(modelsConfig, routesConfig, false, undefined, effective.allowExperimental, effective.localOnly);
+    const effectiveConfigLines = describeEffectiveConfig({
+        router,
+        repo: repoConfig,
+        repoConfigPath: '.factory/config.json',
+        mergePolicy: resolveMergePolicy(configLoaders.loadFactoryConfigForRepo(paths.config), process.env, {
+            auto: readRunFlagOverrides(paths.runFlags).autoMerge,
+        }),
+        prClassifier: resolvePrClassifierPolicy(configLoaders.loadFactoryConfigForRepo(paths.config), process.env, {
+            classifier: readRunFlagOverrides(paths.runFlags).prClassifier,
+        }),
+    });
+    await runTuiImpl({
+        eventsFile: paths.events,
+        repo,
+        stopFile: paths.stop,
+        queueReader: tuiQueueReader({
+            localQueue: opts.localQueue === true,
+            queueFile: paths.queue,
+            queueProposedFile: paths.queueProposed,
+            repo,
+        }),
+        costsFile: paths.costs,
+        approvalsDir: paths.approvals,
+        steeringDir: paths.steering,
+        runsDir: paths.runs,
+        breakerFile: paths.breaker,
+        effectiveConfigLines,
+    });
+}
+export { parkEvents, parkReasonFor } from '@on-par/factory-core';
+export class LaneParkError extends Error {
+    outcome;
+    constructor(message, reason, failure) {
+        super(message);
+        this.outcome = {
+            state: 'parked',
+            reason,
+            ...(failure?.failureSignature !== undefined ? { failureSignature: failure.failureSignature } : {}),
+            ...(failure?.failingChecks !== undefined ? { failingChecks: failure.failingChecks } : {}),
+        };
+    }
+    get reason() {
+        return this.outcome.reason;
+    }
+    get failureSignature() {
+        return this.outcome.failureSignature;
+    }
+    get failingChecks() {
+        return this.outcome.failingChecks;
+    }
+}
+/** CHECK found every failing checker also failing on the base SHA (#1928): the issue is
+ *  released to queued (not parked) and the lane pauses. */
+export class LaneEnvironmentPauseError extends Error {
+    baseSha;
+    failingChecks;
+    failureSignature;
+    constructor(message, failure) {
+        super(message);
+        this.baseSha = failure.baseSha;
+        this.failingChecks = failure.failingChecks;
+        if (failure.failureSignature !== undefined)
+            this.failureSignature = failure.failureSignature;
+    }
+}
+/** Resolves the stable lane URL a build/check agent should use, by probing whether
+ *  a factory proxy (started by `factory run`/`supervise` or `factory proxy`) is
+ *  currently alive for the configured domain. Never throws — an absent/dead proxy
+ *  just degrades to the existing port-based URL, single informational note either way. */
+export function resolveLaneBaseUrl(paths, settings, worktree, appPort, deps = {}) {
+    const { isRunning = isProxyRunning } = deps;
+    if (!settings.enabled || appPort === undefined)
+        return { note: '' };
+    const state = isRunning(paths.proxyState);
+    if (state && state.domain === settings.domain) {
+        const baseUrl = laneBaseUrl(worktree, { domain: state.domain, port: state.port });
+        return { baseUrl, note: `stable lane URL ${baseUrl} -> 127.0.0.1:${appPort}` };
+    }
+    return { note: `proxy enabled but not running — using http://127.0.0.1:${appPort}` };
+}
+/** Builds the port-lease acquirer passed to runIssue, or undefined to skip it. A
+ *  docker-sandbox lane runs inside its own microVM network namespace and binds its
+ *  normal port there, so it needs no host port-lease and (since the proxy resolves
+ *  routes solely from the lease registry) no proxy route either — every other
+ *  runtime keeps acquiring a lease exactly as before. */
+export function resolveEnvironmentAcquirer(opts) {
+    const findPortListeners = opts.findPortListeners ?? coreOps.defaultFindPortListeners;
+    const reapProcesses = opts.reapOrphanProcesses ?? coreOps.reapOrphanProcesses;
+    if (opts.laneSandboxRuntime === 'docker-sandbox') {
+        opts.log('environment_lease', `docker-sandbox lane ${opts.worktree} binds its port inside its own microVM — skipping host port-lease`);
+        return undefined;
+    }
+    return async () => {
+        const reaped = [];
+        const lease = await acquirePortLease({
+            registryFile: opts.paths.ports,
+            lockDir: opts.paths.portsLock,
+            worktreeId: opts.worktree,
+            branch: opts.branch,
+            range: opts.range,
+            onReap: (r) => {
+                reaped.push(r);
+                opts.log('environment_lease_reaped', `reaped stale lease: port ${r.lease.port}, pid ${r.lease.pid}, worktree ${r.lease.worktreeId} — reason: ${r.reason}`);
+            },
+            onPortConflict: (port) => {
+                void findPortListeners(port)
+                    .then((listeners) => {
+                    const detail = listeners.length > 0
+                        ? listeners.map((l) => `pid ${l.pid} (${l.command})`).join(', ')
+                        : 'no listener details available';
+                    opts.log('environment_conflict', `port ${port} busy but unleased — reported as conflict, not terminated: ${detail}`);
+                })
+                    .catch(() => {
+                    opts.log('environment_conflict', `port ${port} busy but unleased — reported as conflict, not terminated`);
+                });
+            },
+        });
+        opts.log('environment_lease', `leased port ${lease.port} for worktree ${opts.worktree}`);
+        if (reaped.length > 0) {
+            await reapProcesses({
+                reaped,
+                graceMs: opts.processGroupGraceMs,
+                onEvent: (e) => opts.log('environment_orphan', `${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' : ''}`),
+            });
+        }
+        return {
+            port: lease.port,
+            env: () => laneEnv(lease.port, process.env),
+            recordPgid(pgid) {
+                void recordLeasePgid({
+                    registryFile: opts.paths.ports,
+                    lockDir: opts.paths.portsLock,
+                    worktreeId: opts.worktree,
+                    pgid,
+                }).catch(() => { });
+            },
+            async release() {
+                await releasePortLease({
+                    registryFile: opts.paths.ports,
+                    lockDir: opts.paths.portsLock,
+                    worktreeId: opts.worktree,
+                });
+            },
+        };
+    };
+}
+export async function shipIssue(issueNum, opts, ctx, deps = {}) {
+    const loaders = resolveConfigLoaders(deps);
+    const git = resolveGitOps(deps);
+    const shell = resolveShellOps(deps);
+    const core = resolveCoreOps(deps);
+    const phases = resolvePhaseOps(deps);
+    const repoRoot = ctx?.repoRoot ?? (await getRepoRoot(shell));
+    const ghRepo = ctx?.ghRepo ?? (await getGitHubRepo(shell));
+    const paths = ctx?.paths ?? getFactoryPaths(repoRoot);
+    // GitHub REST deprecations seen on this run's client become one warn event per route (#2218).
+    const octokit = (deps.octokit ??
+        (() => getOctokit(shell, {
+            log: (d) => logEvent(paths.events, 'github_api_deprecated', issueNum, formatDeprecation(d), { lane: ctx?.lane }),
+        })))();
+    const [ghOwner, ghName] = ghRepo.split('/');
+    const repoConfig = loaders.loadRepoConfig(repoRoot, paths.root);
+    const factoryConfig = loaders.loadFactoryConfigForRepo(paths.config);
+    const classifierPolicy = resolvePrClassifierPolicy(factoryConfig, process.env, { classifier: opts.prClassifier });
+    const timeouts = loaders.resolveTimeouts(factoryConfig);
+    const failoverSettings = resolveAutoFailover(factoryConfig);
+    const breaker = new ProviderBreaker(paths.breaker);
+    const reworkHistory = new ReworkHistory(paths.reworkHistory);
+    const laneFileGuard = new LaneFileGuard(paths.laneFiles);
+    const efficiency = resolveEfficiencyPolicy(repoConfig);
+    const policy = {
+        models: applyRepoConfig(loaders.loadModelsConfig(), repoConfig),
+        routes: loaders.loadRoutesConfig(),
+        sandbox: factoryConfig.sandbox,
+        budget: { perIssueCapUsd: efficiency.perIssueCapUsd },
+        effective: opts.branchPrefix === undefined
+            ? resolveEffectiveConfig(repoConfig)
+            : { ...resolveEffectiveConfig(repoConfig), branchPrefix: opts.branchPrefix },
+    };
+    const router = new core.ModelRouter(policy.models, policy.routes, false, undefined, policy.effective.allowExperimental, policy.effective.localOnly);
+    let issueSpend = 0;
+    let laneSandboxRuntime = 'none';
+    const laneWorkspaceBackend = factoryConfig.workspace?.backend === 'disposable-docker' ? 'disposable-docker' : 'worktree';
+    router.setCostSink((entry) => {
+        issueSpend += entry.cost ?? 0;
+        logCost(paths.costs, {
+            ...entry,
+            issue: String(issueNum),
+            sandboxRuntime: laneSandboxRuntime,
+            reworkRoundCount: laneReworkRounds,
+            workspaceBackend: laneWorkspaceBackend,
+        });
+    });
+    const modelPins = loaders.resolveEffectiveModelPins(router.registryRef, repoConfig);
+    const codexOff = resolveCodexDisabled(repoConfig);
+    const constitutionLoader = new core.ConstitutionLoader();
+    const product = opts.product ?? readActiveProduct(paths.product);
+    const autoRework = opts.autoRework ?? true;
+    const work = ctx?.workRequest ??
+        (await createDefaultWorkSourceRegistry({ octokit }).resolve(GITHUB_ISSUE_SOURCE, {
+            repo: ghRepo,
+            issue: issueNum,
+        }));
+    const issueTitle = work.title;
+    const sizeGateMode = opts.sizeGate ?? resolveSizeGateMode(factoryConfig);
+    const maxSlices = opts.maxSlices ?? resolveSizeGateMaxSlices(factoryConfig);
+    // ADR-0147: slice k >= 2 builds on its own branch, so read the slice plan before the worktree exists.
+    let sliceIndex;
+    if (sizeGateMode === 'slice' && !ctx?.localOnly && work.kind === GITHUB_ISSUE_SOURCE) {
+        try {
+            const lookup = await findSlicePlanComment({ octokit, repo: ghRepo, issue: issueNum });
+            if (lookup.status === 'found')
+                sliceIndex = currentSlice(lookup.plan)?.index;
+        }
+        catch (err) {
+            throw new LaneParkError(`slice plan lookup failed for #${issueNum}: ${errorDetail(err)} — parked before creating a worktree`, 'escalate');
+        }
+    }
+    const branch = branchFor(issueNum, issueTitle, policy.effective.branchPrefix, sliceIndex);
+    const worktree = ctx?.localOnly
+        ? ctx.localOnly.workspace
+        : worktreePathFor(repoRoot, ghRepo, issueNum, policy.effective.branchPrefix, loaders);
+    const specPath = resolve(paths.plans, `issue-${issueNum}.md`);
+    const runStartedAt = new Date().toISOString();
+    const lane = ctx?.lane;
+    // Captures the message of the last terminal event runIssue emits (ready/fail/
+    // escalate/held/conflict/ci-failed/timeout) so the LaneParkError this adapter
+    // raises below carries the same diagnostic text shipIssue used to throw with —
+    // RunOutcome's parked variant carries only the ParkReason enum, not free text.
+    const TERMINAL_EVENT_KINDS = new Set([
+        'ready',
+        'environment-released',
+        'fail',
+        'escalate',
+        'held',
+        'conflict',
+        'ci-failed',
+        'timeout',
+    ]);
+    let terminalMessage;
+    let laneReworkRounds = 0;
+    const mkLog = (phase) => (type, msg, extra) => {
+        if (TERMINAL_EVENT_KINDS.has(type))
+            terminalMessage = msg;
+        if (type === 'rework')
+            laneReworkRounds++;
+        // checkPhase logs each skipped checker as a 'check' event prefixed "SKIPPED: " —
+        // echo it to the terminal the way shipIssue used to print it directly.
+        if (type === 'check' && msg.startsWith('SKIPPED: ')) {
+            console.error(styleText('yellow', `  SKIP: ${msg.slice('SKIPPED: '.length)}`));
+        }
+        // Likewise for each failing checker, so a parked run still names which checker
+        // failed and why — the parked RunOutcome carries only an aggregate count (#675).
+        if (type === 'check' && msg.startsWith('FAILED: ')) {
+            console.error(styleText('red', `  FAIL: ${msg.slice('FAILED: '.length)}`));
+        }
+        logEvent(paths.events, type, issueNum, msg, { ...extra, lane, phase });
+        // Best-effort lastEvent summary (#1327) for factory.run.snapshot — an
+        // observability side channel, so a write failure is swallowed, not logged (that
+        // would re-enter this same function for every event this chokepoint fires on).
+        touchLastEvent(phaseSnapshotFile(paths.runs, issueNum), summarizeEvent(type, msg)).catch(() => { });
+    };
+    const log = mkLog();
+    log('issue-title', issueTitle);
+    if (modelPins.plan) {
+        const source = modelPins.sources.plan === 'repo' ? '.factory/config.json' : 'FACTORY_PLAN_MODEL';
+        log('model-override', `plan model pinned to ${modelPins.plan} (${source})`);
+    }
+    if (modelPins.build) {
+        const source = modelPins.sources.build === 'repo' ? '.factory/config.json' : 'FACTORY_BUILD_MODEL';
+        log('model-override', `build model pinned to ${modelPins.build} (${source})`);
+    }
+    const skipReason = closedWorkSkipReason(work);
+    if (skipReason) {
+        log('skipped-already-closed', skipReason);
+        console.log(styleText('yellow', `skipped: ${skipReason}`));
+        throw new IssueSkippedError(skipReason, 'already-closed');
+    }
+    const sandboxPolicy = resolveSandboxPolicy(policy.sandbox, {
+        worktree,
+        repoRoot,
+        cliDisabled: opts.sandbox === false,
+        laneId: lane,
+        isAvailable: (cmd) => isCommandAvailableViaShell(shell, cmd),
+    });
+    laneSandboxRuntime = sandboxPolicy?.runtime ?? 'none';
+    const worktreeSandbox = worktreeSandboxFor(sandboxPolicy?.runtime, {
+        allowHosts: sandboxPolicy?.allowHosts ?? [],
+    });
+    let activeSandboxPolicy;
+    if (opts.sandbox === false) {
+        console.error(styleText('yellow', 'factory: sandbox disabled by --no-sandbox — agent runs are UNCONTAINED'));
+        log('sandbox-disabled', 'sandbox disabled by --no-sandbox');
+    }
+    else if (!sandboxPolicy) {
+        log('sandbox-disabled', 'sandbox disabled by config/FACTORY_SANDBOX');
+    }
+    else if (sandboxPolicy.runtime === 'none') {
+        log('sandbox-unavailable', 'no sandbox runtime found (sandbox-exec/firejail) — running uncontained');
+    }
+    else if (sandboxPolicy.runtime === 'docker-sandbox') {
+        // docker-sandbox's containment is the microVM created by worktreeWorkspace below
+        // (#653), not a command-prefix wrap — activeSandboxPolicy stays undefined because
+        // wrapCommandInSandbox remains a no-op for this runtime. createMicroVm logs the
+        // actual outcome ('sandbox' on success, 'sandbox-unavailable' on fallback), so no
+        // speculative log is emitted here.
+    }
+    else {
+        activeSandboxPolicy = sandboxPolicy;
+        if (sandboxPolicy.allowHosts.length > 0) {
+            log('sandbox-degraded', `host-level egress filtering unavailable in v1; intended allowlist: ${sandboxPolicy.allowHosts.join(', ')}`);
+        }
+    }
+    // Setup worktree FIRST — PLAN needs cwd=worktree to run claude. Worktree cleanup
+    // stays a CLI concern (not called here, matching today — a worktree persists past
+    // a successful run for GC/sweep commands to reclaim later).
+    let workspace;
+    if (!ctx?.localOnly) {
+        workspace = await worktreeWorkspace({
+            repoRoot,
+            branch,
+            worktreePath: worktree,
+            log,
+            sandbox: worktreeSandbox,
+            findOpenPr: (br) => findOpenPR(octokit, ghOwner, ghName, br),
+            setup: (root, br, wt, sp, sandbox, setupLog, setupOpts) => withGitLock(root, () => withFileLock(paths.gitLock, 
+            // setupWorktree fetches origin itself before creating the worktree (#1167),
+            // so no explicit gitFetch here — still under the git + file locks.
+            () => git.setupWorktree(root, br, wt, sp, sandbox, setupLog, setupOpts), { onSteal: (pid) => log('lock-stolen', `stole ${paths.gitLock} from dead holder pid ${pid ?? 'unknown'}`) })),
+        });
+        log('worktree', `Worktree ready at ${worktree}`);
+    }
+    else {
+        workspace = localOnlyWorkspace(ctx.localOnly);
+        log('workspace', `local-only: using caller-provided workspace ${worktree} (no factory worktree created)`);
+    }
+    const planApprovalEnabled = opts.approvePlan ?? resolvePlanApproval(factoryConfig);
+    const processGroupGraceMs = resolveProcessGroupGraceMs(factoryConfig);
+    const portsSettings = resolveEnvironmentPorts(factoryConfig);
+    if (!portsSettings.enabled) {
+        log('environment_lease', 'port leasing disabled (environment.ports.enabled=false or FACTORY_ENV_PORTS=0)');
+    }
+    // acquireEnvironment.recordPgid/release only persist/deallocate the lease — process-
+    // group tracking and killing is runIssue's own unconditional tracker (Invariant 3),
+    // so a lease-disabled/failed run still tears down every spawned agent process.
+    const acquireEnvironment = portsSettings.enabled
+        ? resolveEnvironmentAcquirer({
+            laneSandboxRuntime: sandboxPolicy?.runtime ?? 'none',
+            paths,
+            worktree,
+            branch,
+            range: portsSettings.range,
+            processGroupGraceMs,
+            log,
+            findPortListeners: core.defaultFindPortListeners,
+            reapOrphanProcesses: core.reapOrphanProcesses,
+        })
+        : undefined;
+    const proxySettings = resolveEnvironmentProxy(factoryConfig);
+    const resolveBaseUrl = (appPort) => resolveLaneBaseUrl(paths, proxySettings, worktree, appPort);
+    const request = {
+        issue: issueNum,
+        repo: ghRepo,
+        branch,
+        specPath,
+        work,
+        workSource: ctx?.workSource,
+        product,
+        startedAt: runStartedAt,
+        lane,
+        options: {
+            interactive: Boolean(opts.interactive),
+            autoRework,
+            approvePlan: planApprovalEnabled,
+            sandboxDisabled: opts.sandbox === false,
+        },
+        localOnly: Boolean(ctx?.localOnly),
+        blockUnresolvedRegressions: resolveDesignRegressionBlock(factoryConfig),
+        publishFromBuild: resolveBuildPublish(factoryConfig),
+        sizeGateMode,
+        maxSlices,
+        prClassifier: classifierPolicy.enabled
+            ? {
+                rules: resolveReviewFloorRules(repoConfig),
+                gateLabel: resolveFilingPolicy(factoryConfig).selfFixLabel,
+                modelPin: repoConfig?.models?.pins?.classifier,
+            }
+            : undefined,
+        timeouts,
+        modelPins,
+        codexDisabled: codexOff,
+        skipCI: loaders.resolveSkipCI(factoryConfig),
+        failover: failoverSettings,
+        efficiency: { maxReworkRounds: efficiency.maxReworkRounds, fastPath: efficiency.fastPath },
+        sandboxPolicy: activeSandboxPolicy,
+        processGroupGraceMs,
+        preferredRoute: repoConfig?.route,
+        eventsFile: paths.events,
+        logsDir: paths.logs,
+        baselineCachePath: paths.baselineCache,
+        flakyLedgerPath: paths.flakyLedger,
+    };
+    const ports = {
+        router,
+        octokit,
+        workspace,
+        events: mkLog,
+        acquireEnvironment,
+        resolveBaseUrl,
+        getIssueSpend: () => issueSpend,
+        breaker,
+        planPhase: phases.planPhase,
+        buildPhase: phases.buildPhase,
+        checkPhase: phases.checkPhase,
+        shipPhase: phases.shipPhase,
+        resolveConstitution: () => 
+        // Resolved once here — runIssue calls this exactly once and reuses the value for
+        // every phase, so the build worker can never author the standards it is graded by.
+        constitutionLoader.resolve(worktree, product, factoryConfig.paths?.constitution),
+        createApprovalGate: () => createFileApprovalGate({ dir: paths.approvals, timeoutMs: timeouts.approval * 1000 }),
+        drainSteering: () => drainSteering(paths.steering, issueNum, worktree),
+        reworkHistory,
+        laneFileGuard,
+        recordPhase: (phase) => {
+            const now = new Date().toISOString();
+            return writePhaseSnapshot(phaseSnapshotFile(paths.runs, issueNum), {
+                issue: issueNum,
+                phase,
+                updatedAt: now,
+                lastActivityAt: now,
+            });
+        },
+        onActivity: () => touchRunActivity(phaseSnapshotFile(paths.runs, issueNum), new Date().toISOString()),
+        onDecomposed: (childIssues) => {
+            const childList = childIssues.map((n) => `#${n}`).join(', ');
+            const planLog = mkLog('plan');
+            try {
+                const before = readTextFileOrEmpty(paths.queue);
+                const rewrite = rewriteQueueForDecomposition(before, { issue: issueNum, childIssues });
+                if (rewrite.changed) {
+                    writeFileSync(paths.queue, rewrite.content);
+                    planLog('decompose_filed', `queue entry for #${issueNum} replaced with ${childList}`);
+                }
+                else {
+                    planLog('decompose_filed', `#${issueNum} had no queue entry to replace — continuing the lane with ${childList}`);
+                }
+            }
+            catch (err) {
+                planLog('decompose_file_failed', `queue rewrite for #${issueNum} failed: ${errorDetail(err)}`);
+            }
+            throw new IssueDecomposedError(`issue #${issueNum} decomposed into ${childList}`, childIssues);
+        },
+        writeLocalRunReport: (info) => maybeWriteLocalRunReport({
+            issueNum,
+            paths,
+            startedAt: runStartedAt,
+            outcome: info.outcome,
+            branch: info.branch,
+            worktree,
+            specPath,
+            route: info.route,
+            reason: info.reason,
+            writeLocalRunReport: core.writeLocalRunReport,
+        }),
+        writeBenchmarkArtifacts: (info) => maybeWriteBenchmarkArtifacts({
+            issueNum,
+            paths,
+            ctx,
+            startedAt: runStartedAt,
+            outcome: info.outcome === 'parked' ? 'failed' : info.outcome,
+            branch: info.branch,
+            specPath,
+            route: info.route,
+            checkSummary: info.checkSummary,
+            reworkRounds: info.reworkRounds,
+            failure: info.failure,
+            reportPath: info.reportPath,
+            diffBase: info.diffBase,
+            log,
+        }),
+    };
+    // #2214: report-only per-lane egress proxy for sandbox-exec. Started here, after worktree setup,
+    // so the finally below is the single place that stops it on every exit path.
+    const proxied = shouldProxyEgress(request.sandboxPolicy) ? request.sandboxPolicy : undefined;
+    const egressProxy = proxied
+        ? await startEgressProxy({
+            allowHosts: proxied.allowHosts,
+            onHost: (host, allowed) => log('egress_host', `${host} (${allowed ? 'on allowlist' : 'not on allowlist'})`),
+        })
+        : undefined;
+    let outcome;
+    try {
+        outcome = await runIssue(proxied && egressProxy ? { ...request, sandboxPolicy: { ...proxied, proxyUrl: egressProxy.url } } : request, policy, ports);
+    }
+    finally {
+        if (proxied && egressProxy) {
+            log('egress_summary', egressSummaryMessage(egressProxy.hosts(), proxied.allowHosts));
+            await egressProxy.close();
+        }
+    }
+    ctx?.onOutcome?.(outcome);
+    if (opts.interactive && !ctx?.localOnly && (outcome.state === 'ready' || outcome.state === 'shipped')) {
+        const leftover = listQueuedSteering(paths.steering, issueNum);
+        if (leftover.length > 0) {
+            log('steering_unconsumed', `${leftover.length} steering message(s) not consumed (no worker phase remained)`);
+        }
+    }
+    if (outcome.state === 'ready' || outcome.state === 'shipped') {
+        if (ctx?.localOnly) {
+            console.log(styleText('green', `✅ Local-only run complete in ${worktree} (no PR — publishing disabled)`));
+        }
+        else {
+            console.log(styleText('green', `✅ Issue #${issueNum} → ${terminalMessage ?? 'ready'}`));
+        }
+        return outcome.branch;
+    }
+    if (outcome.state === 'released') {
+        throw new LaneEnvironmentPauseError(terminalMessage ?? 'environment failure on base', {
+            baseSha: outcome.baseSha,
+            failingChecks: outcome.failingChecks,
+            failureSignature: outcome.failureSignature,
+        });
+    }
+    const reason = outcome.state === 'escalated' ? 'escalate' : outcome.reason;
+    const message = outcome.state === 'escalated' ? outcome.reason : (terminalMessage ?? `run parked: ${outcome.reason}`);
+    throw new LaneParkError(message, reason, outcome.state === 'parked'
+        ? { failureSignature: outcome.failureSignature, failingChecks: outcome.failingChecks }
+        : undefined);
+}
+async function maybeWriteLocalRunReport(opts) {
+    if (process.env.FACTORY_LOCAL_ONLY !== '1')
+        return undefined;
+    const report = await (opts.writeLocalRunReport ?? coreOps.writeLocalRunReport)({
+        issue: opts.issueNum,
+        eventsFile: opts.paths.events,
+        reportsDir: opts.paths.reports,
+        startedAt: opts.startedAt,
+        outcome: opts.outcome,
+        profile: 'local-only',
+        branch: opts.branch,
+        worktree: opts.worktree,
+        specPath: opts.specPath,
+        route: opts.route,
+        reason: opts.reason,
+    });
+    console.log(styleText('cyan', `local-only report: ${report.path}`));
+    return report.path;
+}
+async function maybeWriteBenchmarkArtifacts(opts) {
+    if (!opts.ctx?.localOnly || !opts.ctx.artifactsDir)
+        return;
+    try {
+        const { manifestPath } = await writeBenchmarkArtifacts({
+            issue: opts.issueNum,
+            artifactsDir: opts.ctx.artifactsDir,
+            eventsFile: opts.paths.events,
+            costsFile: opts.paths.costs,
+            startedAt: opts.startedAt,
+            outcome: opts.outcome,
+            workspace: opts.ctx.localOnly.workspace,
+            branch: opts.branch,
+            specPath: opts.specPath,
+            route: opts.route,
+            request: opts.ctx.workRequest,
+            checkSummary: opts.checkSummary,
+            reworkRounds: opts.reworkRounds,
+            failure: opts.failure,
+            reportPath: opts.reportPath,
+            diffBase: opts.diffBase,
+        });
+        opts.log('benchmark-artifacts', `manifest written to ${manifestPath}`);
+        console.log(styleText('cyan', `benchmark artifacts: ${manifestPath}`));
+    }
+    catch (err) {
+        // Never let artifact emission mask the run outcome.
+        opts.log('benchmark-artifacts-failed', `could not write benchmark artifacts: ${err.message}`);
+    }
+}
+/** The autoGcOnRun-gated worktree sweep every pipeline entry point runs before shipping
+ *  (`factory run`, and since #1756 the one-shot `factory ship` / `factory run-issue`). Never
+ *  throws — a GC failure is a warn, never a reason to abort the command. */
+async function runAutoWorktreeGc(repoRoot, paths, ghRepo, eventScope) {
+    try {
+        const factoryConfig = configLoaders.loadFactoryConfigForRepo(paths.config);
+        if (!factoryConfig.worktree.autoGcOnRun)
+            return;
+        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: getOctokit(), sandbox: gcSandbox })));
+        logEvent(paths.events, 'worktree-gc', eventScope, `removed ${report.removed.length} stale worktree(s), kept ${report.kept}`);
+        console.log(internalOps.formatGcReport(report));
+    }
+    catch (err) {
+        logEvent(paths.events, 'warn', eventScope, `worktree gc failed: ${err.message}`);
+    }
+}
+/** Mid-run worktree GC between issues in a lane (#1757). Honors worktree.autoGcOnRun, holds
+ *  the git + file locks every worktree mutation holds, and skips (never waits) when another
+ *  lane holds the land lock so a sweep can never race a merge. Logs worktree-gc only when it
+ *  removed something. Never throws. */
+export async function sweepBetweenLaneIssues(issue, lane, repoRoot, ghRepo, paths, deps = {}) {
+    const { loadConfig = configLoaders.loadFactoryConfigForRepo, sweep = internalOps.sweepWorktrees, emitEvent = logEvent, octokit = getOctokit, } = deps;
+    try {
+        const cfg = loadConfig(paths.config);
+        if (!cfg.worktree.autoGcOnRun)
+            return 'disabled';
+        const gcLog = (type, msg) => emitEvent(paths.events, type, issue, msg, { lane });
+        const sandbox = gcWorktreeSandbox(cfg.sandbox, repoRoot);
+        const report = await withGitLock(repoRoot, () => withFileLock(paths.mergeLock, () => withFileLock(paths.gitLock, () => sweep({ repoRoot, ttlDays: cfg.worktree.gcTtlDays, repo: ghRepo, branchPrefix: resolveBranchPrefix() }, { log: gcLog, octokit: octokit(), sandbox })), { timeoutMs: 0 }));
+        if (report.removed.length > 0) {
+            emitEvent(paths.events, 'worktree-gc', issue, `removed ${report.removed.length} stale worktree(s), kept ${report.kept}`, { lane });
+            console.log(internalOps.formatGcReport(report));
+        }
+        return 'swept';
+    }
+    catch (err) {
+        // A zero-timeout merge-lock acquire failing means another lane is mid-land: skip quietly.
+        if (err?.reason === 'timeout')
+            return 'land-in-progress';
+        emitEvent(paths.events, 'warn', issue, `mid-run worktree gc failed: ${err?.message ?? String(err)}`, { lane });
+        return 'failed';
+    }
+}
+async function cmdShip(issueNum, opts) {
+    if (!coreOps.isCommandAvailable('claude')) {
+        throw new CliExitError(`factory: ${missingClaudeCliMessage()}`, 2);
+    }
+    const repoRoot = await getRepoRoot();
+    const paths = getFactoryPaths(repoRoot);
+    if (!existsSync(paths.root)) {
+        throw new CliExitError(`factory: ${notInitializedMessage()}`, 2);
+    }
+    const mergeNotice = mergeScopeNotice(process.env, issueNum);
+    if (mergeNotice) {
+        console.error(styleText('yellow', mergeNotice));
+        logEvent(paths.events, 'warn', issueNum, mergeNotice);
+    }
+    const branchPrefix = branchPrefixOrExit(opts.branchPrefix);
+    return withRepoRunLock(paths, 'factory ship', async () => {
+        let ghRepo = null;
+        try {
+            ghRepo = await getGitHubRepo();
+        }
+        catch {
+            /* shipIssue reports repo resolution itself */
+        }
+        if (ghRepo)
+            await runAutoWorktreeGc(repoRoot, paths, ghRepo, issueNum);
+        const priorEvents = existsSync(paths.events) ? readEvents(paths.events) : [];
+        if (hasUnresolvedPark(priorEvents, String(issueNum))) {
+            logEvent(paths.events, 'human-restarted', issueNum, 'manual retry of a previously parked/failed run', {
+                actor: process.env.FACTORY_ACTOR ?? process.env.USER ?? 'unknown',
+            });
+        }
+        try {
+            return await shipIssue(issueNum, { ...opts, branchPrefix });
+        }
+        catch (err) {
+            if (err instanceof IssueSkippedError)
+                return;
+            throw new CliExitError(`Ship failed for issue #${issueNum}: ${err.message}`, 1);
+        }
+    });
+}
+async function cmdRunIssue(issueNum, opts) {
+    if (!coreOps.isCommandAvailable('claude')) {
+        throw new CliExitError(`factory: ${missingClaudeCliMessage()}`, 2);
+    }
+    const repoRoot = await getRepoRoot();
+    const paths = getFactoryPaths(repoRoot);
+    if (!existsSync(paths.root)) {
+        throw new CliExitError(`factory: ${notInitializedMessage()}`, 2);
+    }
+    const { runChildren, sizeGate: rawSizeGate, maxSlices: rawMaxSlices, ...shipOpts } = opts;
+    const branchPrefix = branchPrefixOrExit(opts.branchPrefix);
+    const sizeGate = sizeGateOrExit(rawSizeGate);
+    const maxSlices = maxSlicesOrExit(rawMaxSlices);
+    await withRepoRunLock(paths, 'factory run-issue', async () => {
+        const ghRepo = await getGitHubRepo();
+        // Pre-flight: resolve the issue through the canonical work-request seam
+        // BEFORE any worktree or PR exists — a bad issue exits here.
+        const workSources = createDefaultWorkSourceRegistry({ octokit: getOctokit() });
+        let work;
+        try {
+            work = await workSources.resolve(GITHUB_ISSUE_SOURCE, {
+                repo: ghRepo,
+                issue: issueNum,
+            });
+        }
+        catch (err) {
+            if (err instanceof InvalidWorkRequestInputError) {
+                throw new CliExitError(`factory: ${err.message}`, 2);
+            }
+            throw new CliExitError(`factory: could not resolve issue #${issueNum} in ${ghRepo} (${errorDetail(err)}) — no worktree or PR was created`, 2);
+        }
+        console.log(styleText('cyan', `one-shot: resolved ${work.id} — running the pipeline (queue untouched)`));
+        await runAutoWorktreeGc(repoRoot, paths, ghRepo, issueNum);
+        const priorEvents = existsSync(paths.events) ? readEvents(paths.events) : [];
+        if (hasUnresolvedPark(priorEvents, String(issueNum))) {
+            logEvent(paths.events, 'human-restarted', issueNum, 'manual retry of a previously parked/failed run', {
+                actor: process.env.FACTORY_ACTOR ?? process.env.USER ?? 'unknown',
+            });
+        }
+        try {
+            await shipIssue(issueNum, { ...shipOpts, branchPrefix, sizeGate, maxSlices }, { repoRoot, ghRepo, workRequest: work });
+        }
+        catch (err) {
+            if (err instanceof IssueSkippedError)
+                return;
+            if (err instanceof IssueDecomposedError && runChildren) {
+                await runDecomposedChildren(issueNum, err.childIssues, { ...shipOpts, branchPrefix, sizeGate, maxSlices }, { repoRoot, ghRepo, workSources });
+                return;
+            }
+            if (err instanceof IssueDecomposedError && !runChildren) {
+                const children = err.childIssues.map((n) => `#${n}`).join(', ');
+                throw new CliExitError(`Run failed for issue #${issueNum}: the size gate decomposed it into ${children} — no child issue was run. ` +
+                    `Re-run with \`factory run-issue ${issueNum} --run-children\` to run them.`, 1);
+            }
+            throw new CliExitError(`Run failed for issue #${issueNum}: ${err.message}`, 1);
+        }
+    });
+}
+/** Runs each decomposed child through the one-shot pipeline in build order, inside the caller's
+ *  run lock, then prints a per-child summary. Nested decompositions expand in place and closed
+ *  children are skipped. A failed or escalated child is recorded and the next one still runs;
+ *  `.factory/STOP` is checked before each child starts (read only, ADR-0111). Throws CliExitError(1)
+ *  unless every child is ready or skipped (#1747, #1748, #1749). */
+async function runDecomposedChildren(parent, children, opts, env) {
+    const list = children.map((n) => `#${n}`).join(', ');
+    console.log(styleText('cyan', `run-children: #${parent} decomposed into ${list} — running them in build order`));
+    const paths = getFactoryPaths(env.repoRoot);
+    const results = await runChildrenInOrder(children, async (child) => {
+        let work;
+        try {
+            work = await env.workSources.resolve(GITHUB_ISSUE_SOURCE, {
+                repo: env.ghRepo,
+                issue: child,
+            });
+        }
+        catch (err) {
+            return { issue: child, status: 'failed', detail: `could not resolve issue #${child} (${errorDetail(err)})` };
+        }
+        console.log(styleText('cyan', `one-shot: resolved ${work.id} — running the pipeline (queue untouched)`));
+        let outcome;
+        try {
+            await shipIssue(child, opts, {
+                repoRoot: env.repoRoot,
+                ghRepo: env.ghRepo,
+                workRequest: work,
+                onOutcome: (o) => {
+                    outcome = o;
+                },
+            });
+        }
+        catch (err) {
+            if (err instanceof IssueDecomposedError) {
+                const again = err.childIssues.map((n) => `#${n}`).join(', ');
+                console.log(styleText('cyan', `run-children: #${child} decomposed into ${again} — running them in its place`));
+                return { issue: child, status: 'decomposed', children: err.childIssues };
+            }
+            if (err instanceof IssueSkippedError) {
+                return { issue: child, status: 'skipped', detail: err.message };
+            }
+            return { issue: child, status: 'failed', detail: err instanceof Error ? err.message : String(err) };
+        }
+        const done = outcome;
+        return { issue: child, status: 'ready', prNumber: done && 'prNumber' in done ? done.prNumber : undefined };
+    }, [parent], (next) => {
+        if (!existsSync(paths.stop))
+            return false;
+        logEvent(paths.events, 'stopped', next, 'STOP file present');
+        console.log(styleText('yellow', `run-children: .factory/STOP present — not starting #${next} or any later child`));
+        return true;
+    });
+    const ok = childRunSucceeded(results);
+    for (const line of formatChildRunSummary(parent, results)) {
+        console.log(ok ? styleText('green', line) : styleText('yellow', line));
+    }
+    if (!ok) {
+        throw new CliExitError(`Run failed for issue #${parent}: not every decomposed child reached ready-for-review or was skipped as closed (failed or not-run children are listed above)`, 1);
+    }
+}
+async function cmdRunBrief(briefPath, opts) {
+    if (!coreOps.isCommandAvailable('claude')) {
+        throw new CliExitError(`factory: ${missingClaudeCliMessage()}`, 2);
+    }
+    const repoRoot = await getRepoRoot();
+    const paths = getFactoryPaths(repoRoot);
+    if (!existsSync(paths.root)) {
+        throw new CliExitError(`factory: ${notInitializedMessage()}`, 2);
+    }
+    const branchPrefix = branchPrefixOrExit(opts.branchPrefix);
+    await withRepoRunLock(paths, 'factory run-brief', async () => {
+        let localOnly;
+        if (opts.workspace !== undefined) {
+            try {
+                localOnly = resolveLocalOnlyPolicy(opts.workspace);
+            }
+            catch (err) {
+                if (err instanceof InvalidWorkspaceError)
+                    throw new CliExitError(`factory: ${err.message}`, 2);
+                throw err;
+            }
+        }
+        let artifactsDir;
+        if (opts.artifacts !== undefined) {
+            if (!localOnly) {
+                throw new CliExitError('factory: --artifacts requires --workspace (local-only runs only)', 2);
+            }
+            try {
+                artifactsDir = resolveArtifactsDir(opts.artifacts);
+            }
+            catch (err) {
+                if (err instanceof InvalidArtifactsDirError)
+                    throw new CliExitError(`factory: ${err.message}`, 2);
+                throw err;
+            }
+            console.log(styleText('cyan', `local-only: benchmark artifacts will be written to ${artifactsDir}`));
+        }
+        // Local-only runs never touch GitHub — no remote required, no mutation possible.
+        const ghRepo = localOnly ? 'local/workspace' : await getGitHubRepo();
+        // Pre-flight: resolve the brief through the canonical work-request seam
+        // BEFORE any worktree or PR exists — a malformed brief exits here, so BUILD never starts.
+        const workSources = createDefaultWorkSourceRegistry({ octokit: getOctokit() });
+        let work;
+        try {
+            work = await workSources.resolve(LOCAL_BRIEF_SOURCE, { path: briefPath });
+        }
+        catch (err) {
+            if (err instanceof InvalidWorkRequestInputError) {
+                throw new CliExitError(`factory: ${err.message}`, 2);
+            }
+            throw new CliExitError(`factory: could not resolve brief at ${briefPath} (${errorDetail(err)}) — no worktree or PR was created`, 2);
+        }
+        const digest = work.reference?.externalId ?? '';
+        const runNum = briefRunNumber(digest);
+        console.log(styleText('cyan', `one-shot: resolved ${work.id} — running the pipeline (queue untouched)`));
+        logEvent(paths.events, 'work-source', runNum, `inline local brief ${briefPath} (sha256 ${digest})`);
+        if (localOnly) {
+            console.log(styleText('cyan', `local-only: workspace ${localOnly.workspace} — publishing disabled`));
+            logEvent(paths.events, 'local-only', runNum, `caller-provided workspace ${localOnly.workspace} — publishing disabled`);
+        }
+        const priorEvents = existsSync(paths.events) ? readEvents(paths.events) : [];
+        if (hasUnresolvedPark(priorEvents, String(runNum))) {
+            logEvent(paths.events, 'human-restarted', runNum, 'manual retry of a previously parked/failed run', {
+                actor: process.env.FACTORY_ACTOR ?? process.env.USER ?? 'unknown',
+            });
+        }
+        try {
+            await shipIssue(runNum, { ...opts, branchPrefix }, {
+                repoRoot,
+                ghRepo,
+                workRequest: work,
+                workSource: { kind: LOCAL_BRIEF_SOURCE, params: { path: briefPath } },
+                localOnly,
+                artifactsDir,
+            });
+        }
+        catch (err) {
+            throw new CliExitError(`Run failed for brief ${briefPath}: ${err.message}`, 1);
+        }
+    });
+}
+async function cmdLocalSmallDryRun(issueNum, opts) {
+    const repoRoot = await getRepoRoot();
+    const ghRepo = await getGitHubRepo();
+    const paths = getFactoryPaths(repoRoot);
+    const octokit = getOctokit();
+    const [owner, repoName] = ghRepo.split('/');
+    const specPath = resolve(repoRoot, opts.spec ?? resolve(paths.plans, `issue-${issueNum}.md`));
+    const outputDir = resolve(repoRoot, opts.output ?? resolve(paths.state, 'local-small', `issue-${issueNum}`));
+    const { data: issue } = await octokit.rest.issues.get({ owner, repo: repoName, issue_number: issueNum });
+    const result = await internalOps.createLocalSmallDryRun({
+        issue: issueNum,
+        issueTitle: issue.title,
+        issueBody: issue.body ?? '',
+        repoRoot,
+        specPath,
+        outputDir,
+    });
+    console.log(styleText('green', `local-small dry run: ${result.planPath}`));
+    console.log(styleText('green', `local-small context: ${result.contextPath}`));
+}
+async function cmdLocalSmallOvernight(opts) {
+    const repoRoot = await getRepoRoot();
+    const paths = getFactoryPaths(repoRoot);
+    const queueFile = resolve(repoRoot, opts.queue ?? resolve(paths.state, 'local-small', 'overnight-queue'));
+    const statePath = resolve(repoRoot, opts.state ?? resolve(paths.state, 'local-small', 'overnight-state.json'));
+    if (!existsSync(queueFile)) {
+        throw new CliExitError(`factory: overnight queue not found at ${queueFile} — create it with "<lane> <issue#>" lines`, 2);
+    }
+    const { entries, diagnostics } = parseQueue(readFileSync(queueFile, 'utf-8'));
+    warnQueueDiagnostics(diagnostics);
+    if (entries.length === 0) {
+        throw new CliExitError(`factory: overnight queue at ${queueFile} has no valid entries`, 2);
+    }
+    await withRepoRunLock(paths, 'factory local-small-overnight', async () => {
+        const ghRepo = await getGitHubRepo();
+        process.env.FACTORY_LOCAL_ONLY = '1';
+        const preflight = async () => {
+            if (!coreOps.isCommandAvailable('claude'))
+                return { ok: false, reason: missingClaudeCliMessage() };
+            const registry = new coreOps.ModelRegistry(applyRepoConfig(configLoaders.loadModelsConfig(), configLoaders.loadRepoConfig(repoRoot)));
+            const ollamaModels = ollamaModelSet();
+            const diagnoses = coreOps.diagnoseModels(registry, { ollamaModelPresent: ollamaModels ? (m) => ollamaModels.has(m) : undefined }, resolveExperimental(), true);
+            if (!hasReachableWorker(diagnoses)) {
+                const reasons = diagnoses.filter((d) => !d.reachable).map((d) => `${d.model}: ${d.reason}`);
+                return { ok: false, reason: `no reachable local worker model — ${reasons.join('; ')}` };
+            }
+            return { ok: true };
+        };
+        const processItem = async (issue) => {
+            try {
+                await shipIssue(issue, { autoRework: true, interactive: false }, { repoRoot, ghRepo, lane: 'overnight' });
+                return { status: 'ready' };
+            }
+            catch (err) {
+                if (err instanceof IssueSkippedError)
+                    return { status: 'parked', reason: err.message };
+                return parkReasonFor(err) === 'escalate'
+                    ? { status: 'parked', reason: err.message }
+                    : { status: 'failed', reason: err.message };
+            }
+        };
+        const report = (item) => {
+            console.log(styleText('yellow', `factory: issue #${item.issue} ${item.status} — ${item.reason ?? 'unknown'}`));
+            logEvent(paths.events, 'overnight-park', item.issue, `${item.status}: ${item.reason ?? 'unknown'} — see ${paths.reports}`);
+        };
+        const log = (type, msg) => logEvent(paths.events, type, '-', msg);
+        const deps = { preflight, processItem, report, log };
+        const result = await runOvernightQueue({ issues: entries.map((e) => e.issue), statePath }, deps);
+        const ready = result.processed.filter((item) => item.status === 'ready');
+        const parked = result.processed.filter((item) => item.status === 'parked');
+        const failed = result.processed.filter((item) => item.status === 'failed');
+        console.log(styleText('green', `overnight ready: ${ready.length}`));
+        console.log(styleText('yellow', `overnight parked: ${parked.length}`));
+        console.log(styleText('red', `overnight failed: ${failed.length}`));
+        console.log(styleText('yellow', `overnight skipped (already resumed): ${result.skipped.length}`));
+        if (result.halted) {
+            throw new CliExitError(`factory: overnight halted before issue #${result.halted.issue}: ${result.halted.reason} — fix the environment and re-run to resume`, 4);
+        }
+    });
+}
+function worktreePathFor(repoRoot, ghRepo, issueNum, prefix, loaders = configLoaders) {
+    return laneWorktreePath({
+        repoRoot,
+        parent: loaders.loadFactoryConfigForRepo(getFactoryPaths(repoRoot).config).worktree.parent,
+        repo: ghRepo,
+        issue: issueNum,
+        prefix,
+    });
+}
+/** Fences a whole run behind the checkout's `.factory/run.lock` (#598). A live holder is
+ *  refused immediately — never queued behind a multi-hour run — and a dead holder's lock is
+ *  reclaimed by withRunLock. Nested acquisition inside one process is a pass-through, so
+ *  `factory supervise` can hold this across its loop. */
+export async function withRepoRunLock(paths, command, fn, deps = {}) {
+    const { runLock = withRunLock, emitEvent = logEvent } = deps;
+    try {
+        return await runLock(paths.runLock, fn, {
+            command,
+            onReclaim: (pid) => emitEvent(paths.events, 'lock-stolen', '-', `reclaimed ${paths.runLock} from dead holder pid ${pid ?? 'unknown'}`),
+        });
+    }
+    catch (err) {
+        if (err instanceof RunLockHeldError) {
+            emitEvent(paths.events, 'run_lock_conflict', '-', `${command} refused: ${err.message}`);
+            throw new CliExitError(`factory: ${err.message} — stop that run (or wait for it to finish) before starting another. ` +
+                `A dead run's lock is reclaimed automatically; remove ${paths.runLock} only if you are sure no factory run is live.`, 2);
+        }
+        throw err;
+    }
+}
+/** The repo's current docker-sandbox descriptor for worktree-gc sweeps, or undefined for
+ *  every other runtime/config state (including a fixture config with no `sandbox` key). */
+function gcWorktreeSandbox(sandboxCfg, repoRoot) {
+    if (!sandboxCfg)
+        return undefined;
+    const policy = resolveSandboxPolicy(sandboxCfg, { worktree: repoRoot, repoRoot });
+    return worktreeSandboxFor(policy?.runtime);
+}
+/** Eagerly reaps a parked lane's own worktree inside `factory run` (#1007). All the safety
+ *  gates live in reapLaneWorktree; this wrapper resolves the lane's conventional worktree
+ *  path and holds the same git+file lock pairing as every other worktree mutation site. A
+ *  reap failure is logged as a warn and never surfaces — parking must always succeed. */
+export async function reapParkedLaneWorktree(issue, repoRoot, ghRepo, paths, prefixOverride) {
+    try {
+        const factoryConfig = configLoaders.loadFactoryConfigForRepo(paths.config);
+        const branchPrefix = prefixOverride ?? resolveEffectiveConfig(configLoaders.loadRepoConfig(repoRoot)).branchPrefix;
+        const worktreePath = worktreePathFor(repoRoot, ghRepo, issue, branchPrefix);
+        const log = (type, msg) => logEvent(paths.events, type, issue, msg);
+        const sandbox = gcWorktreeSandbox(factoryConfig.sandbox, repoRoot);
+        await withGitLock(repoRoot, () => withFileLock(paths.gitLock, () => reapLaneWorktree(repoRoot, worktreePath, { issue, branchPrefix, log, sandbox })));
+    }
+    catch (err) {
+        logEvent(paths.events, 'warn', issue, `parked-lane worktree reap failed: ${err?.message ?? String(err)}`);
+    }
+}
+export async function cmdWorktreeGc(opts) {
+    const repoRoot = await getRepoRoot();
+    const paths = getFactoryPaths(repoRoot);
+    const factoryConfig = configLoaders.loadFactoryConfigForRepo(paths.config);
+    const ttlDays = opts.ttlDays !== undefined ? Number(opts.ttlDays) : factoryConfig.worktree.gcTtlDays;
+    if (!Number.isFinite(ttlDays) || ttlDays < 0) {
+        throw new CliExitError('factory: --ttl-days must be a non-negative number', 2);
+    }
+    const branchPrefix = branchPrefixOrExit(opts.branchPrefix);
+    const log = (type, msg) => logEvent(paths.events, type, '-', msg);
+    // Best-effort GitHub evidence: tokenless/local-only repos keep today's pure-local behavior.
+    const ghRepo = await getGitHubRepo().catch(() => undefined);
+    const octokit = ghRepo ? (hasGitHubToken() ? getOctokit() : undefined) : undefined;
+    const sandbox = gcWorktreeSandbox(factoryConfig.sandbox, repoRoot);
+    const run = () => internalOps.sweepWorktrees({ repoRoot, ttlDays, dryRun: opts.dryRun, repo: ghRepo, branchPrefix }, { log, octokit, sandbox });
+    const report = opts.dryRun ? await run() : await withGitLock(repoRoot, () => withFileLock(paths.gitLock, run));
+    console.log(internalOps.formatGcReport(report));
+}
+/** `factory reset <issue...>` (#1787): wipes an issue's local state; see reset.ts. */
+export async function cmdReset(issues, opts) {
+    let nums;
+    try {
+        nums = parseResetIssues(issues);
+    }
+    catch (err) {
+        throw new CliExitError(err.message, 2);
+    }
+    const repoRoot = await getRepoRoot();
+    const paths = getFactoryPaths(repoRoot);
+    const branchPrefix = branchPrefixOrExit(opts.branchPrefix);
+    const sandbox = gcWorktreeSandbox(configLoaders.loadFactoryConfigForRepo(paths.config).sandbox, repoRoot);
+    const log = (type, msg) => logEvent(paths.events, type, '-', msg);
+    const run = () => runReset(nums, {
+        repoRoot,
+        cwd: process.cwd(),
+        paths,
+        branchPrefix,
+        git: (cmd) => shellOps.exec(cmd, { cwd: repoRoot }).then((r) => r.stdout),
+        removeWorktree: (p) => gitOps.cleanupWorktree(repoRoot, p, log, sandbox),
+        readLeases: () => readPortLeases(paths.ports),
+        releaseLease: (id) => releasePortLease({ registryFile: paths.ports, lockDir: paths.portsLock, worktreeId: id }),
+        runCommand: (cmd, o) => shellOps.exec(cmd, { cwd: o?.cwd ?? repoRoot }).then((r) => ({ stdout: r.stdout })),
+        dryRun: opts.dryRun === true,
+        force: opts.force === true,
+    });
+    // A dry run takes no lock: the lock itself writes files.
+    const lines = opts.dryRun ? await run() : await withGitLock(repoRoot, () => withFileLock(paths.gitLock, run));
+    for (const line of lines)
+        console.log(line);
+}
+/** deps overrides the config loaders, git ops, internal ops and octokit for this call, like shipIssue. */
+export async function cmdLand(issueNum, opts = {}, deps = {}) {
+    const previousLoaders = configLoaders;
+    const previousOctokitFactory = octokitFactory;
+    const previousGitOps = gitOps;
+    const previousInternalOps = internalOps;
+    const previousShellOps = shellOps;
+    configLoaders = resolveConfigLoaders(deps);
+    gitOps = resolveGitOps(deps);
+    internalOps = resolveInternalOps(deps);
+    shellOps = resolveShellOps(deps);
+    octokitFactory = deps.octokit ?? octokitFactory;
+    try {
+        const branchPrefix = branchPrefixOrExit(opts.branchPrefix);
+        const repoRoot = await getRepoRoot();
+        const ghRepo = await getGitHubRepo();
+        const paths = getFactoryPaths(repoRoot);
+        const octokit = getOctokit();
+        const factoryConfig = configLoaders.loadFactoryConfigForRepo(paths.config);
+        const skipCI = configLoaders.resolveSkipCI(factoryConfig);
+        try {
+            const result = await landIssue(issueNum, repoRoot, ghRepo, paths, octokit, skipCI, branchPrefix, {
+                allowGated: opts.allowGated === true,
+            });
+            console.log(styleText('green', `✅ Landed PR #${result.prNumber} for issue #${issueNum}`));
+        }
+        catch (err) {
+            if (err instanceof AwaitingReviewError) {
+                console.log(styleText('yellow', `⏸ PR #${err.prNumber} for issue #${issueNum} awaiting human review — left open`));
+                return;
+            }
+            if (err instanceof CiUnverifiedError) {
+                console.log(styleText('yellow', `⏸ PR #${err.prNumber} for issue #${issueNum} — CI never reached a green verdict — left open, not merged`));
+                return;
+            }
+            if (err instanceof CiFailedError) {
+                console.log(styleText('yellow', `⏸ PR #${err.prNumber} for issue #${issueNum} has a failing CI check — left open, not merged`));
+                return;
+            }
+            if (err instanceof MergeGatedError) {
+                throw new CliExitError(`factory: ${err.message}`, 4);
+            }
+            if (err instanceof LandConflictError) {
+                throw new CliExitError(`factory: ${err.message}`, 3);
+            }
+            if (err instanceof LandFailureError) {
+                throw new CliExitError(`factory: ${err.message}`, err.code);
+            }
+            throw new CliExitError(`factory: merge failed for issue #${issueNum}: ${err.message}`, 5);
+        }
+    }
+    finally {
+        configLoaders = previousLoaders;
+        gitOps = previousGitOps;
+        internalOps = previousInternalOps;
+        shellOps = previousShellOps;
+        octokitFactory = previousOctokitFactory;
+    }
+}
+async function landIssue(issueNum, repoRoot, ghRepo, paths, octokit, skipCI, branchPrefix, opts = {}) {
+    const [owner, repoName] = ghRepo.split('/');
+    const log = (type, msg, extra) => logEvent(paths.events, type, issueNum, msg, extra);
+    // The issue title may have been edited since the PR was opened, so a
+    // freshly-derived branch name can drift from the branch the PR actually
+    // lives on (same failure mode fixed for waitForMerge in #51). Guess the
+    // branch from the current title first, but fall back to matching the open
+    // PR that references this issue directly and use its real head branch.
+    // Legacy-prefix (LEGACY_BRANCH_PREFIX) branches are guessed too, after the resolved prefix (#1708).
+    const resolved = branchPrefix ?? resolveEffectiveConfig(configLoaders.loadRepoConfig(repoRoot)).branchPrefix;
+    const title = await getIssueTitle(ghRepo, issueNum, octokit);
+    const guesses = factoryBranchPrefixes(resolved).map((p) => branchFor(issueNum, title, p));
+    const guessedBranch = guesses[0];
+    let branch = guessedBranch;
+    let prNumber;
+    try {
+        const findByGuess = async () => {
+            for (const guess of guesses) {
+                const found = await findOpenPRNumber(octokit, owner, repoName, guess);
+                if (found) {
+                    branch = guess;
+                    return found;
+                }
+            }
+            return undefined;
+        };
+        [, prNumber] = await Promise.all([gitOps.gitFetch(repoRoot), findByGuess()]);
+        if (!prNumber) {
+            const fallback = await findOpenPRForIssue(octokit, owner, repoName, issueNum);
+            if (fallback) {
+                branch = fallback.branch;
+                prNumber = fallback.number;
+            }
+        }
+    }
+    catch (err) {
+        const failure = prLookupFailure(issueNum, guessedBranch, err);
+        log('fail', failure.message);
+        throw failure;
+    }
+    if (!prNumber) {
+        log('fail', `no open PR for ${guessedBranch}`);
+        throw new LandFailureError(`no open PR for issue #${issueNum} (${guessedBranch})`, 1);
+    }
+    const landFactoryConfig = configLoaders.loadFactoryConfigForRepo(paths.config);
+    // Every merge path honors the no-auto-merge gate on the issue and on the PR; unreadable labels fail closed (#1720).
+    const filingPolicy = resolveFilingPolicy(landFactoryConfig);
+    const gateLabel = filingPolicy.selfFixLabel;
+    if (opts.allowGated) {
+        console.log(`AUDIT factory land #${issueNum}: --allow-gated override — merging PR #${prNumber} past the ${gateLabel} gate`);
+        log('merge-gated-override', `--allow-gated: merging PR #${prNumber} past ${gateLabel} gate (human override)`);
+    }
+    else {
+        let where;
+        try {
+            const [issueLabels, prLabels] = await Promise.all([
+                defaultListIssueLabels(octokit, owner, repoName, issueNum),
+                defaultListIssueLabels(octokit, owner, repoName, prNumber),
+            ]);
+            if (isAutoMergeBlocked(issueLabels, filingPolicy))
+                where = `issue #${issueNum} is labelled ${gateLabel}`;
+            else if (isAutoMergeBlocked(prLabels, filingPolicy))
+                where = `PR #${prNumber} is labelled ${gateLabel}`;
+        }
+        catch (err) {
+            where = `labels could not be read (${errorDetail(err)}) — failing closed on the ${gateLabel} gate`;
+        }
+        if (where) {
+            log('merge-gated', `land refused: ${where}`);
+            throw new MergeGatedError(`not merging PR #${prNumber} for issue #${issueNum}: ${where} (human approval required). Re-run \`factory land ${issueNum} --allow-gated\` to merge it deliberately.`, issueNum, prNumber, gateLabel);
+        }
+    }
+    const worktree = worktreePathFor(repoRoot, ghRepo, issueNum, branch.startsWith(`${LEGACY_BRANCH_PREFIX}/`) ? LEGACY_BRANCH_PREFIX : resolved);
+    const landSandboxPolicy = resolveSandboxPolicy(landFactoryConfig.sandbox, {
+        worktree,
+        repoRoot,
+    });
+    const worktreeSandbox = worktreeSandboxFor(landSandboxPolicy?.runtime, {
+        allowHosts: landSandboxPolicy?.allowHosts ?? [],
+    });
+    const withLandLock = (fn) => withGitLock(repoRoot, () => withFileLock(paths.mergeLock, fn, {
+        onSteal: (pid) => log('lock-stolen', `stole ${paths.mergeLock} from dead holder pid ${pid ?? 'unknown'}`),
+    }));
+    try {
+        try {
+            await landOpenPullRequest({
+                octokit,
+                owner,
+                repoName,
+                ghRepo,
+                repoRoot,
+                issue: issueNum,
+                branch,
+                worktree,
+                prNumber: prNumber,
+                log,
+                skipCI,
+                adminMerge: resolveMergePolicy(landFactoryConfig).admin,
+                withLock: withLandLock,
+                ensureWorktree: async () => {
+                    if (!existsSync(worktree)) {
+                        await gitOps.setupWorktree(repoRoot, branch, worktree, `origin/${branch}`, worktreeSandbox, log);
+                    }
+                },
+            });
+        }
+        catch (err) {
+            if (err instanceof AwaitingReviewError || err instanceof CiFailedError) {
+                await withLandLock(() => gitOps.cleanupWorktree(repoRoot, worktree, log, worktreeSandbox));
+            }
+            throw err;
+        }
+        log('merged', `squash-merged PR #${prNumber}`);
+        await withLandLock(() => gitOps.cleanupWorktree(repoRoot, worktree, log, worktreeSandbox));
+    }
+    catch (err) {
+        if (err instanceof LandConflictError || err instanceof AwaitingReviewError || err instanceof CiFailedError)
+            throw err;
+        log('fail', `merge failed: ${err.message}`);
+        throw new LandFailureError(`merge failed for issue #${issueNum}: ${err.message}`, 5);
+    }
+    return { branch, prNumber };
+}
+export function prLookupFailure(issueNum, branch, err) {
+    return new LandFailureError(`PR lookup failed for issue #${issueNum} (${branch}): ${errorDetail(err)}`, 5);
+}
+async function cmdTriage(opts) {
+    const repoRoot = await getRepoRoot();
+    const ghRepo = await getGitHubRepo();
+    const paths = getFactoryPaths(repoRoot);
+    if (!existsSync(paths.root)) {
+        throw new CliExitError(`factory: ${notInitializedMessage()}`, 2);
+    }
+    const product = opts.product ?? readActiveProduct(paths.product);
+    const repoConfig = configLoaders.loadRepoConfig(repoRoot);
+    const modelsConfig = applyRepoConfig(configLoaders.loadModelsConfig(), repoConfig);
+    const routesConfig = configLoaders.loadRoutesConfig();
+    const effective = resolveEffectiveConfig(repoConfig);
+    const router = new coreOps.ModelRouter(modelsConfig, routesConfig, false, undefined, effective.allowExperimental, effective.localOnly);
+    const model = router.resolve('triage') ?? 'claude-sonnet-5';
+    const flag = router.registryRef.getClaudeFlag(model);
+    const constitutionNote = product ? `Active constitution: ${product}.` : '';
+    const prompt = `Triage the open GitHub issues of ${ghRepo} for an autonomous software factory.
+${constitutionNote}
+Run: gh issue list --repo ${ghRepo} --state open --limit 100 --json number,title,labels,body
+Read every body. Exclude epics/PRDs/meta, external-account/credential/outreach issues,
+and anything too vague. Group by lane (same-file issues together). Order by dependency then value.
+Write ONLY the queue to ${paths.queueProposed} in format '<lane> <issue#>', with '#' comments
+explaining exclusions.`;
+    let plannerError;
+    logEvent(paths.events, 'triage', '-', `Triaging ${ghRepo} with ${model}`);
+    await shellOps
+        .exec(`claude -p ${shellEscape(prompt)} ${flag ? `--model ${flag}` : ''} --allowedTools "Bash(gh issue:*)" "Bash(gh repo:*)" Read Glob Grep Write`)
+        .catch((err) => {
+        plannerError = err;
+        logEvent(paths.events, 'warn', '-', `triage planner failed: ${errorDetail(err)}`);
+    });
+    const proposed = existsSync(paths.queueProposed) ? readFileSync(paths.queueProposed, 'utf-8') : '';
+    const message = triageProposalMessage(proposed, paths.queueProposed, paths.queue);
+    if (message) {
+        console.log(message);
+    }
+    else {
+        throw triageNoProposalError(plannerError);
+    }
+}
+export function triageProposalMessage(proposed, proposedPath, queuePath) {
+    if (!proposed.trim())
+        return null;
+    return `${proposed}\n---\nreview and run: factory triage accept   (promotes ${proposedPath} -> ${queuePath})`;
+}
+export async function cmdTriageAccept(opts) {
+    const repoRoot = await getRepoRoot();
+    const paths = getFactoryPaths(repoRoot);
+    if (!existsSync(paths.queueProposed)) {
+        console.log(`nothing to accept — ${paths.queueProposed} not found`);
+        return; // zero exit
+    }
+    const content = readFileSync(paths.queueProposed, 'utf-8');
+    const result = validateQueue(content);
+    if (!opts.force && !result.ok) {
+        throw new CliExitError(`factory: proposed queue is invalid — ${paths.queueProposed} left unchanged\n` +
+            result.errors.map((e) => `  - ${e}`).join('\n'), 1);
+    }
+    renameSync(paths.queueProposed, paths.queue); // same dir → atomic
+    let acceptedBy = 'unknown';
+    try {
+        acceptedBy = userInfo().username;
+    }
+    catch {
+        /* keep 'unknown' */
+    }
+    const suffix = opts.force ? ' (--force, validation skipped)' : '';
+    logEvent(paths.events, 'triage_accepted', '-', `accepted ${result.issues.length} issue(s) [${result.issues.join(', ')}] by ${acceptedBy}${suffix}`);
+    console.log(styleText('green', `queue accepted — ${result.issues.length} issue(s) promoted to ${paths.queue}`));
+}
+export async function cmdQueueMigrate(opts = {}) {
+    const repoRoot = await getRepoRoot();
+    const paths = getFactoryPaths(repoRoot);
+    const queueFile = opts.file ? resolve(repoRoot, opts.file) : paths.queue;
+    if (!existsSync(queueFile)) {
+        throw new CliExitError(`factory: queue not found at ${queueFile} — run factory init + triage first, or pass --file`, 2);
+    }
+    const { entries, diagnostics } = parseQueue(readFileSync(queueFile, 'utf-8'));
+    // Stage 1 — structural problems, reported before any GitHub call.
+    const structural = diagnostics.map((d) => d.message);
+    const firstLineFor = new Map();
+    for (const entry of entries) {
+        const first = firstLineFor.get(entry.issue);
+        if (first !== undefined) {
+            structural.push(`line ${entry.lineNo}: duplicate issue #${entry.issue} (already queued at line ${first})`);
+        }
+        else {
+            firstLineFor.set(entry.issue, entry.lineNo);
+        }
+    }
+    if (entries.length === 0 && structural.length === 0) {
+        structural.push('queue has no issue entries');
+    }
+    if (structural.length > 0) {
+        throw new CliExitError(`factory: queue is invalid — ${queueFile} left unchanged\n` + structural.map((p) => `  - ${p}`).join('\n'), 1);
+    }
+    // Stage 2 — GitHub preflight (read-only). Any closed/PR/inaccessible entry aborts all.
+    const [owner, repo] = (await getGitHubRepo()).split('/');
+    const octokit = getOctokit();
+    const unreachable = [];
+    for (const entry of entries) {
+        try {
+            const { data } = await octokit.rest.issues.get({ owner, repo, issue_number: entry.issue });
+            if (data.pull_request) {
+                unreachable.push(`line ${entry.lineNo}: #${entry.issue} is a pull request, not an issue`);
+            }
+            else if (data.state === 'closed') {
+                unreachable.push(`line ${entry.lineNo}: issue #${entry.issue} is closed — cannot queue`);
+            }
+        }
+        catch (err) {
+            unreachable.push(`line ${entry.lineNo}: issue #${entry.issue} is inaccessible — ${errorDetail(err)}`);
+        }
+    }
+    if (unreachable.length > 0) {
+        throw new CliExitError(`factory: queue migration aborted — ${unreachable.length} issue(s) cannot be migrated; no labels applied\n` +
+            unreachable.map((p) => `  - ${p}`).join('\n'), 1);
+    }
+    const plan = planQueueMigration(entries);
+    if (opts.dryRun) {
+        console.log(styleText('cyan', `dry run — ${plan.length} issue(s) would be labelled from ${queueFile}; no GitHub changes made`));
+        for (const step of plan) {
+            console.log(`  #${step.issue} → lane ${step.lane}, position ${step.position} [${step.labels.join(', ')}]`);
+        }
+        return;
+    }
+    const queue = createGithubQueue({ client: createOctokitQueueClient(octokit), owner, repo });
+    try {
+        await queue.migrateLocalQueue(entries);
+    }
+    catch (err) {
+        throw new CliExitError(`factory: queue migration failed — ${errorDetail(err)}`, 1);
+    }
+    console.log(styleText('green', `queue migrated — ${entries.length} issue(s) labelled from ${queueFile}`));
+}
+/** Append one `queue_added` event for newly queued issues; the silent sink keeps stdout untouched. */
+async function recordQueueAdded(lane, results) {
+    const queued = results.filter((r) => r.outcome === 'queued');
+    if (queued.length === 0)
+        return;
+    try {
+        const eventsFile = getFactoryPaths(await getRepoRoot()).events;
+        const summary = queued.map((r) => `#${r.issue} (order ${r.position})`).join(', ');
+        createLogger(eventsFile, { lane }, { out: { write: () => true } }).info('queue_added', `${lane}: ${summary} queued`);
+    }
+    catch (err) {
+        console.error(styleText('yellow', `factory: queue add event not recorded — ${errorDetail(err)}`));
+    }
+}
+/** Append one `issue_unparked` event; the silent sink keeps stdout untouched. */
+async function recordIssueUnparked(result) {
+    try {
+        const eventsFile = getFactoryPaths(await getRepoRoot()).events;
+        createLogger(eventsFile, { lane: result.lane, issue: result.issue }, { out: { write: () => true } }).info('issue_unparked', `#${result.issue} unparked → ${result.lane} (order ${result.order})`);
+    }
+    catch (err) {
+        console.error(styleText('yellow', `factory: unpark event not recorded — ${errorDetail(err)}`));
+    }
+}
+export async function cmdUnpark(issueArg, opts = {}) {
+    const issue = parseIssueArg(issueArg);
+    let result;
+    try {
+        const [owner, repo] = (await getGitHubRepo()).split('/');
+        result = await runUnpark({
+            client: createOctokitQueueClient(getOctokit()),
+            owner,
+            repo,
+            issue,
+            ...(opts.lane === undefined ? {} : { lane: opts.lane }),
+        });
+    }
+    catch (err) {
+        const code = err instanceof UnparkError ? err.code : 'unpark-failed';
+        throw new CliExitError(`factory: unpark #${issue} [${code}] — ${errorDetail(err)}`, 1);
+    }
+    await recordIssueUnparked(result);
+    if (opts.json) {
+        console.log(JSON.stringify(result));
+        return;
+    }
+    console.log(styleText('green', `#${issue} unparked → lane ${result.lane}, position ${result.order}`));
+}
+export async function cmdQueueAdd(lane, issueArgs, opts = {}) {
+    // Validate + dedupe BEFORE any GitHub call. parseIssueArg throws CliExitError(2) on bad input.
+    const seen = new Set();
+    const issues = [];
+    for (const raw of issueArgs) {
+        const n = parseIssueArg(raw);
+        if (!seen.has(n)) {
+            seen.add(n);
+            issues.push(n);
+        }
+    }
+    const enqueueAll = async () => {
+        const [owner, repo] = (await getGitHubRepo()).split('/');
+        const queue = createGithubQueue({ client: createOctokitQueueClient(getOctokit()), owner, repo });
+        return queue.enqueue(lane, issues);
+    };
+    let results;
+    if (opts.json) {
+        try {
+            results = await enqueueAll();
+        }
+        catch (err) {
+            throw new CliExitError(`factory: queue add failed — ${errorDetail(err)}`, 1);
+        }
+    }
+    else {
+        results = await enqueueAll();
+    }
+    await recordQueueAdded(lane, results);
+    if (opts.json) {
+        console.log(JSON.stringify(buildQueueAddJson(lane, results)));
+        const failedJson = results.filter((r) => r.outcome === 'failed');
+        if (failedJson.length > 0) {
+            throw new CliExitError(`factory: ${failedJson.length} issue(s) failed to queue`, 1);
+        }
+        return;
+    }
+    for (const r of results) {
+        if (r.outcome === 'queued') {
+            console.log(styleText('green', `#${r.issue} queued → lane ${lane}, position ${r.position}`));
+        }
+        else if (r.outcome === 'already-queued') {
+            console.log(`#${r.issue} already queued — skipped`);
+        }
+        else {
+            console.error(styleText('red', `#${r.issue} failed — ${r.detail}`));
+        }
+    }
+    const failed = results.filter((r) => r.outcome === 'failed');
+    if (failed.length > 0) {
+        throw new CliExitError(`factory: ${failed.length} issue(s) failed to queue`, 1);
+    }
+}
+export async function cmdQueueReconcile(opts = {}) {
+    const repoRoot = await getRepoRoot();
+    const paths = getFactoryPaths(repoRoot);
+    const [owner, repo] = (await getGitHubRepo()).split('/');
+    const client = createOctokitQueueClient(getOctokit());
+    const { report, conflicts } = await runQueueReconcile({
+        readSnapshot: () => readGithubQueueSnapshot({ client, owner, repo }),
+        reader: admissionStateReaderFor(paths.state),
+        ...(opts.lane === undefined ? {} : { lane: opts.lane }),
+    });
+    console.log(report);
+    if (conflicts > 0) {
+        throw new CliExitError(`factory: ${conflicts} queued issue(s) conflict with Factory App admission state`, 1);
+    }
+}
+export async function cmdQueueList(opts = {}) {
+    if (!opts.json)
+        throw new CliExitError('factory: queue list requires --json', 2);
+    const [owner, repo] = (await getGitHubRepo()).split('/');
+    let snapshot;
+    try {
+        snapshot = await readGithubQueueSnapshot({ client: createOctokitQueueClient(getOctokit()), owner, repo });
+    }
+    catch (err) {
+        throw new CliExitError(`factory: queue list failed — ${errorDetail(err)}`, 1);
+    }
+    console.log(JSON.stringify(buildQueueListJson(snapshot, opts.lane)));
+}
+export async function cmdRuns(opts = {}) {
+    if (!opts.json)
+        throw new CliExitError('factory: runs requires --json', 2);
+    if (opts.diffstat !== undefined) {
+        if (opts.limit !== undefined) {
+            throw new CliExitError('factory: runs — --diffstat and --limit cannot be combined', 2);
+        }
+        let issue;
+        try {
+            issue = parseDiffstatIssue(opts.diffstat);
+        }
+        catch (err) {
+            throw new CliExitError(`factory: runs — ${errorDetail(err)}`, 2);
+        }
+        const repoRoot = await getRepoRoot();
+        let out;
+        try {
+            out = await buildRunDiffstatJson({ runsDir: getFactoryPaths(repoRoot).runs, repoRoot, issue });
+        }
+        catch (err) {
+            if (err instanceof NoRunError)
+                throw new CliExitError(`factory: runs — ${err.message}`, 1);
+            throw new CliExitError(`factory: runs failed — ${errorDetail(err)}`, 1);
+        }
+        console.log(JSON.stringify(out));
+        return;
+    }
+    let limit;
+    try {
+        limit = parseRunsLimit(opts.limit);
+    }
+    catch (err) {
+        throw new CliExitError(`factory: runs — ${errorDetail(err)}`, 2);
+    }
+    const paths = getFactoryPaths(await getRepoRoot());
+    let result;
+    try {
+        result = await buildRunsJson(paths.runs, { limit });
+    }
+    catch (err) {
+        throw new CliExitError(`factory: runs failed — ${errorDetail(err)}`, 1);
+    }
+    for (const note of result.skipped)
+        console.error(note);
+    console.log(JSON.stringify(result.json));
+}
+export async function cmdQueueClear(opts = {}) {
+    const [owner, repo] = (await getGitHubRepo()).split('/');
+    const queue = createGithubQueue({ client: createOctokitQueueClient(getOctokit()), owner, repo });
+    const { report, exitCode, message } = await runQueueClear({
+        previewClear: () => queue.previewClear(opts.lane),
+        clear: () => queue.clear(opts.lane),
+        ...(opts.dryRun === undefined ? {} : { dryRun: opts.dryRun }),
+        ...(opts.yes === undefined ? {} : { yes: opts.yes }),
+        ...(opts.lane === undefined ? {} : { lane: opts.lane }),
+    });
+    console.log(report);
+    if (exitCode !== 0)
+        throw new CliExitError(message ?? 'factory: queue clear refused', exitCode);
+}
+export function triageNoProposalError(plannerError) {
+    const detail = plannerError ? ` — planner failed: ${errorDetail(plannerError)}` : '';
+    return new CliExitError(`triage produced no proposal${detail}`, 1);
+}
+/** Starts the in-process lane proxy for `factory run`/`supervise` when
+ *  `environment.proxy.enabled`. Never throws: a bind failure (EACCES on :80,
+ *  EADDRINUSE, …) is logged as a single `environment_proxy_unavailable` event
+ *  and lanes degrade to port-based URLs, exactly as if the proxy were disabled. */
+export async function startLaneProxy(paths, settings, deps = {}) {
+    if (!settings.enabled)
+        return {};
+    const { createProxy = createLaneProxy, emitEvent = logEvent } = deps;
+    const proxy = createProxy({ registryFile: paths.ports, domain: settings.domain, port: settings.port });
+    try {
+        const boundPort = await proxy.start();
+        writeProxyState(paths.proxyState, {
+            version: 1,
+            pid: process.pid,
+            port: boundPort,
+            domain: settings.domain,
+            startedAt: new Date().toISOString(),
+        });
+        emitEvent(paths.events, 'environment_proxy', 'all', `lane proxy listening on 127.0.0.1:${boundPort} (*.${settings.domain})`);
+        return { proxy };
+    }
+    catch (err) {
+        emitEvent(paths.events, 'environment_proxy_unavailable', 'all', `proxy unavailable (${err.message}) — lanes use port-based URLs`);
+        return {};
+    }
+}
+/** Runs the lane proxy in the foreground for manual use alongside single-lane
+ *  `factory ship` (which only probes proxy.json and degrades — it never spawns
+ *  a proxy itself). Running this command IS the opt-in: it starts even when
+ *  environment.proxy.enabled is false in factory.json. */
+async function cmdProxy() {
+    const repoRoot = await getRepoRoot();
+    const paths = getFactoryPaths(repoRoot);
+    const factoryConfig = configLoaders.loadFactoryConfigForRepo(paths.config);
+    const settings = resolveEnvironmentProxy(factoryConfig);
+    if (!settings.enabled) {
+        console.log(styleText('yellow', 'factory proxy: environment.proxy.enabled is false in factory.json — starting anyway (running this command is the explicit opt-in)'));
+    }
+    const proxy = createLaneProxy({ registryFile: paths.ports, domain: settings.domain, port: settings.port });
+    const boundPort = await proxy.start();
+    writeProxyState(paths.proxyState, {
+        version: 1,
+        pid: process.pid,
+        port: boundPort,
+        domain: settings.domain,
+        startedAt: new Date().toISOString(),
+    });
+    console.log(styleText('green', `factory proxy: listening on 127.0.0.1:${boundPort} (*.${settings.domain})`));
+    const leases = readPortLeases(paths.ports);
+    if (leases.length === 0) {
+        console.log('  no active lane leases yet');
+    }
+    else {
+        for (const lease of leases) {
+            console.log(`  ${laneHostLabel(lease.worktreeId)}.${settings.domain} -> 127.0.0.1:${lease.port}`);
+        }
+    }
+    console.log(styleText('dim', '  *.localhost resolves to loopback in Chrome/Firefox out of the box (RFC 6761); Safari/curl may need ' +
+        'a dnsmasq-backed .test domain instead — documented here, not solved.'));
+    await new Promise((resolveShutdown) => {
+        const shutdown = () => {
+            void proxy
+                .stop()
+                .catch(() => { })
+                .then(() => {
+                clearProxyState(paths.proxyState);
+                resolveShutdown();
+            });
+        };
+        process.once('SIGINT', shutdown);
+        process.once('SIGTERM', shutdown);
+    });
+    process.exit(0);
+}
+/** Runs factoryd in the foreground: a loopback-only HTTP server over the repo
+ *  registry (~/.factory/registry.json) (#777). Owns the daemon runtime state
+ *  next to the registry file — daemon.pid single-instance guard, daemon.port
+ *  bound-address record, daemon.log append sink (#1177). `factory daemon
+ *  start|stop|status|logs` wrap this process in a launchd LaunchAgent (#1179). */
+async function cmdFactoryd(opts) {
+    let config;
+    try {
+        config = resolveFactorydConfig(opts);
+    }
+    catch (err) {
+        if (err instanceof DaemonCtlError)
+            throw new CliExitError(err.message, err.code);
+        throw err;
+    }
+    const { registryFile, port } = config;
+    const runtime = daemonRuntimePaths(dirname(registryFile));
+    const acquired = await acquirePidFile(runtime);
+    if (!acquired.ok) {
+        throw new CliExitError(`factoryd already running (pid ${acquired.holderPid}) — stop it or remove ${runtime.pidFile}`, 2);
+    }
+    const logSink = createDaemonLogSink(runtime.logFile);
+    const log = (line) => {
+        console.log(styleText('dim', line));
+        logSink(line);
+    };
+    if (acquired.stalePid !== null)
+        log(`removed stale pid file (pid ${acquired.stalePid})`);
+    const runRuntime = await createRunRuntime({
+        registryFile,
+        allowParallel: true,
+        execute: createShipExecutor({ cliEntrypoint: fileURLToPath(new URL('../cli.js', import.meta.url)) }),
+    });
+    const daemon = createFactorydServer({ registryFile, runsDir: runtime.runsDir, port, log, runRuntime });
+    const boundPort = await daemon.start();
+    await writePortFile(runtime, boundPort);
+    const banner = [
+        `factoryd: listening on 127.0.0.1:${boundPort}`,
+        `  registry: ${registryFile}`,
+        `  pid file: ${runtime.pidFile} (pid ${process.pid})`,
+        `  port file: ${runtime.portFile}`,
+        `  log file: ${runtime.logFile}`,
+        `  GET http://127.0.0.1:${boundPort}/repos`,
+        `  POST http://127.0.0.1:${boundPort}/runs  {"runId","repo","issue"}`,
+    ];
+    console.log(styleText('green', banner[0] ?? ''));
+    for (const line of banner.slice(1))
+        console.log(line);
+    for (const line of banner)
+        logSink(line);
+    await new Promise((resolveShutdown) => {
+        const shutdown = () => {
+            void daemon
+                .stop()
+                .catch(() => { })
+                .then(() => releaseRuntimeFiles(runtime))
+                .then(() => resolveShutdown());
+        };
+        process.once('SIGINT', shutdown);
+        process.once('SIGTERM', shutdown);
+    });
+    process.exit(0);
+}
+function usageFlagOverrides(opts, threshold) {
+    return {
+        watch: opts.usageWatch,
+        [threshold]: opts.usageThreshold === undefined ? undefined : Number(opts.usageThreshold),
+        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)),
+                        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);
+        }
+        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,
+            })
+                .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,
+                    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),
+                    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 kpis = computeHealthKpis(events, costs);
+                await appendKpiSnapshot(paths, repoRoot, kpis);
+                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;
+    return async () => {
+        if ((await pendingCount()) === 0 && ingestCfg.enabled) {
+            emitEvent(paths.events, 'idle', 'auto', 'queue empty — waiting for ready issues');
+            return;
+        }
+        await cmdRunFn();
+    };
+}
+/** Builds the per-cycle auto-ingest hook passed to superviseLoop; failures are logged, never thrown. */
+export function createIngestHook(repoRoot, paths, ingestCfg, deps = {}) {
+    const { runAutoIngestFn = runAutoIngest, emitEvent = logEvent } = deps;
+    return async () => {
+        try {
+            const result = await runAutoIngestFn({
+                repoDir: repoRoot,
+                queueFile: paths.queue,
+                watermarkFile: paths.ingestWatermark,
+                label: ingestCfg.label,
+                lane: ingestCfg.lane,
+                maxPerCycle: ingestCfg.maxPerCycle,
+                branchPrefix: deps.branchPrefix ?? resolveBranchPrefix(),
+                forceAdmit: process.env.FACTORY_INGEST_FORCE_ADMIT === '1',
+            });
+            for (const held of result.skippedFileOverlap) {
+                emitEvent(paths.events, 'ingest_file_overlap_held', held.issue, `#${held.issue} held back — names the same file (${held.path}) as already-admitted #${held.collidesWith}; set FACTORY_INGEST_FORCE_ADMIT=1 to admit both`);
+            }
+            if (result.appended.length) {
+                emitEvent(paths.events, 'ingested', 'auto', `auto-ingest appended ${result.appended.length} ready issue(s): ${result.appended.join(', ')}`);
+            }
+            return result.appended.length;
+        }
+        catch (err) {
+            emitEvent(paths.events, 'warn', 'auto', `auto-ingest failed: ${errorDetail(err)}`);
+            return 0;
+        }
+    };
+}
+async function cmdSupervise(opts) {
+    const branchPrefix = branchPrefixOrExit(opts.branchPrefix);
+    const repoRoot = await getRepoRoot();
+    const paths = getFactoryPaths(repoRoot);
+    const ingestCfg = resolveIngestConfig(configLoaders.loadFactoryConfigForRepo(paths.config));
+    const countPending = async () => {
+        if (opts.localQueue === true) {
+            const content = existsSync(paths.queue) ? readFileSync(paths.queue, 'utf-8') : '';
+            const parsed = parseQueue(content);
+            warnQueueDiagnostics(parsed.diagnostics);
+            return parsed.entries.length;
+        }
+        const [owner, repo] = (await getGitHubRepo()).split('/');
+        const gq = createGithubQueue({ client: createOctokitQueueClient(getOctokit()), owner, repo });
+        const lanes = await gq.lanes();
+        const counts = await Promise.all(lanes.map((lane) => gq.list(lane)));
+        return counts.reduce((total, issues) => total + issues.length, 0);
+    };
+    if ((await countPending()) === 0 && !ingestCfg.enabled) {
+        throw new CliExitError('queue empty — run factory init + triage first', 2);
+    }
+    let knobs;
+    try {
+        knobs = resolveUsageKnobs(process.env, configLoaders.loadRepoConfig(repoRoot), usageFlagOverrides(opts, 'resumeAt'));
+    }
+    catch (err) {
+        throw new CliExitError(`factory: ${err.message}`, 2);
+    }
+    await withRepoRunLock(paths, 'factory supervise', () => superviseLoop({
+        cap: knobs.cap,
+        resumeAt: knobs.resumeAt,
+        pollMs: knobs.pollMs,
+        watch: knobs.watch,
+        watchSource: knobs.watchSource,
+        resumeAtSource: knobs.resumeAtSource,
+        pollSource: knobs.pollSource,
+        estimator: knobs.estimator,
+        stopFile: paths.stop,
+        eventsFile: paths.events,
+        now: opts.now,
+        runQueue: createSuperviseRunQueue(paths, ingestCfg, {
+            cmdRunFn: () => cmdRun({
+                localQueue: opts.localQueue,
+                autoMerge: opts.autoMerge,
+                usageWatch: opts.usageWatch,
+                usageThreshold: opts.usageThreshold,
+                usagePoll: opts.usagePoll,
+                branchPrefix: opts.branchPrefix,
+            }),
+            pendingCount: countPending,
+        }),
+        ingest: ingestCfg.enabled ? createIngestHook(repoRoot, paths, ingestCfg, { branchPrefix }) : undefined,
+    }));
+}
+export function laneQueueDeps(queue, lane) {
+    return {
+        claimNext: () => queue.claimNext(lane),
+        releaseIssue: (issue, outcome) => queue.release(issue, outcome),
+        heartbeat: (issue) => queue.heartbeat(issue),
+        countRemaining: async () => (await queue.list(lane)).length,
+    };
+}
+export function createQueuePreflightOps(octokit, owner, repo) {
+    return {
+        expectedHeadRepoFullName: `${owner}/${repo}`,
+        findOpenPR: (issue) => findOpenPRForIssue(octokit, owner, repo, issue),
+        getLandState: (prNumber) => getPullRequestLandState(octokit, owner, repo, prNumber),
+        watch: (ref) => internalOps.watchChecks({ octokit, owner, repo, ref }),
+        findSlicePlan: (issue) => findSlicePlanComment({ octokit, repo: `${owner}/${repo}`, issue }),
+        getPullState: async (prNumber) => {
+            const { data } = await octokit.rest.pulls.get({ owner, repo, pull_number: prNumber });
+            if (data.merged || data.merged_at)
+                return 'merged';
+            return data.state === 'open' ? 'open' : 'closed';
+        },
+        saveSlicePlan: async (issue, plan) => {
+            await upsertSlicePlanComment({ octokit, repo: `${owner}/${repo}`, issue, plan });
+        },
+    };
+}
+/** ADR-0147: wait on the current slice PR, record its merge, or park when it was closed unmerged.
+ *  Returns undefined to fall through to the Closes-PR preflight. */
+async function preflightSlice(issue, deps) {
+    let lookup;
+    try {
+        lookup = await deps.findSlicePlan(issue);
+    }
+    catch (err) {
+        return { kind: 'park', reason: `slice plan lookup failed: ${errorDetail(err)}` };
+    }
+    if (lookup.status === 'invalid') {
+        return {
+            kind: 'park',
+            reason: `slice plan comment ${lookup.commentId} on #${issue} is unreadable (${lookup.error})`,
+        };
+    }
+    if (lookup.status === 'not-found')
+        return undefined;
+    const { plan } = lookup;
+    const slice = currentSlice(plan);
+    if (slice === undefined || slice.state !== 'pr-open')
+        return undefined;
+    const label = `slice ${slice.index}/${plan.slices.length}`;
+    if (slice.prNumber === undefined) {
+        return { kind: 'park', reason: `${label} of #${issue} is pr-open but the slice plan records no PR number` };
+    }
+    const pr = slice.prNumber;
+    let state;
+    try {
+        state = await deps.getPullState(pr);
+    }
+    catch (err) {
+        return { kind: 'park', reason: `${label} PR #${pr} state lookup failed: ${errorDetail(err)}` };
+    }
+    if (state === 'open')
+        return { kind: 'defer' };
+    if (state === 'closed') {
+        return { kind: 'park', reason: `${label} PR #${pr} was closed without merging` };
+    }
+    try {
+        await deps.saveSlicePlan(issue, withSliceState(plan, slice.index, 'merged', pr));
+    }
+    catch (err) {
+        return {
+            kind: 'park',
+            reason: `${label} PR #${pr} merged but updating the slice plan failed: ${errorDetail(err)}`,
+        };
+    }
+    return undefined;
+}
+/** Resolve queued work from GitHub evidence without consuming model or worktree resources. */
+export async function preflightQueuedIssue(issue, deps) {
+    if (issue.labels.includes('factory:in-progress'))
+        return { kind: 'defer' };
+    const slice = await preflightSlice(issue.number, deps);
+    if (slice)
+        return slice;
+    let pr;
+    try {
+        pr = await deps.findOpenPR(issue.number);
+    }
+    catch (err) {
+        return { kind: 'park', reason: `PR lookup failed: ${errorDetail(err)}` };
+    }
+    if (!pr)
+        return { kind: 'build' };
+    if (pr.headRepoFullName !== deps.expectedHeadRepoFullName) {
+        return { kind: 'park', reason: `PR #${pr.number} head is not in ${deps.expectedHeadRepoFullName}` };
+    }
+    let state;
+    try {
+        state = await deps.getLandState(pr.number);
+    }
+    catch (err) {
+        return { kind: 'park', reason: `PR #${pr.number} merge-state lookup failed: ${errorDetail(err)}` };
+    }
+    if (state.isDraft !== false) {
+        return { kind: 'park', reason: `PR #${pr.number} is draft or its draft state is unavailable` };
+    }
+    if (!state.mergeStateStatus || state.mergeStateStatus === 'UNKNOWN') {
+        return { kind: 'park', reason: `PR #${pr.number} merge state is unavailable` };
+    }
+    let outcome;
+    try {
+        outcome = await deps.watch(pr.headSha);
+    }
+    catch (err) {
+        return { kind: 'park', reason: `CI watch for PR #${pr.number} failed: ${errorDetail(err)}` };
+    }
+    if (outcome !== 'success')
+        return { kind: 'park', reason: `CI for PR #${pr.number} ended ${outcome}` };
+    return { kind: 'adopt', branch: pr.branch };
+}
+export async function planRunLanes(input) {
+    if (input.localQueue) {
+        const content = input.readLocalQueue();
+        if (content === null) {
+            throw new CliExitError('queue empty — run factory init + triage first', 2);
+        }
+        const { entries, diagnostics } = parseQueue(content);
+        const byLane = new Map();
+        for (const e of entries) {
+            if (!byLane.has(e.lane))
+                byLane.set(e.lane, []);
+            byLane.get(e.lane).push(e.issue);
+        }
+        return {
+            lanes: [...byLane].map(([lane, issues]) => ({ lane, issues, deps: {} })),
+            diagnostics,
+        };
+    }
+    const gq = input.queue();
+    const lanes = await gq.lanes();
+    return {
+        lanes: lanes.map((lane) => ({ lane, issues: [], deps: laneQueueDeps(gq, lane) })),
+        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, pathExists = existsSync, emitEvent = logEvent, claimNext = async () => null, releaseIssue = async () => { }, heartbeat, reapWorktree = async () => { }, sweepFinished = async () => { }, countRemaining, 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) {
+            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;
+        }
+        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;
+            }
+            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, '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;
+                await reapWorktree(issue).catch(() => { });
+                await settle(issue, 'queued');
+                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 });
+}
+export async function isPrMerged(octokit, owner, repoName, branch) {
+    const { data: prs } = await octokit.rest.pulls.list({
+        owner,
+        repo: repoName,
+        state: 'all',
+        head: `${owner}:${branch}`,
+    });
+    if (prs.length === 0)
+        return false;
+    // Ship-it branch names get reused across separate runs for the same issue
+    // (e.g. a "verify-and-close" pass recreates the exact branch name an
+    // earlier, already-merged PR used) — GitHub PR numbers only increase, so
+    // the highest-numbered PR under this head is always the current one.
+    // Checking "was ANY PR ever merged under this branch name" (the old
+    // `state: 'closed'` + `.some()` behavior) matched the stale prior PR and
+    // falsely reported a brand-new, still-open PR under the same name as
+    // merged — waitForMerge then logged "landed" and skipped calling land(),
+    // leaving the real PR open forever while the lane believed it was done.
+    const latest = prs.reduce((newest, pr) => (pr.number > newest.number ? pr : newest));
+    return Boolean(latest.merged_at);
+}
+export async function findOpenPRNumber(octokit, owner, repoName, branch) {
+    const { data: prs } = await octokit.rest.pulls.list({
+        owner,
+        repo: repoName,
+        state: 'open',
+        head: `${owner}:${branch}`,
+    });
+    return prs[0]?.number;
+}
+export async function findOpenPRForIssue(octokit, owner, repoName, issueNum) {
+    const perPage = 100;
+    const matches = new RegExp(`\\bcloses\\s+#${issueNum}\\b`, 'i');
+    for (let page = 1;; page++) {
+        const { data: prs } = await octokit.rest.pulls.list({
+            owner,
+            repo: repoName,
+            state: 'open',
+            per_page: perPage,
+            page,
+        });
+        const pr = prs.find((p) => matches.test(p.body ?? ''));
+        if (pr) {
+            const headRepoFullName = pr.head.repo?.full_name ?? null;
+            if (headRepoFullName !== `${owner}/${repoName}`) {
+                return {
+                    number: pr.number,
+                    branch: pr.head.ref,
+                    headSha: pr.head.sha,
+                    headRepoFullName,
+                };
+            }
+            return { number: pr.number, branch: pr.head.ref, headSha: pr.head.sha, headRepoFullName };
+        }
+        if (prs.length < perPage)
+            return undefined;
+    }
+}
+export async function squashMergeAndDelete(octokit, owner, repoName, branch, prNumber, 
+/** `sha`: the CI-verified head commit. GitHub refuses the merge if the PR head has moved. */
+opts = {}) {
+    const { sha } = opts;
+    if (opts.admin) {
+        const run = opts.run ?? shellOps.exec;
+        const pin = sha ? ` --match-head-commit ${shellEscape(sha)}` : '';
+        await run(`gh pr merge ${prNumber} --repo ${shellEscape(`${owner}/${repoName}`)} --admin --squash --delete-branch${pin}`);
+        return;
+    }
+    await octokit.rest.pulls.merge({
+        owner,
+        repo: repoName,
+        pull_number: prNumber,
+        merge_method: 'squash',
+        ...(sha ? { sha } : {}),
+    });
+    // Best-effort branch delete: the merge is the source of truth.
+    await octokit.rest.git.deleteRef({ owner, repo: repoName, ref: `heads/${branch}` }).catch(() => { });
+}
+export class MergeGatedError extends Error {
+    issue;
+    prNumber;
+    label;
+    constructor(message, issue, prNumber, label) {
+        super(message);
+        this.issue = issue;
+        this.prNumber = prNumber;
+        this.label = label;
+        this.name = 'MergeGatedError';
+    }
+}
+export class LandConflictError extends Error {
+    parkReason = 'conflict';
+}
+/** 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 {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+    }
+}
+export class AwaitingReviewError extends Error {
+    prNumber;
+    constructor(message, prNumber) {
+        super(message);
+        this.prNumber = prNumber;
+    }
+}
+/** The target issue tripped the PLAN pre-flight size gate and was decomposed into real
+ *  filed sub-issues; the queue was rewritten. Not a park — the lane continues with the
+ *  children in place of the oversized issue. (#823) */
+export class IssueDecomposedError extends Error {
+    childIssues;
+    constructor(message, childIssues) {
+        super(message);
+        this.childIssues = childIssues;
+    }
+}
+export class LandFailureError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}
+/** Thrown when watchChecks reports a confirmed CI failure — a completed check run with a
+ *  non-passing conclusion. A confirmed failing check must never be merged, admin override
+ *  or not. See CiUnverifiedError for the no-verdict case. */
+export class CiFailedError extends Error {
+    prNumber;
+    parkReason = 'ci-failed';
+    constructor(message, prNumber) {
+        super(message);
+        this.prNumber = prNumber;
+    }
+}
+/** Thrown when the CI watch never reached a green verdict — a deadline timeout, no check runs ever
+ *  registering, or repeated API failures. A subclass of CiFailedError so every existing guard
+ *  (parkReasonFor → 'ci-failed', worktree cleanup, cmdLand's exit-0 path) treats "we don't know"
+ *  exactly like "we know it's red": never merge. */
+export class CiUnverifiedError extends CiFailedError {
+}
+const MAX_MERGE_ATTEMPTS = 5;
+const MERGE_RETRY_BASE_MS = 5_000;
+/** True when GitHub refused a SHA-pinned merge because the PR head moved past the verified
+ *  commit (REST 409, or gh's "Head branch was modified"). Retrying as-is can never succeed. */
+export function isHeadModifiedMergeError(err) {
+    if (err?.status === 409)
+        return true;
+    const msg = `${err instanceof Error ? err.message : ''}\n${errorDetail(err)}`;
+    return /head branch was modified/i.test(msg);
+}
+export function isReviewRequiredMergeError(err, state) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/approving review/i.test(msg) || /review is required/i.test(msg))
+        return true;
+    return state.mergeStateStatus === 'BLOCKED' && state.reviewDecision === 'REVIEW_REQUIRED';
+}
+export async function getPullRequestLandState(octokit, owner, repoName, prNumber) {
+    const result = await octokit.graphql(`query PullRequestLandState($owner: String!, $repo: String!, $number: Int!) {
+      repository(owner: $owner, name: $repo) {
+        pullRequest(number: $number) {
+          id
+          isDraft
+          mergeStateStatus
+          reviewDecision
+        }
+      }
+    }`, { owner, repo: repoName, number: prNumber });
+    return result.repository?.pullRequest ?? {};
+}
+export async function markPullRequestReady(octokit, pullRequestId) {
+    await octokit.graphql(`mutation MarkPullRequestReady($id: ID!) {
+      markPullRequestReadyForReview(input: { pullRequestId: $id }) {
+        pullRequest { isDraft }
+      }
+    }`, { id: pullRequestId });
+}
+export async function rebaseDirtyPullRequest(opts) {
+    const { issue, branch, worktree, prNumber, log, run = shellOps.exec, pathExists = existsSync } = opts;
+    if (!pathExists(worktree)) {
+        const msg = `PR #${prNumber} DIRTY on ${branch} and worktree gone`;
+        log('conflict', msg);
+        throw new LandConflictError(msg);
+    }
+    try {
+        await run('git rebase origin/main', { cwd: worktree });
+        await run(`git push --force-with-lease origin ${shellEscape(branch)}`, { cwd: worktree });
+    }
+    catch {
+        // Best-effort cleanup: the conflict logged below is the error we surface.
+        await run('git rebase --abort', { cwd: worktree }).catch(() => { });
+        const msg = `rebase conflict on ${branch} — parked`;
+        log('conflict', msg);
+        throw new LandConflictError(`issue #${issue}: ${msg}`);
+    }
+}
+export async function landOpenPullRequest(opts) {
+    const { octokit, owner, repoName, issue, branch, worktree, prNumber, log, run, pathExists, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), skipCI = false, adminMerge = process.env.FACTORY_MERGE_ADMIN === '1', watch = internalOps.watchChecks, withLock = (fn) => fn(), ensureWorktree, } = opts;
+    /** Watches CI on the PR's current head commit and returns that SHA once it is green, so the
+     *  merge can be pinned to exactly the commit CI verified. */
+    const watchCi = async () => {
+        let headSha;
+        let outcome;
+        try {
+            const { data: pr } = await octokit.rest.pulls.get({ owner, repo: repoName, pull_number: prNumber });
+            headSha = pr.head.sha;
+            outcome = await watch({ octokit, owner, repo: repoName, ref: headSha });
+        }
+        catch (err) {
+            const msg = `CI watch for ${branch} failed: ${errorDetail(err)} — refusing to merge without a green verdict`;
+            log('ci-failed', msg);
+            throw new CiUnverifiedError(msg, prNumber);
+        }
+        if (outcome === 'success')
+            return headSha;
+        if (outcome === 'failure') {
+            const msg = `CI failed for PR #${prNumber} on ${branch} — refusing to merge with a failing check`;
+            log('ci-failed', msg);
+            throw new CiFailedError(msg, prNumber);
+        }
+        const msg = `CI watch for ${branch} ended ${outcome} — refusing to merge without a green verdict`;
+        log('ci-failed', msg);
+        throw new CiUnverifiedError(msg, prNumber);
+    };
+    // The CI watch is a 10-20 minute wait, not a mutation: it must never run under the land
+    // locks, or every other lane's setupWorktree serializes behind it (#645).
+    let verifiedSha = skipCI ? undefined : await watchCi();
+    let state = await getPullRequestLandState(octokit, owner, repoName, prNumber);
+    if (state.mergeStateStatus === 'DIRTY') {
+        const rebased = await withLock(async () => {
+            // Re-check under the lock: a sibling lane may have landed (or rebased this branch)
+            // while we waited for it, so the DIRTY verdict read above can be stale.
+            state = await getPullRequestLandState(octokit, owner, repoName, prNumber);
+            if (state.mergeStateStatus !== 'DIRTY')
+                return false;
+            await ensureWorktree?.();
+            await rebaseDirtyPullRequest({ issue, branch, worktree, prNumber, log, run, pathExists });
+            return true;
+        });
+        if (rebased) {
+            if (!skipCI) {
+                verifiedSha = await watchCi();
+            }
+            state = await getPullRequestLandState(octokit, owner, repoName, prNumber);
+        }
+    }
+    for (let attempt = 1;; attempt++) {
+        try {
+            await withLock(async () => {
+                // Same rule as the rebase section: whatever we read before taking the lock (or before
+                // the backoff sleep) may be stale, so the attempt decides from a fresh read.
+                state = await getPullRequestLandState(octokit, owner, repoName, prNumber);
+                if (state.isDraft && state.id) {
+                    log('land', `PR #${prNumber} still a draft — re-issuing ready-for-review (attempt ${attempt})`);
+                    await markPullRequestReady(octokit, state.id).catch((err) => log('warn', `ready-for-review flip failed for PR #${prNumber}: ${errorDetail(err)}`));
+                }
+                await squashMergeAndDelete(octokit, owner, repoName, branch, prNumber, {
+                    admin: adminMerge,
+                    run,
+                    sha: verifiedSha,
+                });
+            });
+            return;
+        }
+        catch (err) {
+            if (verifiedSha && isHeadModifiedMergeError(err)) {
+                const msg = `PR #${prNumber} head moved past CI-verified commit ${verifiedSha} — refusing to merge an unverified head`;
+                log('ci-failed', msg);
+                throw new CiUnverifiedError(msg, prNumber);
+            }
+            if (isReviewRequiredMergeError(err, state)) {
+                log('awaiting-review', `PR #${prNumber} blocked on human review — leaving open for approval`);
+                throw new AwaitingReviewError(`PR #${prNumber} awaiting review: ${err.message}`, prNumber);
+            }
+            if (attempt >= MAX_MERGE_ATTEMPTS)
+                throw err;
+            log('land', `merge attempt ${attempt}/${MAX_MERGE_ATTEMPTS} failed (${err.message}); mergeStateStatus=${state.mergeStateStatus ?? 'unknown'} — retrying with backoff`);
+            // Backoff outside the lock: waiting is not a mutation (#645).
+            await sleep(MERGE_RETRY_BASE_MS * 2 ** (attempt - 1));
+        }
+    }
+}
+export function issueFromFactoryBranch(branch, prefix) {
+    return factoryBranchIssue(branch, prefix) ?? undefined;
+}
+export async function listOpenFactoryPRs(octokit, owner, repoName, branchPrefix) {
+    const prs = [];
+    let cursor;
+    for (;;) {
+        const result = await octokit.graphql(`query OpenFactoryPRs($owner: String!, $repo: String!, $cursor: String) {
+        repository(owner: $owner, name: $repo) {
+          pullRequests(states: OPEN, first: 100, after: $cursor) {
+            pageInfo { hasNextPage endCursor }
+            nodes { number headRefName reviewDecision isDraft }
+          }
+        }
+      }`, { owner, repo: repoName, cursor });
+        const pullRequests = result.repository?.pullRequests;
+        for (const node of pullRequests?.nodes ?? []) {
+            if (factoryBranchPrefixes(branchPrefix).some((p) => node.headRefName.startsWith(`${p}/`))) {
+                prs.push({
+                    number: node.number,
+                    branch: node.headRefName,
+                    reviewDecision: node.reviewDecision,
+                    isDraft: node.isDraft,
+                });
+            }
+        }
+        if (!pullRequests?.pageInfo?.hasNextPage)
+            break;
+        cursor = pullRequests.pageInfo.endCursor;
+    }
+    return prs;
+}
+export async function sweepApprovedPRs(repoRoot, ghRepo, paths, deps = {}, opts = {}) {
+    const { createOctokit = getOctokit, loadConfig = configLoaders.loadFactoryConfigForRepo, listPRs = listOpenFactoryPRs, land = landIssue, emitEvent = logEvent, writeLine = (line) => console.log(line), } = deps;
+    const [owner, repoName] = ghRepo.split('/');
+    const octokit = createOctokit();
+    const skipCI = configLoaders.resolveSkipCI(loadConfig(paths.config));
+    const prs = await listPRs(octokit, owner, repoName, opts.branchPrefix);
+    const landed = [];
+    const skipped = [];
+    const failed = [];
+    for (const pr of prs) {
+        const issue = issueFromFactoryBranch(pr.branch, opts.branchPrefix);
+        if (issue === undefined) {
+            const reason = 'no issue number in branch';
+            skipped.push({ pr: pr.number, branch: pr.branch, reason });
+            writeLine(`[factory] PR #${pr.number} (${pr.branch}) skipped: ${reason}`);
+            continue;
+        }
+        if (pr.reviewDecision !== 'APPROVED') {
+            const reason = `not approved (reviewDecision: ${pr.reviewDecision ?? 'none'})`;
+            skipped.push({ pr: pr.number, branch: pr.branch, reason });
+            writeLine(`[factory] PR #${pr.number} (${pr.branch}) skipped: ${reason}`);
+            continue;
+        }
+        try {
+            await land(issue, repoRoot, ghRepo, paths, octokit, skipCI, opts.branchPrefix);
+            landed.push(pr.number);
+            writeLine(`[factory] PR #${pr.number} (${pr.branch}) landed for issue #${issue}`);
+        }
+        catch (err) {
+            const reason = errorDetail(err);
+            failed.push({ pr: pr.number, issue, reason });
+            writeLine(`[factory] PR #${pr.number} (${pr.branch}) failed to land: ${reason}`);
+            continue;
+        }
+    }
+    emitEvent(paths.events, 'resume-approved', '-', `sweep: ${landed.length} landed, ${skipped.length} skipped, ${failed.length} failed of ${prs.length} open factory PRs`);
+    return { landed, skipped, failed };
+}
+export async function cmdResumeApproved(opts = {}) {
+    const branchPrefix = branchPrefixOrExit(opts.branchPrefix);
+    const repoRoot = await getRepoRoot();
+    const ghRepo = await getGitHubRepo();
+    const paths = getFactoryPaths(repoRoot);
+    const result = await sweepApprovedPRs(repoRoot, ghRepo, paths, {}, { branchPrefix });
+    console.log(styleText('green', `✅ resume-approved: ${result.landed.length} landed, ${result.skipped.length} skipped, ${result.failed.length} failed`));
+    if (result.failed.length > 0) {
+        throw new CliExitError(`factory: resume-approved: ${result.failed.length} PR(s) failed to land`, 5);
+    }
+}
+/** Consecutive merged-state check failures tolerated before waitForMerge parks the lane.
+ *  At the shipped 120s poll that is ~20 minutes of 100% failure (ADR: sustained-failure park). */
+export const MERGE_CHECK_MAX_CONSECUTIVE_FAILURES = 10;
+/** Wall-clock backstop: continuous merged-state check failure for this long parks the lane even
+ *  if fewer than MERGE_CHECK_MAX_CONSECUTIVE_FAILURES attempts were made (slower poll cadence). */
+export const MERGE_CHECK_FAILURE_BUDGET_MS = 2 * 60 * 60 * 1000;
+/** GitHub signals both primary and secondary rate limits with 403 — the same status it uses for a
+ *  token that genuinely lacks the scope. Only a 403 with no rate-limit evidence is permanent. */
+function looksRateLimited(err) {
+    const headers = err?.response?.headers ?? {};
+    const remaining = headers['x-ratelimit-remaining'];
+    if (typeof remaining === 'string' && remaining.trim() === '0')
+        return true;
+    if (typeof remaining === 'number' && remaining === 0)
+        return true;
+    if (headers['retry-after'] !== undefined)
+        return true;
+    return /rate limit|secondary rate|abuse detection/i.test(errorDetail(err));
+}
+/** True when a merged-state check failure cannot recover by retrying: an expired/revoked token
+ *  (401) or a token missing `pulls:read` (403 with no rate-limit evidence). */
+export function isPermanentMergeCheckError(err) {
+    const status = err?.status;
+    if (status === 401)
+        return true;
+    if (status !== 403)
+        return false;
+    return !looksRateLimited(err);
+}
+async function defaultListIssueLabels(octokit, owner, repo, issue) {
+    const { data } = await octokit.rest.issues.listLabelsOnIssue({ owner, repo, issue_number: issue });
+    return data.map((label) => label.name);
+}
+export async function waitForMerge(issue, branch, repoRoot, ghRepo, paths, deps = {}) {
+    const { createOctokit = getOctokit, pathExists = existsSync, checkMerged = isPrMerged, loadConfig = configLoaders.loadFactoryConfigForRepo, land = landIssue, listIssueLabels = defaultListIssueLabels, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), emitEvent = logEvent, mergeEnabled, writeLine = (line) => console.log(line), now = () => Date.now(), mergeOverrides, } = deps;
+    const factoryConfig = loadConfig(paths.config);
+    const isMergeEnabled = mergeEnabled ?? (() => resolveMergePolicy(factoryConfig, process.env, mergeOverrides).auto);
+    const skipCI = configLoaders.resolveSkipCI(factoryConfig);
+    const filingPolicy = resolveFilingPolicy(factoryConfig);
+    const octokit = createOctokit();
+    const [owner, repoName] = ghRepo.split('/');
+    emitEvent(paths.events, 'await-merge', issue, `waiting to merge ${branch}`);
+    let consecutiveFailures = 0;
+    let firstFailureAt = null;
+    while (!pathExists(paths.stop)) {
+        // The merge wait logs nothing on its happy path, so each poll bumps the per-issue heartbeat:
+        // status/TUI staleness rules (ADR-0086, ADR-0093) otherwise read a live wait as a dead run.
+        if (paths.runs)
+            touchRunActivity(phaseSnapshotFile(paths.runs, issue), new Date().toISOString()).catch(() => { });
+        let merged = false;
+        try {
+            merged = await checkMerged(octokit, owner, repoName, branch);
+            consecutiveFailures = 0;
+            firstFailureAt = null;
+        }
+        catch (err) {
+            consecutiveFailures++;
+            firstFailureAt ??= now();
+            const detail = errorDetail(err);
+            emitEvent(paths.events, 'warn', issue, `merged-state check failed (treating as not merged): ${detail}`);
+            const permanent = isPermanentMergeCheckError(err);
+            const elapsedMs = now() - firstFailureAt;
+            const budgetSpent = elapsedMs >= MERGE_CHECK_FAILURE_BUDGET_MS;
+            const streakSpent = consecutiveFailures >= MERGE_CHECK_MAX_CONSECUTIVE_FAILURES;
+            if (permanent || streakSpent || budgetSpent) {
+                const trigger = permanent
+                    ? 'permanent error (auth/scope — retrying cannot help)'
+                    : `${consecutiveFailures} consecutive failures over ${Math.round(elapsedMs / 1000)}s`;
+                const msg = `merged-state check for ${branch} is not recovering — parking lane after ${trigger}: ${detail}`;
+                emitEvent(paths.events, 'escalate', issue, msg);
+                throw new LaneParkError(msg, 'escalate');
+            }
+        }
+        if (merged) {
+            emitEvent(paths.events, 'landed', issue, 'PR merged');
+            return;
+        }
+        if (isMergeEnabled()) {
+            let labels = [];
+            try {
+                labels = await listIssueLabels(octokit, owner, repoName, issue);
+            }
+            catch (err) {
+                emitEvent(paths.events, 'warn', issue, `label check failed (treating as blocked): ${errorDetail(err)}`);
+                labels = [filingPolicy.selfFixLabel];
+            }
+            if (isAutoMergeBlocked(labels, filingPolicy)) {
+                emitEvent(paths.events, 'merge-gated', issue, `auto-merge blocked by ${filingPolicy.selfFixLabel} — awaiting human approval`);
+                writeLine(`[factory] #${issue} auto-merge gated (${filingPolicy.selfFixLabel}); awaiting human merge (poll 120s)`);
+                await sleep(120_000);
+                continue;
+            }
+            await land(issue, repoRoot, ghRepo, paths, octokit, skipCI);
+            return;
+        }
+        writeLine(`[factory] #${issue} awaiting human merge (poll 120s)`);
+        await sleep(120_000);
+    }
+}
+const USAGE_UNAVAILABLE_LINE = '[factory] supervise: usage signal unavailable — proceeding without resume gate (set FACTORY_USAGE_ESTIMATOR=1 to gate on the heuristic)';
+export async function superviseLoop(deps) {
+    const { cap, resumeAt, pollMs, watch = true, watchSource = 'default', resumeAtSource = 'default', pollSource = 'default', estimator = false, stopFile, eventsFile, now, runQueue, readUsageFn = () => readUsage({ cap, estimator }), pathExists = existsSync, clearStop = (path) => rmSync(path, { force: true }), sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), emitEvent = logEvent, writeLine = (line) => console.log(line), ingest, } = deps;
+    let cycle = 0;
+    if (resumeAtSource === 'flag') {
+        const detail = 'usage watchdog threshold set by flag: --usage-threshold';
+        writeLine(`[factory] supervise: ${detail}`);
+        emitEvent(eventsFile, 'watchdog', 'usage', detail);
+    }
+    if (pollSource === 'flag') {
+        const detail = 'usage watchdog poll set by flag: --usage-poll';
+        writeLine(`[factory] supervise: ${detail}`);
+        emitEvent(eventsFile, 'watchdog', 'usage', detail);
+    }
+    while (true) {
+        cycle++;
+        let pct = 0;
+        let source = 'unavailable';
+        if (!watch) {
+            writeLine(`[factory] supervise: usage watchdog disabled (${usageWatchSourceLabel(watchSource, watch)}) — skipping resume gate`);
+        }
+        else {
+            if (watchSource === 'flag') {
+                writeLine(`[factory] supervise: usage watchdog enabled (${usageWatchSourceLabel(watchSource, watch)}) — enforcing resume gate`);
+            }
+            let reading = await readUsageFn();
+            if (reading === null) {
+                writeLine(USAGE_UNAVAILABLE_LINE);
+            }
+            else {
+                pct = reading.pct;
+                source = reading.source;
+                if (cycle > 1 || !now) {
+                    while (pct >= resumeAt) {
+                        writeLine(`[factory] supervise: trailing usage (${source}) ${Math.round(pct * 100)}% >= resume gate ${Math.round(resumeAt * 100)}% — waiting ${pollMs / 1000}s`);
+                        await sleep(pollMs);
+                        reading = await readUsageFn();
+                        if (reading === null) {
+                            writeLine(USAGE_UNAVAILABLE_LINE);
+                            pct = 0;
+                            source = 'unavailable';
+                            break;
+                        }
+                        pct = reading.pct;
+                        source = reading.source;
+                    }
+                }
+            }
+        }
+        emitEvent(eventsFile, 'resumed', 'usage', `supervise cycle ${cycle}: trailing usage (${source}) at ${Math.round(pct * 100)}% of cap — starting run`);
+        clearStop(stopFile);
+        if (ingest) {
+            const appended = await ingest();
+            if (appended > 0)
+                writeLine(`[factory] supervise: auto-ingest appended ${appended} ready issue(s)`);
+        }
+        await runQueue();
+        if (pathExists(stopFile))
+            continue;
+        if (ingest) {
+            await sleep(pollMs);
+            continue;
+        }
+        break;
+    }
+    emitEvent(eventsFile, 'supervisor-done', 'usage', 'supervise finished — queue drained or lanes need attention');
+}
+export function getCliVersion() {
+    return createRequire(import.meta.url)('../../package.json').version;
+}
+function toLeaseRow(health) {
+    return {
+        worktreeId: health.lease.worktreeId,
+        branch: health.lease.branch,
+        port: health.lease.port,
+        pid: health.lease.pid,
+        alive: health.alive,
+        reason: health.reason,
+        portSquatted: health.portSquatted,
+    };
+}
+function toGreenPrRow(pr) {
+    return { number: pr.number, branch: pr.branch, issue: pr.issue, ageHours: pr.ageHours };
+}
+async function scanGreenPrs(ghRepo, octokit) {
+    if (!ghRepo || !octokit)
+        return { status: 'skipped', detail: 'skipped — no GitHub repo or token' };
+    const [owner, repoName] = ghRepo.split('/');
+    try {
+        const prs = await internalOps.findUnmergedGreenPrs({
+            client: createOctokitGreenPrClient(octokit),
+            owner,
+            repo: repoName,
+        });
+        return { status: 'ok', rows: prs.map(toGreenPrRow) };
+    }
+    catch (err) {
+        return { status: 'failed', detail: err?.message ?? String(err) };
+    }
+}
+function probeClaudeKeychain() {
+    if (process.platform !== 'darwin')
+        return { status: 'skipped', detail: 'skipped — not macOS' };
+    if (!coreOps.isCommandAvailable('claude'))
+        return { status: 'skipped', detail: 'skipped — claude CLI not on PATH' };
+    if (process.env.ANTHROPIC_API_KEY)
+        return { status: 'skipped', detail: 'skipped — ANTHROPIC_API_KEY auth in use' };
+    // Check the entry for the profile child `claude` runs will use (CLAUDE_CONFIG_DIR), not
+    // always the default one.
+    const service = claudeKeychainService();
+    const profile = { service, configDir: claudeConfigDirOverride() };
+    try {
+        shellOps.execSync(`security find-generic-password -s ${shellEscape(service)}`, {
+            timeout: 10_000,
+            stdio: 'ignore',
+        });
+        return { status: 'readable', ...profile };
+    }
+    catch {
+        return { status: 'unreadable', inTmux: !!process.env.TMUX, ...profile };
+    }
+}
+async function cmdDoctor(opts = {}) {
+    const checks = runDoctorChecks({
+        commandAvailable: coreOps.isCommandAvailable,
+        envPresent: (key) => !!process.env[key],
+        tryExec: (cmd) => {
+            try {
+                return shellOps.execSync(cmd, { timeout: 10_000, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+            }
+            catch {
+                return null;
+            }
+        },
+        pathExists: existsSync,
+        distFreshness: distFreshnessProbe(import.meta.url),
+    });
+    let repoRoot;
+    try {
+        repoRoot = shellOps
+            .execSync('git rev-parse --show-toplevel', {
+            timeout: 10_000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        })
+            .trim();
+    }
+    catch {
+        repoRoot = null;
+    }
+    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';
+    if (host === 'ok') {
+        const policy = repoRoot === null
+            ? undefined
+            : 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(claudeKeychainCheck(probeClaudeKeychain()));
+    checks.push(...sandboxClaudeAuthChecks({ host, sandboxed, hostDetail, sandboxDetail }));
+    if (repoRoot !== null) {
+        const paths = getFactoryPaths(repoRoot);
+        const factoryConfig = configLoaders.loadFactoryConfigForRepo(paths.config);
+        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)));
+        // 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));
+    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);
+}
+/** Creates the STOP file in one exclusive open (no check-then-write race). Returns false when it already existed. */
+function createStopFile(stopFile) {
+    try {
+        writeFileSync(stopFile, '', { flag: 'wx' });
+        return true;
+    }
+    catch (err) {
+        if (err?.code === 'EEXIST')
+            return false;
+        throw err;
+    }
+}
+/** Removes the STOP file in one unlink (no check-then-unlink race). Returns false when it was not there. */
+function removeStopFile(stopFile) {
+    try {
+        unlinkSync(stopFile);
+        return true;
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return false;
+        throw err;
+    }
+}
+export async function cmdStop(opts = {}) {
+    const repoRoot = await getRepoRoot();
+    const paths = getFactoryPaths(repoRoot);
+    const json = opts.json ? { repo: await getGitHubRepo() } : undefined;
+    ensureDir(paths.state);
+    const before = !createStopFile(paths.stop);
+    const after = true;
+    logEventQuietly(paths.events, 'stop-file-set', before ? 'factory stop: STOP already set (no-op)' : 'factory stop: STOP set — lanes halt between issues');
+    if (json) {
+        console.log(JSON.stringify(buildStopResumeJson({ action: 'stop', repo: json.repo, before, after })));
+        return;
+    }
+    console.log('STOP set — lanes halt between issues');
+}
+export async function cmdResume(opts = {}) {
+    const repoRoot = await getRepoRoot();
+    const paths = getFactoryPaths(repoRoot);
+    const json = opts.json ? { repo: await getGitHubRepo() } : undefined;
+    const before = removeStopFile(paths.stop);
+    const after = false;
+    if (existsSync(paths.root)) {
+        logEventQuietly(paths.events, 'stop-file-cleared', before ? 'factory resume: STOP cleared' : 'factory resume: STOP was not set (no-op)');
+    }
+    if (json) {
+        console.log(JSON.stringify(buildStopResumeJson({ action: 'resume', repo: json.repo, before, after })));
+        return;
+    }
+    console.log('STOP cleared');
+}
+// ---------- main ----------
+export async function main(argv = process.argv, deps = {}) {
+    if (argv.slice(2).length === 0) {
+        console.log(formatOverview());
+        return;
+    }
+    const staleExit = runStalenessGuard({
+        entryUrl: import.meta.url,
+        env: process.env,
+        argv,
+        error: (m) => console.error(styleText('red', m)),
+        warn: (m) => console.error(styleText('yellow', m)),
+    });
+    if (staleExit !== null) {
+        process.exitCode = staleExit;
+        return;
+    }
+    const program = new Command();
+    program
+        .name('factory')
+        .description('Multi-agent software factory with boss-worker-checker orchestration')
+        .version(getCliVersion())
+        .addHelpText('before', PREREQUISITES_TEXT)
+        .addHelpText('after', HELP_FOOTER_TEXT);
+    program
+        .command('init')
+        .description('Set up .factory/ in this repo (config, constitution, queue file, .gitignore) and check model reachability')
+        .option('--force', 'Overwrite an existing .factory config, constitution, and .gitignore')
+        .action((opts) => cmdInit(opts));
+    program
+        .command('migrate')
+        .description('Upgrade .factory/ to the v2 layout (config, constitution.md, .gitignore, state/); --to-yaml converts config.json to config.yaml')
+        .option('--dry-run', 'Print planned changes without writing')
+        .option('--to-yaml', 'Convert .factory/config.json to .factory/config.yaml (removes the JSON only after a round-trip check)')
+        .action((opts) => cmdMigrate(opts));
+    program
+        .command('constitution')
+        .description('Manage product constitutions — .factory/constitution.md in this repo is the source of truth')
+        .option('--init [product]', 'Write .factory/constitution.md in this repo, scaffolded from the template (an optional name overrides the display name)')
+        .option('--list', 'List available constitutions')
+        .option('--product <name>', 'Seed .factory/constitution.md from the bundled example constitution for <name>')
+        .option('--force', 'With --init or --product, overwrite an existing .factory/constitution.md')
+        .action((opts) => cmdConstitution(opts));
+    program
+        .command('models')
+        .description('List models with their tiers, cost per 1M tokens, and availability')
+        .option('--doctor', 'Probe provider CLIs and env keys; report per-model reachability')
+        .action(cmdModels);
+    program
+        .command('doctor')
+        .description('Check your environment (git, claude, gh auth, GitHub token, npm, sandbox, .factory/)')
+        .option('--reconcile', 'Reap stale port leases, dead-run worktrees, stale issue claims, orphan sf-job-*/factory.managed containers, and orphan factory-* sbx VMs')
+        .action((opts) => cmdDoctor(opts));
+    program
+        .command('cost')
+        .description('Show recorded model spend by model (--issue for one issue)')
+        .option('--issue <number>', 'Show per-entry detail for one issue')
+        .option('--json', 'Print one JSON object (schemaVersion 1): rows, perModel, total; unpriced cost is null')
+        .action((opts) => cmdCost(opts));
+    program
+        .command('usage')
+        .description('Report 5-hour subscription usage (falls back to a list-price estimate)')
+        .option('--json', 'Print one JSON object (schemaVersion 1) instead of text')
+        .action((opts) => cmdUsage({}, opts));
+    program
+        .command('status')
+        .description('Show active runs, the GitHub queue, provider health, and recent events')
+        .option('--kpis', 'Also show the full health KPIs and the effective config')
+        .option('--json', 'Print one JSON object (schemaVersion 1): repo, product, stop, breaker, active claims; --kpis is ignored')
+        .action((opts) => cmdStatus(opts));
+    program
+        .command('runs')
+        .description('Print per-issue run state from the local runs directory as one JSON object, newest first (read-only)')
+        .option('--json', 'Print one JSON object (schemaVersion 1) — required')
+        .option('--limit <n>', 'Show at most N runs (default 50)')
+        .option('--diffstat <issue>', "Print per-file added/deleted line counts for one issue's run branch vs origin/<default branch>")
+        .action(async (opts) => {
+        await cmdRuns(opts);
+    });
+    program
+        .command('kpis')
+        .description('Compute factory health KPIs and record a trend snapshot')
+        .option('--branch-prefix <prefix>', BRANCH_PREFIX_MATCH_OPTION_DESCRIPTION)
+        .action(async (opts) => {
+        await cmdKpis(opts);
+    });
+    const classifierCmd = program
+        .command('classifier')
+        .description('Inspect or backtest the shadow PR classifier track record');
+    classifierCmd
+        .command('report')
+        .description('Confusion table, rule-of-three slip bounds and model-vs-floor agreement from classifier-outcomes.jsonl')
+        .option('--json', 'Print one JSON object with the same numbers')
+        .action((opts) => cmdClassifierReport(opts));
+    classifierCmd
+        .command('backtest')
+        .description('Replay the floor and shadow classifier over merged factory PRs and print the outcome report')
+        .requiredOption('--since <date>', 'Only PRs merged on or after this date (YYYY-MM-DD)')
+        .option('--limit <n>', 'Classify at most N PRs (oldest merge first)')
+        .option('--labels <file>', 'CSV of hand labels `pr,class` (class: defect|clean|gated) that override heuristic outcomes')
+        .option('--max-cost <usd>', 'Stop before the next PR once estimated model spend reaches this many USD')
+        .option('--branch-prefix <prefix>', BRANCH_PREFIX_MATCH_OPTION_DESCRIPTION)
+        .option('--json', 'Print one JSON object instead of the table')
+        .action((opts) => cmdClassifierBacktestEntry(opts));
+    program
+        .command('garden')
+        .description('Read-only report of recurring failure patterns in local events, deduped against open issues by GitHub search')
+        .option('--report', 'Print recurring CHECK failure-signature clusters as markdown')
+        .option('--since <duration>', 'Only consider events from this window, e.g. 7d, 36h, 2w', DEFAULT_GARDEN_SINCE)
+        .option('--max-clusters <n>', 'Print at most this many clusters', String(DEFAULT_GARDEN_MAX_CLUSTERS))
+        .option('--json', 'Print the same cluster data as JSON')
+        .option('--out <file>', 'Write the report to this file instead of stdout')
+        .option('--only-new', 'Omit clusters an open issue already tracks; keep new and tracked: unknown clusters')
+        .action((opts) => cmdGarden(opts));
+    program
+        .command('tui')
+        .description('Live read-only view of the current run (q to quit)')
+        .option('--local-queue', 'Read .factory/queue instead of claiming issues from GitHub Issues')
+        .action((opts) => cmdTui(opts, deps.runTui ?? runTui));
+    program
+        .command('logs')
+        .description('Print pipeline events from .factory/events.ndjson (--follow to tail)')
+        .option('--follow', 'Keep watching for new events')
+        .option('--json', 'Emit one JSON object per line')
+        .option('--issue <number>', 'Only show events for this issue')
+        .action(async (opts) => {
+        const repoRoot = await getRepoRoot();
+        const paths = getFactoryPaths(repoRoot);
+        await cmdLogs(opts, { eventsFile: paths.events });
+    });
+    program
+        .command('feedback <pr-url>')
+        .description("File one factory issue (bug, factory:needs-triage) from a PR's human review findings")
+        .option('--note <text>', 'Use this as the issue title instead of the first finding')
+        .option('--branch-prefix <prefix>', BRANCH_PREFIX_MATCH_OPTION_DESCRIPTION)
+        .action(cmdFeedback);
+    const filingCmd = program.command('filing').description('Inspect upstream factory reports (nothing is sent)');
+    filingCmd
+        .command('preview <run-id>')
+        .description('Print the exact redacted [factory-report] title and body that would be sent upstream; sends nothing')
+        .option('--branch-prefix <prefix>', BRANCH_PREFIX_MATCH_OPTION_DESCRIPTION)
+        .action((runId, opts) => cmdFilingPreview(runId, opts));
+    const triage = program
+        .command('triage')
+        .description('Have a model propose a queue from open issues into .factory/queue.proposed')
+        .option('--product <name>', 'Product constitution to scope triage')
+        .action(cmdTriage);
+    triage
+        .command('accept')
+        .description('Validate and atomically promote .factory/queue.proposed to .factory/queue')
+        .option('--force', 'Skip validation and promote as-is')
+        .action(async (opts) => {
+        await cmdTriageAccept(opts);
+    });
+    program
+        .command('unpark <issue>')
+        .description('Unpark a factory:parked issue: remove factory:parked and re-queue it in its lane with a fresh order label (same path as `queue add`)')
+        .option('--lane <lane>', "Lane to re-queue into (default: the issue's existing factory:lane:* label)")
+        .option('--json', 'Print one JSON object (schemaVersion 1): ok, action, issue, lane, order, labelsBefore, labelsAfter')
+        .action(async (issue, opts) => {
+        await cmdUnpark(issue, opts);
+    });
+    const queue = program
+        .command('queue')
+        .description('Manage the GitHub-label work queue (list, add, clear, reconcile, migrate)');
+    queue
+        .command('migrate')
+        .description('Copy valid .factory/queue lane order into GitHub issue labels')
+        .option('--file <path>', 'Read the legacy queue from an explicit path instead of .factory/queue')
+        .option('--dry-run', 'Print the intended label updates without mutating GitHub')
+        .action((opts) => cmdQueueMigrate(opts));
+    queue
+        .command('add <lane> <issues...>')
+        .description('Queue explicit GitHub issues into a lane — applies factory:queued + factory:lane:<lane> (and an order label), creating any missing factory labels idempotently')
+        .option('--json', 'Print one JSON object (schemaVersion 1): ok, action, lane, issues[{number, outcome, order, labelsAdded}], labelsCreated')
+        .action(async (lane, issues, opts) => {
+        await cmdQueueAdd(lane, issues, opts);
+    });
+    queue
+        .command('reconcile')
+        .description('Report queued GitHub issues that conflict with Factory App admission state, with the repair-flow pointer for each')
+        .option('--lane <lane>', 'Only reconcile one lane')
+        .action(async (opts) => {
+        await cmdQueueReconcile(opts);
+    });
+    queue
+        .command('list')
+        .description('Print queued, in-progress and parked GitHub-queue issues per lane as one JSON object (read-only)')
+        .option('--json', 'Print one JSON object (schemaVersion 1) — required')
+        .option('--lane <lane>', 'Only list this lane (factory:lane:<lane>)')
+        .action(async (opts) => {
+        await cmdQueueList(opts);
+    });
+    queue
+        .command('clear')
+        .description('Empty the GitHub-backed queue: removes factory:queued and factory:order:* from every unclaimed queued issue (lane labels kept; claimed issues skipped). Preview with --dry-run; limit to one lane with --lane')
+        .option('--dry-run', 'Print the preview and exit 0 without changing any label')
+        .option('--yes', 'Confirm and remove the queue labels')
+        .option('--lane <lane>', 'Only clear queued issues in this lane (factory:lane:<lane>)')
+        .action(async (opts) => {
+        await cmdQueueClear(opts);
+    });
+    const hosted = program
+        .command('hosted')
+        .description('Experimental remote-runner execution (needs FACTORY_HOSTED_EXEC=1)');
+    hosted
+        .command('smoke')
+        .description('Local end-to-end hosted-exec smoke: create → lease → Docker run → result → cleanup')
+        .option('--repo <slug>', 'owner/repo to clone and run against', 'on-par/software-factory')
+        .option('--image <image>', 'Container image for the smoke run', 'node:20-alpine')
+        .action(async (opts) => {
+        await cmdHostedSmoke(opts);
+    });
+    hosted
+        .command('runner')
+        .description('Register capabilities with the local control plane and lease one compatible job, then exit')
+        .option('--url <url>', 'Control-plane base URL', 'http://127.0.0.1:8799')
+        .option('--runner-id <id>', 'Runner identity (default runner-<pid>)')
+        .option('--capabilities <csv>', 'Comma-separated capability list', 'git,node')
+        .option('--timeout <ms>', 'Bounded wait window for a compatible job, in ms', '30000')
+        .option('--poll-interval <ms>', 'Delay between poll attempts, in ms', '2000')
+        .option('--lease-ttl <ms>', 'Lease TTL, in ms', '300000')
+        .option('--heartbeat-interval <ms>', 'Expected heartbeat interval, in ms', '30000')
+        .action(async (opts) => {
+        await cmdHostedRunner(opts);
+    });
+    hosted
+        .command('queue')
+        .description('Queue one job to the local control plane, tail it to terminal, print the result')
+        .option('--url <url>', 'Control-plane base URL', 'http://127.0.0.1:8799')
+        .option('--repo <slug>', 'owner/repo the job runs against', 'on-par/software-factory')
+        .option('--task <text>', 'Opaque task payload')
+        .option('--capabilities <csv>', 'Comma-separated required capabilities', 'git,node')
+        .option('--authority <authority>', 'Required authority', 'repo:read')
+        .option('--timeout <ms>', 'Bounded wait for a terminal result, in ms', '120000')
+        .option('--poll-interval <ms>', 'Delay between summary polls, in ms', '1000')
+        .option('--job-id <id>', 'Explicit job id (default server-generated)')
+        .action(async (opts) => {
+        await cmdHostedQueue(opts);
+    });
+    program
+        .command('check <issue>')
+        .alias('ready')
+        .description('Check an issue before queuing: required fields and whether the size gate runs it as-is or would split it, plus an advisory INVEST report (read-only, optional --deep model review; exit 0 ready, 1 missing fields or ungradeable criteria, 2 invalid --deep output, 3 would split)')
+        .option('--json', 'Print one JSON object with fields, criteria findings, size verdict, INVEST findings, and reasons')
+        .option('--deep', 'Also call the triage-tier model once: preview the proposed split when the issue would split, otherwise suggest missing criteria and scope concerns (prints model id and cost; never files anything; exit 2 on invalid model output)')
+        .action(cmdCheck);
+    program
+        .command('ship <issue>')
+        .description('Plan → build → check one GitHub issue and open a ready-for-review PR; never merges (merge later with land)')
+        .option('--product <name>', 'Override active product constitution')
+        .option('--no-auto-rework', 'Disable automatic rework loop')
+        .option('--interactive', 'Pause before opening the PR and wait for approval from the TUI')
+        .option('--approve-plan', 'Pause after PLAN freezes the spec and wait for approval before BUILD')
+        .option('--no-sandbox', 'Disable the containment sandbox for agent runs (dangerous)')
+        .option('--branch-prefix <prefix>', BRANCH_PREFIX_OPTION_DESCRIPTION)
+        .action(async (issueNum, opts) => {
+        await cmdShip(parseIssueArg(issueNum), opts);
+    });
+    program
+        .command('run-issue <issue>')
+        .description('Like ship, but loads the issue first and exits 2 before any worktree or PR if it cannot be found')
+        .option('--product <name>', 'Override active product constitution')
+        .option('--no-auto-rework', 'Disable automatic rework loop')
+        .option('--interactive', 'Pause before opening the PR and wait for approval from the TUI')
+        .option('--approve-plan', 'Pause after PLAN freezes the spec and wait for approval before BUILD')
+        .option('--no-sandbox', 'Disable the containment sandbox for agent runs (dangerous)')
+        .option('--branch-prefix <prefix>', BRANCH_PREFIX_OPTION_DESCRIPTION)
+        .option('--run-children', 'File mode only: when the size gate files child issues, run them (slice mode never files issues)')
+        .option('--size-gate <mode>', 'Size gate mode for this run: file (file child issues / park), slice (ship as sequential slice PRs under the same issue; never files issues) or off (skip both gates); beats sizeGate.mode in the config')
+        .option('--max-slices <count>', 'Slice mode: most slices a not-yet-started slice plan may have (1-20); an over-cap plan is recorded and parks; beats sizeGate.maxSlices (default 10)')
+        .action(async (issueNum, opts) => {
+        await cmdRunIssue(parseIssueArg(issueNum), opts);
+    });
+    program
+        .command('run-brief <file>')
+        .description('Like run-issue, but the work comes from a local Markdown brief instead of a GitHub issue')
+        .option('--product <name>', 'Override active product constitution')
+        .option('--no-auto-rework', 'Disable automatic rework loop')
+        .option('--interactive', 'Pause before opening the PR and wait for approval from the TUI')
+        .option('--approve-plan', 'Pause after PLAN freezes the spec and wait for approval before BUILD')
+        .option('--no-sandbox', 'Disable the containment sandbox for agent runs (dangerous)')
+        .option('--workspace <dir>', 'Local-only: run PLAN/BUILD/CHECK in this caller-provided git workspace and disable PR creation, merging, queue polling, and GitHub mutations')
+        .option('--artifacts <dir>', 'Local-only: write a versioned benchmark artifact manifest (manifest.json, request.json, events.ndjson, diff.patch) to this directory; requires --workspace')
+        .option('--branch-prefix <prefix>', BRANCH_PREFIX_OPTION_DESCRIPTION)
+        .action(async (file, opts) => {
+        await cmdRunBrief(file, opts);
+    });
+    program
+        .command('local-small-dry-run <issue>')
+        .description('Create a bounded local-small step plan and first context pack without changing source files')
+        .option('--spec <path>', 'Frozen spec path; defaults to .factory/plans/issue-<n>.md')
+        .option('--output <path>', 'Artifact directory; defaults to .factory/local-small/issue-<n>')
+        .action(async (issueNum, opts) => {
+        await cmdLocalSmallDryRun(parseIssueArg(issueNum), opts);
+    });
+    program
+        .command('local-small-overnight')
+        .description('Process a curated local-small queue one issue at a time: review-only PRs, never merges, parks on ambiguity')
+        .option('--queue <path>', 'Curated queue file; defaults to .factory/local-small/overnight-queue')
+        .option('--state <path>', 'Resume-state file; defaults to .factory/local-small/overnight-state.json')
+        .action(async (opts) => {
+        await cmdLocalSmallOvernight(opts);
+    });
+    program
+        .command('land <issue>')
+        .description("Squash-merge the issue's open PR once CI is green, then remove its worktree (left open if CI fails or review is pending)")
+        .option('--branch-prefix <prefix>', BRANCH_PREFIX_MATCH_OPTION_DESCRIPTION)
+        .option('--allow-gated', 'Merge even when the issue or PR carries the no-auto-merge gate label (human override; writes an AUDIT line and a merge-gated-override event)')
+        .action(async (issueNum, opts) => {
+        await cmdLand(parseIssueArg(issueNum), opts);
+    });
+    program
+        .command('resume-approved')
+        .description(`Land open factory PRs (factory/*, plus legacy ${LEGACY_BRANCH_PREFIX}/*) whose review is now approved; skip the rest`)
+        .option('--branch-prefix <prefix>', BRANCH_PREFIX_MATCH_OPTION_DESCRIPTION)
+        .action(async (opts) => {
+        await cmdResumeApproved(opts);
+    });
+    program
+        .command('run')
+        .description('Claim queued issues (factory:queued labels) and ship them, lanes in parallel; merges only when auto-merge is on')
+        .option('--local-queue', 'Read .factory/queue instead of claiming issues from GitHub Issues')
+        .option('--auto-merge', 'Merge eligible PRs autonomously, overriding .factory/config.yaml and FACTORY_MERGE')
+        .option('--no-auto-merge', 'Never merge autonomously, overriding .factory/config.yaml and FACTORY_MERGE')
+        .option('--pr-classifier', 'Hold PRs whose review floor is B or C for a human (applies no-auto-merge), overriding .factory/config.json and FACTORY_PR_CLASSIFIER')
+        .option('--no-pr-classifier', 'Never run the PR classifier gate, overriding .factory/config.json and FACTORY_PR_CLASSIFIER')
+        .option('--usage-watch', 'Enforce the usage gate for this run, overriding .factory/config.yaml and FACTORY_USAGE_WATCH')
+        .option('--no-usage-watch', 'Skip the usage gate for this run, overriding .factory/config.yaml and FACTORY_USAGE_WATCH')
+        .option('--usage-threshold <fraction>', "Override .factory/config.yaml and FACTORY_STOP_AT for this run's usage threshold")
+        .option('--usage-poll <seconds>', "Override .factory/config.yaml and FACTORY_USAGE_POLL for this run's usage poll")
+        .option('--branch-prefix <prefix>', BRANCH_PREFIX_OPTION_DESCRIPTION)
+        .action((opts) => cmdRun(opts));
+    program
+        .command('proxy')
+        .description('Run the opt-in lane reverse proxy in the foreground (run and supervise start it themselves)')
+        .action(cmdProxy);
+    const daemonCmd = program
+        .command('daemon')
+        .description('Manage factoryd, the long-running background service for this user');
+    daemonCmd
+        .command('run')
+        .description('Run factoryd in the foreground: a localhost-only HTTP API over the repo registry')
+        .option('--port <n>', `Port to bind on 127.0.0.1 (default ${DEFAULT_FACTORYD_PORT})`)
+        .option('--registry <file>', 'Registry file to serve (default ~/.factory/registry.json)')
+        .option('--auto-update', 'Opt in to automatic factoryd self-update (default: off)')
+        .action((opts) => cmdFactoryd(opts));
+    const daemonCtl = (fn) => fn().catch((err) => {
+        if (err instanceof DaemonCtlError)
+            throw new CliExitError(err.message, err.code);
+        throw err;
+    });
+    daemonCmd
+        .command('start')
+        .description('Install and load the com.onpar.factoryd LaunchAgent (macOS only; KeepAlive, RunAtLoad)')
+        .action(() => daemonCtl(() => cmdDaemonStart(deps.daemon)));
+    daemonCmd
+        .command('stop')
+        .description('Unload the LaunchAgent (macOS only; plist stays installed)')
+        .action(() => daemonCtl(() => cmdDaemonStop(deps.daemon)));
+    daemonCmd
+        .command('status')
+        .description('Report factoryd pid, uptime, and attached repos')
+        .option('--json', 'Print one JSON object (schemaVersion 1) instead of text')
+        .action((opts) => daemonCtl(() => cmdDaemonStatus(deps.daemon, { json: opts.json })));
+    daemonCmd
+        .command('logs')
+        .description('Print or tail ~/.factory/daemon.log')
+        .option('-f, --follow', 'Keep tailing')
+        .option('-n, --lines <n>', 'Lines to print first (default 100)')
+        .action((opts) => daemonCtl(() => cmdDaemonLogs(opts, deps.daemon)));
+    const worktreeCmd = program.command('worktree').description('Clean up stale factory worktrees (gc)');
+    worktreeCmd
+        .command('gc')
+        .description('Remove stale factory worktrees (merged/closed branches or older than TTL) and scrub credentials')
+        .option('--dry-run', 'Preview what would be removed without deleting anything')
+        .option('--ttl-days <n>', 'Override worktree.gcTtlDays from .factory/config.yaml (default 7)')
+        .option('--branch-prefix <prefix>', BRANCH_PREFIX_MATCH_OPTION_DESCRIPTION)
+        .action(cmdWorktreeGc);
+    program
+        .command('reset <issue...>')
+        .description("Remove an issue's local factory state (worktree, local branch, plan/phase files, rework history, logs, leases) so the next run starts fresh. A worktree or branch with uncommitted changes or unpushed commits is kept unless --force is passed. Do not run while that issue's lane is active. Preview with --dry-run")
+        .option('--dry-run', 'List every worktree, branch, file, history entry, log dir, claim and lease that would be removed, without changing anything')
+        .option('--force', 'Remove worktrees and branches even when they have uncommitted changes or unpushed commits')
+        .option('--branch-prefix <prefix>', BRANCH_PREFIX_MATCH_OPTION_DESCRIPTION)
+        .action(cmdReset);
+    program
+        .command('supervise')
+        .description('Unattended loop: wait for usage headroom, run the queue, repeat until it is empty')
+        .option('--now', 'Skip the initial headroom wait')
+        .option('--local-queue', 'Read .factory/queue instead of claiming issues from GitHub Issues')
+        .option('--auto-merge', 'Merge eligible PRs autonomously, overriding .factory/config.yaml and FACTORY_MERGE')
+        .option('--no-auto-merge', 'Never merge autonomously, overriding .factory/config.yaml and FACTORY_MERGE')
+        .option('--usage-watch', 'Enforce the usage gate for this run, overriding .factory/config.yaml and FACTORY_USAGE_WATCH')
+        .option('--no-usage-watch', 'Skip the usage gate for this run, overriding .factory/config.yaml and FACTORY_USAGE_WATCH')
+        .option('--usage-threshold <fraction>', "Override .factory/config.yaml and FACTORY_RESUME_AT for this run's usage threshold")
+        .option('--usage-poll <seconds>', "Override .factory/config.yaml and FACTORY_USAGE_POLL for this run's usage poll")
+        .option('--branch-prefix <prefix>', BRANCH_PREFIX_OPTION_DESCRIPTION)
+        .action(async (opts) => {
+        await cmdSupervise(opts);
+    });
+    program
+        .command('stop')
+        .description('Tell running lanes to halt after their current issue')
+        .option('--json', 'Print one JSON object (schemaVersion 1): action, repo, stopFlag before/after')
+        .action((opts) => cmdStop(opts));
+    program
+        .command('resume')
+        .description('Clear a stop so lanes pick up new issues again')
+        .option('--json', 'Print one JSON object (schemaVersion 1): action, repo, stopFlag before/after')
+        .action((opts) => cmdResume(opts));
+    applyHelpGroups(program);
+    const previousLoaders = configLoaders;
+    const previousGitOps = gitOps;
+    const previousInternalOps = internalOps;
+    const previousShellOps = shellOps;
+    const previousCoreOps = coreOps;
+    const previousPhaseOps = phaseOps;
+    const previousOctokitFactory = octokitFactory;
+    configLoaders = resolveConfigLoaders(deps, DEFAULT_CONFIG_LOADERS);
+    gitOps = resolveGitOps(deps, DEFAULT_GIT_OPS);
+    internalOps = resolveInternalOps(deps, DEFAULT_INTERNAL_OPS);
+    shellOps = resolveShellOps(deps, DEFAULT_SHELL_OPS);
+    coreOps = resolveCoreOps(deps, DEFAULT_CORE_OPS);
+    phaseOps = resolvePhaseOps(deps, DEFAULT_PHASE_OPS);
+    octokitFactory = deps.octokit;
+    try {
+        await program.parseAsync(argv);
+    }
+    catch (err) {
+        if (err instanceof CliExitError) {
+            console.error(styleText('red', err.message));
+            process.exitCode = err.code;
+            return;
+        }
+        throw err;
+    }
+    finally {
+        configLoaders = previousLoaders;
+        gitOps = previousGitOps;
+        internalOps = previousInternalOps;
+        shellOps = previousShellOps;
+        coreOps = previousCoreOps;
+        octokitFactory = previousOctokitFactory;
+        phaseOps = previousPhaseOps;
+    }
+}
+//# sourceMappingURL=index.js.map