@open-agent-toolkit/cli 0.1.13 → 0.1.14

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

package/dist/review-remote/reviewer-dispatch.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Tier-1 dispatch wrapper for the `oat-reviewer` subagent's structured-output
+ * mode (see design.md → Component Design → `oat-project-review-provide-remote`
+ * and `.agents/agents/oat-reviewer.md` → Structured-Output Mode).
+ *
+ * The project-rail provide-remote skill's Tier 1 dispatch hands the reviewer a
+ * payload carrying the project context, the posted-review-body schema
+ * reference, the resolved re-review narrowing range, and the
+ * `oat_output_mode: structured` flag. In that mode the reviewer returns a
+ * `StructuredFindings` object in-memory rather than writing a review artifact;
+ * this wrapper validates that object and hands it back to the skill, which is
+ * then responsible for building the posted body and posting to GitHub.
+ *
+ * Responsibilities are deliberately narrow:
+ *
+ * - Build the dispatch payload with the structured-output flag p03 wired.
+ * - Forward it to an injected {@link Dispatcher} (real provider dispatch in the
+ *   skill; stubs in tests).
+ * - Surface dispatcher errors to the caller WITHOUT retry — the Tier 2/3
+ *   fallback decision belongs to the skill, not this wrapper.
+ * - Validate the returned `StructuredFindings` shape with a hand-rolled
+ *   validator (matching the zero-dependency style of the other review-remote
+ *   helpers) and raise a typed {@link StructuredFindingsError} on malformed
+ *   output.
+ */
+import type { NarrowingResult } from './narrowing.js';
+/**
+ * The dispatch-payload key that selects structured-output mode on the
+ * `oat-reviewer` agent. Mirrors the flag p03 added (verified against
+ * `.agents/agents/oat-reviewer.md`); parallels the existing
+ * `oat_review_invocation` dispatch-payload naming.
+ */
+export declare const STRUCTURED_OUTPUT_MODE_FLAG: "oat_output_mode";
+/** The single accepted value of {@link STRUCTURED_OUTPUT_MODE_FLAG}. */
+export declare const STRUCTURED_OUTPUT_MODE_VALUE: "structured";
+export type FindingSeverity = 'critical' | 'important' | 'medium' | 'minor';
+/** A single structured finding (see design.md → Data Models). */
+export interface StructuredFinding {
+    /** Stable per-dispatch ID with a C/I/M/m prefix. */
+    id: string;
+    severity: FindingSeverity;
+    title: string;
+    /** Repo-relative path; both `file` and `line` are set or both `null`. */
+    file: string | null;
+    /** 1-based line in the post-image; paired with `file`. */
+    line: number | null;
+    body: string;
+    fix_guidance: string | null;
+}
+/** Typed return shape from `oat-reviewer` in structured-output mode. */
+export interface StructuredFindings {
+    summary: string;
+    findings: StructuredFinding[];
+    verification_commands: string[];
+}
+/**
+ * Raw response envelope from a provider dispatch. The reviewer's structured
+ * return lands on `findings`; the wrapper validates it before returning.
+ */
+export interface RawAgentResponse {
+    findings: unknown;
+}
+/**
+ * Narrow dispatcher interface. The skill provides the real provider dispatch
+ * (Claude Code Task / Cursor invocation / Codex spawn); tests pass stubs.
+ */
+export interface Dispatcher {
+    spawn(payload: Record<string, unknown>): Promise<RawAgentResponse>;
+}
+/** Context the wrapper needs to build the structured-output dispatch payload. */
+export interface ReviewDispatchContext {
+    /** Resolved OAT project directory path. */
+    projectPath: string;
+    /** Current scope token (`pNN`, `final`, …). */
+    scope: string;
+    /** Full 40-char PR HEAD SHA being reviewed. */
+    headSha: string;
+    /** The Review Scope metadata block the reviewer consumes as its prompt. */
+    reviewScopeMetadata: string;
+    /** Pointer to the posted-review-body schema the skill will build against. */
+    postedBodySchemaRef: string;
+    /** Resolved re-review narrowing decision from {@link pickNarrowingTarget}. */
+    narrowing: NarrowingResult;
+}
+/** Typed error raised when the reviewer returns a malformed structured shape. */
+export declare class StructuredFindingsError extends Error {
+    constructor(message: string);
+}
+/**
+ * Build the dispatch payload for a structured-output reviewer run. The
+ * structured-mode flag is always set; the narrowing range is included only when
+ * the guard actually produced one (`narrow-range`), otherwise it is `null`.
+ */
+export declare function buildDispatchPayload(context: ReviewDispatchContext): Record<string, unknown>;
+/**
+ * Validate an unknown value against the `StructuredFindings` contract. Throws a
+ * {@link StructuredFindingsError} on the first violation; returns the typed
+ * object otherwise.
+ */
+export declare function validateStructuredFindings(value: unknown): StructuredFindings;
+/**
+ * Run a Tier-1 structured-output review: build the payload, dispatch once, and
+ * validate the returned findings. Dispatcher errors propagate unchanged (no
+ * retry) so the skill can decide on a Tier 2/3 fallback. Malformed reviewer
+ * output raises {@link StructuredFindingsError}.
+ */
+export declare function dispatchStructuredReview(context: ReviewDispatchContext, dispatcher: Dispatcher): Promise<StructuredFindings>;
+//# sourceMappingURL=reviewer-dispatch.d.ts.map

package/dist/review-remote/reviewer-dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reviewer-dispatch.d.ts","sourceRoot":"","sources":["../../src/review-remote/reviewer-dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,EAAG,iBAA0B,CAAC;AAEtE,wEAAwE;AACxE,eAAO,MAAM,4BAA4B,EAAG,YAAqB,CAAC;AAElE,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;AAS5E,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,eAAe,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,wEAAwE;AACxE,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,qBAAqB,EAAE,MAAM,EAAE,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACpE;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,mBAAmB,EAAE,MAAM,CAAC;IAC5B,6EAA6E;IAC7E,mBAAmB,EAAE,MAAM,CAAC;IAC5B,8EAA8E;IAC9E,SAAS,EAAE,eAAe,CAAC;CAC5B;AAED,iFAAiF;AACjF,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,GAC7B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAezB;AAgED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CA2B7E;AAED;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,qBAAqB,EAC9B,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,kBAAkB,CAAC,CAK7B"}

package/dist/review-remote/reviewer-dispatch.js

@@ -0,0 +1,153 @@
+/**
+ * Tier-1 dispatch wrapper for the `oat-reviewer` subagent's structured-output
+ * mode (see design.md → Component Design → `oat-project-review-provide-remote`
+ * and `.agents/agents/oat-reviewer.md` → Structured-Output Mode).
+ *
+ * The project-rail provide-remote skill's Tier 1 dispatch hands the reviewer a
+ * payload carrying the project context, the posted-review-body schema
+ * reference, the resolved re-review narrowing range, and the
+ * `oat_output_mode: structured` flag. In that mode the reviewer returns a
+ * `StructuredFindings` object in-memory rather than writing a review artifact;
+ * this wrapper validates that object and hands it back to the skill, which is
+ * then responsible for building the posted body and posting to GitHub.
+ *
+ * Responsibilities are deliberately narrow:
+ *
+ * - Build the dispatch payload with the structured-output flag p03 wired.
+ * - Forward it to an injected {@link Dispatcher} (real provider dispatch in the
+ *   skill; stubs in tests).
+ * - Surface dispatcher errors to the caller WITHOUT retry — the Tier 2/3
+ *   fallback decision belongs to the skill, not this wrapper.
+ * - Validate the returned `StructuredFindings` shape with a hand-rolled
+ *   validator (matching the zero-dependency style of the other review-remote
+ *   helpers) and raise a typed {@link StructuredFindingsError} on malformed
+ *   output.
+ */
+/**
+ * The dispatch-payload key that selects structured-output mode on the
+ * `oat-reviewer` agent. Mirrors the flag p03 added (verified against
+ * `.agents/agents/oat-reviewer.md`); parallels the existing
+ * `oat_review_invocation` dispatch-payload naming.
+ */
+export const STRUCTURED_OUTPUT_MODE_FLAG = 'oat_output_mode';
+/** The single accepted value of {@link STRUCTURED_OUTPUT_MODE_FLAG}. */
+export const STRUCTURED_OUTPUT_MODE_VALUE = 'structured';
+const SEVERITIES = new Set([
+    'critical',
+    'important',
+    'medium',
+    'minor',
+]);
+/** Typed error raised when the reviewer returns a malformed structured shape. */
+export class StructuredFindingsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'StructuredFindingsError';
+    }
+}
+/**
+ * Build the dispatch payload for a structured-output reviewer run. The
+ * structured-mode flag is always set; the narrowing range is included only when
+ * the guard actually produced one (`narrow-range`), otherwise it is `null`.
+ */
+export function buildDispatchPayload(context) {
+    const narrowingRange = context.narrowing.kind === 'narrow-range'
+        ? `${context.narrowing.priorSha}..${context.narrowing.headSha}`
+        : null;
+    return {
+        [STRUCTURED_OUTPUT_MODE_FLAG]: STRUCTURED_OUTPUT_MODE_VALUE,
+        oat_project: context.projectPath,
+        oat_review_scope: context.scope,
+        oat_review_head_sha: context.headSha,
+        review_scope_metadata: context.reviewScopeMetadata,
+        posted_body_schema_ref: context.postedBodySchemaRef,
+        narrowing_range: narrowingRange,
+    };
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function validateFinding(value, index) {
+    const at = `findings[${index}]`;
+    if (!isObject(value)) {
+        throw new StructuredFindingsError(`${at} must be an object.`);
+    }
+    if (typeof value['id'] !== 'string' || value['id'] === '') {
+        throw new StructuredFindingsError(`${at}.id must be a non-empty string.`);
+    }
+    if (typeof value['severity'] !== 'string' ||
+        !SEVERITIES.has(value['severity'])) {
+        throw new StructuredFindingsError(`${at}.severity must be one of critical|important|medium|minor.`);
+    }
+    if (typeof value['title'] !== 'string') {
+        throw new StructuredFindingsError(`${at}.title must be a string.`);
+    }
+    if (typeof value['body'] !== 'string') {
+        throw new StructuredFindingsError(`${at}.body must be a string.`);
+    }
+    const file = value['file'];
+    const line = value['line'];
+    const fileSet = file !== null;
+    const lineSet = line !== null;
+    if (fileSet !== lineSet) {
+        throw new StructuredFindingsError(`${at} must set both file and line, or set both to null.`);
+    }
+    if (fileSet && typeof file !== 'string') {
+        throw new StructuredFindingsError(`${at}.file must be a string or null.`);
+    }
+    if (lineSet && typeof line !== 'number') {
+        throw new StructuredFindingsError(`${at}.line must be a number or null.`);
+    }
+    const fixGuidance = value['fix_guidance'];
+    if (fixGuidance !== null && typeof fixGuidance !== 'string') {
+        throw new StructuredFindingsError(`${at}.fix_guidance must be a string or null.`);
+    }
+    return {
+        id: value['id'],
+        severity: value['severity'],
+        title: value['title'],
+        file: fileSet ? file : null,
+        line: lineSet ? line : null,
+        body: value['body'],
+        fix_guidance: fixGuidance === null ? null : fixGuidance,
+    };
+}
+/**
+ * Validate an unknown value against the `StructuredFindings` contract. Throws a
+ * {@link StructuredFindingsError} on the first violation; returns the typed
+ * object otherwise.
+ */
+export function validateStructuredFindings(value) {
+    if (!isObject(value)) {
+        throw new StructuredFindingsError('StructuredFindings must be an object.');
+    }
+    if (typeof value['summary'] !== 'string') {
+        throw new StructuredFindingsError('summary must be a string.');
+    }
+    if (!Array.isArray(value['findings'])) {
+        throw new StructuredFindingsError('findings must be an array.');
+    }
+    const commands = value['verification_commands'];
+    if (!Array.isArray(commands) ||
+        !commands.every((c) => typeof c === 'string')) {
+        throw new StructuredFindingsError('verification_commands must be an array of strings.');
+    }
+    const findings = value['findings'].map((f, i) => validateFinding(f, i));
+    return {
+        summary: value['summary'],
+        findings,
+        verification_commands: commands,
+    };
+}
+/**
+ * Run a Tier-1 structured-output review: build the payload, dispatch once, and
+ * validate the returned findings. Dispatcher errors propagate unchanged (no
+ * retry) so the skill can decide on a Tier 2/3 fallback. Malformed reviewer
+ * output raises {@link StructuredFindingsError}.
+ */
+export async function dispatchStructuredReview(context, dispatcher) {
+    const payload = buildDispatchPayload(context);
+    // No try/catch — a dispatcher error surfaces to the skill without retry.
+    const response = await dispatcher.spawn(payload);
+    return validateStructuredFindings(response.findings);
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Ephemeral worktree lifecycle helper (see design.md → Data Flow step 2).
+ *
+ * The provide-remote skills review a PR without mutating the caller's working
+ * tree. They acquire an ephemeral, repo-scoped worktree, run `gh pr checkout`
+ * INSIDE it (that step lives in the skill, not here), review, then tear the
+ * worktree down. This helper owns only the create/run/release lifecycle:
+ *
+ *   - `acquireWorktree({ repoRoot })` — `mktemp -d` an ephemeral path OUTSIDE
+ *     `repoRoot`, then `git -C "$repoRoot" worktree add --detach <path> HEAD`.
+ *     The `-C "$repoRoot"` flag is load-bearing: it lets the command run even
+ *     when the caller's CWD is not inside the repository (a thin remote-review
+ *     machine invoking the skill from a home directory). `HEAD` is a
+ *     placeholder ref the skill overwrites with `gh pr checkout <N>`.
+ *   - `runInWorktree(handle, cb)` — invoke `cb(worktreePath)`. The helper does
+ *     NOT chdir the host process; it passes the path so callers run repo-scoped
+ *     git / `cd "$path" && gh pr checkout` in a subshell. This keeps the
+ *     caller's CWD unchanged (verified by tests).
+ *   - `releaseWorktree(handle)` — `git -C "$repoRoot" worktree remove --force`
+ *     then remove the temp directory. Idempotent and safe even if the worktree
+ *     never populated, so callers run it in a `finally`.
+ *
+ * Design Open Question resolution: `oat-worktree-bootstrap-auto` reuse was
+ * considered but the helper is hand-rolled per the design fallback. The plan's
+ * mechanics (repo-scoped git invocation, ephemeral path outside repo root,
+ * force-removal teardown) are implemented directly here; the helper stays
+ * agnostic to PR checkout so it has no dependency on the bootstrap contract.
+ */
+export interface AcquireWorktreeOptions {
+    /** Absolute path to the repository root (`git rev-parse --show-toplevel`). */
+    repoRoot: string;
+}
+/** Opaque handle returned by {@link acquireWorktree}. */
+export interface WorktreeHandle {
+    /** The repository root the worktree was created against. */
+    repoRoot: string;
+    /** The ephemeral worktree path (outside `repoRoot`). */
+    worktreePath: string;
+    /** Internal: whether the worktree is still live (false after release). */
+    released: boolean;
+}
+/**
+ * Create an ephemeral, detached worktree outside the repo root and register it
+ * with git. The path is created via `mktemp`-style `mkdtempSync` under the
+ * system temp dir, so it is guaranteed to be outside `repoRoot`.
+ */
+export declare function acquireWorktree(options: AcquireWorktreeOptions): Promise<WorktreeHandle>;
+/**
+ * Run a callback "inside" the worktree. The callback receives the worktree
+ * path; the helper does not change the host process's working directory, so
+ * callers must scope filesystem / git operations to that path themselves
+ * (e.g., `git -C <path> …` or `cd <path> && gh pr checkout` in a subshell).
+ */
+export declare function runInWorktree<T>(handle: WorktreeHandle, callback: (worktreePath: string) => Promise<T>): Promise<T>;
+/**
+ * Remove the git worktree (force) and clean up the temp directory. Idempotent:
+ * a second call is a no-op, and a failed `git worktree remove` (e.g., the
+ * worktree never populated, or was already pruned) does not prevent the temp
+ * directory cleanup. Safe to call in a `finally`.
+ */
+export declare function releaseWorktree(handle: WorktreeHandle): Promise<void>;
+//# sourceMappingURL=worktree.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../../src/review-remote/worktree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAUH,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,cAAc,CAAC,CAmCzB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7C,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CA2B3E"}

package/dist/review-remote/worktree.js

@@ -0,0 +1,117 @@
+/**
+ * Ephemeral worktree lifecycle helper (see design.md → Data Flow step 2).
+ *
+ * The provide-remote skills review a PR without mutating the caller's working
+ * tree. They acquire an ephemeral, repo-scoped worktree, run `gh pr checkout`
+ * INSIDE it (that step lives in the skill, not here), review, then tear the
+ * worktree down. This helper owns only the create/run/release lifecycle:
+ *
+ *   - `acquireWorktree({ repoRoot })` — `mktemp -d` an ephemeral path OUTSIDE
+ *     `repoRoot`, then `git -C "$repoRoot" worktree add --detach <path> HEAD`.
+ *     The `-C "$repoRoot"` flag is load-bearing: it lets the command run even
+ *     when the caller's CWD is not inside the repository (a thin remote-review
+ *     machine invoking the skill from a home directory). `HEAD` is a
+ *     placeholder ref the skill overwrites with `gh pr checkout <N>`.
+ *   - `runInWorktree(handle, cb)` — invoke `cb(worktreePath)`. The helper does
+ *     NOT chdir the host process; it passes the path so callers run repo-scoped
+ *     git / `cd "$path" && gh pr checkout` in a subshell. This keeps the
+ *     caller's CWD unchanged (verified by tests).
+ *   - `releaseWorktree(handle)` — `git -C "$repoRoot" worktree remove --force`
+ *     then remove the temp directory. Idempotent and safe even if the worktree
+ *     never populated, so callers run it in a `finally`.
+ *
+ * Design Open Question resolution: `oat-worktree-bootstrap-auto` reuse was
+ * considered but the helper is hand-rolled per the design fallback. The plan's
+ * mechanics (repo-scoped git invocation, ephemeral path outside repo root,
+ * force-removal teardown) are implemented directly here; the helper stays
+ * agnostic to PR checkout so it has no dependency on the bootstrap contract.
+ */
+import { execFile as execFileCallback } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+const execFile = promisify(execFileCallback);
+/**
+ * Create an ephemeral, detached worktree outside the repo root and register it
+ * with git. The path is created via `mktemp`-style `mkdtempSync` under the
+ * system temp dir, so it is guaranteed to be outside `repoRoot`.
+ */
+export async function acquireWorktree(options) {
+    const { repoRoot } = options;
+    // Ephemeral path under the OS temp dir — outside repoRoot by construction.
+    const worktreePath = mkdtempSync(join(tmpdir(), 'oat-review-wt-'));
+    // `git worktree add` requires the target path to NOT already exist, so remove
+    // the placeholder mkdtemp directory and let git create it fresh.
+    rmSync(worktreePath, { recursive: true, force: true });
+    try {
+        await execFile('git', [
+            '-C',
+            repoRoot,
+            'worktree',
+            'add',
+            '--detach',
+            worktreePath,
+            'HEAD',
+        ]);
+    }
+    catch (error) {
+        // `git worktree add` can fail after partially creating the target dir
+        // and/or registering `.git/worktrees/<name>` metadata. Because we throw
+        // without returning a handle, the caller's `finally { releaseWorktree }`
+        // never runs — so clean up the partial worktree here before rethrowing.
+        // Best-effort: prune dangling worktree metadata, then remove the temp dir.
+        try {
+            await execFile('git', ['-C', repoRoot, 'worktree', 'prune']);
+        }
+        catch {
+            // Best-effort; ignore (e.g. repoRoot is not a git repo).
+        }
+        rmSync(worktreePath, { recursive: true, force: true });
+        throw error;
+    }
+    return { repoRoot, worktreePath, released: false };
+}
+/**
+ * Run a callback "inside" the worktree. The callback receives the worktree
+ * path; the helper does not change the host process's working directory, so
+ * callers must scope filesystem / git operations to that path themselves
+ * (e.g., `git -C <path> …` or `cd <path> && gh pr checkout` in a subshell).
+ */
+export async function runInWorktree(handle, callback) {
+    return callback(handle.worktreePath);
+}
+/**
+ * Remove the git worktree (force) and clean up the temp directory. Idempotent:
+ * a second call is a no-op, and a failed `git worktree remove` (e.g., the
+ * worktree never populated, or was already pruned) does not prevent the temp
+ * directory cleanup. Safe to call in a `finally`.
+ */
+export async function releaseWorktree(handle) {
+    if (handle.released) {
+        return;
+    }
+    handle.released = true;
+    try {
+        await execFile('git', [
+            '-C',
+            handle.repoRoot,
+            'worktree',
+            'remove',
+            '--force',
+            handle.worktreePath,
+        ]);
+    }
+    catch {
+        // `worktree remove` can fail if the worktree was never populated or was
+        // already removed. That is non-fatal — proceed to temp cleanup so we never
+        // leak the directory, then prune stale worktree metadata best-effort.
+        try {
+            await execFile('git', ['-C', handle.repoRoot, 'worktree', 'prune']);
+        }
+        catch {
+            // Best-effort; ignore.
+        }
+    }
+    rmSync(handle.worktreePath, { recursive: true, force: true });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -34,7 +34,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.1.13"
+    "@open-agent-toolkit/control-plane": "0.1.14"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",