@open-agent-toolkit/cli 0.1.69 → 0.1.73

package/dist/commands/gate/index.js

@@ -1,11 +1,14 @@
 import { spawn } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
-import { readdir, readFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
 import { basename, isAbsolute, join, relative } from 'node:path';
 import { buildCommandContext, } from '../../app/command-context.js';
+import { appendProjectLog } from '../project/log/append.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 { parseJsonConfig } from '../../config/json.js';
+import { BUILTIN_EXEC_TARGETS, MAX_GATE_TIMEOUT_MS, MIN_GATE_TIMEOUT_MS, isValidGateTimeoutMs, readOatConfig, readOatLocalConfig, readUserConfig, writeOatConfig, writeOatLocalConfig, writeUserConfig, } from '../../config/oat-config.js';
 import { resolveEffectiveConfig, resolveExecTargetViews, resolveExecTargets, resolveGate, } from '../../config/resolve.js';
 import { dirExists, fileExists } from '../../fs/io.js';
 import { normalizeToPosixPath, resolveProjectRoot, validateRealPathWithinScope, } from '../../fs/paths.js';
@@ -15,7 +18,10 @@ import { resolveIdentityConfidence, } from '../../providers/identity/provenance.
 import { parseDispatchStamps } from '../../providers/identity/stamp.js';
 import { Command } from 'commander';
 import YAML from 'yaml';
+import { createGateActivityProbe, } from './activity-probes.js';
+import { createBranchLocalGateCli, currentGateCliLaunch, readGateRouteReceipt, removeBranchLocalGateCli, } from './branch-local-cli.js';
 import { parseReviewGateVerdict, severityDisplayName, } from './review-verdict.js';
+import { createGateRouteCommand } from './route.js';
 const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
     resolveProjectRoot,
@@ -26,9 +32,17 @@ const DEFAULT_DEPENDENCIES = {
     readUserConfig,
     writeUserConfig,
     resolveEffectiveConfig,
+    createGateActivityProbe,
+    createBranchLocalGateCli,
+    currentGateCliLaunch,
+    removeBranchLocalGateCli,
+    readGateRouteReceipt,
     runProcess: runChildProcess,
     parseReviewGateVerdict,
+    appendProjectLog,
     processEnv: process.env,
+    writeGateRunMarker,
+    removeGateRunMarker,
     writeDiagnostic: (message) => process.stderr.write(message),
 };
 const VALID_ON_FAILURE = ['block', 'prompt', 'warn'];
@@ -61,6 +75,33 @@ const REVIEW_GATE_CONTEXT_NOTE = [
 const GATE_CHECK_TIMEOUT_MS = 5_000;
 const GATE_EXEC_TIMEOUT_MS = 15 * 60 * 1_000;
 const GATE_LIVENESS_INTERVAL_MS = 30_000;
+async function writeGateRunMarker(path, marker, warn) {
+    try {
+        await mkdir(join(tmpdir(), 'oat-gate-runs'), { recursive: true });
+        await writeFile(path, `${JSON.stringify(marker, null, 2)}\n`, 'utf8');
+        return true;
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        warn(`Unable to write gate run marker ${path}: ${detail}`);
+        return false;
+    }
+}
+async function removeGateRunMarker(path, warn) {
+    try {
+        await rm(path);
+    }
+    catch (error) {
+        if (error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            error.code === 'ENOENT') {
+            return;
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        warn(`Unable to remove gate run marker ${path}: ${detail}`);
+    }
+}
 function reviewGateProjectContext(project) {
     return [
         `Resolved OAT project path: ${project.path}. Run the review for this project path.`,
@@ -158,6 +199,7 @@ function buildGateDispatchReport(invocation, scope) {
 }
 function gateInvocationPromptContext(invocation) {
     const frontmatter = YAML.stringify({
+        oat_gate_headless: true,
         oat_gate_run_id: invocation.runId,
         oat_gate_target: invocation.targetId,
         oat_gate_runtime: invocation.runtime,
@@ -203,6 +245,12 @@ async function runChildProcess(command, args, options) {
         let killTimeout = null;
         let stderrBytes = 0;
         let stdoutBytes = 0;
+        let refusal;
+        let stdoutLineBuffer = '';
+        let stderrLineBuffer = '';
+        let latestActivityEvidence;
+        let latestActivityProbeStatus;
+        let livenessProbePending = false;
         const startedAt = Date.now();
         let lastActivityAt = startedAt;
         const child = spawn(command, args, {
@@ -215,23 +263,71 @@ async function runChildProcess(command, args, options) {
         const recordActivity = () => {
             lastActivityAt = Date.now();
         };
+        const scanChunk = (buffer, chunk) => {
+            const combined = buffer + chunk.toString('utf8');
+            const lines = combined.split('\n');
+            const remainder = lines.pop() ?? '';
+            if (!refusal) {
+                for (const line of lines) {
+                    refusal = extractStructuredRefusal(line.replace(/\r$/, ''));
+                    if (refusal) {
+                        break;
+                    }
+                }
+            }
+            return remainder;
+        };
         child.stdout?.on('data', (chunk) => {
             stdoutBytes += chunk.byteLength;
+            stdoutLineBuffer = scanChunk(stdoutLineBuffer, chunk);
             recordActivity();
             process.stdout.write(chunk);
         });
         child.stderr?.on('data', (chunk) => {
             stderrBytes += chunk.byteLength;
+            stderrLineBuffer = scanChunk(stderrLineBuffer, chunk);
             recordActivity();
             process.stderr.write(chunk);
         });
+        const processAlive = () => {
+            if (child.pid === undefined)
+                return false;
+            try {
+                process.kill(child.pid, 0);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
         const livenessInterval = options.onLiveness && options.livenessIntervalMs
             ? setInterval(() => {
+                if (livenessProbePending)
+                    return;
+                livenessProbePending = true;
                 const now = Date.now();
-                options.onLiveness?.({
-                    elapsedMs: now - startedAt,
-                    hardBudgetMs: options.timeoutMs,
-                    idleMs: now - lastActivityAt,
+                void (async () => {
+                    const activityProbeStatus = await options.activityProbe?.observe(now);
+                    const evidence = activityProbeStatus?.evidence;
+                    if (activityProbeStatus) {
+                        latestActivityProbeStatus = activityProbeStatus;
+                    }
+                    if (evidence)
+                        latestActivityEvidence = evidence;
+                    options.onLiveness?.({
+                        elapsedMs: now - startedAt,
+                        hardBudgetMs: options.timeoutMs,
+                        idleMs: now - lastActivityAt,
+                        processAlive: processAlive(),
+                        ...(latestActivityProbeStatus
+                            ? { activityProbeStatus: latestActivityProbeStatus }
+                            : {}),
+                        ...(latestActivityEvidence
+                            ? { lastActivityEvidence: latestActivityEvidence }
+                            : {}),
+                    });
+                })().finally(() => {
+                    livenessProbePending = false;
                 });
             }, options.livenessIntervalMs)
             : null;
@@ -263,8 +359,18 @@ async function runChildProcess(command, args, options) {
             if (killTimeout) {
                 clearTimeout(killTimeout);
             }
+            refusal ??=
+                extractStructuredRefusal(stdoutLineBuffer.replace(/\r$/, '')) ??
+                    extractStructuredRefusal(stderrLineBuffer.replace(/\r$/, ''));
             resolve({
+                ...(latestActivityEvidence
+                    ? { activityEvidence: latestActivityEvidence }
+                    : {}),
+                ...(latestActivityProbeStatus
+                    ? { activityProbeStatus: latestActivityProbeStatus }
+                    : {}),
                 exitCode: timedOut ? 124 : (code ?? 1),
+                ...(refusal ? { refusal } : {}),
                 stderrBytes,
                 stdoutBytes,
                 ...(timedOut ? { timedOut: true } : {}),
@@ -272,6 +378,10 @@ async function runChildProcess(command, args, options) {
         });
     });
 }
+function extractStructuredRefusal(output) {
+    const match = output.match(/^OAT_GATE_REFUSAL: (.*)$/m);
+    return match?.[1]?.replace(/\r$/, '');
+}
 function isGateWriteLayer(value) {
     return VALID_WRITE_LAYERS.includes(value);
 }
@@ -353,17 +463,131 @@ function parseNumericFlag(value, flag, defaultValue) {
     }
     return parsed;
 }
-function resolveGateExecTimeoutMs(env) {
-    const rawValue = env.OAT_GATE_EXEC_TIMEOUT_MS?.trim();
-    if (!rawValue) {
-        return GATE_EXEC_TIMEOUT_MS;
-    }
-    const parsed = Number(rawValue);
-    if (!Number.isInteger(parsed) || parsed < 1) {
-        return GATE_EXEC_TIMEOUT_MS;
+function parseGateTimeoutFlag(value, flag) {
+    const parsed = Number(value);
+    if (!isValidGateTimeoutMs(parsed)) {
+        throw new Error(`${flag} must be an integer between ${MIN_GATE_TIMEOUT_MS} and ${MAX_GATE_TIMEOUT_MS}.`);
     }
     return parsed;
 }
+function resolveGateExecTimeout(input) {
+    if (input.cliTimeoutMs !== undefined) {
+        return {
+            timeoutMs: parseGateTimeoutFlag(input.cliTimeoutMs, '--timeout-ms'),
+            source: 'cli',
+        };
+    }
+    const warned = new Set();
+    const warnOnce = (key, message) => {
+        if (!warned.has(key)) {
+            warned.add(key);
+            input.warn(message);
+        }
+    };
+    for (const persisted of input.rawPersisted?.target ?? []) {
+        if (isValidGateTimeoutMs(persisted.value)) {
+            return { timeoutMs: persisted.value, source: 'target' };
+        }
+        warnOnce(`target:${persisted.layer}`, `Ignoring invalid target.timeoutMs from ${persisted.layer} config; using the next timeout source.`);
+    }
+    if ((input.rawPersisted?.target.length ?? 0) === 0 &&
+        input.target.timeoutMs !== undefined) {
+        if (isValidGateTimeoutMs(input.target.timeoutMs)) {
+            return { timeoutMs: input.target.timeoutMs, source: 'target' };
+        }
+        input.warn('Ignoring invalid target.timeoutMs; using the next timeout source.');
+    }
+    const reviewType = input.reviewType?.trim().toLowerCase();
+    if (reviewType === 'code' || reviewType === 'artifact') {
+        const key = `workflow.gateTimeouts.${reviewType}`;
+        for (const persisted of input.rawPersisted?.workflow ?? []) {
+            if (isValidGateTimeoutMs(persisted.value)) {
+                return { timeoutMs: persisted.value, source: 'config' };
+            }
+            warnOnce(`${key}:${persisted.layer}`, `Ignoring invalid ${key} from ${persisted.layer} config; using the next timeout source.`);
+        }
+        const entry = input.effective.resolved[key];
+        if ((input.rawPersisted?.workflow.length ?? 0) === 0 &&
+            entry?.value !== null &&
+            entry?.value !== undefined) {
+            if (isValidGateTimeoutMs(entry.value)) {
+                return { timeoutMs: entry.value, source: 'config' };
+            }
+            warnOnce(`${key}:${entry.source}`, `Ignoring invalid ${key} from ${entry.source}; using the next timeout source.`);
+        }
+    }
+    const envValue = input.env.OAT_GATE_EXEC_TIMEOUT_MS?.trim();
+    if (envValue) {
+        const parsed = Number(envValue);
+        if (isValidGateTimeoutMs(parsed)) {
+            return { timeoutMs: parsed, source: 'env' };
+        }
+        warnOnce('env', 'Ignoring invalid OAT_GATE_EXEC_TIMEOUT_MS; using the next timeout source.');
+    }
+    const scope = input.reviewScope?.trim().toLowerCase() ?? '';
+    if (reviewType === 'artifact') {
+        return { timeoutMs: 900_000, source: 'scope-default' };
+    }
+    if (reviewType === 'code') {
+        if (/^p\d+-t\d+$/.test(scope)) {
+            return { timeoutMs: 900_000, source: 'scope-default' };
+        }
+        if (scope === 'final' ||
+            /^p\d+$/.test(scope) ||
+            /^p\d+-p\d+$/.test(scope)) {
+            return { timeoutMs: 1_800_000, source: 'scope-default' };
+        }
+    }
+    return { timeoutMs: GATE_EXEC_TIMEOUT_MS, source: 'default' };
+}
+function rawRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+async function readRawConfig(path) {
+    try {
+        return rawRecord(parseJsonConfig(await readFile(path, 'utf8'), path)) ?? {};
+    }
+    catch (error) {
+        if (typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            error.code === 'ENOENT') {
+            return {};
+        }
+        throw error;
+    }
+}
+async function readRawGateTimeoutLayers(input) {
+    const configs = await Promise.all([
+        readRawConfig(join(input.repoRoot, '.oat', 'config.local.json')),
+        readRawConfig(join(input.repoRoot, '.oat', 'config.json')),
+        readRawConfig(join(input.userConfigDir, 'config.json')),
+    ]);
+    const layers = ['local', 'shared', 'user'];
+    const target = [];
+    const workflow = [];
+    const reviewType = input.reviewType?.trim().toLowerCase();
+    for (const [index, config] of configs.entries()) {
+        const layer = layers[index];
+        const workflowConfig = rawRecord(config.workflow);
+        const gates = rawRecord(workflowConfig?.gates);
+        const execTargets = rawRecord(gates?.execTargets);
+        const rawTarget = rawRecord(execTargets?.[input.targetId]);
+        if (rawTarget &&
+            Object.prototype.hasOwnProperty.call(rawTarget, 'timeoutMs')) {
+            target.push({ layer, value: rawTarget.timeoutMs });
+        }
+        const gateTimeouts = rawRecord(workflowConfig?.gateTimeouts);
+        if ((reviewType === 'code' || reviewType === 'artifact') &&
+            gateTimeouts &&
+            Object.prototype.hasOwnProperty.call(gateTimeouts, reviewType)) {
+            workflow.push({ layer, value: gateTimeouts[reviewType] });
+        }
+    }
+    return { target, workflow };
+}
 function resolveGateLivenessIntervalMs(env) {
     const rawValue = env.OAT_GATE_LIVENESS_INTERVAL_MS?.trim();
     if (!rawValue) {
@@ -431,6 +655,9 @@ function parseExecTargetConfig(options) {
         ...(options.priority !== undefined
             ? { priority: parseNumericFlag(options.priority, '--priority', 0) }
             : {}),
+        ...(options.timeoutMs !== undefined
+            ? { timeoutMs: parseGateTimeoutFlag(options.timeoutMs, '--timeout-ms') }
+            : {}),
         ...(options.invocationModel !== undefined ||
             options.invocationReasoningEffort !== undefined
             ? {
@@ -873,7 +1100,7 @@ async function resolveSelectedExecTarget(targets, options, producerIdentity, con
     }
     return attachDiversityMetadata(selected, avoid, producerIdentity);
 }
-async function executeTarget(selected, prompt, context, dependencies) {
+async function executeTarget(selected, prompt, context, dependencies, timeout) {
     const [command, baseArgs] = argvHead(selected.target.baseCommand);
     if (!command) {
         throw new Error(`Exec target "${selected.id}" has an empty base command.`);
@@ -881,21 +1108,39 @@ async function executeTarget(selected, prompt, context, dependencies) {
     const modelArgs = selected.model && !findPinnedModelArg(selected.target.baseCommand)
         ? ['--model', selected.model]
         : [];
-    const timeoutMs = resolveGateExecTimeoutMs(dependencies.processEnv);
     const livenessIntervalMs = resolveGateLivenessIntervalMs(dependencies.processEnv);
-    if (!context.json) {
-        context.logger.info(`Running gate target ${selected.id} (${selected.target.runtime}); timeout=${timeoutMs}ms.`);
+    const activityProbe = await dependencies.createGateActivityProbe({
+        runtime: selected.target.runtime,
+        cwd: context.cwd,
+        home: context.home,
+        spawnedAt: Date.now(),
+    });
+    if (context.json) {
+        dependencies.writeDiagnostic(`${JSON.stringify({
+            type: 'gate-start',
+            target: selected.id,
+            runtime: selected.target.runtime,
+            timeoutMs: timeout.timeoutMs,
+            timeoutSource: timeout.source,
+        })}\n`);
+    }
+    else {
+        context.logger.info(`Running gate target ${selected.id} (${selected.target.runtime}); timeout=${timeout.timeoutMs}ms (source=${timeout.source}).`);
     }
     try {
         return await dependencies.runProcess(command, [...baseArgs, ...modelArgs, ...prompt], {
             cwd: context.cwd,
             env: dependencies.processEnv,
+            ...(activityProbe ? { activityProbe } : {}),
             livenessIntervalMs,
-            onLiveness: ({ elapsedMs, hardBudgetMs, idleMs }) => {
+            onLiveness: ({ elapsedMs, hardBudgetMs, idleMs, processAlive, activityProbeStatus, lastActivityEvidence, }) => {
                 const telemetry = {
                     elapsedMs,
                     hardBudgetMs,
                     idleMs,
+                    processAlive,
+                    ...(activityProbeStatus ? { activityProbeStatus } : {}),
+                    ...(lastActivityEvidence ? { lastActivityEvidence } : {}),
                     target: selected.id,
                     type: 'gate-liveness',
                 };
@@ -903,13 +1148,18 @@ async function executeTarget(selected, prompt, context, dependencies) {
                     dependencies.writeDiagnostic(`${JSON.stringify(telemetry)}\n`);
                 }
                 else {
-                    context.logger.info(`Gate liveness: target=${selected.id} elapsed_ms=${elapsedMs} idle_ms=${idleMs} hard_budget_ms=${hardBudgetMs}.`);
+                    const activityDescription = lastActivityEvidence
+                        ? lastActivityEvidence.scope === 'ambient-runtime'
+                            ? 'ambient runtime activity (not attributable to this gate child)'
+                            : 'project-directory activity'
+                        : `${activityProbeStatus?.status ?? 'unavailable'} (${activityProbeStatus?.attemptedPath ?? 'no path'})`;
+                    context.logger.info(`Gate liveness: target=${selected.id} elapsed_ms=${elapsedMs} idle_ms=${idleMs} hard_budget_ms=${hardBudgetMs} process_alive=${processAlive} activity_evidence=${activityDescription}.`);
                 }
             },
             purpose: 'execute',
             stdin: 'ignore',
             stdio: 'pipe',
-            timeoutMs,
+            timeoutMs: timeout.timeoutMs,
         });
     }
     catch (error) {
@@ -1283,9 +1533,11 @@ function writeReviewGateResult(context, payload) {
     context.logger.info(payload.handoff);
 }
 function writeReviewGateExecutionFailure(context, payload) {
-    const message = payload.timedOut
-        ? `Review did not complete: target ${payload.target} timed out after ${payload.timeoutMs}ms.`
-        : `Review did not complete: target ${payload.target} exited with code ${payload.exitCode}.`;
+    const message = payload.refusal
+        ? `Review did not complete: reviewer refused the headless route (${payload.refusal}).`
+        : payload.timedOut
+            ? `Review did not complete: target ${payload.target} timed out after ${payload.timeoutMs}ms.`
+            : `Review did not complete: target ${payload.target} exited with code ${payload.exitCode}.`;
     if (context.json) {
         context.logger.json({
             status: 'review_failed',
@@ -1304,9 +1556,16 @@ function writeReviewGateExecutionFailure(context, payload) {
             ...(payload.timeoutMs !== undefined
                 ? { timeoutMs: payload.timeoutMs }
                 : {}),
+            ...(payload.timeoutSource !== undefined
+                ? { timeoutSource: payload.timeoutSource }
+                : {}),
             ...(payload.noOutputProduced !== undefined
                 ? { noOutputProduced: payload.noOutputProduced }
                 : {}),
+            ...(payload.refusal ? { refusal: payload.refusal } : {}),
+            ...(payload.activityEvidence
+                ? { activityEvidence: payload.activityEvidence }
+                : {}),
             message,
         });
         return;
@@ -1397,6 +1656,29 @@ function writeReviewGateTargetingFailure(context, payload) {
     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 finalizeReviewGateProjectLog(context, dependencies, finalization) {
+    const findings = finalization.counts
+        ? ` findings=critical:${finalization.counts.critical},important:${finalization.counts.important},medium:${finalization.counts.medium},minor:${finalization.counts.minor}`
+        : '';
+    const artifact = finalization.artifactPath
+        ? ` artifact=${finalization.artifactPath}`
+        : '';
+    const body = `target=${finalization.target} threshold=${finalization.threshold}${findings} exit=${finalization.exitCode} status=${finalization.status}${artifact}`;
+    try {
+        await dependencies.appendProjectLog({
+            repoRoot: finalization.repoRoot,
+            home: finalization.home,
+            project: finalization.project,
+            structural: true,
+            producer: 'oat gate review',
+            ref: finalization.ref,
+            body,
+        });
+    }
+    catch (error) {
+        context.logger.warn(`Warning: unable to append oat gate review result to the project log: ${error instanceof Error ? error.message : String(error)}. Gate result is unchanged.`);
+    }
+}
 async function updateConfigLayer(context, layer, dependencies, mutate) {
     const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
     const userConfigDir = join(context.home, '.oat');
@@ -1526,7 +1808,21 @@ async function runCrossProviderExec(prompt, options, context, dependencies) {
         const producerIdentity = parseProducerIdentityOption(options.producerIdentity);
         const selected = await resolveSelectedExecTarget(targets, options, producerIdentity, context, dependencies);
         logGateDiversity(selected, context);
-        const result = await executeTarget(selected, prompt, context, dependencies);
+        const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
+        const rawPersisted = await readRawGateTimeoutLayers({
+            repoRoot,
+            userConfigDir: join(context.home, '.oat'),
+            targetId: selected.id,
+        });
+        const timeout = resolveGateExecTimeout({
+            cliTimeoutMs: options.timeoutMs,
+            target: selected.target,
+            effective,
+            env: dependencies.processEnv,
+            warn: context.logger.warn,
+            rawPersisted,
+        });
+        const result = await executeTarget(selected, prompt, context, dependencies, timeout);
         process.exitCode = result.exitCode;
     }
     catch (error) {
@@ -1535,6 +1831,11 @@ async function runCrossProviderExec(prompt, options, context, dependencies) {
 }
 async function runReviewGate(prompt, options, context, dependencies) {
     const runId = randomUUID();
+    let runMarkerPath;
+    let runMarkerWritten = false;
+    let branchLocalGateCli;
+    let projectLogFinalization;
+    let projectLogFinalized = false;
     let postSelectionContext;
     try {
         const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
@@ -1555,6 +1856,22 @@ async function runReviewGate(prompt, options, context, dependencies) {
         });
         const selected = await resolveSelectedExecTarget(targets, options, producerIdentity, context, dependencies);
         const gateInvocation = createGateInvocationMetadata(runId, selected);
+        const rawPersisted = await readRawGateTimeoutLayers({
+            repoRoot,
+            userConfigDir,
+            targetId: selected.id,
+            reviewType: options.reviewType,
+        });
+        const timeout = resolveGateExecTimeout({
+            cliTimeoutMs: options.timeoutMs,
+            target: selected.target,
+            effective,
+            reviewType: options.reviewType,
+            reviewScope: options.reviewScope,
+            env: dependencies.processEnv,
+            warn: context.logger.warn,
+            rawPersisted,
+        });
         const dispatchReport = buildGateDispatchReport(gateInvocation, options.reviewScope?.trim() || 'gate-review');
         postSelectionContext = {
             project: projectPath,
@@ -1564,6 +1881,16 @@ async function runReviewGate(prompt, options, context, dependencies) {
             dispatchReport,
         };
         const threshold = parseReviewGateThreshold(options.exitNonzeroOn);
+        projectLogFinalization = {
+            repoRoot,
+            home: context.home,
+            project: projectPath,
+            ref: options.reviewScope?.trim() || 'gate-review',
+            target: selected.id,
+            threshold,
+            status: 'review_failed',
+            exitCode: 1,
+        };
         const before = await listReviewGateArtifactCandidates({
             repoRoot,
             effective,
@@ -1581,9 +1908,65 @@ async function runReviewGate(prompt, options, context, dependencies) {
                 : []),
             prompt.join(' '),
         ]);
-        const childResult = await executeTarget(selected, [reviewPrompt], context, dependencies);
+        runMarkerPath = join(tmpdir(), 'oat-gate-runs', `${runId}.json`);
+        runMarkerWritten = await dependencies.writeGateRunMarker(runMarkerPath, {
+            runId,
+            targetId: selected.id,
+            runtime: selected.target.runtime,
+            reviewType: options.reviewType?.trim() || null,
+            reviewScope: options.reviewScope?.trim() || null,
+            project: projectPath,
+            startedAt: new Date().toISOString(),
+            budgetMs: timeout.timeoutMs,
+            budgetSource: timeout.source,
+        }, (message) => context.logger.warn(message));
+        if (runMarkerWritten) {
+            if (context.json) {
+                dependencies.writeDiagnostic(`${JSON.stringify({
+                    type: 'gate-run-marker',
+                    runId,
+                    path: runMarkerPath,
+                })}\n`);
+            }
+            else {
+                context.logger.info(`Gate run marker: ${runMarkerPath}.`);
+            }
+        }
+        branchLocalGateCli = await dependencies.createBranchLocalGateCli({
+            runId,
+            launch: dependencies.currentGateCliLaunch(),
+        });
+        const childResult = await executeTarget(selected, [reviewPrompt], context, {
+            ...dependencies,
+            processEnv: {
+                ...dependencies.processEnv,
+                OAT_GATE_HEADLESS: '1',
+                OAT_NON_INTERACTIVE: '1',
+                OAT_GATE_RUN_ID: runId,
+                OAT_GATE_RUNTIME: gateInvocation.runtime,
+                OAT_INVOCATION_MODEL: gateInvocation.model,
+                OAT_GATE_CLI_PATH: branchLocalGateCli.cliPath,
+                OAT_GATE_CLI_ROOT: branchLocalGateCli.cliRoot,
+                OAT_GATE_ROUTE_RECEIPT_PATH: branchLocalGateCli.routeReceiptPath,
+            },
+        }, timeout);
+        const routeReceipt = await dependencies.readGateRouteReceipt(branchLocalGateCli.routeReceiptPath, branchLocalGateCli.cliRoot, selected.target.runtime);
+        dependencies.writeDiagnostic(`${JSON.stringify({
+            type: 'gate-route',
+            target: selected.id,
+            ...routeReceipt,
+        })}\n`);
         const childExitCode = childResult.exitCode;
-        if (childExitCode !== 0 && !childResult.timedOut) {
+        const refusal = childResult.refusal ??
+            extractStructuredRefusal(childResult.capturedOutput ?? '');
+        const writeRefusalFailure = () => {
+            if (!refusal) {
+                return false;
+            }
+            if (projectLogFinalization) {
+                projectLogFinalization.status = 'review_failed';
+                projectLogFinalization.exitCode = 1;
+            }
             writeReviewGateExecutionFailure(context, {
                 runId,
                 target: selected.id,
@@ -1591,13 +1974,18 @@ async function runReviewGate(prompt, options, context, dependencies) {
                 projectResolutionSource: reviewProject.source,
                 exitCode: childExitCode,
                 timedOut: childResult.timedOut ?? false,
-                timeoutMs: resolveGateExecTimeoutMs(dependencies.processEnv),
+                timeoutMs: timeout.timeoutMs,
+                timeoutSource: timeout.source,
+                refusal,
+                ...(childResult.activityEvidence
+                    ? { activityEvidence: childResult.activityEvidence }
+                    : {}),
                 gateInvocation,
                 dispatchReport,
             });
-            process.exitCode = childExitCode;
-            return;
-        }
+            process.exitCode = 1;
+            return true;
+        };
         const after = await listReviewGateArtifactCandidates({
             repoRoot,
             effective,
@@ -1608,9 +1996,46 @@ async function runReviewGate(prompt, options, context, dependencies) {
             before,
             after,
         });
+        if (projectLogFinalization) {
+            projectLogFinalization.artifactPath =
+                artifactResolution.artifact?.path ??
+                    artifactResolution.diagnosticArtifact?.path;
+        }
+        if (!artifactResolution.artifact && writeRefusalFailure()) {
+            return;
+        }
+        if (childExitCode !== 0 &&
+            !childResult.timedOut &&
+            !artifactResolution.artifact) {
+            if (projectLogFinalization) {
+                projectLogFinalization.status = 'review_failed';
+                projectLogFinalization.exitCode = childExitCode;
+            }
+            writeReviewGateExecutionFailure(context, {
+                runId,
+                target: selected.id,
+                project: projectPath,
+                projectResolutionSource: reviewProject.source,
+                exitCode: childExitCode,
+                timedOut: childResult.timedOut ?? false,
+                timeoutMs: timeout.timeoutMs,
+                timeoutSource: timeout.source,
+                ...(childResult.activityEvidence
+                    ? { activityEvidence: childResult.activityEvidence }
+                    : {}),
+                gateInvocation,
+                dispatchReport,
+            });
+            process.exitCode = childExitCode;
+            return;
+        }
         if (childResult.timedOut &&
             artifactResolution.matchingArtifactPaths.length === 0 &&
             !artifactResolution.diagnosticArtifact) {
+            if (projectLogFinalization) {
+                projectLogFinalization.status = 'review_failed';
+                projectLogFinalization.exitCode = childExitCode;
+            }
             writeReviewGateExecutionFailure(context, {
                 runId,
                 target: selected.id,
@@ -1618,8 +2043,12 @@ async function runReviewGate(prompt, options, context, dependencies) {
                 projectResolutionSource: reviewProject.source,
                 exitCode: childExitCode,
                 timedOut: true,
-                timeoutMs: resolveGateExecTimeoutMs(dependencies.processEnv),
+                timeoutMs: timeout.timeoutMs,
+                timeoutSource: timeout.source,
                 noOutputProduced: childResult.stdoutBytes + childResult.stderrBytes === 0,
+                ...(childResult.activityEvidence
+                    ? { activityEvidence: childResult.activityEvidence }
+                    : {}),
                 gateInvocation,
                 dispatchReport,
             });
@@ -1642,6 +2071,10 @@ async function runReviewGate(prompt, options, context, dependencies) {
                 : 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}.`;
+            if (projectLogFinalization) {
+                projectLogFinalization.status = 'targeting_correlation_failed';
+                projectLogFinalization.exitCode = 1;
+            }
             writeReviewGateTargetingFailure(context, {
                 runId,
                 target: selected.id,
@@ -1660,6 +2093,13 @@ async function runReviewGate(prompt, options, context, dependencies) {
         if (producedArtifact.containingProject !== reviewProject.path ||
             (reviewProject.source === 'declared' &&
                 initialTargetCorroboration.project !== 'matched')) {
+            if (writeRefusalFailure()) {
+                return;
+            }
+            if (projectLogFinalization) {
+                projectLogFinalization.status = 'targeting_correlation_failed';
+                projectLogFinalization.exitCode = 1;
+            }
             writeReviewGateTargetingFailure(context, {
                 runId,
                 target: selected.id,
@@ -1681,6 +2121,13 @@ async function runReviewGate(prompt, options, context, dependencies) {
         }
         if (!producedArtifact.generatedAt ||
             !Number.isFinite(producedArtifact.generatedTime)) {
+            if (writeRefusalFailure()) {
+                return;
+            }
+            if (projectLogFinalization) {
+                projectLogFinalization.status = 'artifact_validation_failed';
+                projectLogFinalization.exitCode = 1;
+            }
             writeReviewGateArtifactValidationFailure(context, {
                 runId,
                 target: selected.id,
@@ -1708,7 +2155,14 @@ async function runReviewGate(prompt, options, context, dependencies) {
             });
         }
         catch (error) {
+            if (writeRefusalFailure()) {
+                return;
+            }
             const detail = error instanceof Error ? error.message : String(error);
+            if (projectLogFinalization) {
+                projectLogFinalization.status = 'artifact_validation_failed';
+                projectLogFinalization.exitCode = 1;
+            }
             writeReviewGateArtifactValidationFailure(context, {
                 runId,
                 target: selected.id,
@@ -1725,12 +2179,22 @@ async function runReviewGate(prompt, options, context, dependencies) {
             process.exitCode = 1;
             return;
         }
+        if (projectLogFinalization) {
+            projectLogFinalization.counts = verdict.counts;
+        }
         const targetCorroboration = initialTargetCorroboration;
         const corroboration = corroborateGateInvocation(gateInvocation, verdict.gateInvocation, targetCorroboration);
         if (corroboration.run !== 'matched' ||
             corroboration.invocation !== 'matched') {
+            if (writeRefusalFailure()) {
+                return;
+            }
             const missing = corroboration.run === 'missing' ||
                 corroboration.invocation === 'missing';
+            if (projectLogFinalization) {
+                projectLogFinalization.status = 'artifact_validation_failed';
+                projectLogFinalization.exitCode = 1;
+            }
             writeReviewGateArtifactValidationFailure(context, {
                 runId,
                 target: selected.id,
@@ -1750,6 +2214,13 @@ async function runReviewGate(prompt, options, context, dependencies) {
             return;
         }
         if (verdict.invocation !== 'gate') {
+            if (writeRefusalFailure()) {
+                return;
+            }
+            if (projectLogFinalization) {
+                projectLogFinalization.status = 'artifact_validation_failed';
+                projectLogFinalization.exitCode = 1;
+            }
             writeReviewGateArtifactValidationFailure(context, {
                 runId,
                 target: selected.id,
@@ -1773,6 +2244,12 @@ async function runReviewGate(prompt, options, context, dependencies) {
             threshold,
             blocking,
         });
+        if (projectLogFinalization) {
+            projectLogFinalization.status = blocking ? 'blocked' : 'ok';
+            projectLogFinalization.exitCode = blocking ? 1 : 0;
+            projectLogFinalization.counts = verdict.counts;
+            projectLogFinalization.artifactPath = producedArtifact.path;
+        }
         writeReviewGateResult(context, {
             status: blocking ? 'blocked' : 'ok',
             runId,
@@ -1809,6 +2286,22 @@ async function runReviewGate(prompt, options, context, dependencies) {
             writeError(context, error);
         }
     }
+    finally {
+        try {
+            if (branchLocalGateCli) {
+                await dependencies.removeBranchLocalGateCli(branchLocalGateCli);
+            }
+            if (runMarkerPath) {
+                await dependencies.removeGateRunMarker(runMarkerPath, (message) => context.logger.warn(message));
+            }
+        }
+        finally {
+            if (projectLogFinalization && !projectLogFinalized) {
+                projectLogFinalized = true;
+                await finalizeReviewGateProjectLog(context, dependencies, projectLogFinalization);
+            }
+        }
+    }
 }
 export function createGateCommand(overrides = {}) {
     const dependencies = {
@@ -1816,6 +2309,10 @@ export function createGateCommand(overrides = {}) {
         ...overrides,
     };
     const cmd = new Command('gate').description('Resolve and manage workflow gate configuration');
+    cmd.addCommand(createGateRouteCommand({
+        buildCommandContext: dependencies.buildCommandContext,
+        processEnv: dependencies.processEnv,
+    }));
     cmd
         .command('resolve')
         .description('Print the resolved gate configuration for a skill')
@@ -1849,11 +2346,13 @@ export function createGateCommand(overrides = {}) {
     });
     cmd
         .command('cross-provider-exec')
+        .alias('exec')
         .description('Run a prompt through an alternate configured runtime target')
         .option('--target <id>', 'Run this exact exec target')
         .option('--avoid <mode>', 'Avoidance mode: same-family, same-runtime, or none')
         .option('--current-runtime <runtime>', 'Override detected runtime for testing or manual routing')
         .option('--producer-identity <identity>', 'Producer identity as <value>:<declared|observed|inferred|unknown>')
+        .option('--timeout-ms <milliseconds>', `Gate timeout in milliseconds (${MIN_GATE_TIMEOUT_MS}-${MAX_GATE_TIMEOUT_MS})`)
         .argument('<prompt...>', 'Prompt arguments appended to the target command')
         .action(async (prompt, options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));
@@ -1866,6 +2365,7 @@ export function createGateCommand(overrides = {}) {
         .option('--avoid <mode>', 'Avoidance mode: same-family, same-runtime, or none')
         .option('--current-runtime <runtime>', 'Override detected runtime for testing or manual routing')
         .option('--producer-identity <identity>', 'Producer identity as <value>:<declared|observed|inferred|unknown>')
+        .option('--timeout-ms <milliseconds>', `Gate timeout in milliseconds (${MIN_GATE_TIMEOUT_MS}-${MAX_GATE_TIMEOUT_MS})`)
         .option('--project <path-or-name>', 'Project path or name to review; defaults to the active project')
         .option('--review-scope <scope>', 'Review scope hint for the provider')
         .option('--review-type <type>', 'Review type hint for the provider')
@@ -1887,6 +2387,7 @@ export function createGateCommand(overrides = {}) {
         .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('--timeout-ms <milliseconds>', `Target gate timeout in milliseconds (${MIN_GATE_TIMEOUT_MS}-${MAX_GATE_TIMEOUT_MS})`)
         .option('--disable', 'Disable this exec target in the selected layer')
         .option('--layer <layer>', 'Config layer to write: shared, local, or user')
         .action(async (targetId, options, command) => {