kandev/docs/specs/pr-only-commit-details/spec.md

---
title: Repair PR-only commit details
status: done
created: 2026-08-04
owner: kandev
---

# Repair PR-only commit details

## Problem

The Changes panel combines commits discovered in a task session's local
worktree with commits returned by the task's linked GitHub pull request. When a
pull request is force-pushed after the task worktree is created, those sources
can describe different histories.

PR-only rows currently inherit zero-valued statistics from GitHub's pull
request commit-list response and are opened through the local
`session.commit_diff` action. The list response does not contain commit stats,
and the remote commit may not exist in the task worktree. As a result, Kandev
can show false `+0 -0` totals, an empty or failed detail view, metadata from the
wrong source, and local reset/revert/amend controls for a commit that is not in
the local branch.

## Desired behavior

- A commit row and its detail view use one explicit source of truth.
- A SHA present in the local session commit feed is a **local commit**, even
  when the same SHA is also present in the linked pull request. It keeps the
  current local `session.commit_diff` behavior and local commit actions.
- A SHA present only in the selected linked GitHub pull request is a
  **GitHub commit**. Its source identity includes the workspace, owner,
  repository, and SHA.
- A GitHub commit whose list response has no statistics does not display a
  fabricated `+0 -0`. A known empty commit may display zero additions and zero
  deletions only when those values came from commit-detail data.
- Opening a GitHub commit lazily loads its metadata, aggregate statistics,
  changed files, and patches from GitHub's individual commit endpoint. It does
  not depend on the commit object being present in the task worktree.
- Desktop and mobile commit details render the same source-aware data.
- GitHub-only commit details are read-only relative to the task worktree. They
  do not expose reset, revert, amend, open-current-worktree-file, or local
  context-expansion controls.
- A GitHub request failure produces the existing visible error treatment and
  never silently falls back to local `git show` data.
- Viewing a GitHub commit never fetches, checks out, resets, or otherwise
  mutates the task worktree.

## API contract

Add a workspace-scoped WebSocket request for an individual GitHub commit. The
request carries `workspace_id`, `owner`, `repo`, and an exact commit SHA. The
response carries commit metadata, exact additions/deletions/files-changed
statistics, and the existing GitHub-style file records needed by the diff
viewer.

The backend must authorize the requested repository through the same
workspace-scoped credential and repository checks used by the existing GitHub
pull request actions. Pull request commit-list data must distinguish
unavailable statistics from known zero statistics; omitted data must not be
serialized or interpreted as measured zeroes.

The individual-commit response must merge GitHub's paginated file records so a
commit is not presented as complete after only the first page. Provider limits
or unavailable patches remain explicit upstream limitations rather than a
reason to consult the local worktree.

## Regression scenarios

- **GIVEN** a task worktree at an obsolete pull request head and a linked pull
  request that was force-pushed to new SHAs, **WHEN** the user opens a new
  PR-only commit, **THEN** Kandev shows the GitHub commit's metadata, exact
  statistics, files, and patches without invoking the local commit-diff path.
- **GIVEN** a PR-only commit returned by the pull request commit-list endpoint,
  **WHEN** its row is rendered before detail data is loaded, **THEN** the row
  omits statistics instead of displaying `+0 -0`.
- **GIVEN** the same SHA is present in both the local and pull request feeds,
  **WHEN** the user opens it, **THEN** it is deduplicated as a local commit and
  keeps the existing local detail path and local actions.
- **GIVEN** two linked repositories contain PR-only commits, **WHEN** either
  commit is opened, **THEN** the request uses that row's workspace, owner,
  repository, and SHA rather than the active worktree's repository.
- **GIVEN** a GitHub-only commit on mobile, **WHEN** the user taps the row,
  **THEN** the existing full-height commit sheet renders the remote patch and
  closes normally without exposing local commit actions.
- **GIVEN** GitHub rejects or cannot serve the individual commit request,
  **WHEN** the user opens the row, **THEN** Kandev shows an error and does not
  substitute local worktree content.

## Constraints

- Preserve the current local commit-detail flow and action semantics.
- Fetch individual GitHub commit details lazily; do not issue one request per
  row while rendering the commit list.
- Reuse the current desktop panel and mobile full-height sheet rather than
  adding a new detail composition.
- Keep GitHub patches in their existing patch representation, including the
  current binary, unavailable, or truncated-patch treatment.
- Route any changed user-facing copy through i18n. No new explanatory copy is
  required for this repair.

## Out of scope

- Automatically fetching or checking out the pull request head in the task
  worktree.
- Resetting or rebasing a stale task branch.
- Adding a general stale-worktree warning or synchronization workflow.
- Eagerly enriching every pull request commit row with individual commit data.
- Parent selection or combined-diff controls for merge commits.
- Persistence or database schema changes.
- Adding equivalent remote-commit providers for non-GitHub integrations.