@open-agent-toolkit/cli 0.2.23 → 0.2.25

package/dist/commands/gate/index.js

@@ -1,4 +1,4 @@
-import { execFileSync, spawn } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
 import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
@@ -20,6 +20,7 @@ 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 { runChildProcess, } from './child-process.js';
 import { parseReviewGateVerdict, severityDisplayName, } from './review-verdict.js';
 import { createGateRouteCommand } from './route.js';
 const DEFAULT_DEPENDENCIES = {
@@ -75,6 +76,7 @@ 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;
+const AMBIENT_ACTIVITY_ATTRIBUTION = 'not attributable to this gate child';
 async function writeGateRunMarker(path, marker, warn) {
     try {
         await mkdir(join(tmpdir(), 'oat-gate-runs'), { recursive: true });
@@ -239,152 +241,6 @@ function corroborateGateInvocation(expected, actual, targetCorroboration) {
         },
     };
 }
-async function runChildProcess(command, args, options) {
-    return new Promise((resolve, reject) => {
-        let timedOut = false;
-        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, {
-            cwd: options.cwd,
-            env: options.env,
-            stdio: options.stdio === 'pipe'
-                ? [options.stdin, 'pipe', 'pipe']
-                : options.stdio,
-        });
-        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();
-            const destination = options.stdoutDestination === 'stderr'
-                ? process.stderr
-                : process.stdout;
-            destination.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();
-                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;
-        livenessInterval?.unref();
-        const timeout = setTimeout(() => {
-            timedOut = true;
-            child.kill('SIGTERM');
-            killTimeout = setTimeout(() => {
-                child.kill('SIGKILL');
-            }, 5_000);
-            killTimeout.unref();
-        }, options.timeoutMs);
-        timeout.unref();
-        child.on('error', (error) => {
-            clearTimeout(timeout);
-            if (livenessInterval) {
-                clearInterval(livenessInterval);
-            }
-            if (killTimeout) {
-                clearTimeout(killTimeout);
-            }
-            reject(error);
-        });
-        child.on('close', (code) => {
-            clearTimeout(timeout);
-            if (livenessInterval) {
-                clearInterval(livenessInterval);
-            }
-            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 } : {}),
-            });
-        });
-    });
-}
-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);
 }
@@ -1184,7 +1040,7 @@ async function executeTarget(selected, prompt, context, dependencies, timeout) {
                 else {
                     const activityDescription = lastActivityEvidence
                         ? lastActivityEvidence.scope === 'ambient-runtime'
-                            ? 'ambient runtime activity (not attributable to this gate child)'
+                            ? `ambient runtime activity (${AMBIENT_ACTIVITY_ATTRIBUTION})`
                             : '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}.`);
@@ -1606,6 +1462,25 @@ function writeReviewGateExecutionFailure(context, payload) {
         return;
     }
     context.logger.error(message);
+    if (payload.activityEvidence && !payload.refusal) {
+        context.logger.error(formatGateActivityEvidenceDiagnostic(payload.activityEvidence));
+    }
+}
+function formatGateActivityEvidenceDiagnostic(evidence, now = Date.now()) {
+    const transcriptScope = evidence.scope === 'ambient-runtime'
+        ? `${evidence.runtime} ambient transcript`
+        : `${evidence.runtime} project transcript`;
+    const baselineState = evidence.changedSinceBaseline
+        ? 'changed since baseline'
+        : 'did not change since baseline';
+    const observedAgoMs = Math.max(0, now - evidence.observedAt);
+    const lastChangeTiming = evidence.lastChangeAt === null
+        ? 'latest transcript change time unavailable'
+        : `latest transcript change was ${Math.max(0, evidence.observedAt - evidence.lastChangeAt)}ms before observation`;
+    const attributionWarning = evidence.scope === 'ambient-runtime'
+        ? ` This activity is ${AMBIENT_ACTIVITY_ATTRIBUTION}.`
+        : '';
+    return `Activity evidence: ${transcriptScope} metadata ${baselineState}; observed ${observedAgoMs}ms ago; ${lastChangeTiming}.${attributionWarning}`;
 }
 function writeReviewGateUnexpectedFailure(context, payload) {
     const message = payload.error instanceof Error
@@ -2085,8 +1960,7 @@ async function runReviewGate(prompt, options, context, dependencies) {
             ...routeReceipt,
         })}\n`);
         const childExitCode = childResult.exitCode;
-        const refusal = childResult.refusal ??
-            extractStructuredRefusal(childResult.capturedOutput ?? '');
+        const refusal = childResult.refusal;
         const writeRefusalFailure = () => {
             if (!refusal) {
                 return false;

package/dist/commands/review/latest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"latest.d.ts","sourceRoot":"","sources":["../../../src/commands/review/latest.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAO9B,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAE7E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;CACrB;AASD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,UAAU,wBAAwB;IAChC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;CACnE;AAgOD,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAkG9B;AAmDD,wBAAgB,yBAAyB,CACvC,SAAS,GAAE,OAAO,CAAC,wBAAwB,CAAM,GAChD,OAAO,CA2BT"}
+{"version":3,"file":"latest.d.ts","sourceRoot":"","sources":["../../../src/commands/review/latest.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAO9B,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAE7E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;CACrB;AASD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,UAAU,wBAAwB;IAChC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;CACnE;AAiPD,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAkG9B;AAmDD,wBAAgB,yBAAyB,CACvC,SAAS,GAAE,OAAO,CAAC,wBAAwB,CAAM,GAChD,OAAO,CA2BT"}

package/dist/commands/review/latest.js

@@ -99,20 +99,33 @@ function parseReviewLedgerEvents(planContent) {
     const remaining = planContent.slice(heading.index + heading[0].length);
     const nextHeadingIndex = remaining.search(/^##(?!#)[ \t]+\S.*\r?$/m);
     const section = nextHeadingIndex === -1 ? remaining : remaining.slice(0, nextHeadingIndex);
-    return section
+    const rows = section
         .split('\n')
         .filter((line) => line.trim().startsWith('|'))
-        .slice(2)
         .map((line) => line
         .split('|')
         .slice(1, -1)
-        .map((cell) => cell.trim()))
-        .filter((cells) => cells.length === 5)
-        .map(([scope = '', type = '', status = '', , artifact = '']) => ({
-        scope,
-        type,
-        status,
-        artifact,
+        .map((cell) => cell.trim()));
+    const headers = rows[0];
+    if (!headers) {
+        return [];
+    }
+    const normalizedHeaders = headers.map((header) => header.toLowerCase());
+    const scopeIndex = normalizedHeaders.indexOf('scope');
+    const typeIndex = normalizedHeaders.indexOf('type');
+    const statusIndex = normalizedHeaders.indexOf('status');
+    const artifactIndex = normalizedHeaders.indexOf('artifact');
+    if (scopeIndex === -1 ||
+        typeIndex === -1 ||
+        statusIndex === -1 ||
+        artifactIndex === -1) {
+        return [];
+    }
+    return rows.slice(2).map((cells) => ({
+        scope: cells[scopeIndex] ?? '',
+        type: cells[typeIndex] ?? '',
+        status: cells[statusIndex] ?? '',
+        artifact: cells[artifactIndex] ?? '',
     }));
 }
 async function correlateProjectActionability(repoRoot, projectPath, candidates) {

package/dist/config/resolve.js

@@ -68,7 +68,7 @@ const DEFAULT_WORKFLOW_CONFIG = {
         postImplementSequence: null,
         reviewExecutionModel: null,
         autoReviewAtHillCheckpoints: null,
-        autoNarrowReReviewScope: null,
+        autoNarrowReReviewScope: true,
         autoArtifactReview: {
             plan: true,
             analysis: true,

package/dist/review-remote/body-builder.d.ts

@@ -38,15 +38,13 @@ export interface OutOfDiffFinding {
     /** Finding description / rationale — preserved verbatim, never dropped. */
     body: string;
 }
-export interface BuildInput {
+interface BuildInputBase {
     /** Full 40-char hex SHA of the reviewed PR HEAD. */
     headSha: string;
     /** Scope token (`pNN`, `final`, …) or the `ad-hoc` sentinel. */
     scope: string;
     /** Project path — set only on the project rail; omitted on ad-hoc. */
     project?: string;
-    /** How the review was invoked. */
-    invocation: ReviewInvocation;
     /** 2-3 sentence human-readable summary. */
     summary: string;
     findings: BuilderFinding[];
@@ -63,6 +61,16 @@ export interface BuildInput {
     /** Commands the user can run to verify fixes; omitted when absent/empty. */
     verificationCommands?: string[];
 }
+interface LifecycleBuildInput {
+    invocation: Exclude<ReviewInvocation, 'gate'>;
+    gateTarget?: never;
+}
+interface GateBuildInput {
+    invocation: 'gate';
+    /** Exact non-empty target that owns this gate review lineage. */
+    gateTarget: string;
+}
+export type BuildInput = BuildInputBase & (LifecycleBuildInput | GateBuildInput);
 /**
  * Map a finding set to the GitHub review verdict: `REQUEST_CHANGES` when any
  * critical or important finding is present, otherwise `COMMENT` (including the
@@ -76,4 +84,5 @@ export declare function buildReviewBody(input: BuildInput): {
     body: string;
     verdict: ReviewVerdict;
 };
+export {};
 //# sourceMappingURL=body-builder.d.ts.map

package/dist/review-remote/body-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"body-builder.d.ts","sourceRoot":"","sources":["../../src/review-remote/body-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAE3E,MAAM,MAAM,aAAa,GAAG,iBAAiB,GAAG,SAAS,CAAC;AAE1D,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE5E,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,eAAe,CAAC;CAC3B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,eAAe,CAAC;IAC1B,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,UAAU,EAAE,gBAAgB,CAAC;IAC7B,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACvC,4EAA4E;IAC5E,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,aAAa,CAKpE;AAkED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,aAAa,CAAC;CACxB,CAkCA"}
+{"version":3,"file":"body-builder.d.ts","sourceRoot":"","sources":["../../src/review-remote/body-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAE3E,MAAM,MAAM,aAAa,GAAG,iBAAiB,GAAG,SAAS,CAAC;AAE1D,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE5E,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,eAAe,CAAC;CAC3B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,eAAe,CAAC;IAC1B,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,cAAc;IACtB,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACvC,4EAA4E;IAC5E,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;CACjC;AAED,UAAU,mBAAmB;IAC3B,UAAU,EAAE,OAAO,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;IAC9C,UAAU,CAAC,EAAE,KAAK,CAAC;CACpB;AAED,UAAU,cAAc;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,UAAU,GAAG,cAAc,GACrC,CAAC,mBAAmB,GAAG,cAAc,CAAC,CAAC;AAEzC;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,aAAa,CAKpE;AAgFD;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,aAAa,CAAC;CACxB,CAkCA"}

package/dist/review-remote/body-builder.js

@@ -45,6 +45,17 @@ function buildMarkerBlock(input) {
         lines.push(`oat_project: ${input.project}`);
     }
     lines.push(`oat_review_invocation: ${input.invocation}`);
+    if (input.invocation === 'gate') {
+        if (input.gateTarget.trim() === '' ||
+            input.gateTarget.trim() !== input.gateTarget) {
+            throw new Error('gate invocation requires an exact non-empty gateTarget');
+        }
+        lines.push(`oat_gate_target: ${input.gateTarget}`);
+    }
+    else if ('gateTarget' in input &&
+        input.gateTarget !== undefined) {
+        throw new Error('lifecycle invocation must not include gateTarget');
+    }
     return `<!-- ${MARKER_BLOCK_OPEN}\n${lines.join('\n')}\n-->`;
 }
 /**

package/dist/review-remote/marker-parser.d.ts

@@ -13,7 +13,7 @@
  */
 /** Token that opens the marker comment block. */
 export declare const MARKER_BLOCK_OPEN = "oat-review-metadata";
-export type ReviewInvocation = 'manual' | 'auto';
+export type ReviewInvocation = 'manual' | 'auto' | 'gate';
 export interface MarkerBlock {
     /** Always `true` for an OAT provide-remote review; the discriminator. */
     oat_provide_remote: true;
@@ -26,8 +26,13 @@ export interface MarkerBlock {
      * `null` value) discriminates project rail from ad-hoc rail.
      */
     oat_project?: string;
-    /** How the review was invoked. Defaults to `manual` when omitted. */
-    oat_review_invocation: ReviewInvocation;
+    /**
+     * How the review was invoked. Missing and unknown values stay undefined so
+     * legacy markers cannot silently acquire lifecycle lineage.
+     */
+    oat_review_invocation?: ReviewInvocation;
+    /** Exact gate target. Required before a gate marker can establish lineage. */
+    oat_gate_target?: string;
     /** Forward-compat bag for unknown marker keys. Omitted when none seen. */
     extras?: Record<string, string>;
 }

package/dist/review-remote/marker-parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"marker-parser.d.ts","sourceRoot":"","sources":["../../src/review-remote/marker-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,iDAAiD;AACjD,eAAO,MAAM,iBAAiB,wBAAwB,CAAC;AAavD,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,kBAAkB,EAAE,IAAI,CAAC;IACzB,oDAAoD;IACpD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,qBAAqB,EAAE,gBAAgB,CAAC;IACxC,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAUD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAqEjE"}
+{"version":3,"file":"marker-parser.d.ts","sourceRoot":"","sources":["../../src/review-remote/marker-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,iDAAiD;AACjD,eAAO,MAAM,iBAAiB,wBAAwB,CAAC;AAavD,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1D,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,kBAAkB,EAAE,IAAI,CAAC;IACzB,oDAAoD;IACpD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,qBAAqB,CAAC,EAAE,gBAAgB,CAAC;IACzC,8EAA8E;IAC9E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAWD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CA+EjE"}

package/dist/review-remote/marker-parser.js

@@ -26,6 +26,7 @@ const KNOWN_KEYS = new Set([
     'oat_review_scope',
     'oat_project',
     'oat_review_invocation',
+    'oat_gate_target',
 ]);
 /**
  * Parse the first OAT marker block out of a posted-review body.
@@ -73,17 +74,27 @@ export function parseMarkerBlock(body) {
         return null;
     }
     const invocationRaw = raw['oat_review_invocation'];
-    const oat_review_invocation = invocationRaw === 'auto' ? 'auto' : 'manual';
+    const oat_review_invocation = invocationRaw === 'manual' ||
+        invocationRaw === 'auto' ||
+        invocationRaw === 'gate'
+        ? invocationRaw
+        : undefined;
     const block = {
         oat_provide_remote: true,
         oat_review_head_sha: headSha,
         oat_review_scope: scope,
-        oat_review_invocation,
     };
+    if (oat_review_invocation !== undefined) {
+        block.oat_review_invocation = oat_review_invocation;
+    }
     // Project key existence (not a null value) discriminates the rail.
     if ('oat_project' in raw && raw['oat_project'] !== '') {
         block.oat_project = raw['oat_project'];
     }
+    const gateTarget = raw['oat_gate_target']?.trim();
+    if (gateTarget) {
+        block.oat_gate_target = gateTarget;
+    }
     const extras = {};
     for (const [key, value] of Object.entries(raw)) {
         if (!KNOWN_KEYS.has(key)) {

package/dist/review-remote/narrowing.d.ts

@@ -9,8 +9,15 @@
  * range, so a rebased/force-pushed/shallow prior SHA never produces a
  * misleading partial range.
  */
-import type { ReviewInvocation } from './marker-parser.js';
+import type { MarkerBlock, ReviewInvocation } from './marker-parser.js';
 export type ReviewRail = 'ad-hoc' | 'project';
+export type ReviewLineage = {
+    kind: 'lifecycle';
+} | {
+    kind: 'gate';
+    target: string;
+};
+export type ReviewInvocationKind = ReviewInvocation;
 /** A prior provide-remote review, distilled from its parsed marker block. */
 export interface PriorReview {
     /** Full 40-char SHA recorded by the prior review. */
@@ -19,10 +26,34 @@ export interface PriorReview {
     scope: string;
     /** Project path — present only for project-rail reviews. */
     project?: string;
-    invocation: ReviewInvocation;
+    invocation?: ReviewInvocationKind;
+    /** Review lineage; absent on legacy records, which are not eligible. */
+    lineage?: ReviewLineage;
     /** ISO-8601 review submission timestamp, used for descending sort. */
     submittedAt: string;
 }
+/** Provenance persisted on one tracked Reviews ledger row. */
+export interface ReviewLedgerProvenance {
+    reviewedHead: string;
+    scope: string;
+    project?: string;
+    invocation?: string;
+    gateTarget?: string;
+    artifact: string;
+    submittedAt: string;
+}
+/**
+ * Normalize one parsed GitHub marker into a narrowing candidate. Unknown
+ * invocation and target-less gate markers preserve their metadata but carry no
+ * lineage, so tuple matching rejects them and fails open.
+ */
+export declare function priorReviewFromMarker(marker: MarkerBlock, submittedAt: string): PriorReview;
+/**
+ * Normalize durable ledger provenance into the same candidate shape used by
+ * artifact-sourced reviews. Both sources then pass through {@link matchesTuple}
+ * and cannot drift into separate lineage predicates.
+ */
+export declare function priorReviewFromLedger(row: ReviewLedgerProvenance): PriorReview;
 /**
  * Narrow git surface needed by the guard. Callers pass a worktree-bound
  * implementation (rich-context mode) or a fetch-capable one (diff-only mode);
@@ -35,6 +66,8 @@ export interface GitInvoker {
     isAncestor(sha: string, head: string): Promise<boolean>;
     /** `git fetch origin <sha>:<ref>` — fetch a single ref (diff-only mode). */
     fetchRef(sha: string): Promise<boolean>;
+    /** Files changed in `<priorSha>..<headSha>`. */
+    changedFiles(priorSha: string, headSha: string): Promise<string[]>;
 }
 export interface NarrowingInput {
     reviews: PriorReview[];
@@ -43,30 +76,33 @@ export interface NarrowingInput {
     project: string | null;
     /** Current scope token, or `ad-hoc`. */
     scope: string;
+    /** Current review lineage, including the target for gate invocations. */
+    lineage: ReviewLineage;
     /** Current PR HEAD SHA. */
     headSha: string;
     git: GitInvoker;
     /** `--narrow` was passed explicitly: guard failure becomes a hard error. */
     forceNarrow?: boolean;
-    /** `workflow.autoNarrowReReviewScope === true`: never prompt. */
-    autoNarrow?: boolean;
+    /** Resolved preference: unset and true narrow; false forces full scope. */
+    narrowingPreference?: boolean;
     /** Diff-only mode (no ephemeral worktree): fetch the single ref first. */
     diffOnly?: boolean;
 }
-export type FullScopeReason = 'no-prior-review' | 'stale-sha';
+export type FullScopeReason = 'narrowing-disabled' | 'no-prior-review' | 'stale-sha';
+export type RangeClassification = 'empty' | 'bookkeeping-only' | 'substantive';
 export interface NarrowRangeResult {
     kind: 'narrow-range';
     priorSha: string;
     headSha: string;
-    /** Whether the caller still owes the user a confirm prompt. */
-    prompted: boolean;
+    classification: RangeClassification;
+    /** Why classification conservatively fell back, when enumeration failed. */
+    classificationReason?: 'changed-files-unavailable';
 }
 export interface FullScopeFallbackResult {
     kind: 'full-scope-fallback';
     reason: FullScopeReason;
     /** The stale SHA that triggered the fallback, when applicable. */
     priorSha?: string;
-    prompted: boolean;
 }
 export interface HardErrorResult {
     kind: 'hard-error';

package/dist/review-remote/narrowing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"narrowing.d.ts","sourceRoot":"","sources":["../../src/review-remote/narrowing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9C,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,gBAAgB,CAAC;IAC7B,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5C,yEAAyE;IACzE,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACxD,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,IAAI,EAAE,UAAU,CAAC;IACjB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,UAAU,CAAC;IAChB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,iEAAiE;IACjE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,MAAM,eAAe,GAAG,iBAAiB,GAAG,WAAW,CAAC;AAE9D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,MAAM,EAAE,eAAe,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,eAAe,GACvB,iBAAiB,GACjB,uBAAuB,GACvB,eAAe,CAAC;AAiDpB;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,eAAe,CAAC,CAuC1B"}
+{"version":3,"file":"narrowing.d.ts","sourceRoot":"","sources":["../../src/review-remote/narrowing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAIrE,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9C,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAErC,MAAM,MAAM,oBAAoB,GAAG,gBAAgB,CAAC;AAEpD,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAClC,wEAAwE;IACxE,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,8DAA8D;AAC9D,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,WAAW,EACnB,WAAW,EAAE,MAAM,GAClB,WAAW,CAYb;AAgBD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,sBAAsB,GAC1B,WAAW,CAcb;AAqBD;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5C,yEAAyE;IACzE,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACxD,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,gDAAgD;IAChD,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACpE;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,IAAI,EAAE,UAAU,CAAC;IACjB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,OAAO,EAAE,aAAa,CAAC;IACvB,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,UAAU,CAAC;IAChB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,2EAA2E;IAC3E,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,MAAM,eAAe,GACvB,oBAAoB,GACpB,iBAAiB,GACjB,WAAW,CAAC;AAChB,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,kBAAkB,GAAG,aAAa,CAAC;AAE/E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,mBAAmB,CAAC;IACpC,4EAA4E;IAC5E,oBAAoB,CAAC,EAAE,2BAA2B,CAAC;CACpD;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,MAAM,EAAE,eAAe,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,eAAe,GACvB,iBAAiB,GACjB,uBAAuB,GACvB,eAAe,CAAC;AAgGpB;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,eAAe,CAAC,CAyC1B"}