@open-agent-toolkit/cli 0.1.46 → 0.1.48

package/dist/commands/gate/index.js

@@ -3,16 +3,17 @@ import { createHash, randomUUID } from 'node:crypto';
 import { readdir, readFile } from 'node:fs/promises';
 import { basename, isAbsolute, join, relative } from 'node:path';
 import { buildCommandContext, } from '../../app/command-context.js';
-import { getFrontmatterBlock, getFrontmatterField, parseGeneratedTime, } from '../shared/frontmatter.js';
+import { getFrontmatterBlock, parseFrontmatterScalarFields, parseGeneratedTime, } from '../shared/frontmatter.js';
 import { readGlobalOptions } from '../shared/shared.utils.js';
 import { BUILTIN_EXEC_TARGETS, readOatConfig, readOatLocalConfig, readUserConfig, writeOatConfig, writeOatLocalConfig, writeUserConfig, } from '../../config/oat-config.js';
-import { resolveEffectiveConfig, resolveExecTargets, resolveGate, } from '../../config/resolve.js';
+import { resolveEffectiveConfig, resolveExecTargetViews, resolveExecTargets, resolveGate, } from '../../config/resolve.js';
 import { dirExists, fileExists } from '../../fs/io.js';
-import { normalizeToPosixPath, resolveProjectRoot } from '../../fs/paths.js';
+import { normalizeToPosixPath, resolveProjectRoot, validateRealPathWithinScope, } from '../../fs/paths.js';
 import { classifyModelFamily, } from '../../providers/identity/family.js';
 import { resolveIdentityConfidence, } from '../../providers/identity/provenance.js';
 import { parseDispatchStamps } from '../../providers/identity/stamp.js';
 import { Command } from 'commander';
+import YAML from 'yaml';
 import { parseReviewGateVerdict, severityDisplayName, } from './review-verdict.js';
 const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
@@ -25,6 +26,7 @@ const DEFAULT_DEPENDENCIES = {
     writeUserConfig,
     resolveEffectiveConfig,
     runProcess: runChildProcess,
+    parseReviewGateVerdict,
     processEnv: process.env,
 };
 const VALID_ON_FAILURE = ['block', 'prompt', 'warn'];
@@ -53,8 +55,11 @@ const VALID_IDENTITY_PROVENANCES = [
 const REVIEW_GATE_CONTEXT_NOTE = 'This review is gate-originated. If you run `oat-project-review-provide`, set `oat_review_invocation: gate` in the review artifact. Write a canonical review artifact with `### Critical`, `### Important`, `### Medium`, and `### Minor` headings in that order, using `None` for empty sections.';
 const GATE_CHECK_TIMEOUT_MS = 5_000;
 const GATE_EXEC_TIMEOUT_MS = 10 * 60 * 1_000;
-function reviewGateProjectContext(projectPath) {
-    return `Resolved OAT project path: ${projectPath}. Run the review for this project path.`;
+function reviewGateProjectContext(project) {
+    return [
+        `Resolved OAT project path: ${project.path}. Run the review for this project path.`,
+        `Project resolution source: ${project.source}.`,
+    ].join('\n');
 }
 function assembleReviewGatePrompt(segments) {
     return segments
@@ -62,6 +67,74 @@ function assembleReviewGatePrompt(segments) {
         .filter((segment) => segment.length > 0)
         .join('\n\n');
 }
+function normalizedTargetInvocation(target) {
+    const invocation = target.invocation;
+    return {
+        model: invocation?.model ?? 'unknown',
+        reasoningEffort: invocation?.reasoningEffort ?? 'unknown',
+        source: invocation ? 'exec-target-config' : 'unknown',
+    };
+}
+function createGateInvocationMetadata(runId, selected) {
+    const configuredInvocation = normalizedTargetInvocation(selected.target);
+    const selectedModel = selected.model;
+    const configuredModel = selected.target.invocation?.model;
+    if (selectedModel &&
+        configuredModel !== undefined &&
+        configuredModel !== selectedModel) {
+        throw new Error(`Exec target "${selected.id}" configures invocation model ${configuredModel}, but selected model ${selectedModel} would be executed.`);
+    }
+    return Object.freeze({
+        runId,
+        targetId: selected.id,
+        runtime: selected.target.runtime,
+        ...configuredInvocation,
+        ...(selectedModel
+            ? { model: selectedModel, source: 'exec-target-config' }
+            : {}),
+    });
+}
+function gateInvocationPromptContext(invocation) {
+    const frontmatter = YAML.stringify({
+        oat_gate_run_id: invocation.runId,
+        oat_gate_target: invocation.targetId,
+        oat_gate_runtime: invocation.runtime,
+        oat_invocation_model: invocation.model,
+        oat_invocation_reasoning_effort: invocation.reasoningEffort,
+        oat_invocation_source: invocation.source,
+    }).trimEnd();
+    return [
+        'Gate invocation metadata (copy these exact values into the gate review artifact frontmatter):',
+        frontmatter,
+    ].join('\n');
+}
+function corroborateGateInvocation(expected, actual, targetCorroboration) {
+    const invocationFields = [
+        ['targetId', expected.targetId, actual?.targetId],
+        ['runtime', expected.runtime, actual?.runtime],
+        ['model', expected.model, actual?.model],
+        ['reasoningEffort', expected.reasoningEffort, actual?.reasoningEffort],
+        ['source', expected.source, actual?.source],
+    ];
+    const invocation = invocationFields.some(([, , actualValue]) => !actualValue)
+        ? 'missing'
+        : invocationFields.every(([, expectedValue, actualValue]) => expectedValue === actualValue)
+            ? 'matched'
+            : 'mismatched';
+    return {
+        run: targetCorroboration.run,
+        project: targetCorroboration.project,
+        invocation,
+        expected: {
+            project: targetCorroboration.expectedProject,
+            invocation: expected,
+        },
+        actual: {
+            ...targetCorroboration.actual,
+            invocation: actual ?? null,
+        },
+    };
+}
 async function runChildProcess(command, args, options) {
     return new Promise((resolve, reject) => {
         let timedOut = false;
@@ -244,7 +317,26 @@ function parseExecTargetConfig(options) {
     return {
         runtime: trimRequired(options.runtime ?? '', '--runtime'),
         baseCommand: parseArgvJson(baseCommandJson, '--base-command-json'),
-        priority: parseNumericFlag(options.priority, '--priority', 0),
+        ...(options.priority !== undefined
+            ? { priority: parseNumericFlag(options.priority, '--priority', 0) }
+            : {}),
+        ...(options.invocationModel !== undefined ||
+            options.invocationReasoningEffort !== undefined
+            ? {
+                invocation: {
+                    ...(options.invocationModel !== undefined
+                        ? {
+                            model: trimRequired(options.invocationModel, '--invocation-model'),
+                        }
+                        : {}),
+                    ...(options.invocationReasoningEffort !== undefined
+                        ? {
+                            reasoningEffort: trimRequired(options.invocationReasoningEffort, '--invocation-reasoning-effort'),
+                        }
+                        : {}),
+                },
+            }
+            : {}),
         ...(options.hostDetectionJson !== undefined
             ? {
                 hostDetectionCommand: parseOptionalArgvJson(options.hostDetectionJson, '--host-detection-json'),
@@ -286,13 +378,32 @@ function unsetSkillGate(config, skillName) {
     });
 }
 function setExecTarget(config, targetId, target) {
-    return updateWorkflowGates(config, (gates) => ({
-        ...gates,
-        execTargets: {
-            ...gates.execTargets,
-            [targetId]: target,
-        },
-    }));
+    return updateWorkflowGates(config, (gates) => {
+        const existing = gates.execTargets?.[targetId];
+        const value = target === null
+            ? target
+            : existing === null || existing === undefined
+                ? { priority: 0, ...target }
+                : {
+                    ...existing,
+                    ...target,
+                    ...(existing.invocation || target.invocation
+                        ? {
+                            invocation: {
+                                ...existing.invocation,
+                                ...target.invocation,
+                            },
+                        }
+                        : {}),
+                };
+        return {
+            ...gates,
+            execTargets: {
+                ...gates.execTargets,
+                [targetId]: value,
+            },
+        };
+    });
 }
 function unsetExecTarget(config, targetId) {
     return updateWorkflowGates(config, (gates) => {
@@ -322,6 +433,7 @@ function cloneExecTarget(target) {
         runtime: target.runtime,
         baseCommand: [...target.baseCommand],
         priority: target.priority,
+        ...(target.invocation ? { invocation: { ...target.invocation } } : {}),
         ...(target.models ? { models: [...target.models] } : {}),
         ...(target.hostDetectionCommand
             ? { hostDetectionCommand: [...target.hostDetectionCommand] }
@@ -363,17 +475,32 @@ function parseProducerIdentityOption(value) {
     }
     return identityFromRecords([{ value: producer, provenance: provenance }], 'flag');
 }
-function identityFromStamps(stamps) {
-    const identities = stamps
-        .map((stamp) => identityFromRecords([{ value: stamp.producer, provenance: stamp.provenance }], 'stamp'))
-        .filter((identity) => identity.diversityClaimable && identity.family !== 'unknown');
-    const latest = identities.at(-1);
-    if (!latest) {
+function identityFromStamp(stamp) {
+    return identityFromRecords([{ value: stamp.producer, provenance: stamp.provenance }], 'stamp');
+}
+function exactIdentityFromStamp(stamp) {
+    const identity = identityFromStamp(stamp);
+    return identity.diversityClaimable && identity.family !== 'unknown'
+        ? identity
+        : unknownProducerIdentity();
+}
+function aggregateIdentityFromStamps(stamps) {
+    if (stamps.length === 0) {
         return unknownProducerIdentity();
     }
+    const identities = stamps.map(identityFromStamp);
+    const avoidFamilies = [
+        ...new Set(identities.flatMap((identity) => identity.diversityClaimable && identity.family !== 'unknown'
+            ? [identity.family]
+            : [])),
+    ];
     return {
-        ...latest,
-        avoidFamilies: [...new Set(identities.map((identity) => identity.family))],
+        ...unknownProducerIdentity(),
+        avoidFamilies,
+        contributingScopes: [...new Set(stamps.map((stamp) => stamp.scope))],
+        contributingStampCount: stamps.length,
+        diversityClaimable: avoidFamilies.length > 0,
+        source: 'aggregated-stamps',
     };
 }
 function phaseNumber(scope) {
@@ -383,7 +510,7 @@ function phaseNumber(scope) {
 }
 function reviewScopeRange(scope) {
     if (scope === 'final') {
-        return { start: 1, end: Number.MAX_SAFE_INTEGER };
+        return { start: 0, end: Number.MAX_SAFE_INTEGER };
     }
     const range = scope.match(/^p(\d+)-p(\d+)$/);
     if (!range) {
@@ -417,13 +544,15 @@ async function readStampedProducerIdentity(options) {
         return unknownProducerIdentity();
     }
     const stamps = parseDispatchStamps(markdown).filter((candidate) => candidate.role === 'implementer' || candidate.role === 'fix');
-    const exactStamp = [...stamps]
-        .reverse()
-        .find((candidate) => candidate.scope === scope);
-    if (exactStamp) {
-        return identityFromStamps([exactStamp]);
+    if (!reviewScopeRange(scope)) {
+        const exactStamp = [...stamps]
+            .reverse()
+            .find((candidate) => candidate.scope === scope);
+        return exactStamp
+            ? exactIdentityFromStamp(exactStamp)
+            : unknownProducerIdentity();
     }
-    return identityFromStamps(stamps.filter((candidate) => stampInReviewScope(candidate.scope, scope)));
+    return aggregateIdentityFromStamps(stamps.filter((candidate) => stampInReviewScope(candidate.scope, scope)));
 }
 async function resolveReviewProducerIdentity(options) {
     if (options.explicit?.trim()) {
@@ -480,7 +609,7 @@ function expandExecTargetCandidates(id, target) {
     }));
 }
 function producerHasKnownFamily(identity) {
-    return identity.diversityClaimable && identity.avoidFamilies.length > 0;
+    return identity.avoidFamilies.length > 0;
 }
 function shouldAttemptNoDiverseFallback(avoid) {
     return avoid === 'same-family';
@@ -493,7 +622,9 @@ function achievedDiversity(selected, producerIdentity) {
         !producerIdentity.avoidFamilies.includes(selected.family)) {
         return 'different-family';
     }
-    if (selected.model && selected.model !== producerIdentity.value) {
+    if (producerIdentity.source !== 'aggregated-stamps' &&
+        selected.model &&
+        selected.model !== producerIdentity.value) {
         return 'degraded-to-different-slug';
     }
     return 'same-family - no diverse target available';
@@ -523,6 +654,14 @@ function attachDiversityMetadata(selected, avoid, producerIdentity) {
                 family: producerIdentity.family,
                 source: producerIdentity.source,
                 avoidFamilies: producerIdentity.avoidFamilies,
+                ...(producerIdentity.contributingScopes
+                    ? { contributingScopes: producerIdentity.contributingScopes }
+                    : {}),
+                ...(producerIdentity.contributingStampCount === undefined
+                    ? {}
+                    : {
+                        contributingStampCount: producerIdentity.contributingStampCount,
+                    }),
             },
             reviewer: {
                 target: selected.id,
@@ -719,11 +858,21 @@ async function listProjectCandidates(repoRoot, projectsRoot) {
 async function assertProjectPath(repoRoot, projectPath, source) {
     const normalizedPath = normalizeRepoRelativeProjectPath(repoRoot, projectPath);
     const absolutePath = join(repoRoot, normalizedPath);
-    if (!(await dirExists(absolutePath)) ||
-        !(await fileExists(join(absolutePath, 'state.md')))) {
+    let realProjectPath;
+    let canonicalPath;
+    try {
+        const validated = await validateRealPathWithinScope(absolutePath, repoRoot);
+        realProjectPath = validated.realPath;
+        canonicalPath = normalizeRepoRelativeProjectPath(validated.realScopeRoot, validated.realPath);
+    }
+    catch {
+        throw new Error(`${source} project "${projectPath}" must resolve inside the current repository through a readable real path.`);
+    }
+    if (!(await dirExists(realProjectPath)) ||
+        !(await fileExists(join(realProjectPath, 'state.md')))) {
         throw new Error(`${source} project "${projectPath}" does not resolve to a project directory containing state.md.`);
     }
-    return normalizedPath;
+    return canonicalPath;
 }
 async function resolveExplicitReviewProject(repoRoot, projectsRoot, projectValue) {
     const trimmed = projectValue.trim();
@@ -744,16 +893,25 @@ async function resolveExplicitReviewProject(repoRoot, projectsRoot, projectValue
     }
     return assertProjectPath(repoRoot, `${projectsRoot}/${trimmed}`, '--project');
 }
-async function resolveReviewProject(options) {
-    const projectsRoot = String(options.effective.resolved['projects.root']?.value ??
-        options.effective.shared.projects?.root ??
+function resolvedProjectsRoot(effective) {
+    return String(effective.resolved['projects.root']?.value ??
+        effective.shared.projects?.root ??
         '.oat/projects/shared');
+}
+async function resolveReviewProject(options) {
+    const projectsRoot = resolvedProjectsRoot(options.effective);
     if (options.project !== undefined) {
-        return resolveExplicitReviewProject(options.repoRoot, projectsRoot, options.project);
+        return {
+            path: await resolveExplicitReviewProject(options.repoRoot, projectsRoot, options.project),
+            source: 'declared',
+        };
     }
     const activeProject = options.effective.local.activeProject?.trim();
     if (activeProject) {
-        return assertProjectPath(options.repoRoot, activeProject, 'Active');
+        return {
+            path: await assertProjectPath(options.repoRoot, activeProject, 'Active'),
+            source: 'active-project',
+        };
     }
     const candidates = await listProjectCandidates(options.repoRoot, projectsRoot);
     if (candidates.length === 0) {
@@ -762,7 +920,10 @@ async function resolveReviewProject(options) {
     if (candidates.length > 1) {
         throw new Error(`Multiple OAT projects could be resolved for gate review: ${candidates.join(', ')}. Pass --project <path-or-name>.`);
     }
-    return candidates[0];
+    return {
+        path: candidates[0],
+        source: 'single-candidate',
+    };
 }
 function reviewGateLifecycleRank(scope) {
     const normalizedScope = scope.trim().toLowerCase();
@@ -778,21 +939,27 @@ function reviewGateLifecycleRank(scope) {
     const latestTask = tasks.length > 0 ? Math.max(...tasks) : 9999;
     return latestPhase * 10_000 + latestTask;
 }
-async function readReviewGateArtifactCandidate(repoRoot, relativePath) {
+async function readReviewGateArtifactCandidate(repoRoot, containingProject, relativePath) {
     const content = await readFile(join(repoRoot, relativePath), 'utf8');
     const frontmatter = getFrontmatterBlock(content);
     if (!frontmatter) {
         return null;
     }
-    const generatedAt = getFrontmatterField(frontmatter, 'oat_generated_at');
-    if (!generatedAt) {
-        return null;
-    }
-    const generatedTime = parseGeneratedTime(generatedAt);
-    if (Number.isNaN(generatedTime)) {
-        return null;
-    }
-    const scope = getFrontmatterField(frontmatter, 'oat_review_scope') ?? '';
+    const scalarFields = parseFrontmatterScalarFields(frontmatter, [
+        'oat_generated_at',
+        'oat_review_scope',
+        'oat_gate_run_id',
+        'oat_project',
+    ]);
+    const frontmatterString = (key) => scalarFields.values[key] ?? null;
+    const generatedAt = frontmatterString('oat_generated_at');
+    const parsedGeneratedTime = generatedAt
+        ? parseGeneratedTime(generatedAt)
+        : Number.NaN;
+    const generatedTime = Number.isNaN(parsedGeneratedTime)
+        ? Number.NEGATIVE_INFINITY
+        : parsedGeneratedTime;
+    const scope = frontmatterString('oat_review_scope') ?? '';
     return {
         path: relativePath,
         scope,
@@ -800,9 +967,13 @@ async function readReviewGateArtifactCandidate(repoRoot, relativePath) {
         kind: 'project',
         archived: false,
         actionable: true,
+        containingProject,
+        gateRunId: frontmatterString('oat_gate_run_id'),
+        artifactProject: frontmatterString('oat_project'),
         generatedTime,
         lifecycleRank: reviewGateLifecycleRank(scope),
         signature: createHash('sha256').update(content).digest('hex'),
+        content,
     };
 }
 function sortReviewGateArtifacts(left, right) {
@@ -834,14 +1005,77 @@ async function listActiveProjectReviewCandidates(options) {
     }
     return (await Promise.all(entries
         .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
-        .map((entry) => readReviewGateArtifactCandidate(options.repoRoot, normalizeToPosixPath(join(reviewsDir, entry.name))))))
+        .map((entry) => readReviewGateArtifactCandidate(options.repoRoot, projectPath, normalizeToPosixPath(join(reviewsDir, entry.name))))))
         .filter((candidate) => candidate !== null)
         .sort(sortReviewGateArtifacts);
 }
+async function listReviewGateArtifactCandidates(options) {
+    const configuredProjects = await listProjectCandidates(options.repoRoot, resolvedProjectsRoot(options.effective));
+    const projectPaths = [
+        ...new Set([...configuredProjects, options.reviewProject.path]),
+    ];
+    const candidates = await Promise.all(projectPaths.map((projectPath) => listActiveProjectReviewCandidates({
+        repoRoot: options.repoRoot,
+        projectPath,
+    })));
+    return candidates.flat().sort(sortReviewGateArtifacts);
+}
 function findProducedReviewArtifact(before, after) {
     const beforeSignatures = new Map(before.map((candidate) => [candidate.path, candidate.signature]));
     return (after.find((candidate) => beforeSignatures.get(candidate.path) !== candidate.signature) ?? null);
 }
+function resolveRunCorrelatedReviewArtifact(options) {
+    const matches = options.after.filter((candidate) => candidate.gateRunId === options.runId);
+    const artifact = matches.length === 1 ? matches[0] : null;
+    return {
+        artifact,
+        diagnosticArtifact: artifact ?? findProducedReviewArtifact(options.before, options.after),
+        matchingArtifactPaths: matches.map((candidate) => candidate.path).sort(),
+    };
+}
+function normalizeArtifactProject(repoRoot, artifactProject) {
+    if (!artifactProject) {
+        return null;
+    }
+    try {
+        const normalized = normalizeRepoRelativeProjectPath(repoRoot, artifactProject);
+        return normalized || null;
+    }
+    catch {
+        return null;
+    }
+}
+function corroborateReviewTarget(options) {
+    const actualArtifact = options.artifact ?? options.diagnosticArtifact;
+    const normalizedArtifactProject = normalizeArtifactProject(options.repoRoot, actualArtifact?.artifactProject ?? null);
+    const run = options.matchingArtifactPaths.length > 1
+        ? 'mismatched'
+        : actualArtifact?.gateRunId === options.gateInvocation.runId
+            ? 'matched'
+            : actualArtifact?.gateRunId
+                ? 'mismatched'
+                : 'missing';
+    let project = 'ambient';
+    if (options.reviewProject.source === 'declared') {
+        project = !actualArtifact?.artifactProject
+            ? 'missing'
+            : actualArtifact.containingProject === options.reviewProject.path &&
+                normalizedArtifactProject === options.reviewProject.path
+                ? 'matched'
+                : 'mismatched';
+    }
+    return {
+        run,
+        project,
+        expectedProject: options.reviewProject.path,
+        actual: {
+            containingProject: actualArtifact?.containingProject ?? null,
+            artifactProject: actualArtifact?.artifactProject ?? null,
+            normalizedArtifactProject,
+            matchingArtifactPaths: options.matchingArtifactPaths,
+        },
+    };
+}
 function reviewBlocksAtThreshold(verdict, threshold) {
     if (verdict.counts.critical > 0) {
         return true;
@@ -890,14 +1124,16 @@ function reviewGateOutcome(payload) {
 function writeReviewGateResult(context, payload) {
     const outcome = reviewGateOutcome(payload);
     if (context.json) {
-        context.logger.json({ outcome, ...payload });
+        context.logger.json({ outcome, ...payload, receiveEligible: true });
         return;
     }
     if (outcome === 'review_completed_blocking_findings') {
         context.logger.info('Review completed and found blocking issues.');
     }
     else if (outcome === 'review_completed_artifact_normalized_gate_passed') {
-        context.logger.info('Review completed, artifact was normalized, and gate passed.');
+        context.logger.info(payload.normalization?.persisted
+            ? 'Review completed, artifact was normalized, and gate passed.'
+            : 'Review completed, the immutable artifact snapshot was normalized in memory, and gate passed.');
     }
     else {
         context.logger.info('Review completed and gate passed.');
@@ -905,7 +1141,7 @@ function writeReviewGateResult(context, payload) {
     context.logger.info(`Run: ${payload.runId} (generated ${payload.generatedAt})`);
     context.logger.info(`Review artifact: ${payload.artifactPath}`);
     if (payload.normalization) {
-        context.logger.info(`Artifact normalized: inserted ${payload.normalization.insertedSeverities.map((severity) => severityDisplayName(severity)).join(', ')} empty Findings section(s).`);
+        context.logger.info(`${payload.normalization.persisted ? 'Artifact normalized' : 'Artifact snapshot normalized in memory; source file unchanged'}: inserted ${payload.normalization.insertedSeverities.map((severity) => severityDisplayName(severity)).join(', ')} empty Findings section(s).`);
     }
     context.logger.info(`Verdict: ${payload.status} (critical=${payload.counts.critical}, important=${payload.counts.important}, medium=${payload.counts.medium}, minor=${payload.counts.minor})`);
     if (payload.diversity) {
@@ -927,6 +1163,11 @@ function writeReviewGateExecutionFailure(context, payload) {
             runId: payload.runId,
             target: payload.target,
             project: payload.project,
+            projectResolutionSource: payload.projectResolutionSource,
+            gateInvocation: payload.gateInvocation,
+            ...(payload.corroboration
+                ? { corroboration: payload.corroboration }
+                : {}),
             exitCode: payload.exitCode,
             timedOut: payload.timedOut ?? false,
             ...(payload.timeoutMs !== undefined
@@ -938,6 +1179,25 @@ function writeReviewGateExecutionFailure(context, payload) {
     }
     context.logger.error(message);
 }
+function writeReviewGateUnexpectedFailure(context, payload) {
+    const message = payload.error instanceof Error
+        ? payload.error.message
+        : String(payload.error);
+    if (context.json) {
+        context.logger.json({
+            status: 'review_failed',
+            outcome: 'unexpected_post_selection_failure',
+            runId: payload.gateInvocation.runId,
+            target: payload.target,
+            project: payload.project,
+            projectResolutionSource: payload.projectResolutionSource,
+            gateInvocation: payload.gateInvocation,
+            message,
+        });
+        return;
+    }
+    context.logger.error(`Review failed after target selection for ${payload.target}: ${message}`);
+}
 function writeReviewGateArtifactValidationFailure(context, payload) {
     if (context.json) {
         context.logger.json({
@@ -946,8 +1206,15 @@ function writeReviewGateArtifactValidationFailure(context, payload) {
             runId: payload.runId,
             target: payload.target,
             project: payload.project,
+            projectResolutionSource: payload.projectResolutionSource,
             artifactPath: payload.artifactPath,
             generatedAt: payload.generatedAt,
+            gateInvocation: payload.gateInvocation,
+            ...(payload.corroboration
+                ? { corroboration: payload.corroboration }
+                : {}),
+            receiveEligible: false,
+            handoff: null,
             message: payload.message,
             recovery: payload.recovery,
         });
@@ -956,6 +1223,43 @@ function writeReviewGateArtifactValidationFailure(context, payload) {
     context.logger.error(`Review completed but artifact validation failed: ${payload.message}`);
     context.logger.error(payload.recovery);
 }
+function writeReviewGateTargetingFailure(context, payload) {
+    const corroboration = {
+        run: payload.corroboration.run,
+        project: payload.corroboration.project,
+        invocation: 'missing',
+        expected: {
+            project: payload.corroboration.expectedProject,
+            invocation: payload.gateInvocation,
+        },
+        actual: {
+            ...payload.corroboration.actual,
+            invocation: null,
+        },
+    };
+    if (context.json) {
+        context.logger.json({
+            status: 'targeting_correlation_failed',
+            outcome: 'review_completed_targeting_correlation_failed',
+            runId: payload.runId,
+            target: payload.target,
+            project: payload.project,
+            projectResolutionSource: payload.projectResolutionSource,
+            artifactPath: payload.artifactPath,
+            generatedAt: payload.generatedAt,
+            gateInvocation: payload.gateInvocation,
+            corroboration,
+            receiveEligible: false,
+            remediable: false,
+            handoff: null,
+            message: payload.message,
+        });
+        return;
+    }
+    context.logger.error(`Review completed but target correlation failed: ${payload.message}`);
+    context.logger.error(`Expected project=${payload.corroboration.expectedProject} run=${payload.gateInvocation.runId}; actual containing_project=${payload.corroboration.actual.containingProject ?? 'missing'} artifact_project=${payload.corroboration.actual.artifactProject ?? 'missing'} run_matches=${payload.corroboration.actual.matchingArtifactPaths.join(',') || 'none'}.`);
+    context.logger.error('This targeting failure is not receive-eligible and must be corrected before severity or invocation remediation.');
+}
 async function updateConfigLayer(context, layer, dependencies, mutate) {
     const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
     const userConfigDir = join(context.home, '.oat');
@@ -1045,6 +1349,39 @@ async function runTargetUnset(targetId, options, context, dependencies) {
         writeError(context, error);
     }
 }
+async function runTargetList(context, dependencies) {
+    try {
+        const views = resolveExecTargetViews(await readEffectiveConfig(context, dependencies));
+        const targets = await Promise.all(Object.entries(views)
+            .sort(([leftId, left], [rightId, right]) => {
+            const priority = right.target.priority - left.target.priority;
+            return priority === 0 ? leftId.localeCompare(rightId) : priority;
+        })
+            .map(async ([id, view]) => {
+            const availabilityCommand = view.target.availabilityCommand;
+            const available = view.enabled &&
+                (!availabilityCommand ||
+                    (await checkArgv(availabilityCommand, 'availability', context, dependencies)));
+            const invocation = normalizedTargetInvocation(view.target);
+            return {
+                id,
+                runtime: view.target.runtime,
+                origin: view.origin,
+                explicitlyConfigured: view.explicitlyConfigured,
+                enabled: view.enabled,
+                available,
+                invocation: {
+                    ...invocation,
+                },
+            };
+        }));
+        writeSuccess(context, { targets });
+        process.exitCode = 0;
+    }
+    catch (error) {
+        writeError(context, error);
+    }
+}
 async function runCrossProviderExec(prompt, options, context, dependencies) {
     try {
         const effective = await readEffectiveConfig(context, dependencies);
@@ -1061,15 +1398,17 @@ async function runCrossProviderExec(prompt, options, context, dependencies) {
 }
 async function runReviewGate(prompt, options, context, dependencies) {
     const runId = randomUUID();
+    let postSelectionContext;
     try {
         const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
         const userConfigDir = join(context.home, '.oat');
         const effective = await dependencies.resolveEffectiveConfig(repoRoot, userConfigDir, dependencies.processEnv);
-        const projectPath = await resolveReviewProject({
+        const reviewProject = await resolveReviewProject({
             repoRoot,
             effective,
             project: options.project,
         });
+        const projectPath = reviewProject.path;
         const targets = resolveExecTargets(effective);
         const producerIdentity = await resolveReviewProducerIdentity({
             explicit: options.producerIdentity,
@@ -1078,14 +1417,23 @@ async function runReviewGate(prompt, options, context, dependencies) {
             reviewScope: options.reviewScope,
         });
         const selected = await resolveSelectedExecTarget(targets, options, producerIdentity, context, dependencies);
+        const gateInvocation = createGateInvocationMetadata(runId, selected);
+        postSelectionContext = {
+            project: projectPath,
+            projectResolutionSource: reviewProject.source,
+            target: selected.id,
+            gateInvocation,
+        };
         const threshold = parseReviewGateThreshold(options.exitNonzeroOn);
-        const before = await listActiveProjectReviewCandidates({
+        const before = await listReviewGateArtifactCandidates({
             repoRoot,
-            projectPath,
+            effective,
+            reviewProject,
         });
         const reviewPrompt = assembleReviewGatePrompt([
             REVIEW_GATE_CONTEXT_NOTE,
-            reviewGateProjectContext(projectPath),
+            reviewGateProjectContext(reviewProject),
+            gateInvocationPromptContext(gateInvocation),
             ...(options.reviewType?.trim()
                 ? [`Review type: ${options.reviewType.trim()}.`]
                 : []),
@@ -1101,35 +1449,101 @@ async function runReviewGate(prompt, options, context, dependencies) {
                 runId,
                 target: selected.id,
                 project: projectPath,
+                projectResolutionSource: reviewProject.source,
                 exitCode: childExitCode,
                 timedOut: childResult.timedOut ?? false,
                 timeoutMs: resolveGateExecTimeoutMs(dependencies.processEnv),
+                gateInvocation,
             });
             process.exitCode = childExitCode;
             return;
         }
-        const after = await listActiveProjectReviewCandidates({
+        const after = await listReviewGateArtifactCandidates({
             repoRoot,
-            projectPath,
+            effective,
+            reviewProject,
+        });
+        const artifactResolution = resolveRunCorrelatedReviewArtifact({
+            runId,
+            before,
+            after,
+        });
+        const initialTargetCorroboration = corroborateReviewTarget({
+            repoRoot,
+            reviewProject,
+            gateInvocation,
+            artifact: artifactResolution.artifact,
+            diagnosticArtifact: artifactResolution.diagnosticArtifact,
+            matchingArtifactPaths: artifactResolution.matchingArtifactPaths,
         });
-        const producedArtifact = findProducedReviewArtifact(before, after);
+        const producedArtifact = artifactResolution.artifact;
         if (!producedArtifact) {
+            const diagnosticArtifact = artifactResolution.diagnosticArtifact;
+            const message = artifactResolution.matchingArtifactPaths.length > 1
+                ? `Multiple direct review artifacts carried gate run ID ${runId}.`
+                : initialTargetCorroboration.run === 'mismatched'
+                    ? `The changed review artifact did not carry the expected gate run ID ${runId}.`
+                    : `No direct active project review artifact carried gate run ID ${runId}.`;
+            writeReviewGateTargetingFailure(context, {
+                runId,
+                target: selected.id,
+                project: projectPath,
+                projectResolutionSource: reviewProject.source,
+                artifactPath: diagnosticArtifact?.path ?? null,
+                generatedAt: diagnosticArtifact?.generatedAt ?? null,
+                message,
+                gateInvocation,
+                corroboration: initialTargetCorroboration,
+            });
+            process.exitCode = 1;
+            return;
+        }
+        if (producedArtifact.containingProject !== reviewProject.path ||
+            (reviewProject.source === 'declared' &&
+                initialTargetCorroboration.project !== 'matched')) {
+            writeReviewGateTargetingFailure(context, {
+                runId,
+                target: selected.id,
+                project: projectPath,
+                projectResolutionSource: reviewProject.source,
+                artifactPath: producedArtifact.path,
+                generatedAt: producedArtifact.generatedAt,
+                message: producedArtifact.containingProject !== reviewProject.path
+                    ? 'Review artifact was written outside the resolved review project.'
+                    : initialTargetCorroboration.project === 'missing'
+                        ? 'Review artifact is missing oat_project for the explicitly declared project.'
+                        : 'Review artifact project identity does not match the explicitly declared project.',
+                gateInvocation,
+                corroboration: initialTargetCorroboration,
+            });
+            process.exitCode = 1;
+            return;
+        }
+        if (!producedArtifact.generatedAt ||
+            !Number.isFinite(producedArtifact.generatedTime)) {
             writeReviewGateArtifactValidationFailure(context, {
                 runId,
                 target: selected.id,
                 project: projectPath,
-                artifactPath: null,
-                generatedAt: null,
-                message: `No new review artifact was detected for project ${projectPath}.`,
-                recovery: 'Ensure the review provider wrote a project review artifact. If it did, fix or attach that artifact and run oat-project-review-receive before treating the review as consumed.',
+                projectResolutionSource: reviewProject.source,
+                artifactPath: producedArtifact.path,
+                generatedAt: producedArtifact.generatedAt,
+                message: 'Review artifact oat_generated_at is missing or is not a valid timestamp.',
+                recovery: `Set oat_generated_at to a valid timestamp in ${producedArtifact.path}, then rerun the gate. Invoke oat-project-review-receive only after the gate returns a receive-eligible result.`,
+                gateInvocation,
+                corroboration: corroborateGateInvocation(gateInvocation, undefined, initialTargetCorroboration),
             });
             process.exitCode = 1;
             return;
         }
         let verdict;
         try {
-            verdict = await parseReviewGateVerdict(join(repoRoot, producedArtifact.path), {
+            verdict = await dependencies.parseReviewGateVerdict(join(repoRoot, producedArtifact.path), {
                 normalizeMissingEmptySeveritySections: true,
+                artifactSnapshot: {
+                    content: producedArtifact.content,
+                    signature: producedArtifact.signature,
+                },
             });
         }
         catch (error) {
@@ -1138,10 +1552,52 @@ async function runReviewGate(prompt, options, context, dependencies) {
                 runId,
                 target: selected.id,
                 project: projectPath,
+                projectResolutionSource: reviewProject.source,
                 artifactPath: producedArtifact.path,
                 generatedAt: producedArtifact.generatedAt,
                 message: detail,
-                recovery: `The review artifact was created at ${producedArtifact.path} but could not be consumed. Fix the artifact format, then run oat-project-review-receive for ${producedArtifact.path}; if the only issue is a missing zero-count severity heading, rerun the gate to normalize the same artifact instead of creating a new review version.`,
+                recovery: `The review artifact was created at ${producedArtifact.path} but could not be consumed. Fix the artifact format, then rerun the gate to revalidate it. Invoke oat-project-review-receive only after the gate returns a receive-eligible result; if the only issue is a missing zero-count severity heading, rerun the gate to normalize the same artifact instead of creating a new review version.`,
+                gateInvocation,
+                corroboration: corroborateGateInvocation(gateInvocation, undefined, initialTargetCorroboration),
+            });
+            process.exitCode = 1;
+            return;
+        }
+        const targetCorroboration = initialTargetCorroboration;
+        const corroboration = corroborateGateInvocation(gateInvocation, verdict.gateInvocation, targetCorroboration);
+        if (corroboration.run !== 'matched' ||
+            corroboration.invocation !== 'matched') {
+            const missing = corroboration.run === 'missing' ||
+                corroboration.invocation === 'missing';
+            writeReviewGateArtifactValidationFailure(context, {
+                runId,
+                target: selected.id,
+                project: projectPath,
+                projectResolutionSource: reviewProject.source,
+                artifactPath: producedArtifact.path,
+                generatedAt: producedArtifact.generatedAt,
+                message: missing
+                    ? 'Review artifact invocation metadata is missing required gate-owned values.'
+                    : 'Review artifact invocation metadata does not match the gate-owned configured invocation.',
+                recovery: `Copy the exact gate invocation fields from the review prompt into ${producedArtifact.path}, then run oat-project-review-receive only after the artifact validates.`,
+                gateInvocation,
+                corroboration,
+            });
+            process.exitCode = 1;
+            return;
+        }
+        if (verdict.invocation !== 'gate') {
+            writeReviewGateArtifactValidationFailure(context, {
+                runId,
+                target: selected.id,
+                project: projectPath,
+                projectResolutionSource: reviewProject.source,
+                artifactPath: producedArtifact.path,
+                generatedAt: producedArtifact.generatedAt,
+                message: 'Review artifact is missing the required gate invocation marker `oat_review_invocation: gate`.',
+                recovery: `Set oat_review_invocation: gate in ${producedArtifact.path}, then run oat-project-review-receive only after the artifact validates.`,
+                gateInvocation,
+                corroboration,
             });
             process.exitCode = 1;
             return;
@@ -1158,6 +1614,7 @@ async function runReviewGate(prompt, options, context, dependencies) {
             runId,
             target: selected.id,
             project: projectPath,
+            projectResolutionSource: reviewProject.source,
             artifactPath: producedArtifact.path,
             generatedAt: producedArtifact.generatedAt,
             threshold,
@@ -1169,11 +1626,22 @@ async function runReviewGate(prompt, options, context, dependencies) {
             normalization: verdict.normalization,
             handoff,
             diversity: selected.diversity,
+            gateInvocation,
+            corroboration,
         });
         process.exitCode = blocking ? 1 : 0;
     }
     catch (error) {
-        writeError(context, error);
+        if (postSelectionContext) {
+            writeReviewGateUnexpectedFailure(context, {
+                ...postSelectionContext,
+                error,
+            });
+            process.exitCode = 1;
+        }
+        else {
+            writeError(context, error);
+        }
     }
 }
 export function createGateCommand(overrides = {}) {
@@ -1250,6 +1718,8 @@ export function createGateCommand(overrides = {}) {
         .option('--base-command-json <json>', 'JSON argv array for the base command')
         .option('--host-detection-json <json>', 'JSON argv array for host detection')
         .option('--availability-json <json>', 'JSON argv array for availability')
+        .option('--invocation-model <model>', 'Configured invocation model or provider-default')
+        .option('--invocation-reasoning-effort <effort>', 'Configured reasoning effort or provider-default')
         .option('--priority <number>', 'Target priority, higher wins')
         .option('--disable', 'Disable this exec target in the selected layer')
         .option('--layer <layer>', 'Config layer to write: shared, local, or user')
@@ -1257,6 +1727,13 @@ export function createGateCommand(overrides = {}) {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));
         await runTargetSet(targetId, options, context, dependencies);
     });
+    target
+        .command('list')
+        .description('List resolved exec targets and configuration provenance')
+        .action(async (_options, command) => {
+        const context = dependencies.buildCommandContext(readGlobalOptions(command));
+        await runTargetList(context, dependencies);
+    });
     target
         .command('unset')
         .description('Remove an exec target entry from a concrete config layer')