@on-par/factory-cli 0.9.0 → 0.9.2

package/dist/cli/index.js

@@ -5,16 +5,17 @@ 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 { basename, dirname, join, 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 { 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, kpiBranchPrefixes, 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, reconstructKpiEvents, recordLeasePgid, releasePortLease, renderKpiReport, renderKpiTrend, resolveAutoFailover, resolveCodexDisabled, resolveDefectWindowDays, resolveBuildPublish, resolveSizeGateMode, parseSizeGateMode, parseMaxSlices, resolveSizeGateMaxSlices, SIZE_GATE_MODES, resolveDesignRegressionBlock, resolveReadinessUpdateIssueBody, 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, createPlanReuseStore, checkBaseHealth, 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, defaultRegistryPath, 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, parseRemoteSlug, setupWorktree, shellEscape, shouldProxyEgress, slugify, startEgressProxy, sweepWorktrees, watchChecks, watchChecksWithInfraRerun, 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 { applyStateRootOption } from './state-root.js';
 import { buildCostJson } from './cost-json.js';
 import { buildQueueAddJson } from './queue-add-json.js';
 import { buildQueueListJson } from './queue-list.js';
@@ -22,17 +23,19 @@ 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 { buildStatusUpdateJson, formatUpdateStartupLine, formatUpdateStatusLine, initialUpdateState, readUpdateState, updateStatePath, writeUpdateState, } from './update-state.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 { cmdDaemonLogs, cmdDaemonStart, cmdDaemonStatus, cmdDaemonStop, createAutoUpdateDeps, DaemonCtlError, detectInstall, loadDaemonFileConfig, recoverStaleDrain, resolveFactorydConfig, runAutoUpdateLoop, } from './daemon.js';
+import { checkForUpdate, cmdSelfUpdateCheck } from './self-update.js';
+import { analyzeEventLog, claudeKeychainCheck, doctorFailed, eventLogCheck, formatClaimReconcileReport, formatContainerReconcileReport, formatDoctorChecks, formatMicroVmReconcileReport, formatReconcileReport, formatWorktreeReconcileReport, hasSandboxRuntime, leaseChecks, keychainPreflightError, orphanContainerChecks, orphanMicroVmChecks, runDoctorChecks, sandboxAuthSkipDetail, 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 { buildFeedbackDeps, resolveFeedbackRepo, runFeedback } from './feedback.js';
 import { ensureFactoryExcluded, writeSampleQueue } from './init-files.js';
 import { cmdLogs } from './logs.js';
 import { applyHelpGroups } from './help-groups.js';
@@ -40,6 +43,7 @@ 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 { createBaseHoldGate, formatBaseHoldCleared, formatBaseHoldStatus, readBaseHold, writeBaseHold, } from './base-hold.js';
 import { readRunFlagOverrides, writeRunFlagOverrides } from './run-flags.js';
 import { distFreshnessProbe, runStalenessGuard } from './staleness.js';
 import { readStopFileStatus, stopSentinelCheck, stopSentinelRunSkipMessage } from './stop-sentinel.js';
@@ -487,10 +491,34 @@ export async function runFeedbackCommand(prUrl, opts, deps, log = console.log) {
         throw err;
     }
 }
+/** owner/name of the checkout's origin remote, or null when there is none or it is not a GitHub remote. Never throws. */
+export async function readOriginSlug(shell = shellOps) {
+    try {
+        const { stdout } = await shell.exec('git remote get-url origin');
+        return parseRemoteSlug(stdout.trim());
+    }
+    catch {
+        return null;
+    }
+}
 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));
+    let repo;
+    try {
+        repo = resolveFeedbackRepo({
+            flag: opts.repo,
+            config: configLoaders.loadFactoryConfigForRepo(paths.config).filing.repo,
+            remote: await readOriginSlug(),
+        });
+    }
+    catch (err) {
+        throw new CliExitError(err instanceof Error ? err.message : String(err), 2);
+    }
+    await runFeedbackCommand(prUrl, opts, buildFeedbackDeps(getOctokit(), paths, prefix, createOctokitFilingClient, {
+        repo,
+        shareLocal: opts.includeLocalPaths === true,
+    }));
 }
 async function resolveFactoryCommit() {
     return resolveFactoryCheckoutCommit(dirname(fileURLToPath(import.meta.url)), async (cmd, cwd) => (await shellOps.exec(cmd, { cwd })).stdout);
@@ -809,10 +837,24 @@ function readTextFileOrEmpty(path) {
         throw err;
     }
 }
-async function appendKpiSnapshot(paths, repoRoot, kpis) {
+/** Local events plus human-* events reconstructed from GitHub; warns and marks the result partial when the fetch fails (#2342). */
+async function reconstructHumanEventsForKpis(events, branchPrefix) {
+    let owner = '';
+    let repoName = '';
+    const recon = await reconstructKpiEvents(events, async (issues) => {
+        [owner, repoName] = (await getGitHubRepo()).split('/');
+        return fetchHumanEventSources(getOctokit(), owner, repoName, issues, kpiBranchPrefixes(branchPrefix));
+    });
+    if (recon.partial) {
+        console.error(styleText('yellow', `factory: GitHub human-event reconstruction failed (${recon.error}) — KPI snapshot marked partial (local log only)`));
+    }
+    return { ...recon, owner, repoName };
+}
+async function appendKpiSnapshot(paths, repoRoot, kpis, opts = {}) {
     const record = kpisToHistoryRecord(kpis, new Date().toISOString().slice(0, 10), {
         commitSha: await currentCommitSha(),
         models: resolvedModelTiers(repoRoot, paths.root),
+        partial: opts.partial,
     });
     const updated = appendKpiHistoryLine(readTextFileOrEmpty(paths.kpiHistory), record);
     ensureDir(paths.state);
@@ -938,20 +980,10 @@ async function cmdKpis(opts = {}) {
     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`));
-    }
+    const recon = await reconstructHumanEventsForKpis(events, branchPrefix);
+    let allEvents = recon.events;
+    const prSources = recon.sources;
+    const { owner, repoName } = recon;
     if (prSources.length > 0) {
         try {
             const windowDays = resolveDefectWindowDays(configLoaders.loadFactoryConfigForRepo(paths.config));
@@ -973,7 +1005,7 @@ async function cmdKpis(opts = {}) {
     const kpis = computeHealthKpis(allEvents, costs);
     let history;
     try {
-        ({ history } = await appendKpiSnapshot(paths, repoRoot, kpis));
+        ({ history } = await appendKpiSnapshot(paths, repoRoot, kpis, { partial: recon.partial }));
     }
     catch (err) {
         console.error(styleText('yellow', `factory: KPI snapshot failed (${err?.message ?? err}) — showing the report without persisting a new snapshot`));
@@ -1085,6 +1117,7 @@ export async function cmdStatus(opts = {}) {
             stop: existsSync(paths.stop),
             breakers: await new ProviderBreaker(paths.breaker).list(),
             active,
+            update: buildStatusUpdateJson(readUpdateState(updateStatePath(daemonRuntimePaths().dir))),
             now: Date.now(),
         })));
         return;
@@ -1128,6 +1161,12 @@ export async function cmdStatus(opts = {}) {
     else {
         console.log('  (no queue file)');
     }
+    const baseHold = readBaseHold(paths.baseHold);
+    if (baseHold !== null && baseHold.repo === ghRepo) {
+        console.log(styleText('bold', '\n== Base hold =='));
+        for (const line of formatBaseHoldStatus(baseHold))
+            console.log(line);
+    }
     console.log(styleText('bold', '\n== Queue =='));
     if (!hasGitHubToken()) {
         console.log('  (no GitHub token — run `gh auth login`)');
@@ -1154,6 +1193,8 @@ export async function cmdStatus(opts = {}) {
         }
     }
     console.log(styleText('bold', '\n== Health =='));
+    const update = buildStatusUpdateJson(readUpdateState(updateStatePath(daemonRuntimePaths().dir)));
+    console.log(`  ${formatUpdateStatusLine(update)}`);
     if (opts.kpis) {
         console.log(styleText('bold', '\n  Effective config:'));
         for (const line of describeEffectiveConfig({
@@ -1504,6 +1545,7 @@ export async function shipIssue(issueNum, opts, ctx, deps = {}) {
         'held',
         'conflict',
         'ci-failed',
+        'ci-infra',
         'timeout',
     ]);
     let terminalMessage;
@@ -1645,6 +1687,7 @@ export async function shipIssue(issueNum, opts, ctx, deps = {}) {
         },
         localOnly: Boolean(ctx?.localOnly),
         blockUnresolvedRegressions: resolveDesignRegressionBlock(factoryConfig),
+        readinessUpdateIssueBody: resolveReadinessUpdateIssueBody(factoryConfig),
         publishFromBuild: resolveBuildPublish(factoryConfig),
         sizeGateMode,
         maxSlices,
@@ -1678,10 +1721,12 @@ export async function shipIssue(issueNum, opts, ctx, deps = {}) {
         resolveBaseUrl,
         getIssueSpend: () => issueSpend,
         breaker,
+        planReuse: ctx?.localOnly ? undefined : createPlanReuseStore(specPath),
         planPhase: phases.planPhase,
         buildPhase: phases.buildPhase,
         checkPhase: phases.checkPhase,
         shipPhase: phases.shipPhase,
+        checkBaseHealth: deps.checkBaseHealth ?? checkBaseHealth,
         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.
@@ -2518,8 +2563,12 @@ async function cmdTriage(opts) {
     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);
+    // Triage always runs `claude -p`, so only claude-cli models with a flag are runnable.
+    const registry = router.registryRef;
+    const resolved = router.resolveAll('triage');
+    const candidates = resolved.length > 0 ? resolved : ['claude-sonnet-5'];
+    const model = candidates.find((m) => registry.getHarnessId(m) === 'claude-cli' && registry.getClaudeFlag(m));
+    const flag = model ? registry.getClaudeFlag(model) : undefined;
     const constitutionNote = product ? `Active constitution: ${product}.` : '';
     const prompt = `Triage the open GitHub issues of ${ghRepo} for an autonomous software factory.
 ${constitutionNote}
@@ -2529,7 +2578,7 @@ and anything too vague. Group by lane (same-file issues together). Order by depe
 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}`);
+    logEvent(paths.events, 'triage', '-', `Triaging ${ghRepo} with ${flag ?? 'claude default model'}`);
     await shellOps
         .exec(`claude -p ${shellEscape(prompt)} ${flag ? `--model ${flag}` : ''} --allowedTools "Bash(gh issue:*)" "Bash(gh repo:*)" Read Glob Grep Write`)
         .catch((err) => {
@@ -2915,7 +2964,9 @@ async function cmdProxy() {
 async function cmdFactoryd(opts) {
     let config;
     try {
-        config = resolveFactorydConfig(opts);
+        const registryFile = opts.registry ?? defaultRegistryPath();
+        const fileConfig = loadDaemonFileConfig(join(dirname(registryFile), 'daemon.json'));
+        config = resolveFactorydConfig({ ...opts, registry: registryFile }, { install: detectInstall(), fileConfig });
     }
     catch (err) {
         if (err instanceof DaemonCtlError)
@@ -2935,6 +2986,29 @@ async function cmdFactoryd(opts) {
     };
     if (acquired.stalePid !== null)
         log(`removed stale pid file (pid ${acquired.stalePid})`);
+    for (const notice of config.notices)
+        log(notice);
+    const updateFile = updateStatePath(runtime.dir);
+    const previousUpdate = readUpdateState(updateFile);
+    for (const stop of recoverStaleDrain(previousUpdate, (file) => {
+        try {
+            unlinkSync(file);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    })) {
+        log(`update: removed stale STOP ${stop}`);
+    }
+    const updateState = initialUpdateState(config, previousUpdate);
+    try {
+        writeUpdateState(updateFile, updateState);
+    }
+    catch (err) {
+        log(`could not write ${updateFile}: ${errorDetail(err)}`);
+    }
+    log(formatUpdateStartupLine(updateState));
     const runRuntime = await createRunRuntime({
         registryFile,
         allowParallel: true,
@@ -2946,6 +3020,8 @@ async function cmdFactoryd(opts) {
     const banner = [
         `factoryd: listening on 127.0.0.1:${boundPort}`,
         `  registry: ${registryFile}`,
+        `  update mode: ${config.autoUpdate.mode} (channel ${config.autoUpdate.channel ?? 'none'}, install ${config.install.kind})`,
+        `  update state: ${updateFile}`,
         `  pid file: ${runtime.pidFile} (pid ${process.pid})`,
         `  port file: ${runtime.portFile}`,
         `  log file: ${runtime.logFile}`,
@@ -2957,8 +3033,26 @@ async function cmdFactoryd(opts) {
         console.log(line);
     for (const line of banner)
         logSink(line);
+    let shuttingDown = false;
+    void runAutoUpdateLoop(config, {
+        ...createAutoUpdateDeps({
+            registryFile,
+            stateFile: updateFile,
+            cliEntrypoint: fileURLToPath(new URL('../cli.js', import.meta.url)),
+            check: () => checkForUpdate(config.autoUpdate.mode === 'prerelease' ? 'prerelease' : 'stable'),
+            runRuntime,
+            log,
+            exit: async (code) => {
+                await daemon.stop().catch(() => { });
+                await releaseRuntimeFiles(runtime);
+                process.exit(code);
+            },
+        }),
+        stopped: () => shuttingDown,
+    });
     await new Promise((resolveShutdown) => {
         const shutdown = () => {
+            shuttingDown = true;
             void daemon
                 .stop()
                 .catch(() => { })
@@ -3083,6 +3177,20 @@ async function cmdRun(opts = {}) {
                 pids.push(runLane(planned.lane, planned.issues, repoRoot, ghRepo, paths, {
                     ...planned.deps,
                     laneBreakerThreshold,
+                    baseHoldGate: opts.localQueue === true
+                        ? undefined
+                        : createBaseHoldGate({
+                            file: paths.baseHold,
+                            repo: ghRepo,
+                            onCleared: (c) => logEvent(paths.events, 'base-hold-cleared', planned.lane, formatBaseHoldCleared(c), {
+                                lane: planned.lane,
+                            }),
+                            git: (cmd) => shellOps.exec(cmd, { cwd: repoRoot }).then((r) => r.stdout),
+                            listCheckRuns: (ref) => {
+                                const [owner, repoName] = ghRepo.split('/');
+                                return createOctokitGreenPrClient(getOctokit()).listCheckRuns({ owner, repo: repoName, ref });
+                            },
+                        }),
                     commentIssue: async (issue, body) => {
                         const [owner, repoName] = ghRepo.split('/');
                         await getOctokit().rest.issues.createComment({ owner, repo: repoName, issue_number: issue, body });
@@ -3108,8 +3216,12 @@ async function cmdRun(opts = {}) {
             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);
+                const recon = await reconstructHumanEventsForKpis(events, branchPrefix);
+                const kpis = computeHealthKpis(recon.events, costs);
+                await appendKpiSnapshot(paths, repoRoot, kpis, { partial: recon.partial });
+                if (recon.partial) {
+                    logEvent(paths.events, 'warn', 'all', `kpi snapshot partial: GitHub human-event reconstruction failed: ${recon.error}`);
+                }
                 logEvent(paths.events, 'kpi-snapshot', 'all', `KPI snapshot appended to ${paths.kpiHistory}`);
             }
             catch (err) {
@@ -3388,7 +3500,7 @@ export function renderLanePausedComment(payload) {
     ].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;
+    const { ship = shipIssue, waitMerge = waitForMerge, pathExists = existsSync, emitEvent = logEvent, claimNext = async () => null, releaseIssue = async () => { }, heartbeat, reapWorktree = async () => { }, sweepFinished = async () => { }, countRemaining, baseHoldGate, laneBreakerThreshold = 0, commentIssue = async () => { }, } = deps;
     let streak = null;
     let merged = 0;
     let awaitingReview = 0;
@@ -3420,6 +3532,13 @@ export async function runLane(lane, issues, repoRoot, ghRepo, paths, deps = {})
     };
     for (let i = 0;; i++) {
         if (i >= pending.length) {
+            // A persisted base hold on the unchanged origin/main SHA means the base is still broken
+            // (#2349): claiming would just cycle an issue again, so stop this lane without claiming.
+            const gate = baseHoldGate ? await baseHoldGate().catch(() => ({ kind: 'claim' })) : null;
+            if (gate?.kind === 'hold') {
+                emitEvent(paths.events, 'warn', lane, `lane '${lane}' not claiming: base hold on ${gate.hold.baseSha.slice(0, 8)} (${gate.hold.failingChecks.join(', ')}) — origin/main unchanged and its CI is not green`, { lane });
+                return;
+            }
             const claimed = await claimNext();
             if (claimed === null)
                 break;
@@ -3503,6 +3622,17 @@ export async function runLane(lane, issues, repoRoot, ghRepo, paths, deps = {})
                 streak = null;
                 await reapWorktree(issue).catch(() => { });
                 await settle(issue, 'queued');
+                // Persist the hold so a restarted supervisor remembers the broken base (#2348);
+                // best-effort, never allowed to change lane flow.
+                try {
+                    writeBaseHold(paths.baseHold, {
+                        repo: ghRepo,
+                        baseSha: err.baseSha,
+                        failingChecks: err.failingChecks,
+                        since: new Date().toISOString(),
+                    });
+                }
+                catch { }
                 const payload = {
                     lane,
                     signature: err.failureSignature ?? '',
@@ -3697,6 +3827,12 @@ export class CiFailedError extends Error {
  *  exactly like "we know it's red": never merge. */
 export class CiUnverifiedError extends CiFailedError {
 }
+/** Thrown when the one infra rerun (#2365) also failed for infrastructure reasons on the same head SHA (#2366).
+ *  A CiFailedError subclass so every guard still leaves the PR open and unmerged, but it parks as
+ *  'ci-infra', which the ADR-0155 steward skips. */
+export class CiInfraError extends CiFailedError {
+    parkReason = 'ci-infra';
+}
 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
@@ -3753,7 +3889,7 @@ export async function rebaseDirtyPullRequest(opts) {
     }
 }
 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;
+    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, rerun, 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 () => {
@@ -3762,7 +3898,16 @@ export async function landOpenPullRequest(opts) {
         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 });
+            outcome = await watchChecksWithInfraRerun({
+                octokit,
+                owner,
+                repo: repoName,
+                ref: headSha,
+                watch,
+                rerun,
+                onRescued: ({ runIds }) => log('ci-rescued', `CI rescued for PR #${prNumber} on ${branch}: reran infra-failed run(s) ${runIds.join(', ')} once and the re-watch is green`),
+                onRescueFailed: ({ runIds, outcome: failedOutcome }) => log('ci-rescue-failed', `CI rescue failed for PR #${prNumber} on ${branch}: reran infra-failed run(s) ${runIds.join(', ')} once and the re-watch ended ${failedOutcome}`),
+            });
         }
         catch (err) {
             const msg = `CI watch for ${branch} failed: ${errorDetail(err)} — refusing to merge without a green verdict`;
@@ -3771,6 +3916,11 @@ export async function landOpenPullRequest(opts) {
         }
         if (outcome === 'success')
             return headSha;
+        if (outcome === 'infra-failure') {
+            const msg = `CI failed again for infrastructure reasons for PR #${prNumber} on ${branch} after one rerun — parked as ci-infra, not merged`;
+            log('ci-infra', msg);
+            throw new CiInfraError(msg, prNumber);
+        }
         if (outcome === 'failure') {
             const msg = `CI failed for PR #${prNumber} on ${branch} — refusing to merge with a failing check`;
             log('ci-failed', msg);
@@ -4184,14 +4334,17 @@ async function cmdDoctor(opts = {}) {
     }
     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),
-            });
+    const runtimeAvailable = hasSandboxRuntime(process.platform, (cmd) => isCommandAvailableViaShell(shellOps, cmd));
+    const skip = sandboxAuthSkipDetail({ runtimeAvailable, hostOk: host === 'ok', inRepo: repoRoot !== null });
+    if (skip !== null) {
+        sandboxDetail = skip;
+    }
+    else if (repoRoot !== null) {
+        const policy = resolveSandboxPolicy(configLoaders.loadFactoryConfigForRepo(getFactoryPaths(repoRoot).config).sandbox, {
+            worktree: repoRoot,
+            repoRoot,
+            isAvailable: (cmd) => isCommandAvailableViaShell(shellOps, cmd),
+        });
         if (!policy) {
             sandboxDetail = 'skipped — sandbox disabled by config or FACTORY_SANDBOX';
         }
@@ -4374,7 +4527,19 @@ export async function main(argv = process.argv, deps = {}) {
         .description('Multi-agent software factory with boss-worker-checker orchestration')
         .version(getCliVersion())
         .addHelpText('before', PREREQUISITES_TEXT)
-        .addHelpText('after', HELP_FOOTER_TEXT);
+        .addHelpText('after', HELP_FOOTER_TEXT)
+        .option('--state-root <path>', 'Keep factory state and config outside the checkout: an absolute path, ~/..., or "auto" (~/.factory/<owner>/<name>); env FACTORY_STATE_ROOT');
+    program.hook('preAction', async () => {
+        const flag = program.opts().stateRoot;
+        if (flag === undefined && !process.env.FACTORY_STATE_ROOT?.trim())
+            return;
+        try {
+            applyStateRootOption(flag, await getRepoRoot());
+        }
+        catch (e) {
+            throw new CliExitError(`factory: ${e.message}`, 2);
+        }
+    });
     program
         .command('init')
         .description('Set up .factory/ in this repo (config, constitution, queue file, .gitignore) and check model reachability')
@@ -4419,7 +4584,7 @@ export async function main(argv = process.argv, deps = {}) {
         .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')
+        .option('--json', 'Print one JSON object (schemaVersion 1): repo, product, stop, breaker, active claims, update; --kpis is ignored')
         .action((opts) => cmdStatus(opts));
     program
         .command('runs')
@@ -4485,6 +4650,8 @@ export async function main(argv = process.argv, deps = {}) {
         .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('--repo <owner/name>', 'Repo to file the issue in (default: filing.repo, then the origin remote)')
+        .option('--include-local-paths', 'Include this host name and local design/log paths in the issue')
         .option('--branch-prefix <prefix>', BRANCH_PREFIX_MATCH_OPTION_DESCRIPTION)
         .action(cmdFeedback);
     const filingCmd = program.command('filing').description('Inspect upstream factory reports (nothing is sent)');
@@ -4696,7 +4863,8 @@ export async function main(argv = process.argv, deps = {}) {
         .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)')
+        .option('--update-mode <mode>', 'Self-update channel: manual, stable (npm latest) or prerelease (npm next) (default: stable on npm installs, manual otherwise)')
+        .option('--auto-update', 'Deprecated: same as --update-mode stable')
         .action((opts) => cmdFactoryd(opts));
     const daemonCtl = (fn) => fn().catch((err) => {
         if (err instanceof DaemonCtlError)
@@ -4722,6 +4890,17 @@ export async function main(argv = process.argv, deps = {}) {
         .option('-f, --follow', 'Keep tailing')
         .option('-n, --lines <n>', 'Lines to print first (default 100)')
         .action((opts) => daemonCtl(() => cmdDaemonLogs(opts, deps.daemon)));
+    program
+        .command('self-update')
+        .description('Check npm for a newer factory release (read-only; nothing is installed)')
+        .option('--check', 'Compare the running version with the npm dist-tag (required)')
+        .option('--json', 'Print one JSON object instead of text')
+        .option('--update-mode <mode>', 'Channel to check: stable (npm latest, default) or prerelease (npm next)')
+        .action(async (opts) => {
+        if (opts.check !== true)
+            throw new CliExitError('factory self-update: only --check is supported', 2);
+        process.exitCode = await daemonCtl(() => cmdSelfUpdateCheck(opts, deps.selfUpdate));
+    });
     const worktreeCmd = program.command('worktree').description('Clean up stale factory worktrees (gc)');
     worktreeCmd
         .command('gc')