pi-workflow-engine 0.4.0 → 0.6.1

package/.pi/extensions/pi-workflow-engine/src/inline-workflow.ts

@@ -0,0 +1,396 @@
+import { Type } from "typebox";
+import type { WorkflowApi, WorkflowMeta, WorkflowModule } from "./types.ts";
+import { parseWorkflowMeta } from "./workflow-module.ts";
+
+/**
+ * v1 inline workflow source contract:
+ * - The script starts with `export const meta = { ... };` where the object is a pure literal.
+ * - The script contains exactly one `export default async ...` workflow function.
+ * - Inline scripts must not use `import` or any exports other than `meta` and the default function.
+ * - `Type` is injected lexically by the host; scripts must use that `Type`, not import typebox.
+ */
+
+export class InlineWorkflowCompileError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InlineWorkflowCompileError";
+  }
+}
+
+export interface InlineMetaLiteral {
+  readonly literal: string;
+  readonly value: unknown;
+  readonly endOffset: number;
+}
+
+type InlineWorkflowExecutor = (api: WorkflowApi, typebox: typeof Type) => Promise<unknown>;
+type AsyncFunctionConstructor = new (...args: string[]) => InlineWorkflowExecutor;
+
+const AsyncFunction = Object.getPrototypeOf(async function inlineWorkflowCompilerSentinel() {}).constructor as AsyncFunctionConstructor;
+
+export function compileInlineWorkflow(source: string): WorkflowModule {
+  rejectForbiddenModuleSyntax(source);
+  const metaLiteral = extractMetaLiteral(source);
+  const parsedMeta = parseWorkflowMeta(metaLiteral.value);
+  if ("reason" in parsedMeta) throw new InlineWorkflowCompileError(parsedMeta.reason);
+
+  const defaultExpression = extractDefaultWorkflowExpression(source, metaLiteral.endOffset);
+  const executor = compileExecutor(defaultExpression);
+  return { meta: parsedMeta.meta, default: (api) => executor(api, Type) };
+}
+
+export function extractMetaLiteral(source: string): InlineMetaLiteral {
+  const start = skipWhitespace(source, 0);
+  const prefix = /export\s+const\s+meta\s*=/y;
+  prefix.lastIndex = start;
+  const match = prefix.exec(source);
+  if (!match || match.index !== start) {
+    throw new InlineWorkflowCompileError("inline workflow must start with `export const meta = { ... }`;");
+  }
+
+  const objectStart = skipWhitespace(source, prefix.lastIndex);
+  if (source[objectStart] !== "{") {
+    throw new InlineWorkflowCompileError("inline workflow meta must be an object literal");
+  }
+
+  const parser = new LiteralParser(source, objectStart);
+  const value = parser.parseValue();
+  const literalEnd = parser.offset;
+  let endOffset = skipWhitespace(source, literalEnd);
+  if (source[endOffset] === ";") endOffset++;
+
+  return { literal: source.slice(objectStart, literalEnd), value, endOffset };
+}
+
+function rejectForbiddenModuleSyntax(source: string): void {
+  if (/^\s*import\s/m.test(source)) {
+    throw new InlineWorkflowCompileError("inline workflows must not contain import statements; use injected Type instead");
+  }
+  if (/\bimport\s*\(/.test(source)) {
+    throw new InlineWorkflowCompileError("inline workflows must not use dynamic import()");
+  }
+}
+
+function extractDefaultWorkflowExpression(source: string, startOffset: number): string {
+  const moduleSource = source.slice(startOffset).trim();
+  if (!moduleSource) throw new InlineWorkflowCompileError("inline workflow must export a default async function");
+  if (!moduleSource.startsWith("export default")) {
+    throw new InlineWorkflowCompileError("inline workflow default export must directly follow the meta declaration");
+  }
+
+  const defaultPrefix = /^export\s+default\s+/;
+  const match = defaultPrefix.exec(moduleSource);
+  if (!match) throw new InlineWorkflowCompileError("inline workflow must export a default async function");
+
+  const expressionSource = moduleSource.slice(match[0].length).trimStart();
+  const bodyOpen = findDefaultBodyOpen(expressionSource);
+  const bodyClose = findMatchingDelimiter(expressionSource, bodyOpen, "{", "}");
+  const expression = expressionSource.slice(0, bodyClose + 1);
+  const remainder = expressionSource.slice(bodyClose + 1).trim();
+  if (remainder !== "" && remainder !== ";") {
+    throw new InlineWorkflowCompileError("inline workflow must not contain code after the default export");
+  }
+  return expression;
+}
+
+function findDefaultBodyOpen(expressionSource: string): number {
+  const functionMatch = /^async\s+function(?:\s+[A-Za-z_$][\w$]*)?\s*/.exec(expressionSource);
+  if (functionMatch) {
+    const paramsOpen = skipWhitespace(expressionSource, functionMatch[0].length);
+    if (expressionSource[paramsOpen] !== "(") {
+      throw new InlineWorkflowCompileError("default async function must declare parameters with parentheses");
+    }
+    const paramsClose = findMatchingDelimiter(expressionSource, paramsOpen, "(", ")");
+    const bodyOpen = skipWhitespace(expressionSource, paramsClose + 1);
+    if (expressionSource[bodyOpen] !== "{") {
+      throw new InlineWorkflowCompileError("default async function must use a block body");
+    }
+    return bodyOpen;
+  }
+
+  const arrowMatch = /^async\s*/.exec(expressionSource);
+  if (arrowMatch) {
+    const paramsOpen = skipWhitespace(expressionSource, arrowMatch[0].length);
+    if (expressionSource[paramsOpen] !== "(") {
+      throw new InlineWorkflowCompileError("default async arrow workflow must declare parameters with parentheses");
+    }
+    const paramsClose = findMatchingDelimiter(expressionSource, paramsOpen, "(", ")");
+    let cursor = skipWhitespace(expressionSource, paramsClose + 1);
+    if (!expressionSource.startsWith("=>", cursor)) {
+      throw new InlineWorkflowCompileError("default async arrow workflow must use =>");
+    }
+    cursor = skipWhitespace(expressionSource, cursor + 2);
+    if (expressionSource[cursor] !== "{") {
+      throw new InlineWorkflowCompileError("default async arrow workflow must use a block body");
+    }
+    return cursor;
+  }
+
+  throw new InlineWorkflowCompileError("inline workflow default export must be an async function or async arrow function");
+}
+
+function compileExecutor(defaultExpression: string): InlineWorkflowExecutor {
+  try {
+    return new AsyncFunction("api", "Type", `"use strict";\nconst workflow = ${defaultExpression};\nreturn await workflow(api);`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new InlineWorkflowCompileError(`inline workflow default export did not compile: ${message}`);
+  }
+}
+
+class LiteralParser {
+  private index: number;
+
+  constructor(private readonly source: string, offset: number) {
+    this.index = offset;
+  }
+
+  get offset(): number {
+    return this.index;
+  }
+
+  parseValue(): unknown {
+    this.skipWhitespace();
+    const char = this.source[this.index];
+    if (char === "{") return this.parseObject();
+    if (char === "[") return this.parseArray();
+    if (char === '"' || char === "'") return this.parseString(char);
+    if (char === "-" || isDigit(char)) return this.parseNumber();
+    if (this.source.startsWith("true", this.index)) return this.consumeKeyword("true", true);
+    if (this.source.startsWith("false", this.index)) return this.consumeKeyword("false", false);
+    if (this.source.startsWith("null", this.index)) return this.consumeKeyword("null", null);
+    if (char === "`") this.fail("template literals are not allowed in inline workflow meta");
+    this.fail(`unexpected token in inline workflow meta: ${char ?? "end of input"}`);
+  }
+
+  private parseObject(): Record<string, unknown> {
+    const object: Record<string, unknown> = {};
+    this.expect("{");
+    this.skipWhitespace();
+    if (this.peek() === "}") {
+      this.index++;
+      return object;
+    }
+
+    while (true) {
+      this.skipWhitespace();
+      if (this.source.startsWith("...", this.index)) this.fail("spread properties are not allowed in inline workflow meta");
+      if (this.peek() === "[") this.fail("computed properties are not allowed in inline workflow meta");
+      const key = this.parsePropertyKey();
+      this.skipWhitespace();
+      if (this.peek() !== ":") this.fail("inline workflow meta properties must use explicit key: value syntax");
+      this.index++;
+      object[key] = this.parseValue();
+      this.skipWhitespace();
+      const next = this.peek();
+      if (next === ",") {
+        this.index++;
+        this.skipWhitespace();
+        if (this.peek() === "}") {
+          this.index++;
+          return object;
+        }
+        continue;
+      }
+      if (next === "}") {
+        this.index++;
+        return object;
+      }
+      this.fail("expected `,` or `}` in inline workflow meta object");
+    }
+  }
+
+  private parseArray(): unknown[] {
+    const array: unknown[] = [];
+    this.expect("[");
+    this.skipWhitespace();
+    if (this.peek() === "]") {
+      this.index++;
+      return array;
+    }
+
+    while (true) {
+      array.push(this.parseValue());
+      this.skipWhitespace();
+      const next = this.peek();
+      if (next === ",") {
+        this.index++;
+        this.skipWhitespace();
+        if (this.peek() === "]") {
+          this.index++;
+          return array;
+        }
+        continue;
+      }
+      if (next === "]") {
+        this.index++;
+        return array;
+      }
+      this.fail("expected `,` or `]` in inline workflow meta array");
+    }
+  }
+
+  private parsePropertyKey(): string {
+    const char = this.peek();
+    if (char === '"' || char === "'") return this.parseString(char);
+    if (!isIdentifierStart(char)) this.fail("inline workflow meta property keys must be strings or identifiers");
+    const start = this.index;
+    this.index++;
+    while (isIdentifierPart(this.peek())) this.index++;
+    return this.source.slice(start, this.index);
+  }
+
+  private parseString(quote: string): string {
+    this.expect(quote);
+    let value = "";
+    while (this.index < this.source.length) {
+      const char = this.source[this.index];
+      if (char === quote) {
+        this.index++;
+        return value;
+      }
+      if (char === "\\") {
+        value += this.parseEscapeSequence();
+        continue;
+      }
+      if (char === "\n" || char === "\r") this.fail("inline workflow meta strings must not contain raw newlines");
+      value += char;
+      this.index++;
+    }
+    this.fail("unterminated string in inline workflow meta");
+  }
+
+  private parseEscapeSequence(): string {
+    this.expect("\\");
+    const escaped = this.source[this.index];
+    if (escaped === undefined) this.fail("unterminated escape sequence in inline workflow meta");
+    this.index++;
+    switch (escaped) {
+      case '"':
+      case "'":
+      case "\\":
+      case "/":
+        return escaped;
+      case "b":
+        return "\b";
+      case "f":
+        return "\f";
+      case "n":
+        return "\n";
+      case "r":
+        return "\r";
+      case "t":
+        return "\t";
+      case "u": {
+        const hex = this.source.slice(this.index, this.index + 4);
+        if (!/^[0-9A-Fa-f]{4}$/.test(hex)) this.fail("invalid unicode escape in inline workflow meta");
+        this.index += 4;
+        return String.fromCharCode(Number.parseInt(hex, 16));
+      }
+      default:
+        this.fail(`unsupported escape sequence \\${escaped} in inline workflow meta`);
+    }
+  }
+
+  private parseNumber(): number {
+    const match = /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/y;
+    match.lastIndex = this.index;
+    const parsed = match.exec(this.source);
+    if (!parsed) this.fail("invalid number in inline workflow meta");
+    this.index = match.lastIndex;
+    return Number(parsed[0]);
+  }
+
+  private consumeKeyword<T>(keyword: string, value: T): T {
+    this.index += keyword.length;
+    if (isIdentifierPart(this.peek())) this.fail(`unexpected identifier after ${keyword} in inline workflow meta`);
+    return value;
+  }
+
+  private skipWhitespace(): void {
+    this.index = skipWhitespace(this.source, this.index);
+  }
+
+  private peek(): string | undefined {
+    return this.source[this.index];
+  }
+
+  private expect(char: string): void {
+    if (this.source[this.index] !== char) this.fail(`expected ${char} in inline workflow meta`);
+    this.index++;
+  }
+
+  private fail(message: string): never {
+    throw new InlineWorkflowCompileError(`${message} at offset ${this.index}`);
+  }
+}
+
+function findMatchingDelimiter(source: string, openIndex: number, open: string, close: string): number {
+  let depth = 1;
+  let index = openIndex + 1;
+  while (index < source.length) {
+    const char = source[index];
+    if (char === '"' || char === "'" || char === "`") {
+      index = skipQuotedSource(source, index, char);
+      continue;
+    }
+    if (char === "/" && source[index + 1] === "/") {
+      index = skipLineComment(source, index);
+      continue;
+    }
+    if (char === "/" && source[index + 1] === "*") {
+      index = skipBlockComment(source, index);
+      continue;
+    }
+    if (char === open) depth++;
+    if (char === close) {
+      depth--;
+      if (depth === 0) return index;
+    }
+    index++;
+  }
+  throw new InlineWorkflowCompileError(`unterminated ${open}${close} block in inline workflow default export`);
+}
+
+function skipQuotedSource(source: string, start: number, quote: string): number {
+  let index = start + 1;
+  while (index < source.length) {
+    const char = source[index];
+    if (char === "\\") {
+      index += 2;
+      continue;
+    }
+    if (char === quote) return index + 1;
+    index++;
+  }
+  throw new InlineWorkflowCompileError("unterminated string in inline workflow default export");
+}
+
+function skipLineComment(source: string, start: number): number {
+  const newline = source.indexOf("\n", start + 2);
+  return newline === -1 ? source.length : newline + 1;
+}
+
+function skipBlockComment(source: string, start: number): number {
+  const end = source.indexOf("*/", start + 2);
+  if (end === -1) throw new InlineWorkflowCompileError("unterminated block comment in inline workflow default export");
+  return end + 2;
+}
+
+function skipWhitespace(source: string, start: number): number {
+  let index = start;
+  while (index < source.length && /\s/.test(source[index] ?? "")) index++;
+  return index;
+}
+
+function isDigit(value: string | undefined): boolean {
+  return value !== undefined && value >= "0" && value <= "9";
+}
+
+function isIdentifierStart(value: string | undefined): boolean {
+  return value !== undefined && /[A-Za-z_$]/.test(value);
+}
+
+function isIdentifierPart(value: string | undefined): boolean {
+  return value !== undefined && /[A-Za-z0-9_$]/.test(value);
+}

package/.pi/extensions/pi-workflow-engine/src/review/github-pr-comments.ts

@@ -0,0 +1,185 @@
+import { isCommentableIssue, type ReviewContext, type ReviewIssue } from "./review-issues.ts";
+
+export interface ExecResultLike {
+  readonly stdout: string;
+  readonly stderr?: string;
+  readonly code: number;
+  readonly killed?: boolean;
+}
+
+export type ExecLike = (
+  command: string,
+  args: string[],
+  options?: { readonly cwd?: string; readonly timeout?: number; readonly signal?: AbortSignal },
+) => Promise<ExecResultLike>;
+
+export interface GitHubPrContext {
+  readonly owner: string;
+  readonly repo: string;
+  readonly number: number;
+  readonly headSha: string;
+  readonly url?: string;
+}
+
+export type ResolveGitHubPrContextResult = { readonly ok: true; readonly context: GitHubPrContext } | { readonly ok: false; readonly reason: string };
+
+export type InlineCommentStatus =
+  | { readonly issueId: string; readonly status: "posted"; readonly url?: string }
+  | { readonly issueId: string; readonly status: "skipped"; readonly reason: string }
+  | { readonly issueId: string; readonly status: "failed"; readonly reason: string };
+
+const PR_VIEW_JSON_FIELDS = "number,headRefOid,url,headRepositoryOwner,headRepository";
+
+export async function resolveGitHubPrContext(
+  exec: ExecLike,
+  cwd: string,
+  reviewContext: ReviewContext | undefined,
+): Promise<ResolveGitHubPrContextResult> {
+  const parsedNumber = parsePrNumber(reviewContext?.diffCommand);
+  const prArgs = parsedNumber
+    ? ["pr", "view", String(parsedNumber), "--json", PR_VIEW_JSON_FIELDS]
+    : ["pr", "view", "--json", PR_VIEW_JSON_FIELDS];
+  const prView = await runJson(exec, cwd, prArgs);
+  if (!prView.ok) return { ok: false, reason: prView.reason };
+
+  const number = numberField(prView.value, "number") ?? parsedNumber;
+  const headSha = stringField(prView.value, "headRefOid");
+  if (number === undefined) return { ok: false, reason: "No GitHub PR number found." };
+  if (!headSha) return { ok: false, reason: "GitHub PR head SHA is missing." };
+
+  const ownerFromPr = nestedStringField(prView.value, "headRepositoryOwner", "login");
+  const repoFromPr = nestedStringField(prView.value, "headRepository", "name");
+  let owner = ownerFromPr;
+  let repo = repoFromPr;
+  if (!owner || !repo) {
+    const repoView = await runJson(exec, cwd, ["repo", "view", "--json", "nameWithOwner"]);
+    if (!repoView.ok) return { ok: false, reason: repoView.reason };
+    const nameWithOwner = stringField(repoView.value, "nameWithOwner");
+    const parsed = parseNameWithOwner(nameWithOwner);
+    owner = owner ?? parsed?.owner;
+    repo = repo ?? parsed?.repo;
+  }
+  if (!owner || !repo) return { ok: false, reason: "GitHub repository owner/name is missing." };
+
+  const url = stringField(prView.value, "url");
+  return { ok: true, context: { owner, repo, number, headSha, url } };
+}
+
+export function buildInlineCommentBody(issue: ReviewIssue): string {
+  const finding = issue.finding;
+  const evidence = finding.evidence.length > 0 ? finding.evidence.map((entry) => `- ${entry}`).join("\n") : "- (none cited)";
+  return `**${issue.id}: ${finding.summary}**
+
+Severity: ${finding.severity} · Confidence: ${finding.confidence} · Category: ${finding.category}
+
+Impact: ${finding.impact}
+
+Evidence:
+${evidence}
+
+Recommendation: ${finding.recommendation}`;
+}
+
+export async function postInlineComment(
+  exec: ExecLike,
+  cwd: string,
+  prContext: GitHubPrContext,
+  issue: ReviewIssue,
+): Promise<InlineCommentStatus> {
+  if (!isCommentableIssue(issue)) return { issueId: issue.id, status: "skipped", reason: "Finding has no commentable file/line." };
+
+  const result = await runCommand(exec, cwd, [
+    "api",
+    `repos/${prContext.owner}/${prContext.repo}/pulls/${prContext.number}/comments`,
+    "-f",
+    `body=${buildInlineCommentBody(issue)}`,
+    "-f",
+    `commit_id=${prContext.headSha}`,
+    "-f",
+    `path=${issue.file}`,
+    "-F",
+    `line=${issue.line}`,
+    "-f",
+    "side=RIGHT",
+  ]);
+  if (!result.ok) return { issueId: issue.id, status: "failed", reason: result.reason };
+  return { issueId: issue.id, status: "posted", url: parsePostedCommentUrl(result.stdout) };
+}
+
+export async function postInlineComments(
+  exec: ExecLike,
+  cwd: string,
+  prContext: GitHubPrContext,
+  issues: readonly ReviewIssue[],
+): Promise<InlineCommentStatus[]> {
+  const statuses: InlineCommentStatus[] = [];
+  for (const issue of issues) {
+    statuses.push(await postInlineComment(exec, cwd, prContext, issue));
+  }
+  return statuses;
+}
+
+function parsePrNumber(diffCommand: string | undefined): number | undefined {
+  if (!diffCommand) return undefined;
+  const match = /(?:^|\s)gh\s+pr\s+diff\s+(\d+)(?:\s|$)/.exec(diffCommand);
+  if (!match) return undefined;
+  const parsed = Number(match[1]);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+async function runJson(exec: ExecLike, cwd: string, args: string[]): Promise<{ readonly ok: true; readonly value: unknown } | { readonly ok: false; readonly reason: string }> {
+  const result = await runCommand(exec, cwd, args);
+  if (!result.ok) return result;
+  try {
+    return { ok: true, value: JSON.parse(result.stdout) };
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? `Invalid gh JSON: ${error.message}` : "Invalid gh JSON." };
+  }
+}
+
+async function runCommand(exec: ExecLike, cwd: string, args: string[]): Promise<{ readonly ok: true; readonly stdout: string } | { readonly ok: false; readonly reason: string }> {
+  try {
+    const result = await exec("gh", args, { cwd, timeout: 30_000 });
+    if (result.code !== 0) return { ok: false, reason: result.stderr?.trim() || `gh exited with code ${result.code}` };
+    return { ok: true, stdout: result.stdout };
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : "gh command failed." };
+  }
+}
+
+function numberField(value: unknown, key: string): number | undefined {
+  if (!isRecord(value)) return undefined;
+  const field = value[key];
+  return typeof field === "number" && Number.isFinite(field) ? field : undefined;
+}
+
+function stringField(value: unknown, key: string): string | undefined {
+  if (!isRecord(value)) return undefined;
+  const field = value[key];
+  return typeof field === "string" && field.trim().length > 0 ? field : undefined;
+}
+
+function nestedStringField(value: unknown, objectKey: string, key: string): string | undefined {
+  if (!isRecord(value)) return undefined;
+  const nested = value[objectKey];
+  return stringField(nested, key);
+}
+
+function parseNameWithOwner(value: string | undefined): { readonly owner: string; readonly repo: string } | undefined {
+  if (!value) return undefined;
+  const [owner, repo, extra] = value.split("/");
+  if (!owner || !repo || extra !== undefined) return undefined;
+  return { owner, repo };
+}
+
+function parsePostedCommentUrl(stdout: string): string | undefined {
+  try {
+    return stringField(JSON.parse(stdout), "html_url");
+  } catch {
+    return undefined;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/.pi/extensions/pi-workflow-engine/src/review/review-actions.ts

@@ -0,0 +1,114 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { postInlineComments, resolveGitHubPrContext, type ExecLike, type InlineCommentStatus } from "./github-pr-comments.ts";
+import { buildCommentHandoffPrompt, buildFixHandoffPrompt } from "./review-handoff.ts";
+import { isCommentableIssue, type ReviewContext, type ReviewIssue, type ReviewIssueSelection } from "./review-issues.ts";
+
+export type ReviewActionPi = Pick<ExtensionAPI, "sendUserMessage" | "exec">;
+export interface ReviewActionContext {
+  readonly cwd: string;
+  readonly ui: {
+    confirm(title: string, message: string): Promise<boolean>;
+    notify(message: string, type?: "info" | "warning" | "error"): void;
+  };
+}
+
+export async function handleReviewViewerAction(
+  pi: ReviewActionPi,
+  ctx: ReviewActionContext,
+  action: ReviewIssueSelection | undefined,
+  issues: readonly ReviewIssue[],
+  context: ReviewContext | undefined,
+): Promise<void> {
+  if (!action || action.action === "close") return;
+  const selected = selectedIssues(issues, action.issueIds);
+  if (action.action === "fix") {
+    handleFixAction(pi, ctx, selected, context);
+    return;
+  }
+  await handleCommentAction(pi, ctx, selected, context);
+}
+
+function handleFixAction(pi: ReviewActionPi, ctx: ReviewActionContext, selected: readonly ReviewIssue[], context: ReviewContext | undefined): void {
+  if (selected.length === 0) {
+    ctx.ui.notify("No selected findings to fix", "warning");
+    return;
+  }
+  pi.sendUserMessage(buildFixHandoffPrompt(selected, context), { deliverAs: "followUp" });
+  ctx.ui.notify(`Queued fix request for ${selected.length} selected finding(s)`, "info");
+}
+
+async function handleCommentAction(
+  pi: ReviewActionPi,
+  ctx: ReviewActionContext,
+  selected: readonly ReviewIssue[],
+  context: ReviewContext | undefined,
+): Promise<void> {
+  const commentable = selected.filter(isCommentableIssue);
+  if (commentable.length === 0) {
+    ctx.ui.notify("No selected findings have file and line information for inline PR comments", "warning");
+    return;
+  }
+
+  const confirmed = await ctx.ui.confirm(
+    "Post inline PR comments?",
+    `Post ${commentable.length} selected finding(s) to the upstream PR using GitHub CLI if available?`,
+  );
+  if (!confirmed) {
+    queueCommentFallback(pi, ctx, commentable, context, "User chose parent-agent fallback instead of direct gh posting.");
+    return;
+  }
+
+  const exec = toExecLike(pi);
+  const resolved = await resolveGitHubPrContext(exec, ctx.cwd, context);
+  if (!resolved.ok) {
+    queueCommentFallback(pi, ctx, commentable, context, resolved.reason);
+    return;
+  }
+
+  const statuses = await postInlineComments(exec, ctx.cwd, resolved.context, commentable);
+  const summary = summarizeStatuses(statuses);
+  ctx.ui.notify(`PR comments: ${summary.posted} posted, ${summary.skipped} skipped, ${summary.failed} failed`, summary.failed > 0 ? "warning" : "info");
+  if (summary.failed > 0) {
+    const failedIds = new Set(statuses.filter((status) => status.status === "failed").map((status) => status.issueId));
+    queueCommentFallback(
+      pi,
+      ctx,
+      commentable.filter((issue) => failedIds.has(issue.id)),
+      context,
+      "Direct gh posting failed for one or more selected findings.",
+    );
+  }
+}
+
+function queueCommentFallback(
+  pi: ReviewActionPi,
+  ctx: ReviewActionContext,
+  issues: readonly ReviewIssue[],
+  context: ReviewContext | undefined,
+  reason: string,
+): void {
+  if (issues.length === 0) return;
+  pi.sendUserMessage(buildCommentHandoffPrompt(issues, context, reason), { deliverAs: "followUp" });
+  ctx.ui.notify(`Queued PR comment request for ${issues.length} selected finding(s)`, "info");
+}
+
+function toExecLike(pi: ReviewActionPi): ExecLike {
+  return async (command, args, options) => await pi.exec(command, args, options);
+}
+
+function selectedIssues(issues: readonly ReviewIssue[], issueIds: readonly string[]): ReviewIssue[] {
+  const selected = new Set(issueIds);
+  return issues.filter((issue) => selected.has(issue.id));
+}
+
+function summarizeStatuses(statuses: readonly InlineCommentStatus[]): { readonly posted: number; readonly skipped: number; readonly failed: number } {
+  let posted = 0;
+  let skipped = 0;
+  let failed = 0;
+  for (const status of statuses) {
+    if (status.status === "posted") posted++;
+    else if (status.status === "skipped") skipped++;
+    else failed++;
+  }
+  return { posted, skipped, failed };
+}