feat(review): AI review agents, local worktree, and UI polish

[backnotprop]

Summary

• AI review agents: Codex and Claude Code as background review providers with live log streaming, structured output parsing, and findings as external annotations in the diff viewer
• Claude-specific review model: Own schema (severity-based: important/nit/pre_existing), multi-agent prompt (Bug+Regression, Security, Code Quality, Guideline Compliance), reasoning traces per finding, converged with Claude Code's remote review service
• Local worktree (default for PRs): Automatically creates a temporary worktree/clone so agents have full file access. Same-repo uses fast git worktree with fresh origin/; cross-repo uses shallow clone with local + remote tracking refs. --no-local to opt out
• Separated concerns: agentCwd option keeps agent sandbox completely independent from the diff rendering pipeline — no contamination of file contents, diff switching, or expandable context
• PR comments panel overhaul: Search, sort, collapse, author filter, inline review threads with resolved/outdated state and diff hunk previews via @pierre/diffs
• Pi extension parity: Full agent review mirroring — stdin/stdout/stderr handling, live log streaming, result ingestion, buildCommand/onJobComplete callbacks. Vendored review modules with import rewriting. Runtime-agnostic codex-review.ts (node:fs/promises instead of Bun APIs)
• UI polish: Unified 33px panel headers, consistent borders/backgrounds/typography, responsive toolbar buttons, dockview tab focus fix, shared ReviewAgentsIcon, severity markers + reasoning in inline annotations and copy/export paths
• Security: XSS fix (removed onerror from DOMPurify allowlist), removed find/ls/cat from Claude allowed tools (exec bypass), added glab CLI support, git flag injection guards, baseSha hex validation, shell provider removed, same-repo detection includes host comparison for GHE
• Reliability: stdout drain race fix (2s grace period after proc.exited), Codex verdict override for P0/P1 findings, Claude parse failure logging, temp clone cleanup on failed fetch/checkout
• @pierre/diffs upgrade: 1.1.0-beta.19 → 1.1.12 (13 stable releases of bug fixes)
• Docs: AI Code Review Agents guide with full prompt/command/schema transparency

Test plan

• plannotator review <pr-url> — PR loads with local worktree by default, worktree badge visible
• plannotator review <pr-url> --no-local — no worktree, agents run without file access
• plannotator review (local, no URL) — diff switcher works, merge-base option available
• Launch Codex agent — findings appear with [P0]/[P1] tags, verdict red when P0/P1 present
• Launch Claude agent — findings appear with [important]/[nit] tags, severity dots, reasoning text
• Agent detail panel: live logs stream, findings sorted by severity, legend visible, copy includes reasoning
• PR comments panel: search works, threads show resolved/outdated state, no j/k conflict with file tree
• Panel headers aligned at same height across all three columns
• Same-repo detection works for GHE (host comparison)
• Cross-repo clone creates both local and origin/ refs
• No debug log growth unless PLANNOTATOR_DEBUG=1
• Pi extension: agent launch succeeds with vendored review modules
• No type errors introduced (5 pre-existing errors in review tsconfig)

[backnotprop]

Review from Plannotator

[backnotprop]

[P1] Shell-capable installs can no longer start any review agent

This launch payload now omits command, but the server only synthesizes commands for non-shell providers. On machines where shell is the only available capability, or when a user explicitly selects it, /api/agents/jobs returns Missing "command" array and launchJob() drops the error, so the newly re-enabled Run Agent button becomes a silent no-op.

[backnotprop]

[P2] Findings are normalized against the wrong working tree after a diff switch

This path normalization uses currentDiffType at completion time instead of the job's launch-time cwd from meta.cwd. If the reviewer switches worktrees or diff modes while an agent is still running, absolute paths from the agent are rebased against the wrong root, so the generated annotations no longer match the relative diff file paths and show up unattached or on the wrong file.

[backnotprop]

[P2] GitHub Enterprise cross-repo --local reviews never get a local checkout

In the cross-repo path this expands to gh repo clone owner/repo <dir> --hostname <host> -- ..., but gh repo clone does not support a --hostname flag. For self-hosted GitHub PRs the shallow clone step fails immediately, so the code falls back to remote-only mode and agents lose the local worktree access that --local is supposed to provide.

[backnotprop]

[P1] openDiffFile omitted from annotation click handler — clicking findings no longer navigates to the file

In handleAnnotationClick, the call to state.openDiffFile(ann.filePath) was removed during the refactor that added live logging. The handler now only calls state.onSelectAnnotation(ann.id), which means clicking a finding row in the agent job detail panel selects the annotation in state but the diff viewer does not switch to the relevant file. The function openDiffFile still exists in ReviewStateContext (line 80) and is properly typed. The missing call should be restored:

const handleAnnotationClick = useCallback((ann: CodeAnnotation) => {
  state.openDiffFile(ann.filePath);  // was dropped
  state.onSelectAnnotation(ann.id);
}, [state.openDiffFile, state.onSelectAnnotation]);

[backnotprop]

[P1] gh repo clone passes unvalidated owner/repo before --, enabling flag injection via crafted PR URL

The prRepo value (owner/repo) comes from a URL regex that only excludes / — it allows any other characters, including --flag=value. The -- end-of-flags marker is placed after prRepo and localPath, so it does not protect against flag injection:

[cli, "repo", "clone", prRepo, localPath, ...hostnameArgs, "--", "--depth=1", "--no-checkout"]

A URL like https://github.com/--upload-pack=malicious/repo/pull/1 would produce owner = "--upload-pack=malicious", which gh interprets as a flag. The --upload-pack option causes gh/git to execute an arbitrary command on clone.

Fix: move -- before prRepo:

[cli, "repo", "clone", "--", prRepo, localPath, ...hostnameArgs, "--depth=1", "--no-checkout"]

Or validate owner and repo match ^[a-zA-Z0-9._-]+$ before use.

[backnotprop]

[P2] JSONL lines split on chunk boundaries in stdout drain — garbled live log output

The stdout drain loop splits text (the current chunk) on '\n' directly, without maintaining a partial-line buffer across chunks:

const lines = text.split('\n');

When a JSONL line (e.g. a Claude assistant message) spans two network chunks, the tail of the first chunk and the head of the second are treated as separate lines. Both fail JSON.parse and are broadcast as raw fragments, producing garbled output in LiveLogViewer. The final result is unaffected (stdoutBuf accumulates correctly), but the live view is broken for large messages.

Fix: maintain a lineBuffer that persists the incomplete last segment across iterations:

let lineBuffer = "";
for await (const chunk of reader) {
  const text = ...;
  stdoutBuf += text;
  lineBuffer += text;
  const parts = lineBuffer.split('\n');
  lineBuffer = parts.pop()!;
  for (const line of parts) { /* broadcast */ }
}

[backnotprop]

[P2] formatClaudeLogEvent is exported but never imported or called — live logs show raw JSONL instead of formatted text

formatClaudeLogEvent in packages/server/claude-review.ts was written to extract human-readable text from Claude's stream-json JSONL events (assistant messages, tool calls). However, it is never imported or called anywhere in the codebase — confirmed by grep showing exactly one occurrence (the definition itself).

The stdout drain in agent-jobs.ts broadcasts raw JSONL lines directly. Users watching a Claude review job's Logs tab see raw JSON like {"type":"assistant","message":{"content":[{"type":"text","text":"..."}],...}} instead of formatted output.

Fix: import formatClaudeLogEvent in agent-jobs.ts and use it to filter/format lines before broadcasting:

import { formatClaudeLogEvent } from "./claude-review";
// then in the drain loop:
const formatted = formatClaudeLogEvent(line);
if (formatted !== null) broadcast({ type: "job:log", jobId: id, delta: formatted + '\n' });

[Copilot]

Pull request overview

This PR expands the review experience by adding first-class AI “review agents” (Codex + Claude Code) with structured outputs and live log streaming, introduces default PR-local worktrees for agent file access without affecting the user’s checkout, and polishes the review UI (comments panel overhaul, headers, dock tabs, icons, and styling).

Changes:

• Add Codex/Claude review-agent integration with server-side command building, output parsing → external diff annotations, and live log streaming (job:log).
• Implement default PR-local worktree/sandbox creation (--no-local opt-out), plus shared git worktree primitives vendored to Pi.
• Overhaul PR comments UI (search, navigation, threads, diff hunk previews) and apply broad UI polish across panels/toolbars.

Reviewed changes

Copilot reviewed 45 out of 50 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
packages/ui/hooks/useAgentJobs.ts	Adds jobLogs accumulation from new job:log SSE events.
packages/ui/components/ToolbarButtons.tsx	Adds responsive “short label” support for toolbar buttons.
packages/ui/components/ReviewAgentsIcon.tsx	Introduces shared icon component for review agents tab.
packages/ui/components/ConfirmDialog.tsx	Adds wide layout option for dialogs.
packages/ui/components/AgentsTab.tsx	Refines agent job cards and launches server-built agent runs.
packages/shared/worktree.ts	Adds runtime-agnostic git worktree primitives (fetch/create/remove).
packages/shared/pr-provider.ts	Extends PR context with review threads + optional review URL.
packages/shared/pr-gitlab.ts	Stubs reviewThreads for GitLab (TODO parsing).
packages/shared/pr-github.ts	Fetches GitHub review threads via GraphQL and maps into shared types.
packages/shared/package.json	Exports new ./worktree entry.
packages/shared/agent-jobs.ts	Extends AgentJobInfo (cwd/prompt/summary) + adds job:log event.
packages/server/vcs.ts	Re-exports bun git runtime for shared worktree utilities.
packages/server/review.ts	Adds agentCwd sandboxing, agent command builders, ingestion → annotations, and cleanup hook.
packages/server/PR_LOCAL_WORKTREE.md	Design notes for PR local worktree behavior.
packages/server/git.ts	Exports bun runtime implementing ReviewGitRuntime.
packages/server/external-annotations.ts	Adds direct addAnnotations() helper (bypassing HTTP) with validation reuse.
packages/server/codex-review.ts	New Codex review agent module (prompt/command/schema/output parsing/transform).
packages/server/codex-review-schema.json	Adds on-disk schema file (also duplicated inline in code).
packages/server/claude-review.ts	New Claude Code review agent module (command builder + JSONL parser + log formatter).
packages/server/agent-jobs.ts	Server-side command building, stdin prompt support, stdout capture, and live log SSE deltas.
packages/server/AGENT_LIVE_LOGS.md	Design notes for job:log SSE live logs.
packages/review-editor/package.json	Updates @pierre/diffs dependency.
packages/review-editor/index.css	Dockview theme/header sizing polish + focus outline changes.
packages/review-editor/dock/ReviewStateContext.tsx	Adds platformUser to shared dock state.
packages/review-editor/dock/ReviewDockTabRenderer.tsx	Minor sizing tweak for tab close icon.
packages/review-editor/dock/panels/ReviewPRCommentsPanel.tsx	Passes platformUser through; adjusts overflow behavior.
packages/review-editor/dock/panels/ReviewAgentJobDetailPanel.tsx	Major redesign: findings/logs tabs, verdict, prompt disclosure, live logs, copy/export affordances.
packages/review-editor/dock/JobLogsContext.tsx	Adds separate context for high-frequency job logs.
packages/review-editor/components/ScrollFade.tsx	Adds scroll fade wrapper component for better overflow cues.
packages/review-editor/components/ReviewSidebar.tsx	Re-enables agents tab, UI tweaks, and shared icon import.
packages/review-editor/components/PRSummaryTab.tsx	Safer HTML rendering + broken image hiding; layout polish; memoization.
packages/review-editor/components/PRCommentsTab.tsx	Comments panel overhaul: search, keyboard nav, filters, threads + diff hunk previews.
packages/review-editor/components/PRChecksTab.tsx	Layout polish and clearer check link affordances.
packages/review-editor/components/LiveLogViewer.tsx	New reusable streaming log viewer with truncation and copy.
packages/review-editor/components/FileTreeNode.tsx	Adjusts file tree indentation/padding.
packages/review-editor/components/FileTree.tsx	Combines selectors, aligns header height, updates footer copy-diff UI.
packages/review-editor/components/FileHeader.tsx	Aligns header height with shared panel header variable.
packages/review-editor/components/DiffHunkPreview.tsx	Adds inline diff hunk preview rendering via @pierre/diffs.
packages/review-editor/components/CopyButton.tsx	Adds inline/overlay variants + optional labels.
packages/review-editor/App.tsx	Wires job logs context, worktree badge/dialog, PR panel buttons, and short feedback labels.
package.json	Updates @pierre/diffs dependency.
import-octi/issue-reopened.svg	Adds SVG asset.
import-octi/issue-opened.svg	Adds SVG asset.
import-octi/issue-closed.svg	Adds SVG asset.
bun.lock	Locks updated dependencies/versions.
apps/review/package.json	Updates @pierre/diffs dependency.
apps/pi-extension/vendor.sh	Vendors new shared worktree.ts into Pi extension generated code.
apps/hook/server/index.ts	Implements default PR-local worktree/clone creation and passes agentCwd + cleanup into server.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

toRelativePath() assumes POSIX / separators when stripping cwd from absolute paths. On Windows (or when Codex returns backslashes), this will fail to relativize paths and annotations may not match diff file paths. Using path.relative(cwd, absolutePath) (and normalizing to /) is more robust across platforms and symlinks.

[Copilot]

The explicit process.on("exit") cleanup runs git worktree remove without setting cwd to the source repo. If the process cwd changes during runtime, cleanup may fail. Prefer reusing worktreeCleanup (which already supplies cwd) or pass { cwd: repoDir } to the spawn call.

Suggested change

	try { Bun.spawnSync(["git", "worktree", "remove", "--force", localPath]); } catch {}
	try { Bun.spawnSync(["git", "worktree", "remove", "--force", localPath], { cwd: repoDir }); } catch {}

[Copilot]

jobOutputPaths stores ${id}:cwd only when an explicit spawnOptions.cwd override is provided, but spawnCwd can also come from the default getCwd(). This makes the cwd metadata used in onJobComplete inconsistent. Consider storing spawnCwd for every job (e.g., always set ${id}:cwd or pass entry.info.cwd).

Suggested change

	if (spawnOptions?.cwd) jobOutputPaths.set(`${id}:cwd`, spawnOptions.cwd);
	jobOutputPaths.set(`${id}:cwd`, spawnCwd);

[Copilot]

Same-repo detection compares only org/repo (parseRemoteUrl) and ignores the remote host. On GitHub Enterprise / self-hosted GitLab, this can incorrectly classify a PR as “same repo” and attempt to fetch from the wrong origin. Consider parsing/comparing the host too (e.g., ensure it matches prMetadata.host).

Suggested change

	let isSameRepo = false;
	try {
	const remoteResult = await gitRuntime.runGit(["remote", "get-url", "origin"]);
	if (remoteResult.exitCode === 0) {
	const currentRepo = parseRemoteUrl(remoteResult.stdout.trim());
	const prRepo = prMetadata.platform === "github"
	? `${prMetadata.owner}/${prMetadata.repo}`
	: prMetadata.projectPath;
	isSameRepo = !!currentRepo && currentRepo.toLowerCase() === prRepo.toLowerCase();
	const getRemoteHost = (remoteUrl: string): string | null => {
	const trimmed = remoteUrl.trim();
	if (!trimmed) return null;
	// SCP-like SSH syntax: git@host:owner/repo.git
	const scpLikeMatch = trimmed.match(/^[^@]+@([^:]+):.+$/);
	if (scpLikeMatch?.[1]) {
	return scpLikeMatch[1].toLowerCase();
	}
	try {
	return new URL(trimmed).host.toLowerCase();
	} catch {
	return null;
	}
	};
	let isSameRepo = false;
	try {
	const remoteResult = await gitRuntime.runGit(["remote", "get-url", "origin"]);
	if (remoteResult.exitCode === 0) {
	const remoteUrl = remoteResult.stdout.trim();
	const currentRepo = parseRemoteUrl(remoteUrl);
	const currentHost = getRemoteHost(remoteUrl);
	const prRepo = prMetadata.platform === "github"
	? `${prMetadata.owner}/${prMetadata.repo}`
	: prMetadata.projectPath;
	const prHost = typeof prMetadata.host === "string" ? prMetadata.host.toLowerCase() : null;
	const repoMatches = !!currentRepo && currentRepo.toLowerCase() === prRepo.toLowerCase();
	const hostMatches = !prHost || (!!currentHost && currentHost === prHost);
	isSameRepo = repoMatches && hostMatches;

[Copilot]

This doc still describes --local as opt-in, but the CLI logic now makes local checkout the default for PR/MR reviews and introduces --no-local to opt out. Updating the wording and examples here will prevent confusion.

[Copilot]

The link action label is hardcoded as “View on GitHub”, but PR context can also come from GitLab. This will be misleading for GitLab reviews. Consider deriving the label from the PR platform or using a neutral label like “View on platform”.

Suggested change

	View on GitHub
	View on platform

[Copilot]

This module writes a persistent debug log to ~/.plannotator/codex-review-debug.log on every run (and later logs raw outputs). That can silently persist sensitive repo/PR content on disk and adds ongoing I/O. Consider gating debug logging behind an explicit env/config flag and avoid logging full raw outputs by default.

[Copilot]

job:log deltas are appended into jobLogs but there’s no cleanup path (e.g., on terminal completion, jobs:cleared, or when a job disappears from a future snapshot). Over time this can grow without bound. Consider deleting/clearing per-job log entries when jobs finish or are cleared, and/or trimming here.