@canhta/dsh-autopilot 0.1.0-alpha.1

package/lib/admission/model.d.ts

@@ -0,0 +1,296 @@
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { CodeHostBindingId, CodeHostProviderId, CodeHostRepositoryId, PullRequestReceipt } from '../code-host.js';
+import type { NotificationEvent } from '../notification.js';
+import type { ReadinessGeneration, TrackerBindingId, TrackerCommentId, TrackerIssueId, TrackerProviderId } from '../tracker.js';
+declare const runIdBrand: unique symbol;
+export type RunId = string & {
+    readonly [runIdBrand]: true;
+};
+export type AdmissionSource = 'manual' | 'scheduled' | 'startup' | 'webhook';
+export type SchedulerMode = 'enabled' | 'draining' | 'disabled';
+export interface SchedulerSnapshot {
+    readonly mode: SchedulerMode;
+    readonly changedAt: string;
+}
+export interface ReconcileRequest {
+    source: AdmissionSource;
+    deliveryId?: string;
+    signal?: AbortSignal;
+}
+/** Bounded core failure proving that tracker ingress was not durably accepted. */
+export declare class AdmissionIngressError extends Error {
+    readonly code: 'queue-capacity' | 'not-accepting';
+    /** Construct a caller-safe ingress failure; this operation has no side effects or cancellation point. */
+    constructor(code: 'queue-capacity' | 'not-accepting');
+}
+export type AdmissionRejectionReason = 'missing-brief' | 'ambiguous-brief' | 'invalid-brief' | 'brief-too-large' | 'summary-too-large' | 'not-ready' | 'dependencies-incomplete' | 'dependency-unknown' | 'human-readiness-required';
+export type AdmissionDecision = {
+    displayKey: string;
+    outcome: 'queued' | 'duplicate';
+} | {
+    displayKey: string;
+    outcome: 'deferred';
+    reason: 'queue-capacity';
+} | {
+    displayKey: string;
+    outcome: 'rejected';
+    reason: AdmissionRejectionReason;
+};
+export interface AgentBriefSnapshot {
+    readonly commentId: TrackerCommentId;
+    readonly updatedAt: string;
+    readonly digest: string;
+    readonly content: string;
+}
+export interface QueuedRun {
+    readonly runId: RunId;
+    readonly providerId: TrackerProviderId;
+    readonly bindingId: TrackerBindingId;
+    readonly issueId: TrackerIssueId;
+    readonly displayKey: string;
+    readonly summary: string;
+    readonly priorityRank: number;
+    readonly readinessGeneration: ReadinessGeneration;
+    readonly brief: AgentBriefSnapshot;
+    readonly deliveries: DeliveryRecord[];
+    readonly state: 'queued';
+    readonly queueClass: 'new' | 'resumption';
+    readonly queuedAt: string;
+    readonly queueSequence: number;
+}
+export interface PausedQueuedRun extends Omit<QueuedRun, 'state' | 'queueClass'> {
+    readonly state: 'paused';
+    readonly queueClass: 'resumption';
+    readonly pause: {
+        readonly kind: 'queued';
+        readonly reason: 'operator';
+        readonly operatorHold: true;
+        readonly continuationTarget: 'implementing';
+        readonly pausedAt: string;
+    };
+}
+export type ActivePauseReason = 'operator' | 'scheduler' | 'service-withdrawal';
+export type ActiveResumeAuthorization = 'operator' | 'scheduler';
+export interface ActivePauseSnapshot {
+    readonly kind: 'active';
+    readonly reason: ActivePauseReason;
+    readonly operatorHold: boolean;
+    readonly continuationTarget: 'implementing';
+    readonly requestedAt: string;
+    readonly interruptedOperation: 'agent-turn';
+}
+/** Exact DSH composition captured for a run before it leaves the queue. */
+export interface AgentExecutionComposition {
+    readonly presetId: string;
+    readonly presetFingerprint: string;
+    readonly permission: {
+        readonly presetId: string;
+        readonly sandbox: 'read-only' | 'workspace-write' | 'danger-full-access';
+        readonly approval: 'never';
+    };
+    readonly model: {
+        readonly provider: string;
+        readonly model: string;
+        readonly reasoningEffort?: string | undefined;
+    };
+}
+export interface RunExecutionSnapshot {
+    readonly attempt: number;
+    readonly sessionId: SessionId;
+    readonly targetRepository: string;
+    readonly baseBranch: string;
+    readonly worktreePath: string;
+    readonly branch: string;
+    /** Absent only on durable records created before native DSH composition was captured. */
+    readonly agent?: AgentExecutionComposition | undefined;
+    readonly codeHost: {
+        readonly providerId: CodeHostProviderId;
+        readonly bindingId: CodeHostBindingId;
+        readonly repositoryId: CodeHostRepositoryId;
+        readonly repository: string;
+        readonly allowWorkflowChanges: boolean;
+    };
+    readonly startedAt: string;
+    readonly git?: GitExecutionSnapshot | undefined;
+    readonly recovery?: RunRecoverySnapshot | undefined;
+}
+export interface GitExecutionSnapshot {
+    readonly baseHead: string;
+    readonly head: string;
+    readonly status: string;
+}
+export interface RunRecoverySnapshot {
+    readonly kind: 'required';
+    readonly reason: 'host-restart' | 'composition-unavailable' | 'session-unavailable' | 'workspace-unavailable' | 'worktree-mismatch';
+    readonly interruptedAt: string;
+}
+export type ActiveRecoveryReason = Exclude<RunRecoverySnapshot['reason'], 'host-restart'>;
+export interface RunBudgetSnapshot {
+    readonly capTokens: number;
+    readonly allowanceTokens: number;
+    readonly reservedTokens: number;
+    readonly settledTokens: number;
+    readonly usageUncertain: boolean;
+    readonly usageUncertaintyReason?: string | undefined;
+}
+export interface ImplementingRun extends Omit<QueuedRun, 'state'> {
+    readonly state: 'implementing';
+    readonly execution: RunExecutionSnapshot;
+    readonly budget: RunBudgetSnapshot;
+}
+export interface PausingRun extends Omit<ImplementingRun, 'state'> {
+    readonly state: 'pausing';
+    readonly pause: ActivePauseSnapshot;
+}
+export interface PausedActiveRun extends Omit<ImplementingRun, 'state'> {
+    readonly state: 'paused';
+    readonly pause: ActivePauseSnapshot & {
+        readonly pausedAt: string;
+        readonly lastCompletedPhase: 'agent-quiescent';
+    };
+}
+export type ExecutionOutcome = {
+    readonly kind: 'verified';
+    readonly summary: string;
+    readonly evidence: string[];
+    readonly reportedGit: Pick<GitExecutionSnapshot, 'head' | 'status'>;
+    readonly verification: VerificationResult[];
+    readonly suggestedPullRequest: SuggestedPullRequest;
+} | {
+    readonly kind: 'blocked';
+    readonly summary: string;
+    readonly evidence: string[];
+} | {
+    readonly kind: 'failed';
+    readonly summary: string;
+    readonly evidence: string[];
+};
+export interface TerminalRun extends Omit<QueuedRun, 'state'> {
+    readonly state: 'publishing' | 'completed' | 'blocked' | 'failed';
+    readonly execution: RunExecutionSnapshot;
+    readonly budget: RunBudgetSnapshot;
+    readonly outcome: ExecutionOutcome;
+    readonly completedAt: string;
+    readonly publication?: PublicationIntent | undefined;
+}
+export type RunCancellationSource = 'queued' | 'paused-queued' | 'paused-active' | 'blocked';
+export interface RunCancellationSnapshot<Source extends RunCancellationSource = RunCancellationSource> {
+    readonly requestId: string;
+    readonly cancelledAt: string;
+    readonly from: Source;
+}
+export interface CancelledQueuedRun extends Omit<QueuedRun, 'state'> {
+    readonly state: 'cancelled';
+    readonly cancellation: RunCancellationSnapshot<'queued'>;
+}
+export interface CancelledPausedQueuedRun extends Omit<PausedQueuedRun, 'state'> {
+    readonly state: 'cancelled';
+    readonly cancellation: RunCancellationSnapshot<'paused-queued'>;
+}
+export interface CancelledPausedActiveRun extends Omit<PausedActiveRun, 'state'> {
+    readonly state: 'cancelled';
+    readonly cancellation: RunCancellationSnapshot<'paused-active'>;
+}
+export interface CancelledBlockedRun extends Omit<TerminalRun, 'state' | 'outcome'> {
+    readonly state: 'cancelled';
+    readonly outcome: Extract<ExecutionOutcome, {
+        kind: 'blocked';
+    }>;
+    readonly cancellation: RunCancellationSnapshot<'blocked'>;
+}
+export type CancelledRun = CancelledQueuedRun | CancelledPausedQueuedRun | CancelledPausedActiveRun | CancelledBlockedRun;
+export type AutopilotRun = QueuedRun | PausedQueuedRun | ImplementingRun | PausingRun | PausedActiveRun | TerminalRun | CancelledRun;
+export type RunUsageSettlement = {
+    readonly kind: 'known';
+    readonly tokens: number;
+} | {
+    readonly kind: 'uncertain';
+    readonly reason: string;
+};
+export interface AdmissionBudgetSnapshot {
+    readonly reservedTokens: number;
+    readonly settledTokens: number;
+    readonly usageUncertain: boolean;
+}
+export interface AdmissionSnapshot {
+    revision: number;
+    runs: readonly AutopilotRun[];
+    acceptedIngress: readonly string[];
+    budget: AdmissionBudgetSnapshot;
+    scheduler: SchedulerSnapshot;
+}
+export interface VerificationResult {
+    readonly command: string;
+    readonly status: 'passed' | 'failed' | 'skipped';
+    readonly summary: string;
+    readonly reason?: string | undefined;
+}
+export interface SuggestedPullRequest {
+    readonly title: string;
+    readonly body: string;
+}
+export interface PublicationIntent {
+    readonly id: string;
+    readonly revision: number;
+    readonly providerId: CodeHostProviderId;
+    readonly bindingId: CodeHostBindingId;
+    readonly repositoryId: CodeHostRepositoryId;
+    readonly repository: string;
+    readonly baseBranch: string;
+    readonly headBranch: string;
+    readonly baseHead: string;
+    readonly localHead: string;
+    readonly marker: string;
+    readonly title: string;
+    readonly body: string;
+    readonly status: 'pending' | 'in-flight' | 'uncertain' | 'retryable-failure' | 'exhausted' | 'failed' | 'succeeded';
+    readonly attempts: number;
+    readonly owner?: string | undefined;
+    readonly nextRetryAt?: string | undefined;
+    readonly exhaustedFrom?: 'uncertain' | 'retryable-failure' | undefined;
+    readonly lastError?: string | undefined;
+    readonly branchReceipt?: {
+        readonly remoteHead: string;
+        readonly receivedAt: string;
+    } | undefined;
+    readonly receipt?: PullRequestReceipt | undefined;
+}
+export interface DeliveryRecordBase {
+    readonly id: string;
+    readonly eventId: string;
+    readonly revision: number;
+    readonly status: 'pending' | 'in-flight' | 'uncertain' | 'retryable-failure' | 'exhausted' | 'permanent-failure' | 'succeeded' | 'retired';
+    readonly attempts: number;
+    readonly owner?: string | undefined;
+    readonly nextRetryAt?: string | undefined;
+    readonly exhaustedFrom?: 'uncertain' | 'retryable-failure' | undefined;
+    readonly lastError?: string | undefined;
+    readonly receiptId?: string | undefined;
+    readonly receivedAt?: string | undefined;
+}
+export type DeliveryRecord = (DeliveryRecordBase & {
+    readonly kind: 'tracker-report';
+    readonly providerId: TrackerProviderId;
+    readonly payload: Extract<import('../tracker.js').TrackerOutboundDelivery, {
+        kind: 'report';
+    }>;
+}) | (DeliveryRecordBase & {
+    readonly kind: 'tracker-projection';
+    readonly providerId: TrackerProviderId;
+    readonly payload: Extract<import('../tracker.js').TrackerOutboundDelivery, {
+        kind: 'projection';
+    }>;
+}) | (DeliveryRecordBase & {
+    readonly kind: 'notification';
+    readonly providerId: import('../notification.js').NotificationProviderId;
+    readonly destinationId: import('../notification.js').NotificationDestinationId;
+    readonly payload: NotificationEvent;
+});
+export interface ReconcileResult extends AdmissionSnapshot {
+    decisions: readonly AdmissionDecision[];
+}
+export interface SchedulerDisableResult {
+    readonly snapshot: AdmissionSnapshot;
+    readonly pausingRunIds: readonly RunId[];
+}
+export {};

package/lib/admission/model.js

@@ -0,0 +1,13 @@
+/** Bounded core failure proving that tracker ingress was not durably accepted. */
+export class AdmissionIngressError extends Error {
+    code;
+    /** Construct a caller-safe ingress failure; this operation has no side effects or cancellation point. */
+    constructor(code) {
+        super(code === 'queue-capacity'
+            ? 'Admission queue capacity deferred eligible tracker work.'
+            : 'Admission is not accepting tracker ingress.');
+        this.code = code;
+        this.name = 'AdmissionIngressError';
+    }
+}
+//# sourceMappingURL=model.js.map

package/lib/admission/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../src/admission/model.ts"],"names":[],"mappings":"AA4BA,kFAAkF;AAClF,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAEzB,IAAI;IADzB,yGAAyG;IACzG,YAAqB,IAAwC;QAC3D,KAAK,CACH,IAAI,KAAK,gBAAgB;YACvB,CAAC,CAAC,0DAA0D;YAC5D,CAAC,CAAC,6CAA6C,CAClD,CAAA;oBALkB,IAAI;QAMvB,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAA;IACrC,CAAC;CACF"}

package/lib/admission/pause-control.d.ts

@@ -0,0 +1,44 @@
+import type { AdmissionSnapshot, GitExecutionSnapshot, PausedActiveRun, PausedQueuedRun, PausingRun, RunId, RunUsageSettlement, SchedulerDisableResult, SchedulerMode } from './model.js';
+import type { AdmissionDependencies } from './ports.js';
+export declare class PauseControl {
+    private readonly dependencies;
+    constructor(dependencies: AdmissionDependencies);
+    /**
+     * Atomically persist the scheduler admission/claim gate and return a detached aggregate snapshot. Draining permits
+     * implementing runs to settle; disabling rejects while any run is implementing. Invalid input or durable-write
+     * failure leaves the previous mode unchanged. The command accepts no caller cancellation signal.
+     */
+    setSchedulerMode(mode: SchedulerMode): Promise<AdmissionSnapshot>;
+    /**
+     * Atomically disable admission/dequeue and move every implementing run to `pausing`. The returned run ids identify
+     * live executions whose owner must request cancellation and checkpoint only after quiescence. Existing pause requests
+     * retain their operator-hold intent. Durable-write failure leaves both scheduler and runs unchanged. This operation
+     * requests lifecycle work but does not itself own or cancel an Agent.
+     */
+    requestSchedulerDisable(): Promise<SchedulerDisableResult>;
+    /**
+     * Atomically move implementing runs to `pausing` before the dispatcher loses a required execution service. Scheduler
+     * mode and existing operator/scheduler pause intent are retained. The returned ids identify every pausing execution
+     * whose retiring dispatcher owner must cancel and checkpoint before its disposer completes.
+     */
+    requestServiceWithdrawalPause(): Promise<RunId[]>;
+    /**
+     * Atomically request an operator pause for one allocated run. An implementing run becomes `pausing`; an existing
+     * scheduler pause is upgraded to an operator hold without losing its original checkpoint facts. Queued runs use
+     * `holdQueued` instead. The request owns no Agent cancellation and accepts no caller cancellation signal.
+     */
+    requestRunPause(runId: RunId): Promise<PausingRun | PausedActiveRun>;
+    /**
+     * Commit a pause only after the execution owner has proven its root idle, flushed the Session, and inspected Git.
+     * Known usage releases the reservation and advances settled usage. Missing, malformed, or excessive usage retains the
+     * reservation and marks deployment usage uncertain for later reconciliation. A lost pause race or write failure leaves
+     * the `pausing` checkpoint unchanged. The method accepts no caller cancellation signal.
+     */
+    checkpointPaused(runId: RunId, git: GitExecutionSnapshot, usage: RunUsageSettlement): Promise<PausedActiveRun>;
+    /**
+     * Atomically place one queued run on a durable operator hold before Session or worktree allocation.
+     * The run must exist and still be queued. Invalid input, a different lifecycle state, or durable-write failure leaves
+     * the run unchanged. The returned paused run is detached; this operation has no external effects or cancellation point.
+     */
+    holdQueued(runId: RunId): Promise<PausedQueuedRun>;
+}

package/lib/admission/pause-control.js

@@ -0,0 +1,220 @@
+import { STATE_KEY } from './constants.js';
+import { appendLifecycleDeliveries } from './deliveries.js';
+import { activePause, isPausedActiveRun, usageUncertaintyReason, validUsageSettlement } from './policy.js';
+import { executionSchema, runIdSchema, schedulerModeSchema, stateSchema } from './state.js';
+import { snapshotOf } from './state-domain.js';
+export class PauseControl {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    /**
+     * Atomically persist the scheduler admission/claim gate and return a detached aggregate snapshot. Draining permits
+     * implementing runs to settle; disabling rejects while any run is implementing. Invalid input or durable-write
+     * failure leaves the previous mode unchanged. The command accepts no caller cancellation signal.
+     */
+    async setSchedulerMode(mode) {
+        const parsedMode = schedulerModeSchema.parse(mode);
+        const committed = await this.dependencies.table().update(STATE_KEY, (current) => {
+            if (parsedMode === 'disabled' && current.runs.some((run) => run.state === 'implementing')) {
+                throw new Error('scheduler cannot be disabled while an implementing run exists');
+            }
+            if (parsedMode === 'enabled' && current.runs.some((run) => run.state === 'pausing')) {
+                throw new Error('scheduler cannot be enabled while a run is still pausing');
+            }
+            if (current.scheduler.mode === parsedMode)
+                return current;
+            const next = structuredClone(current);
+            next.scheduler = { mode: parsedMode, changedAt: new Date().toISOString() };
+            next.revision += 1;
+            return stateSchema.parse(next);
+        });
+        return snapshotOf(committed);
+    }
+    /**
+     * Atomically disable admission/dequeue and move every implementing run to `pausing`. The returned run ids identify
+     * live executions whose owner must request cancellation and checkpoint only after quiescence. Existing pause requests
+     * retain their operator-hold intent. Durable-write failure leaves both scheduler and runs unchanged. This operation
+     * requests lifecycle work but does not itself own or cancel an Agent.
+     */
+    async requestSchedulerDisable() {
+        let pausingRunIds = [];
+        const committed = await this.dependencies.table().update(STATE_KEY, (current) => {
+            const requestedAt = new Date().toISOString();
+            const next = structuredClone(current);
+            next.scheduler = { mode: 'disabled', changedAt: requestedAt };
+            next.runs = next.runs.map((run) => run.state === 'implementing'
+                ? {
+                    ...run,
+                    state: 'pausing',
+                    pause: activePause('scheduler', requestedAt),
+                }
+                : run);
+            pausingRunIds = next.runs.filter((run) => run.state === 'pausing').map((run) => run.runId);
+            if (current.scheduler.mode === 'disabled' && !current.runs.some((run) => run.state === 'implementing')) {
+                return current;
+            }
+            next.revision += 1;
+            return stateSchema.parse(next);
+        });
+        return { snapshot: snapshotOf(committed), pausingRunIds: [...pausingRunIds] };
+    }
+    /**
+     * Atomically move implementing runs to `pausing` before the dispatcher loses a required execution service. Scheduler
+     * mode and existing operator/scheduler pause intent are retained. The returned ids identify every pausing execution
+     * whose retiring dispatcher owner must cancel and checkpoint before its disposer completes.
+     */
+    async requestServiceWithdrawalPause() {
+        let pausingRunIds = [];
+        await this.dependencies.table().update(STATE_KEY, (current) => {
+            const requestedAt = new Date().toISOString();
+            const next = structuredClone(current);
+            next.runs = next.runs.map((run) => run.state === 'implementing'
+                ? {
+                    ...run,
+                    state: 'pausing',
+                    pause: activePause('service-withdrawal', requestedAt),
+                }
+                : run);
+            pausingRunIds = next.runs.filter((run) => run.state === 'pausing').map((run) => run.runId);
+            if (!current.runs.some((run) => run.state === 'implementing'))
+                return current;
+            next.revision += 1;
+            return stateSchema.parse(next);
+        });
+        return [...pausingRunIds];
+    }
+    /**
+     * Atomically request an operator pause for one allocated run. An implementing run becomes `pausing`; an existing
+     * scheduler pause is upgraded to an operator hold without losing its original checkpoint facts. Queued runs use
+     * `holdQueued` instead. The request owns no Agent cancellation and accepts no caller cancellation signal.
+     */
+    async requestRunPause(runId) {
+        const parsedRunId = runIdSchema.parse(runId);
+        let requested;
+        await this.dependencies.table().update(STATE_KEY, (current) => {
+            const index = current.runs.findIndex((run) => run.runId === parsedRunId);
+            const run = current.runs[index];
+            if (run === undefined)
+                throw new Error(`run "${parsedRunId}" does not exist`);
+            if (isPausedActiveRun(run) && run.pause.operatorHold) {
+                requested = structuredClone(run);
+                return current;
+            }
+            const next = structuredClone(current);
+            let nextRun;
+            if (run.state === 'implementing') {
+                nextRun = { ...run, state: 'pausing', pause: activePause('operator', new Date().toISOString()) };
+            }
+            else if (run.state === 'pausing') {
+                nextRun = {
+                    ...run,
+                    pause: { ...run.pause, reason: 'operator', operatorHold: true },
+                };
+            }
+            else if (isPausedActiveRun(run)) {
+                nextRun = {
+                    ...run,
+                    pause: { ...run.pause, reason: 'operator', operatorHold: true },
+                };
+            }
+            else {
+                throw new Error(`run "${parsedRunId}" is not an allocated active or paused run`);
+            }
+            requested = nextRun;
+            next.runs[index] = nextRun;
+            next.revision += 1;
+            return stateSchema.parse(next);
+        });
+        if (requested === undefined)
+            throw new Error(`run "${parsedRunId}" pause was not requested`);
+        return structuredClone(requested);
+    }
+    /**
+     * Commit a pause only after the execution owner has proven its root idle, flushed the Session, and inspected Git.
+     * Known usage releases the reservation and advances settled usage. Missing, malformed, or excessive usage retains the
+     * reservation and marks deployment usage uncertain for later reconciliation. A lost pause race or write failure leaves
+     * the `pausing` checkpoint unchanged. The method accepts no caller cancellation signal.
+     */
+    async checkpointPaused(runId, git, usage) {
+        const parsedRunId = runIdSchema.parse(runId);
+        const parsedGit = executionSchema.shape.git.unwrap().parse(git);
+        let paused;
+        await this.dependencies.table().update(STATE_KEY, (current) => {
+            const next = structuredClone(current);
+            const index = next.runs.findIndex((run) => run.runId === parsedRunId);
+            const run = next.runs[index];
+            if (run?.state !== 'pausing')
+                throw new Error(`run "${parsedRunId}" is not pausing`);
+            const usageKnown = validUsageSettlement(run, usage);
+            const pausedAt = new Date().toISOString();
+            const pausedWithoutDeliveries = {
+                ...run,
+                state: 'paused',
+                execution: { ...run.execution, git: parsedGit },
+                budget: {
+                    ...run.budget,
+                    reservedTokens: usageKnown ? 0 : run.budget.reservedTokens,
+                    settledTokens: usageKnown ? run.budget.settledTokens + usage.tokens : run.budget.settledTokens,
+                    usageUncertain: !usageKnown,
+                    ...(usageKnown ? {} : { usageUncertaintyReason: usageUncertaintyReason(run, usage) }),
+                },
+                pause: { ...run.pause, pausedAt, lastCompletedPhase: 'agent-quiescent' },
+            };
+            paused = {
+                ...pausedWithoutDeliveries,
+                deliveries: appendLifecycleDeliveries(pausedWithoutDeliveries, this.dependencies.settings(), 'paused', current.revision + 1, pausedAt),
+            };
+            next.runs[index] = paused;
+            if (usageKnown) {
+                next.budget.reservedTokens -= run.budget.reservedTokens;
+                next.budget.settledTokens += usage.tokens;
+            }
+            else {
+                next.budget.usageUncertain = true;
+            }
+            next.revision += 1;
+            return stateSchema.parse(next);
+        });
+        if (paused === undefined)
+            throw new Error(`run "${parsedRunId}" pause checkpoint was not recorded`);
+        return structuredClone(paused);
+    }
+    /**
+     * Atomically place one queued run on a durable operator hold before Session or worktree allocation.
+     * The run must exist and still be queued. Invalid input, a different lifecycle state, or durable-write failure leaves
+     * the run unchanged. The returned paused run is detached; this operation has no external effects or cancellation point.
+     */
+    async holdQueued(runId) {
+        const parsedRunId = runIdSchema.parse(runId);
+        let held;
+        await this.dependencies.table().update(STATE_KEY, (current) => {
+            const index = current.runs.findIndex((run) => run.runId === parsedRunId);
+            const run = current.runs[index];
+            if (run === undefined)
+                throw new Error(`run "${parsedRunId}" does not exist`);
+            if (run.state !== 'queued')
+                throw new Error(`run "${parsedRunId}" is not queued`);
+            held = {
+                ...structuredClone(run),
+                state: 'paused',
+                queueClass: 'resumption',
+                pause: {
+                    kind: 'queued',
+                    reason: 'operator',
+                    operatorHold: true,
+                    continuationTarget: 'implementing',
+                    pausedAt: new Date().toISOString(),
+                },
+            };
+            const next = structuredClone(current);
+            next.runs[index] = held;
+            next.revision += 1;
+            return stateSchema.parse(next);
+        });
+        if (held === undefined)
+            throw new Error(`run "${parsedRunId}" was not held`);
+        return structuredClone(held);
+    }
+}
+//# sourceMappingURL=pause-control.js.map

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

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

package/lib/admission/policy.d.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import type { CodeHostBinding } from '../code-host.js';
+import type { AutopilotSettings } from '../config.js';
+import type { TrackerIssueSnapshot, TrackerProviderId } from '../tracker.js';
+import type { ActivePauseReason, ActivePauseSnapshot, ActiveResumeAuthorization, AdmissionRejectionReason, AgentBriefSnapshot, AgentExecutionComposition, AutopilotRun, GitExecutionSnapshot, ImplementingRun, PausedActiveRun, PausedQueuedRun, PausingRun, QueuedRun, ReconcileRequest, RunExecutionSnapshot, RunId, RunUsageSettlement } from './model.js';
+export interface EligibleIssue {
+    issue: TrackerIssueSnapshot & {
+        readiness: Extract<TrackerIssueSnapshot['readiness'], {
+            kind: 'transition';
+        }>;
+    };
+    brief: AgentBriefSnapshot;
+}
+export declare function activePause(reason: ActivePauseReason, requestedAt: string): ActivePauseSnapshot;
+export declare function isPausedActiveRun(run: AutopilotRun | undefined): run is PausedActiveRun;
+export declare function isPausedQueuedRun(run: AutopilotRun | undefined): run is PausedQueuedRun;
+export declare function validUsageSettlement(run: ImplementingRun | PausingRun, usage: RunUsageSettlement): usage is Extract<RunUsageSettlement, {
+    kind: 'known';
+}>;
+export declare function usageUncertaintyReason(run: ImplementingRun | PausingRun, usage: RunUsageSettlement): string;
+export declare function boundedExternalRetry(retryAfterMs: number | undefined, attempts: number): number;
+export declare function validateActiveResumeFacts(run: PausedActiveRun, observedGit: GitExecutionSnapshot, settings: AutopilotSettings, authorization: ActiveResumeAuthorization): void;
+export declare function evaluateIssue(issue: TrackerIssueSnapshot, maxBriefBytes: number): EligibleIssue | {
+    displayKey: string;
+    reason: AdmissionRejectionReason;
+};
+export declare function runIdentity(providerId: TrackerProviderId, issue: EligibleIssue['issue']): string;
+export declare function runIdentityFromRun(run: Pick<AutopilotRun, 'providerId' | 'bindingId' | 'issueId' | 'readinessGeneration'>): string;
+export declare function matchesRetainedIssue(run: Pick<AutopilotRun, 'providerId' | 'bindingId' | 'issueId' | 'readinessGeneration' | 'brief'>, providerId: TrackerProviderId, evaluation: EligibleIssue): boolean;
+export declare function sameRetainedRun(current: PausedQueuedRun, expected: PausedQueuedRun): boolean;
+export declare function runId(identity: string): RunId;
+export declare function compareQueuedRuns(left: QueuedRun, right: QueuedRun): number;
+export declare function occupiesQueueCapacity(run: AutopilotRun): boolean;
+export declare function compareSnapshotRuns(left: AutopilotRun, right: AutopilotRun): number;
+export declare function executionFor(run: QueuedRun, settings: AutopilotSettings, codeHost: CodeHostBinding, agent: AgentExecutionComposition): RunExecutionSnapshot;
+export declare function assertStateSize(state: object): void;
+export declare function boundedNonEmptyString(maxBytes: number, label: string): z.ZodString;
+export declare function truncateUtf8(value: string, maxBytes: number): string;
+export declare function validateRequest(request: ReconcileRequest): void;