opencode-swarm 7.155.0 → 7.157.0

package/dist/harness/source-candidate.d.ts

@@ -0,0 +1,45 @@
+import { lstatSync } from 'node:fs';
+import type { HarnessEvolutionConfig } from '../config/schema.js';
+import { type HarnessCandidateFileV1, type HarnessCandidateManifestV1 } from './contracts.js';
+export type HarnessSourceCandidateFileV1 = HarnessCandidateFileV1;
+export type HarnessSourceCandidateV1 = HarnessCandidateManifestV1 & {
+    /** Inert evidence only. No production API applies this patch. */
+    patch?: string;
+};
+type ValidationFailureCode = 'ALLOWLIST_EMPTY' | 'INVALID_BASE_SHA' | 'STALE_BASE' | 'PATCH_TOO_LARGE' | 'UNSUPPORTED_PATCH' | 'PATH_REJECTED' | 'PATH_NOT_ALLOWLISTED' | 'PROTECTED_PATH' | 'GIT_FAILED' | 'UNTRACKED_PATH' | 'UNSUPPORTED_TRACKED_MODE' | 'SYMLINK_PATH' | 'HARDLINK_PATH' | 'BINARY_FILE' | 'FILE_TOO_LARGE' | 'TOTAL_TOO_LARGE' | 'FILE_COUNT_EXCEEDED' | 'LINE_COUNT_EXCEEDED' | 'PATH_CHANGED_DURING_VALIDATION' | 'PATCH_DOES_NOT_APPLY';
+export type SourceCandidateValidationResult = {
+    ok: true;
+    candidate: HarnessSourceCandidateV1;
+} | {
+    ok: false;
+    code: ValidationFailureCode;
+    reason: string;
+};
+interface GitCommandResult {
+    ok: boolean;
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+interface GitBinaryCommandResult {
+    ok: boolean;
+    code: number;
+    stdout: Uint8Array;
+    stderr: string;
+}
+export declare function validateSourceCandidate(args: {
+    directory: string;
+    config: HarnessEvolutionConfig;
+    candidateId: string;
+    baseSha: string;
+    origin: string;
+    patch: string;
+}): Promise<SourceCandidateValidationResult>;
+declare function runGitCommand(directory: string, args: string[]): Promise<GitCommandResult>;
+declare function runGitBinaryCommand(directory: string, args: string[], maxOutputBytes?: number): Promise<GitBinaryCommandResult>;
+export declare const _internals: {
+    runGitCommand: typeof runGitCommand;
+    runGitBinaryCommand: typeof runGitBinaryCommand;
+    lstatSync: typeof lstatSync;
+};
+export {};

package/dist/harness/store.d.ts

@@ -0,0 +1,256 @@
+import { type WriteApprovalRequest } from '../security/write-authority.js';
+import { type BlueprintPatchV1, type HarnessBlueprintV1, type PromptArtifactV1 } from './contracts.js';
+import type { HarnessSourceCandidateV1 } from './source-candidate.js';
+type RetainedCandidateBinding = {
+    candidateId: string;
+    manifestHash: string;
+};
+export interface StoredHarnessCandidateV1 {
+    v: 1;
+    candidate: HarnessSourceCandidateV1;
+    promptArtifacts?: PromptArtifactV1[];
+    baseBlueprint?: HarnessBlueprintV1;
+    targetBlueprint?: HarnessBlueprintV1;
+    blueprintPatch?: BlueprintPatchV1;
+    recordedAt: string;
+}
+export interface HarnessVersionV1 {
+    v: 1;
+    versionId: string;
+    candidateId: string;
+    manifestHash: string;
+    allowedPathDigest: string;
+    generation: number;
+    sourceKind: 'activation' | 'rollback';
+    parentVersionId: string | null;
+    restoredFromVersionId: string | null;
+    approvalFactId: string;
+    blueprint?: HarnessBlueprintV1;
+    recordedAt: string;
+}
+export interface HarnessCurrentProjectionV1 {
+    v: 1;
+    currentVersionId: string | null;
+    currentCandidateId: string | null;
+    currentManifestHash: string | null;
+    currentHash: string;
+    generation: number;
+    versionIds: string[];
+    updatedAt: string;
+    ledgerHeadSegment: string | null;
+    ledgerHeadSeq: number;
+    ledgerHeadHash: string;
+}
+export interface HarnessLedgerRecordV1 {
+    v: 1;
+    seq: number;
+    timestamp: string;
+    kind: 'candidate_recorded' | 'activated' | 'rolled_back' | 'recovered_tail' | 'compacted';
+    candidateId: string;
+    versionId: string | null;
+    parentVersionId: string | null;
+    restoredFromVersionId: string | null;
+    approvalFactId: string | null;
+    payloadHash: string;
+    generation: number;
+    currentHashBefore: string;
+    currentHashAfter: string;
+    nextCurrentVersionId: string | null;
+    nextCurrentCandidateId: string | null;
+    nextCurrentManifestHash: string | null;
+    nextVersionIds: string[];
+    nextUpdatedAt: string;
+    ledgerSegment: string;
+    prunedVersionIds: string[];
+    recoverySegment: string | null;
+    recoveredBytes: number | null;
+    retainedCandidates: RetainedCandidateBinding[];
+    compactedRecords: number | null;
+    hashBefore: string;
+    hashAfter: string;
+}
+export type RecordHarnessCandidateResult = {
+    status: 'recorded';
+    candidate: StoredHarnessCandidateV1;
+    retentionReconciled: boolean;
+    retentionFailures: string[];
+} | {
+    status: 'conflict';
+    reason: string;
+};
+export type ActivateHarnessCandidateResult = {
+    status: 'activated';
+    version: HarnessVersionV1;
+    current: HarnessCurrentProjectionV1;
+    projectionReconciled: boolean;
+    prunedArtifactsReconciled: boolean;
+    prunedArtifactFailures: string[];
+    retentionReconciled: boolean;
+    retentionFailures: string[];
+} | {
+    status: 'candidate_not_found';
+    reason: string;
+} | {
+    status: 'candidate_not_activatable';
+    reason: string;
+} | {
+    status: 'consumer_mismatch';
+    reason: string;
+} | {
+    status: 'approval_required';
+    reason: string;
+} | {
+    status: 'retention_conflict';
+    reason: string;
+    maxVersions: number;
+    requiredVersionIds: string[];
+} | {
+    status: 'stale_current';
+    reason: string;
+};
+export type RollbackHarnessVersionResult = {
+    status: 'rolled_back';
+    version: HarnessVersionV1;
+    current: HarnessCurrentProjectionV1;
+    projectionReconciled: boolean;
+    prunedArtifactsReconciled: boolean;
+    prunedArtifactFailures: string[];
+    retentionReconciled: boolean;
+    retentionFailures: string[];
+} | {
+    status: 'version_not_found';
+    reason: string;
+} | {
+    status: 'consumer_mismatch';
+    reason: string;
+} | {
+    status: 'approval_required';
+    reason: string;
+} | {
+    status: 'retention_conflict';
+    reason: string;
+    maxVersions: number;
+    requiredVersionIds: string[];
+} | {
+    status: 'stale_current';
+    reason: string;
+};
+export type SaveHarnessVersionResult = {
+    status: 'saved';
+    version: HarnessVersionV1;
+} | {
+    status: 'conflict';
+    reason: string;
+};
+export interface HarnessHistoryResult {
+    records: HarnessLedgerRecordV1[];
+    truncated: boolean;
+    quarantinePath: string | null;
+    totalRecordCount: number;
+    limit: number;
+    totalSegments: number;
+}
+export type HarnessLedgerAuditResult = {
+    outcome: 'ok';
+    records: HarnessLedgerRecordV1[];
+    truncated: boolean;
+    quarantinePath: string | null;
+    totalSegments: number;
+} | {
+    outcome: 'scope_exceeded';
+    maxSegments: number;
+    totalSegments: number;
+    replayBoundExceeded?: true;
+    maxReplayRecords?: number;
+};
+export declare class HarnessStoreIntegrityError extends Error {
+    readonly artifactPath: string;
+    readonly code = "HARNESS_STORE_INTEGRITY";
+    constructor(artifactPath: string, message: string);
+}
+export declare class HarnessReplayBoundExceededError extends Error {
+    readonly maxReplayRecords: number;
+    readonly code = "HARNESS_REPLAY_BOUND_EXCEEDED";
+    constructor(maxReplayRecords: number);
+}
+declare function appendLedgerLine(directory: string, line: string, expectedSegmentName?: string): void;
+declare function removeVersionArtifact(filePath: string): void;
+declare function writeCurrentProjection(directory: string, current: HarnessCurrentProjectionV1): Promise<void>;
+declare function removeCandidateArtifact(directory: string): void;
+declare function removeLedgerArtifact(target: string): void;
+export declare function buildHarnessActivationApprovalRequest(args: {
+    targetSessionId: string;
+    candidate: StoredHarnessCandidateV1;
+    expectedCurrentHash: string | null;
+    expectedCurrentGeneration: number;
+    targetContentHash: string;
+    allowedPathDigest: string;
+}): WriteApprovalRequest;
+export declare function buildHarnessRollbackApprovalRequest(args: {
+    targetSessionId: string;
+    currentVersionId: string;
+    targetVersionId: string;
+    expectedCurrentHash: string;
+    expectedCurrentGeneration: number;
+    targetContentHash: string;
+    allowedPathDigest: string;
+}): WriteApprovalRequest;
+export declare function recordHarnessCandidate(args: {
+    directory: string;
+    candidate: StoredHarnessCandidateV1;
+    maxReplayRecords?: number;
+    maxInactiveCandidates?: number;
+}): Promise<RecordHarnessCandidateResult>;
+export declare function saveHarnessVersion(args: {
+    directory: string;
+    version: HarnessVersionV1;
+}): Promise<SaveHarnessVersionResult>;
+export declare function loadHarnessCurrent(directory: string, maxReplayRecords?: number): Promise<HarnessCurrentProjectionV1>;
+/** Explicitly reconcile the derived projection; read paths never mutate state. */
+export declare function reconcileHarnessCurrent(directory: string, maxReplayRecords?: number): Promise<HarnessCurrentProjectionV1>;
+export declare function loadHarnessCandidate(directory: string, candidateId: string, maxReplayRecords?: number): Promise<StoredHarnessCandidateV1 | null>;
+export declare function loadHarnessPromptArtifact(directory: string, candidateId: string, promptHash: string): PromptArtifactV1 | null;
+export declare function loadHarnessVersion(directory: string, versionId: string): Promise<HarnessVersionV1 | null>;
+export declare function listHarnessHistory(directory: string, options?: number | {
+    maxReplayRecords?: number;
+    limit?: number;
+}): Promise<HarnessHistoryResult>;
+export declare function auditHarnessLedger(directory: string, options: {
+    maxReplayRecords?: number;
+    maxSegments: number;
+}): Promise<HarnessLedgerAuditResult>;
+export declare function recoverHarnessCorruptTail(directory: string, maxReplayRecords?: number): Promise<HarnessHistoryResult>;
+export declare function activateHarnessCandidate(args: {
+    directory: string;
+    candidateId: string;
+    consumerSessionId: string;
+    targetSessionId?: string;
+    expectedCurrentHash: string | null;
+    expectedCurrentGeneration: number;
+    targetContentHash: string;
+    allowedPathDigest: string;
+    maxVersions?: number;
+    maxReplayRecords?: number;
+    maxInactiveCandidates?: number;
+}): Promise<ActivateHarnessCandidateResult>;
+export declare function rollbackHarnessVersion(args: {
+    directory: string;
+    targetVersionId: string;
+    consumerSessionId: string;
+    targetSessionId?: string;
+    expectedCurrentHash: string;
+    expectedCurrentGeneration: number;
+    targetContentHash: string;
+    allowedPathDigest: string;
+    maxVersions?: number;
+    maxReplayRecords?: number;
+    maxInactiveCandidates?: number;
+}): Promise<RollbackHarnessVersionResult>;
+export declare const _storeInternals: {
+    appendLedgerLine: typeof appendLedgerLine;
+    writeCurrentProjection: typeof writeCurrentProjection;
+    removeVersionArtifact: typeof removeVersionArtifact;
+    removeCandidateArtifact: typeof removeCandidateArtifact;
+    removeLedgerArtifact: typeof removeLedgerArtifact;
+};
+export {};

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

@@ -4,7 +4,7 @@ import { type CandidateSeverity, type FindingsSeverity, type RowFormatFamily } f
 import { type LaneOutputArtifact } from '../background/lane-output-store.js';
 import { type BackgroundDelegationRecord, type BackgroundDelegationResult, type BackgroundDelegationWorkflowLaneFailureClass, type BackgroundDelegationWorkflowLaneRecovery, 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 { type RevisionDigestResult, resolveCommitCountSince, resolveCommitCountSinceAsync, resolveCurrentGitHead, resolveCurrentGitHeadAsync, resolveCurrentLocalHeadRefAsync, resolveCurrentUpstreamPushTarget, resolveCurrentUpstreamPushTargetAsync, resolveCurrentUpstreamRemoteRef, resolveExactRemoteBranchHead, resolveExactRemoteBranchHeadAsync, resolveIsExactSingleChildCommit, resolveIsExactSingleChildCommitAsync, resolveIsWorkingTreeClean, resolveIsWorkingTreeCleanAsync, resolvePrReviewDiffStats, resolvePrReviewDiffStatsAsync, resolvePrWorkflowRevisionDigest, resolvePrWorkflowRevisionDigestDetailed, resolveRemoteRefsContainingHead, resolveRemoteRefsContainingHeadAsync, resolveRemoteUrlIdentity, resolveRemoteUrlIdentityAsync } from '../background/workspace-snapshot.js';
 import { type PrReviewResilienceConfig } from '../config/schema.js';
 import { classifyPrWorkflowGitState, type PrWorkflowGitState } from '../git/pr-workflow-state.js';
 import { classifyPrReviewCircuitSignal, type PrReviewCircuitLegacyRecord, type PrReviewCircuitRecordV2 } from './pr-review-resilience-circuit.js';
@@ -259,6 +259,94 @@ interface PrFeedbackReadyToPublishRecord {
     remoteRef: string;
     validatedAt: string;
 }
+/**
+ * Issue #2108: durable publication-generation state machine. The legacy
+ * {@link PrFeedbackReadyToPublishRecord} above becomes a derived mirror that
+ * is present exactly while the active generation is `{armed, push_in_flight}`
+ * (or a legacy record awaits migration), so a rolled-back binary keeps
+ * enforcing the armed window instead of turning permissive.
+ */
+export type PrFeedbackPublicationGenerationState = 'reviewing' | 'armed' | 'invalidated' | 'push_in_flight' | 'published' | 'cancelled_without_publication';
+export interface PrFeedbackPublicationEvidenceJoin {
+    stageAValidatedAt: string;
+    batches: Array<{
+        phase: PrFeedbackGatePhase;
+        batchId: string;
+        laneId: string;
+    }>;
+}
+export interface PrFeedbackPublicationGeneration {
+    schemaVersion: 1;
+    generation: number;
+    state: PrFeedbackPublicationGenerationState;
+    /** Canonical workspace identity at arming (`canonicalWorkspaceIdentity`). */
+    workspaceIdentity: string;
+    sessionID: string;
+    /** HTTPS PR URL bound at arming (PR identity disclosure), when present. */
+    prTargetUrl?: string;
+    /** Immutable intake head the approved commit descends from. */
+    intakeHeadSha: string;
+    /** Local branch ref resolved at arming. */
+    localHeadRef: string;
+    /** Exact approved local head commit. */
+    localHead: string;
+    remoteName: string;
+    /** Credential-redacted remote URL identity (`git remote get-url`). */
+    remoteUrlIdentity?: string;
+    remoteBranchRef: string;
+    remoteRef: string;
+    revisionDigest: string;
+    /** The exact receipt set that authorized this generation. */
+    evidence: PrFeedbackPublicationEvidenceJoin;
+    invalidationReason?: string;
+    supersededByGeneration?: number;
+    createdAt: string;
+    armedAt?: string;
+    invalidatedAt?: string;
+    publishedAt?: string;
+    cancelledAt?: string;
+}
+export type PrFeedbackPushAttemptOutcome = 'completed' | 'rejected' | 'uncertain' | 'cancelled';
+export interface PrFeedbackPushAttempt {
+    attemptId: string;
+    generation: number;
+    sessionID: string;
+    callID?: string;
+    /** SHA-256 over the canonical intent JSON. */
+    intentDigest: string;
+    intent: {
+        remote: string;
+        sourceSha: string;
+        destRef: string;
+    };
+    prePush: {
+        localHead: string;
+        worktreeClean: boolean;
+        remoteName: string;
+        remoteBranchRef: string;
+        observedRemoteHead: string | null;
+    };
+    startedAt: string;
+    result?: {
+        outcome: PrFeedbackPushAttemptOutcome;
+        exitStatus: number | 'not-observed';
+        /** Bounded (<=500 chars) and secret-redacted. */
+        diagnostic: string;
+        postPush: {
+            localHead: string | null;
+            observedRemoteHead: string | null;
+        };
+        completedAt: string;
+    };
+}
+export interface PrFeedbackPublicationState {
+    schemaVersion: 1;
+    active?: PrFeedbackPublicationGeneration;
+    /** Bounded superseded-generation summaries (last 4). */
+    history: PrFeedbackPublicationGeneration[];
+    /** Bounded attempt records for the active generation (last 8). */
+    attempts: PrFeedbackPushAttempt[];
+}
 export type PrWorkflowCompletionStatus = 'completed' | 'ready-to-publish' | 'verified-no-change';
 export type PrReviewValidationPhase = 'council' | 'reviewer' | 'critic';
 export type PrReviewArtifactBoundary = 'post_explorer' | 'post_reviewer' | 'post_critic';
@@ -427,6 +515,13 @@ export interface PrWorkflowGateState {
     prFeedbackStageA?: PrFeedbackStageARecord;
     prFeedbackGateBatches?: PrFeedbackGateBatchRecord[];
     prFeedbackReadyToPublish?: PrFeedbackReadyToPublishRecord;
+    /**
+     * Issue #2108: audited publication generations + push attempts. The
+     * authoritative publication state machine; `prFeedbackReadyToPublish`
+     * above is its derived rollback mirror. Optional so pre-#2108 state (and
+     * older binaries, via the root `.passthrough()`) loads unchanged.
+     */
+    prFeedbackPublication?: PrFeedbackPublicationState;
     /**
      * Issue #2131 criterion C2: count of controlled base-sync/rebind transitions.
      * Each rebind moves the immutable intake head to a new verified remote PR
@@ -707,8 +802,18 @@ export declare function settlePresumedStalePrWorkflowLanes(directory: string, se
  */
 export declare function abortPrWorkflow(directory: string, sessionID: string, options?: {
     expectedMode?: PrWorkflowMode;
-    kind: 'recovery' | 'force';
+    kind: 'recovery' | 'force' | 'cancel-publication';
     reason: string;
+    /**
+     * Issue #2108: the explicit cancellation-without-publication arm. While
+     * an armed/push_in_flight/invalidated publication generation exists,
+     * this arm (and ONLY this arm — mutually exclusive with `force`) may
+     * clear the workflow: it records the generation as
+     * `cancelled_without_publication` with the observed remote head and a
+     * REQUIRED reason, and never manufactures push authority. Plain
+     * `recovery`/`force` aborts remain refused while armed.
+     */
+    cancelPublication?: boolean;
 }): Promise<{
     mode: PrWorkflowMode;
     prHeadSha?: string;
@@ -860,6 +965,174 @@ export declare function recordPrFeedbackGateBatch(directory: string, sessionID:
 export declare function assertPrFeedbackGatePhaseSettled(directory: string, sessionID: string, phase: PrFeedbackGatePhase): Promise<PrWorkflowGateState>;
 /** Require every ordered feedback gate on one unchanged revision. */
 export declare function assertPrFeedbackReadyToPublish(directory: string, sessionID: string): Promise<PrWorkflowGateState>;
+/** Build the evidence join for a freshly armed generation. */
+declare function buildPublicationEvidenceJoin(state: PrWorkflowGateState, currentDigest: string): PrFeedbackPublicationEvidenceJoin | null;
+/**
+ * Snapshot of the publication container with bounded history trimming.
+ * History keeps the last {@link MAX_PUBLICATION_HISTORY_GENERATIONS}
+ * superseded generations; attempts belong to the active generation only.
+ */
+declare function nextPublicationContainer(previous: PrFeedbackPublicationState | undefined, active: PrFeedbackPublicationGeneration | undefined, historyAppends?: PrFeedbackPublicationGeneration[], attempts?: PrFeedbackPushAttempt[]): PrFeedbackPublicationState;
+/**
+ * The audited invalidation transition (issue #2108 §4/§5). Supersedes every
+ * content-dependent approval of the active generation — Stage A result,
+ * verification batches, ordered-gate batches, scope declarations — by
+ * removing them from ACTIVE state (the underlying lane artifacts remain in
+ * their own stores; the superseded join is pinned in the generation record),
+ * marks the generation `invalidated`, clears the rollback mirror, and appends
+ * the audit event. Never deletes the generation itself or its history.
+ *
+ * `driftReverification` (auto-detected drift) re-proves the drifted component
+ * under the session lock before writing, so a TOCTOU between the unlocked
+ * snapshot and this write cannot invalidate on stale evidence.
+ */
+declare function invalidatePublicationGeneration(directory: string, sessionID: string, reason: string, options?: {
+    drift?: {
+        component: string;
+        detail: string;
+    };
+    driftReverification?: boolean;
+    finalizeInFlightAs?: PrFeedbackPushAttemptOutcome;
+}): Promise<PrWorkflowPublicationTransitionResult>;
+interface PrWorkflowPublicationTransitionResult {
+    generation: PrFeedbackPublicationGeneration;
+    state: PrWorkflowGateState;
+}
+/**
+ * Migrate a legacy armed record (pre-#2108 state) into the generation state
+ * machine, conservatively: every identity component must recompute and match
+ * under the session lock, and the active receipts must be present and bound
+ * to the mirror's digest. Any mismatch or failure persists generation 1 as
+ * `invalidated` with a `legacy-migration-*` reason — never silently armed.
+ * No-op when no legacy record exists (returns the current state unchanged).
+ */
+declare function ensurePublicationGenerationCurrent(directory: string, sessionID: string): Promise<PrWorkflowGateState | null>;
+/**
+ * The reaper (issue #2108 §3): finalize any result-less push attempt before
+ * another armed-window interaction proceeds. Recovers restarts and missed
+ * `tool.execute.after` observations as `uncertain` and re-observes the remote
+ * head, so `push_in_flight` can never wedge a generation.
+ */
+declare function reconcileForeignInFlightAttempt(directory: string, sessionID: string, currentCallId?: string): Promise<PrWorkflowGateState | null>;
+/**
+ * Controller-facing invalidation/rework transition (issue #2108 §4): the
+ * explicit declaration that approved content must change, which opens the
+ * mutation path by superseding every content-dependent approval of the
+ * current armed generation. Requires a non-empty reason. Refuses when no
+ * live window exists and reports already-invalidated as an informative
+ * diagnostic (idempotent no-op is NOT silently accepted — the caller should
+ * see the current state).
+ */
+export declare function invalidatePrFeedbackPublication(directory: string, sessionID: string, reason: string): Promise<PrFeedbackPublicationGeneration>;
+/**
+ * Operator-facing publication summary for `pr_workflow_status` (issue #2108):
+ * generation, state, target, attempts, invalidation reason, and the
+ * state-appropriate recovery instruction. Returns null when the workflow has
+ * no publication state to describe.
+ */
+export declare function describePrWorkflowPublicationSection(state: PrWorkflowGateState): string | null;
+/**
+ * Issue #2108 safety boundary — "fail closed on corrupt, MISSING, ambiguous,
+ * copied, cross-workspace, or conflicting generation state" and "a manual
+ * state-file edit … cannot clear the authorization requirement": when the
+ * gate state file for a session is absent (e.g. deleted by hand while a
+ * generation was live) but the retained events window shows a LIVE
+ * publication generation for that session — an `armed` or
+ * `push_attempt_started` event with no later terminal (`published`,
+ * `cancelled`, `invalidated`) — publication-capable commands fail closed
+ * until an audited terminal lands. The events store is the append-only audit
+ * authority the state-file deletion cannot touch; when the trail is empty or
+ * compacted past the event the guard is silent (it never invents a dangling
+ * generation from absent evidence).
+ */
+export declare function findDanglingLivePublicationGeneration(directory: string, sessionID: string): {
+    generation: number;
+} | null;
+/** Typed rejection taxonomy for a standalone `git push` command. */
+export type ExactPushIntentRejection = 'shell-syntax' | 'token-shape' | 'flag-or-option' | 'credential-bearing-remote' | 'invalid-source-sha' | 'invalid-dest-ref' | 'delete-refspec' | 'wildcard-refspec' | 'remote-mismatch' | 'branch-mismatch' | 'source-mismatch' | 'unbound-target';
+export interface ExactPushIntent {
+    remote: string;
+    sourceSha: string;
+    destRef: string;
+}
+export interface ExactPushIntentParseResult {
+    ok: boolean;
+    intent?: ExactPushIntent;
+    /** SHA-256 over the canonical intent JSON (persisted in attempt records). */
+    digest?: string;
+    reason?: ExactPushIntentRejection;
+}
+/**
+ * Fold an audited invalidation into a PENDING single-write state transition
+ * (the Stage A re-record and inventory-amendment disarm sites, issue #2108
+ * R3.3): when the pending state still carries a live publication window, the
+ * generation is marked `invalidated` with the given reason, the rollback
+ * mirror and the remaining ancestry-bound receipts (verifications, gate
+ * batches, scope declarations) are superseded in the SAME atomic write, and
+ * any result-less attempt is finalized `uncertain`. A fresh `prFeedbackStageA`
+ * the pending write itself is recording survives — it is evidence recorded
+ * after the invalidation moment. No-op when no live window exists (the
+ * normal unarmed flow keeps its existing behavior).
+ *
+ * Returns the pending state plus the audit-event payload; the CALLER appends
+ * the event only AFTER its persistState succeeds (PR #2422 review PRR-023:
+ * an event must never claim an invalidation whose state write failed — the
+ * abort path's retraction discipline, applied here at the source).
+ */
+declare function supersedeLivePublicationInPendingState(pending: PrWorkflowGateState, reason: string): {
+    state: PrWorkflowGateState;
+    invalidationEvent: Record<string, unknown> | null;
+};
+/**
+ * Parse a standalone push command into a typed intent BEFORE any shell
+ * execution. The only publish-capable intent is the exact armed tuple —
+ * `git push <remote> <localHead>:refs/heads/<branch>` — with NO flags, NO
+ * extra refspecs, NO wildcard/delete/mirror/tag forms, and NO
+ * credential-bearing remote token. This is a structural refactor of the
+ * previous single-regex defense with the SAME accepted grammar (nothing that
+ * the regex rejected is accepted here); every rejection is now explicit,
+ * typed, and auditable. Remote and branch compare case-SENSITIVELY (git ref
+ * semantics); the source SHA compares exactly, as before.
+ */
+declare function parseExactBoundPushIntent(command: string, armed: {
+    remoteName: string;
+    remoteBranchRef: string;
+    localHead: string;
+}): ExactPushIntentParseResult;
+/**
+ * Durable attempt-start before the exact bound push is permitted to execute
+ * (issue #2108 §3), all under ONE session-lock acquisition: re-verify the
+ * armed identity, observe the remote head, and either (a) record an
+ * attempt whose result is already `completed` because the remote is observed
+ * at the approved head (no-op push; the observation — not an exit code — is
+ * the truth), or (b) persist the attempt-start and move the generation to
+ * `push_in_flight` BEFORE the push can run.
+ */
+declare function admitPrFeedbackPushAttempt(directory: string, sessionID: string, callID: string | undefined, intent: ExactPushIntent, intentDigest: string): Promise<{
+    kind: 'started' | 'already-published-remotely';
+}>;
+/**
+ * Record the result of an admitted push from the `tool.execute.after` chain
+ * (issue #2108 §3). Fail-open by design: a missed observation is recovered by
+ * the reaper as `uncertain`; publication truth always comes from
+ * complete_pr_workflow's direct remote verification, never from an exit code
+ * alone. Exported for the single `tool.execute.after` guard in `src/index.ts`.
+ */
+export declare function recordPrFeedbackPushAttemptResult(directory: string, input: {
+    sessionID: string;
+    callID?: string;
+    tool: string;
+}, command: string, output: unknown): Promise<void>;
+/**
+ * Cancellation without publication (issue #2108 §6): a terminal no-publish
+ * transition. Finalizes any in-flight attempt as `cancelled`, discloses the
+ * observed remote head, marks the generation `cancelled_without_publication`,
+ * appends the audit event, and NEVER manufactures push authority. Used only
+ * by `abortPrWorkflow`'s explicit `cancelPublication` arm. Returns the NEW
+ * state revision when a state write landed (the abort clear must CAS against
+ * it), or null when the generation state was absent/unreadable.
+ */
+declare function cancelPrFeedbackPublication(directory: string, sessionID: string, reason: string): Promise<number | null>;
 export declare function resolvePrReviewWriterRunId(directory: string, sessionID: string, requestedRunId?: string): Promise<string>;
 export declare function markPrReviewTriggerEvaluationComplete(directory: string, sessionID: string, runId: string, artifactPath: string): Promise<PrWorkflowGateState>;
 /** Freeze one exact inline trigger ledger across every micro dispatch. */
@@ -898,7 +1171,7 @@ export declare function validatePrFeedbackScopeBinding(directory: string, bindin
     workflowSessionId?: string;
     workflowRevisionDigest?: string;
 }): Promise<boolean>;
-export declare function enforcePrWorkflowToolBefore(directory: string, sessionID: string, toolName: string, args: Record<string, unknown> | undefined, generatedAgentNames?: readonly string[]): Promise<void>;
+export declare function enforcePrWorkflowToolBefore(directory: string, sessionID: string, toolName: string, args: Record<string, unknown> | undefined, generatedAgentNames?: readonly string[], callID?: string): Promise<void>;
 /** Validate the terminal PR workflow contract before removing its durable gate. */
 export declare function completePrWorkflow(directory: string, sessionID: string, expectedMode: PrWorkflowMode, prHeadSha: string): Promise<PrWorkflowCompletionStatus>;
 export declare const _test_exports: {
@@ -985,6 +1258,21 @@ export declare const _test_exports: {
     resolveCurrentUpstreamPushTarget: typeof resolveCurrentUpstreamPushTarget;
     resolveCurrentUpstreamPushTargetAsync: typeof resolveCurrentUpstreamPushTargetAsync;
     resolveCurrentUpstreamRemoteRef: typeof resolveCurrentUpstreamRemoteRef;
+    resolveCurrentLocalHeadRefAsync: typeof resolveCurrentLocalHeadRefAsync;
+    resolveRemoteUrlIdentity: typeof resolveRemoteUrlIdentity;
+    resolveRemoteUrlIdentityAsync: typeof resolveRemoteUrlIdentityAsync;
+    parseExactBoundPushIntent: typeof parseExactBoundPushIntent;
+    admitPrFeedbackPushAttempt: typeof admitPrFeedbackPushAttempt;
+    recordPrFeedbackPushAttemptResult: typeof recordPrFeedbackPushAttemptResult;
+    reconcileForeignInFlightAttempt: typeof reconcileForeignInFlightAttempt;
+    ensurePublicationGenerationCurrent: typeof ensurePublicationGenerationCurrent;
+    invalidatePublicationGeneration: typeof invalidatePublicationGeneration;
+    invalidatePrFeedbackPublication: typeof invalidatePrFeedbackPublication;
+    cancelPrFeedbackPublication: typeof cancelPrFeedbackPublication;
+    buildPublicationEvidenceJoin: typeof buildPublicationEvidenceJoin;
+    nextPublicationContainer: typeof nextPublicationContainer;
+    supersedeLivePublicationInPendingState: typeof supersedeLivePublicationInPendingState;
+    describePrWorkflowPublicationSection: typeof describePrWorkflowPublicationSection;
     resolveExactRemoteBranchHead: typeof resolveExactRemoteBranchHead;
     resolveExactRemoteBranchHeadAsync: typeof resolveExactRemoteBranchHeadAsync;
     resolveCommitCountSince: typeof resolveCommitCountSince;

package/dist/index.d.ts

@@ -63,3 +63,5 @@ export type { EvaluatePrReviewRecoveryV1Options } from './evaluation/pr-review-r
 export { evaluatePrReviewRecoveryV1 } from './evaluation/pr-review-recovery.js';
 export type { EvaluateCandidateV1Options, EvaluateCandidateV1Result, } from './evaluation/public-api.js';
 export { evaluateCandidateV1, evaluationV1, } from './evaluation/public-api.js';
+export type { AgentBlueprintV1, BlueprintPatchV1, HarnessBlueprintV1, HarnessCandidateManifestV1, OrchestrationSpecV1, PromptArtifactV1, ToolSpecV1, } from './harness/contracts.js';
+export { harnessMutationV1 } from './harness/public-api.js';