@neurcode-ai/cli 0.9.36 → 0.9.38

package/dist/commands/verify.js

@@ -44,6 +44,7 @@ const git_1 = require("../utils/git");
 const diff_parser_1 = require("@neurcode-ai/diff-parser");
 const policy_engine_1 = require("@neurcode-ai/policy-engine");
 const governance_runtime_1 = require("@neurcode-ai/governance-runtime");
+const contracts_1 = require("@neurcode-ai/contracts");
 const config_1 = require("../config");
 const api_client_1 = require("../api-client");
 const path_1 = require("path");
@@ -63,6 +64,7 @@ const policy_audit_1 = require("../utils/policy-audit");
 const governance_1 = require("../utils/governance");
 const policy_compiler_1 = require("../utils/policy-compiler");
 const change_contract_1 = require("../utils/change-contract");
+const artifact_signature_1 = require("../utils/artifact-signature");
 const policy_1 = require("@neurcode-ai/policy");
 // Import chalk with fallback
 let chalk;
@@ -85,6 +87,155 @@ catch {
     };
 }
 ;
+function toArtifactSignatureSummary(status) {
+    return {
+        required: status.required,
+        present: status.present,
+        valid: status.valid,
+        keyId: status.keyId,
+        verifiedWithKeyId: status.verifiedWithKeyId,
+        issues: [...status.issues],
+    };
+}
+function resolveCliComponentVersion() {
+    const fromEnv = process.env.NEURCODE_CLI_VERSION || process.env.npm_package_version;
+    if (fromEnv && fromEnv.trim()) {
+        return fromEnv.trim();
+    }
+    try {
+        const packagePath = (0, path_1.join)(__dirname, '../../package.json');
+        const raw = (0, fs_1.readFileSync)(packagePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.version === 'string' && parsed.version.trim()) {
+            return parsed.version.trim();
+        }
+    }
+    catch {
+        // Ignore and fall back.
+    }
+    return '0.0.0';
+}
+const CLI_COMPONENT_VERSION = resolveCliComponentVersion();
+function asCompatibilityRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+async function probeApiRuntimeCompatibility(apiUrl) {
+    const normalizedApiUrl = apiUrl.replace(/\/$/, '');
+    const healthUrl = `${normalizedApiUrl}/health`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 5000);
+    try {
+        const response = await fetch(healthUrl, {
+            method: 'GET',
+            signal: controller.signal,
+            headers: {
+                'User-Agent': 'neurcode-cli-verify/compat-probe',
+            },
+        });
+        if (!response.ok) {
+            return {
+                healthUrl,
+                apiVersion: null,
+                status: 'warn',
+                messages: [`Health endpoint returned status ${response.status}; skipping runtime compatibility handshake.`],
+            };
+        }
+        const payload = (await response.json().catch(() => ({})));
+        const compatibility = asCompatibilityRecord(payload.compatibility);
+        const apiVersionFromHealth = typeof payload.version === 'string' && payload.version.trim()
+            ? payload.version.trim()
+            : null;
+        if (!compatibility) {
+            return {
+                healthUrl,
+                apiVersion: apiVersionFromHealth,
+                status: 'warn',
+                messages: ['API health payload is missing compatibility metadata.'],
+            };
+        }
+        const contractId = typeof compatibility.contractId === 'string' ? compatibility.contractId.trim() : '';
+        const runtimeContractVersion = typeof compatibility.runtimeContractVersion === 'string'
+            ? compatibility.runtimeContractVersion.trim()
+            : '';
+        const cliJsonContractVersion = typeof compatibility.cliJsonContractVersion === 'string'
+            ? compatibility.cliJsonContractVersion.trim()
+            : '';
+        const component = typeof compatibility.component === 'string' ? compatibility.component.trim() : '';
+        const componentVersion = typeof compatibility.componentVersion === 'string'
+            ? compatibility.componentVersion.trim()
+            : '';
+        const minimumPeerVersions = asCompatibilityRecord(compatibility.minimumPeerVersions) || {};
+        const apiRequiresCli = typeof minimumPeerVersions.cli === 'string' && minimumPeerVersions.cli.trim()
+            ? minimumPeerVersions.cli.trim()
+            : undefined;
+        const errors = [];
+        if (contractId !== contracts_1.RUNTIME_COMPATIBILITY_CONTRACT_ID) {
+            errors.push(`API compatibility contractId mismatch (expected ${contracts_1.RUNTIME_COMPATIBILITY_CONTRACT_ID}, got ${contractId || 'missing'}).`);
+        }
+        if (runtimeContractVersion !== contracts_1.RUNTIME_COMPATIBILITY_CONTRACT_VERSION) {
+            errors.push(`API runtimeContractVersion mismatch (expected ${contracts_1.RUNTIME_COMPATIBILITY_CONTRACT_VERSION}, got ${runtimeContractVersion || 'missing'}).`);
+        }
+        if (cliJsonContractVersion !== contracts_1.CLI_JSON_CONTRACT_VERSION) {
+            errors.push(`API cliJsonContractVersion mismatch (expected ${contracts_1.CLI_JSON_CONTRACT_VERSION}, got ${cliJsonContractVersion || 'missing'}).`);
+        }
+        if (component !== 'api') {
+            errors.push(`API compatibility payload component must be "api" (received ${component || 'missing'}).`);
+        }
+        const resolvedApiVersion = componentVersion || apiVersionFromHealth;
+        const minimumApiForCli = (0, contracts_1.getMinimumCompatiblePeerVersion)('cli', 'api');
+        if (minimumApiForCli && resolvedApiVersion) {
+            const cliRequiresApi = (0, contracts_1.isSemverAtLeast)(resolvedApiVersion, minimumApiForCli);
+            if (cliRequiresApi === null) {
+                errors.push(`Unable to compare API version "${resolvedApiVersion}" against required minimum "${minimumApiForCli}".`);
+            }
+            else if (!cliRequiresApi) {
+                errors.push(`API version ${resolvedApiVersion} is below CLI required minimum ${minimumApiForCli}.`);
+            }
+        }
+        if (apiRequiresCli) {
+            const apiRequiresThisCli = (0, contracts_1.isSemverAtLeast)(CLI_COMPONENT_VERSION, apiRequiresCli);
+            if (apiRequiresThisCli === null) {
+                errors.push(`Unable to compare CLI version "${CLI_COMPONENT_VERSION}" against API required minimum "${apiRequiresCli}".`);
+            }
+            else if (!apiRequiresThisCli) {
+                errors.push(`CLI version ${CLI_COMPONENT_VERSION} is below API required minimum ${apiRequiresCli}.`);
+            }
+        }
+        if (errors.length > 0) {
+            return {
+                healthUrl,
+                apiVersion: resolvedApiVersion || null,
+                status: 'error',
+                messages: errors,
+            };
+        }
+        return {
+            healthUrl,
+            apiVersion: resolvedApiVersion || null,
+            status: 'ok',
+            messages: [],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error && error.name === 'AbortError'
+            ? 'Health endpoint timed out after 5s.'
+            : error instanceof Error
+                ? error.message
+                : 'Unknown error';
+        return {
+            healthUrl,
+            apiVersion: null,
+            status: 'warn',
+            messages: [`Runtime compatibility probe failed: ${message}`],
+        };
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
 /**
  * Check if a file path should be excluded from verification analysis
  * Excludes internal/system files that should not count towards plan adherence
@@ -391,6 +542,94 @@ function resolveAuditIntegrityStatus(requireIntegrity, auditIntegrity) {
         issues,
     };
 }
+function describePolicyExceptionSource(mode) {
+    switch (mode) {
+        case 'org':
+            return 'org control plane';
+        case 'org_fallback_local':
+            return 'local file fallback (org unavailable)';
+        case 'local':
+        default:
+            return 'local file';
+    }
+}
+function pickExceptionIdentity(userId, email, allowSet) {
+    const normalizedUserId = typeof userId === 'string' ? userId.trim() : '';
+    const normalizedEmail = typeof email === 'string' ? email.trim() : '';
+    if (allowSet.size > 0) {
+        if (normalizedEmail && allowSet.has(normalizedEmail.toLowerCase())) {
+            return normalizedEmail;
+        }
+        if (normalizedUserId && allowSet.has(normalizedUserId.toLowerCase())) {
+            return normalizedUserId;
+        }
+    }
+    if (normalizedEmail)
+        return normalizedEmail;
+    if (normalizedUserId)
+        return normalizedUserId;
+    return 'unknown';
+}
+function mapOrgPolicyExceptionToLocalEntry(exception, allowSet) {
+    const createdBy = pickExceptionIdentity(exception.createdBy, exception.requestedByEmail, allowSet);
+    const requestedBy = pickExceptionIdentity(exception.requestedBy, exception.requestedByEmail, allowSet);
+    return {
+        id: exception.id,
+        rulePattern: exception.rulePattern,
+        filePattern: exception.filePattern,
+        reason: exception.reason,
+        ticket: exception.ticket,
+        createdAt: exception.createdAt,
+        createdBy,
+        requestedBy,
+        expiresAt: exception.expiresAt,
+        severity: exception.severity,
+        active: exception.active === true
+            && exception.workflowState !== 'revoked'
+            && exception.workflowState !== 'rejected',
+        approvals: (exception.approvals || []).map((approval) => ({
+            approver: pickExceptionIdentity(approval.approverUserId, approval.approverEmail, allowSet),
+            approvedAt: approval.createdAt,
+            comment: approval.note || null,
+        })),
+    };
+}
+async function resolveEffectivePolicyExceptions(input) {
+    const localExceptions = (0, policy_exceptions_1.readPolicyExceptions)(input.projectRoot);
+    if (!input.useOrgControlPlane) {
+        return {
+            mode: 'local',
+            exceptions: localExceptions,
+            localConfigured: localExceptions.length,
+            orgConfigured: 0,
+            warning: null,
+        };
+    }
+    try {
+        const orgExceptions = await input.client.listOrgPolicyExceptions({ limit: 250 });
+        const allowSet = new Set((input.governance.exceptionApprovals.allowedApprovers || []).map((item) => item.toLowerCase()));
+        const mapped = orgExceptions
+            .map((entry) => mapOrgPolicyExceptionToLocalEntry(entry, allowSet))
+            .sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+        return {
+            mode: 'org',
+            exceptions: mapped,
+            localConfigured: localExceptions.length,
+            orgConfigured: mapped.length,
+            warning: null,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        return {
+            mode: 'org_fallback_local',
+            exceptions: localExceptions,
+            localConfigured: localExceptions.length,
+            orgConfigured: 0,
+            warning: `Org policy exceptions unavailable; falling back to local exceptions (${message})`,
+        };
+    }
+}
 async function recordVerificationIfRequested(options, config, payload) {
     if (!options.record) {
         return;
@@ -746,10 +985,20 @@ async function executePolicyOnlyMode(options, diffFiles, ignoreFilter, projectRo
     const policyResult = (0, policy_engine_1.evaluateRules)(diffFilesForPolicy, effectiveRules.allRules);
     policyViolations = (policyResult.violations || []);
     policyViolations = policyViolations.filter((v) => !ignoreFilter(v.file));
-    const governance = (0, policy_governance_1.readPolicyGovernanceConfig)(projectRoot);
+    const localPolicyGovernance = (0, policy_governance_1.readPolicyGovernanceConfig)(projectRoot);
+    const governance = (0, policy_governance_1.mergePolicyGovernanceWithOrgOverrides)(localPolicyGovernance, orgGovernanceSettings?.policyGovernance);
     const auditIntegrity = (0, policy_audit_1.verifyPolicyAuditIntegrity)(projectRoot);
     const auditIntegrityStatus = resolveAuditIntegrityStatus(governance.audit.requireIntegrity, auditIntegrity);
-    const configuredPolicyExceptions = (0, policy_exceptions_1.readPolicyExceptions)(projectRoot);
+    const policyExceptionResolution = await resolveEffectivePolicyExceptions({
+        client,
+        projectRoot,
+        useOrgControlPlane: Boolean(config.apiKey),
+        governance,
+    });
+    if (policyExceptionResolution.warning && !options.json) {
+        console.log(chalk.dim(`   ${policyExceptionResolution.warning}`));
+    }
+    const configuredPolicyExceptions = policyExceptionResolution.exceptions;
     const exceptionDecision = (0, policy_exceptions_1.applyPolicyExceptions)(policyViolations, configuredPolicyExceptions, {
         requireApproval: governance.exceptionApprovals.required,
         minApprovals: governance.exceptionApprovals.minApprovals,
@@ -803,6 +1052,10 @@ async function executePolicyOnlyMode(options, diffFiles, ignoreFilter, projectRo
             ? `Policy violations: ${policyViolations.map((v) => `${v.file}: ${v.message || v.rule}`).join('; ')}`
             : 'Policy check completed';
     const policyExceptionsSummary = {
+        sourceMode: policyExceptionResolution.mode,
+        sourceWarning: policyExceptionResolution.warning,
+        localConfigured: policyExceptionResolution.localConfigured,
+        orgConfigured: policyExceptionResolution.orgConfigured,
         configured: configuredPolicyExceptions.length,
         active: exceptionDecision.activeExceptions.length,
         usable: exceptionDecision.usableExceptions.length,
@@ -885,6 +1138,7 @@ async function executePolicyOnlyMode(options, diffFiles, ignoreFilter, projectRo
                 console.log(chalk.red(`   • ${v.file}: ${v.message || v.rule}`));
             });
         }
+        console.log(chalk.dim(`   Policy exceptions source: ${describePolicyExceptionSource(policyExceptionsSummary.sourceMode)}`));
         if (policyExceptionsSummary.suppressed > 0) {
             console.log(chalk.yellow(`   Policy exceptions applied: ${policyExceptionsSummary.suppressed}`));
         }
@@ -927,12 +1181,48 @@ async function verifyCommand(options) {
         };
         const enforceChangeContract = options.enforceChangeContract === true ||
             isEnabledFlag(process.env.NEURCODE_VERIFY_ENFORCE_CHANGE_CONTRACT);
-        const strictArtifactMode = options.strictArtifacts === true ||
+        const explicitStrictArtifactMode = options.strictArtifacts === true ||
             isEnabledFlag(process.env.NEURCODE_VERIFY_STRICT_ARTIFACTS) ||
             isEnabledFlag(process.env.NEURCODE_ENTERPRISE_MODE);
+        const ciEnterpriseDefaultStrict = process.env.CI === 'true'
+            && !isEnabledFlag(process.env.NEURCODE_VERIFY_ALLOW_NON_STRICT_CI)
+            && Boolean(options.apiKey || process.env.NEURCODE_API_KEY);
+        const strictArtifactMode = explicitStrictArtifactMode || ciEnterpriseDefaultStrict;
+        const signingConfig = resolveGovernanceSigningConfig();
+        const aiLogSigningKey = signingConfig.signingKey;
+        const aiLogSigningKeyId = signingConfig.signingKeyId;
+        const aiLogSigningKeys = signingConfig.signingKeys;
+        const aiLogSigner = signingConfig.signer;
+        const hasSigningMaterial = Boolean(aiLogSigningKey) || Object.keys(aiLogSigningKeys).length > 0;
+        const allowUnsignedArtifacts = isEnabledFlag(process.env.NEURCODE_VERIFY_ALLOW_UNSIGNED_ARTIFACTS)
+            || isEnabledFlag(process.env.NEURCODE_VERIFY_DISABLE_SIGNED_ARTIFACTS);
+        const requireSignedArtifacts = options.requireSignedArtifacts === true
+            || isEnabledFlag(process.env.NEURCODE_VERIFY_REQUIRE_SIGNED_ARTIFACTS)
+            || (!allowUnsignedArtifacts && strictArtifactMode && hasSigningMaterial);
         const changeContractRead = (0, change_contract_1.readChangeContract)(projectRoot, options.changeContract);
         const compiledPolicyRead = (0, policy_compiler_1.readCompiledPolicyArtifact)(projectRoot, options.compiledPolicy);
         let compiledPolicyMetadata = resolveCompiledPolicyMetadata(compiledPolicyRead.artifact, compiledPolicyRead.exists ? compiledPolicyRead.path : null);
+        const compiledPolicySignatureStatus = compiledPolicyRead.artifact
+            ? (0, artifact_signature_1.verifyGovernanceArtifactSignature)({
+                artifact: compiledPolicyRead.artifact,
+                requireSigned: requireSignedArtifacts,
+                signingKey: aiLogSigningKey,
+                signingKeyId: aiLogSigningKeyId,
+                signingKeys: aiLogSigningKeys,
+            })
+            : null;
+        if (compiledPolicyMetadata && compiledPolicySignatureStatus) {
+            compiledPolicyMetadata.signature = toArtifactSignatureSummary(compiledPolicySignatureStatus);
+        }
+        const changeContractSignatureStatus = changeContractRead.contract
+            ? (0, artifact_signature_1.verifyGovernanceArtifactSignature)({
+                artifact: changeContractRead.contract,
+                requireSigned: requireSignedArtifacts,
+                signingKey: aiLogSigningKey,
+                signingKeyId: aiLogSigningKeyId,
+                signingKeys: aiLogSigningKeys,
+            })
+            : null;
         let changeContractSummary = {
             path: changeContractRead.path,
             exists: changeContractRead.exists,
@@ -940,6 +1230,9 @@ async function verifyCommand(options) {
             valid: changeContractRead.contract ? null : changeContractRead.exists ? false : null,
             planId: changeContractRead.contract?.planId || null,
             contractId: changeContractRead.contract?.contractId || null,
+            signature: changeContractSignatureStatus
+                ? toArtifactSignatureSummary(changeContractSignatureStatus)
+                : undefined,
             violations: changeContractRead.error
                 ? [
                     {
@@ -961,6 +1254,16 @@ async function verifyCommand(options) {
                     ? `Change contract artifact invalid (${changeContractRead.error})`
                     : `Change contract artifact missing (${changeContractRead.path})`);
             }
+            if (compiledPolicySignatureStatus
+                && !compiledPolicySignatureStatus.valid
+                && (requireSignedArtifacts || compiledPolicySignatureStatus.present)) {
+                strictErrors.push(`Compiled policy artifact signature validation failed (${compiledPolicySignatureStatus.issues.join('; ') || 'unknown issue'})`);
+            }
+            if (changeContractSignatureStatus
+                && !changeContractSignatureStatus.valid
+                && (requireSignedArtifacts || changeContractSignatureStatus.present)) {
+                strictErrors.push(`Change contract artifact signature validation failed (${changeContractSignatureStatus.issues.join('; ') || 'unknown issue'})`);
+            }
             if (strictErrors.length > 0) {
                 const message = `Strict artifact mode requires deterministic compiled-policy + change-contract artifacts.\n- ${strictErrors.join('\n- ')}`;
                 if (options.json) {
@@ -995,7 +1298,60 @@ async function verifyCommand(options) {
                     strictErrors.forEach((entry) => {
                         console.log(chalk.red(`   • ${entry}`));
                     });
-                    console.log(chalk.dim('\nSet --compiled-policy and --change-contract with valid artifacts before verify.\n'));
+                    console.log(chalk.dim('\nSet --compiled-policy and --change-contract with valid artifacts before verify.'));
+                    if (requireSignedArtifacts) {
+                        console.log(chalk.dim('Enable signing keys via NEURCODE_GOVERNANCE_SIGNING_KEY or NEURCODE_GOVERNANCE_SIGNING_KEYS to generate signed artifacts.\n'));
+                    }
+                    else {
+                        console.log('');
+                    }
+                }
+                process.exit(2);
+            }
+        }
+        if (!strictArtifactMode && requireSignedArtifacts) {
+            const signatureErrors = [];
+            if (compiledPolicyRead.artifact && compiledPolicySignatureStatus && !compiledPolicySignatureStatus.valid) {
+                signatureErrors.push(`Compiled policy artifact signature validation failed (${compiledPolicySignatureStatus.issues.join('; ') || 'unknown issue'})`);
+            }
+            if (changeContractRead.contract && changeContractSignatureStatus && !changeContractSignatureStatus.valid) {
+                signatureErrors.push(`Change contract artifact signature validation failed (${changeContractSignatureStatus.issues.join('; ') || 'unknown issue'})`);
+            }
+            if (signatureErrors.length > 0) {
+                const message = `Signed artifact enforcement failed.\n- ${signatureErrors.join('\n- ')}`;
+                if (options.json) {
+                    emitVerifyJson({
+                        grade: 'F',
+                        score: 0,
+                        verdict: 'FAIL',
+                        violations: signatureErrors.map((entry) => ({
+                            file: entry.toLowerCase().includes('compiled policy') ? compiledPolicyRead.path : changeContractRead.path,
+                            rule: 'signed_artifacts_required',
+                            severity: 'block',
+                            message: entry,
+                        })),
+                        adherenceScore: 0,
+                        bloatCount: 0,
+                        bloatFiles: [],
+                        plannedFilesModified: 0,
+                        totalPlannedFiles: 0,
+                        message,
+                        scopeGuardPassed: false,
+                        mode: 'signed_artifacts_required',
+                        policyOnly: options.policyOnly === true,
+                        changeContract: changeContractSummary,
+                        ...(compiledPolicyMetadata ? { policyCompilation: compiledPolicyMetadata } : {}),
+                    });
+                }
+                else {
+                    (0, scope_telemetry_1.printScopeTelemetry)(chalk, scopeTelemetry, {
+                        includeBlockedWarning: true,
+                    });
+                    console.log(chalk.red('\n⛔ Signed Artifact Requirements Failed'));
+                    signatureErrors.forEach((entry) => {
+                        console.log(chalk.red(`   • ${entry}`));
+                    });
+                    console.log(chalk.dim('\nEnable signing keys via NEURCODE_GOVERNANCE_SIGNING_KEY or NEURCODE_GOVERNANCE_SIGNING_KEYS and regenerate artifacts.\n'));
                 }
                 process.exit(2);
             }
@@ -1016,6 +1372,28 @@ async function verifyCommand(options) {
             else if (changeContractRead.contract) {
                 console.log(chalk.dim(`   Change contract loaded: ${changeContractRead.path}`));
             }
+            if (compiledPolicySignatureStatus) {
+                if (compiledPolicySignatureStatus.valid) {
+                    console.log(chalk.dim(`   Compiled policy signature: valid${compiledPolicySignatureStatus.verifiedWithKeyId ? ` (key ${compiledPolicySignatureStatus.verifiedWithKeyId})` : ''}`));
+                }
+                else if (compiledPolicySignatureStatus.present || requireSignedArtifacts) {
+                    console.log(chalk.yellow(`   Compiled policy signature: invalid (${compiledPolicySignatureStatus.issues.join('; ') || 'unknown issue'})`));
+                }
+            }
+            if (changeContractSignatureStatus) {
+                if (changeContractSignatureStatus.valid) {
+                    console.log(chalk.dim(`   Change contract signature: valid${changeContractSignatureStatus.verifiedWithKeyId ? ` (key ${changeContractSignatureStatus.verifiedWithKeyId})` : ''}`));
+                }
+                else if (changeContractSignatureStatus.present || requireSignedArtifacts) {
+                    console.log(chalk.yellow(`   Change contract signature: invalid (${changeContractSignatureStatus.issues.join('; ') || 'unknown issue'})`));
+                }
+            }
+            if (ciEnterpriseDefaultStrict && !explicitStrictArtifactMode) {
+                console.log(chalk.dim('   CI enterprise mode detected: strict deterministic artifact enforcement is auto-enabled (set NEURCODE_VERIFY_ALLOW_NON_STRICT_CI=1 to opt out).'));
+            }
+            if (requireSignedArtifacts) {
+                console.log(chalk.dim('   Artifact signature enforcement: enabled (set NEURCODE_VERIFY_ALLOW_UNSIGNED_ARTIFACTS=1 to relax)'));
+            }
         }
         // Load configuration
         const config = (0, config_1.loadConfig)();
@@ -1043,6 +1421,72 @@ async function verifyCommand(options) {
             // Ensure no trailing slash
             config.apiUrl = config.apiUrl.replace(/\/$/, '');
         }
+        const enforceCompatibilityHandshake = isEnabledFlag(process.env.NEURCODE_VERIFY_ENFORCE_COMPAT_HANDSHAKE)
+            || strictArtifactMode
+            || (process.env.CI === 'true' && Boolean(config.apiKey));
+        if (config.apiKey && config.apiUrl) {
+            const compatibilityProbe = await probeApiRuntimeCompatibility(config.apiUrl);
+            if (compatibilityProbe.status !== 'ok' && enforceCompatibilityHandshake) {
+                const failureMessages = compatibilityProbe.messages.length > 0
+                    ? compatibilityProbe.messages
+                    : ['Runtime compatibility handshake did not return a successful result.'];
+                const message = `Runtime compatibility handshake failed against ${compatibilityProbe.healthUrl}.\n` +
+                    failureMessages.map((entry) => `- ${entry}`).join('\n');
+                if (options.json) {
+                    emitVerifyJson({
+                        grade: 'F',
+                        score: 0,
+                        verdict: 'FAIL',
+                        violations: failureMessages.map((entry) => ({
+                            file: 'runtime-compatibility',
+                            rule: 'runtime_compatibility_handshake',
+                            severity: 'block',
+                            message: entry,
+                        })),
+                        adherenceScore: 0,
+                        bloatCount: 0,
+                        bloatFiles: [],
+                        plannedFilesModified: 0,
+                        totalPlannedFiles: 0,
+                        message,
+                        scopeGuardPassed: false,
+                        mode: 'runtime_compatibility_failed',
+                        policyOnly: options.policyOnly === true,
+                        changeContract: changeContractSummary,
+                        ...(compiledPolicyMetadata ? { policyCompilation: compiledPolicyMetadata } : {}),
+                    });
+                }
+                else {
+                    console.log(chalk.red('\n⛔ Runtime Compatibility Handshake Failed'));
+                    failureMessages.forEach((entry) => {
+                        console.log(chalk.red(`   • ${entry}`));
+                    });
+                    console.log(chalk.dim(`   Health endpoint: ${compatibilityProbe.healthUrl}`));
+                    if (compatibilityProbe.apiVersion) {
+                        console.log(chalk.dim(`   API version: ${compatibilityProbe.apiVersion}`));
+                    }
+                    console.log(chalk.dim(`   CLI version: ${CLI_COMPONENT_VERSION}`));
+                    console.log(chalk.dim('   Upgrade/downgrade CLI, Action, or API to satisfy the runtime compatibility contract before running verify.\n'));
+                }
+                process.exit(2);
+            }
+            if (compatibilityProbe.status === 'error' && !options.json) {
+                console.log(chalk.yellow('\n⚠️  Runtime compatibility mismatch detected (advisory mode).'));
+                compatibilityProbe.messages.forEach((entry) => {
+                    console.log(chalk.yellow(`   • ${entry}`));
+                });
+            }
+            else if (compatibilityProbe.status === 'warn' && !options.json) {
+                compatibilityProbe.messages.forEach((entry) => {
+                    console.log(chalk.dim(`   ${entry}`));
+                });
+            }
+            else if (compatibilityProbe.status === 'ok'
+                && !options.json
+                && isEnabledFlag(process.env.NEURCODE_VERIFY_VERBOSE_COMPAT_HANDSHAKE)) {
+                console.log(chalk.dim(`   Runtime compatibility check passed (CLI ${CLI_COMPONENT_VERSION}, API ${compatibilityProbe.apiVersion || 'unknown'})`));
+            }
+        }
         // Explicitly load config file to get sessionId and lastSessionId
         const configPath = (0, path_1.join)(projectRoot, 'neurcode.config.json');
         let configData = {};
@@ -1065,11 +1509,6 @@ async function verifyCommand(options) {
             orgId: (0, state_1.getOrgId)(),
             projectId: projectId || null,
         };
-        const signingConfig = resolveGovernanceSigningConfig();
-        const aiLogSigningKey = signingConfig.signingKey;
-        const aiLogSigningKeyId = signingConfig.signingKeyId;
-        const aiLogSigningKeys = signingConfig.signingKeys;
-        const aiLogSigner = signingConfig.signer;
         let orgGovernanceSettings = null;
         if (config.apiKey) {
             try {
@@ -1095,7 +1534,6 @@ async function verifyCommand(options) {
             }
         }
         const signedLogsRequired = isSignedAiLogsRequired(orgGovernanceSettings);
-        const hasSigningMaterial = Boolean(aiLogSigningKey) || Object.keys(aiLogSigningKeys).length > 0;
         const recordVerifyEvent = (verdict, note, changedFiles, planId) => {
             if (!brainScope.orgId || !brainScope.projectId) {
                 return;
@@ -1358,7 +1796,9 @@ async function verifyCommand(options) {
         if (options.policyOnly) {
             await runPolicyOnlyModeAndExit('explicit');
         }
-        const requirePlan = options.requirePlan === true || process.env.NEURCODE_VERIFY_REQUIRE_PLAN === '1';
+        const requirePlan = options.requirePlan === true
+            || process.env.NEURCODE_VERIFY_REQUIRE_PLAN === '1'
+            || strictArtifactMode;
         // Get planId: Priority 1: options flag, Priority 2: state file (.neurcode/config.json), Priority 3: legacy config
         let planId = options.planId;
         if (!planId) {
@@ -1865,7 +2305,16 @@ async function verifyCommand(options) {
         const diffFilesForPolicy = diffFiles.filter((f) => !shouldIgnore(f.path));
         const policyResult = (0, policy_engine_1.evaluateRules)(diffFilesForPolicy, effectiveRules.allRules);
         policyViolations = policyResult.violations.filter((v) => !shouldIgnore(v.file));
-        const configuredPolicyExceptions = (0, policy_exceptions_1.readPolicyExceptions)(projectRoot);
+        const policyExceptionResolution = await resolveEffectivePolicyExceptions({
+            client,
+            projectRoot,
+            useOrgControlPlane: Boolean(config.apiKey),
+            governance,
+        });
+        if (policyExceptionResolution.warning && !options.json) {
+            console.log(chalk.dim(`   ${policyExceptionResolution.warning}`));
+        }
+        const configuredPolicyExceptions = policyExceptionResolution.exceptions;
         const exceptionDecision = (0, policy_exceptions_1.applyPolicyExceptions)(policyViolations, configuredPolicyExceptions, {
             requireApproval: governance.exceptionApprovals.required,
             minApprovals: governance.exceptionApprovals.minApprovals,
@@ -1904,6 +2353,10 @@ async function verifyCommand(options) {
         }
         policyDecision = resolvePolicyDecisionFromViolations(policyViolations);
         const policyExceptionsSummary = {
+            sourceMode: policyExceptionResolution.mode,
+            sourceWarning: policyExceptionResolution.warning,
+            localConfigured: policyExceptionResolution.localConfigured,
+            orgConfigured: policyExceptionResolution.orgConfigured,
             configured: configuredPolicyExceptions.length,
             active: exceptionDecision.activeExceptions.length,
             usable: exceptionDecision.usableExceptions.length,
@@ -1986,6 +2439,7 @@ async function verifyCommand(options) {
                 valid: changeContractEvaluation.valid,
                 planId: changeContractRead.contract?.planId || null,
                 contractId: changeContractRead.contract?.contractId || null,
+                signature: changeContractSummary.signature,
                 coverage: changeContractEvaluation.coverage,
                 violations: changeContractEvaluation.violations.map((item) => ({
                     code: item.code,
@@ -2065,6 +2519,9 @@ async function verifyCommand(options) {
         // Call verify API
         if (!options.json) {
             console.log(chalk.dim('   Sending to Neurcode API...\n'));
+            if (options.asyncMode) {
+                console.log(chalk.dim('   Queue-backed verification enabled (async job mode).'));
+            }
         }
         try {
             let verifySource = 'api';
@@ -2075,7 +2532,13 @@ async function verifyCommand(options) {
                     .map((policy) => policy.rule_text)
                     .filter((ruleText) => typeof ruleText === 'string' && ruleText.trim().length > 0);
             try {
-                verifyResult = await client.verifyPlan(finalPlanId, diffStats, changedFiles, projectId, intentConstraintsForVerification, deterministicPolicyRules, 'api', compiledPolicyMetadata);
+                verifyResult = await client.verifyPlan(finalPlanId, diffStats, changedFiles, projectId, intentConstraintsForVerification, deterministicPolicyRules, 'api', compiledPolicyMetadata, {
+                    async: options.asyncMode === true,
+                    pollIntervalMs: Number.isFinite(options.verifyJobPollMs) ? options.verifyJobPollMs : undefined,
+                    timeoutMs: Number.isFinite(options.verifyJobTimeoutMs) ? options.verifyJobTimeoutMs : undefined,
+                    idempotencyKey: options.verifyIdempotencyKey,
+                    maxAttempts: Number.isFinite(options.verifyJobMaxAttempts) ? options.verifyJobMaxAttempts : undefined,
+                });
             }
             catch (verifyApiError) {
                 if (planFilesForVerification.length === 0) {
@@ -2291,6 +2754,7 @@ async function verifyCommand(options) {
                 if (governanceResult) {
                     displayGovernanceInsights(governanceResult, { explain: options.explain });
                 }
+                console.log(chalk.dim(`\n   Policy exceptions source: ${describePolicyExceptionSource(policyExceptionsSummary.sourceMode)}`));
                 if (policyExceptionsSummary.suppressed > 0) {
                     console.log(chalk.yellow(`\n⚠️  Policy exceptions applied: ${policyExceptionsSummary.suppressed}`));
                     if (policyExceptionsSummary.matchedExceptionIds.length > 0) {