@volter/twin-github 0.1.0 → 0.1.1

package/src/github-graphql.ts

@@ -12,8 +12,11 @@
 //             issues(first) { totalCount nodes { number title state } } } }
 //   query { node(id) { ... on PullRequest { number title } } }   — id = "PR_<owner>/<repo>#<n>"
 //   mutation { addComment(input: { subjectId, body }) { commentEdge { node { id body } } } }
+//   query { repository(owner, name) { discussions(first) { nodes { id number title body category { name slug isAnswerable }
+//             comments { nodes { id body isAnswer } } } } } }   — id = "D_<owner>/<repo>#<n>"
+//   mutation { addDiscussionComment(input: { discussionId, body, replyToId? }) { comment { id body url } } }
 // Anything else (other root fields, unmodeled selection fields) → a typed GraphQL error.
-import { applyGithubWrite } from './github-twin.ts';
+import { applyGithubWrite, prPlaneDiffFiles } from './github-twin.ts';
 import { githubState, type GithubState } from './github-twin.ts';
 
 export type GraphqlResult = { data?: Record<string, unknown> | null; errors?: Array<{ message: string; type?: string }> };
@@ -33,6 +36,29 @@ const REPO_FIELDS = new Set([
   // RepositoryInfo (gh pr create / gh repo view): the `repo` fragment + repo-level merge settings.
   'id', 'owner', 'login', 'hasIssuesEnabled', 'description', 'hasWikiEnabled', 'viewerPermission',
   'defaultBranchRef', 'parent', 'mergeCommitAllowed', 'rebaseMergeAllowed', 'squashMergeAllowed', 'repo',
+  // gh pr view <n> / gh issue view <n> resolve ONE node by number.
+  'pullRequest', 'issue',
+  // Discussions: real GitHub serves them over GraphQL alone (repository.discussions; addDiscussionComment).
+  'discussions',
+]);
+const DISCUSSION_FIELDS = new Set(['id', 'number', 'title', 'body', 'url', 'createdAt', 'updatedAt', 'category', 'name', 'slug', 'isAnswerable', 'comments', 'author', 'login', 'isAnswered', 'closed', 'locked', '__typename']);
+// The single-PR fields `gh pr view --json …` selects — the exact set the repo's own
+// merge-gate scripts read (headRefOid/state/baseRefName/statusCheckRollup/
+// closingIssuesReferences/changedFiles/labels/body/comments/assignees/reviewRequests; see
+// scripts/human-approval-gate.ts, break-glass-gate.ts, finalize-agent-review.ts,
+// review-prerequisites.ts). `statusCheckRollup` is gh's ALIAS for commits(last:1){…} — the
+// token list admits both spellings. Anything else stays an honest undefinedField error.
+const PR_VIEW_FIELDS = new Set([
+  'number', 'id', 'url', 'title', 'state', 'body', 'isDraft', 'headRefOid', 'headRefName',
+  'baseRefName', 'changedFiles', 'additions', 'deletions', 'createdAt', 'updatedAt', 'closedAt',
+  'mergedAt', 'labels', 'closingIssuesReferences', 'statusCheckRollup', 'commits', 'comments',
+  'assignees', 'reviewRequests', '__typename',
+]);
+// The single-issue fields `gh issue view --json …` selects (human-approval-gate reads a
+// linked issue's labels; finalize-agent-review reads its comments and posts one).
+const ISSUE_VIEW_FIELDS = new Set([
+  'number', 'id', 'url', 'title', 'state', 'body', 'labels', 'comments', 'assignees',
+  'createdAt', 'updatedAt', 'closedAt', 'author', '__typename',
 ]);
 const PR_FIELDS = new Set(['number', 'title', 'state', 'id', '__typename',
   // PR connection node fields gh pr view/list select (modeled from the PR projection).
@@ -72,6 +98,8 @@ function selectionFields(query: string, parentToken: string): string[] {
 function argValue(query: string, argName: string, variables: Record<string, unknown>): string | undefined {
   const lit = new RegExp(`${argName}:\\s*"([^"]*)"`).exec(query);
   if (lit) return lit[1];
+  const num = new RegExp(`${argName}:\\s*(-?\\d+)`).exec(query); // Int literal (pullRequest(number: 2))
+  if (num) return num[1];
   const ref = new RegExp(`${argName}:\\s*\\$([A-Za-z_][A-Za-z0-9_]*)`).exec(query);
   if (ref && variables[ref[1]!] !== undefined) return String(variables[ref[1]!]);
   return undefined;
@@ -98,6 +126,21 @@ export async function resolveGithubGraphql(req: { query: string; variables?: Rec
 
   // ── mutation addComment(input: { subjectId, body }) ──────────────────────────────────────
   if (isMutation) {
+    // ── mutation addDiscussionComment(input: { discussionId, body, replyToId? }) ──────────────
+    // discussionId "D_<repo>#<n>" (what repository.discussions returns); maps onto the SAME write path the
+    // REST twin uses for a discussion comment.
+    if (/\baddDiscussionComment\b/.test(query)) {
+      const discussionId = String(vars.discussionId ?? argValue(query, 'discussionId', vars) ?? '');
+      const body = String(vars.body ?? argValue(query, 'body', vars) ?? '');
+      const m = /^D_(.+)#(\d+)$/.exec(discussionId);
+      if (!m) return { errors: [{ message: `Could not resolve to a node with the global id of '${discussionId}'`, type: 'NOT_FOUND' }] };
+      const repo = m[1]!; const number = Number(m[2]);
+      const replyTo = /^DC_(.+)#(\d+)$/.exec(String(vars.replyToId ?? argValue(query, 'replyToId', vars) ?? ''));
+      const res = await applyGithubWrite({ method: 'POST', path: `/repos/${repo}/discussions/${number}/comments`, body: JSON.stringify({ body, ...(replyTo ? { parent_id: Number(replyTo[2]) } : {}) }), root: req.root });
+      if (res.response.status !== 201) return { errors: [{ message: 'addDiscussionComment failed', type: res.response.status === 404 ? 'NOT_FOUND' : 'UNPROCESSABLE' }] };
+      const cid = (res.response.body as { id?: number }).id;
+      return { data: { addDiscussionComment: { comment: { id: `DC_${repo}#${cid}`, body, url: `https://github.com/${repo}/discussions/${number}#discussioncomment-${cid}` } } } };
+    }
     if (/\baddComment\b/.test(query)) {
       // subjectId/body come from variables or inline input. subjectId "PR_<repo>#<n>" or "I_…".
       const subjectId = String(vars.subjectId ?? argValue(query, 'subjectId', vars) ?? '');
@@ -154,6 +197,68 @@ export async function resolveGithubGraphql(req: { query: string; variables?: Rec
     if (bad) return { errors: [unmodeled(bad, 'Repository')] };
     const known = state.repos.find((r) => r.full_name === repo);
     const { prs, issues } = repoToNodes(state, repo);
+    // ── repository.pullRequest(number:) — the single-PR read gh pr view sends ──────────────
+    // (`\bpullRequest\b(?!s)` so the plural connection never shadows it.)
+    // Both single-node branches anchor on the FIELD-WITH-ARGS form (`pullRequest(` /
+    // `issue(`): a bare word match would hijack queries whose owner/name ARGUMENT contains
+    // the token (repository(name: "issue-tracker") — a real §9 round-two find).
+    const prTokenAt = query.search(/\bpullRequest\b(?!s)\s*\(/);
+    if (prTokenAt >= 0) {
+      const sub = query.slice(prTokenAt);
+      const bad = selectionFields(sub, 'pullRequest').find((f) => !PR_VIEW_FIELDS.has(f));
+      if (bad) return { errors: [unmodeled(bad, 'PullRequest')] };
+      const num = Number(vars.number ?? vars.pr_number ?? vars.prNumber ?? argValue(sub, 'number', vars) ?? NaN);
+      const pr = state.prs.find((p) => p.repository === repo && p.number === num);
+      if (!pr) return { errors: [{ message: `Could not resolve to a PullRequest with the number of ${num}.`, type: 'NOT_FOUND' }] };
+      return { data: { repository: { pullRequest: resolvePullRequestView(state, repo, pr, req.root) } } };
+    }
+    // ── repository.issue(number:) — gh issue view's single-issue read ──────────────────────
+    const issueTokenAt = query.search(/\bissue\b(?!s)\s*\(/);
+    if (issueTokenAt >= 0) {
+      const sub = query.slice(issueTokenAt);
+      const bad = selectionFields(sub, 'issue').find((f) => !ISSUE_VIEW_FIELDS.has(f));
+      if (bad) return { errors: [unmodeled(bad, 'Issue')] };
+      const num = Number(vars.number ?? argValue(sub, 'number', vars) ?? NaN);
+      const issue = state.issues.find((i) => i.repository === repo && i.number === num);
+      if (!issue) return { errors: [{ message: `Could not resolve to an Issue with the number of ${num}.`, type: 'NOT_FOUND' }] };
+      const labels = (issue.labels ?? []).map((name) => ({ name }));
+      const comments = state.comments
+        .filter((c) => c.repository === repo && c.number === num && c.kind === 'issue')
+        .map((c) => ({
+          id: `IC_${repo}#${c.id}`, author: null, authorAssociation: 'NONE', body: c.body ?? '',
+          createdAt: c.created_at ?? null, includesCreatedEdit: false, isMinimized: false, minimizedReason: null,
+          reactionGroups: [], url: `https://github.com/${repo}/issues/${num}#issuecomment-${c.id}`, viewerDidAuthor: false,
+        }));
+      return { data: { repository: { issue: {
+        number: num, id: `I_${repo}#${num}`, url: `https://github.com/${repo}/issues/${num}`,
+        title: issue.title ?? null, state: (issue.state ?? 'open').toUpperCase(), body: issue.body ?? '',
+        author: null, createdAt: null, updatedAt: null, closedAt: null,
+        labels: { nodes: labels, totalCount: labels.length },
+        comments: { nodes: comments, totalCount: comments.length, pageInfo: { hasNextPage: false, endCursor: null } },
+        assignees: { nodes: (issue.assignees ?? []).map((login) => ({ login, id: `U_${login}`, name: null })), totalCount: (issue.assignees ?? []).length },
+      } } } };
+    }
+    // ── repository.discussions(first, orderBy) — the community's threads, with their comments ─────
+    if (/\bdiscussions\b/.test(query)) {
+      const bad = selectionFields(query, 'discussions').find((f) => !DISCUSSION_FIELDS.has(f) && !CONNECTION_FIELDS.has(f));
+      if (bad) return { errors: [unmodeled(bad, 'Discussion')] };
+      const categories = state.discussionCategories.filter((c) => c.repository === repo);
+      const nodes = state.discussions.filter((d) => d.repository === repo).map((d) => {
+        const cat = categories.find((c) => c.slug === d.category_slug);
+        const comments = state.discussionComments.filter((c) => c.repository === repo && c.discussion_number === d.number).map((c) => ({
+          id: `DC_${repo}#${c.id}`, body: c.body ?? '', createdAt: c.created_at ?? null, author: null, isAnswer: Boolean(c.is_answer),
+          replyTo: c.parent_id ? { id: `DC_${repo}#${c.parent_id}` } : null,
+        }));
+        return {
+          id: `D_${repo}#${d.number}`, number: d.number, title: d.title ?? null, body: d.body ?? '', url: `https://github.com/${repo}/discussions/${d.number}`,
+          createdAt: d.created_at ?? null, updatedAt: d.updated_at ?? null, author: null, closed: d.state === 'closed', locked: Boolean(d.locked),
+          isAnswered: d.answer_comment_id !== undefined && d.answer_comment_id !== null,
+          category: cat ? { id: `DIC_${repo}#${cat.id}`, name: cat.name, slug: cat.slug, isAnswerable: Boolean(cat.is_answerable) } : null,
+          comments: { nodes: comments, totalCount: comments.length, pageInfo: { hasNextPage: false, endCursor: null } },
+        };
+      });
+      return { data: { repository: { id: `R_${repo}`, nameWithOwner: repo, discussions: { nodes, totalCount: nodes.length, pageInfo: { hasNextPage: false, endCursor: null } } } } };
+    }
     // unmodeled subfields under pullRequests/issues nodes are honest errors too (connection-level
     // fields like pageInfo/edges are allowed; only unknown PullRequest/Issue node fields error).
     if (/\bpullRequests\b/.test(query)) { const b = selectionFields(query, 'pullRequests').find((f) => !PR_FIELDS.has(f) && !CONNECTION_FIELDS.has(f)); if (b) return { errors: [unmodeled(b, 'PullRequest')] }; }
@@ -185,3 +290,109 @@ export async function resolveGithubGraphql(req: { query: string; variables?: Rec
   const unknownRoot = rootFields.find((f) => !['viewer', 'repository', 'node'].includes(f));
   return { errors: [unmodeled(unknownRoot ?? rootFields[0] ?? 'unknown', 'Query')] };
 }
+
+// ── The single-PR view model (repository.pullRequest) ──────────────────────────────────────
+// Every field folds from the SAME projection the REST twin serves — headRefOid is the PR's
+// resolved head sha, statusCheckRollup folds the SAME check-run/commit-status rows the REST
+// checks surface reads, closingIssuesReferences derives from the PR body's closing keywords
+// (the same linkage real GitHub computes). Nothing here is a second store.
+
+// GitHub GraphQL enum spellings for the rollup (StatusState / CheckStatusState / CheckConclusionState).
+function statusStateEnum(s: string | undefined): string {
+  const v = (s ?? 'pending').toUpperCase();
+  return ['ERROR', 'EXPECTED', 'FAILURE', 'PENDING', 'SUCCESS'].includes(v) ? v : 'PENDING';
+}
+function checkStatusEnum(s: string | undefined): string {
+  const v = (s ?? 'queued').toUpperCase();
+  return ['QUEUED', 'IN_PROGRESS', 'COMPLETED', 'WAITING', 'PENDING', 'REQUESTED'].includes(v) ? v : 'QUEUED';
+}
+function checkConclusionEnum(s: string | undefined): string | null {
+  if (!s) return null;
+  const v = s.toUpperCase();
+  return ['ACTION_REQUIRED', 'TIMED_OUT', 'CANCELLED', 'FAILURE', 'SUCCESS', 'NEUTRAL', 'SKIPPED', 'STARTUP_FAILURE', 'STALE'].includes(v) ? v : null;
+}
+
+/** The closing-keyword issue linkage (Closes/Fixes/Resolves #n) real GitHub derives from the PR body. */
+export function closingIssueNumbersFromBody(body: string | undefined): number[] {
+  const out: number[] = [];
+  for (const m of (body ?? '').matchAll(/\b(?:clos(?:e[sd]?|ing)|fix(?:e[sd]|ing)?|resolv(?:e[sd]?|ing))\s*:?\s+#(\d+)/gi)) {
+    const n = Number(m[1]);
+    if (!out.includes(n)) out.push(n);
+  }
+  return out;
+}
+
+type GhPrRow = GithubState['prs'][number];
+
+function resolvePullRequestView(state: GithubState, repo: string, pr: GhPrRow, root?: string): Record<string, unknown> {
+  const headSha = pr.head_sha ?? '';
+  // Latest commit-status per context (GitHub's rollup shows each context once, most recent wins).
+  const latestByContext = new Map<string, GithubState['statuses'][number]>();
+  for (const s of state.statuses.filter((s) => s.repository === repo && s.sha === headSha).sort((a, b) => a.id - b.id)) {
+    latestByContext.set(s.context ?? 'default', s);
+  }
+  const runs = state.checkRuns.filter((c) => c.repository === repo && c.head_sha === headSha).sort((a, b) => a.id - b.id);
+  const contexts: Array<Record<string, unknown>> = [
+    ...runs.map((c) => ({
+      __typename: 'CheckRun', name: c.name,
+      status: checkStatusEnum(c.status), conclusion: checkConclusionEnum(c.conclusion),
+      startedAt: c.started_at ?? null, completedAt: c.completed_at ?? null, detailsUrl: c.details_url ?? null,
+    })),
+    ...[...latestByContext.values()].map((s) => ({
+      __typename: 'StatusContext', context: s.context, state: statusStateEnum(s.state),
+      targetUrl: s.target_url ?? null, description: s.description ?? null, createdAt: s.created_at ?? null,
+    })),
+  ];
+  const anyFailed = contexts.some((c) =>
+    (c.__typename === 'CheckRun' && ['FAILURE', 'TIMED_OUT', 'CANCELLED', 'ACTION_REQUIRED', 'STARTUP_FAILURE'].includes(String(c.conclusion)))
+    || (c.__typename === 'StatusContext' && ['FAILURE', 'ERROR'].includes(String(c.state))));
+  const anyPending = contexts.some((c) =>
+    (c.__typename === 'CheckRun' && c.conclusion === null)
+    || (c.__typename === 'StatusContext' && ['PENDING', 'EXPECTED'].includes(String(c.state))));
+  const rollupState = contexts.length === 0 ? null : anyFailed ? 'FAILURE' : anyPending ? 'PENDING' : 'SUCCESS';
+  const rollup = {
+    nodes: [{
+      commit: {
+        statusCheckRollup: rollupState === null ? null : {
+          state: rollupState,
+          contexts: { nodes: contexts, totalCount: contexts.length, pageInfo: { hasNextPage: false, endCursor: null } },
+        },
+      },
+    }],
+  };
+  const comments = state.comments
+    .filter((c) => c.repository === repo && c.number === pr.number && c.kind === 'issue')
+    .map((c) => ({
+      id: `IC_${repo}#${c.id}`, author: null, authorAssociation: 'NONE',
+      body: c.body ?? '', createdAt: c.created_at ?? null, includesCreatedEdit: false, isMinimized: false,
+      minimizedReason: null, reactionGroups: [], url: `https://github.com/${repo}/pull/${pr.number}#issuecomment-${c.id}`,
+      viewerDidAuthor: false,
+    }));
+  const closing = closingIssueNumbersFromBody(pr.body)
+    .filter((n) => state.issues.some((i) => i.repository === repo && i.number === n))
+    .map((n) => {
+      const issue = state.issues.find((i) => i.repository === repo && i.number === n)!;
+      return { number: n, title: issue.title ?? null, url: `https://github.com/${repo}/issues/${n}` };
+    });
+  const stateEnum = pr.merged ? 'MERGED' : (pr.state ?? 'open').toUpperCase();
+  // changedFiles: carried count → carried per-file list → the REAL diff from the git plane
+  // (a pushed PR's true file count — merge-gate scope classification depends on this being
+  // the actual paths, not 0) → 0 only when no evidence exists anywhere.
+  const planeFiles = pr.changed_files === undefined && !pr.files?.length ? prPlaneDiffFiles(state, repo, pr, root) : null;
+  return {
+    number: pr.number, id: `PR_${repo}#${pr.number}`, url: `https://github.com/${repo}/pull/${pr.number}`,
+    title: pr.title ?? null, state: stateEnum, body: pr.body ?? '', isDraft: pr.draft ?? false,
+    headRefOid: headSha, headRefName: pr.head_ref ?? null, baseRefName: pr.base_ref ?? null,
+    changedFiles: pr.changed_files ?? pr.files?.length ?? planeFiles?.length ?? 0,
+    additions: pr.additions ?? 0, deletions: pr.deletions ?? 0,
+    createdAt: null, updatedAt: null, closedAt: null, mergedAt: pr.merged_at ?? null,
+    labels: { nodes: (pr.labels ?? []).map((name) => ({ name })), totalCount: (pr.labels ?? []).length },
+    closingIssuesReferences: { nodes: closing, totalCount: closing.length, pageInfo: { hasNextPage: false, endCursor: null } },
+    // gh's `statusCheckRollup` json field is the alias for commits(last:1){…} — serve BOTH
+    // spellings so the alias and the raw field name each resolve.
+    statusCheckRollup: rollup, commits: rollup,
+    comments: { nodes: comments, totalCount: comments.length, pageInfo: { hasNextPage: false, endCursor: null } },
+    assignees: { nodes: (pr.assignees ?? []).map((login) => ({ login, id: `U_${login}`, name: null })), totalCount: (pr.assignees ?? []).length },
+    reviewRequests: { nodes: (pr.requested_reviewers ?? []).map((login) => ({ requestedReviewer: { __typename: 'User', login } })), totalCount: (pr.requested_reviewers ?? []).length },
+  };
+}

package/src/github-journey.uitest.ts

@@ -0,0 +1,193 @@
+// GITHUB PILOT UI JOURNEY (TWIN-47 / H1, dev/02) — the first real proof of the uiJourney
+// harness: seed PRs/issues/reviews through the pack's OWN write path (`applyGithubWrite`,
+// same handler github-writes.test.ts / github-ui-structure.ts already use — never
+// hand-written events.jsonl), boot the real mirror server (`createGithubMirrorServer`) on an
+// ephemeral port, and drive it with real headless Playwright chromium using role/text
+// locators ONLY — the locators an agent transfers from the real GitHub UI, never a
+// className/test-id a test author invented. Proves navigation + LIVE interactivity: tab
+// clicks actually swap the rendered view, and selecting a PR actually flows PR-specific data
+// (body/review content) that the list row never shows.
+//
+// NOTE on assertions: we import the bare `playwright` library (not `@playwright/test`), so
+// there is no web-first `expect(locator).toBeVisible()`. Instead we use Playwright's own
+// auto-waiting/polling primitive directly — `locator.waitFor({ state })` — which retries until
+// the DOM state holds or the page's default timeout elapses, then throws (failing the
+// journey) if it never does. `visible`/`attached` prove seeded data reached the live DOM;
+// `detached` proves a view actually unmounted (not merely CSS-hidden) after a tab switch.
+//
+// Must never hard-fail on a browserless machine: skip cleanly (loud console line) when
+// `browserAvailable()` is false. The GATE-level advisory (never-silently-green) is the job of
+// scripts/ui-journeys.ts; this file's own skip is a courtesy for anyone running `bun test`
+// directly on a machine with no chromium cache.
+//
+// TWIN-49 (H3, dev/02) additions: the pilot journey now ALSO asserts the vendor-faithful
+// pathname at each navigation step (client-side pushState routing — see pathFor/stateFor in
+// github-mirror.tsx), an issue-detail case flips `github.journey.issue_detail` from a census
+// todo to a real spec (the Issues row is now a role-reachable <button>), and a NEW deep-link
+// journey `goto()`s a PR path directly (no clicking) and proves back/forward (popstate).
+import { describe, test } from 'bun:test';
+import type { Page } from 'playwright';
+import { requireBrowser, runUiJourney, JOURNEY_TIMEOUT_MS, visible, gone, atPath, waitForMount } from '@volter/twin-tooling';
+
+const JOURNEY_LABEL = 'github UI journey';
+import { applyGithubWrite } from './github-twin.ts';
+import { createGithubMirrorServer } from './github-mirror-ui.ts';
+
+// `.first()`: some seeded titles legitimately render TWICE at once (the currently-selected PR's
+// list row AND its Conversation <h2> both carry the title) — that duplication is real product
+// behavior, not a bug, so we assert against "at least/at most this one instance" rather than
+// forcing every locator to be uniquely-matching.
+/** Wait until `text` renders visibly on the live page (throws/fails the journey if it never does). */
+/** Wait until NO element matching `text` remains in the DOM (proves a real unmount, not CSS hiding). */
+/** Wait until the live page's pathname matches `path` exactly (proves pushState/popstate — not
+ *  the address-bar decoration text, the REAL `location.pathname` the browser tracks). */
+/** Wait until a DOM mount has actually happened after a fresh `page.goto` (the harness's own
+ *  mount-wait only covers the FIRST navigation; a deep-link journey re-navigates mid-test). */
+
+describe('github UI journey (pilot, TWIN-47 dev/02)', () => {
+  test('seeded PRs/issues/reviews are reachable by real browser navigation', async () => {
+    if (!(await requireBrowser(JOURNEY_LABEL))) return;
+
+    await runUiJourney({
+      label: 'github seeded PRs/issues/reviews are reachable by real browser navigat',
+      seed: async (root) => {
+        // Real write path — same handler github-writes.test.ts / github-ui-structure.ts use.
+        // PR #1 (earlier): a distinct, greppable title + body only the detail pane shows.
+        await applyGithubWrite({
+          method: 'POST', path: '/repos/acme/twin-journey/pulls', root,
+          body: JSON.stringify({ title: 'Twin Journey Alpha PR', head: 'alpha', base: 'main', body: 'alpha-pr-body-marker' }),
+          occurredAt: '2026-05-01T00:00:00Z',
+        });
+        // PR #2 (later, so it sorts first by updatedAt): distinct title/body + a review whose
+        // body is ONLY reachable once this PR is selected (never shown in the list row).
+        await applyGithubWrite({
+          method: 'POST', path: '/repos/acme/twin-journey/pulls', root,
+          body: JSON.stringify({ title: 'Twin Journey Beta PR', head: 'beta', base: 'main', body: 'beta-pr-body-marker' }),
+          occurredAt: '2026-05-02T00:00:00Z',
+        });
+        await applyGithubWrite({
+          method: 'POST', path: '/repos/acme/twin-journey/pulls/2/reviews', root,
+          body: JSON.stringify({ event: 'APPROVED', body: 'beta-review-body-marker' }),
+          occurredAt: '2026-05-02T01:00:00Z',
+        });
+        // One issue with a distinct title + body (the body is ONLY reachable once the issue is
+        // opened — the Issues list row never renders it) — proves both the Issues tab swap AND
+        // the issue-detail selection (dev/02: github.journey.issue_detail).
+        await applyGithubWrite({
+          method: 'POST', path: '/repos/acme/twin-journey/issues', root,
+          body: JSON.stringify({ title: 'Twin Journey Tracking Issue', body: 'tracking-issue-body-marker' }),
+          occurredAt: '2026-05-03T00:00:00Z',
+        });
+      },
+      serve: (root) => {
+        const server = createGithubMirrorServer({ root, port: 0 });
+        return { url: `http://127.0.0.1:${server.port}`, stop: () => server.stop() };
+      },
+      journey: async (page) => {
+        // 1. Navigation lands on the PR list; both seeded PR titles render (list view shows
+        //    ALL matching PRs, so both are visible before any selection). URL: the "all repos"
+        //    cross-repo pulls page (no PR opened yet) — /pulls.
+        await visible(page, 'Twin Journey Alpha PR');
+        await visible(page, 'Twin Journey Beta PR');
+        await atPath(page, '/pulls');
+
+        // 2. Click the Issues TAB (a real <button>, role-reachable) → the seeded issue title
+        //    appears AND the pulls-only markers (the seeded PR titles) are gone — proves the
+        //    click handler fired and the view actually swapped (hydration is live, not SSR
+        //    residue left over from the initial HTML). URL: /issues (no issue opened yet).
+        await page.getByRole('button', { name: /^Issues/ }).click();
+        await visible(page, 'Twin Journey Tracking Issue');
+        await gone(page, 'Twin Journey Alpha PR');
+        await gone(page, 'Twin Journey Beta PR');
+        await atPath(page, '/issues');
+
+        // 2b. Click the seeded issue's row (dev/02: github.journey.issue_detail — the Issues
+        //     row is a role-reachable <button>, not a bare onClick <div>). With only one seeded
+        //     issue, its detail pane is already shown as the split-pane default (same
+        //     single-item fallback the PR view uses, so no "gone before click" assertion here
+        //     — that's covered by the multi-PR case below); the URL is what proves the click
+        //     actually navigated: it becomes the issue's own repo-scoped detail path — issues
+        //     and PRs share one number counter, so this repo's 3rd object (after the 2 seeded
+        //     PRs) is issue #3.
+        await visible(page, 'tracking-issue-body-marker');
+        await page.getByRole('button', { name: /Twin Journey Tracking Issue/ }).click();
+        await atPath(page, '/acme/twin-journey/issues/3');
+
+        // 3. Click back to Pull requests — the PR titles reappear (round-trip proves the tab
+        //    state, not a one-way navigation, actually drives the render). URL: back to /pulls
+        //    (no PR opened in this run yet, so no numbered path).
+        await page.getByRole('button', { name: /^Pull requests/ }).click();
+        await visible(page, 'Twin Journey Alpha PR');
+        await atPath(page, '/pulls');
+
+        // 4. Click the Alpha PR's row (a real <button>, role-reachable via its title text) →
+        //    its body appears in the detail pane — content the list row NEVER renders (the
+        //    list row only shows title/repo/state/meta, never pr.body). This proves selection
+        //    state flows PR-specific data through a live store-door fetch (`GET /twin/store/mirror`), not a static shell.
+        //    URL: opening a PR always routes to ITS OWN repo's numbered path, even from the
+        //    "all repos" list — /acme/twin-journey/pull/1.
+        await gone(page, 'alpha-pr-body-marker'); // not shown pre-selection (Beta sorts first)
+        await page.getByRole('button', { name: /Twin Journey Alpha PR/ }).click();
+        await visible(page, 'alpha-pr-body-marker');
+        await atPath(page, '/acme/twin-journey/pull/1');
+
+        // 5. Click the Beta PR's row → its review body (seeded via a REAL review write)
+        //    becomes visible — proves the review data-coupling reaches the live DOM too, and
+        //    that switching selection re-renders (Alpha's body is no longer shown). URL moves
+        //    to PR #2's path.
+        await page.getByRole('button', { name: /Twin Journey Beta PR/ }).click();
+        await visible(page, 'beta-review-body-marker');
+        await gone(page, 'alpha-pr-body-marker');
+        await atPath(page, '/acme/twin-journey/pull/2');
+      },
+    });
+  }, JOURNEY_TIMEOUT_MS);
+});
+
+describe('github UI journey — deep link + back/forward (TWIN-49 / H3, dev/02)', () => {
+  test('a direct deep link to a PR renders it without clicking, and back restores it (popstate)', async () => {
+    if (!(await requireBrowser(JOURNEY_LABEL))) return;
+
+    await runUiJourney({
+      label: 'github a direct deep link to a PR renders it without clicking, and bac',
+      seed: async (root) => {
+        await applyGithubWrite({
+          method: 'POST', path: '/repos/acme/deep-link-journey/pulls', root,
+          body: JSON.stringify({ title: 'Deep Link Alpha PR', head: 'alpha', base: 'main', body: 'deep-link-alpha-body-marker' }),
+          occurredAt: '2026-05-10T00:00:00Z',
+        });
+        await applyGithubWrite({
+          method: 'POST', path: '/repos/acme/deep-link-journey/pulls', root,
+          body: JSON.stringify({ title: 'Deep Link Beta PR', head: 'beta', base: 'main', body: 'deep-link-beta-body-marker' }),
+          occurredAt: '2026-05-10T01:00:00Z',
+        });
+      },
+      serve: (root) => {
+        const server = createGithubMirrorServer({ root, port: 0 });
+        return { url: `http://127.0.0.1:${server.port}`, stop: () => server.stop() };
+      },
+      journey: async (page) => {
+        // Deep link: goto the PR #2 path DIRECTLY (no clicking at all) — the client must
+        // derive the initial view + selection from `location.pathname` on mount, not from any
+        // in-memory click history.
+        const origin = new URL(page.url()).origin;
+        await page.goto(`${origin}/acme/deep-link-journey/pull/2`);
+        await waitForMount(page);
+        await visible(page, 'deep-link-beta-body-marker');
+        await gone(page, 'deep-link-alpha-body-marker'); // proves PR #2 rendered, not a fallback/default
+        await atPath(page, '/acme/deep-link-journey/pull/2');
+
+        // Click to another view (real navigation, pushState) — proves the deep-linked page is
+        // still live/interactive, not a dead static render.
+        await page.getByRole('button', { name: /^Issues/ }).click();
+        await atPath(page, '/acme/deep-link-journey/issues');
+        await gone(page, 'deep-link-beta-body-marker');
+
+        // Back (popstate tooth): the PR view AND its URL are both restored.
+        await page.goBack();
+        await atPath(page, '/acme/deep-link-journey/pull/2');
+        await visible(page, 'deep-link-beta-body-marker');
+      },
+    });
+  }, JOURNEY_TIMEOUT_MS);
+});