@on-par/factory-cli 0.9.11-next.9 → 0.9.12-next.1

package/dist/cli/index.js

@@ -10,15 +10,19 @@ import { LaneEnvironmentPauseError } from './lane-environment-pause-error.js';
 import { INVALID_BRANCH_PREFIX_MESSAGE, resolveBranchPrefixOption } from './branch-prefix.js';
 import { sweepLaneClaims, warnQueueDiagnostics } from './queue-startup.js';
 import { proposeTriageQueue } from './triage-open-prs.js';
+import { makeQueuePreflightOps, preflightQueuedIssue } from './queue-preflight.js';
 import { acquirePortLease, aggregateCosts, appendKpiHistoryLine, applyRepoConfig, buildPhase, checkPhase, clearProxyState, computeHealthKpis, ConstitutionLoader, createDefaultWorkSourceRegistry, createLogger, createLaneProxy, defaultFindPortListeners, describeEffectiveConfig, detectPostMergeDefects, diagnoseModels, probeDeclaredHarnesses, estimateTrailingSpend, fetchDefectSources, fetchSubscriptionUsage, formatUsageReport, getConstitutionsDir, getFactoryPaths, GITHUB_ISSUE_SOURCE, hasUnresolvedPark, InvalidArtifactsDirError, InvalidWorkRequestInputError, InvalidWorkspaceError, isCommandAvailable, isProxyRunning, kpiBranchPrefixes, kpisToHistoryRecord, laneBaseUrl, laneEnv, laneHostLabel, loadFactoryConfigForRepo, loadModelsConfig, loadRepoConfig, loadRoutesConfig, LOCAL_BRIEF_SOURCE, joinClassifierOutcomes, mergeClassifierOutcomes, parseClassifierOutcomes, summarizeClassifierOutcomes, formatClassifierReport, mergedPrRefs, ModelRegistry, ModelRouter, parkReasonFor, parseKpiHistory, parseQueue, planPhase, readEvents, readPortLeases, readQueue, readUsage, reapOrphanProcesses, reconstructKpiEvents, recordLeasePgid, releasePortLease, renderKpiReport, renderKpiTrend, resolveDefectWindowDays, parseSizeGateMode, parseMaxSlices, SIZE_GATE_MODES, resolveEffectiveModelPins, resolveEnvironmentProxy, resolveArtifactsDir, resolveLocalOnlyPolicy, resolveMergePolicy, resolveSkipCI, resolveTimeouts, resolveUsageCap, resolveWatchdogPolicy, runAutoIngest, shipPhase, formatCostTotal, validateQueue, watchUsage, writeLocalRunReport, writeProxyState, } from '@on-par/factory-core';
-import { acquirePidFile, createCheckResumeStore, findSlicePlanComment, upsertSlicePlanComment, withSliceState, DEFAULT_GARDEN_MAX_CLUSTERS, DEFAULT_GARDEN_SINCE, capGardenClusters, clusterGarden, dedupGardenClusters, filterGardenOnlyNew, filterGardenWindow, markGardenTrackingUnknown, parseGardenDuration, readHarvestEvents, renderGardenJson, renderGardenReport, laneWorktreePath, migrateRepoConfigToYaml, REPO_CONFIG_YAML_HEADER, claudeConfigDirOverride, claudeKeychainService, cleanupWorktree, createDaemonLogSink, factoryBranchIssue, factoryBranchPrefixes, createFactorydServer, createRunRuntime, createShipExecutor, createGithubQueue, createLocalSmallDryRun, createOctokitFilingClient, createOctokitGreenPrClient, createOctokitQueueClient, daemonRuntimePaths, defaultRegistryPath, ensureDir, fetchHumanEventSourcesCached, FACTORY_RUNTIME_CONFIG_KEYS, findUnmergedGreenPrs, formatGcReport, gitFetch, listMicroVms, listOrphanContainers, logCost, logEvent, planQueueMigration, pollBlockedParks, readCosts, readGithubQueueSnapshot, reapCleanShipWorktree, reapLaneWorktree, reapOrphanContainers, reapOrphanMicroVm, releaseRuntimeFiles, releaseStaleClaims, resolveBranchPrefix, resolveEffectiveConfig, resolveExperimental, resolveLocalOnly, resolvePrClassifierPolicy, resolveReviewFloorRules, RunLockHeldError, runOvernightQueue, parseRemoteSlug, setupWorktree, shellEscape, listBuiltInCheckers, sweepWorktrees, watchChecks, withFileLock, withGitLock, withRunLock, writePortFile, buildTriagePrompt, parseTriageCandidates, recordLocalAuthFailure, laneSlug, } from '@on-par/factory-core/internal';
+import { acquirePidFile, createCheckResumeStore, DEFAULT_GARDEN_MAX_CLUSTERS, DEFAULT_GARDEN_SINCE, capGardenClusters, clusterGarden, dedupGardenClusters, filterGardenOnlyNew, filterGardenWindow, markGardenTrackingUnknown, parseGardenDuration, readHarvestEvents, renderGardenJson, renderGardenReport, laneWorktreePath, migrateRepoConfigToYaml, REPO_CONFIG_YAML_HEADER, claudeConfigDirOverride, claudeKeychainService, cleanupWorktree, createDaemonLogSink, factoryBranchIssue, factoryBranchPrefixes, createFactorydServer, createRunRuntime, createShipExecutor, createGithubQueue, createLocalSmallDryRun, createOctokitFilingClient, createOctokitGreenPrClient, createOctokitQueueClient, daemonRuntimePaths, defaultRegistryPath, ensureDir, fetchHumanEventSourcesCached, FACTORY_RUNTIME_CONFIG_KEYS, findUnmergedGreenPrs, formatGcReport, gitFetch, listMicroVms, listOrphanContainers, logCost, logEvent, planQueueMigration, pollBlockedParks, readCosts, readGithubQueueSnapshot, reapCleanShipWorktree, reapLaneWorktree, reapOrphanContainers, reapOrphanMicroVm, releaseRuntimeFiles, releaseStaleClaims, resolveBranchPrefix, resolveEffectiveConfig, resolveExperimental, resolveLocalOnly, resolvePrClassifierPolicy, resolveReviewFloorRules, RunLockHeldError, runOvernightQueue, parseRemoteSlug, setupWorktree, shellEscape, listBuiltInCheckers, sweepWorktrees, watchChecks, withFileLock, withGitLock, withRunLock, writePortFile, buildTriagePrompt, parseTriageCandidates, recordLocalAuthFailure, laneSlug, formatStopMarker, readStopMarker, } from '@on-par/factory-core/internal';
+import { formatSteerabilityReport } from '@on-par/factory-core/internal';
 import { runTui } from '@on-par/factory-tui';
+import { clearSelfUpdateStop } from './self-update-stop.js';
 import { admissionStateReaderFor, runQueueReconcile } from './admission.js';
 import { cmdClassifierBacktest, ClassifierBacktestInputError, } from './classifier-backtest.js';
+import { buildSteerabilityReport } from './steerability-report.js';
 import { runHarnessCheckCommand } from './harness-check.js';
-import { findOpenPRForIssue, landIssue } from './land.js';
+import { landIssue } from './land.js';
 import { STOP_SET_MESSAGE } from './stop-sentinel.js';
-import { AwaitingReviewError, CiFailedError, CiUnverifiedError, getPullRequestLandState, LandConflictError, LandFailureError, MergeGatedError, } from './land-pr.js';
+import { AwaitingReviewError, CiFailedError, CiUnverifiedError, LandConflictError, LandFailureError, MergeGatedError, } from './land-pr.js';
 import { setLandRuntime } from './land-runtime.js';
 import { cmdRun } from './run.js';
 import { shipIssue } from './ship.js';
@@ -31,6 +35,7 @@ import { buildCostJson } from './cost-json.js';
 import { buildQueueAddJson } from './queue-add-json.js';
 import { renderQueueAddLines, renderUnparkLines } from './queue-output.js';
 import { buildQueueListJson } from './queue-list.js';
+import { cmdSteer } from './steer.js';
 import { appendUnparkEvent, runUnpark, UnparkError } from './unpark.js';
 import { buildRunsJson, parseRunsLimit } from './runs.js';
 import { buildRunDiffstatJson, NoRunError, parseDiffstatIssue } from './runs-diffstat.js';
@@ -46,6 +51,7 @@ import { cmdHostedSmoke } from './hosted.js';
 import { cmdHostedQueue } from './hosted-queue.js';
 import { cmdHostedRunner } from './hosted-runner.js';
 import { resolveFactoryCheckoutCommit, runFilingPreview } from './filing.js';
+import { cmdRisk } from './risk.js';
 import { buildFeedbackDeps, resolveFeedbackRepo, runFeedback } from './feedback.js';
 import { ensureFactoryExcluded, writeSampleQueue } from './init-files.js';
 import { cmdLogs } from './logs.js';
@@ -875,7 +881,7 @@ async function cmdModels(opts = {}) {
     const byModel = new Map(diagnoses.map((d) => [d.model, d]));
     for (const m of registry.list()) {
         const tiers = registry.getTiers(m).join('/');
-        const est = registry.estimateCost(m, 1_000_000, 1_000_000);
+        const est = registry.estimateCost(m, { inputTokens: 1_000_000, outputTokens: 1_000_000 }).cost;
         const cost = est === null ? 'unpriced' : `$${est.toFixed(2)}/M`;
         const d = byModel.get(m);
         const avail = d ? modelStatusIcon(d) : styleText('red', '❌');
@@ -888,6 +894,7 @@ async function cmdModels(opts = {}) {
         console.log(`  ${tier}: ${models.join(' ')}`);
     }
 }
+const CACHED_RATE_MARKER = ' (cached at full input rate)';
 async function cmdCost(opts = {}) {
     const repoRoot = await getRepoRoot();
     const paths = getFactoryPaths(repoRoot);
@@ -911,7 +918,7 @@ async function cmdCost(opts = {}) {
         }
         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}]` : ''}`);
+            console.log(`  ${c.task} ${c.model} ${c.cost === null || c.cost === undefined ? 'unknown' : `$${c.cost.toFixed(4)}`}${c.failoverReason ? ` [failover: ${c.failoverReason}]` : ''}${c.cachedRateMissing === true ? CACHED_RATE_MARKER : ''}`);
         }
         const t = aggregateCosts(filtered).total;
         console.log('  ---');
@@ -924,7 +931,14 @@ async function cmdCost(opts = {}) {
     }
     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 };
+        const e = byModel.get(c.model) ?? {
+            tasks: 0,
+            priced: 0,
+            pricedCount: 0,
+            unpriced: 0,
+            failovers: 0,
+            cachedRateMissing: 0,
+        };
         e.tasks++;
         if (c.unpriced === true || c.cost === null || c.cost === undefined)
             e.unpriced++;
@@ -934,13 +948,16 @@ async function cmdCost(opts = {}) {
         }
         if (c.failoverReason)
             e.failovers++;
+        if (c.cachedRateMissing === true)
+            e.cachedRateMissing++;
         byModel.set(c.model, e);
     }
     console.log(styleText('bold', '== Cost Summary =='));
-    for (const [model, { tasks, priced, pricedCount, unpriced, failovers }] of byModel) {
+    for (const [model, { tasks, priced, pricedCount, unpriced, failovers, cachedRateMissing }] 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 cachedSuffix = cachedRateMissing > 0 ? CACHED_RATE_MARKER : '';
+        console.log(`  ${model}: ${tasks} tasks, ${modelCost}${failoverSuffix}${cachedSuffix}`);
     }
     const grand = aggregateCosts(costs).total;
     console.log('  ---');
@@ -956,6 +973,7 @@ async function cmdCheck(issueRaw, opts) {
         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);
+        router.setCodexFullAccessTasks?.(configLoaders.loadFactoryConfigForRepo(getFactoryPaths(repoRoot).config).sandbox.codexFullAccessTasks);
         router.setLocalAuthSink?.(recordLocalAuthFailure);
         runModel = createDeepModelRunner(router, repoRoot);
     }
@@ -1045,16 +1063,35 @@ function persistClassifierOutcomes(paths, events, sources, opts) {
     ensureDir(paths.state);
     writeFileSync(paths.classifierOutcomes, updated);
 }
+/** `factory risk <pr>` (#3385): the handler lives in ./risk.ts; this binds its runtime. */
+function runRisk(pr, opts = {}) {
+    return cmdRisk(pr, opts, { getRepoRoot, getGitHubRepo, getOctokit, CliExitError, log: console.log });
+}
 async function cmdClassifierReport(opts = {}) {
     const repoRoot = await getRepoRoot();
     const paths = getFactoryPaths(repoRoot);
     const report = summarizeClassifierOutcomes(parseClassifierOutcomes(readTextFileOrEmpty(paths.classifierOutcomes)));
+    const steerability = await buildSteerabilityReport(paths);
     if (opts.json) {
-        console.log(JSON.stringify(report));
+        console.log(JSON.stringify({ ...report, steerability }));
         return;
     }
     for (const line of formatClassifierReport(report))
         console.log(line);
+    console.log('');
+    for (const line of formatSteerabilityReport(steerability))
+        console.log(line);
+}
+async function cmdReport(opts = {}) {
+    if (!opts.steerability)
+        throw new CliExitError('factory: report requires --steerability', 2);
+    const report = await buildSteerabilityReport(getFactoryPaths(await getRepoRoot()));
+    if (opts.json) {
+        console.log(JSON.stringify(report));
+        return;
+    }
+    for (const line of formatSteerabilityReport(report))
+        console.log(line);
 }
 async function cmdClassifierBacktestEntry(opts) {
     const branchPrefix = branchPrefixOrExit(opts.branchPrefix);
@@ -1064,6 +1101,7 @@ async function cmdClassifierBacktestEntry(opts) {
     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);
+    router.setCodexFullAccessTasks?.(configLoaders.loadFactoryConfigForRepo(paths.config).sandbox.codexFullAccessTasks);
     router.setLocalAuthSink?.(recordLocalAuthFailure);
     try {
         await cmdClassifierBacktest({ ...opts, branchPrefix }, {
@@ -1315,6 +1353,7 @@ async function cmdTui(opts = {}, runTuiImpl = runTui) {
     const routesConfig = configLoaders.loadRoutesConfig();
     const effective = resolveEffectiveConfig(repoConfig);
     const router = new coreOps.ModelRouter(modelsConfig, routesConfig, false, undefined, effective.allowExperimental, effective.localOnly);
+    router.setCodexFullAccessTasks?.(configLoaders.loadFactoryConfigForRepo(paths.config).sandbox.codexFullAccessTasks);
     router.setLocalAuthSink?.(recordLocalAuthFailure);
     const effectiveConfigLines = describeEffectiveConfig({
         router,
@@ -1537,7 +1576,11 @@ async function cmdShip(issueNum, opts) {
         catch (err) {
             if (err instanceof IssueSkippedError)
                 return;
-            if (ghRepo && !(err instanceof InvalidWorkRequestInputError) && !(err instanceof LaneEnvironmentPauseError)) {
+            // A --no-pr run keeps its worktree either way: inspecting it is the point.
+            if (ghRepo &&
+                opts.pr !== false &&
+                !(err instanceof InvalidWorkRequestInputError) &&
+                !(err instanceof LaneEnvironmentPauseError)) {
                 await reapPrlessShipWorktree(issueNum, repoRoot, ghRepo, paths, branchPrefix);
             }
             // #2492: a pull request number is a usage error, not a failed ship.
@@ -1560,6 +1603,9 @@ async function cmdRunIssue(issueNum, opts) {
     const branchPrefix = branchPrefixOrExit(opts.branchPrefix);
     const sizeGate = sizeGateOrExit(rawSizeGate);
     const maxSlices = maxSlicesOrExit(rawMaxSlices);
+    if (opts.pr === false && ((sizeGate !== undefined && sizeGate !== 'off') || runChildren)) {
+        throw new CliExitError('factory: --no-pr runs with the size gate off — drop --size-gate/--run-children or drop --no-pr', 2);
+    }
     await withRepoRunLock(paths, 'factory run-issue', async () => {
         const ghRepo = await getGitHubRepo();
         // Pre-flight: resolve the issue through the canonical work-request seam
@@ -1995,6 +2041,7 @@ 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);
+    router.setCodexFullAccessTasks?.(configLoaders.loadFactoryConfigForRepo(paths.config).sandbox.codexFullAccessTasks);
     router.setLocalAuthSink?.(recordLocalAuthFailure);
     router.skipMissingHarnessClis(coreOps.isCommandAvailable);
     router.setCostSink((entry) => logCost(paths.costs, { ...entry, issue: '-' }));
@@ -2415,8 +2462,7 @@ async function cmdFactoryd(opts) {
     const previousUpdate = readUpdateState(updateFile);
     for (const stop of recoverStaleDrain(previousUpdate, (file) => {
         try {
-            unlinkSync(file);
-            return true;
+            return clearSelfUpdateStop(file);
         }
         catch {
             return false;
@@ -2542,167 +2588,12 @@ export function laneQueueDeps(queue, lane) {
         countRemaining: async () => (await queue.list(lane)).length,
     };
 }
+export { preflightQueuedIssue };
 export function createQueuePreflightOps(octokit, owner, repo, opts = {}) {
-    return {
-        autoMergeStack: opts.autoMergeStack ?? false,
-        getPullRefs: async (prNumber) => {
-            const { data } = await octokit.rest.pulls.get({ owner, repo, pull_number: prNumber });
-            return { headRef: data.head.ref, baseRef: data.base.ref, headSha: data.head.sha };
-        },
-        expectedHeadRepoFullName: `${owner}/${repo}`,
-        findOpenPR: (issue) => findOpenPRForIssue(octokit, owner, repo, issue),
-        getLandState: (prNumber) => getPullRequestLandState(octokit, owner, repo, prNumber),
+    return makeQueuePreflightOps(octokit, owner, repo, {
         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/ADR-0161: walk every pr-open slice PR bottom-up. Merged layers are recorded, a closed layer parks
- *  (naming the layers above it), and the lowest open layer defers, or is adopted when stack auto-merge is on and
- *  its base is main with green CI on the rebased head. Returns undefined to fall through to the Closes-PR
- *  preflight only when no slice PR is still open. */
-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 n = plan.slices.length;
-    const open = plan.slices.filter((s) => s.state === 'pr-open');
-    if (open.length === 0)
-        return undefined;
-    let next = plan;
-    let lastMerged;
-    const save = async () => {
-        if (lastMerged === undefined)
-            return undefined;
-        try {
-            await deps.saveSlicePlan(issue, next);
-        }
-        catch (err) {
-            return {
-                kind: 'park',
-                reason: `${lastMerged.label} PR #${lastMerged.pr} merged but updating the slice plan failed: ${errorDetail(err)}`,
-            };
-        }
-        return undefined;
-    };
-    for (const [at, slice] of open.entries()) {
-        const label = `slice ${slice.index}/${n}`;
-        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 === 'merged') {
-            next = withSliceState(next, slice.index, 'merged', pr);
-            lastMerged = { label, pr };
-            continue;
-        }
-        if (state === 'closed') {
-            const above = open.slice(at + 1);
-            const suffix = above.length > 0
-                ? `; layers above it: ${above.map((a) => `slice ${a.index}/${n} (#${a.prNumber})`).join(', ')}`
-                : '';
-            return { kind: 'park', reason: `${label} PR #${pr} was closed without merging${suffix}` };
-        }
-        const saved = await save();
-        if (saved)
-            return saved;
-        if (!deps.autoMergeStack)
-            return { kind: 'defer' };
-        let refs;
-        try {
-            refs = await deps.getPullRefs(pr);
-        }
-        catch (err) {
-            return { kind: 'park', reason: `${label} PR #${pr} ref lookup failed: ${errorDetail(err)}` };
-        }
-        // GitHub has not retargeted the layer to main yet: the lower layer is still unmerged.
-        if (refs.baseRef !== 'main')
-            return { kind: 'defer' };
-        let outcome;
-        try {
-            outcome = await deps.watch(refs.headSha);
-        }
-        catch (err) {
-            return { kind: 'park', reason: `CI watch for ${label} PR #${pr} failed: ${errorDetail(err)}` };
-        }
-        if (outcome === 'failure')
-            return { kind: 'park', reason: `CI for ${label} PR #${pr} ended failure` };
-        if (outcome !== 'success')
-            return { kind: 'defer' };
-        return { kind: 'adopt', branch: refs.headRef, stackLayer: { index: slice.index, count: n, prNumber: pr } };
-    }
-    return (await save()) ?? 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 };
+        ...opts,
+    });
 }
 export async function planRunLanes(input) {
     if (input.localQueue) {
@@ -2831,7 +2722,7 @@ export async function cmdResumeApproved(opts = {}) {
 }
 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', repoConfigLabel, 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;
+    const { cap, resumeAt, pollMs, watch = true, watchSource = 'default', repoConfigLabel, resumeAtSource = 'default', pollSource = 'default', estimator = false, stopFile, eventsFile, now, runQueue, readUsageFn = () => readUsage({ cap, estimator }), pathExists = existsSync, clearStop = (path) => rmSync(path, { force: true }), readStopMarker: readMarker = readStopMarker, 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';
@@ -2879,7 +2770,15 @@ export async function superviseLoop(deps) {
             }
         }
         emitEvent(eventsFile, 'resumed', 'usage', `supervise cycle ${cycle}: trailing usage (${source}) at ${Math.round(pct * 100)}% of cap — starting run`);
-        clearStop(stopFile);
+        const marker = readMarker(stopFile);
+        if (marker?.source === 'usage-watchdog') {
+            clearStop(stopFile);
+        }
+        else if (marker) {
+            writeLine(`[factory] supervise: STOP set by ${marker.source}${marker.at ? ` at ${marker.at}` : ''}; waiting for factory resume`);
+            while (pathExists(stopFile))
+                await sleep(pollMs);
+        }
         if (ingest) {
             const appended = await ingest();
             if (appended > 0)
@@ -2958,7 +2857,7 @@ function logEventQuietly(eventsFile, 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' });
+        writeFileSync(stopFile, formatStopMarker('manual'), { flag: 'wx' });
         return true;
     }
     catch (err) {
@@ -2993,6 +2892,18 @@ export async function cmdStop(opts = {}) {
     }
     console.log(STOP_SET_MESSAGE);
 }
+/** `factory steer <ref>` (#3401): the handler lives in ./steer.ts; this binds its runtime. */
+function runSteerCommand(ref, opts = {}) {
+    return cmdSteer(ref, opts, {
+        getRepoRoot,
+        gitUserName: async () => (await shellOps.exec('git config user.name')).stdout,
+        env: process.env,
+        now: () => new Date().toISOString(),
+        CliExitError,
+        errorDetail,
+        log: console.log,
+    });
+}
 export async function cmdResume(issue, opts = {}) {
     if (issue === undefined && opts.from !== undefined) {
         throw new CliExitError('factory: resume --from needs an issue number: factory resume <issue> --from check', 2);
@@ -3158,6 +3069,8 @@ export const PROGRAM_HANDLERS = {
     cmdRuns,
     cmdKpis,
     cmdClassifierReport,
+    cmdReport,
+    cmdRisk: runRisk,
     cmdClassifierBacktestEntry,
     cmdGarden,
     cmdTui,
@@ -3196,6 +3109,7 @@ export const PROGRAM_HANDLERS = {
     cmdSupervise: runSupervise,
     cmdStop,
     cmdResume,
+    cmdSteer: runSteerCommand,
     parseIssueArg,
     getRepoRoot,
     getCliVersion,