@vintasoftware/pr-review-canvas 0.3.0 → 0.4.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,55 @@ 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.
+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,7 +77,7 @@ 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
 
@@ -103,7 +127,15 @@ pr-review publish <canvasDir> --agent <your agent id> --model <model id if you k
   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 +152,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)
 
@@ -179,6 +209,6 @@ 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
+for the same commit. 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/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
 }

package/src/chat/chat-manager.ts

@@ -5,6 +5,7 @@ import type { AgentRunner } from '../acpx/acpx.js'
 import type { ChatContext, ChatEvent, ChatThreadsResponse, ChatTurn } from '../contract/chat.js'
 import type { FileEntry, Repo, ReviewArtifact } from '../contract/review-artifact.js'
 import type { Settings, SettingsOverrides } from '../contract/settings.js'
+import type { ReviewKey } from '../contract/review-key.js'
 import type { ChatThread } from '../contract/state.js'
 import type { SettingsStore } from '../store/settings-store.js'
 import type { StateStore } from '../store/state-store.js'
@@ -38,9 +39,9 @@ export interface ChatManagerDeps {
   now: () => Date
 }
 
-/** Everything about the pull request one turn needs, resolved by the route. */
+/** Everything about the review target one turn needs, resolved by the route. */
 export interface ChatTarget {
-  prNumber: number
+  key: ReviewKey
   headSha: string
   artifact: ReviewArtifact
   files: FileEntry[]
@@ -58,13 +59,13 @@ export interface ChatSendInput {
 
 export interface ChatManager {
   effectiveSettings(): Promise<Settings>
-  threads(prNumber: number): Promise<ChatThreadsResponse>
-  createThread(prNumber: number): Promise<ChatThread>
-  selectThread(prNumber: number, name: string): Promise<ChatThread | null>
+  threads(key: ReviewKey): Promise<ChatThreadsResponse>
+  createThread(key: ReviewKey): Promise<ChatThread>
+  selectThread(key: ReviewKey, name: string): Promise<ChatThread | null>
   send(target: ChatTarget, input: ChatSendInput): AsyncIterable<ChatEvent>
   /** True when a turn was running and has been asked to stop. */
-  cancel(prNumber: number): Promise<boolean>
-  busy(prNumber: number): boolean
+  cancel(key: ReviewKey): Promise<boolean>
+  busy(key: ReviewKey): boolean
 }
 
 /** The slot a turn holds while it runs. The handle is filled in once the agent has started. */
@@ -75,7 +76,7 @@ interface RunningTurn {
 }
 
 export function createChatManager(deps: ChatManagerDeps): ChatManager {
-  const running = new Map<number, RunningTurn>()
+  const running = new Map<ReviewKey, RunningTurn>()
 
   const effectiveSettings = async (): Promise<Settings> => {
     const saved = await deps.settings.read()
@@ -86,12 +87,12 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
     }
   }
 
-  const newThread = async (prNumber: number, agent: string): Promise<ChatThread> => {
+  const newThread = async (key: ReviewKey, agent: string): Promise<ChatThread> => {
     const at = deps.now().toISOString()
     let created: ChatThread | null = null
-    await deps.state.update(prNumber, state => {
+    await deps.state.update(key, state => {
       const thread: ChatThread = {
-        name: threadName(deps.repo, prNumber, agent, nextThreadIndex(state.chat.threads)),
+        name: threadName(deps.repo, key, agent, nextThreadIndex(state.chat.threads)),
         agent,
         rev: 0,
         title: NEW_THREAD_TITLE,
@@ -108,8 +109,8 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
   }
 
   /** The thread a message goes to: the one asked for, the active one, or a fresh one. */
-  const resolveThread = async (prNumber: number, agent: string, wanted?: string): Promise<ChatThread> => {
-    const state = await deps.state.read(prNumber)
+  const resolveThread = async (key: ReviewKey, agent: string, wanted?: string): Promise<ChatThread> => {
+    const state = await deps.state.read(key)
     const byName = wanted === undefined ? undefined : state.chat.threads.find(t => t.name === wanted)
     const active =
       byName ??
@@ -118,10 +119,10 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
         : state.chat.threads.find(t => t.name === state.chat.activeThread))
     // Changing the agent starts a new thread: the old session belongs to the old agent.
     if (active === undefined || active.agent !== agent) {
-      return newThread(prNumber, agent)
+      return newThread(key, agent)
     }
     if (state.chat.activeThread !== active.name) {
-      await deps.state.update(prNumber, current => ({
+      await deps.state.update(key, current => ({
         ...current,
         chat: { ...current.chat, activeThread: active.name },
       }))
@@ -134,18 +135,18 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
    * try creates the session again and sends the seed again.
    */
   const saveTurn = async (
-    prNumber: number,
+    key: ReviewKey,
     thread: ChatThread,
     userText: string,
     assistant: ChatTurn,
     seededHeadSha: string,
     reached: boolean
   ): Promise<void> => {
-    await deps.transcripts.append(prNumber, thread.name, assistant)
+    await deps.transcripts.append(key, thread.name, assistant)
     if (!reached) {
       return
     }
-    await deps.state.update(prNumber, state => ({
+    await deps.state.update(key, state => ({
       ...state,
       chat: {
         ...state.chat,
@@ -169,8 +170,8 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
    * it, so the next turn creates the session again and sends the seed with it. The revision keeps
    * counting the turns the thread has taken, which is what its title is keyed on.
    */
-  const forgetSession = async (prNumber: number, name: string): Promise<void> => {
-    await deps.state.update(prNumber, state => ({
+  const forgetSession = async (key: ReviewKey, name: string): Promise<void> => {
+    await deps.state.update(key, state => ({
       ...state,
       chat: {
         ...state.chat,
@@ -180,17 +181,17 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
   }
 
   async function* send(target: ChatTarget, input: ChatSendInput): AsyncIterable<ChatEvent> {
-    if (running.has(target.prNumber)) {
+    if (running.has(target.key)) {
       throw new ChatBusyError()
     }
     // The slot is taken before the first await, so a second request that arrives while this one
     // is still reading the settings sees a busy chat rather than starting a second agent.
     const slot: RunningTurn = { run: null, stopped: false }
-    running.set(target.prNumber, slot)
+    running.set(target.key, slot)
     try {
       yield* runTurn(target, input, slot)
     } finally {
-      running.delete(target.prNumber)
+      running.delete(target.key)
     }
   }
 
@@ -200,7 +201,7 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
     slot: RunningTurn
   ): AsyncIterable<ChatEvent> {
     const settings = await effectiveSettings()
-    const thread = await resolveThread(target.prNumber, settings.agent, input.thread)
+    const thread = await resolveThread(target.key, settings.agent, input.thread)
     const seeded = thread.seededHeadSha !== target.headSha
     const at = deps.now().toISOString()
     const contextBlock = await renderChatContext(input.context, {
@@ -224,7 +225,7 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
       })
     }
 
-    await deps.transcripts.append(target.prNumber, thread.name, {
+    await deps.transcripts.append(target.key, thread.name, {
       role: 'user',
       text: input.message,
       at,
@@ -235,7 +236,7 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
     // transcript is written before the events, so a reader who leaves now still finds it there.
     if (slot.stopped) {
       await saveTurn(
-        target.prNumber,
+        target.key,
         thread,
         input.message,
         { role: 'assistant', text: '', at: deps.now().toISOString(), incomplete: 'cancelled' },
@@ -258,7 +259,7 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
       maxTurns: settings.maxTurns ?? undefined,
       // The runner scrubs the line before it gets here; this only writes it down.
       onRawLine: line => {
-        void deps.transcripts.appendEvent(target.prNumber, thread.name, line).catch(() => undefined)
+        void deps.transcripts.appendEvent(target.key, thread.name, line).catch(() => undefined)
       },
     })
     slot.run = run
@@ -316,7 +317,7 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
         await run.cancel().catch(() => undefined)
       }
       await saveTurn(
-        target.prNumber,
+        target.key,
         thread,
         input.message,
         {
@@ -330,15 +331,15 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
         answer !== '' || incomplete === undefined || incomplete === 'cancelled'
       )
       if (incomplete === 'AGENT_NO_SESSION') {
-        await forgetSession(target.prNumber, thread.name)
+        await forgetSession(target.key, thread.name)
       }
     }
   }
 
   return {
     effectiveSettings,
-    async threads(prNumber) {
-      const [state, settings] = await Promise.all([deps.state.read(prNumber), effectiveSettings()])
+    async threads(key) {
+      const [state, settings] = await Promise.all([deps.state.read(key), effectiveSettings()])
       return {
         threads: state.chat.threads.map(t => ({
           name: t.name,
@@ -350,25 +351,25 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
         agent: settings.agent,
       }
     },
-    async createThread(prNumber) {
+    async createThread(key) {
       const settings = await effectiveSettings()
-      return newThread(prNumber, settings.agent)
+      return newThread(key, settings.agent)
     },
-    async selectThread(prNumber, name) {
-      const state = await deps.state.read(prNumber)
+    async selectThread(key, name) {
+      const state = await deps.state.read(key)
       const thread = state.chat.threads.find(t => t.name === name)
       if (thread === undefined) {
         return null
       }
-      await deps.state.update(prNumber, current => ({
+      await deps.state.update(key, current => ({
         ...current,
         chat: { ...current.chat, activeThread: name },
       }))
       return thread
     },
     send,
-    async cancel(prNumber) {
-      const slot = running.get(prNumber)
+    async cancel(key) {
+      const slot = running.get(key)
       if (slot === undefined) {
         return false
       }
@@ -378,7 +379,7 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
       await slot.run?.cancel()
       return true
     },
-    busy: prNumber => running.has(prNumber),
+    busy: key => running.has(key),
   }
 }