@open-agent-toolkit/cli 0.1.13 → 0.1.14

package/dist/review-remote/capability-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-probe.d.ts","sourceRoot":"","sources":["../../src/review-remote/capability-probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,EAAE,EAAE,OAAO,CAAC;IACZ,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,eAAe,CAAC,CAAC;AAEvD,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,eAAe,GAAG,SAAS,CAAC;AAEvE,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,OAAO,EAAE,cAAc,CAAC;IACxB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AA4CD;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,SAAS,EAChB,KAAK,CAAC,EAAE,UAAU,GACjB,OAAO,CAAC,gBAAgB,CAAC,CA2B3B"}

package/dist/review-remote/capability-probe.js

@@ -0,0 +1,87 @@
+/**
+ * Capability probe for the optional `agent-reviews` posting flow (see design.md
+ * → Error Handling → Capability probe).
+ *
+ * The provide-remote skills prefer `agent-reviews` for tooling symmetry IF it
+ * exposes a "post / submit a full PR review" flow. The probe runs a
+ * non-mutating `agent-reviews --help` once, parses the help text for such a
+ * flag, and caches the result for the run. `gh api` is always the safe
+ * fallback — the probe never fails the skill.
+ *
+ * Empirical current-state finding (probed 2026-05-29, `agent-reviews@1.0.2`):
+ * the CLI exposes list/detail/watch commands plus `--reply <id>` for replying
+ * to existing comments, but NO command or flag that posts a full PR review. So
+ * the probe returns `not-supported` today and the skill posts via `gh api`.
+ * The probe is forward-compatible: when `agent-reviews` gains a posting flow,
+ * this parser recognizes it without a code change to the skill.
+ */
+/**
+ * Candidate flag tokens that, if present in the help text, indicate a
+ * full-review posting flow. Reply-to-comment flags (`--reply`) are deliberately
+ * excluded — replying to an existing comment is not posting a review.
+ *
+ * The intent-specific tokens (`--post-review`, `--submit-review`) come first;
+ * the generic `--review`/`--post` are kept as broad fallbacks. The generic
+ * tokens carry a small forward-compat false-positive risk: a future
+ * `agent-reviews` could add `--review` with an unrelated meaning (e.g.
+ * "show a review"), which the probe would report as `supported`. That risk is
+ * accepted here because `gh api` remains the safe posting path even when the
+ * probe mis-detects an `agent-reviews` posting flow — a false positive degrades
+ * to the same fallback as `unknown`, it never drops or corrupts a review.
+ */
+const POSTING_FLAG_CANDIDATES = [
+    '--post-review',
+    '--submit-review',
+    '--review',
+    '--post',
+];
+/** Extract the first posting flag present in the help text, or `undefined`. */
+function findPostingFlag(helpText) {
+    for (const flag of POSTING_FLAG_CANDIDATES) {
+        // Word-boundary-ish match: the flag followed by whitespace, `=`, or EOL, so
+        // `--post` does not spuriously match `--post-review` (and vice versa) and a
+        // substring of an unrelated token never matches.
+        const pattern = new RegExp(`(?:^|\\s)${escapeRegExp(flag)}(?=$|[\\s=])`, 'm');
+        if (pattern.test(helpText)) {
+            return flag;
+        }
+    }
+    return undefined;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Probe whether `agent-reviews` supports posting a full PR review.
+ *
+ * @param probe injectable `agent-reviews --help` runner.
+ * @param cache optional per-run cache; when provided, the probe runs at most
+ *   once and subsequent calls return the cached result.
+ */
+export async function probeAgentReviewsPosting(probe, cache) {
+    if (cache?.result !== undefined) {
+        return cache.result;
+    }
+    let outcome;
+    try {
+        outcome = await probe();
+    }
+    catch {
+        // A rejecting probe is treated the same as an errored one: unknown.
+        outcome = { ok: false, stdout: '' };
+    }
+    let result;
+    if (!outcome.ok) {
+        result = { posting: 'unknown' };
+    }
+    else {
+        const flag = findPostingFlag(outcome.stdout);
+        result = flag
+            ? { posting: 'supported', flag }
+            : { posting: 'not-supported' };
+    }
+    if (cache) {
+        cache.result = result;
+    }
+    return result;
+}

package/dist/review-remote/line-mapper.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Inline-comment line-mapping validator (see design.md → Error Handling →
+ * Inline-comment line mapping).
+ *
+ * GitHub's `POST /repos/:owner/:repo/pulls/:N/reviews` rejects inline comments
+ * at file:line positions not present in the PR diff. Before adding a finding to
+ * the `comments[]` payload, the caller classifies it against the parsed hunk
+ * ranges. Out-of-diff findings are NOT silently dropped or shifted — the caller
+ * downgrades them to a top-level "Findings outside the PR diff" subsection.
+ *
+ * Two parsers feed one classifier with a single shared {@link HunkRange} shape:
+ *  - {@link parsePullFilesPatch} for the per-file `patch` field of
+ *    `gh api /repos/.../pulls/<N>/files` (rich-context mode).
+ *  - {@link parseUnifiedDiff} for `gh pr diff <N>` (diff-only fallback mode).
+ */
+/** A single diff hunk's old- and new-side ranges. Shared by both parsers. */
+export interface HunkRange {
+    /** 1-based start line on the old (LEFT) side. */
+    oldStart: number;
+    /** Line count on the old side. */
+    oldCount: number;
+    /** 1-based start line on the new (RIGHT) side. */
+    newStart: number;
+    /** Line count on the new side. */
+    newCount: number;
+    /** Pre-rename path, when the owning file was renamed. */
+    previousFilename?: string;
+}
+/** A finding location to classify against a file's hunk ranges. */
+export interface FindingLocation {
+    file: string;
+    line: number;
+    /** Set when the finding is explicitly about removed code (LEFT side). */
+    removed?: boolean;
+}
+export interface InDiffClassification {
+    status: 'in-diff';
+    side: 'RIGHT' | 'LEFT';
+    line: number;
+}
+export interface OutOfDiffClassification {
+    status: 'out-of-diff';
+    /** Original file reference, carried through for the downgrade subsection. */
+    file: string;
+    /** Original line reference, carried through for the downgrade subsection. */
+    line: number;
+}
+export type FindingClassification = InDiffClassification | OutOfDiffClassification;
+/**
+ * Parse the `patch` field of a single `gh api .../pulls/<N>/files` entry into
+ * its hunk ranges. Returns `[]` for an empty patch (e.g., a binary file, whose
+ * entry has no `patch`).
+ *
+ * Caller contract for renamed files: a `gh api .../files` entry carries the
+ * pre-rename path in a sibling `previous_filename` field, NOT in `patch`. This
+ * parser only sees `patch`, so it cannot populate `HunkRange.previousFilename`
+ * in rich-context (gh api) mode. When a finding is reported against the
+ * pre-rename path, the caller must remap it to the entry's post-rename
+ * `filename` (using the JSON `previous_filename`) before calling
+ * `classifyFinding` — otherwise the finding is treated as out-of-diff. (The
+ * `gh pr diff` path handles this internally: `parseUnifiedDiff` records
+ * `previousFilename` from the `rename from` header.)
+ */
+export declare function parsePullFilesPatch(patch: string): HunkRange[];
+/**
+ * Parse a full `gh pr diff <N>` unified diff into a map of post-image file path
+ * → hunk ranges. Renamed files are keyed under their post-rename path with
+ * `previousFilename` recorded; binary files map to an empty array.
+ */
+export declare function parseUnifiedDiff(diff: string): Record<string, HunkRange[]>;
+/**
+ * Classify a finding against a file's hunk ranges.
+ *
+ * A line inside any hunk's new-side range is `in-diff` on the `RIGHT` side
+ * (additions/context); when the finding is explicitly about removed code it is
+ * mapped to the `LEFT` side instead. A line outside every hunk — or a file with
+ * no ranges (binary) — is `out-of-diff`, carrying the original `file:line` so
+ * the caller can downgrade it without mutating the source finding.
+ */
+export declare function classifyFinding(finding: FindingLocation, ranges: HunkRange[]): FindingClassification;
+//# sourceMappingURL=line-mapper.d.ts.map

package/dist/review-remote/line-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"line-mapper.d.ts","sourceRoot":"","sources":["../../src/review-remote/line-mapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,6EAA6E;AAC7E,MAAM,WAAW,SAAS;IACxB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,aAAa,CAAC;IACtB,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,qBAAqB,GAC7B,oBAAoB,GACpB,uBAAuB,CAAC;AAkB5B;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,CAY9D;AAUD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CA+E1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,SAAS,EAAE,GAClB,qBAAqB,CAevB"}

package/dist/review-remote/line-mapper.js

@@ -0,0 +1,165 @@
+/**
+ * Inline-comment line-mapping validator (see design.md → Error Handling →
+ * Inline-comment line mapping).
+ *
+ * GitHub's `POST /repos/:owner/:repo/pulls/:N/reviews` rejects inline comments
+ * at file:line positions not present in the PR diff. Before adding a finding to
+ * the `comments[]` payload, the caller classifies it against the parsed hunk
+ * ranges. Out-of-diff findings are NOT silently dropped or shifted — the caller
+ * downgrades them to a top-level "Findings outside the PR diff" subsection.
+ *
+ * Two parsers feed one classifier with a single shared {@link HunkRange} shape:
+ *  - {@link parsePullFilesPatch} for the per-file `patch` field of
+ *    `gh api /repos/.../pulls/<N>/files` (rich-context mode).
+ *  - {@link parseUnifiedDiff} for `gh pr diff <N>` (diff-only fallback mode).
+ */
+/** Matches a unified-diff hunk header: `@@ -a,b +c,d @@`. */
+const HUNK_HEADER_PATTERN = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
+function parseHunkHeader(line) {
+    const match = line.match(HUNK_HEADER_PATTERN);
+    if (!match) {
+        return null;
+    }
+    const oldStart = Number(match[1]);
+    // A missing count means 1 per unified-diff convention.
+    const oldCount = match[2] === undefined ? 1 : Number(match[2]);
+    const newStart = Number(match[3]);
+    const newCount = match[4] === undefined ? 1 : Number(match[4]);
+    return { oldStart, oldCount, newStart, newCount };
+}
+/**
+ * Parse the `patch` field of a single `gh api .../pulls/<N>/files` entry into
+ * its hunk ranges. Returns `[]` for an empty patch (e.g., a binary file, whose
+ * entry has no `patch`).
+ *
+ * Caller contract for renamed files: a `gh api .../files` entry carries the
+ * pre-rename path in a sibling `previous_filename` field, NOT in `patch`. This
+ * parser only sees `patch`, so it cannot populate `HunkRange.previousFilename`
+ * in rich-context (gh api) mode. When a finding is reported against the
+ * pre-rename path, the caller must remap it to the entry's post-rename
+ * `filename` (using the JSON `previous_filename`) before calling
+ * `classifyFinding` — otherwise the finding is treated as out-of-diff. (The
+ * `gh pr diff` path handles this internally: `parseUnifiedDiff` records
+ * `previousFilename` from the `rename from` header.)
+ */
+export function parsePullFilesPatch(patch) {
+    if (!patch) {
+        return [];
+    }
+    const ranges = [];
+    for (const line of patch.split('\n')) {
+        const hunk = parseHunkHeader(line);
+        if (hunk) {
+            ranges.push(hunk);
+        }
+    }
+    return ranges;
+}
+/** Strip a leading `a/` or `b/` diff prefix from a path token. */
+function stripDiffPrefix(path) {
+    if (path.startsWith('a/') || path.startsWith('b/')) {
+        return path.slice(2);
+    }
+    return path;
+}
+/**
+ * Parse a full `gh pr diff <N>` unified diff into a map of post-image file path
+ * → hunk ranges. Renamed files are keyed under their post-rename path with
+ * `previousFilename` recorded; binary files map to an empty array.
+ */
+export function parseUnifiedDiff(diff) {
+    const byFile = {};
+    if (!diff) {
+        return byFile;
+    }
+    const lines = diff.split('\n');
+    let currentFile = null;
+    let previousFilename;
+    let renameFrom;
+    const ensureFile = (path) => {
+        if (!byFile[path]) {
+            byFile[path] = [];
+        }
+        return byFile[path];
+    };
+    for (const line of lines) {
+        if (line.startsWith('diff --git ')) {
+            // `diff --git a/<old> b/<new>` — default the file to the new path.
+            const parts = line.slice('diff --git '.length).trim().split(' ');
+            const newPath = parts.length >= 2 ? stripDiffPrefix(parts[parts.length - 1]) : null;
+            currentFile = newPath;
+            previousFilename = undefined;
+            renameFrom = undefined;
+            if (currentFile) {
+                ensureFile(currentFile);
+            }
+            continue;
+        }
+        if (line.startsWith('rename from ')) {
+            renameFrom = line.slice('rename from '.length).trim();
+            continue;
+        }
+        if (line.startsWith('rename to ')) {
+            const renameTo = line.slice('rename to '.length).trim();
+            // Re-key under the post-rename path and drop the placeholder key.
+            if (currentFile && currentFile !== renameTo) {
+                delete byFile[currentFile];
+            }
+            currentFile = renameTo;
+            previousFilename = renameFrom;
+            ensureFile(currentFile);
+            continue;
+        }
+        if (line.startsWith('+++ ')) {
+            const token = line.slice('+++ '.length).trim();
+            if (token !== '/dev/null') {
+                const path = stripDiffPrefix(token);
+                if (path && path !== currentFile) {
+                    if (currentFile) {
+                        delete byFile[currentFile];
+                    }
+                    currentFile = path;
+                    ensureFile(currentFile);
+                }
+            }
+            continue;
+        }
+        if (line.startsWith('Binary files ')) {
+            // Binary file: no hunks, keep the (already-ensured) empty array.
+            continue;
+        }
+        const hunk = parseHunkHeader(line);
+        if (hunk && currentFile) {
+            if (previousFilename) {
+                hunk.previousFilename = previousFilename;
+            }
+            ensureFile(currentFile).push(hunk);
+        }
+    }
+    return byFile;
+}
+/**
+ * Classify a finding against a file's hunk ranges.
+ *
+ * A line inside any hunk's new-side range is `in-diff` on the `RIGHT` side
+ * (additions/context); when the finding is explicitly about removed code it is
+ * mapped to the `LEFT` side instead. A line outside every hunk — or a file with
+ * no ranges (binary) — is `out-of-diff`, carrying the original `file:line` so
+ * the caller can downgrade it without mutating the source finding.
+ */
+export function classifyFinding(finding, ranges) {
+    for (const range of ranges) {
+        if (finding.removed) {
+            const oldEnd = range.oldStart + range.oldCount - 1;
+            if (finding.line >= range.oldStart && finding.line <= oldEnd) {
+                return { status: 'in-diff', side: 'LEFT', line: finding.line };
+            }
+            continue;
+        }
+        const newEnd = range.newStart + range.newCount - 1;
+        if (finding.line >= range.newStart && finding.line <= newEnd) {
+            return { status: 'in-diff', side: 'RIGHT', line: finding.line };
+        }
+    }
+    return { status: 'out-of-diff', file: finding.file, line: finding.line };
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Parser for the posted-review-body marker block.
+ *
+ * The marker block is an HTML comment opened by `<!-- oat-review-metadata`
+ * carrying simple single-line YAML-ish scalars (see design.md → Data Models →
+ * Posted-review-body). GitHub renders the comment as nothing but preserves it
+ * across round-trips, so it is the durable routing channel between the
+ * provide-remote skills (writers) and the receive-remote skills (readers).
+ *
+ * This is intentionally a tolerant single-line scalar parser — NOT a full YAML
+ * parser. The schema is flat (no nested structures), so a line-oriented reader
+ * is sufficient and avoids a dependency the schema does not need.
+ */
+/** Token that opens the marker comment block. */
+export declare const MARKER_BLOCK_OPEN = "oat-review-metadata";
+export type ReviewInvocation = 'manual' | 'auto';
+export interface MarkerBlock {
+    /** Always `true` for an OAT provide-remote review; the discriminator. */
+    oat_provide_remote: true;
+    /** Full 40-char hex SHA of the reviewed PR HEAD. */
+    oat_review_head_sha: string;
+    /** Scope token (`pNN`, `final`, …) or the `ad-hoc` sentinel. */
+    oat_review_scope: string;
+    /**
+     * Project path — present only on the project rail. Key existence (not a
+     * `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;
+    /** Forward-compat bag for unknown marker keys. Omitted when none seen. */
+    extras?: Record<string, string>;
+}
+/**
+ * Parse the first OAT marker block out of a posted-review body.
+ *
+ * Returns `null` when the body is not an OAT provide-remote review — either
+ * because no marker block exists, because `oat_provide_remote` is not `true`,
+ * or because the recorded head SHA is not a valid 40-char hex SHA (a value the
+ * caller could not safely narrow against; returning null lets the caller fall
+ * back to full-scope review).
+ */
+export declare function parseMarkerBlock(body: string): MarkerBlock | null;
+//# sourceMappingURL=marker-parser.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,97 @@
+/**
+ * Parser for the posted-review-body marker block.
+ *
+ * The marker block is an HTML comment opened by `<!-- oat-review-metadata`
+ * carrying simple single-line YAML-ish scalars (see design.md → Data Models →
+ * Posted-review-body). GitHub renders the comment as nothing but preserves it
+ * across round-trips, so it is the durable routing channel between the
+ * provide-remote skills (writers) and the receive-remote skills (readers).
+ *
+ * This is intentionally a tolerant single-line scalar parser — NOT a full YAML
+ * parser. The schema is flat (no nested structures), so a line-oriented reader
+ * is sufficient and avoids a dependency the schema does not need.
+ */
+/** Token that opens the marker comment block. */
+export const MARKER_BLOCK_OPEN = 'oat-review-metadata';
+/**
+ * Matches the first `<!-- oat-review-metadata ... -->` HTML comment block.
+ * Non-greedy body capture so a later comment in prose never wins.
+ */
+const MARKER_BLOCK_PATTERN = new RegExp(`<!--\\s*${MARKER_BLOCK_OPEN}\\s*([\\s\\S]*?)-->`);
+/** A full 40-character lowercase/uppercase hex SHA. */
+const FULL_SHA_PATTERN = /^[0-9a-fA-F]{40}$/;
+const KNOWN_KEYS = new Set([
+    'oat_provide_remote',
+    'oat_review_head_sha',
+    'oat_review_scope',
+    'oat_project',
+    'oat_review_invocation',
+]);
+/**
+ * Parse the first OAT marker block out of a posted-review body.
+ *
+ * Returns `null` when the body is not an OAT provide-remote review — either
+ * because no marker block exists, because `oat_provide_remote` is not `true`,
+ * or because the recorded head SHA is not a valid 40-char hex SHA (a value the
+ * caller could not safely narrow against; returning null lets the caller fall
+ * back to full-scope review).
+ */
+export function parseMarkerBlock(body) {
+    if (!body) {
+        return null;
+    }
+    const match = body.match(MARKER_BLOCK_PATTERN);
+    if (!match || match[1] === undefined) {
+        return null;
+    }
+    const raw = {};
+    for (const line of match[1].split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '') {
+            continue;
+        }
+        const sep = trimmed.indexOf(':');
+        if (sep === -1) {
+            continue;
+        }
+        const key = trimmed.slice(0, sep).trim().toLowerCase();
+        const value = trimmed.slice(sep + 1).trim();
+        if (key === '') {
+            continue;
+        }
+        raw[key] = value;
+    }
+    if (raw['oat_provide_remote'] !== 'true') {
+        return null;
+    }
+    const headSha = raw['oat_review_head_sha'];
+    if (!headSha || !FULL_SHA_PATTERN.test(headSha)) {
+        return null;
+    }
+    const scope = raw['oat_review_scope'];
+    if (!scope) {
+        return null;
+    }
+    const invocationRaw = raw['oat_review_invocation'];
+    const oat_review_invocation = invocationRaw === 'auto' ? 'auto' : 'manual';
+    const block = {
+        oat_provide_remote: true,
+        oat_review_head_sha: headSha,
+        oat_review_scope: scope,
+        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 extras = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!KNOWN_KEYS.has(key)) {
+            extras[key] = value;
+        }
+    }
+    if (Object.keys(extras).length > 0) {
+        block.extras = extras;
+    }
+    return block;
+}

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

@@ -0,0 +1,81 @@
+/**
+ * Re-review narrowing filter + stale-SHA guard (see design.md → Component
+ * Design + Error Handling → Stale prior-review SHA).
+ *
+ * Given the PR's prior provide-remote reviews and a `(rail, project, scope)`
+ * tuple, pick the most recent matching review and decide whether the current
+ * pass can narrow to `<prior_sha>..<HEAD>`. The guard runs existence + ancestry
+ * checks (via an injected {@link GitInvoker}) before declaring a narrowing
+ * range, so a rebased/force-pushed/shallow prior SHA never produces a
+ * misleading partial range.
+ */
+import type { ReviewInvocation } from './marker-parser.js';
+export type ReviewRail = 'ad-hoc' | 'project';
+/** A prior provide-remote review, distilled from its parsed marker block. */
+export interface PriorReview {
+    /** Full 40-char SHA recorded by the prior review. */
+    headSha: string;
+    /** Scope token or the `ad-hoc` sentinel. */
+    scope: string;
+    /** Project path — present only for project-rail reviews. */
+    project?: string;
+    invocation: ReviewInvocation;
+    /** ISO-8601 review submission timestamp, used for descending sort. */
+    submittedAt: string;
+}
+/**
+ * Narrow git surface needed by the guard. Callers pass a worktree-bound
+ * implementation (rich-context mode) or a fetch-capable one (diff-only mode);
+ * tests pass stubs.
+ */
+export interface GitInvoker {
+    /** `git cat-file -e <sha>` — does the object exist locally? */
+    objectExists(sha: string): Promise<boolean>;
+    /** `git merge-base --is-ancestor <sha> <head>` — reachable from HEAD? */
+    isAncestor(sha: string, head: string): Promise<boolean>;
+    /** `git fetch origin <sha>:<ref>` — fetch a single ref (diff-only mode). */
+    fetchRef(sha: string): Promise<boolean>;
+}
+export interface NarrowingInput {
+    reviews: PriorReview[];
+    rail: ReviewRail;
+    /** Resolved project path on the project rail; `null` on the ad-hoc rail. */
+    project: string | null;
+    /** Current scope token, or `ad-hoc`. */
+    scope: string;
+    /** 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;
+    /** Diff-only mode (no ephemeral worktree): fetch the single ref first. */
+    diffOnly?: boolean;
+}
+export type FullScopeReason = 'no-prior-review' | 'stale-sha';
+export interface NarrowRangeResult {
+    kind: 'narrow-range';
+    priorSha: string;
+    headSha: string;
+    /** Whether the caller still owes the user a confirm prompt. */
+    prompted: boolean;
+}
+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';
+    reason: 'stale-sha';
+    priorSha: string;
+}
+export type NarrowingResult = NarrowRangeResult | FullScopeFallbackResult | HardErrorResult;
+/**
+ * Pick the narrowing target for the current re-review pass.
+ */
+export declare function pickNarrowingTarget(input: NarrowingInput): Promise<NarrowingResult>;
+//# sourceMappingURL=narrowing.d.ts.map

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

@@ -0,0 +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"}

package/dist/review-remote/narrowing.js

@@ -0,0 +1,90 @@
+/**
+ * Re-review narrowing filter + stale-SHA guard (see design.md → Component
+ * Design + Error Handling → Stale prior-review SHA).
+ *
+ * Given the PR's prior provide-remote reviews and a `(rail, project, scope)`
+ * tuple, pick the most recent matching review and decide whether the current
+ * pass can narrow to `<prior_sha>..<HEAD>`. The guard runs existence + ancestry
+ * checks (via an injected {@link GitInvoker}) before declaring a narrowing
+ * range, so a rebased/force-pushed/shallow prior SHA never produces a
+ * misleading partial range.
+ */
+/** Does a prior review match the current `(rail, project, scope)` tuple? */
+function matchesTuple(review, input) {
+    if (input.rail === 'ad-hoc') {
+        // Ad-hoc: scope sentinel must match AND there must be no project key.
+        return review.scope === 'ad-hoc' && review.project === undefined;
+    }
+    // Project rail: same project AND same scope.
+    return (review.project !== undefined &&
+        review.project === input.project &&
+        review.scope === input.scope);
+}
+function mostRecentMatch(input) {
+    const matches = input.reviews.filter((r) => matchesTuple(r, input));
+    if (matches.length === 0) {
+        return null;
+    }
+    // Descending by submission time — newest matching review wins.
+    matches.sort((a, b) => b.submittedAt.localeCompare(a.submittedAt));
+    return matches[0];
+}
+/**
+ * Run the two-step stale-SHA guard. In diff-only mode, attempt a single-ref
+ * fetch before re-checking existence. Returns true only when the prior SHA both
+ * exists locally and is an ancestor of the current PR HEAD.
+ */
+async function guardPasses(priorSha, input) {
+    let exists = await input.git.objectExists(priorSha);
+    if (!exists && input.diffOnly) {
+        const fetched = await input.git.fetchRef(priorSha);
+        if (!fetched) {
+            return false;
+        }
+        exists = await input.git.objectExists(priorSha);
+    }
+    if (!exists) {
+        return false;
+    }
+    return input.git.isAncestor(priorSha, input.headSha);
+}
+/**
+ * Pick the narrowing target for the current re-review pass.
+ */
+export async function pickNarrowingTarget(input) {
+    const prior = mostRecentMatch(input);
+    if (!prior) {
+        return {
+            kind: 'full-scope-fallback',
+            reason: 'no-prior-review',
+            prompted: false,
+        };
+    }
+    const passed = await guardPasses(prior.headSha, input);
+    if (passed) {
+        return {
+            kind: 'narrow-range',
+            priorSha: prior.headSha,
+            headSha: input.headSha,
+            // Auto-narrow skips the prompt; otherwise the caller still confirms.
+            prompted: !input.autoNarrow,
+        };
+    }
+    // Guard failed. The user explicitly asked to narrow → hard error.
+    if (input.forceNarrow) {
+        return {
+            kind: 'hard-error',
+            reason: 'stale-sha',
+            priorSha: prior.headSha,
+        };
+    }
+    // Otherwise fall back to full scope. Auto-narrow surfaces this as the
+    // auto-fallback notice (no prompt); manual mode does not prompt here either —
+    // the fallback is informational.
+    return {
+        kind: 'full-scope-fallback',
+        reason: 'stale-sha',
+        priorSha: prior.headSha,
+        prompted: false,
+    };
+}