@open-agent-toolkit/cli 0.1.13 → 0.1.15

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,
+    };
+}

package/dist/review-remote/project-resolver.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Project resolution helper for the project-rail provide-remote skill
+ * (see design.md → Component Design → `oat-project-review-provide-remote`).
+ *
+ * Locates the OAT project on machine B by scanning the PR diff for
+ * `state.md` files two levels deep under `.oat/projects/` (scope/project). An
+ * explicit `--project <path>` override takes precedence over the scan and is
+ * validated to resolve to a directory containing `state.md`.
+ *
+ * The result is a discriminated union mirroring {@link NarrowingResult}'s
+ * pattern so callers branch on `kind`.
+ */
+export interface ResolvedProject {
+    kind: 'resolved';
+    /** Project directory path (no trailing slash, no `state.md` suffix). */
+    projectPath: string;
+}
+export interface AmbiguousProject {
+    kind: 'ambiguous';
+    /** Sorted, de-duplicated candidate project directory paths. */
+    candidates: string[];
+}
+export interface ProjectNotFound {
+    kind: 'not-found';
+}
+export interface InvalidOverride {
+    kind: 'invalid-override';
+    overridePath: string;
+    message: string;
+}
+export type ResolveResult = ResolvedProject | AmbiguousProject | ProjectNotFound | InvalidOverride;
+export interface ResolveOptions {
+    /** Explicit `--project <path>` override; takes precedence over diff scan. */
+    overridePath?: string;
+    /**
+     * Existence probe for `state.md`. Injected so tests avoid the real
+     * filesystem. Receives a candidate `state.md` path.
+     */
+    pathExists?: (path: string) => boolean;
+}
+/**
+ * Resolve the target OAT project from a PR's changed-file list, honoring an
+ * explicit override.
+ */
+export declare function resolveProject(diffFiles: string[], options?: ResolveOptions): ResolveResult;
+//# sourceMappingURL=project-resolver.d.ts.map

package/dist/review-remote/project-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-resolver.d.ts","sourceRoot":"","sources":["../../src/review-remote/project-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,UAAU,CAAC;IACjB,wEAAwE;IACxE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,WAAW,CAAC;IAClB,+DAA+D;IAC/D,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,kBAAkB,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,aAAa,GACrB,eAAe,GACf,gBAAgB,GAChB,eAAe,GACf,eAAe,CAAC;AAEpB,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CACxC;AAaD;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EAAE,EACnB,OAAO,GAAE,cAAmB,GAC3B,aAAa,CAgCf"}

package/dist/review-remote/project-resolver.js

@@ -0,0 +1,60 @@
+/**
+ * Project resolution helper for the project-rail provide-remote skill
+ * (see design.md → Component Design → `oat-project-review-provide-remote`).
+ *
+ * Locates the OAT project on machine B by scanning the PR diff for
+ * `state.md` files two levels deep under `.oat/projects/` (scope/project). An
+ * explicit `--project <path>` override takes precedence over the scan and is
+ * validated to resolve to a directory containing `state.md`.
+ *
+ * The result is a discriminated union mirroring {@link NarrowingResult}'s
+ * pattern so callers branch on `kind`.
+ */
+/** Matches a two-level `.oat/projects/<scope>/<project>/state.md` path. */
+const STATE_MD_PATTERN = /^\.oat\/projects\/([^/]+)\/([^/]+)\/state\.md$/;
+/** Strip a trailing slash and a trailing `state.md` segment from a path. */
+function normalizeProjectDir(path) {
+    let dir = path.replace(/\/+$/, '');
+    if (dir.endsWith('/state.md')) {
+        dir = dir.slice(0, -'/state.md'.length);
+    }
+    else if (dir === 'state.md') {
+        dir = '';
+    }
+    return dir;
+}
+/**
+ * Resolve the target OAT project from a PR's changed-file list, honoring an
+ * explicit override.
+ */
+export function resolveProject(diffFiles, options = {}) {
+    // 1. Explicit override wins, but must point at a real project (has state.md).
+    if (options.overridePath !== undefined && options.overridePath !== '') {
+        const projectDir = normalizeProjectDir(options.overridePath);
+        const stateMdPath = `${projectDir}/state.md`;
+        const exists = options.pathExists?.(stateMdPath) ?? false;
+        if (!exists) {
+            return {
+                kind: 'invalid-override',
+                overridePath: options.overridePath,
+                message: `--project path "${options.overridePath}" does not resolve to a directory containing state.md.`,
+            };
+        }
+        return { kind: 'resolved', projectPath: projectDir };
+    }
+    // 2. Diff scan for `.oat/projects/<scope>/<project>/state.md`.
+    const candidates = new Set();
+    for (const file of diffFiles) {
+        const match = file.match(STATE_MD_PATTERN);
+        if (match) {
+            candidates.add(`.oat/projects/${match[1]}/${match[2]}`);
+        }
+    }
+    if (candidates.size === 0) {
+        return { kind: 'not-found' };
+    }
+    if (candidates.size > 1) {
+        return { kind: 'ambiguous', candidates: [...candidates].sort() };
+    }
+    return { kind: 'resolved', projectPath: [...candidates][0] };
+}