pi-pr-review 1.3.1 → 1.5.0

package/README.md

@@ -8,7 +8,7 @@ Pass a PR number and pi will:
 2. Derive the **base branch** and **head (merging) branch** automatically from the PR.
 3. Review the base↔head diff with disciplined passes (overview, convention compliance, bugs, security/perf, readability), best-effort build/test verification, then validate each candidate.
 4. Return a **full structured review**: overview, strengths, verification, findings at **every** severity (`nit → P3 → P2 → P1 → P0`) with a blocking flag, correctness/security/performance notes, and a verdict.
-5. Optionally post the review + inline PR comments (`--comment`).
+5. Optionally publish one formal GitHub `COMMENT` review with a top-level body and associated inline comments.
 
 **Captures everything, then ranks it.** Unlike a high-signal-only reviewer, it does not discard minor issues — nits, style, naming, missing edge cases, and "worth confirming" observations are all reported as low-severity findings. The **verdict** depends only on *blocking* (P0/P1) findings, so a clean PR is still approved while its nits are still recorded.
 
@@ -66,6 +66,8 @@ The `/pr-review-config` command maps three labels to models:
 /pr-review-config light=<spec> medium=<spec> heavy=<spec>   # set primary tier models
 /pr-review-config heavy_fallbacks=<spec>,<spec>     # retry chain for quota/rate-limit failures
 /pr-review-config light_tool_policy=none            # tier default when a pass omits tool_policy
+/pr-review-config auto_post_reviews=true            # opt in to automatic GitHub COMMENT reviews
+/pr-review-config auto_post_reviews=false           # disable automatic posting (the default)
 /pr-review-config medium=unset                      # clear a tier (back to pi default)
 /pr-review-config heavy_fallbacks=unset             # clear a fallback chain
 /pr-review-config light_tool_policy=unset           # restore legacy configured-tool behavior
@@ -74,7 +76,7 @@ The `/pr-review-config` command maps three labels to models:
 
 Running `/pr-review-config` with no arguments in the TUI opens an interactive settings menu that mirrors pi's `/settings` and the NERVous `/nervous:config`:
 
-- One primary-model, fallback-model, and tool-policy row per tier (`light` / `medium` / `heavy`) plus a configured-tool allowlist row.
+- One primary-model, fallback-model, and tool-policy row per tier (`light` / `medium` / `heavy`), an automatic-posting toggle, plus a configured-tool allowlist row.
 - Press Enter on a primary or fallback row to pick a model from a searchable list (or unset it); Enter/Space cycles tool policies and allowlist presets. The menu sets one fallback model at a time; use the `key=value` form for longer fallback chains.
 - Selections apply and persist **immediately**; Esc closes the menu.
 - Type to search, and tab-completion is available for the `key=value` form.
@@ -105,6 +107,7 @@ Example `pr-review.json`:
     "medium": "configured",
     "heavy": "configured"
   },
+  "autoPostReviews": false,
   "tools": ["read", "bash", "grep", "find", "ls"]
 }
 ```
@@ -127,21 +130,28 @@ The orchestrator (which fetches the PR, merges findings, and emits the JSON) and
 Type `/` in the pi editor and pick `pr-review`, or:
 
 ```
-/pr-review 123                            # analysis only — prints the JSON report, no GitHub writes
-/pr-review 123 --comment                  # also posts inline review comments to the PR
+/pr-review 123                            # use autoPostReviews (false by default)
+/pr-review 123 --comment                  # force one COMMENT review for this run
+/pr-review 123 --no-comment               # suppress posting for this run
 /pr-review 123 --include-closed           # review a closed/merged PR without a confirmation prompt
-/pr-review 123 --review-closed --comment  # review/comment on a closed/merged PR when GitHub accepts it
+/pr-review 123 --review-closed --comment  # review and attempt a body-only COMMENT review
 ```
 
 `123` is the PR number in the current repo.
 
 ### Closed or merged PRs
 
-Closed/merged PRs no longer hard-skip. If you run `/pr-review 123` on a non-open PR, the prompt asks whether to continue before producing a review. Use `--include-closed` or `--review-closed` to proceed non-interactively. If `--comment` is also used and GitHub rejects inline comments on the non-open PR, findings should be folded into the summary comment instead.
+Closed/merged PRs no longer hard-skip. If you run `/pr-review 123` on a non-open PR, the prompt asks whether to continue before producing a review. Use `--include-closed` or `--review-closed` to proceed non-interactively. When publication is enabled, the extension preemptively folds inline findings into one body-only formal `COMMENT` review; if GitHub rejects it, publication fails explicitly without creating an issue comment.
+
+### Automatic GitHub review posting
+
+`autoPostReviews` is a strict top-level boolean and defaults to `false`. A trusted project `.pi/pr-review.json` value overlays the user value; malformed effective values never enable posting. `/pr-review-config` edits user scope only and displays the effective value/source—if a trusted project overlay wins, edit that project file or use `--no-comment` for the run. Invocation flags are captured before prompt expansion: `--comment` forces posting for one run, `--no-comment` suppresses it, and using both is rejected.
+
+Publishing is extension-owned—the model never constructs the write request, and final JSON marked `disposition: "skipped"` is never published. It creates exactly one formal pull-request review containing a top-level body and associated P0–P3 inline comments. The GitHub event is hardcoded to `COMMENT`; the publisher cannot send `APPROVE` or `REQUEST_CHANGES`, even when the review's suggested verdict is `request_changes`. It validates the current head and every inline diff anchor before the single POST, so an invalid open-PR inline comment fails without leaving a partial review. Closed/merged PRs require either `--include-closed`/`--review-closed` or the one-shot affirmative confirmation, then use one body-only `COMMENT` review with inline findings folded into the body. Unknown or unconfirmed non-open lifecycle states fail without posting.
 
 ### Duplicate review handling
 
-`--comment` summary comments include a hidden `pi-pr-review` marker with the reviewed `headRefOid`. A later run skips only when it finds a marker for the **current** head SHA. If new commits were pushed after the previous review, the head SHA changes and `/pr-review` reviews the PR again. Older unmarked comments are treated as unknown/stale, not proof that the current head was already reviewed.
+Published reviews include a hidden `pi-pr-review` marker with the reviewed `headRefOid`. A later run skips only when it finds a same-head marker authored by the current authenticated GitHub identity in either formal reviews or legacy issue comments. If new commits were pushed, the head SHA changes and `/pr-review` reviews the PR again. Older or unmarked content is not proof that the current head was reviewed.
 
 ### Response format
 
@@ -153,7 +163,8 @@ Example payload:
 
 ```json
 {
-  "pr": { "number": 33, "title": "fix(logs): parse date-time log timestamps" },
+  "pr": { "number": 33, "title": "fix(logs): parse date-time log timestamps", "head_sha": "0123456789abcdef0123456789abcdef01234567" },
+  "disposition": "reviewed",
   "verification": "`go build ./...` ✅, `go test ./...` ✅ (130 passed)",
   "overview": "Migrates log timestamps from epoch-ms to RFC3339 to match the endpoint contract.",
   "strengths": ["Reuses FormatTimestamp instead of ad-hoc formatting; net -3 lines."],
@@ -182,7 +193,7 @@ Example payload:
 
 Severity tags: `[P0]` blocking/drop-everything · `[P1]` blocking/urgent · `[P2]` normal · `[P3]` low · `[nit]` trivial/optional. Verdict is `approve` (no blocking findings), `request_changes` (a blocking finding exists), or `comment`.
 
-**Inline-comment ready.** Each finding's `code_location` is diff-anchored — repo-relative `absolute_file_path`, `line_range` on `side` (`RIGHT` for added/context lines, `LEFT` for removed), and `commentable` (whether the lines are inside a diff hunk). The rendered table shows an **Inline** ✎ column for findings that can be posted as GitHub inline review comments. With `--comment`, a summary review is posted plus inline comments (single- or multi-line, using each finding's anchor) for every commentable blocking/P2/P3 finding; nits and off-diff/repo-wide observations fold into the summary.
+**Inline-comment ready.** Each finding's `code_location` is diff-anchored — repo-relative `absolute_file_path`, `line_range` on `side` (`RIGHT` for added/context lines, `LEFT` for removed), and `commentable` (whether the lines are inside a diff hunk). The rendered table shows an **Inline** ✎ column. When publishing is enabled, the extension validates these anchors against current GitHub diff metadata and attaches eligible P0–P3 findings under the single formal review; nits and off-diff observations stay in the top-level body.
 
 ## What's in the package
 
@@ -191,9 +202,11 @@ pi-pr-review/
 ├─ package.json                      # pi manifest: prompts + extensions
 ├─ prompts/pr-review.md              # the /pr-review orchestrator prompt
 ├─ lib/pr-review-policy.ts           # pure tool-policy resolution/argv helpers
+├─ lib/pr-review-publish.ts          # safe COMMENT-review payload, validation, and gh publisher
 ├─ extensions/pr-review-subagent.ts  # review_subagents/review_subagent tools + /pr-review-config command
-├─ extensions/review-table.ts        # renders the final JSON as a table (TUI only)
-└─ tests/pr-review-policy.test.ts     # focused policy compatibility tests
+├─ extensions/review-table.ts        # renders JSON and triggers trusted configured publishing
+├─ tests/pr-review-policy.test.ts     # focused policy compatibility tests
+└─ tests/pr-review-publish.test.ts    # posting gate, payload, marker, and anchor tests
 ```
 
 ## Speed, security & cost notes
@@ -201,12 +214,14 @@ pi-pr-review/
 - The four independent review lenses remain intact. Only overview runs context-only with `--no-tools`; medium and both heavy specialists retain configured tools for surrounding-file validation. All subprocesses use `--no-context-files` because the orchestrator supplies the base review context explicitly, and convention excerpts are sent only to the medium pass instead of every model.
 - Tool results include effective `toolPolicy` and `elapsedMs` telemetry (plus per-attempt timing) so repeated representative runs can be compared at p50/p95 without guessing. Restore tools for a custom pass by sending `tool_policy: "configured"`; callers that omit policy retain legacy behavior unless `toolPolicies` config says otherwise.
 - The `review_subagents` batch tool and `review_subagent` fallback spawn isolated `pi` subprocesses (`--mode json -p --no-session`) on your configured tier models. Reviewer prompts prohibit modifications, but a configured allowlist containing `bash` is not technically read-only; use a narrower allowlist if stronger enforcement is required.
-- Project-local `pr-review.json` is only read when the project is trusted.
+- Project-local `pr-review.json` is only read when the project is trusted. Because project `autoPostReviews: true` causes writes under your authenticated `gh` identity, the effective setting and source are surfaced when publication occurs.
+- GitHub publication uses `gh` only, verifies the current identity and PR head, checks paginated formal reviews and legacy comments for same-head markers, and hardcodes `event: COMMENT`. Ambiguous transport failures are reconciled once and never blindly retried.
+- **`gh api -f` caution:** `gh api ... -f body=@/tmp/file.md` posts the literal text `@/tmp/file.md`; unlike `gh pr comment --body-file`, `-f` does not expand `@file`. Use a JSON payload via `gh api ... --input -` for API requests. The built-in publisher already does this.
 - Tiered review calls multiple models per PR, concurrently for independent passes. Point `light` at a cheap model for overview/risk scan; reserve `heavy` for deep passes, and configure per-tier `fallbacks` only for acceptable backup models because retries can increase cost.
 
 ## Design notes
 
-- **Process** mirrors the Claude review workflow (PR-number driven, confirm-before-reviewing closed/merged PRs, skip draft/same-head-already-reviewed, overview + strengths, convention/readability/maintainability, best-effort build/test verification, validate-then-classify, optional comment posting with strict GitHub permalink rules) with bounded parallel multi-model fan-out (configurable light/medium/heavy tiers).
+- **Process** is PR-number driven: confirm non-open PRs, skip draft/same-head-already-reviewed work, fan out four review lenses, verify, validate/classify, emit JSON, then optionally publish one extension-owned formal `COMMENT` review.
 - **Captures every severity** (`nit → P0`) with a `blocking` flag; the verdict depends only on blocking findings, so nothing minor is lost but a clean PR still gets approved.
 - **Verification is non-destructive:** any build/test runs in an isolated `git worktree` on the PR head — the prompt never checks out, commits, or pushes in your working tree.
 - pi has no built-in sub-agents, so tiering is implemented as an extension that spawns isolated `pi` subprocesses per tier; the batch tool gives deterministic parallelism, and the prompt degrades gracefully to single-pass or inline review when the extension is absent.

package/extensions/pr-review-subagent.ts

@@ -53,6 +53,7 @@ import {
 	resolveToolPolicy,
 	type ToolPolicy,
 } from "../lib/pr-review-policy.ts";
+import { resolveAutoPostSetting } from "../lib/pr-review-publish.ts";
 
 // ---------------------------------------------------------------------------
 // Config
@@ -80,6 +81,8 @@ interface PrReviewConfig {
 	fallbacks: Partial<Record<Tier, string[]>>;
 	/** Optional tier-level policy used when a tool call does not override it. */
 	toolPolicies: Partial<Record<Tier, ToolPolicy>>;
+	/** Automatically publish final review JSON as a GitHub COMMENT review. Disabled by default. */
+	autoPostReviews: boolean;
 	/** Tools granted to review subagents whose effective policy is configured. */
 	tools: string[];
 }
@@ -136,6 +139,17 @@ function normalizeToolPolicies(
 	return out;
 }
 
+function resolveAutoPostForContext(ctx: Pick<ExtensionContext, "cwd" | "isProjectTrusted">) {
+	const user = readConfigFile(userConfigPath());
+	let project: Partial<PrReviewConfig> | undefined;
+	try {
+		if (ctx.isProjectTrusted()) project = readConfigFile(projectConfigPath(ctx.cwd));
+	} catch {
+		/* user config only */
+	}
+	return resolveAutoPostSetting(user, project);
+}
+
 /** User config, overlaid by project config when the project is trusted. */
 function loadConfig(ctx: Pick<ExtensionContext, "cwd" | "isProjectTrusted">): PrReviewConfig {
 	const user = readConfigFile(userConfigPath());
@@ -145,6 +159,7 @@ function loadConfig(ctx: Pick<ExtensionContext, "cwd" | "isProjectTrusted">): Pr
 	} catch {
 		/* trust check unavailable -> user config only */
 	}
+	const autoPost = resolveAutoPostSetting(user, project);
 	return {
 		tiers: { ...(user.tiers ?? {}), ...(project.tiers ?? {}) },
 		fallbacks: { ...normalizeFallbacks(user.fallbacks, true), ...normalizeFallbacks(project.fallbacks, true) },
@@ -152,6 +167,7 @@ function loadConfig(ctx: Pick<ExtensionContext, "cwd" | "isProjectTrusted">): Pr
 			...normalizeToolPolicies(user.toolPolicies),
 			...normalizeToolPolicies(project.toolPolicies),
 		},
+		autoPostReviews: autoPost.valid ? autoPost.value : false,
 		tools: project.tools ?? user.tools ?? DEFAULT_TOOLS,
 	};
 }
@@ -159,10 +175,12 @@ function loadConfig(ctx: Pick<ExtensionContext, "cwd" | "isProjectTrusted">): Pr
 /** User-level config only (the scope the config command edits), with defaults. */
 function readUserConfig(): PrReviewConfig {
 	const raw = readConfigFile(userConfigPath());
+	const autoPost = resolveAutoPostSetting(raw);
 	return {
 		tiers: { ...(raw.tiers ?? {}) },
 		fallbacks: normalizeFallbacks(raw.fallbacks),
 		toolPolicies: normalizeToolPolicies(raw.toolPolicies),
+		autoPostReviews: autoPost.valid ? autoPost.value : false,
 		tools: raw.tools ?? [...DEFAULT_TOOLS],
 	};
 }
@@ -952,8 +970,9 @@ const CONFIG_COMPLETIONS: Array<{ value: string; label: string }> = [
 		value: `${t}_tool_policy=`,
 		label: `${t}_tool_policy=<none|configured|unset> — default tool access when a pass does not override it`,
 	})),
+	{ value: "auto_post_reviews=", label: "auto_post_reviews=<true|false> — automatically post COMMENT reviews (default false)" },
 	{ value: "tools=", label: "tools=read,bash,grep,find,ls — allowlist used by configured policy" },
-	{ value: "show", label: "show — print the current tier config" },
+	{ value: "show", label: "show — print the current review config" },
 ];
 
 /** Split respecting single/double quotes so `evidence`-style values with spaces survive. */
@@ -1019,6 +1038,7 @@ interface ConfigPatch {
 	tiers: Partial<Record<Tier, string | null>>;
 	fallbacks: Partial<Record<Tier, string[] | null>>;
 	toolPolicies: Partial<Record<Tier, ToolPolicy | null>>;
+	autoPostReviews?: boolean;
 	tools?: string[];
 }
 
@@ -1047,11 +1067,15 @@ function parseConfigArgs(args: string): { patch: ConfigPatch; hasChanges: boolea
 				if (policy) patch.toolPolicies[tier] = policy;
 				else errors.push(`invalid ${key} "${value}" (expected none|configured|unset)`);
 			}
+		} else if (key === "auto_post_reviews" || key === "autopostreviews" || key === "auto-post-reviews") {
+			if (value === "true") patch.autoPostReviews = true;
+			else if (value === "false") patch.autoPostReviews = false;
+			else errors.push(`invalid ${key} "${value}" (expected true|false)`);
 		} else if (key === "tools") {
 			patch.tools = splitCommaList(value);
 		} else {
 			errors.push(
-				`unknown key "${key}" (expected light|medium|heavy|<tier>_fallbacks|<tier>_tool_policy|tools)`,
+				`unknown key "${key}" (expected light|medium|heavy|<tier>_fallbacks|<tier>_tool_policy|auto_post_reviews|tools)`,
 			);
 		}
 	}
@@ -1059,6 +1083,7 @@ function parseConfigArgs(args: string): { patch: ConfigPatch; hasChanges: boolea
 		Object.keys(patch.tiers).length > 0 ||
 		Object.keys(patch.fallbacks).length > 0 ||
 		Object.keys(patch.toolPolicies).length > 0 ||
+		patch.autoPostReviews !== undefined ||
 		patch.tools !== undefined;
 	return { patch, hasChanges, errors };
 }
@@ -1068,6 +1093,7 @@ function applyConfigPatch(base: PrReviewConfig, patch: ConfigPatch): PrReviewCon
 		tiers: { ...base.tiers },
 		fallbacks: normalizeFallbacks(base.fallbacks),
 		toolPolicies: normalizeToolPolicies(base.toolPolicies),
+		autoPostReviews: base.autoPostReviews,
 		tools: [...base.tools],
 	};
 	for (const tier of TIERS) {
@@ -1087,6 +1113,7 @@ function applyConfigPatch(base: PrReviewConfig, patch: ConfigPatch): PrReviewCon
 			else next.toolPolicies[tier] = value;
 		}
 	}
+	if (patch.autoPostReviews !== undefined) next.autoPostReviews = patch.autoPostReviews;
 	if (patch.tools) next.tools = patch.tools;
 	return next;
 }
@@ -1110,6 +1137,7 @@ function summarizeConfig(
 	} catch {
 		/* ignore */
 	}
+	const autoPost = resolveAutoPostForContext(ctx);
 	const lines = [
 		`# PR review config${changed ? " updated" : ""}`,
 		"",
@@ -1119,6 +1147,7 @@ function summarizeConfig(
 			(t) =>
 				`| \`${t}\` | ${user.tiers[t] ? `\`${user.tiers[t]}\`` : "_unset_"} | ${effective.tiers[t] ? `\`${effective.tiers[t]}\`` : "_pi default_"} | ${TIER_PURPOSE[t]} |`,
 		),
+		`| \`autoPostReviews\` | \`${user.autoPostReviews}\` | \`${effective.autoPostReviews}\` (${autoPost.source}) | automatically post one GitHub \`COMMENT\` review; default \`false\` |`,
 		`| \`tools\` | \`${user.tools.join(",")}\` | \`${effective.tools.join(",")}\` | allowlist used when policy is \`configured\` |`,
 		"",
 		"| Tier | Your fallbacks | Effective fallbacks | Tool policy |",
@@ -1131,6 +1160,10 @@ function summarizeConfig(
 		`User config: \`${userConfigPath()}\``,
 	];
 	if (projectPath) lines.push(`Project overlay (trusted): \`${projectPath}\``);
+	if (!autoPost.valid) lines.push(`Automatic posting config error: ${autoPost.error}`);
+	else if (autoPost.source === "project") {
+		lines.push("Automatic posting is controlled by the trusted project overlay; this command edits user config only.");
+	}
 	lines.push(
 		"",
 		"## Usage",
@@ -1138,6 +1171,8 @@ function summarizeConfig(
 		"- Print this summary: `/pr-review-config show`",
 		"- Set directly: `/pr-review-config light=provider/model heavy=provider/model:high`",
 		"- Set fallback chain: `/pr-review-config heavy_fallbacks=provider/backup:high,provider/backup2`",
+		"- Enable automatic GitHub review posting: `/pr-review-config auto_post_reviews=true`",
+		"- Disable automatic GitHub review posting: `/pr-review-config auto_post_reviews=false`",
 		"- Set tier tool policy: `/pr-review-config light_tool_policy=none`",
 		"- Clear a tier: `/pr-review-config medium=unset`",
 		"- Clear fallback chain: `/pr-review-config heavy_fallbacks=unset`",
@@ -1250,6 +1285,13 @@ function configMenuItems(cfg: PrReviewConfig, available: string[]): SettingItem[
 		...tierItems,
 		...fallbackItems,
 		...policyItems,
+		{
+			id: "auto_post_reviews",
+			label: "user automatic posting setting",
+			description: "Post one GitHub COMMENT review after final JSON. Disabled by default.",
+			currentValue: String(cfg.autoPostReviews),
+			values: ["false", "true"],
+		},
 		{
 			id: "tools",
 			label: "configured tool allowlist",
@@ -1281,6 +1323,7 @@ async function showConfigMenu(
 					settingsList.updateValue(`${tier}_fallbacks`, draft.fallbacks[tier]?.join(",") || "(none)");
 					settingsList.updateValue(`${tier}_tool_policy`, draft.toolPolicies[tier] ?? INHERIT_TOOL_POLICY);
 				}
+				settingsList.updateValue("auto_post_reviews", String(draft.autoPostReviews));
 				settingsList.updateValue("tools", draft.tools.join(","));
 			};
 
@@ -1299,6 +1342,8 @@ async function showConfigMenu(
 						const policy = normalizeToolPolicy(newValue);
 						if (policy) draft.toolPolicies[tier] = policy;
 					}
+				} else if (id === "auto_post_reviews") {
+					draft.autoPostReviews = newValue === "true";
 				} else if (id === "tools") {
 					draft.tools = splitCommaList(newValue);
 				} else {
@@ -1309,12 +1354,26 @@ async function showConfigMenu(
 					refresh();
 					const shown = id === "tools"
 						? draft.tools.join(",")
-						: isFallbackKey(id)
-							? (draft.fallbacks[tierFromCompoundKey(id)]?.join(",") ?? "(none)")
-							: isToolPolicyKey(id)
-								? (draft.toolPolicies[tierFromCompoundKey(id)] ?? INHERIT_TOOL_POLICY)
-								: (draft.tiers[id as Tier] ?? UNSET);
-					ctx.ui.notify(`PR review config: ${id} = ${shown}`, "info");
+						: id === "auto_post_reviews"
+							? String(draft.autoPostReviews)
+							: isFallbackKey(id)
+								? (draft.fallbacks[tierFromCompoundKey(id)]?.join(",") ?? "(none)")
+								: isToolPolicyKey(id)
+									? (draft.toolPolicies[tierFromCompoundKey(id)] ?? INHERIT_TOOL_POLICY)
+									: (draft.tiers[id as Tier] ?? UNSET);
+					if (id === "auto_post_reviews") {
+						const effective = resolveAutoPostForContext(ctx);
+						if (effective.source === "project") {
+							ctx.ui.notify(
+								`User autoPostReviews saved as ${shown}, but trusted project config remains effective at ${effective.value}. Edit ${projectConfigPath(ctx.cwd)} or use --no-comment.`,
+								"warning",
+							);
+						} else {
+							ctx.ui.notify(`PR review config: ${id} = ${shown} (effective ${effective.value})`, "info");
+						}
+					} else {
+						ctx.ui.notify(`PR review config: ${id} = ${shown}`, "info");
+					}
 				} catch (e) {
 					ctx.ui.notify(`pr-review-config failed: ${errMessage(e)}`, "error");
 				}
@@ -1323,7 +1382,7 @@ async function showConfigMenu(
 
 			settingsList = new SettingsList(
 				configMenuItems(draft, available),
-				12,
+				13,
 				getSettingsListTheme(),
 				(id, newValue) => persist(id, newValue),
 				() => done(undefined),

package/extensions/review-table.ts

@@ -1,15 +1,36 @@
 /**
  * review-table
  *
- * Renders the /pr-review final JSON response as a full, readable review in the TUI:
- * header, verification, overview, strengths, a findings table (nit → P0) with
- * per-finding details, correctness/security/performance notes, and the verdict.
+ * Renders the /pr-review final JSON response as a readable TUI review and owns
+ * configured GitHub publication after valid final JSON. Publishing is bound to raw
+ * invocation flags/config, validates current PR state and anchors, and can emit only
+ * one formal COMMENT review with associated inline comments.
  *
- * Only rewrites in interactive TUI mode. In print / json / rpc modes the raw JSON is
- * left untouched so piping and automation keep a machine-readable payload.
+ * Rendering only rewrites interactive TUI output. Print/json/rpc modes retain raw JSON.
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+	CONFIG_DIR_NAME,
+	type ExtensionAPI,
+	type ExtensionContext,
+	getAgentDir,
+} from "@earendil-works/pi-coding-agent";
+import {
+	classifyAssistantCompletion,
+	isNonOpenConfirmationPrompt,
+	parsePublishMode,
+	parsePublishableReview,
+	publishPullReview,
+	resolveAutoPostSetting,
+	ReviewInvocationGate,
+	shouldPublishReview,
+	validateReviewInvocation,
+	type AutoPostResolution,
+	type ReviewInvocation,
+	type ReviewLike,
+} from "../lib/pr-review-publish.ts";
 
 type Severity = "P0" | "P1" | "P2" | "P3" | "nit";
 
@@ -29,7 +50,8 @@ interface Finding {
 }
 
 interface Review {
-	pr?: { number?: number | null; title?: string | null } | null;
+	pr?: { number?: number | null; title?: string | null; head_sha?: string | null } | null;
+	disposition?: "reviewed" | "skipped";
 	verification?: string;
 	overview?: string;
 	strengths?: string[];
@@ -256,19 +278,138 @@ function renderReviewMarkdown(r: Review): string {
 	return out.join("\n").trimEnd();
 }
 
+interface ConfigReadResult {
+	value: Record<string, unknown>;
+	error?: string;
+}
+
+function readJsonObject(filePath: string): ConfigReadResult {
+	try {
+		if (!fs.existsSync(filePath)) return { value: {} };
+		const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+		return parsed && typeof parsed === "object"
+			? { value: parsed as Record<string, unknown> }
+			: { value: {}, error: `${filePath} must contain a JSON object` };
+	} catch (error) {
+		return { value: {}, error: `${filePath} is invalid JSON: ${String(error)}` };
+	}
+}
+
+function resolvePublishingConfig(ctx: ExtensionContext): AutoPostResolution {
+	const user = readJsonObject(path.join(getAgentDir(), "pr-review.json"));
+	if (user.error) return { value: false, valid: false, source: "user", error: user.error };
+	let project: ConfigReadResult | undefined;
+	try {
+		if (ctx.isProjectTrusted()) {
+			project = readJsonObject(path.join(ctx.cwd, CONFIG_DIR_NAME, "pr-review.json"));
+			if (project.error) return { value: false, valid: false, source: "project", error: project.error };
+		}
+	} catch {
+		/* user config only */
+	}
+	return resolveAutoPostSetting(user.value, project?.value);
+}
+
+async function maybePublishReview(text: string, invocation: ReviewInvocation, ctx: ExtensionContext): Promise<void> {
+	if (invocation.mode === "disabled") return;
+	const setting = resolvePublishingConfig(ctx);
+	if (invocation.mode === "auto") {
+		if (!setting.valid) {
+			ctx.ui.notify(`PR review was not posted: ${setting.error}`, "error");
+			return;
+		}
+		if (!setting.value) return;
+	}
+	const parsed = parsePublishableReview(text);
+	if (!parsed.review) {
+		ctx.ui.notify(`PR review was not posted: ${parsed.error}`, "error");
+		return;
+	}
+	const bindingError = validateReviewInvocation(parsed.review, invocation);
+	if (bindingError) {
+		ctx.ui.notify(`PR review was not posted: ${bindingError}`, "error");
+		return;
+	}
+	if (!shouldPublishReview(parsed.review)) return;
+	const headSha = parsed.review.pr?.head_sha;
+	if (typeof headSha !== "string") {
+		ctx.ui.notify("PR review was not posted: final JSON is missing pr.head_sha", "error");
+		return;
+	}
+	const result = await publishPullReview({
+		cwd: ctx.cwd,
+		prNumber: invocation.prNumber,
+		headSha,
+		allowNonOpen: invocation.allowNonOpen,
+		review: parsed.review as ReviewLike,
+	});
+	const source = invocation.mode === "force" ? "--comment" : `${setting.source} config`;
+	if (result.status === "posted") {
+		ctx.ui.notify(`PR review posted as COMMENT (${source})${result.url ? `: ${result.url}` : ""}`, "info");
+	} else if (result.status === "posted_degraded") {
+		ctx.ui.notify(`PR review posted as body-only COMMENT for non-open PR (${source})`, "warning");
+	} else if (result.status === "skipped_duplicate") {
+		ctx.ui.notify("PR review not reposted: this head was already reviewed by the current GitHub identity", "info");
+	} else {
+		ctx.ui.notify(`PR review publish ${result.status}: ${result.message}`, "error");
+	}
+}
+
 export default function (pi: ExtensionAPI) {
+	const invocationGate = new ReviewInvocationGate();
+
+	pi.on("session_start", () => {
+		invocationGate.clear();
+	});
+
+	pi.on("input", (event, ctx) => {
+		if (invocationGate.phase() === "awaiting_confirmation") {
+			const confirmation = invocationGate.resolveConfirmationInput(event.text);
+			if (confirmation === "confirmed") return;
+			// Negative/unrelated input clears authority; a fresh /pr-review may bind below.
+		}
+		const parsed = parsePublishMode(event.text);
+		if (!parsed.matched) return;
+		if (invocationGate.peek() && event.streamingBehavior === undefined) {
+			// Replace an abandoned/settled invocation, but never a queued/steering one.
+			invocationGate.clear();
+		}
+		const gate = invocationGate.begin(parsed);
+		if (!gate.accepted) {
+			ctx.ui.notify(`Invalid /pr-review invocation: ${gate.error}`, "error");
+			return { action: "handled" as const };
+		}
+	});
+
 	pi.on("message_end", async (event, ctx) => {
-		// Keep raw JSON for automation; only prettify for interactive terminals.
-		if (ctx.mode !== "tui") return;
 		if (event.message.role !== "assistant") return;
-		if (hasToolCall(event.message)) return; // not the final text-only answer
+		const completion = classifyAssistantCompletion(event.message.stopReason, hasToolCall(event.message));
+		if (completion === "continue_tools") return;
+		if (completion === "clear_invocation") {
+			invocationGate.clear();
+			return;
+		}
 
 		const text = assistantText(event.message);
-		if (!text.trim()) return;
+		const active = invocationGate.peek();
+		if (
+			active &&
+			invocationGate.phase() === "reviewing" &&
+			isNonOpenConfirmationPrompt(text, active.prNumber)
+		) {
+			invocationGate.markAwaitingConfirmation();
+			return;
+		}
 
+		// Every other terminal response consumes authority, whether valid, empty, or unrelated.
+		const invocation = active ? invocationGate.consume() : undefined;
+		if (!text.trim()) return;
 		const review = parseReview(text);
 		if (!review) return; // not a /pr-review JSON payload — leave untouched
+		if (invocation) await maybePublishReview(text, invocation, ctx);
 
+		// Keep raw JSON for automation; only prettify for interactive terminals.
+		if (ctx.mode !== "tui") return;
 		const nonText = (event.message.content as MessagePart[]).filter((p) => p.type !== "text");
 		return {
 			message: {