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

package/dist/cli/index.d.ts

@@ -0,0 +1,656 @@
+import { type StdioOptions } from 'node:child_process';
+import type { Octokit } from '@octokit/rest';
+import type { Environment, EnvironmentProxySettings, EventKind, FactoryConfig, IngestSettings, LaneProxy, LocalOnlyPolicy, MergePolicyOverrides, ModelDiagnosis, LanePausedPayload, ParkReason, QueueDiagnostic, RepoFactoryConfig, RunOutcome, RunPorts, SandboxRuntime, UsageReading, WatchdogPolicyOverrides, WatchdogPolicySource, WorkRequest, WorkRequestSourceKind } from '@on-par/factory-core';
+import { ConstitutionLoader, createLaneProxy, defaultFindPortListeners, diagnoseModels, estimateTrailingSpend, fetchSubscriptionUsage, formatUsageReport, getConstitutionsDir, getFactoryPaths, isCommandAvailable, isProxyRunning, loadFactoryConfigForRepo, loadModelsConfig, loadRepoConfig, loadRoutesConfig, ModelRegistry, ModelRouter, reapOrphanProcesses, type SizeGateMode, resolveEffectiveModelPins, resolveSkipCI, resolveTimeouts, runAutoIngest, watchUsage, writeLocalRunReport } from '@on-par/factory-core';
+import type { CiOutcome, GithubQueue, QueueClaim, QueueIssue, QueuePreflightDecision, QueueReleaseOutcome, SlicePlan, SlicePlanCommentLookup, WatchChecksOptions } from '@on-par/factory-core/internal';
+import { migrateRepoConfigToYaml, cleanupWorktree, createLocalSmallDryRun, findUnmergedGreenPrs, formatGcReport, gitFetch, listMicroVms, listOrphanContainers, logEvent, readCosts, reapOrphanContainers, reapOrphanMicroVm, releaseStaleClaims, setupWorktree, sweepWorktrees, watchChecks, withRunLock } from '@on-par/factory-core/internal';
+import { type QueueReader, runTui } from '@on-par/factory-tui';
+import { type DaemonCtlDeps } from './daemon.js';
+import { type FeedbackDeps } from './feedback.js';
+type ConfigLoaderKey = 'loadModelsConfig' | 'loadRoutesConfig' | 'loadFactoryConfigForRepo' | 'loadRepoConfig' | 'resolveTimeouts' | 'resolveSkipCI' | 'getConstitutionsDir' | 'resolveEffectiveModelPins';
+type GitOpKey = 'setupWorktree' | 'cleanupWorktree' | 'gitFetch';
+type InternalOpKey = 'watchChecks' | 'createLocalSmallDryRun' | 'readCosts' | 'sweepWorktrees' | 'releaseStaleClaims' | 'findUnmergedGreenPrs' | 'listOrphanContainers' | 'reapOrphanContainers' | 'listMicroVms' | 'reapOrphanMicroVm' | 'formatGcReport';
+export type ShellExec = (command: string, options?: {
+    cwd?: string;
+    timeout?: number;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export type ShellExecSync = (command: string, options?: {
+    timeout?: number;
+    stdio?: StdioOptions;
+}) => string;
+type ShellOpKey = 'exec' | 'execSync';
+type CoreOpKey = 'ModelRouter' | 'ConstitutionLoader' | 'ModelRegistry' | 'isCommandAvailable' | 'defaultFindPortListeners' | 'reapOrphanProcesses' | 'estimateTrailingSpend' | 'formatUsageReport' | 'watchUsage' | 'fetchSubscriptionUsage' | 'diagnoseModels' | 'writeLocalRunReport';
+type CommandRunner = (command: string, options?: {
+    cwd?: string;
+    timeout?: number;
+}) => Promise<unknown>;
+export declare const PREREQUISITES_TEXT = "Prerequisites:\n  - Claude Code CLI installed and authenticated (Claude subscription): https://claude.com/claude-code\n  - GitHub CLI authenticated: gh auth login\n  - GITHUB_TOKEN or GH_TOKEN set (falls back to `gh auth token`)\nRun inside a git repository with a GitHub remote.\n";
+/** Printed after the command list in `factory --help`: the env vars operators reach for most. */
+export declare const HELP_FOOTER_TEXT = "\nCommon environment variables:\n  FACTORY_MERGE=1                     Squash-merge eligible PRs (--auto-merge / --no-auto-merge win)\n  FACTORY_MERGE_ADMIN=1               Merge with GitHub admin bypass of unmet requirements\n  FACTORY_SKIP_CI=1                   Do not wait for CI before merging\n  FACTORY_SANDBOX=0                   Disable the containment sandbox for agent runs (dangerous)\n  FACTORY_PLAN_MODEL=<id>             Pick the PLAN model\n  FACTORY_BUILD_MODEL=<id>            Pick the BUILD model\n  FACTORY_STOP_AT=<fraction>          Usage fraction (0-1] at which work pauses\n  FACTORY_RESUME_AT=<fraction>        Usage fraction (0-1] at which paused work resumes\n  FACTORY_ALLOW_STALE=1               Run even when the built CLI is older than its source\nEvery config key, its default, and its env var: docs/config.example.yaml\n\nRun `factory <command> --help` for a command's options.\nDocs: https://github.com/on-par/software-factory#readme";
+export declare function errorDetail(err: unknown): string;
+export declare function hasGitHubToken(env?: NodeJS.ProcessEnv, tryToken?: () => string): boolean;
+/** 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 declare function buildInitConfig(format?: 'yaml' | 'json'): string;
+/** One-line onboarding reachability summary, e.g. "policy=auto, 3/7 models reachable". */
+export declare function formatInitReachability(diagnoses: ModelDiagnosis[]): string;
+/** 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 declare function runMigrate(repoRoot: string, opts?: {
+    dryRun?: boolean;
+    toYaml?: boolean;
+    migrateToYaml?: typeof migrateRepoConfigToYaml;
+}): Promise<void>;
+export declare class InvalidProductNameError extends Error {
+}
+/** Expected user-facing CLI failure. Thrown by command helpers; only main() maps it to a process exit code. */
+export declare class CliExitError extends Error {
+    readonly code: number;
+    constructor(message: string, code: number);
+}
+/** Parse a CLI <issue> argument. Throws CliExitError(2) before any git/GitHub work runs. */
+export declare function parseIssueArg(raw: string): number;
+/** Run `factory feedback` and print the filed issue; validation errors become exit-2 CliExitErrors. */
+export declare function runFeedbackCommand(prUrl: string, opts: {
+    note?: string;
+}, deps: FeedbackDeps, log?: (line: string) => void): Promise<void>;
+export declare function cmdFeedback(prUrl: string, opts: {
+    note?: string;
+    branchPrefix?: string;
+}): Promise<void>;
+export declare function cmdFilingPreview(runId: string, opts: {
+    branchPrefix?: string;
+}): Promise<void>;
+export declare function assertValidProduct(product: string): void;
+export interface ReadActiveProductDeps {
+    fileExists?: (p: string) => boolean;
+    readFile?: (p: string) => string;
+}
+/**
+ * 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 declare function readActiveProduct(productPath: string, deps?: ReadActiveProductDeps): string | undefined;
+/** Extract the template's ```markdown skeleton and fill in the product name. */
+export declare function scaffoldConstitution(template: string, product: string): string;
+export declare function cmdConstitution(opts: {
+    list?: boolean;
+    product?: string;
+    init?: string | boolean;
+    force?: boolean;
+}, deps?: Pick<CliDeps, 'ConstitutionLoader'>): Promise<void>;
+export declare function formatDoctorReport(diagnoses: ModelDiagnosis[]): string;
+export declare function hasReachableWorker(diagnoses: ModelDiagnosis[]): boolean;
+export interface UsageKnobs {
+    cap: number;
+    stopAt: number;
+    resumeAt: number;
+    pollMs: number;
+    watch: boolean;
+    estimator: boolean;
+    /** Where `watch` was decided — `'flag'` when `--usage-watch`/`--no-usage-watch` was supplied. */
+    watchSource: WatchdogPolicySource;
+    stopAtSource: WatchdogPolicySource;
+    resumeAtSource: WatchdogPolicySource;
+    pollSource: WatchdogPolicySource;
+}
+export declare function resolveUsageKnobs(env?: NodeJS.ProcessEnv, repoConfig?: RepoFactoryConfig | null, overrides?: WatchdogPolicyOverrides): UsageKnobs;
+/** 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 declare function usageWatchSourceLabel(source: WatchdogPolicySource, watch: boolean): string;
+export declare function cmdUsage(deps?: Pick<CliDeps, ShellOpKey | 'fetchSubscriptionUsage' | 'estimateTrailingSpend' | 'formatUsageReport'>, opts?: {
+    json?: boolean;
+}): Promise<void>;
+export declare function cmdStatus(opts?: {
+    kpis?: boolean;
+    json?: boolean;
+}): Promise<void>;
+/** 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 declare function tuiQueueReader(input: {
+    localQueue: boolean;
+    queueFile: string;
+    queueProposedFile: string;
+    repo: string | undefined;
+    token?: () => string | undefined;
+    octokit?: (token: string) => Octokit;
+}): QueueReader;
+export type { ParkReason, RunOutcome } from '@on-par/factory-core';
+export { parkEvents, parkReasonFor } from '@on-par/factory-core';
+export declare class LaneParkError extends Error {
+    readonly outcome: Extract<RunOutcome, {
+        state: 'parked';
+    }>;
+    constructor(message: string, reason: ParkReason, failure?: {
+        failureSignature?: string;
+        failingChecks?: string[];
+    });
+    get reason(): ParkReason;
+    get failureSignature(): string | undefined;
+    get failingChecks(): string[] | undefined;
+}
+/** 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 declare class LaneEnvironmentPauseError extends Error {
+    readonly baseSha: string;
+    readonly failingChecks: string[];
+    readonly failureSignature?: string;
+    constructor(message: string, failure: {
+        baseSha: string;
+        failingChecks: string[];
+        failureSignature?: string;
+    });
+}
+/** 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 declare function resolveLaneBaseUrl(paths: ReturnType<typeof getFactoryPaths>, settings: EnvironmentProxySettings, worktree: string, appPort: number | undefined, deps?: {
+    isRunning?: typeof isProxyRunning;
+}): {
+    baseUrl?: string;
+    note: string;
+};
+/** 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 declare function resolveEnvironmentAcquirer(opts: {
+    laneSandboxRuntime: SandboxRuntime;
+    paths: ReturnType<typeof getFactoryPaths>;
+    worktree: string;
+    branch: string;
+    range: [number, number];
+    processGroupGraceMs: number;
+    log: (type: EventKind, msg: string) => void;
+    findPortListeners?: typeof defaultFindPortListeners;
+    reapOrphanProcesses?: typeof reapOrphanProcesses;
+}): (() => Promise<Environment>) | undefined;
+export declare function shipIssue(issueNum: number, opts: {
+    product?: string;
+    autoRework?: boolean;
+    interactive?: boolean;
+    sandbox?: boolean;
+    approvePlan?: boolean;
+    branchPrefix?: string;
+    /** `run-issue --size-gate` (ADR-0147); undefined defers to sizeGate.mode in the config. */
+    sizeGate?: SizeGateMode;
+    /** run-issue --max-slices (ADR-0156); undefined defers to sizeGate.maxSlices. */
+    maxSlices?: number;
+    /** `--pr-classifier` / `--no-pr-classifier` (#1724); undefined defers to config/env. */
+    prClassifier?: boolean;
+}, ctx?: {
+    repoRoot: string;
+    ghRepo: string;
+    /** Resolved factory state paths, supplied by daemon lanes with an external state root. */
+    paths?: ReturnType<typeof getFactoryPaths>;
+    lane?: string;
+    workRequest?: WorkRequest;
+    /** Receives the core RunOutcome before shipIssue maps it to a return/throw — lets
+     *  `run-issue --run-children` read the PR number as data (#1747). */
+    onOutcome?: (outcome: RunOutcome) => void;
+    /** Input source for planPhase to resolve; defaults inside planPhase to this run's GitHub issue. */
+    workSource?: {
+        kind: WorkRequestSourceKind;
+        params: unknown;
+    };
+    /** Local-only policy (#508): run in this caller-provided workspace, skip
+     *  worktree creation, disable publishing, and skip the SHIP phase. */
+    localOnly?: LocalOnlyPolicy;
+    /** Benchmark artifact directory (#509) — only set for local-only runs. */
+    artifactsDir?: string;
+}, deps?: Pick<CliDeps, 'octokit' | 'planPhase' | 'buildPhase' | 'checkPhase' | 'shipPhase' | ConfigLoaderKey | GitOpKey | ShellOpKey | CoreOpKey>): Promise<string>;
+export interface LaneGcDeps {
+    loadConfig?: (configPath: string) => Pick<FactoryConfig, 'worktree' | 'sandbox'>;
+    sweep?: typeof sweepWorktrees;
+    emitEvent?: typeof logEvent;
+    octokit?: () => NonNullable<Parameters<typeof sweepWorktrees>[1]>['octokit'];
+}
+/** 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 declare function sweepBetweenLaneIssues(issue: number, lane: string, repoRoot: string, ghRepo: string, paths: ReturnType<typeof getFactoryPaths>, deps?: LaneGcDeps): Promise<'disabled' | 'land-in-progress' | 'swept' | 'failed'>;
+/** 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 declare function withRepoRunLock<T>(paths: ReturnType<typeof getFactoryPaths>, command: string, fn: () => Promise<T>, deps?: {
+    runLock?: typeof withRunLock;
+    emitEvent?: typeof logEvent;
+}): Promise<T>;
+/** 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 declare function reapParkedLaneWorktree(issue: number, repoRoot: string, ghRepo: string, paths: ReturnType<typeof getFactoryPaths>, prefixOverride?: string): Promise<void>;
+export declare function cmdWorktreeGc(opts: {
+    dryRun?: boolean;
+    ttlDays?: string;
+    branchPrefix?: string;
+}): Promise<void>;
+/** `factory reset <issue...>` (#1787): wipes an issue's local state; see reset.ts. */
+export declare function cmdReset(issues: string[], opts: {
+    branchPrefix?: string;
+    dryRun?: boolean;
+    force?: boolean;
+}): Promise<void>;
+/** deps overrides the config loaders, git ops, internal ops and octokit for this call, like shipIssue. */
+export declare function cmdLand(issueNum: number, opts?: {
+    branchPrefix?: string;
+    allowGated?: boolean;
+}, deps?: Pick<CliDeps, ConfigLoaderKey | GitOpKey | InternalOpKey | ShellOpKey | 'octokit'>): Promise<void>;
+declare function landIssue(issueNum: number, repoRoot: string, ghRepo: string, paths: ReturnType<typeof getFactoryPaths>, octokit: Octokit, skipCI?: boolean, branchPrefix?: string, opts?: {
+    allowGated?: boolean;
+}): Promise<{
+    branch: string;
+    prNumber: number;
+}>;
+export declare function prLookupFailure(issueNum: number, branch: string, err: unknown): LandFailureError;
+export declare function triageProposalMessage(proposed: string, proposedPath: string, queuePath: string): string | null;
+export declare function cmdTriageAccept(opts: {
+    force?: boolean;
+}): Promise<void>;
+export declare function cmdQueueMigrate(opts?: {
+    file?: string;
+    dryRun?: boolean;
+}): Promise<void>;
+export declare function cmdUnpark(issueArg: string, opts?: {
+    lane?: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function cmdQueueAdd(lane: string, issueArgs: string[], opts?: {
+    json?: boolean;
+}): Promise<void>;
+export declare function cmdQueueReconcile(opts?: {
+    lane?: string;
+}): Promise<void>;
+export declare function cmdQueueList(opts?: {
+    json?: boolean;
+    lane?: string;
+}): Promise<void>;
+export declare function cmdRuns(opts?: {
+    json?: boolean;
+    limit?: string;
+    diffstat?: string;
+}): Promise<void>;
+export declare function cmdQueueClear(opts?: {
+    dryRun?: boolean;
+    yes?: boolean;
+    lane?: string;
+}): Promise<void>;
+export declare function triageNoProposalError(plannerError: unknown): CliExitError;
+/** 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 declare function startLaneProxy(paths: ReturnType<typeof getFactoryPaths>, settings: EnvironmentProxySettings, deps?: {
+    createProxy?: typeof createLaneProxy;
+    emitEvent?: typeof logEvent;
+}): Promise<{
+    proxy?: LaneProxy;
+}>;
+/** Wraps cmdRun so an empty queue is a no-op (not a throw) while auto-ingest is enabled and watching. */
+export declare function createSuperviseRunQueue(paths: ReturnType<typeof getFactoryPaths>, ingestCfg: IngestSettings, deps?: {
+    cmdRunFn?: () => Promise<void>;
+    readQueueFile?: () => string;
+    pendingCount?: () => Promise<number>;
+    emitEvent?: typeof logEvent;
+}): () => Promise<void>;
+/** Builds the per-cycle auto-ingest hook passed to superviseLoop; failures are logged, never thrown. */
+export declare function createIngestHook(repoRoot: string, paths: ReturnType<typeof getFactoryPaths>, ingestCfg: IngestSettings, deps?: {
+    runAutoIngestFn?: typeof runAutoIngest;
+    emitEvent?: typeof logEvent;
+    branchPrefix?: string;
+}): () => Promise<number>;
+type RunLaneDeps = {
+    /** Lane circuit breaker (#1918): pause after this many consecutive parks with the same
+     *  non-empty failure signature. 0 or absent = off; cmdRun wires the resolved
+     *  budget.laneBreakerThreshold. */
+    laneBreakerThreshold?: number;
+    /** Posts the lane-paused comment on the tripping issue (#1919). Defaults to a no-op so
+     *  injected-deps callers and tests are unaffected; cmdRun wires it to issues.createComment. */
+    commentIssue?: (issue: number, body: string) => Promise<void>;
+    ship?: (issue: number, opts: {
+        product?: string;
+        autoRework?: boolean;
+        interactive?: boolean;
+        approvePlan?: boolean;
+    }, ctx?: {
+        repoRoot: string;
+        ghRepo: string;
+        paths: ReturnType<typeof getFactoryPaths>;
+        lane?: string;
+        onOutcome?: (outcome: RunOutcome) => void;
+    }) => Promise<string>;
+    waitMerge?: typeof waitForMerge;
+    pathExists?: (path: string) => boolean;
+    emitEvent?: typeof logEvent;
+    claimNext?: () => Promise<QueueClaim | null>;
+    releaseIssue?: (issue: number, outcome: QueueReleaseOutcome) => Promise<void>;
+    /** Refreshes the claim lease every HEARTBEAT_INTERVAL_MS while an issue is in flight
+     *  (#1500). Absent for static local-queue lanes, which carry no remote claim to lease. */
+    heartbeat?: (issue: number) => Promise<unknown>;
+    /** Eager park-time worktree reap (#1007). Defaults to a no-op so injected-deps callers and
+     *  tests are unaffected; cmdRun wires it to reapParkedLaneWorktree. */
+    reapWorktree?: (issue: number) => Promise<void>;
+    /** Between-issues worktree GC pass (#1757), run after every terminal outcome before the
+     *  lane moves on. Defaults to a no-op so injected-deps callers and tests are unaffected;
+     *  cmdRun wires it to sweepBetweenLaneIssues. */
+    sweepFinished?: (issue: number) => Promise<void>;
+    /** Number of issues still claimable on this lane's remote queue (#1222). Absent for
+     *  static local lanes, whose pending list is the whole truth. */
+    countRemaining?: () => Promise<number>;
+};
+export interface PlannedLane {
+    lane: string;
+    /** Seed issues to work before claiming. Always empty in GitHub-queue mode. */
+    issues: number[];
+    deps: Pick<RunLaneDeps, 'claimNext' | 'releaseIssue' | 'heartbeat' | 'countRemaining'>;
+}
+export declare function laneQueueDeps(queue: GithubQueue, lane: string): Pick<RunLaneDeps, 'claimNext' | 'releaseIssue' | 'heartbeat' | 'countRemaining'>;
+export interface OpenPullRequestEvidence {
+    number: number;
+    branch: string;
+    headSha: string;
+    headRepoFullName: string | null;
+}
+/** A slice PR's state as the queue preflight sees it (ADR-0147). */
+export type SlicePullState = 'open' | 'merged' | 'closed';
+export interface QueuePreflightOps {
+    expectedHeadRepoFullName: string;
+    findOpenPR(issue: number): Promise<OpenPullRequestEvidence | undefined>;
+    getLandState(prNumber: number): ReturnType<typeof getPullRequestLandState>;
+    watch(ref: string): Promise<CiOutcome>;
+    /** The factory-written slice plan comment on the issue (ADR-0147). */
+    findSlicePlan(issue: number): Promise<SlicePlanCommentLookup>;
+    /** State of a slice PR found by the number recorded in the slice plan. */
+    getPullState(prNumber: number): Promise<SlicePullState>;
+    /** Rewrite the factory's slice plan comment in place. */
+    saveSlicePlan(issue: number, plan: SlicePlan): Promise<void>;
+}
+export declare function createQueuePreflightOps(octokit: Octokit, owner: string, repo: string): QueuePreflightOps;
+/** Resolve queued work from GitHub evidence without consuming model or worktree resources. */
+export declare function preflightQueuedIssue(issue: QueueIssue, deps: QueuePreflightOps): Promise<QueuePreflightDecision>;
+export declare function planRunLanes(input: {
+    localQueue: boolean;
+    /** `null` when `.factory/queue` does not exist. */
+    readLocalQueue: () => string | null;
+    /** Lazy so the octokit client is never built under --local-queue. */
+    queue: () => GithubQueue;
+}): Promise<{
+    lanes: PlannedLane[];
+    diagnostics: QueueDiagnostic[];
+}>;
+export declare function renderLanePausedComment(payload: LanePausedPayload): string;
+export declare function runLane(lane: string, issues: number[], repoRoot: string, ghRepo: string, paths: ReturnType<typeof getFactoryPaths>, deps?: RunLaneDeps): Promise<void>;
+export declare function isPrMerged(octokit: Octokit, owner: string, repoName: string, branch: string): Promise<boolean>;
+export declare function findOpenPRNumber(octokit: Octokit, owner: string, repoName: string, branch: string): Promise<number | undefined>;
+export declare function findOpenPRForIssue(octokit: Octokit, owner: string, repoName: string, issueNum: number): Promise<OpenPullRequestEvidence | undefined>;
+export declare function squashMergeAndDelete(octokit: Octokit, owner: string, repoName: string, branch: string, prNumber: number, 
+/** `sha`: the CI-verified head commit. GitHub refuses the merge if the PR head has moved. */
+opts?: {
+    admin?: boolean;
+    run?: CommandRunner;
+    sha?: string;
+}): Promise<void>;
+export declare class MergeGatedError extends Error {
+    readonly issue: number;
+    readonly prNumber: number;
+    readonly label: string;
+    constructor(message: string, issue: number, prNumber: number, label: string);
+}
+export declare class LandConflictError extends Error {
+    readonly parkReason: ParkReason;
+}
+/** 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 declare class IssueSkippedError extends Error {
+    readonly reason: 'already-closed';
+    constructor(message: string, reason: 'already-closed');
+}
+export declare class AwaitingReviewError extends Error {
+    readonly prNumber: number;
+    constructor(message: string, prNumber: number);
+}
+/** 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 declare class IssueDecomposedError extends Error {
+    readonly childIssues: number[];
+    constructor(message: string, childIssues: number[]);
+}
+export declare class LandFailureError extends Error {
+    readonly code: number;
+    constructor(message: string, code: number);
+}
+/** 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 declare class CiFailedError extends Error {
+    readonly prNumber: number;
+    readonly parkReason: ParkReason;
+    constructor(message: string, prNumber: number);
+}
+/** 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 declare class CiUnverifiedError extends CiFailedError {
+}
+/** 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 declare function isHeadModifiedMergeError(err: unknown): boolean;
+export declare function isReviewRequiredMergeError(err: unknown, state: {
+    mergeStateStatus?: string;
+    reviewDecision?: string;
+}): boolean;
+export declare function getPullRequestLandState(octokit: Octokit, owner: string, repoName: string, prNumber: number): Promise<{
+    id?: string;
+    isDraft?: boolean;
+    mergeStateStatus?: string;
+    reviewDecision?: string;
+}>;
+export declare function markPullRequestReady(octokit: Octokit, pullRequestId: string): Promise<void>;
+export declare function rebaseDirtyPullRequest(opts: {
+    issue: number;
+    branch: string;
+    worktree: string;
+    prNumber: number;
+    log: (type: EventKind, msg: string) => void;
+    run?: CommandRunner;
+    pathExists?: (path: string) => boolean;
+}): Promise<void>;
+/** A critical section runner: the land path takes this instead of owning lock composition,
+ *  so the locks can be scoped to git mutations and stubbed in tests (#645). */
+export type LandLock = <T>(fn: () => Promise<T>) => Promise<T>;
+export declare function landOpenPullRequest(opts: {
+    octokit: Octokit;
+    owner: string;
+    repoName: string;
+    ghRepo: string;
+    repoRoot: string;
+    issue: number;
+    branch: string;
+    worktree: string;
+    prNumber: number;
+    log: (type: EventKind, msg: string) => void;
+    run?: CommandRunner;
+    pathExists?: (path: string) => boolean;
+    sleep?: (ms: number) => Promise<void>;
+    skipCI?: boolean;
+    adminMerge?: boolean;
+    watch?: (opts: WatchChecksOptions) => Promise<CiOutcome>;
+    withLock?: LandLock;
+    /** Materializes an adopted branch only after its locked state re-read confirms it needs rebasing. */
+    ensureWorktree?: () => Promise<void>;
+}): Promise<void>;
+export declare function issueFromFactoryBranch(branch: string, prefix?: string): number | undefined;
+export declare function listOpenFactoryPRs(octokit: Octokit, owner: string, repoName: string, branchPrefix?: string): Promise<Array<{
+    number: number;
+    branch: string;
+    reviewDecision?: string;
+    isDraft?: boolean;
+}>>;
+export interface SweepDeps {
+    createOctokit?: () => Octokit;
+    loadConfig?: (configPath: string) => FactoryConfig;
+    listPRs?: typeof listOpenFactoryPRs;
+    land?: typeof landIssue;
+    emitEvent?: typeof logEvent;
+    writeLine?: (line: string) => void;
+}
+export declare function sweepApprovedPRs(repoRoot: string, ghRepo: string, paths: ReturnType<typeof getFactoryPaths>, deps?: SweepDeps, opts?: {
+    branchPrefix?: string;
+}): Promise<{
+    landed: number[];
+    skipped: Array<{
+        pr: number;
+        branch: string;
+        reason: string;
+    }>;
+    failed: Array<{
+        pr: number;
+        issue: number;
+        reason: string;
+    }>;
+}>;
+export declare function cmdResumeApproved(opts?: {
+    branchPrefix?: string;
+}): Promise<void>;
+/** 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 declare 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 declare const MERGE_CHECK_FAILURE_BUDGET_MS: number;
+/** 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 declare function isPermanentMergeCheckError(err: unknown): boolean;
+type WaitForMergeDeps = {
+    createOctokit?: () => Octokit;
+    pathExists?: (path: string) => boolean;
+    checkMerged?: typeof isPrMerged;
+    loadConfig?: (configPath: string) => FactoryConfig;
+    land?: (issueNum: number, repoRoot: string, ghRepo: string, paths: ReturnType<typeof getFactoryPaths>, octokit: Octokit) => Promise<{
+        branch: string;
+        prNumber: number;
+    }>;
+    listIssueLabels?: (octokit: Octokit, owner: string, repo: string, issue: number) => Promise<string[]>;
+    sleep?: (ms: number) => Promise<void>;
+    emitEvent?: typeof logEvent;
+    mergeEnabled?: () => boolean;
+    writeLine?: (line: string) => void;
+    /** Injectable clock so the wall-clock failure budget is testable. Default `() => Date.now()`. */
+    now?: () => number;
+    /** Per-invocation CLI flag overrides (`--auto-merge`/`--no-auto-merge`). Threaded in by
+     *  cmdRun rather than read from disk so a live run's merge gate cannot change underneath
+     *  it (#1400). */
+    mergeOverrides?: MergePolicyOverrides;
+};
+export declare function waitForMerge(issue: number, branch: string, repoRoot: string, ghRepo: string, paths: ReturnType<typeof getFactoryPaths>, deps?: WaitForMergeDeps): Promise<void>;
+export interface SuperviseDeps {
+    cap: number;
+    resumeAt: number;
+    pollMs: number;
+    watch?: boolean;
+    /** Where `watch` was decided, so the loop can attribute an explicit operator override
+     *  to the flag rather than always blaming FACTORY_USAGE_WATCH (#1404). */
+    watchSource?: WatchdogPolicySource;
+    /** Where the resume threshold was decided, for attribution of explicit CLI overrides. */
+    resumeAtSource?: WatchdogPolicySource;
+    /** Where the poll interval was decided, for attribution of explicit CLI overrides. */
+    pollSource?: WatchdogPolicySource;
+    estimator?: boolean;
+    stopFile: string;
+    eventsFile: string;
+    now?: boolean;
+    runQueue: () => Promise<void>;
+    readUsageFn?: () => Promise<UsageReading | null>;
+    pathExists?: (path: string) => boolean;
+    clearStop?: (path: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+    emitEvent?: typeof logEvent;
+    writeLine?: (line: string) => void;
+    /** When set, run once per cycle before draining the queue; returns count appended. Its presence
+     *  also switches the loop into perpetual-poll mode (see superviseLoop). */
+    ingest?: () => Promise<number>;
+}
+export declare function superviseLoop(deps: SuperviseDeps): Promise<void>;
+export declare function getCliVersion(): string;
+/** Injectable seams for main(). Unset fields fall back to the real implementations. */
+export interface CliDeps {
+    /** Shell seams for every `exec` / `execSync` the CLI runs (git, gh, claude, ollama, security). Default to node:child_process. */
+    exec?: ShellExec;
+    execSync?: ShellExecSync;
+    /** Passed to the `factory daemon start|stop|status|logs` wrappers. */
+    daemon?: DaemonCtlDeps;
+    /** Replaces the TUI entry point used by `factory tui`. */
+    runTui?: typeof runTui;
+    /** Builds the GitHub client for every CLI GitHub call (shipIssue, land, queue, triage, …). Defaults to createFactoryOctokit with the resolved token. */
+    octokit?: () => Octokit;
+    /** Phase overrides forwarded into RunPorts by shipIssue, including calls made from main(). Each defaults to the factory-core phase. */
+    planPhase?: RunPorts['planPhase'];
+    buildPhase?: RunPorts['buildPhase'];
+    checkPhase?: RunPorts['checkPhase'];
+    shipPhase?: RunPorts['shipPhase'];
+    /** Config loaders and resolvers. Each defaults to the factory-core export of the same name. */
+    loadModelsConfig?: typeof loadModelsConfig;
+    loadRoutesConfig?: typeof loadRoutesConfig;
+    loadFactoryConfigForRepo?: typeof loadFactoryConfigForRepo;
+    loadRepoConfig?: typeof loadRepoConfig;
+    resolveTimeouts?: typeof resolveTimeouts;
+    resolveSkipCI?: typeof resolveSkipCI;
+    getConstitutionsDir?: typeof getConstitutionsDir;
+    resolveEffectiveModelPins?: typeof resolveEffectiveModelPins;
+    /** Git worktree/fetch side effects. Each defaults to the factory-core export of the same name. */
+    setupWorktree?: typeof setupWorktree;
+    cleanupWorktree?: typeof cleanupWorktree;
+    gitFetch?: typeof gitFetch;
+    /** factory-core/internal ops (CI watch, costs, worktree GC, reconcile reaps, local-small). Each defaults to the export of the same name. */
+    watchChecks?: typeof watchChecks;
+    createLocalSmallDryRun?: typeof createLocalSmallDryRun;
+    readCosts?: typeof readCosts;
+    sweepWorktrees?: typeof sweepWorktrees;
+    releaseStaleClaims?: typeof releaseStaleClaims;
+    findUnmergedGreenPrs?: typeof findUnmergedGreenPrs;
+    listOrphanContainers?: typeof listOrphanContainers;
+    reapOrphanContainers?: typeof reapOrphanContainers;
+    listMicroVms?: typeof listMicroVms;
+    reapOrphanMicroVm?: typeof reapOrphanMicroVm;
+    formatGcReport?: typeof formatGcReport;
+    /** factory-core classes and ops (routing, constitutions, process/port probes, usage, diagnose, local report). Each defaults to the export of the same name. */
+    ModelRouter?: typeof ModelRouter;
+    ConstitutionLoader?: typeof ConstitutionLoader;
+    ModelRegistry?: typeof ModelRegistry;
+    isCommandAvailable?: typeof isCommandAvailable;
+    defaultFindPortListeners?: typeof defaultFindPortListeners;
+    reapOrphanProcesses?: typeof reapOrphanProcesses;
+    estimateTrailingSpend?: typeof estimateTrailingSpend;
+    formatUsageReport?: typeof formatUsageReport;
+    watchUsage?: typeof watchUsage;
+    fetchSubscriptionUsage?: typeof fetchSubscriptionUsage;
+    diagnoseModels?: typeof diagnoseModels;
+    writeLocalRunReport?: typeof writeLocalRunReport;
+}
+export declare function cmdStop(opts?: {
+    json?: boolean;
+}): Promise<void>;
+export declare function cmdResume(opts?: {
+    json?: boolean;
+}): Promise<void>;
+export declare function main(argv?: string[], deps?: CliDeps): Promise<void>;
+//# sourceMappingURL=index.d.ts.map