@on-par/factory-cli 0.9.11-next.5 → 0.9.11-next.50

package/dist/cli/index.js

@@ -6,18 +6,21 @@ import { createRequire } from 'node:module';
 import { arch, hostname as osHostname, release, platform, userInfo } from 'node:os';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { promisify, styleText } from 'node:util';
+import { 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 { 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 { 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';
@@ -338,7 +341,7 @@ setShipRuntime(() => ({
     IssueSkippedError,
     IssueDecomposedError,
 }));
-export { shipIssue };
+export { LaneEnvironmentPauseError, shipIssue };
 export function hasGitHubToken(env = process.env, tryToken) {
     if (env.GITHUB_TOKEN || env.GH_TOKEN)
         return true;
@@ -874,7 +877,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', '❌');
@@ -887,6 +890,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);
@@ -910,7 +914,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('  ---');
@@ -923,7 +927,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++;
@@ -933,13 +944,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('  ---');
@@ -955,6 +969,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);
     }
@@ -1063,6 +1078,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 }, {
@@ -1314,6 +1330,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,
@@ -1366,24 +1383,6 @@ export class LaneParkError extends Error {
         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;
-    /** BUILD output was kept for `factory resume --from check` (#2564); runLane must not reap it. */
-    buildPreserved;
-    constructor(message, failure) {
-        super(message);
-        if (failure.buildPreserved !== undefined)
-            this.buildPreserved = failure.buildPreserved;
-        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
@@ -2012,6 +2011,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: '-' }));
@@ -2432,8 +2432,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;
@@ -2559,167 +2558,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) {
@@ -2848,7 +2692,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';
@@ -2896,7 +2740,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)
@@ -2975,7 +2827,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) {