User runs /plannotator-review command
↓
Claude Code: plannotator review subcommand runs
OpenCode: event handler intercepts command
↓
VCS provider captures local changes (Git, GitButler, JJ, or P4 where supported). When review runs from a
non-VCS parent that contains nested Git/JJ/GitButler repos, child diffs are combined with
folder-prefixed paths.
↓
Review server starts, opens browser with diff viewer
↓
User annotates code, provides feedback
↓
Send Feedback → feedback sent to agent session
Approve → approved prompt sent to agent session (with the note/annotations when approving with notes)
Every git command the review servers parse goes through prepareGitCommand
(packages/shared/review-core.ts, both runtimes), which prepends
GIT_COLOR_FREE_ARGS: --no-pager plus -c color.<key>=never for ui,
diff, status, branch, grep, showBranch and interactive.
color.ui=never alone is not enough, because an explicit color.diff = always
in the user's config wins over it and colors a piped diff, which used to parse
to 0 files and 0 viewed-file identities. jj gets JJ_COLOR_FREE_ARGS
(--color=never --no-pager, packages/shared/jj-core.ts) in both runtimes'
runJj, gh pr diff gets --color=never, and agent jobs inherit the same git
settings as GIT_CONFIG_* variables (gitColorFreeEnvironment). As a backstop,
parseDiffToFiles strips ANSI codes from a patch whose diff --git headers are
colored (stripPatchColor, packages/core/diff-files.ts); a normal patch is
returned byte for byte. A new git/jj spawn that bypasses these runners must add
the same options. packages/server/review-git-color-config.test.ts runs both
servers against a sandboxed config that forces color on.
Both runtimes' agent-jobs.ts start a job's CLI (code review, Code Tour,
Guided Review) and a marker engine's model listing through planAgentJobSpawn
(packages/ai/providers/command-path.ts, vendored into Pi). On Windows, a CLI
found on PATH as a .cmd/.bat (Pi's ~\.pi\agent\bin\pi.cmd, npm's shims)
is resolved as Ask AI resolves it (resolveWindowsCommandShim). It is then
started as cmd.exe /d /s /c ""<script>" "<arg>" …" with
windowsVerbatimArguments. Node cannot spawn it by its bare name: that failed
with spawn pi ENOENT. A prompt cannot cross cmd.exe (line breaks, quotes,
%), so the engine's promptOnStdin (Pi only: pi … -p reads the prompt from
piped stdin) moves it to stdin. When an argument still holds a character that
cmd.exe reads (", %, !, ^, control characters), both servers fail the
job and name the script; nothing is started. Stop (and the model listing's 5 s
limit) ends such a job's whole tree with taskkill /t /f
(killWindowsProcessTree), not cmd.exe alone. A job's stdin pipe has an error
listener, so a child that exits before reading its prompt cannot crash the
host. An .exe, a program not on PATH, and other platforms keep the command
as built. Tests: planAgentJobSpawn in packages/ai/ai.test.ts, and Pi's
argv in packages/server/marker-review.test.ts (both simulate win32);
agent-jobs-windows-cmd-shim.test.ts (in packages/server/ and
apps/pi-extension/server/) runs a stub pi.cmd (tests/helpers/fake-pi-cmd.ts)
through each server's real spawn path, on Windows only: the Windows workflow's
pi-extension-ai-runtime-windows job.
plannotator review [DIRECTORY | PR_URL] (and /plannotator-review on OpenCode
and Pi) accepts one local repository/worktree or multi-repo workspace directory.
The shared parseReviewArgs + resolveReviewTarget resolve it against the
invoking terminal/session cwd, validate it before discovery, and reject multiple
targets or a directory combined with --patch-file. A sole word is the target:
when it names no folder, or a file, every host refuses it (CLI exit 1, OpenCode
log and toast, Pi notify) and nothing opens, as annotate refuses a target that
names nothing. The message names the word and the directory it was resolved
against, then the commands to run: a close existing folder ("Did you mean …?",
each missing path segment matched against its parent's folders), --diff-type
for a diff mode's name, the PR URL form for a number, and plannotator review
for the current project. Two sole words stay prose: a quoted sentence (a word
with whitespace that is not path-shaped) and a bare word beside --patch-file.
Prose of several words stays tolerated (#1483): a path-shaped word naming a
folder is the target, every other word (including a missing or file path-shaped
word) is ignored with a notice and the invoking cwd is reviewed. A folder that
exists but holds no repository fails in VCS discovery. Hosts pass the resolved cwd
through existing VCS/workspace discovery and project detection; never use
process.chdir() in a plugin host. Explicit targets inside a repository normalize
to its detected VCS root. A named directory also removes GIT_DIR and its kin
(GIT_REPO_ENV, @plannotator/shared/child-env) from the CLI's env, so a value
the calling shell exported (a git hook, a script) cannot point the session's git
at another repository; with no directory named they still decide (Pi's
/plannotator-review runs in Pi's own process and does not change its env).
OpenCode uses the internal opencode-review-directory
command for these targets so an older CLI rejects them rather than silently
reviewing the caller's repo; ordinary reviews keep opencode-review.
Feedback still goes to the invoking agent
session, with withReviewDirectory naming the active directory at submission when feedback has content
(a bare approval stays bare). File operations, AI jobs and persistence continue
using the resulting gitContext.cwd / workspace root.
The agent-destination review header uses the same adaptive split control the annotate surfaces
adopted: a ghost-X Close plus DecisionControl (packages/ui/components/DecisionControl.tsx)
rendered from the pure buildDecisionSpec mapping — Approve with no annotations,
Send Feedback otherwise, with Request changes… / Send with a note… and the explicit
Approve, discard n annotations… confirm behind the caret. One submitPrimaryDecision()
callback serves the header primary, the global Mod+Enter handler, and the compact primary row.
Transport routing is pure in packages/review-editor/reviewDecision.ts and single-endpoint:
every decision POSTs /api/feedback with approved as the only fork; a change-request note
becomes a scope:'general' CodeAnnotation (sentinel filePath ''/0/0, riding the export's
## Global comments section, which the export writes before the per-file sections) with a one-render deferred submit — zero server change. Approve-carrying
menu items (Approve with notes, Approve with a note…) are capability-gated on the
server-sent approvalNotesSupported advert, which rides every diff payload (/api/diff,
/api/diff/switch, /api/pr-diff-scope, /api/pr-switch, both runtimes) and reads as false
when absent, so an old server renders no approve-carrying items. For the OpenCode CLI bridge
the advert additionally requires the plugin's own supportsApprovalNotes: true declaration on
the opencode-review stdin JSON (the binary and plugin version independently; an old plugin
omits it and the advert fails closed, so a new binary can never hand an old bridge a note it
would discard). A capable session's approvals post buildReviewApprovalBody: bare approve
sends feedback: '' (the old 'LGTM - no changes requested.' placeholder is gone — a bare
approval now archives as lgtm with no sidecar), "Approve with a note…" sends the note as the
feedback, and "Approve with notes" sends the live annotations plus their export (a note, if
both are ever present, is folded in ahead of the export — never dropped). The four agent-facing
decision consumers (Claude Code CLI, OpenCode native + CLI bridge, Pi) emit approvals through
the shared composeReviewApprovedMessage (packages/shared/prompts.ts, vendored to Pi):
a bare approval is the plain approved prompt; an approval carrying feedback uses the
approved-with-notes framing (prompts.review.approvedWithNotes, default
DEFAULT_REVIEW_APPROVED_WITH_NOTES_PROMPT — "non-blocking guidance, do not revise or
reopen"), because the bare prompt plus a change-request-shaped export would read as a
contradiction. The legacy placeholder is filtered there so a stale built client cannot get
filler framed as guidance. The standalone dev server (apps/review/server) is the exception:
it emits the raw decision JSON with the feedback unfiltered and does not route through the
composer. Compact/touch rows are generated from the same spec, so a visible positive decision
exists in every state; composer rows open DecisionNoteDialog. Platform (PR) mode renders the
same ghost-X + DecisionControl shape from buildDecisionSpec's platform arm, with no
composer items ever: every menu action opens the existing ReviewSubmissionDialog (per-target
state, retry, "leave PR open" toggle — whose general-comment textarea is the only note field on
that side), and the self-approval mute is preserved on GitHub only (selfReviewBlocked) — muted
primary/items with the "You can't approve your own PR" reason. GitLab and Bitbucket leave Approve
live on your own PR/MR and let the forge decide: GitLab accepts an author's approval unless the
project forbids it, and then answers 401; submitGlMRReview turns that into "GitLab refused the
approval (<GitLab's message>) …". A refused decision with nothing else posted is thrown (like
Bitbucket), so the dialog shows it as a plain failure and the review stays open with no retry
locked to Approve; after comments landed it is a partial whose retry is the decision alone.
Request changes is a real review event (#1611). PRReviewAction (packages/shared/pr-types.ts)
is 'approve' | 'comment' | 'request_changes', carried end to end: resolvePlatformDecisionAction
returns { action, chooseEvent }; Post comments, then… opens the dialog with a Comment /
Request changes choice (Comment selected) and the empty-state Request changes… preselects
Request changes, while the primary Post Comments keeps the plain comment flow with no choice.
POST /api/pr-action validates action with parsePRReviewAction in BOTH runtimes (anything
else is 400, never a silent COMMENT), and submitGhPRReview maps it to REQUEST_CHANGES on the
single create-review call AND on the pending-review → /events submit path (#1600), with the
same See inline comments. placeholder COMMENT gets when the body is empty (GitHub requires a
body on both). A comment on a whole file goes on GitLab as its own file discussion (position_type: "file", postGlFileThreads in packages/shared/pr-gitlab-file-threads.ts) before the note; one GitLab refuses (an older GitLab, a renamed file) rides the note as **path:** text, as on GitHub, and once a file thread went, a note that fails is a partial whose retry.body carries it. GitLab posts the note and discussions first, then in one GraphQL request appends you as a reviewer (mergeRequestSetReviewers, APPEND) and sets the reviewer state with
the mergeRequestRequestChanges GraphQL mutation (a failure there is a partial whose retry is
request_changes alone). GitLab before 18.9 has no mergeRequestRequestChanges and rejects the
whole request with an undefinedField error on it, so nothing changes there: the review stays the
plain comment it already posted and the result carries postedAs: "comment", which the review
app's agent status line and the Inbox's posted words follow ("Review posted on GitLab"). Any other
error is still a failure. A platform without a request-changes decision sets
requestChangesSupported: false on the spec's platform input. The menu subtitles then say it
posts as a comment, and the dialog's Request changes option is disabled with that reason. GitHub
refuses REQUEST_CHANGES on your own PR like APPROVE, so with requestChangesSupported: true and
selfAuthored the empty-state Request changes… mutes with its own reason and a live
Comment… row (note-with-feedback, compact id comment) keeps the state from being a dead
end; Post comments, then… stays live with the dialog option disabled. The spec field is
optional and absent keeps the pre-#1611 copy for hosts. In a stacked multi-PR submission every
target posts the same event; the choice locks once any target may have been posted
(success/partial/blocked) so retries and the tab-scoped recovery (which stores action) keep
that event, while after a plain failure (nothing posted) it can still change. A refusal GitHub
answers anyway surfaces its own reason through the #1600 githubErrorDetail path.
PR platforms are providers (#1583). GitHub, GitLab and Bitbucket Cloud each implement one
PRProvider (packages/shared/pr-provider.ts: checkAuth, getUser, fetchPR, fetchContext,
fetchFileContent, fetchFileBytes, submitReview, plus optional fetchViewedFiles /
markFilesViewed / fetchStack / fetchList); the dispatch functions look the provider up by
PRRef.platform, and an absent optional method is the neutral answer (no viewed state, no stack,
empty PR list). GitLab's stack walk and MR switcher list are in packages/shared/pr-gitlab-stack.ts
(merge_requests?source_branch= up, target_branch= down; an opened MR before a merged one, closed skipped),
and the switcher and stack label number layers with the platform's prefix (!12). What the UI shows comes from getPRPlatformCapabilities (packages/shared/pr-types.ts,
browser-safe): requestChanges, selfReviewBlocked, fileLevelComments, viewedSync, artifacts,
reviewBodyRequired, agentCliAccess, labels and the CLI. Pure helpers replace the old
platform === "github" ? number : iid ternaries: getPRNumber, getDisplayRepo, getPRHeadFetchSpec
(where a local checkout fetches the head: refs/pull/N/head, refs/merge-requests/N/head, or
Bitbucket's source branch, from the fork URL when sourceRepo is set) and getPRCloneCommand.
GitHub/GitLab outputs of all of these are pinned byte-for-byte (pr-platforms.test.ts, including the
draft target keys). Bitbucket specifics: REST API 2.0 over fetch (packages/shared/pr-bitbucket.ts,
vendored to Pi), credentials per the PLANNOTATOR_BITBUCKET_* rows above or the config-only bitbucketTokenCommand (environment.md); the PR object's 12-char
hashes are resolved to full SHAs and the merge base comes from /merge-base (the PR diff is
three-dot); existing inline threads get a GitHub-shaped diffHunk cut from the PR diff (bitbucketDiffHunk), since Bitbucket comments carry none; a review posts each line comment as an inline comment
(inline: { path, to | from, start_to | start_from }), THEN the body as one general comment (the
Activity feed lists newest first, so this puts the summary above the inline comments, #1583), then
POST /approve or POST /request-changes (so requestChangesSupported is true, and an author may approve their own PR,
so nothing is muted); it follows GitLab's partial contract, with retry.action naming the failed
decision (request_changes included) and retry.body carrying the general comment when that is the
part that failed after inline comments landed (buildPRActionRequest resends exactly it). File-level comments fold into the body, there is no viewed sync
and no stack discovery, the PR Artifacts panel is hidden (artifacts: false), and agent review, Code Tour and
Guided Review prompts carry the diff inline when no local checkout is ready (agentCliAccess: false: no CLI a job may run can read the PR). The portable
guide format names only github/gitlab, so a Bitbucket guide omits source.pr.platform. Recorded
(anonymized) API responses and a fake API server live in tests/test-fixtures/bitbucket/;
scripts/bitbucket-live-smoke.sh runs the real flow against a throwaway repo.
Which gh account a GitHub PR review runs as (#2157). gh can hold several accounts per host and
uses the active one. GitHub's checkAuth first asks only that gh is signed in (checkGhAuth:
gh auth status --active --hostname H; when that fails, an older gh or a broken active login, it
goes on as long as some account on the host is usable, because plain gh auth status exits 1 when
ANY account on the host is broken). Then ensureGhPRAccess (packages/shared/pr-github-account.ts,
vendored to Pi) checks, before the review opens, that the active account can read the PR
(gh api repos/O/R/pulls/N; when that is refused but the repository is readable, the number is
wrong and the fetch reports it as before; network and rate-limit failures give no verdict). Refused:
every other account gh auth status lists for the host (--json hosts from gh v2.81.0, else the
text with NO_COLOR=1 and ANSI stripped) is tried with its token (gh auth token --hostname H --user L,
gh v2.40.0+) as GH_TOKEN (GH_ENTERPRISE_TOKEN off github.com and *.ghe.com); the first that can read
it is used for THIS review only. gh auth switch is never run and gh's settings never change. None
can: the review does not open (the CLI exits 1, like other startup failures) and the error names the
active account, the accounts that can't see it, an account that reads the repo but not the PR ("the
PR number may be wrong"), the accounts with no verdict (broken login, no token, offline, rate limit:
"Couldn't check", with gh auth switch -u <that one>), else gh auth login / gh auth switch -u <user>, plus a note when GH_TOKEN is the active source. The choice is an in-memory override keyed
by host/owner/repo, and the token goes ONLY where that PR needs it: the dispatch functions in
pr-provider.ts run that repo's gh calls through ghScopedRuntime, which passes it as
CommandOptions.env (an optional argument both runtimes add to the process env for that one child),
so a /api/pr-switch to another repo runs as the active account; PR artifact downloads send it;
agent jobs get it from their launch PR (ghAccountEnvForPRUrl in both runtimes' agent-jobs.ts).
checkAuth answers PRAuthResult { notice, childEnv }: the Bun CLI prints the notice on stderr
("Using gh account X for this review: …") and adds childEnv to this PR's checkout steps only (the
clone, git fetches and worktree add of --local); it never goes in process.env, so the browser
opener, the update wrapper, Ask AI providers and other children never see it. Pi notifies it and runs
its checkout (clone, fork fetch, and every git step through reviewRuntimeWithEnv) with it; OpenCode
logs it. A token is never printed, logged or put in an error. Tests: pr-github-account.test.ts,
packages/server/pr-gh-account.test.ts, apps/pi-extension/server/pr-gh-account.test.ts and
apps/hook/server/review-gh-account-cli.test.ts (including --local, through a git wrapper that logs
which account's token each git call got), against a fake gh (tests/helpers/fake-gh.ts, which
asserts Bun.which("gh", { PATH }) finds it) first on the PATH the code under test STARTED with:
Bun.spawn without an explicit env looks a command up through the PATH the process started with, not
a later process.env.PATH, so a runtime test runs in a child process
(tests/helpers/gh-account-runtime-probe.ts).
Interaction-model changes worth knowing (F8 and siblings): the agent-mode Approve primary
follows the FeedbackButton responsive pattern and is icon-only below the lg breakpoint,
where the old ApproveButton showed a compact OK label — the title carries the accessible
name, and compact/touch rows keep full labels. Approving despite annotations is now two clicks
(caret → Approve, discard n annotations… → Discard & approve) instead of the old dimmed
one-click Approve with its warning dialog, and Mod+Enter never stacks with the removed
approve-warning dialog — an open confirm dialog owns Mod+Enter outright (the
data-plannotator-confirm-dialog sentinel guard in the app's keydown effect; without it one
keystroke over the discard confirm would post two contradictory decisions). Accepted edge: the
compact DecisionNoteDialog keeps its draft locally and discards it if the item behind it leaves
the live spec (the dialog closes), while the desktop popover composer keeps drafts keyed by item
id — an intentional asymmetry, not a bug.
The review sidebar carries the durable human producer for review-level comments:
"+ Global comment" renders in the Annotations tab's "Global comments" section header (even with zero
global comments) AND in the all-empty state, opening the shared DecisionNoteField in a small
anchored popover whose width clamps to the resizable panel (200-600px persisted) so it never
clips inside the sidebar's overflow-x: hidden scroll area. Composer state (open + draft) lives
in ReviewSidebar, shared by both placements: the draft survives a dismissal, a placement flip
(an external annotation arriving mid-sentence moves the button from the empty state to the
section header), and a tab switch; collapsing the sidebar discards it. The producer is
deliberately present in platform (PR) mode too — a session-level comment there rides the posted
review body through the pre-existing scope:'general' handling in buildFileScopedBody /
ReviewSubmissionDialog. Unlike the header composer's submit note (one-submit lifetime), a sidebar
general comment goes through addCodeAnnotationsWithHistory — undoable, draft-persisted,
deletable — and both producers share one shape factory, createGeneralReviewComment in
reviewDecision.ts: scope:'general', sentinel filePath ''/0/0, review-note- UUID id, and
deliberately no PR context, so the comment passes every PR scope predicate and survives an
in-place PR switch. Creating one raises totalAnnotationCount, which is what flips the header
control to Send Feedback — the control is state-driven, not wired to the button. The
feedback archive records each annotation's scope (additive scope?: string in
packages/shared/feedback-archive.ts's normalizer, vendored to Pi), so a review-level general
comment stays distinguishable from a line comment in index.jsonl.
The tab strip's right side (packages/review-editor/dock/ReviewDockRightActions.tsx, approval "diff-controls-headers") holds one Split / Unified button (@plannotator/ui/components/DiffLayoutToggle: the mark is the layout on screen, a click switches, the tooltip says both), the All files panel's collapse-all button, and the "Diff display" gear (components/DiffOptionsPopover.tsx, a wrapper of @plannotator/ui/components/DiffDisplayOptions): Wrap long lines, Line numbers, Backgrounds (and their strength), Change marks, Changed words, Tab size, Whole file and Hide whitespace, with no Split / Unified row. The popover lives in packages/ui so the Inbox draws the same one (without Whole file and Hide whitespace; docs/agent-guides/inbox-files-and-guides.md, "Diff controls") without loading review-editor. Every row writes the config store (plannotator-diff-* cookies and config.json diffOptions), so a choice holds in the Inbox too. Test: packages/review-editor/dock/ReviewDockRightActions.test.tsx.
The header's right cluster on desktop reads, left to right: Close · Approve | Split / Unified · Collapse all · gear | Annotations · Ask AI · Review Agents | ☰ (the owner's order). The diff controls are in the header only while a guided review is open: the guide hides the dock, and with it this strip, so it draws the same three there, in the Inbox's order (Collapse all only with more than one file), with a divider after them (packages/review-editor/components/guide/GuideDiffControls.tsx, portaled from GuideScreen into a slot App.tsx renders after Close and Approve while the guide is open). In the plain review they stay in the dock strip. Split / Unified writes the same diffStyle; Collapse all folds or opens the guide's file cards through the guide host's collapseAll and is not remembered. The tool icons open the sidebar, so they sit at the right between two dividers. Options (components/ReviewHeaderMenu.tsx) is the ☰ alone, with the tooltip and accessible name "Options" and no visible word. A compact touch layout keeps its own header: no diff controls in it, and Options keeps its word. Tests: packages/review-editor/components/guide/GuideDiffControls.test.tsx, packages/review-editor/components/ReviewHeaderMenu.test.tsx.
The default code-review diff is since-base — a composite of merge-base(base, HEAD) vs the working tree plus untracked files ("everything a PR would show if you committed and pushed now"). It can render as a three-section git status panel (Committed / Changes / Untracked) via SectionsPanel, with Tree / Git status / Commits as the text tabs at the top of the left panel (ReviewPanelHeader, see "The left panel's header" below). The Commits segment (local git and jj sessions; not GitButler, P4, workspace or PR mode) is a linear --first-parent history rail (CommitsPanel): clicking a commit opens its own diff (commit:<sha>, vs its first parent) as the all-files view headed by the commit message rendered as markdown. In a jj session the same rail and contract run over the jj family (listJjCommitHistory / getJjCommitDiffInfo in packages/shared/commit-history.ts, vendored to Pi): the rail is first_ancestors(@) ~ root() (jj >= 0.33), dropping @ when it is the usual blank working copy (empty, no description, exactly ONE parent: a blank merge jj new A B stays, since its first-parent diff is real), isHead marks @ (badge @, not HEAD), shortSha carries the short CHANGE id while sha stays the full commit id, and the divider is the jj compare target (resolveJjCommitRailBase: the session base, except an Evolution-diff base, which is not a line base, falls back to the context's line base; labeled by its bookmark). A click opens jj-commit:<commit id> — a separate family because providers claim diff types by prefix and git owns commit: (a pure jj repo has no git work tree), always addressed as commit_id(<id>) so a hex-named bookmark cannot shadow it — diffed --from <first parent> --to <id> (never jj diff -r, which compares a merge against all its parents), with hunk expansion, image previews, the fingerprint and the analysis snapshot going through the same per-VCS tables as every other jj type (resolveJjSideRevs, getJjSnapshotRevsets). jj REWRITES a mutable revision on every edit (the working copy on every snapshot) while the old id keeps resolving as a hidden commit, so the jj-commit fingerprint is visibility-aware (commit_id(X) & ::visible_heads(): visible / hidden / gone) — an opened @ goes "Diff out of date" on the next save — and both servers' /api/diff/switch pass jj types through canonicalizeJjCommitDiffType (packages/shared/jj-core.ts), which maps a hidden id to its change's single current version (change_id(<change>); divergent or abandoned changes stay put). Refresh therefore lands on the new @, and the client adopts the returned commit-family diffType even on an in-place (preserveFile) refresh. The feedback export labels a jj revision by its short change id (commitShortId from the commitInfo sidecar); git keeps the 7-char sha. Client code asks one question for both families: commitShaFromMode / isCommitDiffType (packages/review-editor/utils/), server code commitFamilyId (packages/shared/review-core.ts). The Commits view is a self-contained detour: entering it memoizes the previously active diff, exiting to Tree restores that diff verbatim (exiting to Git status resets to since-base as always), the memo clears whenever any non-commit diff is applied, and a reload that serves a commit-family diff with a non-Commits panel view snaps once to the session default so the commit diff cannot outlive the visit. The toggle never writes the persisted reviewPanelView/defaultDiffType pair (no server writes from a toggle click), but it does record a cookie-only last-used memo (reviewPanelViewLastUsed, sections | tree — never commits; the Commits view is session-only). A review OPENS on caller-pinned flags (plannotator review --base <ref> / --diff-type <id>, session-only: openStatePinned on /api/diff disables the panel-pair self-heal and never persists anything) ?? session choice ?? last-used memo ?? persisted reviewPanelView ?? the registry default, which is tree (cookie-only, written only by Settings through setReviewPanelView(), which also syncs the memo so an explicit choice is never shadowed by a stale one — except the App self-heal, which passes recordLastUsed: false to repair the diff half of a conflicted pair without touching the memo). There is no first-run chooser: a profile with no reviewPanelView cookie opens on Tree, which renders every diff type, and the Tree / Git status / Commits tabs plus Settings → Review are the two ways to change it. The persisted pair is coupled: the Sections view only renders since-base, so choosing a classic diff default snaps the persisted view to Tree and vice-versa (enforced in the Git section of Settings → Review and by the coupled setters in packages/ui/config/reviewView.ts); with tree as the default the pair is trivially consistent for a reviewer who has chosen neither, so the App self-heal only ever fires for a profile whose reviewPanelView cookie already reads sections — chosen in Settings, or seeded by a build whose registry default was still sections.
The left panel (approved design record "review-sidebar-aligned", .product/approved/review-sidebar-aligned/, not in this repo; the tabs and sentence from "review-sidebar-header", variant "sentence"). One layout for the three views, so nothing moves between them. Two left edges for the whole panel: containers (Go to file, the nav rows, the Changes pill, selected rows) start at 8 px, content (icons, chevrons, the first letter of a label) at 16 px, and labels at 34 px (nav labels, group heading labels, folder names). Rows are 28 px, groups 12 px apart, the tree indents 12 px a level. Selected and pressed states are a grey fill (--sidebar-fill* in .review-sidebar, index.css), never a coloured bar, border or glow. From the top:
- Header (
components/ReviewPanelHeader.tsx, fed oneReviewPanelHeaderModelbuilt in App): Go to file as a quiet field (GoToFileField: icon and words on the two edges, its keys as plain text, hidden under 210 px;aria-keyshortcuts"Meta+P" / "Control+P" throughariaKeyShortcut), then Tree / Git status / Commits as real tabs (ViewTabs:role="tablist""Panel view",role="tab"witharia-selectedandaria-controlsthe list, which isrole="tabpanel"labelled by the chosen tab throughreviewPanelBodyProps). The chosen tab is the one Tab stop; Left and Right move focus between the tabs, wrapping, and Enter or Space chooses (manual activation: a view switch can load a diff). The keys are the standard tabs pattern handled in the tablist's ownonKeyDown, not page shortcuts, so they are not in the shortcut registry (like the tree keys ofDiffFileTree). Each view is its own panel component, so a chosen tab is remembered (pendingTabFocus) and takes focus in the new panel's header. Under 200 px (NARROW_HEADER_WIDTH) the tabs are icons with the name in a tooltip andaria-label; a session with one view draws "Files". The tabs' track is the panel's one line. - The comparison as one sentence under the tabs: "All changes ⌄ since main ⌄". The first word opens the diff type menu (
DiffTypePickerwith a caller-drawntrigger), the base word the base picker (BaseBranchPicker, same seam);diffWordspicks the words (since-base and merge-base "since", jj-line "from"; without a base word the option's own label). In Git status the noun is fixed ("All changes": the view IS since-base) and only the base is a control; in Commits there is no sentence. A long base keeps its start and end (middleTruncateRef: "feature/very-l…ame-for-a-stack", sized from the panel width), the full name in the trigger's title and accessible name. The jj evolution picker and a worktree picker stay rows of their own under the header. - Nav rows (
PanelNavRows.tsx, in anav"Review views"): All changes, then PR overview, Artifacts, Semantic diff and Call flow when present; the open one isaria-currentwith the grey fill. - The sticky tools block (
PanelControlsRowinPanelChrome.tsx), which stays at the top of the list while the files scroll under it, with a hairline under it only while something is under it (data-stuck, from a sentinel and the scroller's scroll events). Its first row is Changes N / All files (ScopeSwitchinReviewPanelHeader.tsx, passed asscope; "Files" when the panel has none; All files keeps its count in its accessible name and tooltip, not on screen, and its live dot at its top corner, so from 256 px (TOOLS_ONE_ROW_WIDTH,oneRow) the pills and tools share one line in either scope; narrower, the tools always wrap under the pills, so switching scope never moves the list), then Search in diff and Collapse all folders as 24 px icons (Search in diff is a toggle: pressed while the search shows, and a second click closes it, clearing a typed query as the field's × does), then a "…" button ("List options", a Base UI menu,data-review-tree-settings) with Copy all diffs (stays open to show "Copied all diffs"), Auto-mark viewed, Group by kind, and "On each file": the Viewed button and the Git add button (turning the Viewed button off first turns Hide viewed off, so the list is never filtered with no way to see it). Its second row is the progress in words ("0 of 12 viewed · 1 staged", "All 12 viewed" in green when done; wraps between its parts in a narrow panel) with Hide viewed as an eye toggle (aria-pressed) at its end. While the pointer is in the panel, Hide viewed hides only what was already viewed when the pointer came in: a file that becomes viewed meanwhile (the one you just left, auto-marked) keeps its row until the pointer leaves, so the list never moves under the next click (useHiddenViewedFiles, #2713). A key press releases the hold (keyboard navigation does not aim at a row), and the pointer's next move takes it again; with Hide viewed off there is no hold. The scope pills ("All" under 200 px) hide while a diff search runs (the results come from the changes only). While All files is on, its listing's state is a dot at the pill's corner (green while live, an amber ring for a partial listing; decoration,aria-hidden, the age in its tooltip), a visible line "Part of the repository is listed (the platform stopped early)." for a partial listing, and a politerole="status"region ("All files is live: 1 added, 1 edited on disk since the diff.") that changes only when the listing turns live or the files changed on disk change, never on the 15 s age tick; the All files button's name stays "All files N". - Group headings (
PanelSectionHeaderinFileRowBits.tsx: the tree's Code / Tests / Generated, Git status's Committed / Changes / Untracked) are flush: the kind icon in the folder-chevron column, the label on the folder-name edge, heavier and darker than folders. The whole row is onebuttonwitharia-expanded, so Enter and Space fold it; a chevron after the label shows on a folded group always, on an open one on hover and keyboard focus (always on touch screens). A kind heading's spoken name says its numbers and what the group holds ("Code: 9 files, 0 viewed, 66 lines added, 9 removed. Everything that is not a test…"), and the same "what it holds" is its tooltip. - Numbers in two columns: every row's +/- (All changes, headings, folders, files) is a
CountColumnsgrid whose two column widths come from the panel's totals (countColumnVarssets--count-add-w/--count-del-won the list), so every + ends on one edge and every - on the next; an empty cell keeps its width. Headings and folders draw them in the tertiary grey, files in green and red; a kind heading adds viewed/total as a third column. Under 220 px (COMPACT_ROWS_WIDTH,data-compact-rows) headings, folders and files drop their numbers so names keep the room (All changes keeps its totals; a heading's spoken name keeps them). - Tree rows (
FileTreeNode.tsx): the Changes tree indents throughalignedTreeIndent(8 px + 12 px a level up tomaxTreeIndent(width), then 4 px a level: never 0, so a child never lines up with its parent's siblings; a deep name truncates instead); a row'stitleis its full path (a folder's without the kind scope,folderDisplayPath). All files (RepoFileTree) keeps the shareddiffFileTreeIndent; its "changed on disk" dot sits just left of the + column (.review-on-disk-dot, from the column widths), and revealing the active row keeps it clear of the sticky block. The Viewed and Git add controls get 24 px hit areas.
The diff types whose label read "All files" (git's all, "Every file (HEAD)"; jj's jj-all, "Every file"; the same words in the feedback export) were renamed so the sentence never reads "All files ⌄" over the All files scope. The guides.show viewer imports the review stylesheet through apps/guides-show/viewer/review-styles.css, which keeps the panel's components (ReviewPanelHeader, PanelChrome, PanelNavRows, FileTree, FileTreeNode, RepoFileTree, SectionsPanel, CommitsPanel) out of its Tailwind scan (@source not): the viewer never draws the panel, and their classes would otherwise change the viewer's CSS and so the pinned /v1/ file. Tests: DOM ReviewPanelHeader.test.tsx (tabs, arrow keys, focus kept across the remount, scope), PanelChrome.test.tsx (the "…" menu's settings, Hide viewed, the hairline), FileTree.fileKinds.test.tsx (headings, the number columns, the narrow panel), FileTreeNode.controls.test.tsx (the indent cap), and tests/e2e/review-sidebar.spec.ts in a real browser (arrow keys and Enter / Space on the tabs, Enter / Space on a heading, the sticky block while scrolling, the number edges); tests/e2e/review-file-list-stays-put.spec.ts (opening a folded file in All changes leaves every header in place; Hide viewed keeps the row you left while the pointer is in the list).
The list's first row, which opens every change in one view (the dock tab of the same name), is All changes (AllChangesRow in PanelNavRows.tsx; it was "All files", which clashed with the scope). Its +/- counts are derived from the live palette (utils/diffCountColors.ts, hooks/useDiffCountColors.ts): each keeps its OKLCH hue and chroma (within what sRGB can show) and moves only its lightness, lighter on a dark ground and darker on a light one, just far enough to read at 4.5:1 on the sidebar, the selected row and the hovered row; a palette token with no hue (a palette that draws deletions in its text colour) takes the usual green or red. The tokens are read with readThemeTokenValues (packages/ui/utils/themeTokens.ts, the reader readThemeTokens in mermaidTheme.ts now uses, split out so the review app can read tokens without importing anything that names a diagram runtime). diffCountColors.test.ts sweeps every palette in packages/ui/themes, light and dark: 4.5:1 on every surface, + green-ish and - red-ish (or the palette's own hue where it chose another, as colorblind does), and the two hues at least 60° apart. In a narrow panel the sticky tools row (PanelControlsRow) wraps its icons onto a second line instead of drawing them over the scope.
Staging display invariant: useGitAdd's stagedFiles is the EFFECTIVE staged set (sections-sidecar snapshot + session stage/unstage overrides) and is the only source any surface may render staging state from. The sidecar entry's staged flag is a snapshot — ORing it back in makes files unstaged mid-session render as staged (and inverts the next toggle).
since-base is only offered when the base ref actually resolves — on a repo whose trunk isn't discoverable (trunk, no origin/HEAD) getGitContext omits it and the default falls through to uncommitted, so committed branch work is never silently hidden. The since-base patch/sections/fingerprint/file-content paths all degrade to HEAD together when merge-base fails for a resolvable-but-unrelated base. There is no first-run review-setup dialog (ReviewSetupDialog was removed, as DiffTypeSetupDialog was before it): the panel view simply defaults to Tree and the panel toggle / Settings → Review change it. The one-time dialog chain is guide intro → look-and-feel → Edit Mode → token hover cards → the terminal-tools announcement → the Inbox announcement → "Ask this session" → the agent-tool offer; none of the dialogs stack, and no two announcements share a load. The token hover announcement is last and additionally skips a session where hover cards cannot run at all (no live workspace), WITHOUT consuming its cookie, and never shows to a reviewer whose trigger is already non-default (which after the boolean-to-trigger migration is exactly the early adopter who turned cards off). Analysis layers no longer add a startup dialog: Semantic Changes retains its enabled default, while Call Flow remains disabled until the user explicitly enables it in Settings, which is also consent for its managed runtime installation.
Saved default diff per VCS (Settings → Review). The Review tab (formerly Git) has a Git section and a Jujutsu section. Git keeps its original setting, diffOptions.defaultDiffType (cookie plannotator-default-diff-type, coupled to reviewPanelView as above), so settings saved by older versions need no rewrite. Jujutsu saves its own value in reviewDefaults.jj.defaultDiffType (config.json reviewDefaults, cookie plannotator-review-defaults; setProviderReviewDefaultDiffType / getProviderReviewDefaultDiffType in packages/ui/config/reviewView.ts), never coupled to the Git pair. resolveDefaultDiffTypeFor(config, vcsId) in packages/shared/config.ts (vendored to Pi) picks what a local review opens on: in jj, the saved jj mode, or jj-current when it is unset or not a jj mode; every other VCS reads resolveDefaultDiffType. A saved jj mode the change cannot offer (Evolution diff without history, Line of work without a resolvable base) opens on Current change. Opening on Evolution diff compares against the change's previous state (gitContext.jjEvologs[1]), as switching to it in the UI does, and the hosts forward that base to the server. The client's commit-exit fallback (savedDefaultDiffTypeFor in App.tsx) reads the same per-VCS value. The review --base / --diff-type flags stay Git-only.
A one-time panel announcing Plannotator's two terminal clients, Plannotator
TUI (plannotator/plannotator-tui) and Herdr Annotate
(plannotator/herdr-annotate). One cookie covers every surface —
plannotator-announce-tui-herdr-seen, value '1', read and written by
needsTerminalToolsAnnouncement() / markTerminalToolsAnnouncementSeen() in
packages/ui/utils/terminalToolsAnnouncement.ts — so dismissing it in plan
review retires it in annotate and code review too, and vice versa. It is a
plain storage key rather than a settings-registry entry for the same reason
lookAndFeelAnnouncement.ts is: configStore.ensureLoaded seeds every
registry default into a cookie on first access, so a registry-backed flag could
never tell "never seen" from "seeded default".
The component is packages/ui/components/TerminalToolsAnnouncementDialog.tsx
(shared shell: portal, z-[100], hand-rolled Escape + Tab wrap + focus
restore, data-terminal-tools-announcement-dialog). It is video first: the
real demo footage fills the top of the panel edge to edge, and the text under
it is one headline and one sentence, then one action row (star the two repos,
"Watch on X", "Got it"). There is no mock terminal, no install commands, no
feature list; the repo pages carry all of that. Two deliberate departures from
its siblings: the backdrop dismisses (the panel collects no decision, so there
is nothing to lose by closing it impatiently), and its keydown listener is
registered on the CAPTURE phase and swallows Mod+Enter, so a keystroke aimed
at the announcement cannot approve a plan or post a review behind it.
Media is hosted, not bundled. The two demos (tui-herdr-full-demo and
tui-herdr-lite-demo, mp4 + webm + poster jpg each, ~23MB together) are served from
https://plannotator.ai/assets/ (the videos are uploaded there by hand, see
Marketing Site videos; the posters ship from
apps/marketing/public/assets/), the same
precedent as GuideIntroDialog's hero image (the Edit Mode recording is small
enough to inline; these are not). The <video> is muted playsInline loop
with preload="auto", mp4 first in source order, and autoPlay unless
prefers-reduced-motion matches, in which case the poster waits behind a
play button. A Full | Lite segmented switch (role="tablist") swaps the
footage and the "Watch on X" link together; the panel is keyed per demo so
playback and load-failure state reset with it. If neither source can load
(offline), the frame keeps its place and shows a "Watch on X" link over it.
The panel's width follows the viewport HEIGHT as well as its width
(min(1120px, 100%, (100dvh - 14rem) * 1280/806)) so the video never
scrolls out of view on a short window. No CSP is involved: the app HTML ships
no Content-Security-Policy, and the servers only set one on sandboxed
artifact responses.
Ordering: LAST in each app's chain, never first. Code review gates it
through terminalToolsAnnouncementCanShow on guide intro, look-and-feel, Edit
Mode and token hover cards; the plan editor gates it on the
look-and-feel chooser, goal setup and permission-mode setup. The destination
spotlight and the auto-viewed toast were extended to defer behind it too, so
nothing stacks. Last rather than first because none of those dialogs consumes
this cookie: a session busy asking setup questions defers the announcement to
the next load instead of burning it, and that also puts it in front of the right
reader — someone opening Plannotator for the first time is still learning this
app, while the people who should hear that it now runs in a terminal are the
ones who already answered every setup question and see it on their next load.
Suppressed, never consumed, on: archive browsing and read-only shared plans
(which is also what the share portal serves, via isSharedSession), the
compact touch shell, and while the initial payload is still loading. The
guides.show portable viewer never mounts either App, so it is unaffected by
construction. @plannotator/ui exposes no first-run-suppression seam on
configurePlannotatorUI; a host that wants the announcement off installs its
own storageBackend (the documented escape hatch) and pre-seeds the key.
A one-time panel for 0.28.0's integrated sessions: Ask AI answered by the agent session that opened
Plannotator, and reviews that no longer hold that session. Same shape as the terminal-tools
announcement above: packages/ui/components/AskSessionAnnouncementDialog.tsx (portal, z-[100],
Escape / Tab wrap / focus restore, backdrop dismiss, capture-phase keydown that swallows
Mod+Enter, data-ask-session-announcement-dialog) and packages/ui/utils/askSessionAnnouncement.ts
(one plain cookie, plannotator-announce-ask-session-seen = '1', shared by every surface; not a
settings-registry entry, for the same seeding reason).
Who sees it: only a plan review, annotate or code review session that is actually connected
right now: /api/ai/capabilities lists the session-bridge provider for claude-code, pi or
opencode and its status is not gone (connectedAskSessionAgent), and Ask AI is reachable on
the surface (the plan editor's canUseAI and not taken over by the annotate agent terminal; code
review's AI button). Everything else defers WITHOUT writing the cookie, so the reader sees it in a
session where it is true: no bridge (remote, a --tailscale tab of anyone but the machine's owner, Windows, the mod off, -p, Pi's
event-API path, OpenCode 1, an older CLI), a gone session, other origins, PLANNOTATOR_AI=disabled,
archive / shared / no-server sessions, the compact touch shell and the initial load. The headline
names the connected host and the footer always says "This session is connected"; there is no
setup variant. OpenCode's copy says "code review and annotate no longer hold the session" because
its plan review still does.
Timing: useFirstRunAnnouncementWindow (packages/ui/hooks/) lets it open only before the
reader's first pointer press, key press or focus into a text field, within 4 s of the initial load,
and never while a text field (a comment composer) or an iframe has focus. Work inside the raw-HTML
and live-app iframes never reaches the parent's listeners, so a window blur after the first
second (the viewer's own startup may focus its iframe) also closes the window. Capabilities can answer late (model
discovery), and a dialog that opened then would take focus mid-comment and be dismissed unread by
the next Space or Enter; instead it misses the load, cookie unwritten. Once open it stays until
dismissed.
Ordering: after the terminal-tools announcement and never on the same load
(askSessionAnnouncementPendingThisLoad is false while that cookie is unset), so a fresh browser
sees terminal tools first and this one on the next load; behind every chain dialog in both apps
(the permission-mode setup included). Code review's destination spotlight, auto-viewed toast and
history-shortcut guard defer behind it like they do behind terminal tools.
Media: real footage, hosted like the terminal-tools demos:
https://plannotator.ai/assets/ask-this-session-demo.{mp4,webm} + ask-this-session-poster.jpg
(1280x800, ~35 s). Recorded from a real Claude Code 2.1.289 session (real plugin and mod, real
compiled CLI, real review app) whose model calls went to a scripted local stand-in for the
Messages API, so the question, the Read tool call and the streamed answer are real traffic with
scripted model text. Offline it says the video could not load; reduced motion waits on the poster.
A one-time, nearly full-screen panel for the Plannotator Inbox on plan review, annotate and code
review (the editor app shows it in both of its modes, as every announcement does):
packages/ui/components/InboxAnnouncementDialog.tsx and packages/ui/utils/inboxAnnouncement.ts
(one plain cookie, plannotator-announce-inbox-seen = '1', shared by every surface; not a
settings-registry entry, for the same seeding reason). The Inbox film fills the top; under it the
title "The Plannotator Inbox", one sentence, Close (initial focus) and Learn about the
Inbox, a link to https://plannotator.ai/inbox in a new tab. Close, Escape, the backdrop and the
link all write the cookie (the link closes the panel on the next task, so the browser still follows
it). Unlike the other announcements it is built on the shared dialog (components/ui/dialog, Base
UI: modal, focus trapped and restored), with the same capture-phase keydown that swallows
Mod+Enter and keeps Escape from the App's own handlers (data-inbox-announcement-dialog).
Media: the marketing page's own film, https://plannotator.ai/assets/inbox-film.mp4
(1920x1080, ~14 MB, voice-led) and inbox-film-poster.jpg (~120 KB), from
https://plannotator.ai/assets/ like the other announcements' footage (no CSP is involved; see
the terminal-tools section). It never autoplays and is preload="none", so opening the panel loads
only the poster; until it plays the frame is the poster with one play button, as on the Inbox page,
then the native controls take over. A film that cannot load says so in the frame; the rest of the
panel is unchanged.
Who sees it: deferred WITHOUT writing the cookie in archive / shared / no-server sessions, in
the VS Code extension's webview (window.__PLANNOTATOR_VSCODE, isVSCodeWebview), while loading,
and behind every other first-run dialog. It is NOT deferred on the compact touch shell: the panel is
a film and one link, and the Inbox is read on a phone too. The Inbox's own window never mounts
either App. Timing is useFirstRunAnnouncementWindow, as for "Ask this session".
Ordering: after the terminal-tools announcement, never on the same load (that one takes the
load while it is pending and can show on this surface, i.e. not on the compact shell, or was shown
this load), and before "Ask this session" and the agent-tool offer, which wait while this one takes
the load (inboxTakesThisLoad: shown this load, or eligible now). Code review's destination
spotlight, auto-viewed toast, history-shortcut guard and the update toast defer behind it. App
tests that seed plannotator-announce-tui-herdr-seen to clear the chain seed this key too.
The plannotator agent tool (off by default on Pi and OpenCode 2, on for the Claude Code mod and in Oh My Pi)
has a switch in Settings → General on plan review, annotate and code review, and a one-time
offer on Pi and OpenCode 2. Both read parseAgentToolSetting(serverConfig)
(packages/ui/utils/agentToolSetting.ts): present only when the server reports
agentToolHost and agentToolEnabled (the integration that launched the server has the tool),
so OpenCode 1, Codex, the classic hook and @plannotator/ui hosts (which pass neither
agentToolSetting nor onAgentToolChange to Settings) get nothing. An OpenCode bridge
alone is not enough: the plugin also reports that its host can register the tool (a
tool.transform domain) as PLANNOTATOR_OPENCODE_TOOL_CAPABLE=1 on the CLI it launches and
opencodeToolCapable on its in-process plan server (agentToolHostForServer in
packages/server/ai-runtime.ts), so an OpenCode host without the domain, or an older plugin,
gets no switch and no offer. The row says when a change applies: the next Pi session, the next
time Claude Code / OpenCode / Oh My Pi starts (the mod and the OpenCode plugin decide once per
process; OMP may keep the extension loaded across its sessions), and what it costs per host
(agentToolCostNote: Pi and OpenCode about 800 tokens per request, Oh My Pi one short line).
Writes go through
saveAgentToolSetting (POST /api/config { agentTool }, awaited, not the settings registry's
debounced best-effort write-back); the handlers answer 500 when the value did not reach
config.json (agentToolSaveFailed), and both surfaces show that. The row is locked with a note
when agentToolEnv is set. One useAgentToolSetting per App feeds both, so a change in one
shows in the other.
The offer (AgentToolAnnouncementDialog, packages/ui/utils/agentToolAnnouncement.ts, cookie
plannotator-announce-agent-tool-seen, a plain storage key for the registry-seeding reason)
follows the announcement shell (portal, z-[100], Escape / Tab wrap / focus restore, backdrop
dismiss, capture-phase Mod+Enter swallow) but collects a decision. Approved design ("Loop";
design record, not in this repo): a theme-token SVG of the round trip over the question
"Do you use Plannotator as a skill?", two example requests, one line of why, the token cost,
and the buttons "No, I’ll just use slash commands" (initial focus) and "Yes, turn it on". The
copy is the approved design's; agree a change with the maintainer before editing it. The
dialog cannot close while a save is in flight, a failure shows the reason with "Try again",
success says when it starts and offers Done. Declining, Escape, the backdrop and a successful
save write the cookie; a failed
save does not. It shows only for a Pi / OpenCode 2 host (never Oh My Pi, where the tool is on by default) whose next-session value is off, never
chosen in config.json (agentToolConfigured), and not set by the env. Ordering: LAST in each
app's chain, after terminal tools (latched, agentToolAnnouncementPendingThisLoad) and after
"Ask this session" per load (earlierAnnouncementMayShow: that one was shown this load, or is
pending and its capabilities answer is outstanding or eligible), so never two announcements on
one load, while a reader who is never connected still gets the offer. Same deferrals as the
others (archive, shared, no server, compact, loading) and the same
useFirstRunAnnouncementWindow. Code review's destination spotlight, auto-viewed toast and
history-shortcut guard defer behind it.
Code-review drafts (/api/draft) keep the patch-key lookup (contentHash(rawPatch)) and also store the draft under a stable review target, so unsent comments survive a changed diff. PR mode: prDraftTargetKey(meta, scope) = pr- + hash of platform + host + repo (owner/repo or GitLab projectPath, lower-cased) + PR number + diff scope (layer / full-stack are different patches). Local Git (#1645): localGitDraftTargetKey = local- + hash of localGitReviewIdentity (packages/shared/review-progress.ts, shared with viewed progress but independent of its setting): canonical worktree root + branch (detached HEAD: the commit) + diff type + base (base-relative modes only). Local patch keys are scoped by the target too (localReviewDraftKeys), so an identical patch on another branch or worktree never shares comments or tombstones. Older unscoped drafts are still read on an exact patch (legacyPatchKey) and migrate on the next save. Workspace, jj/GitButler/P4 and piped-patch reviews have no target and keep patch-only drafts. All of it lives in packages/shared/review-draft.ts (vendored to Pi); both review servers hold one createReviewDraftSession() and route /api/draft, /api/feedback and /api/exit through it (without a target key every call is the plain draft.ts call, including the historical always-ok save response).
Local target capture. The identity is read once per displayed snapshot (at startup, on /api/diff/switch, on the automatic origin/<default> upgrade), never on a draft write, so a later checkout in the terminal cannot redirect writes. The startup read is awaited before the server listens: its git calls (rev-parse --show-toplevel, symbolic-ref HEAD, rev-parse HEAD) run in one parallel round, each killed after LOCAL_DRAFT_TARGET_TIMEOUT_MS (2s); a failure or timeout gives no target, which is patch-only drafts as before. An unpinned default base with automatic remote checks on keys on the locally discovered origin/<default> from the first snapshot, so the async startup upgrade does not strand an early draft; explicit bases and remote-check opt-outs keep their exact ref. /api/diff and /api/diff/switch advertise localDraftTarget (the switch also carries draftState). The client stamps localReviewTarget on comments and uses the PR anchor/Outdated machinery below. Its transport (utils/localReviewDraft.ts) sends ?target=; both servers answer a request for a target that is no longer on screen with 409 { code: "draft_target_changed" } (distinct from generation conflicts), and the hook then pauses saving and shows a notice with Refresh review (comments stay in memory). Pending saves flush best-effort before a local diff switch. The sidebar keeps the page's comments across switches; inline rendering and stored drafts stay per target. A save writes edits to earlier targets' comments back to those targets (keeping each one's viewed fields). This cross-target bookkeeping (write-back, Clear all, decision cleanup) is scoped by the page's ephemeral ?client= id, so a reload or second tab never treats missing comments as deletions; a local caller without that id touches only the active target.
- Load tries the patch key first and returns it unless the target copy is strictly newer by
draftGeneration. The target copy is stamped server-side with thepatchKeyit was saved on pluspatchKeys(every patch it was ever saved on); when served for a different patch the response carriespatchChanged: true. Clients can forge none of these fields and never see the lists. - Delete clears the patch key, the target key, and every remembered patch key, with or without a generation. A decision (
/api/feedback,/api/exit) additionally clears every target the session saved to or restored from (an in-place/api/pr-switch,/api/pr-diff-scopeor local/api/diff/switchmoves the target, and a submit must not leave the earlier one behind). A clientDELETE(clear-all, dismiss) touches only the target on screen in PR mode; local Git also clears the targets this page load saved, because Clear all empties the page's whole list. - Tombstones: the target key's tombstone guards the whole logical draft — a save at or below it is rejected under BOTH keys (PR mode answers
409 { ok: false, found, draftGeneration }instead of swallowing it), and a patch-key copy at or below it is not served. - In-place switches:
/api/pr-switchand/api/pr-diff-scoperesponses carrydraftState: { found, draftGeneration }for the new keys. The client'sadoptDraftTargetraises its generation to that floor (otherwise every save after switching onto a previously submitted target would be refused). When the target holds a draft, the hook loads it and AUTO-MERGES its items into the session throughonDraftTargetMerge(skipping ids the session already holds or deleted this session; the app re-checks their anchors and shows a small non-blocking toast), then autosave saves the merge normally — no banner after a switch. The only wait: while that read is in flight, autosave skips writing under the new target (it would overwrite a draft it has not read). Each read is two attempts, each bounded byTARGET_LOAD_TIMEOUT_MS(5s), so a hungGET /api/draftfails instead of pausing autosave. If both attempts fail, the target counts as unreadable: autosave still never writes over it, and instead retries the read on each later save attempt, saving normally once a read succeeds. The next switch (or unmount) supersedes all of this, so nothing can stick. A per-switch counter makes a stale load from an earlier target a no-op. The page-load restore banner is unchanged.
Client side (packages/review-editor, packages/ui/utils/codeAnnotationAnchor.ts): in PR and local Git modes withPRContext records on each line comment anchorText (the anchored lines), anchorContext (two lines before and after on the same side plus the hunk header's function context, so a common line like } is not "still valid" by coincidence) and anchorSnapshot (the review snapshot id whose coordinates it uses). reanchorCodeAnnotations runs on restore (every in-scope line comment when patchChanged) and whenever the snapshot on screen changes: a comment whose text and context still match at the same side/lines is re-stamped; any other in-scope line comment, including one with no anchor fields, gets outdated: true and keeps its old line numbers (never dropped, never moved). File and general comments, and comments bound to another PR or scope, pass through. The app remembers the latest layer snapshot per PR, and buildReviewSubmission posts a line comment inline unless canPostInline refuses it: an outdated comment, or one stamped on a snapshot other than the one the page KNOWS for its PR. No evidence is not evidence of change: an unstamped comment, or one for a PR whose snapshot this page has not seen (after a reload only the PR on screen is known), posts inline. Refused comments go in the review body with the code they were written on; only a comment an anchor check marked outdated carries OUTDATED_ANNOTATION_LABEL. Restoring a draft whose patch changed does not restore Viewed marks on files still in the diff (restorableViewedFiles: the draft cannot tell which files the push touched), and every /api/feedback post, the platform path's status post included, carries draftGeneration. Outdated comments are not drawn on the diff (the review-state context filters them), show an "Outdated" chip and an Edit action in the sidebar, export under OUTDATED_ANNOTATION_LABEL, and a sidebar click opens their file without a scroll request.
The Dock's Paths view (CallFlowTreeView in packages/review-editor/components/CallFlowTreeView.tsx, header in dock/panels/ReviewCallFlowPanel.tsx, styles under "Call-flow Dock + file-header Lens" in packages/review-editor/index.css) is the approved "Cards" look (.product/approved/review-callflow-cards/, not in this repo). The header is the title plus one summary line ("14 new · 1 removed · 4 files · 2 entries"), then a legend with the hollow "unchanged" marker and the click hint. Each entry point is a card whose header shows "Entry", the entry name and a quiet "N changed" count. A row leads with the called name: splitCallFlowSignature (utils/callFlowPresentation.ts) splits a call label into a muted receiver, the name, and the more muted arguments, and the arguments truncate before the receiver (the name never does). Branch rows keep their plain label. The status is a dot: green for new, red for removed (with the name struck through), a hollow ring for unchanged context. The dot is aria-hidden; the row's comment button carries a visually hidden "New: " or "Removed: " so a screen reader reads the status with the call. Rounded tree lines join each caller's dot to its children; their geometry comes from the --call-flow-* variables on .call-flow-trees (indent, base, toggle, marker cell, row height), so change the variables and never the line rules. Every mode must keep indent >= toggle + marker cell / 2, or a child's toggle cell starts left of its caller's line and the elbow collapses: the compact Lens shrinks the toggle and marker cells (12px) with its 19px indent, and a coarse pointer keeps the 14px toggle cell and grows only the button's touch area (button.call-flow-expand::after, 44px over the indent and the marker cell, which takes no pointer events). CallFlowTreeView.geometry.test.ts resolves the variables for every Dock/Lens, fine/coarse and wide/narrow combination and fails when an elbow would collapse. file:line is one chip: strong (call-flow-node-location-cross-file) where the call moves into a file other than its caller's (the nearest calling step that has a file; an entry's first step always counts), faint where it stays in the same file. The full path is in the chip's title and accessible name. The Lens (CallFlowFileBadge) renders the same component with compact. Commenting (click, Enter, Shift-click to add steps), jump to file:line, the source preview, search (matches are found on the whole label and marked across the receiver/name split), collapse and focus rings are unchanged. Light and dark come only from theme tokens. The summary items are spaced by CSS gap, with a visually hidden ", " between them for screen readers. Known gaps: the chip shows only the file name, so two files with the same name in different directories look alike (the title and accessible name carry the full path), and a search that matches only a directory finds the row but marks nothing in it. Tests: CallFlowTreeView.interaction.test.tsx ("CallFlowTreeView cards"), CallFlowTreeView.geometry.test.ts, CallFlowTreeView.test.ts, utils/callFlowPresentation.test.ts.
One function's calls as a tree, one call per row (CallTree in packages/review-editor/components/callTree/CallTree.tsx, styles in callTree.css beside it, imported by index.css). It is fed by one versioned document, CallTreeDoc (plannotator.callTree/1, packages/core/call-tree.ts, re-exported as @plannotator/shared/call-tree), and callbacks only (onOpen, onAnnotateTargets, onBack, loadNodeSource); it reads no review state, so a Guided Review chapter or the Inbox review can mount it as it is. A node is CallDiff's CallFlowNode plus an optional provenance: "agent" and notes (each with its own provenance); words with an agent provenance are drawn with a pencil mark. Nothing writes them yet (agent notes are phase 2).
- Where: the Call flow tab opens on the Call tree (the owner's decision once the tree had search); its switch is Call tree | Paths | Raw, and Paths (the approved cards) is unchanged. The choice lasts while the panel is mounted, as the Paths/Raw choice did; there is no setting. Each hunk Call flow can draw a tree for gets a "Call tree" entry just above its first change, in All changes and the single-file diff (a
HostLineNotefromApp.tsx, drawn by both diff views). It opens the tab on the tree rooted at the function around the hunk, with the caller trail ("from a › b"); Escape returns to the hunk, Close shows the tab's own trees. Hunks with no tree get no entry. No endpoint:/api/call-flowand/api/semantic-diffare re-read in the browser. - Re-rooting (
findCallTreeRoot): withsem's innermost changed entity around the hunk's first change (utils/callTreeHunks.ts), the shallowest call to that name whose own calls are written in its range (or an entry written there); without sem, the shallowest node whose calls are written in the hunk, lifted out of a call's arguments (CallDiff nests a call written in an options object or callback under the call it is passed to). Removed calls are matched on the old side. - Rows (
buildCallTreeRows, iterative, so deep trees never hit a recursion limit): tree lines; the file:line on the right, only:linewhen the call stays in its caller's file; a red or green band only where a call's own line changed (a wholly new subtree bands its top row and keeps dots below, never the all-green look the owner rejected); "↑ above" for a call already drawn with the same calls below it, not expanded again; unchanged branches fold by default with "N calls"; "Changes only" keeps the root and the paths to changes. Hover is a grey band with the name underlined; the current row shows "⏎ open". - Keys (scope
review-call-treeincallTree.shortcuts.ts, in the shortcut help): ↑/↓ move, ←/→ fold and unfold (or move to the caller / first call), Enter opens the line, C comments, Escape goes back. They are bound to the tree element and stop there, so the file tree's arrows and All files'Cnever see them. Enter opening (not commenting) is the owner's decision of 2026-11-10; the Paths cards keep click-to-comment. - Open and comment: a row opens like a Paths location when its line is in the patch (
openDiffFile+ the line selection), else the file's whole-file view (kept in Back); a removed call outside the patch does not open. A comment goes throughonAddCallFlowAnnotationwithannotationTargetForCallFlowNode, so it lands on the row's file line (old side for a removed call) exactly like a Paths card comment. - Search (
CallTreeList, which the tab mounts for both its own trees and a hunk's tree): the Paths view's search, reused rather than rebuilt:CallFlowSearchControls(same field, "Search call paths", "Find calls or files", then/mcount, Enter / Shift+Enter, Escape),useCallFlowFindShortcut(Cmd/Ctrl+F while the Dock panel is active) and Paths' match rule (callTreeNodeMatches: trimmed, any case, in the label or the file path) and marks (searchRanges/highlightSlice, across the receiver/name split and in the location). No new key. One field searches every tree of the tab; matches are numbered across them and next / previous moves the current row of the tree holding the match.buildCallTreeRows({ query })keeps matching rows and their callers, all open (so a match in a folded branch shows), no repeats, and intersects with Changes only; a tree with no match keeps only its root. Folds made while searching are kept apart and dropped with the search, so clearing it gives back the person's folds. The trees get the query throughuseDeferredValueand rows compare what they draw (sameRow), so the field answers each key in a frame on 3,041 rows (the tree follows in about 64 ms; arrows and next match stay one frame). - Source preview: the file:line keeps the Paths view's preview (next section): the same hook, window and loader.
- Size: 3,041 unfolded rows mount in about 85 ms in Chromium and an arrow move takes one frame, so rows are not virtualized.
Tests: packages/core/call-tree.test.ts (incl. "search rows"), utils/callTreeHunks.test.ts, components/callTree/CallTree.test.tsx (incl. "CallTree search", which also checks the count equals the Paths search's for the same query), dock/panels/ReviewCallFlowPanel.callTree.test.tsx.
In the Semantic Changes panel, resting the pointer on (or focusing) an entity row opens its source: the entity's line range on the side it lives on (lineSelectionForChange; the old file for a deletion), through SemanticDiffChangeRow in packages/review-editor/dock/panels/semanticDiffShared.tsx. In the Call Flow Dock panel, resting the pointer on (or focusing) a step's file:line location opens a floating source window: the step's lines marked, three lines of context around them, syntax highlighted; the Call tree view's file:line does the same. The window is CodeSnippetPreview (packages/ui/components/CodeSnippetPreview.tsx) with the dwell/close timing of useHoverPreview (packages/ui/hooks/useHoverPreview.ts, 150 ms to open, 200 ms grace to move into the window), the same pair plan / annotate code-file links use (CodeFileLink in InlineMarkdown.tsx). Both read through createReviewFileSourceLoader (packages/review-editor/hooks/useReviewFileSource.ts; Call Flow adapts it per step in useCallFlowNodeSource.ts) over /api/file-content, bound to the review's base and snapshot, so a PR or since-base review previews the reviewed source rather than the working tree; a removed step shows the old side, and a renamed file asks with its oldPath. One request per file is shared by its rows; a failed one (a stale snapshot) is forgotten so a later hover asks again. Nothing loads before the dwell, a static patch review (contextExpansionAvailable === false) gets no loader and no preview, and the window closes on any scroll since it is placed once. The per-file Lens (CallFlowFileBadge) and the file header's semantic popover (SemanticFileBadge) pass no loader on purpose: each is itself a hover popover, and a second, portalled one would read as the pointer leaving it. Tests: packages/review-editor/components/CallFlowTreeView.sourcePreview.test.tsx, packages/review-editor/components/callTree/CallTree.test.tsx ("CallTree source preview"), packages/review-editor/dock/panels/semanticDiffShared.sourcePreview.test.tsx.
Call flow runs CallDiff 0.6.0 at upstream commit 2086f6e4e9ed3c410bba7c94ca3dde77791b1956 (CALLDIFF_VERSION, CALLDIFF_COMMIT, CALLDIFF_SOURCE_INTEGRITY in packages/shared/call-flow.ts); the full contract is adr/specs/calldiff-call-flow-integration-20260811.md. Languages are call-flow-languages.ts: 22 of upstream's 23 extractors (C++ includes CUDA .cu/.cuh). Perl is left out because tree-sitter-perl has no prebuilt binaries, so its pack would need a C compiler. The Node floor is CallDiff's own engines value, 22.18 (CALL_FLOW_MIN_NODE_VERSION). An older Node gets "Call flow needs Node.js 22.18 or newer. You have Node.js vX." from the preflight, the runtime probe and the install, before any download; the rest of code review is unaffected.
- Moving the pin. Hash the archive at
CALLDIFF_SOURCE_SPEC(SHA-512, base64,sha512-prefix). Re-hashing the old commit must give the old pin, which proves the method. In a temp directory, put the committedcall-flow-runtime/package.jsonandpackage-lock.jsonbeside the archive namedcalldiff-<commit>.tar.gz. Change thecalldifffile spec and the version (<calldiff>-plannotator.<n>, back to.1for a new CallDiff version). Then runnpm install --package-lock-only --ignore-scripts --legacy-peer-deps --no-audit --no-fund: npm keeps every other locked version that still fits, and itsintegrityforcalldiffmust equal the new pin. npm 11.12 omits the rootoverridesentry. Keep it, so that the lock has the same shape as the one that shipped. Compare upstream's grammar pins (src/languages/*.ts,grammars.tsinstall specs) withcall-flow-languages.ts. The pack locks undercall-flow-runtime/packs/change only when a grammar pin changes; they did not for 0.6.0. - Upgrade. The managed core folder is named by version (
vendor/call-flow/calldiff-<version>) and also checks.calldiff-revisionand the committed lock, so an older pin's folder is never used. A new pin installs on the next use with the same consent (runtime-unavailable→ install). Its install copies each optional pack whose lock marker matches from the older folder, and checks that the pack loads through the new core (preserveValidatedLanguagePacks). Only after the new core is published (or on an install that finds it already installed) does it remove stale folders (removeStaleCallFlowRuntimeDirs): oldercalldiff-<x.y.z>cores and interrupted-swapcalldiff-<x.y.z>.previous-<pid>-<ms>backups of an older or the current pin, real directories only (no symlinks), only in this data dir'svendor/call-flow. Each is first renamed to a.calldiff-stale-<pid>-<ms>-<n>tombstone, which no version resolves, and then deleted. A delete that is cut short therefore never leaves a half-deletedcalldiff-0.4.1that an older Plannotator would take as installed. The next install sweeps leftover tombstones. A folder that cannot be renamed (in use on Windows) stays whole and is tried again next time. A failed download or build removes only its own temp folder, so the older folder stays and Retry starts again. - Downgrade. An older Plannotator looks only at its own
calldiff-<old>folder. It installs that folder again (or uses it, when a failed upgrade left it) and never reads or removes the newer folder. The cleanup removes only strictly older versions, so the newer folder is still in place when the user upgrades again. Tests:packages/shared/call-flow-upgrade.test.ts.
In a github.com PR (the same proxiesGitHubImages check the image proxy uses), a paragraph containing only a bare GitHub attachment URL is inspected through /api/pr-artifact-content with a one-byte range request. A successful video/* response loads a hidden native video player (controls, metadata preload, no autoplay), and the player replaces the link once its metadata loads, so the page shifts once and the URL text is no longer on the page to select or comment on. Other content types, failed probes, and playback errors keep the original link. The description's Markdown itself is unchanged. Because the paragraph changes shape when the probe answers, AnnotatableDescription restores saved comments with verifyRestoredContent, which re-anchors a comment by its text when its saved position no longer matches. RenderedMarkdown.renderParagraph supplies the host seam; other callers retain their existing rendering.
A changed image whose patch chunk has no hunks (git's binary stub, our oversized stub, or a header-only GitHub/GitLab fallback chunk) renders as a Before/After preview (packages/review-editor/components/ImageDiffPreview.tsx) instead of the "Binary or oversized file" notice, in the single-file view and the all-files view, when the server advertises imagePreviewSupported. Added files show After only, deleted files Before only, identical bytes (pure rename, mode change) one pane plus "Contents unchanged"; panes stack under ~480px of width, in the compact shell, and for tall images. Cards fetch only once near the viewport (IntersectionObserver), abort on unmount, and keep a 64-entry object-URL LRU per snapshot; SVG is only ever shown through <img src=blob:…>. The notices stay the fallback: not an image → binary notice, an oversized stub over 10 MB → oversized notice. The all-files view takes the preview through a renderImagePreview render prop that only the review app's all-files panel sets, so the guide chain and the guides.show viewer keep the plain notice and never request images.
Freshness: the endpoint checks the snapshot id only, not a per-image VCS fingerprint (that probe per image would be expensive on a large PR). So for a working-tree side (uncommitted, unstaged, since-base, local-vs-remote, GitButler workspace) the After pane can show a file NEWER than the diff on screen if it changed after the snapshot; the "Diff out of date · Refresh" banner (the 5s /api/diff/fresh poll) covers that case, and a refresh re-binds every card to the new snapshot. Server reads run behind a 4-wide limiter that takes the request's abort signal (Bun req.signal, Pi the response close), so reads queued for cards the reviewer scrolled past are dropped before they run, and no platform API call starts for a request that is gone. The client cache holds at most 64 sides and 128 MB, never revokes an object URL a mounted <img> still uses, and ignores a response that arrives after the page moved to another snapshot.
Server side, every decision is in packages/shared/review-image.ts (vendored to Pi): eligibility via findPatchFileEntry, caps (MAX_REVIEW_IMAGE_PREVIEW_BYTES 10 MB, MAX_REVIEW_IMAGE_PREVIEW_PIXELS 50 MP, both in packages/core/diff-paths.ts), sniffing, header dimensions, error mapping and headers; both servers only say where the current mode reads a side, behind a 4-wide read limiter. Which object each side is comes from ONE table per VCS shared with hunk expansion: resolveDiffSideSources (git), resolveJjSideRevs (jj), resolveGitButlerSideSources; bytes come from readDiffSideBytes (git cat-file --batch-check then cat-file blob <oid>, never show; worktree reads refuse symlinks and require the realpath inside the repository toplevel) over the optional runtime methods runGitBytes / readFileBytes / realPath / runJjBytes (absent means unavailable). PR mode reads the local checkout at the fixed merge-base/head commits first and falls back to fetchPRFileBytes (GitHub contents API, then the blobs API for files over 1 MB after a size check; GitLab JSON files API), base64 in both cases so bytes survive the CLI's text stdout. Workspace mode delegates per child repo (WorkspaceReviewSession.getFileBytes). Off: static patch, P4, the guide chain and guides.show.
A changed package.json, package-lock.json (or npm-shrinkwrap.json), bun.lock, pnpm-lock.yaml (v6 and later) or yarn.lock (classic and Berry) gets a quiet card under its header listing the dependencies the diff adds, removes, upgrades, downgrades, changes or moves between sections, in the single-file and the all-files views (PackageChangesCard.tsx). Read-only hosts (the guide chain, guides.show) set neither seam (packageChangesAvailable, renderPackageChanges), so they never fetch or draw it; a static patch has no files behind it and gets nothing.
- Server-side derivation.
GET /api/package-changesreads both sides of every manifest and lockfile in the diff (plus thepackage.jsonbeside a changed lockfile, for yarn.lock's direct dependencies, new side only) through the per-side byte reader the image routes use (readReviewSidein both servers, up to 32 MB a side, 4 reads at a time) and runsanalyzePackageChanges(@plannotator/core/package-changes). A side the diff says exists but that comes back missing, too large or from a failed platform call is unreadable (PackageUnreadable), never absent: the card shows the quiet error row ("Unreadable bun.lock", the side and reason in a tooltip), never a table of removals. A lockfile that does not parse, or a yarn.lock whosepackage.jsoncannot be read, gets the same row. A manifest's rows show the versions its governing lockfile (the nearest changed lockfile in the same or a parent directory) resolved, else the spec's floor; a resolved bump inside an unchanged range is still a row. The card nearest the lockfile also carries the other workspaces' direct changes (tagged with the workspace directory) and a fold of the indirect packages whose versions changed. A changed lockfile gets its own card only when no changed manifest it governs is in the diff (a Dependabot lockfile bump); in the all-files view that card stays visible while the lockfile is folded as a generated file. A lockfile that does not read or parse leaves the manifests on their ranges. - Ecosystem seam. Each ecosystem is one
PackageEcosystementry (file names, manifest and lockfile readers, spec classification, version order); npm ispackage-changes-npm.ts. Cargo, Go and Python are planned as further entries. - npm lookup (consent). Off by default. "Look up N on npm" on any card saves config.json
packageChanges.lookup: true(POST/api/config) and every card then looks itself up, so N is every name the review would send (lookup.total, the union across cards), not the card's own. Settings → Analysis turns it off;PLANNOTATOR_PACKAGE_LOOKUP=0is a hard off (and then no registry setting is read at all). The server enforces it:POST /api/package-changes/lookupanswers 403 until it is on, takes only a card path, and sends that card'slookup.names, which the server listed. - What may be sent (fail closed). A name leaves the machine only when every registry setting that could route it elsewhere was read and none does (
package-changes-service.ts,packageRoutinginpackage-metadata.ts). Settings are read where the package manager reads them: in a local or workspace review, from the working tree on disk in every directory from the card (and its lockfile) up to the filesystem root, so a gitignored or untracked.npmrccounts whatever the diff mode; in a PR review, at the PR head commit: from the local PR checkout when it holds that commit (onegit ls-tree, then only the settings files that exist; no GitHub call), else through the platform API, at mostREMOTE_SETTINGS_READS(16) calls per head commit, and a PR that would need more (a monorepo PR touching packages in several folders) withholds every name and offers no button. On first load the PR checkout is usually still being prepared: the card waits for it (prepareon the host: BunensurePRLocalCwd, PiworktreePool.ensure), and reads through the API only when no checkout can exist, or afterPACKAGE_CHECKOUT_WAIT_MS(18 s), in which case the result is not kept and the next look reads again. Without a checkout the package files themselves cost at mostREMOTE_PACKAGE_READS(20) calls per base and head commit: the cards that fit are drawn and nothing is offered for lookup, since the total a click would send is not knowable. Settings and package-file reads are kept per head commit, so a new snapshot of the same PR costs nothing (prSettingsSourceinpackage-changes-service.ts;packages/server/package-changes-pr.test.tscounts thecontentscalls for 1, 5 and 30 cards, with and without a checkout); always the user's own files (NPM_CONFIG_USERCONFIGor~/.npmrc, the globalnpmrcfromNPM_CONFIG_GLOBALCONFIG, else$PREFIX/etc/npmrcforNPM_CONFIG_PREFIX, the node onPATHand the usual prefixes,~/.yarnrc.yml,~/.yarnrc,~/.bunfig.toml,$XDG_CONFIG_HOME/.bunfig.toml) and the environment (anynpm_config_*registrykey, case-insensitive, scoped ones included;YARN_NPM_REGISTRY_SERVER,YARN_REGISTRY,YARN_NPM_SCOPES,BUN_CONFIG_REGISTRY). Files per directory:.npmrc,.yarnrc.yml(orYARN_RC_FILENAME),.yarnrc,bunfig.toml. A scope is withheld when set to another registry in.npmrcor.yarnrc, or configured at all in.yarnrc.ymlnpmScopes(block or flow style, any indent) orbunfig.tomlinstall.scopes; every name is withheld when the default registry is not npm's, when a settings file exists but cannot be read (a directory, over 1 MB, permission denied), when a PR read fails (a gh error or rate limit), or when the working tree cannot be located. A package the lockfile fetches from anywhere butregistry.npmjs.org/registry.yarnpkg.com(resolvedin package-lock and yarn.lock,tarballor a git resolution in pnpm, bun.lock's registry slot, git and tarball versions) is markedprivateSourceand withheld on every card. Withheld names show a lock icon. - Lookups. The full packument (license, per-version publish time, deprecation) and the downloads API (bulk for unscoped names, one request per scoped name), 4 at a time, one in-flight request per package however many versions ask, 8 s timeout, cached 1 h in memory up to 2,000 entries per cache (
packages/shared/package-metadata.ts). - Card. Header: fold (one remembered choice for every card, cookie
plannotator-package-changes-folded), icon, "Packages", count, and on the right either the consent button ("Look up N on npm"; its tooltip says N counts every card in the review) or a failure word with Retry. Columns, old then new: Package (change icon with a tooltip, name, section and workspace tags, lock, deprecated pill), Previous ("—" for an addition or a section move), Version (the warning tone for a semver-breaking step, said in its tooltip with the spec; ↑ and ↓ are both neutral), then after the lookup License, Released (under 7 days in the warning tone) and Downloads (weekly, smaller and fainter, last;SHOW_DOWNLOADSdrops the column). A row npm was not asked about leaves those three as one blank span. A failed lookup shows only its status and Retry, no lookup columns. Eight rows, then "N more"; the indirect fold shows 100 at a time ("N more"). Under 600 px the rows stack in the same order (old → new) and a native select sorts. No keyboard shortcuts. - Settings → Analysis: "Package changes" (config.json
packageChanges.card, default on; off hides every card) and "Look up packages on npm" (packageChanges.lookup). Both ride serverConfigpackageChanges: { card, lookup, lookupEnv? }throughusePackageChangesSetting(@plannotator/ui/hooks), not the settings registry. A server that does not advertise it gets no card.
Approved design record "review-file-kinds" (not in this repo). One pure classifier, fileKind(path, generated?) in @plannotator/core/file-kind (vendored to Pi), sorts every changed file into code, test or generated: generated is the host's generated set when it has one (the review server's generatedFiles, .gitattributes included), else the built-in name list; test is a test file name (*.test., *.spec., *.cy., *.e2e., *.test-d. or *_test. followed by a code extension (CODE_EXT: ts, tsx, js, py, go, rs, java, kt, rb, cs, ...), with a name before the marker; *.stories.*; test_*.py, conftest.py, tests.py; *.snap) or a folder above the file named __tests__, __snapshots__, __fixtures__, __mocks__, test, tests, spec, e2e, fixtures, testdata or testFixtures (case-insensitive), a Gradle source set src/<name>Test, or a .NET *.Tests / *.UnitTests project; code is everything else, docs and config included. contest.ts, latest.ts, test.ts, testing-library.config.js, openapi.spec.yaml and load_test.md stay code. groupByFileKind splits a list in that kind order, keeping each item's order. The three glyphs (angle brackets, a flask, a package) are FileKindIcon in @plannotator/guide-viewer/FileKindIcon, shared by the review app, the Inbox and guides.show.
- Tree (
FileTree,utils/fileKindTree.ts): with "Group by kind" on (the list options "…" menu, default on, cookieplannotator-review-group-by-kind=offwhen turned off; deliberately not a settings-registry entry, which the guides.show viewer bundles) and two or more kinds, the tree is one block per kind, each today's folder tree, under a flush group heading (PanelSectionHeaderinFileRowBits.tsx, whichSectionsPaneluses too) with the kind icon, viewed/total and +/- (see "The left panel" above). A header folds its block in the tree only; Generated starts folded. Folder paths are scoped per block (kind:path), so the expansion hook and collapse-all keep working. j/k/Home/End follow the block order. A file that becomes active by any route (j/k, a click in all-files, the scroll highlight, an annotation or search jump) opens its folded block, as folded folders open for the active file; a new file list never does, so Generated stays folded when a diff loads. With hide-viewed on, a block whose rows are all hidden hides its header too. The all-files surface follows it too (fileOrder: 'kind',getFileKindOrder); the Git status view keeps its sections and the Commits view its tree order. One kind, or the switch off: today's tree. - Flask: test files get it in diff headers (
FileHeaderisTest, fromAllFilesCodeViewand the single-file panel) and on Git status rows. Tree rows inside a block get no icon. - Guided Reviews (
GuideSectionCard): within a chapter, files come together by kind (code, then a "Tests N" subhead, then "Generated N"), the author's order kept inside each kind; subheads show only with two or more kinds; diff cards follow the chip order; test cards stay open and generated cards start folded (GuideFileCardkind). Hosts may passgeneratedFileson the guide host (the review app does); the Inbox and guides.show use the name list. No change to the guide format, prompt or export. It costs the guides.show viewer about 1.3 KB gzip, inside its 400 KB budget.
Approved design record "review-explorer" (.product/approved/review-explorer/, not in this repo; the owner's answers: a review opens on Changes, the tree follows the disk while the diff waits for Refresh, comments outside the diff go in a PR's review body, build steps 1 to 3). The left panel has a Changes N / All files N pair (ScopeSwitch, leading the sticky tools block, drawn only when the session advertises repoFilesSupported; App then passes the remembered scope to FileTree, else changes). Chosen from Git status, All files goes to the Tree view. Changes is today's tree, unchanged. All files is every file of the repository at the revision the diff's new side reads.
- Which revision: one table,
resolveDiffSideSources(resolveGitNewSideinpackages/shared/review-core.ts): the working tree for uncommitted, unstaged, since-base and local-vs-remote; the index for staged; the commit otherwise (ls-tree -r --full-tree). The working tree is listed withls-files --cached --others --exclude-standardminus--deleted, so.gitignoreapplies and nothing ignored (an.env,dist/) is ever listed or readable. jj:jj file list -r <new rev>(listJjFilesForDiff, never live). GitButler: the Workspace view's working tree or the stack/branch tip (listGitButlerFilesForDiff). Multi-repo workspace: each child's list, folder-prefixed (WorkspaceReviewSession.listFiles). PR with its local checkout:ls-treeat the head sha in the checkout; without one, and while a--localclone is still being made (the listing never waits for it; the cache key names the source, so the checkout takes over once ready), the platform tree API (fetchPRTree: GitHubgit/trees/<sha>?recursive=1with itstruncatedflag, GitLab's repository tree page by page up toGL_TREE_MAX_PAGES(500 pages of 100), Bitbucket'ssrc/<sha>/?max_depth=up to 500 pages; past either budget the listing istruncated). A file read from the platform goes throughfetchPRFileByteswith the 5 MiB cap anddecodeRepoFileBytes, so a binary file is said to be one. P4 and static patches: none (repoFilesSupported: false).VcsProvider.listFiles/listVcsFilesinvcs-core.tscarry it for every provider. - Routes (
packages/shared/repo-files.ts, vendored to Pi; both review servers route throughhandleRepoFilesRequest/handleRepoFileRequestand only say where they list and read):GET /api/repo-files?snapshot=(409 for a stale snapshot),GET /api/repo-file?path=&snapshot=(only a LISTED path is read, so ignored files and..are unreachable; a working-tree file goes through the same guard as code navigation,readRepoFileinrepo-file.ts, viareadRepoWorkingTreeFileinrepo-files-node.ts, which the shared handler requires both runtimes to pass asreadWorkingTree; text, orreason: too-large | binary | missing | unavailable; the 5 MiB cap),GET /api/repo-files/stream?snapshot=(SSE, working-tree listings only; 400 without a snapshot, 409 for a stale one). One listing per snapshot (createRepoListingCache), dropped on every snapshot change (captureDiffFingerprint) and on every live change. - Big repositories: up to
REPO_FILES_LAZY_THRESHOLD(200,000) paths the whole sorted list goes to the browser once; past it the list stays on the server and the browser asks for one folder at a time (?dir=,repoDirEntries; the tree asks when a folder opens). The client tree is virtualized either way (RepoFileTree, fixed 28 px rows, a window plus overscan), built from a folder index linear in paths (utils/repoTree.ts). Tests passrepoFilesLazyThresholdto the servers. - Live: a working-tree listing is watched with annotate's watcher engine (
file-browser-watch-core.ts;review-repo-watch.tsin both runtimes, 500 ms debounce,.git,node_modulesand cache folders ignored byREPO_WATCH_IGNORED_NAMES, plus everything git ignores when watching starts,gitIgnoredEntries, so build output is never watched). PastREPO_FILES_LAZY_THRESHOLDpaths, and for a multi-repo workspace (whose root is a parent folder), it is polled instead (repoLiveMode, everyREPO_LIVE_POLL_MS, 5 s, backing off 1.5x per look that finds nothing up to 30 s, back to 5 s after a change;nextRepoPollDelay). Either way an event only counts when the working tree's signature moved (createRepoChangeGateovergitLiveSignature: git status plus each reported path's mtime; a workspace's listing), so writes to gitignored output never list the tree again. A real change drops the server's listing and tells the page, which lists again (useRepoFiles). The page lists and watches only while All files is on screen: the Tree view of an open file tree, not merely the remembered choice. Shown again after being hidden, a live listing is fetched again quietly (nothing watched the disk meanwhile). A stream is attached only after git's ignore list is read, and only if the page is still there (Bun: the request's signal; Pi:closeregistered first), so a page gone meanwhile leaves no subscriber, heartbeat or watcher;closeAllreleases every one. Files modified after the diff was taken carry an amber "changed on disk" dot (onDisk,findRepoOnDiskChanges: the diff's files andgit status, compared by mtime with when the snapshot was captured; A / M / D; computed once per listing and sent only with the root request, never with a folder's?dir=), and a small dot after the All files count says it (green while live, an amber ring for a partial listing), its words "Live · updated just now · 1 added, 1 edited" in a tooltip and for screen readers (data-repo-listing-status). The diff never redraws by itself: the existing "Diff out of date · Refresh" banner offers that (answer 2). The Changes count stays the diff's. - Rows: a changed file keeps today's row (
FileTreeNodeItem: viewed circle, staging, letter, +/-, comment badge), a file the diff deletes stays in the tree though the new side lacks it, other files are muted, and folders show no changed-file count (the owner removed it, 2026-10-27). It opens on the folders that lead to changes (and the active file's). Kind blocks, hide-viewed and the j/k order keep applying to Changes only. - Remembered per browser in the cookie
plannotator-review-tree-scope=all(useTreeScope; cookie only, deliberately not a settings-registry entry, which the guides.show viewer bundles). The repository is listed only while All files is on screen. - Tree component: our own virtualized tree, not
@pierre/trees: its rows are decorations only (no interactive viewed circle or stage control in a row), it brings preact into the single-file build (measured +248 KB minified, +70 KB gzip for its React entry alone), and our row stays one component for both scopes. All files added +15.5 KB raw, +3.9 KB gzip to the review app. - Tests:
packages/server/repo-files.test.ts(both runtimes: revisions,.gitignore, reading only listed paths, lazy folders, stale snapshots, on-disk changes and the stream, gitignored writes never counted, polling past the threshold, on-disk marks only on the root request, the stream's snapshot check, static patch; jj),packages/shared/repo-files.test.ts, DOMFileTree.allFiles.test.tsxandhooks/useRepoFiles.test.tsx, andtests/e2e/review-explorer.spec.tson the compiled binary.
Same approval record as All files. A file opens in a tab from the tree, Go to File and code navigation (step 3):
- Preview and keep (
openRepoFileinApp.tsx): a single click on a file the review does not change opens it in the one preview tab (REVIEW_FILE_PREVIEW_PANEL_ID, italic title,data-preview-tab), replaced by the next single click; a single click on a changed file opens the diff tab as before. A double click on a tree row opens the file in a tab of its own (makeReviewFilePanelId(path), panel typereview-file,ReviewFilePanel); a double click on the preview tab, or a comment made in it, keeps THAT tab (the same panel,preview: false, so its place in the strip and its scroll stay;handleKeepFileTab). File tabs are found by their parameters (findFilePanel), never by id: a kept preview keeps itsreview-file-preview:<n>id. A kept changed file shows its diff; double-clicking a changed row used to do the same as a single click and now keeps it. - A file not in the review (
RepoFileView): the path, a "Not in this review" chip and the revision it was read at ("at working tree", "at a1b2c3d"), then the file whole and read-only through ui'sCodeFileView, read fromGET /api/repo-file(useRepoFileText, one read per snapshot and path; too large, binary, gone and a stale snapshot each say why). - A changed file: a Changes | Whole file switch in its header (
FileViewSwitchthroughDiffViewer'sheaderAccessory; per file, for this review,fileViewOf/onFileViewChange; not for Markdown, whose Read view already shows the document; disabled for a deleted file; absent where the session has no All files). Whole file (WholeFileView,DiffViewer'sbodyOverride, so the header, viewed and staging controls stay) is the new side from/api/repo-filewith change bars in the gutter from the patch (utils/wholeFileMarks.ts: added, modified, a wedge where lines were removed; drawn throughCodeFileView'sextraCss). - Comments on any line (answer 3): a comment made in a whole-file view inside one hunk is an ordinary diff comment; anywhere else (
isLineRangeInPatchsays no, or the file is not in the review) it carriesoutsideDiff: trueand the commented code inanchorText(handleAddWholeFileAnnotation). It is drawn only in whole-file views (the diff surfaces filter it out), never marked Outdated by a diff re-check (reanchorCodeAnnotations), and its sidebar card and inline card say "not in the diff". To the agent it is exported under its file as### Lines 49-52 (new) (not in the diff)with the code fenced (OUTSIDE_DIFF_ANNOTATION_LABEL). On a PR it is never posted inline (canPostInlinerefuses it): the review body gets a Comments outside the diff section, each entry linking to the lines at the head commit (prBlobPermalinkinpr-types.ts: GitHubblob/<sha>/<path>#L10-L11, GitLab-/blob/<sha>/<path>#L10-11, Bitbucketsrc/<sha>/<path>#lines-10:11) with the code quoted (at mostOUTSIDE_DIFF_QUOTE_MAX_LINES, 40, then…, so a long range cannot push the body past GitHub's 65,536 characters; the permalink shows the rest; in a stacked review each comment links to its own PR's head, from the PRs this page has shown), and the submit dialog says how many go there before posting (outsideDiffCount,data-outside-diff-note). A sidebar click on one opens its file's whole-file view. The feedback archive records the flag (outsideDiff: true, additive). - Tests:
utils/outsideDiffComments.test.ts(PR body, permalinks, export, re-check, change bars), DOMcomponents/RepoFileView.test.tsx, and the second test oftests/e2e/review-explorer.spec.ts(preview replaced, kept by a double click on the tab, Whole file, a comment outside the diff reaching the agent's stdout).
Same approval record. The keys are one registry scope, review-explorer (packages/ui/shortcuts/code-review/explorer.shortcuts.ts, in codeReviewSurface), so Settings → Shortcuts and the docs page list them; VS Code's own defaults per system:
| Does | macOS | Windows | Linux |
|---|---|---|---|
| Go to File | ⌘P | Ctrl+P | Ctrl+P |
| Go to Definition | F12 (also ⌘F12 / Ctrl+F12, for browsers that keep F12) | F12 | F12 |
| Go to References | ⇧F12 | Shift+F12 | Shift+F12 |
| Back | ⌃- | Alt+← | Ctrl+Alt+- |
| Forward | ⌃⇧- | Alt+→ | Ctrl+Shift+- |
| Next / previous change | ⌥F5 / ⇧⌥F5 | Alt+F5 / Shift+Alt+F5 | Alt+F5 / Shift+Alt+F5 |
- The registry gained what these need (
packages/ui/shortcuts/core.ts): aCtrltoken (the physical Control key, ⌃ on macOS;Modstill means ⌘ or Ctrl, so no existing key changed), a-token matched by its key code (so Shift's_still reads as it), andplatformBindingsper system (resolveShortcutBindings,getShortcutOS; the runtime and the double-tap hook use it; the docs page prints each system's keys withformatShortcutDefinitionText). The PR destination's double-tap Alt moved onto the registry's double-tap hook (useReviewEditorDoubleTap), which counts a tap only when Alt went down and came up alone, so ⌥F5 or Alt+← twice never switches where the review goes. Settings → Shortcuts' review list adds thereview-explorerand Markdown (P) scopes, read from the registry. No key works over a dialog, the guide, or while typing (Go to File does, as in VS Code, but on macOS only with ⌘ there: ⌃P in a field is the field's own);canHandleExplorerKeyinApp.tsx. F12 / ⇧F12 with no symbol under the pointer (or clicked) are left alone, so the browser keeps its developer tools. Inside the VS Code panel ⌘P stays VS Code's Quick Open (the panel always forwards it); Go to File is the tree's row there. - Go to File (
components/GoToFile.tsx; also the Go to file field at the top of the left panel): fuzzy over every file of the listing (packages/shared/fuzzy-path.ts, Plannotator's own matcher: every term's characters in order; greedy alignments from a few starting points, word starts first; bonuses for word starts, runs, the file name and how much of the file name the query covers; a small cost for gaps and long paths), changed files marked with their status and +/- and winning ties, nothing typed listing the files opened last then the changed files. A listing the browser holds is searched in the browser (measured about 15-90 ms for 200,000 paths per keystroke, so no worker); a lazy listing (pastREPO_FILES_LAZY_THRESHOLD) or one still loading is searched on the server,GET /api/repo-files/search?snapshot=&q=&limit=(both runtimes,handleRepoFilesSearchRequest, listed paths only). Opening the palette lists the repository even on Changes. Enter opens the file (a jump, below); Alt+Enter keeps it in a tab beside the current one; Escape (or a click outside) puts focus back where it was. A session with no listing (static patch, Perforce) searches its changed files and says so. - F12 / ⇧F12: a diff has no caret, so the symbol is the token under the pointer, else the last token clicked (
utils/tokenTarget.ts, fed byDiffViewer/AllFilesCodeViewonTokenTargetandCodeFileViewonTokenTarget, all optional; the guide chain and guides.show pass none). F12 asks today's ripgrep code-nav (/api/code-nav/resolve): one distinct definition opens its file at the line; anything else opens the references panel. ⇧F12, and Cmd/Ctrl-click in a whole-file view, open the references panel; a click on a result now also opens its file at the line (beside the code, never in the panel's own group). A line the diff shows opens the diff with the line selected; any other line of a changed file opens its Whole file view; a file not in the review opens in the preview tab. Code-nav's lines are the working tree's: a tab that shows another revision looks for the symbol near that line (findSymbolLine, whole word, ±200 lines) and otherwise opens at the top with a note. Needs the local checkout, as code-nav does. The references panel now opens beside whichever tab is active (it used to name the diff tab, which may not exist). - Back / Forward (
utils/explorerNavigation.ts): a review-local history, never the browser's. Only jumps record an entry (Go to File, Go to Definition, a reference opened); opening from the tree does not. A jump that flipped a changed file to Whole file records it, and Back puts the file back on Changes. The file a jump opened shows "‹ From buildFileTree.ts:11 · Go to Definition (F12)" (JumpCrumb), and ‹ › appear in the tab strip once there is history. The keys are always taken in code review (Alt+← no longer leaves the review on Windows). - Next / previous change (
utils/explorerChangeNavigation.ts; separate from main'sN/Shift+N, #1543, inutils/changeNavigation.ts, which steps inside one diff and stops at its ends): walks the runs of changed rows Pierre drew in the active view (data-line-type="change-…", and the lines a Whole file view lists indata-change-lines), placing each a third of the way down; views that draw only what is near the screen are scrolled on until a run appears. Past the last run (or when the file fits the screen) it opens the next changed file and lands on its first run (previous: the last run of the file before). - Tests:
packages/ui/shortcuts.explorer.test.ts,packages/shared/fuzzy-path.test.ts,utils/explorerNavigation.test.ts, the search route inpackages/server/repo-files.test.ts(both runtimes), DOMcomponents/GoToFile.test.tsx, the double tap inApp.decisionControl.test.tsx, and the third test oftests/e2e/review-explorer.spec.ts(Go to File, Back / Forward, F12 into a tab at its line, ⇧F12 and a result into a tab, next change across files and through a long diff; needsrg, which the e2e workflow installs).
Approved design: owner-approved variant C (design record, not in this repo). A Markdown file (.md, .mdx, .markdown, config.json markdownExtensions) can be shown rendered instead of as a line diff.
Controls. One control per Markdown file (owner, 2026-10-12 controls amendment, variant "Menu"): a button in the file's header naming its view with a chevron ("Source ▾"), opening a menu Source (the line diff), Changes (the rendered diff) and Read (the whole document rendered, no diff marks), in that order, the same words everywhere. Added and deleted files, and a rename that changed nothing, offer Source and Read only (markdownViewsFor in utils/markdownPreview.ts; a wish for Changes there resolves to Read, resolveMarkdownView). The menu is Base UI's (components/MarkdownViewMenu.tsx: role="menu" with menuitemradio items and aria-checked, arrows, Home/End, type-ahead, Escape back to the button); its title says "Select text to comment" in a rendered view. In the compact touch shell the same button (drawn 36 px, a 44 px hit area from an ::after box) opens the same items as a bottom sheet titled "Show as". There is no global button and no switch inside the file. Defaults: every file starts in Source (approved); a view picked on any Markdown file becomes the starting view for every Markdown file not set by hand in this review, so those follow on screen, and it is remembered for the next review in the cookie plannotator-markdown-view (source | changes | read; cookie only, deliberately not a settings-registry entry, which is bundled into the guides.show viewer; the earlier plannotator-markdown-preview-all=true is read once as changes, rewritten under the new name and removed). A file set by hand keeps its view for the session. Navigation that needs a view (a search hit or a line comment needs Source, a rendered comment its own view, the "not in this view" action) sets that one file only and remembers nothing across reviews (show, vs a person's choose); like a pick, it pins that file for the session, so a later pick on another file does not move it (chosen over "navigation leaves no override" because yanking the file away from the search hit or comment the person just jumped to would be worse). While a file holds the edit session (All files; it is always in Source then, since Edit is refused on a rendered file), its view is locked: starting the session pins the view it shows (an override, as if set by hand), so a pick or P on another file, which moves every file not set by hand, cannot move it; a pick, P or navigation aimed at it is refused; its menu is disabled with "Finish editing first" in All files and in the single-file view (markdownViewDisabledReason), and P on it shows that as a toast (onLocked). A search hit in it scrolls in place (the session's file always shows its diff). The pin stays after the session ends (the file keeps Source until picked), and the swap effect re-runs when the session ends, so nothing held back stays half-applied (lockReason / setEditingFile; AllFilesCodeView reports the session's file through markdownPreview.onEditingFileChange). P reads its key target from composedPath()[0], so typing p in the Pierre editor (a shadow root) never switches views. Key (review-markdown-preview scope in packages/ui/shortcuts/code-review/, so help and the docs page list it): P steps the open file (in All files, among the files intersecting the viewport, never the overscan: the Markdown file holding focus or under the pointer, else the top-most Markdown file, resolved when the key is pressed through markdownPreview.registerViewTarget) Source -> Changes -> Read -> Source, skipping Changes where the file has none, and counts as a pick; never while typing, off a diff, or on a code file. There is no Shift+P: a pick already moves every file not set by hand, so an "every file" key would only override files the person set on purpose. Files shown in Changes or Read show an eye in the file tree. The control is not drawn by FileHeader itself (renderMarkdownView slot): DiffViewer draws it, and in All files the panel passes renderViewControl, whose component reads review state from context, so a Changes <-> Read switch relabels it without republishing the CodeView item; read-only hosts (the guide chain, guides.show) carry none of it. State: useMarkdownPreview / useMarkdownPreviewKeys (packages/review-editor/hooks/useMarkdownPreview.ts), on review state as markdownPreview, absent (no UI anywhere) without the advert or with no full contents (static patch).
What the rendered views show (components/MarkdownFilePreview.tsx, lazily loaded). Changes is plan review's PlanCleanDiffView over computePlanDiff(old, new) with its review-only seams (renderBlock, lineGutter, foldUnchanged, unchangedClassName; see packages/ui/HANDOFF.md): added, removed and changed sections (classic stacked old over new), unchanged runs folded behind "N unchanged sections", source lines in a gutter. Read renders the new version whole (a deletion: the old one). Both render blocks through BlockRenderer, except Mermaid and Graphviz fences, which draw as diagrams with the engine the review server serves on demand (see "Diagrams in code review, loaded on demand" below; read-only: no diagram comments, the preview's rendered-text comments are unchanged; without the engine they render as code), images through the per-revision route below (old side for removed sections, new side otherwise), links through the PR's resolver (a file of this review opens in the review; anything else is inert). In a PR review (prMetadata; holdRemoteImages overrides) a remote image is held behind a placeholder: any source a browser would fetch from another server, read the way a URL parser reads it (isRemoteImageSource: tabs and line breaks dropped, a backslash counts as a slash, so https:host/a.png, https:/host/…, https:\\host\…, //host and \\host all count; every http(s): source does, holding one too many being harmless), and a line above the document says how many with Load remote images; a click on that button or on any held placeholder loads them for that preview, so opening a stranger's file never tells a tracking pixel's server the reviewer's IP address. Repository images always load through the route. Local reviews load remote images as written. Added and deleted files show their one side whole (the header's status letter and the green or red rail say which); a rename with no change says so. Both sides must still agree with the patch on screen (markdownPreviewSides), else "changed after the diff was captured"; over 300 KB a side asks first (Preview anyway). A search hit, a line comment opened from the sidebar, or a line selection sends the file back to Source. In All files the card lives in the item's header slot (measured like an image preview) and the item's diff is swapped for a hunkless one while previewed (markdownPreviewFileDiff; the real one, including a full-content augmentation, waits in fullDiffsRef); hosts that pass no markdownPreview prop (the guide chain, guides.show) get none of it.
Comments. The PR description's experience: useAnnotationHighlighter in comment mode on the rendered text, select anything and the composer opens. The result is an ordinary file-scoped CodeAnnotation carrying markdownPreview: { originalText, view, diffContext?, startMeta?, endMeta? } (packages/ui/types.ts), so it is listed in the sidebar under its file (with a "rendered" tag and the quote), shown in the file's comment banner in Source, drafted, undoable, and counted. In the other view it is found by its text (stored positions only apply in the view it was made in); when the text is not there (a comment on removed text, seen in Read) the preview says how many comments are not in this view, with "Show in Changes" / "Show in Read". The export prints it under its file as "Comment on the rendered Markdown" with the quote and, in the rendered diff, "(in added / removed / changed text)" (markdownPreviewQuote). In a PR review it always goes into the review body with the quote, never inline and never as a file-level thread (buildFileScopedBody). Line comments are not drawn in the preview (the header says so). The feedback archive records the quote as originalText.
Capability. Every diff payload carries markdownPreviewSupported beside imagePreviewSupported (/api/diff, /api/diff/switch, /api/pr-diff-scope, /api/pr-switch, both runtimes): true wherever /api/file-content can read a full file, i.e. every session except a static patch. Absent (an older server) reads as false, and the client then shows no preview UI.
Images. A previewed Markdown file's images load through GET /api/review-markdown-image?doc=&side=old|new&src=&snapshot= (packages/shared/review-markdown-image.ts, vendored to Pi; handleReviewMarkdownImageRequest), read at THAT side's revision, never from the working tree by default, so a deleted file, a PR or a committed diff shows the images it had. The rules, in order: the session must be one /api/review-image serves (available = imagePreviewSupported); doc must be a file in the current patch whose path at that side is Markdown (.md, .mdx, .markdown, or config.json markdownExtensions) and that side must exist (404 not-in-diff / absent); src (the source exactly as written; the client never trims it, and the route drops leading and trailing ASCII whitespace from it and from every reference alike, as a browser's URL parser does) must be a plain path — no scheme, //, backslash or control character, at most 2048 chars, ?query/#fragment dropped, %xx decoded — naming an image by extension (400 bad-request, 415 not-image), checked before anything is read; it resolves against the doc's folder at that side (a renamed doc's old side uses its old folder; a leading / is the repository root, GitHub's README rule; in a multi-repo workspace that is the workspace root), and one that climbs above the root is 403 outside-repo; the doc's text at that side (read up to 2 MB, 413 past it) must reference src as an image — a markdown image (, <src>, with a title), a reference-style image's definition, or an <img src> value (decoded), never one inside a fenced code block or an inline code span (stripMarkdownCode) — else 403 not-referenced, so the route reads only what the file shows. In jj sessions every read names its path as a literal (jjRootFileFileset: root-file:"…", \ and " escaped, control characters as \xHH), never a bare path after --, which jj parses as a fileset expression (a|b.png would read a and b.png); this covers /api/review-image, this route and full-file contents, in both runtimes (packages/server/jj-fileset-literal.test.ts, real jj). The image itself goes through the same per-side reader as /api/review-image (one readReviewSide per runtime now serves both routes, behind the same 4-wide limiter) and is answered by the same tail, reviewImageBytesResponse in review-image.ts: the 10 MB / 50 MP caps, the LFS-pointer refusal, the sniffed Content-Type, the sandbox CSP, nosniff, CORP and ETag/304. Tests: packages/shared/review-markdown-image.test.ts (the decision table over a fake reader) and packages/server/review-markdown-image.test.ts (both runtimes against a real repo).
Owner approval "review-diagrams-on-demand" (2026-10-23; issue #2096). Mermaid and Graphviz fences in a Markdown file's Read and Changes views, and a guide overview's Mermaid diagram, draw with ui's diagram engine (DiagramBlock: themed, zoom, the popout), read-only. The single-file review page still carries no diagram runtime (the earlier owner rule: diagrams return to code review only through true lazy loading, never by bundling; tests/entry-assets.test.ts): the engine is three separate files the review server serves and the page imports by URL only when a preview or guide overview actually holds a diagram fence.
- The files (
apps/review/diagram-engine/build.ts, run byapps/review'sbuildafter the page build intoapps/review/dist/diagram-engine/):engine.js(ui'sMermaidBlock/GraphvizBlock→DiagramBlockpath: canvas, overlay, popout, the renderer slot and sanitizer; about 190 KB, entryengine.tsx),mermaid.js(the Mermaid runtime with ELK, about 4.8 MB) andgraphviz.js(@viz-js/viz, wasm inlined, about 1.3 MB), each a minified ES module. The engine brings no React and no copy of ui's stateful modules: imports of React,react/jsx-runtime,react-dom,ThemeProvider,config(the store),utils/identityandutils/mathbecome modules that read the PAGE's instances from a host object (DIAGRAM_ENGINE_SHARED_MODULES,packages/review-editor/utils/diagramEngineContract.ts; RollupsyntheticNamedExports), so hooks, the theme context and the config store are the page's own. The build fails when the engine would bundle a stateful ui module (packages/ui/config/, storage, the theme registry, the identity and math slots, ThemeProvider), any repository module that defines a React context (its ownanchorClaimsexcepted), React or a runtime. The renderer slots'import('mermaid')/import('@viz-js/viz')(exactly one site each inutils/mermaid.ts/utils/graphviz.ts, or the build fails) are rewritten to imports of the URLs the host carries, so the ui source and the guides.show viewer bundle are unchanged. Mermaid's ownimport("katex")goes toutils/mermaid-math-slot, which typesets$$labels with the page's math renderer, so the runtime carries no second KaTeX. The Source pane (CodeMirror) is stubbed out: code review never edits a diagram's source.build:hookcopies the folder toapps/hook/dist/diagram-engine/; build:opencode and Pi's build copy it into their packages (diagram-engine/, gitignored, in each package'sfiles). - Serving (
packages/shared/diagram-engine-assets.ts, vendored to Pi): the review server takesdiagramEngine(the three files' text, or a function that reads them; the CLI'sapps/hook/server/diagram-engine.tsreaches them through literal dynamicimport(..., { with: { type: "file" } })and reads the embedded path withBun.file, whichbun build --compileembeds and a source checkout without the files survives (atype: "text"dynamic import of the 4.8 MB Mermaid file cost ~2.4 s of startup in a compiled binary on bun 1.3.14; on 1.4.4 both take ~2 ms, but Bun 1.4 stores atype: "text"import that is not pure ASCII as UTF-16, twice its size, sotype: "file"keeps the binary ~5 MB smaller; the app pages are embedded the same way, see project-and-development.md); Pi and OpenCode read their package folder), hashes them off the request path at start (warm()), advertisesdiagramEngine: { engine, mermaid, graphviz }on/api/diff(paths/assets/diagram-engine/<name>-<sha256 16 hex>.js; absent when the host has no complete set) and answersGET/HEAD /assets/diagram-engine/<name>-<hash>.jswithtext/javascript; charset=utf-8,Cache-Control: public, max-age=31536000, immutable,nosniffandCross-Origin-Resource-Policy: same-origin; any other name under the prefix is404(never the app page), other methods405. Remote and--tailscalesessions get them compressed exactly as the app page (prepareAppHtml's newcontentTypeargument; its cache now holds 8 bodies). Both runtimes: Bunpackages/server/review.ts, Piapps/pi-extension/server/serverReview.ts; the OpenCode 1 embedded/plannotator-reviewpasses its package folder; OpenCode 2 runs the CLI. The host allowlist and the cross-origin write guard apply as to every route. - The page (
packages/review-editor/utils/diagramEngine.ts,components/ReviewDiagramFence.tsx): App reads the advert once from/api/diff(parseDiagramEngineUrls: three same-origin paths, else none) into review state (diagramEngine).MarkdownFilePreview'srenderBlockhands a Mermaid or Graphviz fence (diagramLanguages, now exported by@plannotator/ui/components/diagramLanguages) toReviewDiagramFence, andReviewGuideHostpassesrenderOverviewDiagram(components/guide/overviewDiagram.tsx, Mermaid only; an HTML picture keeps the chain's note). The first such fence installs the host (globalThis.__plannotatorDiagramEngineHost: the shared modules and the runtime URLs) and imports the engine by URL (import(/* @vite-ignore */ url), which the single-file build leaves alone), once per page; the engine then imports each runtime on its first diagram of that kind. Until it lands the fence shows as code; a failed import shows the code with a quiet note and Retry, and is forgotten so a later fence tries again. No advert (an older server, a host without the files, the demo): code, as before. The Source view, a review without diagram fences and a guide without an overview diagram request nothing. - Measured (2026-10-23, Apple M-series, compiled binaries of main and this change, 5 headless Chromium loads each): the review page grew 4.8 KB (17,199,799 to 17,204,622 bytes; 3 KB gzipped); the engine files are 192 KB, 4,835 KB and 1,318 KB; the median time from navigation to the file tree (about 485 ms),
/api/diff(about 97 ms) and process start to ready (about 670 ms) were unchanged. Tests:packages/review-editor/utils/diagramEngine.test.ts(the loader),components/MarkdownFilePreview.test.tsxandcomponents/guide/overviewDiagram.test.tsx(DOM: drawn by the engine, code without it, the note when it fails),packages/server/diagram-engine-assets.test.ts(both runtimes: the advert, the route's headers, 404/405, no engine, remote compression),tests/entry-assets.test.ts(the page imports no engine, only the loader imports by URL, the built files hold their runtimes apart with no bare imports), andtests/e2e/review-diagrams.spec.ts(compiled binary: Read and Changes draw both diagrams with each file requested once; a review without diagrams and the Source view request nothing).
Viewed marks are independent of annotation drafts and survive feedback submission,
server restarts, and reopening a review. packages/shared/review-progress.ts owns
fingerprinting, storage and request validation, mirrored into Pi by vendor.sh.
GET/POST /api/review-progress?snapshot=<snapshotId> loads or updates progress;
writes carry the server-issued scope key and displayed per-file fingerprints and
reject stale snapshots. The review UI restores automatically through
useReviewProgress; explicit viewed/unviewed mutations (including auto-view and
stage-to-view) save immediately, and pending saves flush before switches/decisions.
Storage is ${dataDir}/review-progress/{scopeHash}/{pathHash}.json: atomic per-file
records prevent independent tabs/processes from overwriting unrelated marks.
Local Git scopes include canonical worktree root, branch and comparison selection
(base ref only for base-relative modes), never HEAD except when detached. PRs use
their URL and layer/full-stack scope. Workspace/non-Git reviews and piped patches
keep the existing draft behavior. Local Git carries a generation-time
fileIdentities sidecar: --raw --patch --no-abbrev supplies object IDs, paths and
modes without changing rendered patch bytes or existing annotation draft keys.
Bounded worktree hashes are checked against the displayed index line; no live
files are read at click time. This also covers mode-only changes and pure renames.
Files without reliable identities (including oversized untracked files) cannot
restore as viewed. Platform text patches use per-file patch hashes when full IDs
are absent; opaque binary/metadata-only patches without IDs cannot restore.
A mismatch is unviewed regardless of the auto-mark setting. Explicit unchecks
override platform seeds; in-session auto-view suppression survives content refresh.
Progress loading has explicit loading/ready/unsupported/error states: unsuccessful
loads preserve current marks and retain the legacy draft fallback, and a later
mutation or flush retries errors. Requests and the entire pre-decision/switch flush
each have a five-second limit, so stalled persistence cannot block review actions
indefinitely; a timeout warns and unsaved edits remain pending for a later retry.
Legacy draft viewed fields are ignored only on
progress-enabled surfaces (and deferred while capability detection is pending).
Purge uninstall removes review-progress; ordinary uninstall preserves it.
Opt-out: PLANNOTATOR_REVIEW_PROGRESS=0 or { "reviewProgress": false } (see the
environment table); the server then captures no progress snapshot and the client
falls back to draft-based viewed tracking.
Guided Review ticks mark files viewed (#1786). Ticking a guide section
"Reviewed" (live job or saved:{id} guide) marks its files viewed through the
same path as the per-file Viewed checkbox (handleGuideMarkFilesViewed in
packages/review-editor/App.tsx: durable progress, auto-view suppression lifted,
/api/pr-viewed in PR mode). A file the guide splits across chapters is marked
only once EVERY chapter showing it is ticked; refs not in the diff on screen are
skipped; un-ticking unmarks nothing (filesViewedByTickingSection,
packages/review-editor/utils/guideReviewedViewed.ts). Not gated on the
auto-mark setting (it is an explicit gesture). Auto-mark on scroll still does
not run inside the guide. The guide chain and the guides.show viewer are
unchanged: the host wraps onToggleReviewed in GuideScreen.
GitButler is a distinct VCS provider, ordered after JJ and before Git in both Bun and Pi. It is selected only while symbolic HEAD is refs/heads/gitbutler/workspace (or legacy gitbutler/integration) and the repository has GitButler's local target-ref configuration; a leftover database or an ordinary branch with the reserved name is not detection. An active workspace requires but >= 0.21.0 on PATH, and a missing/incompatible CLI is an explicit error rather than a fallback to ordinary Git staging against the synthetic workspace commit. --gitbutler forces this provider; --git remains the escape hatch.
The default gitbutler:workspace view is GitButler's reported merge base versus the working tree plus untracked files, so it includes every applied committed change and assigned/unassigned worktree change. Multi-branch stack views are committed-only merge-base→stack-tip Git diffs; branch views are committed-only first-parent segment diffs. Client IDs encode branch-name anchors, never GitButler's transient CLI IDs. Do not concatenate independent GitButler hunks: their bases can differ. Assigned worktree hunks stay in Workspace until GitButler exposes an authoritative combined stack diff.
GitButler assignment is not the Git index, so the provider never opts into stage/unstage. Git-status sections, commit history, remote-base discovery/fetch, and the first-run Git setup remain vcsType: "git" only. File expansion uses the exact object range for committed views and merge-base/working-tree pair for Workspace; fingerprints cover the visible Git content plus canonical stack/branch topology. Nested multi-repo mode maps only workspace-current to GitButler; staged/unstaged/last modes are unavailable when a GitButler child is present.
Ask AI's "changes under review" context for code review is generated by the shared agent-review prompt machine (buildAgentReviewUserMessage / buildAgentReviewUserMessageForTarget in packages/server/agent-review-message.ts) — the same machine the launchable review jobs use — and is delivered on the user's messages, not the system prompt. The review server computes it for the current view (buildCurrentAiReviewContext in packages/server/review.ts, mirrored in apps/pi-extension/server/serverReview.ts) and ships it as aiReviewContext in the diff payloads (/api/diff and the switch/PR endpoints). The client (packages/review-editor) latches it onto each question via buildReviewContextPreamble (packages/ui/utils/aiPrompt.ts): the full block on the first message and whenever the view changes, a short reminder otherwise (never re-pasting a large diff). This keeps the agent looking at exactly the on-screen changeset across every mode (uncommitted/untracked, branch, merge-base, stacked-PR full-stack, hide-whitespace, PR worktrees, workspace, GitButler, jj). The code-review system prompt (buildCodeReviewPrompt in packages/ai/context.ts) is intentionally role-only.
A comment from a review agent this session launched (its source is a job source from useAgentJobs, never a name prefix) gets an Explain finding action (sparkles) in its hover row: inline in the diff, in the file banner, in the sidebar, and in the agent job's findings list. It asks Ask AI to check the finding against the code and explain it (packages/review-editor/utils/explainFinding.ts). The finding text and the agent's reasoning travel as fenced untrusted data; the question targets the finding's lines when they are in the diff on screen, else the file with a short note. The chat shows only "Explain this finding: …" (AskAIParams.displayPrompt); the agent gets the full prompt. The action is shown only when Ask AI is available and is disabled while a question runs. With "Ask this session" the question goes to the agent that opened the review, like any other Ask (the session header tells it not to edit files), and a busy session offers the usual "Ask when it finishes" / "Interrupt and ask now".
The board lives inside Reviews (the owner's pick, take C): there is no sidebar row of its own, and the Reviews row has the pull-request icon. On a desktop the board fills Reviews' right pane while no review, stack or System drawing is open there (PullsPage's prBoard, SheetPage mode="pane"; its Open | Merged kept in memory). A phone has no right pane: a "Pull requests · N open · N need you" row at the top of the Reviews list opens the board's own page (#prs, with a back arrow to Reviews; Code review off sends the route to #reviews). A PR opened from the pane is &from=reviews and its Back returns to Reviews; on a desktop a stack page's Back and a PR opened from #prs also go back to Reviews (prsHome / prsBack in App.tsx). Code in packages/inbox/prs/, styles in prs.css (its @source in apps/inbox/index.css); tests in prsInReviews.test.tsx.
- Scope, "everywhere, mine": PRs in any repository that ask for the person's review, are theirs or are assigned to them, plus every open PR of the Inbox projects' repositories, on this machine and each linked one ("The PR board" in
inbox-machines.md: a linked machine's PR is read and closed, reopened or merged by that machine's gh):GET /api/inbox/pulls?everywhere=1&machines=1(see the Server API table inserver-and-storage.md), on the Reviews page's clock (useSheetPulls), no extra polling. The server answers it and Reviews' list from one read per host. A repository that is not a project says "not a project". - The Sheet: a header line ("N open, N need you, N with failing checks, N landed this week"), a bar (filter by title, author, repository or number; Open | Merged, Merged the last 14 days; "Closed on GitHub" a link to the forge's search), then one section per repository, each PR a number tile with its checks mark. A stack shows as joined tiles, folded to one strip (a mark per layer, its counts, a link to the stack page) only over 8 PRs (
FOLD_OVER). The filter dims misses and hides repositories with no match. Hidden while nothing is listed, the header's counts would repeat the empty words. - Needs you and order live in one pure module,
packages/inbox/prs/sheetModel.ts(tests beside it): needs you is a review asked of the person and not yet given, or their own PR with changes requested. Within a repository: waiting longest on you (oldestupdated_atfirst), then a layer that blocks a stack, then changes requested, then ready to land, risk (usePullRisk) breaking ties before time. Repositories are ordered by how many need you, then by open count. - Tile popover: title, author, state, checks, the stack line, and Open, Open on GitHub, and Merge. Open (and a mouse click on a tile) opens a single open PR's launchpad in Reviews (
#reviews&stack=…; the owner, 2026-11-11;tileOpensinsheetModel.ts, once Reviews' own list has the PR), else the existing PR view (#prs&stack=…&layer=…&from=sheet): a layer of a stack of several, a merged PR, a PR in a repository that is no project. A mouse click on a tile opens it; hover or focus shows the popover; Enter or a tap pins it with focus on its first action; on a phone it is a bottom sheet. Merge shows only when the list says the PR can land (mergeOffered: open, no conflicts, not changes requested or review required, checks not failing or pending, a head sha). The first click turns it into Confirm merge, the second postsPOST /api/inbox/pulls/merge, which asks the forge again and merges at that head with the repository's default method (packages/shared/inbox-pull-merge.ts); a refusal shows its words and Merge is withdrawn. Merge sits in one slot as wide as its widest word (Merge, Confirm merge, Merging…, Merged stacked in one grid cell), so the second click lands on the same button; the confirm hint goes under the buttons on a desktop and above them in a phone's bottom sheet. From the second click the popover is held open (the pointer leaving or another tile does not close it); "✓ Merged" shows in the slot forMERGED_SHOWN_MS(1.5 s), then the popover closes, the PR leaves Open at once (the page marks it merged before the next read) and the list is read again; the server marks it merged too (markMerged), so the read cache and a forge search that still says open do not bring it back. - Stack page (
#prs&stack=<layer key>): layers top first, the base branch at the bottom, merged layers greyed in place, the next to land lightly filled; a row opens that layer in the PR view. - A range of layers (approval "inbox-pr-dashboard", q-0a2467a4;
prs/stackRange.ts,prs/StackRangeBar.tsx): with three or more open layers the stack page offers Choose a range under the list; in it a click or tap picks an end instead of opening the layer, and a shift-click on a row does the same from outside it. One end, then the other on the same line of the stack (a sibling branch's layer starts again from it; merged layers are no ends), the same one again lets it go. The bar sticks above the list: "N of M layers", once both ends are picked "Layers i–j as one diff" (i and j the page's own numbers) and Open as one diff, and Clear. Picked rows are filled. It opens the PR view on layer j as "Layers i–j" (&range=<layer i's key>), the compare from the branch layer i is based on to layer j's head; a range from the lowest open layer opens Whole stack instead, and a range the list no longer holds as one shows layer j's own diff (liveView). Its title is "Layers i–j as one diff", the rail adds its "Layers i–j" row, and a verdict goes to the stack's review thread as Whole stack's does (the agent reads it as the stack from layer i's base). No keys. - Changed since you looked (q-6cf84c0b;
prs/looked.ts): the PR view marks each layer its diff shows as looked at, at the head shown and when. The look is kept on the machine that lists the PR (inbox/pull-looked.json, server'sinbox-pull-looked.ts,POST /api/inbox/pulls/looked), as the Board's look is kept on its project's machine: a linked machine's PR's look goes there through the forward (rule 8'sset, held while it sleeps; the newer look wins), and every PR on the board carries itslooked, so every window, another browser, the phone over the tailnet and a linked machine's window all mark the same layers. The browser keeps a copy (plannotator-inbox-pull-looked, the newest 400) for at once, and for a linked machine too old to keep looks (nolookedon itsmachinesentry, markpulls-looked): nothing is sent there, nothing is shown, and that copy marks its PRs in this browser only. A look the copy holds newer than its machine's (one from before, or one that did not arrive) is sent once. Viewed ticks are still this browser's only. An open layer whose listed head is not the one last opened gets a dot after its number on the stack page, and the header counts them ("N changed since you looked"); a layer never opened is not marked. In the PR view the rail offers Since you looked while the layer's head moved since that look (still offered for the rest of the visit after the page marks it), which opens the compare from that commit to the head (&since=<sha>); a PR with no stack rail gets a row with its own number back to its diff. - Table (approval "inbox-pr-board-bulk"): a desktop's bar has Grid | Table after Open | Merged; a phone has no switch and keeps the grid. The choice is per window:
#prs&layout=tableon the page (sheetLayoutOf/sheetLayoutHashinprs/tableModel.ts; Grid writes nothing), App state in Reviews' pane, as Open | Merged. The table (prs/SheetTable.tsx) has one row per repository (its name and the section's counts), then one 40 px row per PR: Pull request, Title, Author (20 px face, "You" or the login), State (the popover's status words), Checks (Passed / Running / Failing), Risk, Updated (ageShort) and Size. A stack's layers run in landing order, the first with the layers mark (it opens the stack's page), the rest with an elbow; a strip never folds them. A header sorts its column inside each repository, a stack moving as one block by its next layer to land; the same header again reverses (sortUnits,nextSort); the sort is kept in memory. A row's click is a tile's (onOpenPull); its number is the row's button for the keyboard. The filter dims rows as it dims tiles. The bar and the header stick while the rows scroll. The table's own width (a container query) drops Risk under 1000 px, Updated and Size under 920 px and Author under 640 px, so the title keeps about 200 px (Reviews' pane at 1440 is about 750 px). Merged with Table on lists the merged PRs as rows. Tests:prs/tableModel.test.ts,prs/sheetTable.test.tsx. - Select mode (approval "inbox-pr-board-bulk", the owner's pick B: a mode of its own, never always on): no box shows anywhere until Select (at the end of the filter row, Open only) is pressed; it turns into Done, which leaves the mode. In it, every open tile has a box and is a checkbox (
role="checkbox", its words its name), each repository's head has a box ("Select all in ", its name and tooltip), and the table gets a first column of boxes, "Select all" in its head and one per repository row. A tile's or a row's click (Enter, a tap) picks it and opens nothing, with no popover; a shift-click picks every open PR between the last one clicked and this one, in the order on screen (the table's sort included; a folded strip's layers are not in the grid's order). A box over a group picks its open PRs that the filter does not dim, half-filled (aria-checked="mixed") while only some are, and lets them all go when all are. A picked tile or row is filled (--ib-cur-bg), never outlined; only a picked tile has a fill, so a tile that needs you drops its purple in the mode and reads as its table row does, bold in the primary colour (the owner on #3247: unpicked purple tiles looked more picked than picked ones). While something is picked, the bar in place of the filter row is "N selected" and Clear (Clear leaves the mode); on a phone the filter row stays, with Done, and the count and Clear are a sheet at the bottom (44 px). On a desktop the bar sticks while the mode is on. A pick that stops being open drops out; Merged leaves the mode. Outside the mode every click is as before. Its actions are Merge, Close and Start review thread (below). Escape leaves the mode too (the owner's "Yes" on #3247): the same Escape as everywhere, scopeinbox-pr-board(shortcuts/prBoard.shortcuts.ts), listed on the map's "Close, one layer at a time" row with no words of its own. SheetPage reads it on the document, so an open menu, the filter's list, a field, a dialog or anything inside the page that used the key keeps it first; once it acts it marks the key used and App's ladder on the window stands down; focus on Clear or a box moves to Select. Tests:prs/sheetSelect.test.tsx. - Bulk Merge (approval "inbox-pr-board-bulk": a confirm, and "merge the green ones and tell me about the rest"): the bar while something is picked reads "N selected" · Merge N · a hint · Clear (a phone's sheet: the same, 44 px). N counts the green picks (
prs/bulkMerge.ts): the popover'smergeOfferedplus, in a stack, only the layer that lands next (one above would merge into that layer's branch). Every other pick names why in the board's words ("#1190 can't merge now: its checks are failing.", "it lands after #412", a draft, a conflict, GitHub or GitLab not having said whether it conflicts, changes asked, a review still needed, checks running, no head commit); the hint says how many stay ("2 can't merge now; they stay selected."), and with none green there is no Merge, only the hint. The first click turns Merge into green Confirm merge with "Click again to merge 3 pull requests. A merge can't be undone." (a phone: "Tap again to merge 3. …") and lists under the bar what merges (number and title) and what stays and why; a click anywhere else, another pick, or Escape (one layer: select mode stays) drops it. The second click merges one PR at a time through the popover's ownPOST /api/inbox/pulls/merge(confirmed: true, the head the list showed; the server asks the forge again and uses the repository's own method), the bar reading "Merging 2 of 3…" with Clear, picking and Escape held. Each merged PR leaves Open as it lands (mergedHere); a refusal is never sent again by itself. The report under the bar: "Merged #5, #20.", each refusal after its number in the server's words, each pick left out as "#8 Not merged: its checks are failing."; the refused and left-out picks stay picked, and the list is read again once. Another pick, Clear or Done ends the report. No server change. Tests:prs/bulkMerge.test.ts,prs/sheetMerge.test.tsx. - Bulk Close (approval "inbox-pr-board-bulk": the count with Undo): Close N after Merge in the bar (and in a phone's sheet), N every pick (all are open). No confirm: Undo is the pause. One click closes the picks one at a time through
POST /api/inbox/pulls/close(the host asked first; Bun only), the bar reading "Closing 2 of 3…" with picking, Clear and Escape held. Each closed PR leaves Open as it goes; the report under the bar says "Closed #7, #20." and each refusal after its number in the host's words ("#8 It is already merged."), which stays picked, never sent again by itself. The window's toast says "Closed 2" with Undo for 8 s (CLOSE_UNDO_MS; its button only, noZ): Undo reopens exactly the PRs that Close closed (POST /api/inbox/pulls/reopen, which takes only a PR this Inbox closed in the last 5 minutes), "Reopening 1 of 2…", picks them again in select mode (back on if it was left), reports "Reopened #7." and each refusal in the host's words (a deleted head branch), and toasts "Reopened 1". A run started from the toast waits for one under way (queue). Closing and undoing leaves closed and reopened events on each PR and notifies its watchers. Tests:prs/sheetClose.test.tsx,packages/shared/inbox-pull-close.test.ts, the routes inpackages/server/inbox-pulls.test.ts,tests/inbox-pull-close-window-only.test.ts. - Start review thread (approval "inbox-pr-board-bulk": one thread per repository; the several-PR words approved as written): after Close N in the bar (and a phone's sheet), "Start review thread", or "Start 2 review threads" when the picks to start are in two repositories. No confirm: one click starts one review thread per repository and machine, one after another ("Starting 1 of 2…"), through
prs/startReviews.ts, the same steps as New review's Start for one PR without the box: To is what that box fills in (reviewDefaultTo: a live agent of that repository's project, else a new agent where the machine can start one), skipping an agent that is working;pulls/ownerwithvalidate_onlyand that project; the thread (POST /api/inbox/messages); thenpulls/ownerwith its PRs andask: "guide". One PR's thread is today's (pullHandoffMessage,pullHandoffThreadName); several getpullsHandoffMessageand "Review #7, #8 and #9" (pulls/manyHandoff.ts), lowest number first, at most 20 (the rest say why). A linked machine's PRs start there: its compose read, its agents and project, the thread andpulls/ownerthrough the forward (forge, never held: an asleep machine answers " cannot be reached now." and starts nothing; a start the forward holds is cancelled and said the same way). A pick with a live review thread (the list's link, or one started here since the last read) gets no second: it is linked. The report under the bar: "Started 2 reviews: ledger (3 PRs), web (1 PR)" with each repository a link to its thread, "Already in review: #8 with Codex." with each number a link, "#30, #31 Not started: Mac mini cannot be reached now." (or "tool is not a project.", "no agent can start in web."), and "#5 Not tied to its thread: " when the thread started but the owner route refused. Such a thread is kept in the window (prs/reviewStarts.ts, localStorage): its PRs read as in review across a reload, never given a second thread, and the tie is tried again each time the board opens until it holds. A group's Send key is kept for 10 minutes, so a press again after a Send that failed or went late replays it (the Inbox answers the thread it wrote); a hold that was cancelled forgets its key, which would only answer the cancelled hold. A linked machine whose Plannotator has nopulls/ownerdoor route yet gives "Update Plannotator on to start agents there." (inboxMachineLaunchWords). A phone shows each heading ("Started 2 reviews", "Already in review") on its own row with one 44 px row per thread under it. What started or was linked leaves the picks; what could not stays picked. A run that started only new agents toasts "Started 2 reviews" with Stop (8 s, its button only), which stops those launches (launchStop; their threads stay) and toasts "Stopped 2"; one given to a live agent has no Stop. A tile's popover has Open review thread while its PR has a live review thread. Tests:prs/sheetReview.test.tsx,pulls/manyHandoff.test.ts, the door inpackages/server/inbox-machine-pulls-linked.test.ts. - Checks mark is one small component,
ChecksMark.tsx, to swap the style in one place. - Tab and Enter only; no new shortcuts.
Show me in the Inbox asks the session for a real Shape (see "Show me" in inbox-files-and-guides.md; plannotator shape --help is the agent's side). plannotator shape answers only with Shape's own switch on (shapeBoardsOn in packages/shared/shape/switch.ts; approval "code-review-029-shape-off": Code review alone brings none of Shape). An older agent's plannotator review draw … or review drawings … gets INBOX_REVIEW_DRAW_GONE (core inbox-review.ts) on stderr and exit 1 while Code review and Shape are both on; with either off, the review parse takes them (the feature never shipped, so no new words). index.ts checks that only when the arguments have the old command's own shape (isReviewDrawCommand in apps/hook/server/review-draw-command.ts: draw then --file, --review, --turn or --help; drawings then one msg_… id or --help), and reads config.json only for those two words, quietly: a broken one is Code review off. Off, the review parse takes them exactly as it always did (apps/hook/server/show-me-off.test.ts). The HTTP routes are gone with it: /api/inbox/reviews/:msg/drawings is the unknown route. A review's html diagram (an old guide's overview.diagram, or a chapter's sections[].diagram) keeps Shape's drawing rules (checkInboxDrawing); an agent reads the html kind (get_guide_brief's rule and schema kind, inboxReviewChapterDiagramDoc(shapeOn)) and the window draws it only while Code review and Shape are both on. A chapter's Mermaid diagram is offered with Code review on whatever Shape says (the brief, and the review skills' chapter lines, which name Mermaid only while Shape is off).
Ask AI providers are detected independently from installed/authenticated local CLIs, then the UI picks a default from the detected Plannotator origin. The mapping lives in packages/core/agents.ts (re-exported via the packages/shared/agents.ts shim) and is applied by packages/ui/utils/aiProvider.ts:
| Origin | Preferred Ask AI provider |
|---|---|
claude-code |
claude-agent-sdk |
amp |
no dedicated provider; fallback to saved/server default |
droid |
no dedicated provider; fallback to saved/server default |
codex |
codex-sdk |
opencode |
opencode-sdk |
pi |
pi-sdk |
copilot-cli |
no dedicated provider; fallback to saved/server default |
gemini-cli |
no dedicated provider; fallback to saved/server default |
mistral-vibe |
no dedicated provider; fallback to saved/server default |
qwen-code |
qwen-sdk |
dsh |
no dedicated provider; fallback to saved/server default |
DeepSeek Harness reviews opened by the @plannotator/dsh plugin's tool and commands (see "DeepSeek Harness" in plan-review.md) carry no session bridge yet, so they offer no "Ask this session" and no Settings row for the agent tool (agentToolHostOf has no dsh until the bridge has that host).
Automatic resolution is session-only and never writes a preference. Explicit per-origin choices are persisted in cookies, so a user can override the automatic match for one agent without changing the default for another.
New chat (#1981). Plan review, annotate and code review show a small New chat row above the Ask AI messages once there are any (NewChatButton, packages/ui/components/ai/; the optional onNewChat prop on DocumentAIChatPanel and the review AITab, absent for hosts, so their panel is unchanged; no keyboard shortcut). It calls useAIChat().newChat(): the thread and its Plannotator AI session id are cleared, so the next question starts a fresh session (a separate AI gets the full document or "changes under review" context again). Unlike resetThread (archive or goal setup; the editor no longer resets on a document switch, see #1001 below), newChat never stops anything: while a question is in flight (streaming, creating its session, or waiting on a busy "Ask this session"), or while a busy answer still offers "Ask when it finishes" / "Interrupt and ask now" (hasPendingBusyChoice), it returns false and the button is unavailable (aria-disabled, still focusable, the reason as its aria-describedby description), so no turn is aborted and no pending ask is dropped. It keeps the provider/model choice and the per-page record of the draft list the agent session already received (deliveredDraftsRef), because with "Ask this session" a new chat reaches the SAME host session, which still remembers earlier questions; there the button reads Clear chat and says so. Earlier chats are not kept to reopen.
One chat per session, documents named by path (#1001). In the plan/annotate editor, Ask AI is ONE chat for the whole Plannotator session, as code review's already was: switching files in a folder or bundle, opening a linked document, Back, the multi-message picker and a plan revision all keep the thread and its Plannotator AI session (aiDocumentKey in packages/editor/App.tsx is session; only archive and goal setup, other contexts, get their own, and New chat still starts fresh). The session is created from the document on screen at the first question (a separate AI gets it in its session context, unchanged; "Ask this session" gets its surface line), so that question carries nothing extra. A later question on a different document carries one short note leading the prompt (askDocumentContext.ts: describeAskDocument, planAskDocumentContext, askDocumentParams): the absolute path the reviewer is looking at now (how it is shown: rendered HTML, converted to markdown, "file 2 of 3"), "back on" when they returned to it, and up to 10 documents viewed earlier in this chat, most recent first, so the agent reads the files itself; never the document's text. A plan revision reads "The plan was revised to version N: " for a separate AI, from the additive planPath on /api/plan (both plan servers: the history version file holding the exact plan on screen; the revision poll re-reads it). "Ask this session" is never pointed at that copy (it is outside the project, so it could raise a permission prompt, and that agent wrote the revision): it gets the plan's own file, the additive planFilePath (Bun plan server, only while the hook's plan file holds the plan on screen; PlanFile.path), or just "The plan was revised to version N", and earlier versions are listed as "the plan (version N)". Only a document with no readable file (a converted URL page, an agent message, a plan from a server without planPath) carries its text, once, when it changes, and never to "Ask this session" (the agent wrote the plan or message, or can open the URL; a paste would stay in its context window). The same document twice adds nothing. The latch moves only once a question reached the session (AskAIParams.onDelivered, called once when the stream shows delivery; a busy or failed ask leaves it, and the retry that lands moves it), and a question that creates a session (first one, a provider switch, New chat) starts it over. Drafts still travel apart (draftAnnotations / contextUpdate, unchanged), and no system prompt changes. Tests: packages/editor/askDocumentContext.test.ts, the DOM test packages/editor/askDocumentLatch.test.tsx, and tests/e2e/annotate-ai-history.spec.ts (compiled binary: annotate file switches, and a claude-mod-plan revision).
"Ask this session" (session bridge). A host can let Ask AI be answered by the agent session that opened Plannotator instead of a separate SDK agent. The host implements the small SessionBridge interface (packages/ai/session-bridge.ts, vendored to Pi: host, status() = ready | busy | blocked | gone, modes { turn, transient }, ask(req, sink, signal), optional interrupt()) and passes it as sessionBridge to the server (startReviewServer / startAnnotateServer / plan ServerOptions on Bun; review, annotate and plan review on Pi), which then registers SessionBridgeProvider under id session-bridge as the ONLY Ask AI provider, behind the unchanged /api/ai/* endpoints: with a bridge (in-process or pull) the SDK providers go into a separate catalog-only registry (catalogRegistry on createAIEndpoints, set by createAIRuntime / createPiAIRuntime), so /api/ai/capabilities lists only the bridge under providers and makes it defaultProvider, and /api/ai/session answers 503 for any other provider id whatever the client saved. The catalog-only providers exist so the agent-job launchers (Review Agents, Code Tour, Guided Review) keep their discovered Claude / Codex model lists: ?activate=<id> naming one runs its discovery and reports it under catalogProviders, which only useModelCatalogs reads; Ask AI never reads that field. Without a bridge (no mod, OpenCode 1, remote mode) the SDK providers register exactly as before; in a --tailscale session with a bridge, a tailnet request from anyone but the machine's owner is answered by a second set of endpoints over the SDK providers (tailnet on createAIRuntime). /api/ai/capabilities adds label ("Ask this session · Pi") and live sessionBridge { host, status, modes } for it, models: [] (no model picker). The provider, not the host, enforces one question at a time across threads (ask_in_flight), sends no system prompt (the question carries the SESSION_ASK_HEADER line plus the surface), and never interrupts implicitly: a busy session answers agent_busy, and the client re-asks with /api/ai/query busyPolicy: "wait" ("Ask when it finishes", streams status: waiting until idle) or "interrupt" ("Interrupt and ask now", host interrupt() then ask). session_gone / session_blocked offer no other AI (there is none): the answer shows a plain note that the session that opened Plannotator is gone, or waiting on this decision, and Ask AI cannot reach it. Abort cancels only our question; the runtime detach()es the bridge before teardown so a decision/exit never stops a turn already running. Take-over (every host): once another message enters the turn answering our question (the person typing into the session, another extension's steer; never a background task's notification, an engine notice, a compaction, or on Claude Code a peer session's message), the rest of that turn answers THAT message, so the host stops streaming at once, keeps what it already sent, and settles with the bridge error code taken_over (SessionBridgeErrorCode; the provider maps it to session_taken_over with SESSION_ASK_TAKEN_OVER_TEXT, the neutral "Another message entered this session while it was answering, so the rest of the reply went to that message."; the Claude Code mod sends SESSION_ASK_TAKEN_OVER_BY_PERSON_TEXT, "You typed into this session…", when it knows the person typed it). When the answer had already finished before the other message entered (the turn's last model response stopped with no tool call: Claude end_turn, Pi stop, OpenCode finish: "stop" with no session.tool.input.started in that step, since some OpenAI-compatible providers report "stop" on a tool-calling step; and some answer text was shown), it settles done instead: a follow-up such as Plannotator's own decision never turns a complete answer into a cut one. From then on neither a Stop nor "Interrupt and ask now" stops that turn: Stop only closes the question, and interrupt() refuses (SESSION_ASK_TAKEN_OVER_INTERRUPT_TEXT) while the taken-over run lasts. The client (useAIChat) treats session_taken_over as a note, not an error: the partial answer stays and SessionAskNote renders the text under it (response.notice). Per host: Claude Code mod, prompt.submit with the question turn's turnId from an allowlisted origin (see "Claude Code mod"); Pi, a user message, or a custom message other than ours delivered right after a turn_start (a steer or follow-up), in the run answering our question; a non-triggering display-only custom message (e.g. plannotator-handoff) is appended at turn_end, outside that window, and takes nothing over; the run stays protected until agent_settled (idle on Pi without it), so an error retry of the person's run is covered; OpenCode 2, a session.inbox.delivered for another row whose kind, read from session.inbox.enqueued (item.type), is user (synthetic, compaction, move and unseen rows never take over), after ours was delivered AND the model began answering (session.step.started or any answer output), so a command's session-URL notice promoted in the same batch as the question is not a take-over. Older servers: the pull server advertises the codes it knows as features on every poll answer (SESSION_BRIDGE_POLL_FEATURES, today ["taken_over"]). A pull host (the mod's bridge.ts, runPullSessionBridgeClient) talking to a server without taken_over settles a take-over as done with the partial answer plus the note as its last paragraph (takenOverFallback), because an older server reads the unknown code as failed and its UI would replace the partial answer with the error. Client (resolveAIProviderSelection): a bridge in the list is the selection in every status, ahead of any saved pick; without one the order is unchanged. The saved provider cookies are never rewritten for this, so a pick still applies to sessions without a bridge; with a bridge the Ask AI bars and Settings → AI show only its label (no provider or model picker). Code review sends the diff's identity (buildSessionReviewIdentity), never the patch. Draft annotations (#1748): the session is the agent the feedback is FOR, so the reviewer's unsubmitted annotations never reach it as feedback. /api/ai/query ignores contextUpdate (the feedback export a separate AI still gets on every question after the first) for a bridge session; the plan/annotate editor instead sends draftAnnotations, a plain one-line-per-draft list (formatDraftAnnotationsForAsk in packages/ui/utils/parser.ts: Draft 2 (line 14): comment on "…" — …, no export title, no "pieces of feedback", no "Feedback on" headings, no skill injection), which useAIChat sends only when it differs from what the agent session last RECEIVED (draftAnnotationsToSend; recorded once the stream shows delivery, so a busy or gone ask resends it; kept per page, not per Ask AI session, because a new thread or a document switch is a new Ask AI session on the same agent session), and '' once when every draft was removed. A string in the list that reads like the end marker (any case or spacing) is neutralized, so a draft or page text cannot close the frame early. formatSessionAskText frames it between the surface and the question with SESSION_ASK_DRAFTS_LABEL ("…Do not act on them; the reviewer will send them when ready…") and SESSION_ASK_DRAFTS_END (or SESSION_ASK_DRAFTS_CLEARED), in turn and transient mode alike; the system prompt is untouched. The annotate agent terminal's Ask prompt uses the same list and frame (buildTerminalAskPrompt, deduplicated per terminal session). Code review sends no annotations to Ask AI at all. Pi (apps/pi-extension/pi-session-bridge.ts): review, annotate, last and plan review (plan review no longer blocks the session, see "Pi plan review does not block" below), off in remote mode; the question is a pi.sendMessage({ customType: "plannotator-ask", display: true, details: { askId } }, { triggerTurn: true }) turn read back from message_start / message_update text deltas / tool_execution_start / agent_end; listeners register once at load because pi.on returns no unsubscribe before Pi 1.0. OpenCode 2 (apps/opencode-plugin/opencode-session-bridge.ts): review, annotate and last ask a real turn — ctx.session.prompt({ id, text, delivery: "steer", metadata: { source: "plannotator-ask" } }) under a message id generated in OpenCode's own ascending msg_ format, streamed back from ctx.event.subscribe() (session.inbox.delivered with our id starts the answer, then session.text.delta / text.ended / tool.input.started, ended by session.execution.succeeded|failed|interrupted), with session.wait + session.context as the fallback when the event stream is missing (upstream #44788). Delivery is "steer", not "queue", on purpose: every V2 command leaves its session-URL notice as a pending steer row, and a queued question would wake the session with that notice promoted alone as its own model turn (seen live on 2.0.22). Busy comes from the execution events cross-checked by a single outstanding session.wait probe; abort and "Interrupt and ask now" use session.interrupt (whole execution), only on a turn that is ours or on the reviewer's explicit choice. Plan review answers from context only ("Quick answer from this session · OpenCode", modes { turn: false, transient: true }): submit_plan is a pending tool call, so a real turn cannot run until the decision (a prompt sent then waits for the tool result, verified live), and markPlanReviewPending makes EVERY bridge on that session report blocked so nothing can interrupt the review. The quick answer is session.generate (no transcript write; verified live on 2.0.22 with OpenAI during a pending submit_plan, and @opencode/ai's normalizeToolHistory fills the unfinished call with an error result for every provider); it still offers the model its tools, so the question carries SESSION_ASK_TRANSIENT_NOTE and an empty answer (a tool call) is reported as a failure. The embedded plan server takes the bridge in-process; review/annotate/last and the CLI plan fallback run the plannotator CLI as a child and use the pull bridge below. OpenCode 1 has no bridge (a second adapter over V1's different message/event model, not a small lift). Claude Code answers through its mod over the pull bridge below (review, annotate, last and plan review, all real turns; see "Claude Code mod"); without the mod Claude Code has no bridge.
Pull bridge (host-neutral, packages/ai/session-bridge-pull.ts server half, vendored to Pi; session-bridge-pull-client.ts host half). For a host that runs the Plannotator server as a SEPARATE process and must not open a listener of its own (the OpenCode plugin's CLI child and the Claude Code mod). The host generates a per-launch secret and starts the server with PLANNOTATOR_SESSION_BRIDGE_TOKEN (>= 32 chars), PLANNOTATOR_SESSION_BRIDGE_HOST (opencode / claude-code / pi) and optional PLANNOTATOR_SESSION_BRIDGE_MODES (turn,transient; default turn). The Bun CLI takes that config at its very first line (takeEnvPullSessionBridgeConfig, cached once per process; createAIRuntime reads the cache) and deletes the three variables, so nothing it spawns (git/gh before the server starts, agent jobs, terminals, the auto-update wrapper) inherits the token. Deleting is only half of it: on Bun, Bun.spawn, Bun.spawnSync and node's synchronous spawnSync / execFileSync / execSync hand a child the environment the process STARTED with whenever env is missing or undefined (Bun's documented SpawnOptions.env), deleted variables included, and Bun.which without { PATH } searches the startup PATH. So every such spawn passes the live env explicitly, env: childEnv() (packages/shared/child-env.ts, vendored to Pi; childEnv(extra) lays variables over it, an undefined value removes one) or an env built from process.env, and Bun.which gets { PATH: childPath() }. The same holds for every other variable the CLI takes and scrubs (PLANNOTATOR_HOST_RESULT_FILE, PLANNOTATOR_HOST_MESSAGES_FILE, PLANNOTATOR_HOST_REVIEW_ID). Node's async spawn / execFile and Bun Shell read the live env. tests/child-env-guard.test.ts fails on a Bun or synchronous spawn without env (or with an optional x.env field that may be undefined) and on a one-argument Bun.which in the production trees (exemption: a child-env-guard: <why> comment), and apps/hook/server/scrubbed-env-cli.test.ts runs plannotator review as a real process with logging stubs for git, gh and the agent CLIs and checks none of them sees a scrubbed variable; --tailscale keeps it since #2166 (this machine and the owner's Tailscale login only; see "Ask this session" over the tailnet under "Tailnet sessions"). The runtime registers the same SessionBridgeProvider over it; it is off in remote mode (and an in-process bridge wins). Pi's createPiAIRuntime accepts the same config as its pullSessionBridge option (no env takeover: Pi itself always bridges in-process). The host learns the port (OpenCode: PLANNOTATOR_READY_FILE) and then talks to two endpoints on http://127.0.0.1:<port>, both POST + JSON with Authorization: Bearer <token>: /api/ai/bridge/poll { status?, modes?, waitMs? } long-polls (clamped to 25s; answers early when there is work) and returns { commands, closing?, superseded? }, commands being { type: "ask", askId, text, mode }, { type: "cancel", askId } and { type: "interrupt", interruptId }; /api/ai/bridge/event takes one event or { events: [...] } — started, delta, tool, done, error (per question, code one of busy|blocked|gone|aborted|failed|taken_over; anything else reads as failed); every poll answer also carries features (optional protocol features the server knows, SESSION_BRIDGE_POLL_FEATURES), status, and interrupted { interruptId, ok, message? } — and answers 409 { code: "ask_not_active" } for a question that is no longer running, which tells the host to stop it. An interrupt that reaches a client whose bridge reads gone answers ok: false without calling the host. Commands are re-sent every ~5s until acknowledged (any event for that question; interrupted for an interrupt), so hosts dedupe by id. Guards, in order: a loopback Host with the server's own port (the runtime's authorizeSessionBridgeRequest, 403 session_bridge_forbidden_host), no Origin header (403, a browser is never the host), the bearer token (401); without a pull bridge both paths answer 404, which an older-binary-aware host treats as "no bridge". Liveness: until the host's first request the bridge reports ready (a question waits for the first poll); no first request within 30s, or 30s with no open poll after that, is gone, and a running question then fails session_gone. The newest poll supersedes an open one. A reviewer's Stop drops a question the host never confirmed, else queues cancel and frees the slot when the host confirms (or after 15s); detach() (decision / shutdown) drops only unconfirmed questions, and dispose() answers the open poll closing. PullSessionBridge.connected says the host has polled (an event alone reports no status), so status() is what it reported: the Inbox's Ask AI waits for it (inbox-messages.md), and it is the one server that sets keepRunningOnDisconnect on createAIEndpoints (default off: a dropped stream aborts). Both runtimes route the two paths through createAIEndpoints (pullBridge dep), and Bun lifts the idle timeout for the poll (isLongLivedAIEndpointPath). Tests: packages/ai/session-bridge-pull.test.ts (fake host over the real client: streaming, early question, busy wait / interrupt, abort before and after pickup, host disappears, never connects, transient, bad token / Origin / rebinding Host, supersede, dispose, detach), packages/server/ai-runtime.sessionBridge.test.ts (env takeover, scrub, remote-off), apps/opencode-plugin/session-bridge-cli.test.ts (plugin ↔ CLI child end to end).
GitHub attachment images in PR text. For a PR on https://github.com
(proxiesGitHubImages in packages/review-editor/utils/prImage.ts), PR descriptions and
comment/review bodies route GitHub attachment images (github.com/user-attachments/…,
user-images and private-user-images.githubusercontent.com) through the existing
/api/pr-artifact-content endpoint, which checks the active PR context and fetches with
provider credentials on the server. Every other image keeps its direct URL. A GitLab MR or a
GitHub Enterprise PR gets no rewrite at all, since the server refuses github.com attachments
there (isGitHubArtifactHost). Raw HTML keeps <picture><source> and srcset, each
candidate URL rewritten the same way (responsiveImages on RenderedMarkdown;
prImageSrcset in comments), so a dark-mode <source> still applies. In the description a
GitHub-PR image that fails to load becomes the dashed "Image could not be loaded"
placeholder (the resolver's HostResolvedImage). Comment HTML is rewritten on an inert
<template> and then sanitized, so DOMPurify's output is what is inserted. Description
videos remain visible; local commit-message images keep their direct URLs. The shared fetch
guard matches an absolute context reference whose scheme, host case or default port differ
from the requested URL, but compares its path as written: a reference with a dot segment or
a backslash never authorizes the URL it resolves to. No additional listener or
Tailscale-specific URL is needed.
Pictures and videos in PR text open in Artifacts (owner, 2026-11-11: "Artifacts panel for both").
In the PR description and the Comments tab (PRMediaScope, wrapped around AnnotatableDescription's
RenderedMarkdown and MarkdownBody with prMedia), a picture the Artifacts list holds, and a link to a
video it holds (GitHub saves a pasted video as a bare user-attachments/assets/<id> link), open the
Artifacts panel at that item: openPRArtifact(id) on ReviewStateContext opens the panel and leaves
prArtifactFocus, which the panel shows (un-hiding it, turning Hide resolved off for it), puts focus on
its row, and clears (onPRArtifactFocusHandled), so a later reopen starts on the gallery. A selected
note on another artifact is deselected first, or it would pull the panel back. Matching is the list's
own dedupe rule (findPRArtifactByUrl), through the proxy's url parameter for a proxied picture
(prMediaTarget.ts). Any other picture (another host, a picture the list does not collect) opens in
place in ui's ImageLightbox; a picture that is a link's face keeps the link and loses the zoom cursor.
Pictures become role="button" with tabindex="0", pressed with Enter or Space (no new shortcut); a
video link opens on a plain click, while Cmd/Ctrl/Shift/middle click still open GitHub. A click on a
playing <video> stays the player's: the comments' .mp4 player has an Open in Artifacts button
under it (OpenInArtifactsButton), and a raw-HTML <video> in the description plays in place (open it
from the list). The scope only adds attributes after render, never moves a node, so the highlighter and
React keep their DOM. A screenshot GitHub wrote as an <img> tag inside a description's table cell or sentence renders through the same picture path (ui's InlineImageTagsContext, on for a github.com PR's description; comments already render such cells as sanitized HTML). Commit messages are not wrapped. Under 640 px the panel's list is icons only (names, group labels and the header's Add note / Source / Open words are max-sm:sr-only), so the item and its name keep the room. Test: PRMediaScope.test.tsx (DOM).
The proxy's fetch is strict (fetchPRArtifactContent, packages/shared/pr-artifact-document.ts, vendored to Pi, so both runtimes). Redirects are followed by hand, at most 4. For a PR on github.com each hop must land on github.com, raw.githubusercontent.com, user-images / private-user-images.githubusercontent.com, or GitHub's upload bucket (exactly ^github-production-user-asset-[0-9a-z]+\.s3\.amazonaws\.com$) over https; media.githubusercontent.com only as the Git LFS hand-off from raw.githubusercontent.com for the PR's own repository (/media/<owner>/<repo>/), never with the token; GitLab and GitHub Enterprise keep the public-https rule, since their object storage hands off to a host each instance configures. The sign-in goes only to the first request's origin, never across a redirect: a private github.com/user-attachments/assets/<id> needs it there and then 302s to a signed S3 URL that needs none (checked live). A request without source (a picture or video) must answer PNG, JPEG, GIF, WebP, AVIF, MP4, QuickTime or WebM, else 415; a resource an HTML or Markdown artifact pulls in (source) keeps its type (CSS, scripts, fonts).
Model lists come from the installed tools, not hand lists. Claude's list is the SDK's supportedModels() against the installed claude (a throwaway process with no prompt, settingSources: [] so no user hooks run, no MCP servers, 10s cap, ~0.5s measured); Codex's is the app-server model/list. Both run lazily behind the provider initializer (?activate= or the first session), never at startup; a success is kept for the process, a failure may be retried after 60s (createBestEffortOnce), and the capabilities answer marks each such provider's list modelsSource: 'fallback' | 'discovered' so the client forgets a fallback answer and retries on its next load. The same discovery captures the tool version once (claude --version run alongside it; codex from the app-server initialize userAgent, via cliVersionFrom), kept even when discovery fails, and the answer carries it as an optional toolVersion; every Claude/Codex model picker (Agents tab launchers, Guided Review, Ask AI bars, Settings) shows a muted ModelSourceHint line ("From your installed Codex 0.155.1", or the built-in-list variant on fallback) only when toolVersion is present, so a host that omits it gets no hint. Both runtimes share createDeferredModelDiscovery: an ?activate= probe waits for discovery, and so does a session for every provider except Claude, whose sessions resolve the model against the current list while discovery finishes in the background, so the first Ask AI answer does not wait on it — except when that list is still the fallback and lacks the requested pick (e.g. opus[1m]), where the session waits for discovery rather than silently running a different model once. One shape, CatalogModel in packages/core/model-catalog.ts (id, label, efforts + default effort, fast mode, resolvedId), serves Ask AI AND the review / Code Tour / Guided Review launchers: useModelCatalogs (packages/ui/hooks/) fetches the same /api/ai/capabilities?activate= answer for the ONE engine a launcher is set to, and useAgentSettings resolves saved picks against it at read time (the cookie is never rewritten). ONE resolver, resolveModelChoice, is used by the launchers, Ask AI's client (aiProvider.ts) and the AI session endpoint: exact id → the alias whose resolvedId covers it → the same family's alias (claude-opus-5 → opus) → the surface default (Claude opus for review, sonnet for tour/guide; Codex '' = the model the Codex list marks default, except Guided Review, which prefers gpt-6-luna when offered: PREFERRED_GUIDE_CODEX_MODEL) → the catalog default; it never moves a pick onto a [1m] id unless the pick was one. Efforts clamp to the model's own levels, launches wait until the catalog settles, and a loading row shows meanwhile. The Claude catalog drops the SDK's default pointer row and adds a bare latest alias per family offered, and always offers opus / sonnet / haiku (some CLIs, e.g. Claude Code 2.1.141, name Opus only through the default row, whose description then supplies the version); alias labels carry the version parsed from the row's resolvedModel (claudeModelVersion: "Opus 5.5 (latest)"), since the SDK's displayName has none. Codex fast mode is dropped when resolution replaces a saved model with a different one; changing Fast or reasoning then re-keys the section to the model shown. Codex fast support is read from serviceTiers (a priority/fast tier) as well as the deprecated additionalSpeedTiers. The only static lists are the small CLAUDE_FALLBACK_MODELS / CODEX_FALLBACK_MODELS, used when discovery fails.
Agents Ask AI starts stand Plannotator's own integration down. Every provider starts its agent with askAiChildEnv() (packages/ai/providers/ask-ai-env.ts: PLANNOTATOR_INBOX_TOOL=0, PLANNOTATOR_AGENT_TOOL=0, PLANNOTATOR_ASK_AI_CHILD=1), so the Inbox MCP shim lists no tools, the plan-review hook exits 0 and the OpenCode plugin registers nothing. Codex clears a stdio MCP server's env, so codex app-server also gets a -c override that disables its plannotator-inbox server, and Claude sessions disallow mcp__plannotator-inbox whatever its transport. See PLANNOTATOR_ASK_AI_CHILD in environment.md for details and what is not covered.
Codex transport note: the
codex-sdkprovider id is a stable identifier only — it no longer uses@openai/codex-sdk/codex exec. It drives a long-livedcodex app-serverprocess over JSON-RPC (packages/ai/providers/codex-app-server.ts), which respects the user's/enterprise-managed approval policy and supports interactive Allow/Deny approvals. The id stayscodex-sdkto preserve saved cookie preferences, theagents.tsmapping, and the UI reasoning-effort gate.
Pi transport note: the
pi-sdkprovider (pi-sdk.tsfor Bun,pi-sdk-node.tsfor the Pi extension) runs each model probe and session aspi --mode rpcwithaskAiChildEnv()(ask-ai-env.ts, shared by every provider): the live env plusPLANNOTATOR_INBOX_TOOL=0,PLANNOTATOR_AGENT_TOOL=0andPLANNOTATOR_ASK_AI_CHILD=1. Pi's RPC mode reportsctx.hasUI === true(it binds a dialog UI), so without them the Plannotator Pi extension inside that throwaway Pi would offer its modelplannotator_inbox(andplannotator), show it in the Inbox and run the reply wake there. The extension itself keeps gating onhasUI, notctx.mode === "tui": a person can drive Pi over RPC, andapps/pi-extension/inbox.test.tsproves the Inbox on Pi's RPC mode. Test:pi-sdk-models.test.ts.
Qwen Code transport note: the
qwen-sdkprovider (packages/ai/providers/qwen-sdk.ts, one node:child_process file for both runtimes; Pi vendors it withqwen-events.ts) registers whenqwenis on PATH. Each question is oneqwen --output-format stream-json --include-partial-messages --approval-mode plan --exclude-tools=<QWEN_EXCLUDED_TOOLS> --max-wall-time 10mrun with the prompt on stdin (the review context goes with the first question only). Not fully read-only: Qwen approves a call the user's settings allow (permissions.allowrules, atrust: trueMCP server, auto-memory paths) before its plan-mode block runs, so plan mode alone would let such a call write.QWEN_EXCLUDED_TOOLSremoves the file-writing, memory and worktree tools outright (edit,write_file,notebook_edit,save_memory,manage_memory,enter_worktreeandexit_worktree, which Qwen allows by default and which make a branch and a checkout under<repo>/.qwen/worktrees, plusexit_plan_mode, so the Plannotator Qwen extension never opens a plan review from an Ask AI run); a whole-tool deny wins over an allow rule. Still possible: any other tool the user's Qwen settings auto-approve (a trusted MCP server, or an allow rule, e.g. foragent,web_fetchor anmcp__server__tool), and a shell command Qwen's plan-mode shell policy accepts (it rejects writes, and a non-interactive run denies the unknown ones). Session ids areQWEN_ASK_AI_SESSION_PREFIX(a5ca1000, inqwen-events.ts) plus random, still a UUID v4. The first question passes--session-id <id>, later ones--resume <id>. A first question that got no output at all retries under a fresh id next time. A resume that prints nothing, exits non-zero (not 55) and prints Qwen's fixedNo saved session foundon stderr means Qwen has no saved session ("No saved session found":general.chatRecording: false, which Plannotator does not override, or a run that died before Qwen saved it): the same question is sent once more under a fresh id with the review context, so only the history is lost. Any other startup failure of a resume (sign-in, network, a bad model, an unknown flag) is shown as the error, and the conversation is kept. Each run waits up to 5s for the previous one to exit, then stops it; Stop ends that wait at once. Ask AI conversations are ordinary Qwen chats inprojects/<cwd>/chats/: they show in the session list and, being the newest chat, are whatqwen --continueresumes.plannotator lastskips them (QWEN_ASK_AI_CHAT_PREFIXinapps/hook/server/qwen-session.ts, pinned equal to the provider's). Models come from$QWEN_HOME/settings.json(else~/.qwen; comments allowed):modelProviders[security.auth.selectedType ?? "openai"], withmodel.nameas the default (qwenCatalogFromSettingsinpackages/core/model-catalog.ts); discovery runs no process and sessions never wait on it. No fork, no reasoning efforts, no tool-version hint. The 10-minute limit is Qwen's own and starts after Qwen's startup (config, auth, MCP); Plannotator has no backstop timer. Tests:packages/ai/providers/qwen-sdk.test.ts,qwen-events.test.ts, theQwen Codeblocks in bothai-runtime.test.tsfiles (fakeqwenintests/test-fixtures/fake-qwen-cli.ts), and the Ask AI chat skip inapps/hook/server/qwen-session.test.ts.
OpenCode transport note: the
opencode-sdkprovider spawns its ownopencode serveper process on an OS-assigned port (port: 0) and never attaches to a server it did not spawn (an attached server can't be cleaned up by us, and opencode's per-directory instances accumulate in it without eviction). The spawned server is closed on dispose and on process exit. Model discovery is deferred behind the provider initializer (?activate=from the model picker, or the first opencode session) exactly like Codex — nothing spawns at server boot, so the picker lists opencode with an empty model list until first activation. Regression-pinned bypackages/ai/providers/opencode-sdk.test.ts.