@canhta/dsh-autopilot 0.1.0-alpha.1

package/lib/admission/resume-control.js

@@ -0,0 +1,213 @@
+import { z } from 'zod';
+import { validateExecutionSettings } from '../config.js';
+import { trackerProviderId } from '../tracker.js';
+import { readEveryCandidate } from './candidates.js';
+import { STATE_KEY } from './constants.js';
+import { evaluateIssue, isPausedActiveRun, isPausedQueuedRun, matchesRetainedIssue, sameRetainedRun, validateActiveResumeFacts, } from './policy.js';
+import { executionSchema, runIdSchema, stateSchema } from './state.js';
+export class ResumeControl {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    /**
+     * Revalidate an operator-held queued run against the current tracker issue and return it to the resumption queue.
+     * Requires an enabled scheduler, certain deployment usage, the selected tracker provider, one currently eligible issue,
+     * and an unchanged readiness generation and Agent Brief. Provider/read/validation failures or a concurrent durable
+     * state change preserve the hold. Success clears only the hold, keeps the run identity, and allocates no Session or
+     * worktree. Provider withdrawal owns cancellation of its read; callers cannot independently cancel this operation.
+     */
+    async resumeRun(runId) {
+        const parsedRunId = runIdSchema.parse(runId);
+        const settings = this.dependencies.settings();
+        const providerId = trackerProviderId(settings.trackerProvider);
+        const beforeRead = this.dependencies.state();
+        if (beforeRead.scheduler.mode !== 'enabled') {
+            throw new Error('scheduler must be enabled to resume a run');
+        }
+        if (beforeRead.budget.usageUncertain) {
+            throw new Error('deployment token usage is uncertain; reconcile it before resuming');
+        }
+        const retained = beforeRead.runs.find((run) => run.runId === parsedRunId);
+        if (retained === undefined)
+            throw new Error(`run "${parsedRunId}" does not exist`);
+        if (!isPausedQueuedRun(retained) || !retained.pause.operatorHold) {
+            throw new Error(`run "${parsedRunId}" is not paused on an operator hold`);
+        }
+        if (retained.providerId !== providerId) {
+            throw new Error(`run "${parsedRunId}" cannot be resumed from tracker provider "${providerId}"`);
+        }
+        return this.dependencies.tracker.withProvider(providerId, async (reader) => {
+            const candidates = await readEveryCandidate(reader, providerId);
+            const matches = candidates.filter((issue) => issue.bindingId === retained.bindingId && issue.issueId === retained.issueId);
+            if (matches.length !== 1) {
+                throw new Error(`run "${parsedRunId}" cannot be resumed because its tracker issue is not uniquely current`);
+            }
+            const issue = matches[0];
+            if (issue === undefined)
+                throw new Error(`run "${parsedRunId}" cannot be resumed without its tracker issue`);
+            const evaluation = evaluateIssue(issue, settings.maxBriefBytes);
+            if ('reason' in evaluation) {
+                throw new Error(`run "${parsedRunId}" cannot be resumed because tracker eligibility is ${evaluation.reason}`);
+            }
+            if (!matchesRetainedIssue(retained, providerId, evaluation)) {
+                throw new Error(`run "${parsedRunId}" cannot be resumed because its tracker authorization changed`);
+            }
+            let resumed;
+            await this.dependencies.table().update(STATE_KEY, (current) => {
+                if (current.scheduler.mode !== 'enabled') {
+                    throw new Error('scheduler must be enabled to resume a run');
+                }
+                if (current.budget.usageUncertain) {
+                    throw new Error('deployment token usage is uncertain; reconcile it before resuming');
+                }
+                const currentSettings = this.dependencies.settings();
+                if (trackerProviderId(currentSettings.trackerProvider) !== providerId) {
+                    throw new Error(`run "${parsedRunId}" cannot be resumed because the selected tracker provider changed`);
+                }
+                const currentEvaluation = evaluateIssue(issue, currentSettings.maxBriefBytes);
+                if ('reason' in currentEvaluation) {
+                    throw new Error(`run "${parsedRunId}" cannot be resumed because current tracker eligibility is ${currentEvaluation.reason}`);
+                }
+                const index = current.runs.findIndex((run) => run.runId === parsedRunId);
+                const run = current.runs[index];
+                if (!isPausedQueuedRun(run) || !run.pause.operatorHold) {
+                    throw new Error(`run "${parsedRunId}" is not paused on an operator hold`);
+                }
+                if (!sameRetainedRun(run, retained) || !matchesRetainedIssue(run, providerId, currentEvaluation)) {
+                    throw new Error(`run "${parsedRunId}" cannot be resumed because its retained identity changed`);
+                }
+                const { pause: _pause, ...queued } = structuredClone(run);
+                resumed = { ...queued, state: 'queued', queueClass: 'resumption' };
+                const next = structuredClone(current);
+                next.runs[index] = resumed;
+                next.revision += 1;
+                return stateSchema.parse(next);
+            });
+            if (resumed === undefined)
+                throw new Error(`run "${parsedRunId}" was not resumed`);
+            return structuredClone(resumed);
+        });
+    }
+    /**
+     * Revalidate an allocated pause against the current tracker and execution policy, then atomically reserve the retained
+     * run's remaining token cap and return it to `implementing`. The caller must first prove the retained Session readable
+     * and supply exact current Git facts. Scheduler authorization cannot clear an operator hold; explicit operator
+     * authorization can. Any failed or concurrent check leaves the pause unchanged.
+     */
+    async resumeActiveRun(runId, observedGit, authorization) {
+        const parsedRunId = runIdSchema.parse(runId);
+        const parsedGit = executionSchema.shape.git.unwrap().parse(observedGit);
+        const settings = this.dependencies.settings();
+        validateExecutionSettings(settings);
+        const providerId = trackerProviderId(settings.trackerProvider);
+        const beforeRead = this.dependencies.state();
+        if (beforeRead.scheduler.mode !== 'enabled')
+            throw new Error('scheduler must be enabled to resume a run');
+        if (beforeRead.budget.usageUncertain) {
+            throw new Error('deployment token usage is uncertain; reconcile it before resuming');
+        }
+        const retained = beforeRead.runs.find((run) => run.runId === parsedRunId);
+        if (!isPausedActiveRun(retained))
+            throw new Error(`run "${parsedRunId}" is not an allocated paused run`);
+        validateActiveResumeFacts(retained, parsedGit, settings, authorization);
+        return this.dependencies.tracker.withProvider(providerId, async (reader) => {
+            const candidates = await readEveryCandidate(reader, providerId);
+            const matches = candidates.filter((issue) => issue.bindingId === retained.bindingId && issue.issueId === retained.issueId);
+            if (matches.length !== 1) {
+                throw new Error(`run "${parsedRunId}" cannot be resumed because its tracker issue is not uniquely current`);
+            }
+            const issue = matches[0];
+            if (issue === undefined)
+                throw new Error(`run "${parsedRunId}" cannot be resumed without its tracker issue`);
+            const evaluation = evaluateIssue(issue, settings.maxBriefBytes);
+            if ('reason' in evaluation || !matchesRetainedIssue(retained, providerId, evaluation)) {
+                throw new Error(`run "${parsedRunId}" cannot be resumed because its tracker authorization changed`);
+            }
+            let resumed;
+            await this.dependencies.table().update(STATE_KEY, (current) => {
+                const currentSettings = this.dependencies.settings();
+                if (current.scheduler.mode !== 'enabled')
+                    throw new Error('scheduler must be enabled to resume a run');
+                if (current.budget.usageUncertain) {
+                    throw new Error('deployment token usage is uncertain; reconcile it before resuming');
+                }
+                if (trackerProviderId(currentSettings.trackerProvider) !== providerId) {
+                    throw new Error(`run "${parsedRunId}" cannot be resumed because the selected tracker provider changed`);
+                }
+                const currentEvaluation = evaluateIssue(issue, currentSettings.maxBriefBytes);
+                const index = current.runs.findIndex((run) => run.runId === parsedRunId);
+                const run = current.runs[index];
+                if (!isPausedActiveRun(run))
+                    throw new Error(`run "${parsedRunId}" is no longer paused`);
+                if ('reason' in currentEvaluation ||
+                    !matchesRetainedIssue(run, providerId, currentEvaluation) ||
+                    JSON.stringify(run) !== JSON.stringify(retained)) {
+                    throw new Error(`run "${parsedRunId}" cannot be resumed because its retained authorization changed`);
+                }
+                validateActiveResumeFacts(run, parsedGit, currentSettings, authorization);
+                const reservation = Math.min(run.budget.allowanceTokens, run.budget.capTokens - run.budget.settledTokens);
+                if (current.budget.settledTokens + current.budget.reservedTokens + reservation >
+                    currentSettings.deploymentTokenCap) {
+                    throw new Error('deployment token cap cannot cover the retained run continuation');
+                }
+                const { pause: _pause, ...allocated } = structuredClone(run);
+                resumed = {
+                    ...allocated,
+                    state: 'implementing',
+                    queueClass: 'resumption',
+                    execution: { ...allocated.execution, attempt: allocated.execution.attempt + 1 },
+                    budget: { ...allocated.budget, reservedTokens: reservation },
+                };
+                const next = structuredClone(current);
+                next.runs[index] = resumed;
+                next.budget.reservedTokens += reservation;
+                next.revision += 1;
+                return stateSchema.parse(next);
+            });
+            if (resumed === undefined)
+                throw new Error(`run "${parsedRunId}" was not resumed`);
+            return structuredClone(resumed);
+        });
+    }
+    /**
+     * Persist a definite retained-resource incompatibility discovered before an allocated pause can resume. The run must
+     * still be the same durable active pause; an identical recovery reason is idempotent. This operation starts no Agent,
+     * releases no retained identity, and accepts no caller cancellation signal.
+     */
+    async requireActiveRecovery(runId, reason) {
+        const parsedRunId = runIdSchema.parse(runId);
+        const parsedReason = z
+            .enum(['composition-unavailable', 'session-unavailable', 'workspace-unavailable', 'worktree-mismatch'])
+            .parse(reason);
+        let recovery;
+        await this.dependencies.table().update(STATE_KEY, (current) => {
+            const index = current.runs.findIndex((run) => run.runId === parsedRunId);
+            const run = current.runs[index];
+            if (!isPausedActiveRun(run))
+                throw new Error(`run "${parsedRunId}" is no longer an allocated pause`);
+            if (run.execution.recovery?.reason === parsedReason) {
+                recovery = structuredClone(run);
+                return current;
+            }
+            if (run.execution.recovery !== undefined) {
+                throw new Error(`run "${parsedRunId}" already requires ${run.execution.recovery.reason} recovery`);
+            }
+            recovery = {
+                ...structuredClone(run),
+                execution: {
+                    ...structuredClone(run.execution),
+                    recovery: { kind: 'required', reason: parsedReason, interruptedAt: new Date().toISOString() },
+                },
+            };
+            const next = structuredClone(current);
+            next.runs[index] = recovery;
+            next.revision += 1;
+            return stateSchema.parse(next);
+        });
+        if (recovery === undefined)
+            throw new Error(`run "${parsedRunId}" recovery requirement was not recorded`);
+        return structuredClone(recovery);
+    }
+}
+//# sourceMappingURL=resume-control.js.map

package/lib/admission/resume-control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume-control.js","sourceRoot":"","sources":["../../src/admission/resume-control.ts"],"names":[],"mappings":"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"}

package/lib/admission/run-fence.d.ts

@@ -0,0 +1,11 @@
+import type { RunId } from './model.js';
+/** Serialize lifecycle and maintenance work for one run and fence stale observations with a process-local generation. */
+export declare class RunOperationFence {
+    private readonly entries;
+    generation(runId: RunId): number;
+    exclusive<T>(runId: RunId, operation: () => Promise<T>): Promise<T>;
+    mutate<T>(runId: RunId, operation: () => Promise<T>): Promise<T>;
+    mutateMany<T>(runIds: readonly RunId[], operation: () => Promise<T>): Promise<T>;
+    private lock;
+    private entry;
+}

package/lib/admission/run-fence.js

@@ -0,0 +1,49 @@
+/** Serialize lifecycle and maintenance work for one run and fence stale observations with a process-local generation. */
+export class RunOperationFence {
+    entries = new Map();
+    generation(runId) {
+        return this.entry(runId).generation;
+    }
+    exclusive(runId, operation) {
+        return this.lock(runId, operation, false);
+    }
+    mutate(runId, operation) {
+        return this.lock(runId, operation, true);
+    }
+    async mutateMany(runIds, operation) {
+        const ordered = [...new Set(runIds)].sort();
+        const lockAt = async (index) => {
+            const runId = ordered[index];
+            return runId === undefined ? await operation() : await this.lock(runId, () => lockAt(index + 1), true);
+        };
+        return await lockAt(0);
+    }
+    async lock(runId, operation, mutate) {
+        const entry = this.entry(runId);
+        const previous = entry.tail;
+        let release;
+        const current = new Promise((resolve) => {
+            release = resolve;
+        });
+        entry.tail = previous.catch(() => undefined).then(() => current);
+        await previous.catch(() => undefined);
+        try {
+            const result = await operation();
+            if (mutate)
+                entry.generation += 1;
+            return result;
+        }
+        finally {
+            release?.();
+        }
+    }
+    entry(runId) {
+        let entry = this.entries.get(runId);
+        if (entry === undefined) {
+            entry = { generation: 0, tail: Promise.resolve() };
+            this.entries.set(runId, entry);
+        }
+        return entry;
+    }
+}
+//# sourceMappingURL=run-fence.js.map

package/lib/admission/run-fence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-fence.js","sourceRoot":"","sources":["../../src/admission/run-fence.ts"],"names":[],"mappings":"AAOA,yHAAyH;AACzH,MAAM,OAAO,iBAAiB;IACX,OAAO,GAAG,IAAI,GAAG,EAAwB,CAAA;IAE1D,UAAU,CAAC,KAAY;QACrB,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,UAAU,CAAA;IACrC,CAAC;IAED,SAAS,CAAI,KAAY,EAAE,SAA2B;QACpD,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,CAAA;IAC3C,CAAC;IAED,MAAM,CAAI,KAAY,EAAE,SAA2B;QACjD,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,CAAA;IAC1C,CAAC;IAED,KAAK,CAAC,UAAU,CAAI,MAAwB,EAAE,SAA2B;QACvE,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QAC3C,MAAM,MAAM,GAAG,KAAK,EAAE,KAAa,EAAc,EAAE;YACjD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;YAC5B,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,SAAS,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAA;QACxG,CAAC,CAAA;QACD,OAAO,MAAM,MAAM,CAAC,CAAC,CAAC,CAAA;IACxB,CAAC;IAEO,KAAK,CAAC,IAAI,CAAI,KAAY,EAAE,SAA2B,EAAE,MAAe;QAC9E,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QAC/B,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAA;QAC3B,IAAI,OAAiC,CAAA;QACrC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAC5C,OAAO,GAAG,OAAO,CAAA;QACnB,CAAC,CAAC,CAAA;QACF,KAAK,CAAC,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,CAAA;QAChE,MAAM,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;QACrC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,SAAS,EAAE,CAAA;YAChC,IAAI,MAAM;gBAAE,KAAK,CAAC,UAAU,IAAI,CAAC,CAAA;YACjC,OAAO,MAAM,CAAA;QACf,CAAC;gBAAS,CAAC;YACT,OAAO,EAAE,EAAE,CAAA;QACb,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,KAAY;QACxB,IAAI,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QACnC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,KAAK,GAAG,EAAE,UAAU,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,EAAE,CAAA;YAClD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;QAChC,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC;CACF"}

package/lib/admission/service.d.ts

@@ -0,0 +1,130 @@
+import { type Context, Service } from '@deepseek-ai/cordis';
+import type { PullRequestReceipt } from '../code-host.js';
+import type { NotificationReceipt } from '../notification.js';
+import type { TrackerIngressRequest, TrackerOutboundReceipt } from '../tracker.js';
+import { type PreparedAgentComposition } from './composition-claim.js';
+import type { ActiveRecoveryReason, ActiveResumeAuthorization, AdmissionSnapshot, CancelledRun, DeliveryRecord, ExecutionOutcome, GitExecutionSnapshot, ImplementingRun, PausedActiveRun, PausedQueuedRun, PausingRun, QueuedRun, ReconcileRequest, ReconcileResult, RunId, RunUsageSettlement, SchedulerDisableResult, SchedulerMode, TerminalRun } from './model.js';
+import { RunOperationFence } from './run-fence.js';
+import { type OperatorCommandKind, type OperatorCommandRecord } from './state.js';
+export interface OperatorCommandRequest {
+    readonly requestId: string;
+    readonly kind: OperatorCommandKind;
+    readonly runId?: string | undefined;
+    readonly deliveryId?: string | undefined;
+    readonly previewId?: string | undefined;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        admission: Admission;
+    }
+}
+export declare class Admission extends Service {
+    static readonly inject: string[];
+    private state?;
+    readonly runOperations: RunOperationFence;
+    constructor(ctx: Context);
+    [Service.init](): AsyncGenerator<() => Promise<void>, void, void>;
+    /**
+     * Return a detached view with active work first, then queued work in dispatch order, then retained inactive runs.
+     * Throws if the service has not finished initialization; it performs no I/O and has no cancellation point.
+     */
+    snapshot(): AdmissionSnapshot;
+    /** Atomically retain one accepted operator command before its effect starts, deduplicated by caller request id. */
+    acceptOperatorCommand(request: OperatorCommandRequest): Promise<{
+        readonly command: OperatorCommandRecord;
+        readonly created: boolean;
+    }>;
+    /** Persist a command transition in the same authoritative aggregate as the run/scheduler effect. */
+    updateOperatorCommand(requestId: string, patch: Pick<OperatorCommandRecord, 'status'> & Partial<Pick<OperatorCommandRecord, 'finishedAt' | 'message' | 'revision'>>): Promise<OperatorCommandRecord>;
+    operatorCommand(requestId: string): OperatorCommandRecord | undefined;
+    operatorCommands(): OperatorCommandRecord[];
+    /** Explain whether durable runs or outbound intents still depend on one tracker configuration. */
+    trackerSwitchBlocker(providerId: string): string | undefined;
+    /** Explain whether admitted runs still depend on one code-host provider selection. */
+    codeHostSwitchBlocker(providerId: string): string | undefined;
+    /** Prevent one provider id from being rebound while queued work or durable run history still names that binding. */
+    codeHostBindingSwitchBlocker(providerId: string): string | undefined;
+    /** Explain whether unallocated admitted work would be redirected by an execution-routing Settings change. */
+    executionRoutingSwitchBlocker(): string | undefined;
+    /** Atomically change the admission/dequeue gate; rejects invalid modes or unsafe disable and has no cancellation point. */
+    setSchedulerMode(mode: SchedulerMode): Promise<AdmissionSnapshot>;
+    /**
+     * Persist a draining/disabled transition and pause requests for active work.
+     * Rejects storage/schema failures; returned run ids still require the dispatcher to reach quiescence.
+     */
+    requestSchedulerDisable(): Promise<SchedulerDisableResult>;
+    /** Persist service-withdrawal pause requests for active runs; it does not itself cancel agents or accept cancellation. */
+    requestServiceWithdrawalPause(): Promise<RunId[]>;
+    /** Request an operator pause for one active run; rejects missing/terminal runs and performs no agent cancellation itself. */
+    requestRunPause(runId: RunId): Promise<PausingRun | PausedActiveRun>;
+    /**
+     * Commit a quiescent active-run pause after the dispatcher has observed Git and usage.
+     * Rejects stale/non-pausing runs, invalid facts, or durable-write failures; no caller cancellation is accepted.
+     */
+    checkpointPaused(runId: RunId, git: GitExecutionSnapshot, usage: RunUsageSettlement): Promise<PausedActiveRun>;
+    /** Persist an operator hold for queued work before resources are allocated; rejects non-queued runs. */
+    holdQueued(runId: RunId): Promise<PausedQueuedRun>;
+    /** End one quiescent queued, paused, or blocked run without authorizing tracker or resource side effects. */
+    cancelRun(runId: RunId, requestId: string): Promise<CancelledRun>;
+    /** Revalidate and return operator-held queued work to dispatch order; rejects changed eligibility or disabled admission. */
+    resumeRun(runId: RunId): Promise<QueuedRun>;
+    /**
+     * Revalidate retained issue, Session/worktree Git facts, scheduler and budget before active continuation.
+     * Rejects unauthorized/stale recovery and durable failures; it allocates no external resource and has no cancellation.
+     */
+    resumeActiveRun(runId: RunId, observedGit: GitExecutionSnapshot, authorization: ActiveResumeAuthorization): Promise<ImplementingRun>;
+    /** Persist a bounded explicit-recovery requirement for an allocated paused run; rejects incompatible lifecycle state. */
+    requireActiveRecovery(runId: RunId, reason: ActiveRecoveryReason): Promise<PausedActiveRun>;
+    /** Atomically claim and reserve the next eligible queued run, or return undefined; rejects invalid settings/state. */
+    claimNext(preparedAgent: PreparedAgentComposition): Promise<ImplementingRun | undefined>;
+    /** Persist verified worktree ownership facts for the claimed run; rejects stale identity, invalid Git facts or writes. */
+    recordWorktree(runId: RunId, git: GitExecutionSnapshot): Promise<ImplementingRun | PausingRun>;
+    /** Atomically settle one implementing run and its usage reservation; rejects mismatched outcomes or stale state. */
+    settle(runId: RunId, outcome: ExecutionOutcome, usage: RunUsageSettlement): Promise<TerminalRun>;
+    /** Claim one persisted publication intent for the sole Host publisher; no external side effect occurs. */
+    claimPublication(runId: RunId): Promise<{
+        run: TerminalRun;
+        owner: string;
+    }>;
+    /** Fail if a publication worker no longer owns the current durable intent; this check performs no I/O. */
+    assertPublicationOwner(runId: RunId, owner: string): void;
+    /** Persist a reconciled remote branch receipt while retaining publication ownership. */
+    recordPublicationBranch(runId: RunId, owner: string, remoteHead: string): Promise<TerminalRun>;
+    /** Commit the confirmed ready PR and completed lifecycle event atomically. */
+    completePublication(runId: RunId, owner: string, receipt: PullRequestReceipt): Promise<TerminalRun>;
+    /** Persist a sanitized permanent, retryable, or ambiguous publication failure without changing verified work. */
+    failPublication(runId: RunId, owner: string, error: unknown, status: 'uncertain' | 'retryable-failure' | 'failed', retryAfterMs?: number): Promise<TerminalRun>;
+    claimDelivery(deliveryId: string): Promise<{
+        runId: RunId;
+        delivery: DeliveryRecord;
+        owner: string;
+    }>;
+    assertDeliveryOwner(runId: RunId, deliveryId: string, owner: string): void;
+    succeedDelivery(runId: RunId, deliveryId: string, owner: string, receipt: TrackerOutboundReceipt | NotificationReceipt): Promise<DeliveryRecord>;
+    failDelivery(runId: RunId, deliveryId: string, owner: string, error: unknown, status: 'uncertain' | 'retryable-failure' | 'permanent-failure', retryAfterMs?: number): Promise<DeliveryRecord>;
+    retryDelivery(deliveryId: string): Promise<DeliveryRecord>;
+    /** Replace one settled failed tracker projection after its provider mapping has been corrected. */
+    repairTrackerProjection(deliveryId: string): Promise<DeliveryRecord>;
+    /**
+     * Read the selected tracker provider and atomically admit every currently eligible issue.
+     * When the scheduler is not enabled, returns an unchanged detached snapshot without reading the provider or retaining
+     * an ingress receipt. Provider, validation, capacity, or durable-write failures reject without advancing admission
+     * state. Provider withdrawal cancels its owned reads; a caller signal fences mutation after cancellation.
+     */
+    reconcile(request: ReconcileRequest): Promise<ReconcileResult>;
+    /** Authenticate raw tracker ingress and keep that provider generation alive through its durable admission commit. */
+    reconcileIngress(request: TrackerIngressRequest, signal?: AbortSignal): Promise<ReconcileResult>;
+    private pauseControl;
+    private cancellationControl;
+    private resumeControl;
+    private executionControl;
+    private publicationControl;
+    private deliveryControl;
+    private deliveryRunId;
+    private dependencies;
+    private currentSettings;
+    private currentTable;
+    private currentState;
+    private markInterruptedRunsForRecovery;
+}
+export default Admission;