@vintasoftware/pr-review-canvas 0.3.0 → 0.5.0

package/skills/pr-review-canvas/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pr-review-canvas
 model: sonnet
-description: Generate a review canvas for a GitHub pull request (or two refs) with the pr-review tool. Runs `pr-review prepare`, writes the layered model.json the prompt asks for, and runs `pr-review publish` until the validator passes. Use when the user runs `/pr-review-canvas <pr-number>`, `/pr-review-canvas --base <ref> --head <ref>`, or asks for a review canvas for a PR.
+description: Generate a review canvas for a GitHub pull request or GitLab merge request, for the work in this clone before a pull request exists, or for two refs, with the pr-review tool. Runs `pr-review prepare`, writes the layered model.json the prompt asks for, and runs `pr-review publish` to validate and automatically share it as a compressed PR/MR comment. Use when the user runs `/pr-review-canvas <pr-number>`, `/pr-review-canvas branch`, `/pr-review-canvas uncommitted`, `/pr-review-canvas --base <ref> --head <ref>`, or asks for a review canvas for a PR or MR, for their branch, or for what they have not committed.
 ---
 
 # pr-review-canvas
@@ -11,31 +11,60 @@ points, and hand it to the `pr-review` CLI. The CLI does the deterministic work
 validation, storage); you do the reading and the writing of `model.json`. Nothing here checks out
 a branch or writes outside the canvas directory.
 
-Arguments: `<pr-number> [--force]` or `--base <ref> --head <ref> [--force]`. `--force` regenerates
-a canvas that already exists for the head commit: prepare removes the old `model.json` and any
-other leftovers from the canvas directory, keeping `derived/`, `publish.log` (the attempts history),
-and the published `review.json` + `manifest.json` (the page keeps showing the old canvas until your
-publish replaces it), so you start a fresh `model.json`. Run every `pr-review` command from the
-repository root.
+When the target already has a canvas for a commit this head was built on, prepare renders a
+different prompt: it names that canvas, lists which files the new commits left untouched, and tells
+you what to carry from it word for word and what to decide again. Follow that prompt as written;
+the two lists are computed, not suggestions.
+
+Arguments: `<pr-number> [--force]`, `branch [--base <ref>] [--force]`,
+`uncommitted [--base <ref>] [--force]`, or `--base <ref> --head <ref> [--force]`. `--force`
+regenerates a canvas that already exists for the head commit: prepare removes the old `model.json` and any other leftovers from the canvas
+directory, keeping `derived/`, `publish.log` (the attempts history), and the published
+`review.json` + `manifest.json` (the page keeps showing the old canvas until your publish replaces
+it), so you start a fresh `model.json`. Run every `pr-review` command from the repository root.
 
 ## Flow
 
 ### Model choice
 
-Claude Code defaults this skill to Sonnet. If the prepared diff changes authentication, access
-policy, or protected health information (PHI) handling, use an Opus agent for the generation and
-validation steps when available. Pass it the prepared prompt and context paths; it writes the
-same model file. Honor an explicit user model choice. Other hosts keep their selected model.
+Use a mid-tier model, such as Sonnet, by default. If the prepared diff changes authentication,
+access policy, or protected health information (PHI) handling, use a more capable model, such as
+Opus, for the generation and validation steps when available. When delegating to another agent,
+pass it the prepared prompt and context paths; it writes the same model file. Honor an explicit
+user model choice. If the host cannot select models, keep its selected model.
 Record the model that actually generated the canvas when publishing.
 
 ### 1. Prepare
 
 ```bash
 pr-review prepare --pr <n> [--force]
-# or, before a PR exists:
+# or, before a pull request exists, one of the two reviews of this clone:
+pr-review prepare --branch [--base <ref>] [--force]
+pr-review prepare --uncommitted [--base <ref>] [--force]
+# or, for any two refs:
 pr-review prepare --base <ref> --head <ref> [--force]
 ```
 
+The skill word maps to the flag: `/pr-review-canvas branch` runs `prepare --branch`, and
+`/pr-review-canvas uncommitted` runs `prepare --uncommitted`.
+
+Both compare against the default branch, which prepare reads from `origin/HEAD` unless `--base`
+names another one. They differ in what the head holds:
+
+- `--branch` is the tip of the current branch. Whatever is in the working tree is left out.
+- `--uncommitted` is the working tree itself: prepare snapshots the edits and the untracked files
+  into a commit of its own, without touching anything the user has staged. With a clean tree it is
+  the branch tip, and the canvas is the same one `--branch` would build.
+
+They are separate reviews with separate pages, progress and chat threads, so preparing one leaves
+the other alone. Pick the one the user asked for; when they only say "review my work", ask which,
+unless the words already decide it ("before I commit" is `uncommitted`, "before I open the PR" with
+everything committed is `branch`).
+
+The JSON carries an extra `local` object with the review's name, the base that was resolved, the
+branch the head is on, and whether uncommitted work is in it. Tell the user all four: a review of
+the wrong base, or of a tree that has moved, is worth catching early.
+
 Progress goes to stderr. The last stdout line is JSON:
 
 ```json
@@ -53,12 +82,14 @@ Progress goes to stderr. The last stdout line is JSON:
   "canvas already exists for <headSha>; run with --force to regenerate".
 - A line of the form `{ "error": { "code", "message", "hint" } }` means prepare failed. Report the
   code, message, and hint verbatim and stop. `pr-review doctor` names which of git, origin,
-  `gh`, the data dir, and the skill install is missing.
+  `gh` or `glab`, the data dir, and the skill install is missing.
 
 ### 2. Read the task
 
 Read `promptPath` in full: it holds the pull request, the manifest with every hunk id, the diffs
-(inline or by file path), the layering and length rules, the rulebook, and the JSON schema. Read
+(inline or by file path), the layering and length rules, the rulebook, and the JSON schema. On an
+incremental run it also names the basis canvas and its `review.json`: read that file for the exact
+wording of everything it tells you to carry. Read
 `contextPath` when you need the paths of the head files, the base files, or the patches. Read any
 untouched file with `git show <headSha>:<path>` from the repository root, using the SHA returned
 by prepare. The working tree may be on another branch. Do not check anything out.
@@ -98,12 +129,20 @@ pr-review publish <canvasDir> --agent <your agent id> --model <model id if you k
 ```
 
 - `--agent`: a free-text id of the agent product you are: `claude`, `codex`, `gemini`, ...
-- `--model`: the model id when you know it (`claude-opus-4-1`, `gpt-5`, ...); omit it otherwise.
+- `--model`: the model id when you know it (`claude-opus-5-5`, `gpt-6-astra`, ...); omit it otherwise.
 - `--harness`: `claude-code` when you run inside Claude Code, `codex` inside Codex, `other`
   anywhere else.
 
 On success the last line is `{ "status": "published", "headSha", "reviewJsonPath", "attempts",
-"reviewUrl" }` (`reviewUrl` is absent for a `--base/--head` run).
+"reviewUrl", "sharing" }` (`reviewUrl` is absent only for a `--base/--head` run; a local run
+points at `/review/branch` or `/review/uncommitted`).
+For PR/MR runs, publish automatically creates or updates your canvas comment using the host CLI login.
+Always inspect `sharing.status`: local validation success does not mean remote sharing succeeded.
+
+For a local run there is nothing to share: `sharing.status` is `"local"`. Report `reviewUrl` and
+tell the user to start `pr-review serve` to read the canvas. If publish prints `CANVAS_STALE`, the
+branch or the working tree changed while you worked; offer to prepare again rather than passing
+`--allow-stale`, because the canvas would then describe code the user has already changed.
 
 On failure the command prints one line per problem, then an error line, and exits 5:
 
@@ -120,35 +159,33 @@ verbatim. Do not weaken the content to pass: shorten text, move hunks, fix links
 If publish prints `CANVAS_STALE`, the branch moved while you worked. Tell the user and offer to run
 prepare again; pass `--allow-stale` only when the user asks for the canvas of the old commit.
 
-### 6. Export the zip
+### 6. Report the sharing result
 
-```bash
-pr-review export --head <headSha> [--pr <n>]
-```
-
-Pass `--pr <n>` when the run had a PR number, so the file name and the manifest carry it. The
-command prints one JSON line with the absolute `path` of the zip.
+For a PR/MR run, report the local `reviewUrl` (start it with `pr-review serve`) and inspect `sharing`:
 
-### 7. Finish
+- `status: "shared"`: link to `sharing.url` and say the canvas was shared automatically.
+- `status: "failed"`: clearly warn that automatic sharing failed, quote `sharing.warning`, and
+  give the absolute `sharing.zipPath`. Tell the user to open the PR/MR, edit its description,
+  drag the ZIP into the editor, wait for upload to finish, and save. Replace any older canvas
+  attachment link. Include these instructions in your final response; the local canvas is ready,
+  but reviewers still need the upload. Do not regenerate the model to repair a sharing failure.
 
-For a PR run, report the `reviewUrl` from publish, the absolute zip path from export, and a link
-to the GitHub PR from the prepared context. End with upload instructions:
+For a local run, `sharing.status` is `"local"` and there is nothing to share. Give the user
+`reviewUrl` (`http://localhost:<port>/review/branch` or `.../review/uncommitted`) and tell them to
+start `pr-review serve` if it is not running. Say which base was compared and whether uncommitted
+work was included, both from the `local` object prepare printed.
 
-> The canvas is ready at <reviewUrl> (start the server with `pr-review serve` if it is not running).
-> ZIP: <path>
-> If you're happy with the produced canvas, open <PR URL>, edit the PR description, drag the ZIP
-> into the editor, wait for the upload to finish, and save.
+For a `--base/--head` run, `sharing.status` is `"local"` too, but the canvas has no page of its
+own. Report the stored commit and export it:
 
-For an update, tell the user to replace the old canvas attachment link with the new one.
-Include these instructions in the final response without asking a question or waiting for a reply.
-
-Uploading and saving the description are manual browser steps. Do not create a release or claim
-the ZIP was uploaded. GitHub's `gh --attach` supports images and video, but not ZIP files
-([supported types](https://github.com/cli/cli/blob/trunk/internal/attachments/userasset.go)).
+```bash
+pr-review export --head <headSha>
+```
 
-For a `--base/--head` run, say the canvas is stored for `<headSha>`, that the zip has no PR number
-yet, and that `pr-review export --pr <n>` re-exports it once the pull request exists. Include the
-manual upload instructions for when the PR is ready.
+Give the returned absolute ZIP path. Once a PR exists, `pr-review export --head <headSha> --pr <n>`
+stamps its number for manual upload, or rerun this skill for the PR number with `--force` to share
+automatically. A canvas of a working-tree snapshot cannot be carried to a pull request this way:
+its commit is on no branch, so generate a fresh one for the PR.
 
 ## Rules the validator enforces (and models tend to break)
 
@@ -178,7 +215,9 @@ manual upload instructions for when the PR is ready.
 
 ## Updating a shared canvas
 
-After new commits, run this skill again for the PR number. Add `--force` to regenerate a canvas
-for the same commit. Export the new zip and ask the user to replace the attachment in their PR
-description. Reviewers click **refresh** to load it. A canvas for a different
+After new commits, run this skill again for the PR number. The run updates the canvas of the
+nearest earlier commit instead of writing one from nothing, and the reviewer's progress on the
+untouched files follows it. Add `--force` to regenerate a canvas for the same commit, or to start
+over from a blank page. Publish updates your canvas comment; follow the sharing-result instructions
+above if it fails. Reviewers click **refresh** to load it. A canvas for a different
 PR head shows **Canvas is outdated**; an older canvas remains readable with posting disabled.

package/src/acpx/acpx.ts

@@ -4,7 +4,10 @@
  * `src/testing/fake-runner.ts` or spawn `src/testing/fake-acpx.mjs` through this adapter.
  */
 import { type ChildProcess, execFile, type SpawnOptions, spawn } from 'node:child_process'
+import { accessSync, constants } from 'node:fs'
+import path from 'node:path'
 import { promisify } from 'node:util'
+import { z } from 'zod'
 import {
   type AgentErrorCode,
   type AgentEvent,
@@ -13,6 +16,7 @@ import {
   mapAcpxMessage,
   scrubForLog,
 } from './events.js'
+import type { ModelUpgrades } from './models.js'
 import { createNdjsonSplitter, NdjsonError } from './ndjson.js'
 
 const execFileAsync = promisify(execFile)
@@ -23,6 +27,8 @@ export const ACPX_BIN = 'acpx'
 export const KILL_GRACE_MS = 3000
 /** A cancel that has not answered by then is given up on, and the child is killed instead. */
 export const CANCEL_TIMEOUT_SEC = 30
+/** `sessions show` reads a local record, so it answers fast or not at all. */
+export const SHOW_TIMEOUT_SEC = 20
 /** The runner's deadline sits this far past acpx's, so acpx reports its own timeout first. */
 export const DEADLINE_SLACK_MS = 15_000
 
@@ -68,6 +74,10 @@ export interface AgentRunner {
   acpxVersion(): Promise<string | null>
   /** Whether one agent's own CLI is installed and logged in. */
   availability(agent: string): Promise<{ installed: boolean; authenticated: boolean; reason?: string }>
+  /** Which models the agent's catalog says were replaced, and by what. Empty when it says nothing. */
+  modelUpgrades(agent: string): Promise<ModelUpgrades>
+  /** The model the named session last ran, or null when acpx does not say. */
+  sessionModel(options: { agent: string; session: string; cwd: string }): Promise<string | null>
 }
 
 /**
@@ -115,6 +125,10 @@ export function buildEnsureArgs(agent: string, session: string, cwd: string, tim
   return [...commonAcpxArgs(cwd, timeoutSec), agent, 'sessions', 'ensure', '-s', session]
 }
 
+export function buildShowArgs(agent: string, session: string, cwd: string): string[] {
+  return [...commonAcpxArgs(cwd, SHOW_TIMEOUT_SEC), agent, 'sessions', 'show', session]
+}
+
 export function buildExecArgs(agent: string, cwd: string, timeoutSec: number, prompt: string): string[] {
   return [...commonAcpxArgs(cwd, timeoutSec), agent, 'exec', prompt]
 }
@@ -125,16 +139,62 @@ const AUTH_CHECKS: Readonly<Record<string, { bin: string; args: string[] }>> = {
   codex: { bin: 'codex', args: ['login', 'status'] },
 }
 
+/** The part of `codex debug models` read here: each model and the one that replaced it. */
+const CodexCatalogSchema = z.object({
+  models: z.array(z.object({ slug: z.string(), upgrade: z.object({ model: z.string() }).nullish() })),
+})
+
+/** The part of `sessions show` read here: the model the session last ran. */
+const SessionRecordSchema = z.object({ acpx: z.object({ current_model_id: z.string().min(1) }) })
+
+/** The path `name` runs from on this PATH, or null when it is not there. */
+export function findOnPath(name: string, env: NodeJS.ProcessEnv): string | null {
+  for (const dir of (env['PATH'] ?? '').split(path.delimiter)) {
+    if (dir === '') {
+      continue
+    }
+    const candidate = path.join(dir, name)
+    try {
+      accessSync(candidate, constants.X_OK)
+      return candidate
+    } catch {
+      // Not in this directory.
+    }
+  }
+  return null
+}
+
+/**
+ * The environment acpx runs under. Without `CLAUDE_CODE_EXECUTABLE`, the Claude adapter runs the
+ * Claude Code build bundled with it, which can be months behind the installed one and so resolves
+ * `opus` to an older model. A value the user set already is kept.
+ */
+export function acpxEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  if (env['CLAUDE_CODE_EXECUTABLE'] !== undefined) {
+    return env
+  }
+  const claude = findOnPath('claude', env)
+  return claude === null ? env : { ...env, CLAUDE_CODE_EXECUTABLE: claude }
+}
+
 /** Only the one call shape the runner makes, so a test double is a plain function. */
 export type SpawnImpl = (file: string, args: string[], options: SpawnOptions) => ChildProcess
 export type ExecFileImpl = (
   file: string,
   args: string[],
-  options: { cwd?: string; timeout?: number; maxBuffer?: number; killSignal?: NodeJS.Signals }
+  options: {
+    cwd?: string
+    timeout?: number
+    maxBuffer?: number
+    killSignal?: NodeJS.Signals
+    env?: NodeJS.ProcessEnv
+  }
 ) => Promise<{ stdout: string; stderr: string }>
 
 export interface CreateAgentRunnerOptions {
   bin?: string
+  /** The environment acpx gets, before `acpxEnv` fills it in. Defaults to this process's. */
+  env?: NodeJS.ProcessEnv
   spawnImpl?: SpawnImpl
   execFileImpl?: ExecFileImpl
   /** How far the runner's own deadline sits past acpx's. Tests shorten it. */
@@ -189,6 +249,7 @@ function createEventQueue(): {
 
 export function createAgentRunner(opts: CreateAgentRunnerOptions = {}): AgentRunner {
   const bin = opts.bin ?? ACPX_BIN
+  const env = acpxEnv(opts.env ?? process.env)
   const slackMs = opts.deadlineSlackMs ?? DEADLINE_SLACK_MS
   const cancelGraceMs = opts.cancelGraceMs ?? CANCEL_TIMEOUT_SEC * 1000
   const spawnImpl = opts.spawnImpl ?? spawn
@@ -201,9 +262,7 @@ export function createAgentRunner(opts: CreateAgentRunnerOptions = {}): AgentRun
     args: string[],
     options: { cwd?: string; timeoutSec?: number; killSignal?: NodeJS.Signals } = {}
   ): Promise<{ ok: boolean; stdout: string; stderr: string; error?: unknown }> => {
-    const call: { cwd?: string; timeout?: number; maxBuffer?: number; killSignal?: NodeJS.Signals } = {
-      maxBuffer: 4 * 1024 * 1024,
-    }
+    const call: Parameters<ExecFileImpl>[2] = { maxBuffer: 4 * 1024 * 1024, env }
     if (options.cwd !== undefined) {
       call.cwd = options.cwd
     }
@@ -226,6 +285,7 @@ export function createAgentRunner(opts: CreateAgentRunnerOptions = {}): AgentRun
     run(options) {
       return startRun(
         bin,
+        env,
         spawnImpl,
         options,
         // The cancel call gets its own timeout, and SIGKILL when it elapses: a cancel that hangs
@@ -307,6 +367,34 @@ export function createAgentRunner(opts: CreateAgentRunnerOptions = {}): AgentRun
         reason: `\`${check.bin} ${check.args.join(' ')}\` failed; log in and try again`,
       }
     },
+
+    async modelUpgrades(agent) {
+      if (agent !== 'codex') {
+        return new Map()
+      }
+      // Codex keeps the catalog it last fetched on disk, so this answers in milliseconds.
+      const result = await execQuiet('codex', ['debug', 'models'], { timeoutSec: 20 })
+      // A failed call, output that is not JSON, and an unknown shape all mean no known upgrades.
+      try {
+        const catalog = CodexCatalogSchema.parse(JSON.parse(result.stdout))
+        return new Map(catalog.models.flatMap(m => (m.upgrade ? [[m.slug, m.upgrade.model] as const] : [])))
+      } catch {
+        return new Map()
+      }
+    },
+
+    async sessionModel(options) {
+      const result = await execQuiet(bin, buildShowArgs(options.agent, options.session, options.cwd), {
+        cwd: options.cwd,
+        timeoutSec: SHOW_TIMEOUT_SEC,
+      })
+      // A missing session prints an error line instead, which fails the schema like any other.
+      try {
+        return SessionRecordSchema.parse(JSON.parse(result.stdout)).acpx.current_model_id
+      } catch {
+        return null
+      }
+    },
   }
 }
 
@@ -367,6 +455,7 @@ export function readExecStream(stdout: string): {
 /** Spawns one prompt turn and turns its output into events. */
 function startRun(
   bin: string,
+  env: NodeJS.ProcessEnv,
   spawnImpl: SpawnImpl,
   options: AgentRunOptions,
   cancelCall: (args: string[]) => Promise<unknown>,
@@ -385,7 +474,11 @@ function startRun(
 
   let child: ChildProcess
   try {
-    child = spawnImpl(bin, buildPromptArgs(options), { cwd: options.cwd, stdio: ['pipe', 'pipe', 'pipe'] })
+    child = spawnImpl(bin, buildPromptArgs(options), {
+      cwd: options.cwd,
+      env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
   } catch {
     queue.push({ type: 'error', code: 'AGENT_MISSING', message: `${bin} could not be started` })
     queue.end()

package/src/acpx/models.ts

@@ -0,0 +1,43 @@
+/**
+ * A saved model id names a family, not a frozen version: every turn runs the newest model of it.
+ *
+ * Claude has family aliases (`opus`, `sonnet[1m]`, ...) that the Claude CLI resolves to its newest
+ * model, so a versioned id is rewritten to its alias. GPT has no aliases, and a family's next model can
+ * carry a new name (`gpt-5.6-terra` became `gpt-6-sol`), so the Codex catalog's own `upgrade` links
+ * are followed instead. `pin:<id>` opts out: the id after it is sent as written.
+ */
+
+export const PIN_PREFIX = 'pin:'
+
+/**
+ * `claude-opus-4-8`, `claude-sonnet-5[1m]`, `claude-haiku-4-5-20251001`. Bedrock and Vertex ids
+ * (`us.anthropic.claude-...`, `claude-...@date`) do not match, so they run as written too.
+ */
+const CLAUDE_VERSIONED = /^claude-(opus|sonnet|haiku|fable)-\d[\w.-]*?(\[[^\]]+\])?$/i
+
+/** A trailing `[...]` is a setting on the model (`[1m]`, `[high]`), kept across the upgrade. */
+const SUFFIX = /^([^[]+)(\[[^\]]+\])?$/
+
+/** Old model slug to the slug that replaced it, as the agent's catalog reports it. */
+export type ModelUpgrades = ReadonlyMap<string, string>
+
+export function latestModel(agent: string, model: string, upgrades: ModelUpgrades): string {
+  if (model.startsWith(PIN_PREFIX)) {
+    return model.slice(PIN_PREFIX.length).trim()
+  }
+  if (agent === 'claude') {
+    const versioned = CLAUDE_VERSIONED.exec(model)
+    return versioned === null ? model : `${versioned[1]?.toLowerCase()}${versioned[2] ?? ''}`
+  }
+  const parts = SUFFIX.exec(model)
+  if (parts?.[1] === undefined) {
+    return model
+  }
+  let slug = parts[1]
+  const seen = new Set([slug])
+  for (let next = upgrades.get(slug); next !== undefined && !seen.has(next); next = upgrades.get(slug)) {
+    seen.add(next)
+    slug = next
+  }
+  return `${slug}${parts[2] ?? ''}`
+}

package/src/canvas/comment.ts

@@ -0,0 +1,24 @@
+import type { CanvasZip } from './export.js'
+
+export const CANVAS_COMMENT_MARKER = '<!-- pr-review-canvas:v1\n'
+
+/** The ZIP stays in the raw comment body; the rendered comment gives reviewer instructions. */
+export function buildCanvasComment(zip: CanvasZip, limit: number): string {
+  const body = `PR Review Canvas for commit ${zip.headSha}.\n\nRun \`pr-review serve\` and open #${zip.prNumber}. If already reviewing, click **refresh**.\n\n${CANVAS_COMMENT_MARKER}${zip.name}\n${Buffer.from(zip.bytes).toString('base64')}\n-->`
+  if (body.length > limit) {
+    throw new Error(
+      `the compressed canvas comment needs ${body.length} characters; the host limit is ${limit}`
+    )
+  }
+  return body
+}
+
+/** Only the versioned envelope is decoded. ZIP contents are checked by the normal importer. */
+export function readCanvasComment(body: string): { name: string; bytes: Uint8Array } | null {
+  const match = /<!-- pr-review-canvas:v1\n([A-Za-z0-9._-]+\.zip)\n([A-Za-z0-9+/]+={0,2})\n-->/.exec(body)
+  if (match === null) return null
+  const name = match[1]!
+  const encoded = match[2]!
+  if (encoded.length > 1_000_000 || encoded.length % 4 !== 0) return null
+  return { name, bytes: Buffer.from(encoded, 'base64') }
+}

package/src/canvas/import.ts

@@ -1,18 +1,20 @@
 // One import path for the three ways a canvas arrives: the drop zone, `pr-review import`, and a
 // zip discovered on the pull request. Everything is checked here, so no caller can skip a step.
 import type { CanvasRelation, ImportResult } from '../contract/api.js'
-import type { CanvasManifest } from '../contract/canvas-manifest.js'
-import type { ReviewArtifact } from '../contract/review-artifact.js'
+import { type DiffedCommit, standsForHead } from '../review/carry-over.js'
 import type { AppContext } from '../server/context.js'
 import { AppError } from '../server/errors.js'
-import { CanvasZipError, readCanvasZip } from './zip.js'
+import { type CanvasZipContents, CanvasZipError, readCanvasZip } from './zip.js'
 
 export interface ImportOptions {
   bytes: Uint8Array
   /** The pull request the canvas is imported for; recorded on the canvas. */
   prNumber?: number | undefined
-  /** The head the page is looking at. Absent means the canvas is taken as the current one. */
-  currentHeadSha?: string | undefined
+  /**
+   * The head the page is looking at, with the merge base its diff runs from. Absent means the
+   * canvas is taken as the current one.
+   */
+  currentHead?: DiffedCommit | undefined
   /** Accepts a canvas exported from another repository. */
   force?: boolean | undefined
 }
@@ -79,13 +81,13 @@ async function relateToHead(
  * canvas already on disk is kept unless the incoming one was generated later.
  */
 export async function importCanvas(ctx: AppContext, opts: ImportOptions): Promise<ImportResult> {
-  let contents: { manifest: CanvasManifest; artifact: ReviewArtifact }
+  let contents: CanvasZipContents
   try {
     contents = readCanvasZip(opts.bytes)
   } catch (err) {
     throw err instanceof CanvasZipError ? toAppErrorFromZip(err) : err
   }
-  const { manifest, artifact } = contents
+  const { manifest, artifact, prNumber: canvasPr } = contents
   const warnings: string[] = []
   if (!sameRepo(manifest.repo, ctx.config.repo)) {
     const from = `${manifest.repo.owner}/${manifest.repo.name}`
@@ -100,8 +102,21 @@ export async function importCanvas(ctx: AppContext, opts: ImportOptions): Promis
     warnings.push(`imported a canvas exported from ${from}`)
   }
 
+  // The wrong zip attached to a pull request is the common mistake, and the head check below does
+  // not catch it: two open pull requests have unrelated heads either way. This is the one check
+  // --force cannot lift: the canvas in this zip may only be stored under the pull request it
+  // names, so forcing could only write an index entry that contradicts the zip it came from.
+  if (opts.prNumber !== undefined && canvasPr !== undefined && canvasPr !== opts.prNumber) {
+    throw new AppError(
+      'CANVAS_PR_MISMATCH',
+      `this canvas was exported for #${canvasPr}, and it is being imported for #${opts.prNumber}`,
+      400,
+      `import it without --pr to store it under #${canvasPr}, or generate a canvas for #${opts.prNumber}`
+    )
+  }
+
   const headSha = manifest.headSha
-  const currentHeadSha = opts.currentHeadSha ?? headSha
+  const currentHeadSha = opts.currentHead?.headSha ?? headSha
   const index = await ctx.canvases.readIndex()
   const stored = index.canvases[headSha]
   const keepStored = stored !== undefined && stored.generatedAt >= artifact.generatedAt
@@ -119,7 +134,13 @@ export async function importCanvas(ctx: AppContext, opts: ImportOptions): Promis
   if (keepStored) {
     return { status: 'exists', headSha, currentHeadSha, derivable, warnings }
   }
-  if (headSha === currentHeadSha) {
+  // The same rule the page reads: a canvas of another commit is current when the head's diff is
+  // identical to the one it was generated from, so the CLI never calls stale what the page shows
+  // as carried over.
+  if (
+    opts.currentHead === undefined ||
+    (await standsForHead(ctx, opts.currentHead, { headSha, mergeBaseSha }))
+  ) {
     return { status: 'ready', headSha, currentHeadSha, derivable, warnings }
   }
   const related = await relateToHead(ctx, headSha, currentHeadSha)

package/src/canvas/name.ts

@@ -33,6 +33,7 @@ export function buildCanvasZipName(opts: BuildNameOptions): string {
   return `${target}-${timestamp}-${opts.headSha.slice(0, 8)}-${repoSlug(opts.repo)}-canvas.zip`
 }
 
+/** The strict form of the grammar the drop zone applies to a picked file (`validateCanvasFilename`). */
 const NAME_RE = /^(?:pr-([1-9]\d*)|ref)-\d{8}t\d{6}z-([0-9a-f]{8})$/
 
 /**

package/src/canvas/zip.ts

@@ -14,6 +14,12 @@ export const ZIP_MAGIC = [0x50, 0x4b, 0x03, 0x04] as const
 export interface CanvasZipContents {
   manifest: CanvasManifest
   artifact: ReviewArtifact
+  /**
+   * The pull request the canvas was made for, once for every reader: the two entries are proved to
+   * agree below, and the two ways of holding "no pull request" are settled into one. A canvas
+   * generated before the pull request existed names none, and joins the PR that imports it.
+   */
+  prNumber?: number
 }
 
 /** A zip that cannot be read as a canvas. `issues` names the problems, never the file's content. */
@@ -122,5 +128,19 @@ export function readCanvasZip(bytes: Uint8Array): CanvasZipContents {
       `${REVIEW_ENTRY} is for ${artifact.data.pr.headSha.slice(0, 7)} while ${MANIFEST_ENTRY} says ${manifest.data.headSha.slice(0, 7)}`,
     ])
   }
-  return { manifest: manifest.data, artifact: artifact.data }
+  // A canvas generated before the pull request existed carries no number in review.json, and the
+  // export stamps one on the manifest; only two numbers that are both there must agree.
+  const artifactPr = artifact.data.pr.number
+  const manifestPr = manifest.data.prNumber
+  if (artifactPr !== null && manifestPr !== undefined && artifactPr !== manifestPr) {
+    throw new CanvasZipError('CANVAS_INVALID', 'the zip is not a review canvas', [
+      `${REVIEW_ENTRY} is for #${artifactPr} while ${MANIFEST_ENTRY} says #${manifestPr}`,
+    ])
+  }
+  const contents: CanvasZipContents = { manifest: manifest.data, artifact: artifact.data }
+  const prNumber = manifestPr ?? artifactPr
+  if (prNumber !== null) {
+    contents.prNumber = prNumber
+  }
+  return contents
 }