opencode-swarm 7.144.2 → 7.144.3

package/dist/hooks/pr-workflow-gate.d.ts

@@ -2,7 +2,7 @@ import * as fsp from 'node:fs/promises';
 import { z } from 'zod';
 import { type CandidateSeverity, type RowFormatFamily } from '../background/candidate-contract.js';
 import { type LaneOutputArtifact } from '../background/lane-output-store.js';
-import { type BackgroundDelegationRecord, type BackgroundDelegationResult, findByBatchId } from '../background/pending-delegations.js';
+import { type BackgroundDelegationRecord, type BackgroundDelegationResult, findByBatchId, sweepStaleDelegations } from '../background/pending-delegations.js';
 import { type PrReviewInlineTriggerRow } from '../background/pr-review-trigger-contract.js';
 import { type RevisionDigestResult, resolveCommitCountSince, resolveCommitCountSinceAsync, resolveCurrentGitHead, resolveCurrentGitHeadAsync, resolveCurrentUpstreamPushTarget, resolveCurrentUpstreamPushTargetAsync, resolveCurrentUpstreamRemoteRef, resolveExactRemoteBranchHead, resolveExactRemoteBranchHeadAsync, resolveIsExactSingleChildCommit, resolveIsExactSingleChildCommitAsync, resolveIsWorkingTreeClean, resolveIsWorkingTreeCleanAsync, resolvePrReviewDiffStats, resolvePrReviewDiffStatsAsync, resolvePrWorkflowRevisionDigest, resolvePrWorkflowRevisionDigestDetailed, resolveRemoteRefsContainingHead, resolveRemoteRefsContainingHeadAsync } from '../background/workspace-snapshot.js';
 import { classifyPrWorkflowGitState, type PrWorkflowGitState } from '../git/pr-workflow-state.js';
@@ -408,13 +408,99 @@ export declare function withInactivePrWorkflowCheckoutRestoreLock<T>(directory:
 export declare function clearPrWorkflowGateState(directory: string, sessionID: string, expectedRevision?: number, options?: {
     allowSalvagedRead?: boolean;
 }): Promise<void>;
+/**
+ * The single session operation the liveness probe needs.
+ *
+ * Deliberately a narrow LOCAL structural type rather than a type-only import of
+ * `SessionOps` from `src/tools/dispatch-lanes.ts`: that module's
+ * `isLaneReadyForCollection` is the fail-CLOSED counterpart of this probe, and
+ * keeping the two textually independent removes any invitation to "share" the
+ * predicate. A type-only import would be erased either way; this is about
+ * preventing the wrong reuse, not about module graph cost.
+ */
+interface PrWorkflowLaneLivenessSessionOps {
+    status?: (args: {
+        query?: {
+            directory?: string;
+        };
+    }) => Promise<{
+        data?: Record<string, {
+            type?: string;
+        }> | null;
+        error?: unknown;
+    }>;
+}
+/** Why a probe produced no evidence of life. Absent means the probe ran. */
+export type PrWorkflowLaneProbeDegradedReason = 'probe-unavailable' | 'probe-error' | 'probe-timeout' | 'probe-no-data';
+/**
+ * Probe which of `records` have a session the host affirmatively reports as
+ * still running (issue #2251).
+ *
+ * **FAIL-OPEN, by design.** For its ERROR and NO-DATA cases this is the exact
+ * inverse of `isLaneReadyForCollection` (`src/tools/dispatch-lanes.ts`), which
+ * returns `false` on a truthy `error`, on missing `data`, and on a throw —
+ * because a lane it cannot verify must not be collected. The two agree, rather
+ * than invert, on ONE case: a host that exposes no `status` function at all.
+ * There the collector returns `true` (`dispatch-lanes.ts`, the `typeof
+ * session.status !== 'function'` guard) and this probe reports
+ * `probe-unavailable`, so both fall through to proceeding — an unprobeable host
+ * must not wedge either side.
+ *
+ * Here the default outcome must be "settle": an unavailable, erroring,
+ * timing-out or empty probe returns the empty set, so age alone decides and the
+ * reachability floor this whole subsystem exists to preserve is untouched. Only
+ * a probe that RAN and affirmatively named a live session may contradict
+ * staleness.
+ *
+ * The returned set is built only from a fully-read response — a mid-iteration
+ * throw yields the empty set rather than a partial spare list, so a malformed
+ * response can never spare an arbitrary subset of lanes.
+ *
+ * Keys are `subagentSessionId`s. A record without one is unprobeable and is
+ * simply never added (it settles), which is the fail-open direction.
+ */
+declare function probeAlivePrWorkflowLaneSessions(directory: string, records: BackgroundDelegationRecord[]): Promise<{
+    alive: Set<string>;
+    degradedReason?: PrWorkflowLaneProbeDegradedReason;
+}>;
 export interface PrWorkflowStaleLaneSettlement {
-    /** Lanes still genuinely in flight (fresh `updatedAt`). These still block. */
+    /**
+     * Every lane that still blocks: lanes with a fresh `updatedAt` PLUS lanes
+     * past the horizon whose session the liveness probe reported still running.
+     */
     openLaneIds: string[];
     openLanes: number;
+    /**
+     * Open lanes that block on FRESHNESS alone (age below the horizon).
+     *
+     * Separated from `openLanes` because the human-only `force` abort override
+     * (issue #2251 S3) must distinguish "blocked only by probe retention", which
+     * an operator may override, from "blocked by a lane that is genuinely young",
+     * which stays fail-closed. Deriving it by subtraction or by comparing lane
+     * LABELS would be wrong: `prWorkflowLaneLabel` falls back to `'unknown'`, so
+     * labels are not unique.
+     */
+    freshOpenLanes: number;
     /** Lanes stale past the horizon, treated as settled with disclosure. */
     presumedStaleLaneIds: string[];
-    /** Operator-facing disclosure; `undefined` when nothing was presumed stale. */
+    /**
+     * Lanes past the horizon that the probe spared. Present only when non-empty.
+     */
+    probedAliveLaneIds?: string[];
+    /**
+     * The SAME records as {@link probedAliveLaneIds}, in the same order, keyed by
+     * `correlationId` instead of by display label.
+     *
+     * Both are needed and neither substitutes for the other: `prWorkflowLaneLabel`
+     * falls back to `'unknown'` and is not unique, so it cannot address a durable
+     * record — while `correlationId` is the ledger's primary key and is what the
+     * human-only `force` override must name to finalize exactly these records and
+     * nothing else. Present only when non-empty.
+     */
+    probeRetainedCorrelationIds?: string[];
+    /** Set when the probe could not produce evidence; absent when it ran. */
+    probeDegradedReason?: PrWorkflowLaneProbeDegradedReason;
+    /** Operator-facing disclosure; `undefined` when nothing was settled or retained. */
     disclosure?: string;
 }
 /**
@@ -439,6 +525,13 @@ export interface PrWorkflowStaleLaneSettlement {
  *
  * A lane with a RECENT `updatedAt` still blocks: a re-verification that CAN run
  * and reports "still progressing" contradicts settlement and fails closed.
+ *
+ * Issue #2251 adds the second, stronger contradiction: a lane PAST the horizon
+ * whose session the host affirmatively reports as `busy`/`retry` is genuinely
+ * running (nothing heartbeats `updatedAt`, so age alone cannot see this) and is
+ * retained instead of discarded. The probe is fail-open — see
+ * {@link probeAlivePrWorkflowLaneSessions} — so an unavailable, erroring or
+ * empty probe leaves the age-only behaviour exactly as it was.
  */
 export declare function settlePresumedStalePrWorkflowLanes(directory: string, sessionID: string): Promise<PrWorkflowStaleLaneSettlement>;
 /**
@@ -480,6 +573,16 @@ export declare function abortPrWorkflow(directory: string, sessionID: string, op
     openLanes: number;
     presumedStaleLanes?: string[];
     presumedStaleDisclosure?: string;
+    /** Lanes past the horizon the liveness probe reported as still running. */
+    probeRetainedLanes?: string[];
+    /**
+     * Present ONLY when a human `force` abort cleared the gate while those
+     * probe-retained lanes were the sole remaining reason it was blocked
+     * (issue #2251 S3).
+     */
+    probeRetentionOverrideDisclosure?: string;
+    /** Why the liveness probe produced no evidence, when it could not run. */
+    probeDegradedReason?: PrWorkflowLaneProbeDegradedReason;
     stateSalvaged?: boolean;
     stateSalvageDisclosure?: string;
     casEscapeDisclosure?: string;
@@ -652,6 +755,32 @@ export declare const _test_exports: {
     removeCheckoutLock: typeof removeCheckoutLockFile;
     checkoutMutationActionTimeoutMs: number;
     classifyPrWorkflowGitStateAsync: typeof classifyPrWorkflowGitState;
+    /**
+     * The durability sweep, reached through a seam so a test can prove that a
+     * failing sweep cannot un-settle the decision `settlePresumedStalePrWorkflow-
+     * Lanes` already made in memory. It cannot throw today (it catches internally
+     * and returns 0) — the seam is what makes that guarantee testable rather than
+     * merely asserted.
+     */
+    sweepStaleDelegationsAsync: typeof sweepStaleDelegations;
+    /** The fail-open liveness probe (issue #2251). */
+    probeLaneLivenessAsync: typeof probeAlivePrWorkflowLaneSessions;
+    /**
+     * Session handle for the liveness probe.
+     *
+     * A seam rather than a direct `swarmState.opencodeClient` read at the call
+     * site because 20+ test files mutate that field; without this, this suite and
+     * the stale-lane suite would be order-dependent in bun's shared process.
+     * Mirrors `_internals.getSessionOps` in `src/tools/dispatch-lanes.ts`.
+     */
+    getSessionOps: () => PrWorkflowLaneLivenessSessionOps | null;
+    /**
+     * Probe deadline, read through the seam at CALL time. `freezeClock` patches
+     * `Date.now()`, not `setTimeout`, so a test that must reach the timeout branch
+     * has to shorten the real deadline. Same precedent as
+     * `checkoutMutationActionTimeoutMs` above.
+     */
+    laneLivenessProbeTimeoutMs: number;
     resolveCurrentGitHead: typeof resolveCurrentGitHead;
     resolveCurrentGitHeadAsync: typeof resolveCurrentGitHeadAsync;
     resolveCurrentUpstreamPushTarget: typeof resolveCurrentUpstreamPushTarget;