oh-my-codex 0.18.12 → 0.18.14

package/dist/ralplan/consensus-gate.d.ts

@@ -4,6 +4,28 @@ export declare const RALPLAN_CONSENSUS_BLOCKED_REASONS: {
     readonly missingSequentialApproval: "missing_sequential_architect_then_critic_approval";
 };
 export type RalplanConsensusBlockedReason = typeof RALPLAN_CONSENSUS_BLOCKED_REASONS[keyof typeof RALPLAN_CONSENSUS_BLOCKED_REASONS];
+export interface RalplanNativeReviewDiagnostic {
+    role: 'architect' | 'critic';
+    session_id: string | null;
+    thread_id: string | null;
+    tracker_path: string;
+    session_found: boolean;
+    thread_found: boolean;
+    kind: string | null;
+    completed: boolean;
+    problem: string | null;
+}
+export interface RalplanConsensusGateDiagnostic {
+    expected_schema: string[];
+    current_session_id: string | null;
+    tracker_path: string;
+    architect: RalplanNativeReviewDiagnostic;
+    critic: RalplanNativeReviewDiagnostic;
+    distinct_thread_ids: boolean | null;
+    pair_problem: string | null;
+    remediation: string[];
+    docs: string;
+}
 export interface RalplanConsensusGateEvidence {
     complete: boolean;
     sequence: ['architect-review', 'critic-review'];
@@ -12,6 +34,7 @@ export interface RalplanConsensusGateEvidence {
     source: string | null;
     blockedReason: RalplanConsensusBlockedReason | null;
     blockedDetails?: string[];
+    diagnostic?: RalplanConsensusGateDiagnostic;
 }
 export interface RalplanNativeSubagentConsensusOptions {
     requireNativeSubagents?: boolean;
@@ -21,6 +44,7 @@ export interface RalplanNativeSubagentConsensusOptions {
 export interface RalplanConsensusSource {
     source: string;
     value: unknown;
+    sessionId?: string;
 }
 export declare function buildRalplanConsensusGateFromSources(sources: RalplanConsensusSource[], options?: RalplanNativeSubagentConsensusOptions): RalplanConsensusGateEvidence;
 export declare function buildRalplanConsensusGateForCwd(cwd: string, options?: {
@@ -34,4 +58,5 @@ export declare function hasDurableRalplanConsensusEvidenceForCwd(cwd: string, op
     requireNativeSubagents?: boolean;
 }): boolean;
 export declare function readLocalRalplanConsensusStateCandidates(cwd: string, sessionId?: string): RalplanConsensusSource[];
+export declare function withParentReturnToRalplanContext(value: unknown, parent: Record<string, unknown>): unknown;
 //# sourceMappingURL=consensus-gate.d.ts.map

package/dist/ralplan/consensus-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consensus-gate.d.ts","sourceRoot":"","sources":["../../src/ralplan/consensus-gate.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,iCAAiC;;;;CAIpC,CAAC;AAEX,MAAM,MAAM,6BAA6B,GACvC,OAAO,iCAAiC,CAAC,MAAM,OAAO,iCAAiC,CAAC,CAAC;AAE3F,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,CAAC,kBAAkB,EAAE,eAAe,CAAC,CAAC;IAChD,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzD,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACtD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,aAAa,EAAE,6BAA6B,GAAG,IAAI,CAAC;IACpD,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,qCAAqC;IACpD,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,wBAAgB,oCAAoC,CAClD,OAAO,EAAE,sBAAsB,EAAE,EACjC,OAAO,GAAE,qCAA0C,GAClD,4BAA4B,CA0E9B;AAED,wBAAgB,+BAA+B,CAC7C,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,sBAAsB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1G,4BAA4B,CAY9B;AAED,wBAAgB,wCAAwC,CACtD,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,sBAAsB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1G,OAAO,CAET;AAED,wBAAgB,wCAAwC,CACtD,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,sBAAsB,EAAE,CAuB1B"}
+{"version":3,"file":"consensus-gate.d.ts","sourceRoot":"","sources":["../../src/ralplan/consensus-gate.ts"],"names":[],"mappings":"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"}

package/dist/ralplan/consensus-gate.js

@@ -9,38 +9,49 @@ export const RALPLAN_CONSENSUS_BLOCKED_REASONS = {
 };
 export function buildRalplanConsensusGateFromSources(sources, options = {}) {
     let nativeBlockedEvidence = null;
-    let invalidCompleteEvidence = null;
+    let firstCompleteEvidence = null;
     for (const candidate of sources) {
-        const evidence = extractSequentialConsensusEvidence(candidate.value);
-        if (evidence) {
+        const evidence = resolveConsensusEvidence(candidate.value);
+        const candidateOptions = {
+            ...options,
+            sessionId: options.sessionId ?? candidate.sessionId,
+        };
+        if (evidence?.kind === 'invalid') {
+            if (isConsensusEvidenceNewerThanSelected(evidence, firstCompleteEvidence)) {
+                firstCompleteEvidence = { ...evidence, source: candidate.source };
+            }
+            continue;
+        }
+        if (evidence?.kind === 'valid') {
             if (options.requireNativeSubagents
-                && !hasTrackerBackedNativeRalplanLanes(evidence, options)) {
-                nativeBlockedEvidence ??= { ...evidence, source: candidate.source };
+                && !hasTrackerBackedNativeRalplanLanes(evidence, candidateOptions)) {
+                nativeBlockedEvidence ??= { ...evidence, source: candidate.source, options: candidateOptions };
                 continue;
             }
-            return {
-                complete: true,
-                sequence: ['architect-review', 'critic-review'],
-                ralplan_architect_review: evidence.ralplan_architect_review,
-                ralplan_critic_review: evidence.ralplan_critic_review,
-                source: candidate.source,
-                blockedReason: null,
-            };
-        }
-        const invalidEvidence = extractInvalidCompleteConsensusEvidence(candidate.value);
-        if (invalidEvidence) {
-            invalidCompleteEvidence ??= { ...invalidEvidence, source: candidate.source };
+            if (isConsensusEvidenceNewerThanSelected(evidence, firstCompleteEvidence)) {
+                firstCompleteEvidence = { ...evidence, source: candidate.source };
+            }
         }
     }
-    if (invalidCompleteEvidence) {
+    if (firstCompleteEvidence?.kind === 'invalid') {
         return {
             complete: false,
             sequence: ['architect-review', 'critic-review'],
-            ralplan_architect_review: invalidCompleteEvidence.ralplan_architect_review,
-            ralplan_critic_review: invalidCompleteEvidence.ralplan_critic_review,
-            source: invalidCompleteEvidence.source,
+            ralplan_architect_review: firstCompleteEvidence.ralplan_architect_review,
+            ralplan_critic_review: firstCompleteEvidence.ralplan_critic_review,
+            source: firstCompleteEvidence.source,
             blockedReason: RALPLAN_CONSENSUS_BLOCKED_REASONS.nonApprovingReview,
-            blockedDetails: invalidCompleteEvidence.blockedDetails,
+            blockedDetails: firstCompleteEvidence.blockedDetails,
+        };
+    }
+    if (firstCompleteEvidence?.kind === 'valid') {
+        return {
+            complete: true,
+            sequence: ['architect-review', 'critic-review'],
+            ralplan_architect_review: firstCompleteEvidence.ralplan_architect_review,
+            ralplan_critic_review: firstCompleteEvidence.ralplan_critic_review,
+            source: firstCompleteEvidence.source,
+            blockedReason: null,
         };
     }
     if (nativeBlockedEvidence) {
@@ -52,9 +63,11 @@ export function buildRalplanConsensusGateFromSources(sources, options = {}) {
             source: nativeBlockedEvidence.source,
             blockedReason: RALPLAN_CONSENSUS_BLOCKED_REASONS.nativeSubagentEvidenceMissing,
             blockedDetails: [
-                trackerBackedNativeReviewProblem(nativeBlockedEvidence.ralplan_architect_review, 'architect', options),
-                trackerBackedNativeReviewProblem(nativeBlockedEvidence.ralplan_critic_review, 'critic', options),
+                trackerBackedNativeReviewPairProblem(nativeBlockedEvidence, nativeBlockedEvidence.options),
+                trackerBackedNativeReviewProblem(nativeBlockedEvidence.ralplan_architect_review, 'architect', nativeBlockedEvidence.options),
+                trackerBackedNativeReviewProblem(nativeBlockedEvidence.ralplan_critic_review, 'critic', nativeBlockedEvidence.options),
             ].filter((detail) => Boolean(detail)),
+            diagnostic: buildTrackerBackedNativeConsensusDiagnostic(nativeBlockedEvidence, nativeBlockedEvidence.options),
         };
     }
     return {
@@ -67,12 +80,22 @@ export function buildRalplanConsensusGateFromSources(sources, options = {}) {
     };
 }
 export function buildRalplanConsensusGateForCwd(cwd, options = {}) {
+    const localStateCandidates = readLocalRalplanConsensusStateCandidates(cwd, options.sessionId)
+        .map((candidate) => ({
+        ...candidate,
+        value: options.artifacts
+            ? withParentReturnToRalplanContext(candidate.value, options.artifacts)
+            : candidate.value,
+    }));
     return buildRalplanConsensusGateFromSources([
         ...(options.artifacts ? [
             { source: 'stage-context-artifacts', value: options.artifacts },
-            { source: 'stage-context-ralplan-artifact', value: options.artifacts.ralplan },
+            {
+                source: 'stage-context-ralplan-artifact',
+                value: withParentReturnToRalplanContext(options.artifacts.ralplan, options.artifacts),
+            },
         ] : []),
-        ...readLocalRalplanConsensusStateCandidates(cwd, options.sessionId),
+        ...localStateCandidates,
     ], {
         cwd,
         sessionId: options.sessionId,
@@ -93,59 +116,74 @@ export function readLocalRalplanConsensusStateCandidates(cwd, sessionId) {
         ? uniquePaths(sessionIdList.flatMap((id) => [
             join(scopedStateDir, 'sessions', id),
             join(localStateDir, 'sessions', id),
-        ]))
-        : [localStateDir];
-    const paths = stateRoots.flatMap((dir) => [
-        join(dir, 'ralplan-state.json'),
-        join(dir, 'autopilot-state.json'),
+        ])).map((dir) => ({
+            dir,
+            sessionId: sessionIdFromStateRoot(dir),
+        }))
+        : [{ dir: localStateDir }];
+    const paths = stateRoots.flatMap(({ dir, sessionId }) => [
+        { path: join(dir, 'ralplan-state.json'), sessionId },
+        { path: join(dir, 'autopilot-state.json'), sessionId },
     ]);
-    return paths.flatMap((path) => {
+    return paths.flatMap(({ path, sessionId }) => {
         const state = readJsonState(path);
         if (!state)
             return [];
-        return [{ source: path, value: state }];
+        return [{ source: path, value: state, sessionId }];
     });
 }
-function extractSequentialConsensusEvidence(value) {
+function resolveConsensusEvidence(value) {
     if (!value || typeof value !== 'object')
         return null;
     const record = value;
-    const gate = record.ralplanConsensusGate ?? record.ralplan_consensus_gate;
-    if (gate && typeof gate === 'object') {
-        const gateRecord = gate;
-        const architectReview = asRecord(gateRecord.ralplan_architect_review ?? gateRecord.architectReview ?? gateRecord.architect_review);
-        const criticReview = asRecord(gateRecord.ralplan_critic_review ?? gateRecord.criticReview ?? gateRecord.critic_review);
-        if (gateRecord.complete === true
-            && hasArchitectThenCriticSequence(gateRecord)
-            && isApproveReview(architectReview, 'architect')
-            && isApproveReview(criticReview, 'critic')
-            && isCriticNotBeforeArchitect(architectReview, criticReview)) {
-            return { ralplan_architect_review: architectReview, ralplan_critic_review: criticReview };
+    const returnToRalplanCycle = isReturnToRalplanCycle(record);
+    const advancedReviewCycle = explicitFreshnessReviewCycle(record);
+    const staleReturnToRalplanCycle = returnToRalplanCycle && advancedReviewCycle === null;
+    const directGate = resolveDirectGate(record);
+    let deferredOrderedDirectGate = null;
+    if (directGate) {
+        if (!returnToRalplanCycle)
+            return directGate;
+        if (advancedReviewCycle !== null) {
+            if (reviewsCarryFreshnessCycle(directGate, advancedReviewCycle))
+                return directGate;
+        }
+        else if (!hasExplicitReturnToRalplanReviewCycle(record) && consensusEvidenceOrder(directGate) !== null) {
+            deferredOrderedDirectGate = directGate;
         }
     }
-    const handoffArtifactsAreStale = isReturnToRalplanCycle(record);
+    const handoffArtifactsAreStale = staleReturnToRalplanCycle;
     const topLevelHandoffArtifacts = handoffArtifactsAreStale ? null : asRecord(record.handoff_artifacts);
     if (topLevelHandoffArtifacts) {
-        const evidence = extractSequentialConsensusEvidence(topLevelHandoffArtifacts);
+        const evidence = resolveConsensusEvidence(withParentReturnToRalplanContext(topLevelHandoffArtifacts, record));
         if (evidence)
             return evidence;
     }
     const stateRecord = asRecord(record.state);
-    const stateHandoffArtifacts = handoffArtifactsAreStale || (stateRecord && isReturnToRalplanCycle(stateRecord))
+    const stateHasOwnReturnLoopContext = stateRecord !== null && isReturnToRalplanCycle(stateRecord);
+    const stateHandoffArtifacts = handoffArtifactsAreStale && !stateHasOwnReturnLoopContext
         ? null
         : asRecord(stateRecord?.handoff_artifacts);
     if (stateHandoffArtifacts) {
-        const evidence = extractSequentialConsensusEvidence(stateHandoffArtifacts);
+        const stateContext = stateHasOwnReturnLoopContext ? stateRecord : record;
+        const evidence = resolveConsensusEvidence(withParentReturnToRalplanContext(stateHandoffArtifacts, stateContext));
         if (evidence)
             return evidence;
     }
+    if (deferredOrderedDirectGate)
+        return deferredOrderedDirectGate;
+    if (returnToRalplanCycle && advancedReviewCycle === null)
+        return null;
     const directArchitectReview = asRecord(record.ralplan_architect_review);
     const directCriticReview = asRecord(record.ralplan_critic_review);
     if (hasArchitectThenCriticSequence(record)
         && isApproveReview(directArchitectReview, 'architect')
         && isApproveReview(directCriticReview, 'critic')
-        && isCriticNotBeforeArchitect(directArchitectReview, directCriticReview)) {
+        && isCriticNotBeforeArchitect(directArchitectReview, directCriticReview)
+        && (!returnToRalplanCycle
+            || (advancedReviewCycle !== null && reviewPairCarriesFreshnessCycle(directArchitectReview, directCriticReview, advancedReviewCycle)))) {
         return {
+            kind: 'valid',
             ralplan_architect_review: directArchitectReview,
             ralplan_critic_review: directCriticReview,
         };
@@ -157,8 +195,10 @@ function extractSequentialConsensusEvidence(value) {
         const criticReview = asRecord(latestReviewEntry.ralplan_critic_review ?? latestReviewEntry.critic_review ?? latestReviewEntry.criticReview);
         if (isApproveReview(architectReview, 'architect')
             && isApproveReview(criticReview, 'critic')
-            && isCriticNotBeforeArchitect(architectReview, criticReview)) {
-            return { ralplan_architect_review: architectReview, ralplan_critic_review: criticReview };
+            && isCriticNotBeforeArchitect(architectReview, criticReview)
+            && (!returnToRalplanCycle
+                || (advancedReviewCycle !== null && reviewPairCarriesFreshnessCycle(architectReview, criticReview, advancedReviewCycle)))) {
+            return { kind: 'valid', ralplan_architect_review: architectReview, ralplan_critic_review: criticReview };
         }
     }
     const architectReviews = Array.isArray(record.architectReviews) ? record.architectReviews : [];
@@ -168,31 +208,45 @@ function extractSequentialConsensusEvidence(value) {
         const criticReview = asRecord(criticReviews.at(-1));
         if (isApproveReview(architectReview, 'architect')
             && isApproveReview(criticReview, 'critic')
-            && isCriticNotBeforeArchitect(architectReview, criticReview)) {
-            return { ralplan_architect_review: architectReview, ralplan_critic_review: criticReview };
+            && isCriticNotBeforeArchitect(architectReview, criticReview)
+            && (!returnToRalplanCycle
+                || (advancedReviewCycle !== null && reviewPairCarriesFreshnessCycle(architectReview, criticReview, advancedReviewCycle)))) {
+            return { kind: 'valid', ralplan_architect_review: architectReview, ralplan_critic_review: criticReview };
         }
     }
     return null;
 }
-function extractInvalidCompleteConsensusEvidence(value) {
-    if (!value || typeof value !== 'object')
-        return null;
-    const record = value;
+function resolveDirectGate(record) {
     const gate = record.ralplanConsensusGate ?? record.ralplan_consensus_gate;
     if (gate && typeof gate === 'object') {
         const gateRecord = gate;
         const architectReview = asRecord(gateRecord.ralplan_architect_review ?? gateRecord.architectReview ?? gateRecord.architect_review);
         const criticReview = asRecord(gateRecord.ralplan_critic_review ?? gateRecord.criticReview ?? gateRecord.critic_review);
-        if (gateRecord.complete === true && hasArchitectThenCriticSequence(gateRecord)) {
+        if (gateRecord.complete === true
+            && hasArchitectThenCriticSequence(gateRecord)
+            && isApproveReview(architectReview, 'architect')
+            && isApproveReview(criticReview, 'critic')
+            && isCriticNotBeforeArchitect(architectReview, criticReview)) {
+            return {
+                kind: 'valid',
+                ralplan_architect_review: architectReview,
+                ralplan_critic_review: criticReview,
+            };
+        }
+        if (gateRecord.complete === true) {
             const blockedDetails = [
                 ...reviewApprovalProblems(architectReview, 'architect'),
                 ...reviewApprovalProblems(criticReview, 'critic'),
             ];
+            if (!hasArchitectThenCriticSequence(gateRecord)) {
+                blockedDetails.push('consensus review sequence is not architect-review then critic-review');
+            }
             if (!isCriticNotBeforeArchitect(architectReview, criticReview)) {
                 blockedDetails.push('critic review is ordered before architect review');
             }
             if (blockedDetails.length > 0) {
                 return {
+                    kind: 'invalid',
                     ralplan_architect_review: architectReview,
                     ralplan_critic_review: criticReview,
                     blockedDetails,
@@ -200,14 +254,93 @@ function extractInvalidCompleteConsensusEvidence(value) {
             }
         }
     }
-    const stateHandoffArtifacts = asRecord(asRecord(record.state)?.handoff_artifacts);
-    if (stateHandoffArtifacts) {
-        const evidence = extractInvalidCompleteConsensusEvidence(stateHandoffArtifacts);
-        if (evidence)
-            return evidence;
-    }
     return null;
 }
+export function withParentReturnToRalplanContext(value, parent) {
+    const reason = parent.return_to_ralplan_reason ?? parent.returnToRalplanReason;
+    if (typeof reason !== 'string' || reason.trim() === '' || !value || typeof value !== 'object' || Array.isArray(value)) {
+        return value;
+    }
+    const record = value;
+    const parentReviewCycle = numericValue(parent.return_to_ralplan_parent_review_cycle
+        ?? parent.returnToRalplanParentReviewCycle
+        ?? parent.review_cycle
+        ?? parent.reviewCycle);
+    const inheritedReviewCycle = record.review_cycle ?? record.reviewCycle ?? parent.review_cycle ?? parent.reviewCycle;
+    return {
+        ...record,
+        review_cycle: inheritedReviewCycle,
+        current_phase: parent.current_phase ?? parent.currentPhase ?? 'ralplan',
+        return_to_ralplan_reason: reason,
+        return_to_ralplan_parent_review_cycle: parentReviewCycle,
+    };
+}
+function explicitFreshnessReviewCycle(record) {
+    const parentReviewCycle = numericValue(record.return_to_ralplan_parent_review_cycle ?? record.returnToRalplanParentReviewCycle);
+    const candidateReviewCycle = numericValue(record.review_cycle ?? record.reviewCycle);
+    return parentReviewCycle !== null
+        && candidateReviewCycle !== null
+        && candidateReviewCycle > parentReviewCycle
+        ? candidateReviewCycle
+        : null;
+}
+function reviewsCarryFreshnessCycle(evidence, reviewCycle) {
+    return reviewPairCarriesFreshnessCycle(evidence.ralplan_architect_review, evidence.ralplan_critic_review, reviewCycle);
+}
+function isConsensusEvidenceNewerThanSelected(evidence, selected) {
+    if (!selected)
+        return true;
+    const evidenceCycle = consensusEvidenceReviewCycle(evidence);
+    const selectedCycle = consensusEvidenceReviewCycle(selected);
+    if (evidenceCycle !== null || selectedCycle !== null) {
+        if (selectedCycle === null)
+            return true;
+        if (evidenceCycle === null)
+            return false;
+        if (evidenceCycle !== selectedCycle)
+            return evidenceCycle > selectedCycle;
+    }
+    const evidenceOrder = consensusEvidenceOrder(evidence);
+    const selectedOrder = consensusEvidenceOrder(selected);
+    if (evidenceOrder !== null || selectedOrder !== null) {
+        if (selectedOrder === null)
+            return true;
+        if (evidenceOrder === null)
+            return false;
+        if (evidenceOrder !== selectedOrder)
+            return evidenceOrder > selectedOrder;
+    }
+    return false;
+}
+function consensusEvidenceReviewCycle(evidence) {
+    return maxKnownNumber(numericValue(evidence.ralplan_architect_review?.review_cycle ?? evidence.ralplan_architect_review?.reviewCycle), numericValue(evidence.ralplan_critic_review?.review_cycle ?? evidence.ralplan_critic_review?.reviewCycle));
+}
+function consensusEvidenceOrder(evidence) {
+    return maxKnownNumber(reviewOrderValue(evidence.ralplan_architect_review ?? {}), reviewOrderValue(evidence.ralplan_critic_review ?? {}));
+}
+function maxKnownNumber(left, right) {
+    if (left === null)
+        return right;
+    if (right === null)
+        return left;
+    return Math.max(left, right);
+}
+function hasExplicitReturnToRalplanReviewCycle(record) {
+    return numericValue(record.review_cycle ?? record.reviewCycle) !== null
+        || numericValue(record.return_to_ralplan_parent_review_cycle ?? record.returnToRalplanParentReviewCycle) !== null;
+}
+function reviewPairCarriesFreshnessCycle(architectReview, criticReview, reviewCycle) {
+    return reviewCarriesFreshnessCycle(architectReview, reviewCycle)
+        && reviewCarriesFreshnessCycle(criticReview, reviewCycle);
+}
+function reviewCarriesFreshnessCycle(review, reviewCycle) {
+    const cycle = numericValue(review?.review_cycle ?? review?.reviewCycle);
+    return cycle !== null && cycle >= reviewCycle;
+}
+function numericValue(value) {
+    const parsed = typeof value === 'number' ? value : typeof value === 'string' ? Number(value) : Number.NaN;
+    return Number.isFinite(parsed) ? parsed : null;
+}
 function asRecord(value) {
     return value && typeof value === 'object' ? value : null;
 }
@@ -288,9 +421,7 @@ function reviewOrderValue(review) {
     return null;
 }
 function hasTrackerBackedNativeRalplanLanes(evidence, options) {
-    const architectThreadId = nativeReviewThreadId(evidence.ralplan_architect_review);
-    const criticThreadId = nativeReviewThreadId(evidence.ralplan_critic_review);
-    if (!architectThreadId || !criticThreadId || architectThreadId === criticThreadId)
+    if (trackerBackedNativeReviewPairProblem(evidence, options))
         return false;
     return isTrackerBackedNativeReview(evidence.ralplan_architect_review, 'architect', options)
         && isTrackerBackedNativeReview(evidence.ralplan_critic_review, 'critic', options);
@@ -298,9 +429,86 @@ function hasTrackerBackedNativeRalplanLanes(evidence, options) {
 function nativeReviewThreadId(review) {
     return typeof review?.thread_id === 'string' ? review.thread_id.trim() : '';
 }
+function currentTransitionSessionId(evidence, options) {
+    const transitionSessionId = typeof options.sessionId === 'string' ? options.sessionId.trim() : '';
+    return transitionSessionId
+        || nativeReviewSessionId(evidence.ralplan_architect_review)
+        || nativeReviewSessionId(evidence.ralplan_critic_review);
+}
+function buildTrackerBackedNativeConsensusDiagnostic(evidence, options) {
+    const cwd = typeof options.cwd === 'string' ? options.cwd.trim() : '';
+    const trackerPath = cwd ? subagentTrackingPath(cwd) : '.omx/state/subagent-tracking.json';
+    const currentSessionId = currentTransitionSessionId(evidence, options);
+    const architectThreadId = nativeReviewThreadId(evidence.ralplan_architect_review);
+    const criticThreadId = nativeReviewThreadId(evidence.ralplan_critic_review);
+    return {
+        expected_schema: [
+            '.omx/state/subagent-tracking.json contains:',
+            'sessions["<current_session_id>"].threads["<architect_thread_id>"].kind = "subagent"',
+            'sessions["<current_session_id>"].threads["<critic_thread_id>"].kind = "subagent"',
+            'both threads have completed_at',
+            'architect and critic thread IDs are distinct',
+        ],
+        current_session_id: currentSessionId || null,
+        tracker_path: trackerPath,
+        architect: buildNativeReviewDiagnostic(evidence.ralplan_architect_review, 'architect', options),
+        critic: buildNativeReviewDiagnostic(evidence.ralplan_critic_review, 'critic', options),
+        distinct_thread_ids: architectThreadId && criticThreadId ? architectThreadId !== criticThreadId : null,
+        pair_problem: trackerBackedNativeReviewPairProblem(evidence, options),
+        remediation: [
+            'Re-run native ralplan Architect/Critic reviews.',
+            'Or repair the review artifact so agent_role, provenance_kind, session_id, thread_id, and tracker_path point to completed native subagent threads in the current tracker.',
+        ],
+        docs: 'docs/contracts/ralplan-consensus-gate.md',
+    };
+}
+function buildNativeReviewDiagnostic(review, agentRole, options) {
+    const cwd = typeof options.cwd === 'string' ? options.cwd.trim() : '';
+    const trackerPath = cwd ? subagentTrackingPath(cwd) : '.omx/state/subagent-tracking.json';
+    const problem = trackerBackedNativeReviewProblem(review, agentRole, options);
+    const sessionId = review
+        ? (typeof options.sessionId === 'string' && options.sessionId.trim()
+            ? options.sessionId.trim()
+            : nativeReviewSessionId(review))
+        : '';
+    const threadId = nativeReviewThreadId(review);
+    const tracking = cwd && sessionId ? readJsonState(trackerPath) : null;
+    const session = asRecord(asRecord(tracking?.sessions)?.[sessionId]);
+    const thread = asRecord(asRecord(session?.threads)?.[threadId]);
+    const completedAt = typeof thread?.completed_at === 'string' ? thread.completed_at.trim() : '';
+    return {
+        role: agentRole,
+        session_id: sessionId || null,
+        thread_id: threadId || null,
+        tracker_path: trackerPath,
+        session_found: Boolean(session),
+        thread_found: Boolean(thread),
+        kind: typeof thread?.kind === 'string' ? thread.kind : null,
+        completed: Boolean(completedAt),
+        problem,
+    };
+}
+function trackerBackedNativeReviewPairProblem(evidence, options) {
+    const architectThreadId = nativeReviewThreadId(evidence.ralplan_architect_review);
+    const criticThreadId = nativeReviewThreadId(evidence.ralplan_critic_review);
+    if (architectThreadId && criticThreadId && architectThreadId === criticThreadId) {
+        return 'architect and critic reviews must reference distinct native subagent tracker threads';
+    }
+    const transitionSessionId = typeof options.sessionId === 'string' ? options.sessionId.trim() : '';
+    const architectSessionId = transitionSessionId || nativeReviewSessionId(evidence.ralplan_architect_review);
+    const criticSessionId = transitionSessionId || nativeReviewSessionId(evidence.ralplan_critic_review);
+    if (!architectSessionId || !criticSessionId)
+        return null;
+    return architectSessionId === criticSessionId
+        ? null
+        : `architect and critic reviews must resolve to the same native subagent tracker session; architect session_id=${architectSessionId}, critic session_id=${criticSessionId}`;
+}
 function isTrackerBackedNativeReview(review, agentRole, options) {
     return trackerBackedNativeReviewProblem(review, agentRole, options) === null;
 }
+function nativeReviewSessionId(review) {
+    return typeof review?.session_id === 'string' ? review.session_id.trim() : '';
+}
 function trackerBackedNativeReviewProblem(review, agentRole, options) {
     const issues = [];
     if (!review)
@@ -316,18 +524,15 @@ function trackerBackedNativeReviewProblem(review, agentRole, options) {
             : '';
     const reviewSessionId = typeof review.session_id === 'string' ? review.session_id.trim() : '';
     const threadId = typeof review.thread_id === 'string' ? review.thread_id.trim() : '';
-    const artifactPath = typeof review.artifact_path === 'string' ? review.artifact_path.trim() : '';
     const trackerPath = typeof review.tracker_path === 'string' ? review.tracker_path.trim() : '';
     if (!sessionId)
         issues.push(`${agentRole} review cannot resolve session_id`);
-    if (!reviewSessionId || reviewSessionId !== sessionId)
-        issues.push(`${agentRole} review session_id=${reviewSessionId || 'missing'} does not match ${sessionId || 'missing'}`);
+    if (reviewSessionId && reviewSessionId !== sessionId)
+        issues.push(`${agentRole} review session_id=${reviewSessionId} does not match ${sessionId || 'missing'}`);
     if (!threadId)
         issues.push(`${agentRole} review missing thread_id`);
-    if (!artifactPath)
-        issues.push(`${agentRole} review missing artifact_path`);
-    if (!trackerPath || !trackerPath.endsWith('subagent-tracking.json'))
-        issues.push(`${agentRole} review missing subagent-tracking.json tracker_path`);
+    if (trackerPath && !trackerPath.endsWith('subagent-tracking.json'))
+        issues.push(`${agentRole} review tracker_path=${trackerPath} is not subagent-tracking.json`);
     const cwd = typeof options.cwd === 'string' ? options.cwd.trim() : '';
     if (!cwd)
         issues.push(`${agentRole} review cannot resolve cwd for tracker lookup`);
@@ -348,6 +553,9 @@ function trackerBackedNativeReviewProblem(review, agentRole, options) {
         return `${agentRole} tracker thread ${threadId} is the session leader`;
     if (thread.kind !== 'subagent')
         return `${agentRole} tracker thread ${threadId} has kind=${String(thread.kind || 'missing')}`;
+    const completedAt = typeof thread.completed_at === 'string' ? thread.completed_at.trim() : '';
+    if (!completedAt)
+        return `${agentRole} tracker thread ${threadId} is not completed`;
     return null;
 }
 function currentSessionNativeLeaderThreadId(cwd) {
@@ -399,6 +607,12 @@ function readLocalCurrentSessionIds(cwd) {
 function localBaseStateDir(cwd) {
     return join(resolveWorkingDirectoryForState(cwd), '.omx', 'state');
 }
+function sessionIdFromStateRoot(path) {
+    const normalized = path.replace(/\\/g, '/');
+    const match = /\/sessions\/([^/]+)$/.exec(normalized);
+    const sessionId = match?.[1];
+    return sessionId && validateLocalSessionId(sessionId).length > 0 ? sessionId : undefined;
+}
 function uniquePaths(paths) {
     return [...new Set(paths)];
 }