@open-mercato/cezar 0.8.0-pr550.472 → 0.8.0-pr552.477

package/dist/server/forge/github.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import type { DraftPrInput, DraftPrOutcome, ForgeAvailability, ForgeComment, ForgeCommentsData, ForgeDriver, ForgeItem } from './types.js';
+import type { DraftPrInput, DraftPrOutcome, ForgeAvailability, ForgeComment, ForgeCommentsData, ForgeDriver, ForgeItem, ForgeTimelineEvent, ForgeTimelineEventKind } from './types.js';
 /** One GitHub issue or pull request, flattened for the cockpit's GitHub tab. */
 export type GithubItem = ForgeItem;
 export interface GithubData {
@@ -71,6 +71,192 @@ export declare function parseOwnerName(nameWithOwner: string): {
 } | null;
 export declare const GH_MAX_LIMIT = 1000;
 export declare function fetchGithub(repoRoot: string, refresh?: boolean, limit?: number): Promise<GithubData>;
+/** The event kinds rendered in v1 — an allowlist, so a new GitHub event type is dropped rather
+ *  than rendered and can never crash or clutter the thread. Real timelines carry plenty that
+ *  github.com itself doesn't surface (`subscribed`, `mentioned`, `review_requested`).
+ *
+ *  `reviewed` is deliberately absent: timeline `reviewed` rows DO carry a body and would work,
+ *  but `/pulls/{n}/reviews` is already normalized, chipped and empty-body-filtered, so sourcing
+ *  both would render every review twice. */
+export declare const TIMELINE_EVENT_KINDS: Set<ForgeTimelineEventKind>;
+/** Events get their OWN cap, independent of `THREAD_ENTRY_CAP`. A combined cap would mean a
+ *  thread with 150 comments and 100 events returns ~120 comments — silently removing contents
+ *  from a §2-protected response. */
+export declare const TIMELINE_EVENT_CAP = 200;
+/** `gh api --paginate` has no page limit, so the timeline fetch hand-rolls a bounded loop. */
+export declare const TIMELINE_MAX_PAGES = 10;
+/** ONE budget shared by every page. `gh()`'s timeout is per invocation, so ten pages at the 15 s
+ *  default would put the ceiling at 150 s — an order of magnitude worse than the single
+ *  `--paginate` spawn this replaces. The loop tracks a deadline and passes what's left. */
+export declare const TIMELINE_BUDGET_MS = 15000;
+/** Never spawn a page that cannot finish. A bare `remaining <= 0` guard catches only the exact
+ *  boundary; the realistic case is 300 ms left, which spawns `gh` with a 300 ms timeout, throws,
+ *  and is indistinguishable from a real endpoint failure. */
+export declare const TIMELINE_MIN_PAGE_MS = 2000;
+/** One timeline row. `event` stays a loose `z.string()` so unknown kinds parse and are dropped by
+ *  the allowlist rather than throwing the whole page. Extras are stripped by default — notably
+ *  `author.email`, which is read for nothing and must not reach the wire type. */
+export declare const ghTimelineEventSchema: z.ZodObject<{
+    event: z.ZodString;
+    id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    node_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    actor: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        login: z.ZodString;
+        avatar_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        login: string;
+        avatar_url?: string | null | undefined;
+    }, {
+        login: string;
+        avatar_url?: string | null | undefined;
+    }>>>;
+    url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    html_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    sha: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    author: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        name?: string | null | undefined;
+        date?: string | null | undefined;
+    }, {
+        name?: string | null | undefined;
+        date?: string | null | undefined;
+    }>>>;
+    label: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        name: z.ZodString;
+        color: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        color?: string | null | undefined;
+    }, {
+        name: string;
+        color?: string | null | undefined;
+    }>>>;
+    assignee: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        login: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        login: string;
+    }, {
+        login: string;
+    }>>>;
+    rename: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        from: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        to: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        from?: string | null | undefined;
+        to?: string | null | undefined;
+    }, {
+        from?: string | null | undefined;
+        to?: string | null | undefined;
+    }>>>;
+    source: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        issue: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            number: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            html_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            pull_request: z.ZodOptional<z.ZodNullable<z.ZodUnknown>>;
+        }, "strip", z.ZodTypeAny, {
+            number?: number | null | undefined;
+            title?: string | null | undefined;
+            html_url?: string | null | undefined;
+            pull_request?: unknown;
+        }, {
+            number?: number | null | undefined;
+            title?: string | null | undefined;
+            html_url?: string | null | undefined;
+            pull_request?: unknown;
+        }>>>;
+    }, "strip", z.ZodTypeAny, {
+        issue?: {
+            number?: number | null | undefined;
+            title?: string | null | undefined;
+            html_url?: string | null | undefined;
+            pull_request?: unknown;
+        } | null | undefined;
+    }, {
+        issue?: {
+            number?: number | null | undefined;
+            title?: string | null | undefined;
+            html_url?: string | null | undefined;
+            pull_request?: unknown;
+        } | null | undefined;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    event: string;
+    message?: string | null | undefined;
+    author?: {
+        name?: string | null | undefined;
+        date?: string | null | undefined;
+    } | null | undefined;
+    id?: number | null | undefined;
+    label?: {
+        name: string;
+        color?: string | null | undefined;
+    } | null | undefined;
+    url?: string | null | undefined;
+    rename?: {
+        from?: string | null | undefined;
+        to?: string | null | undefined;
+    } | null | undefined;
+    source?: {
+        issue?: {
+            number?: number | null | undefined;
+            title?: string | null | undefined;
+            html_url?: string | null | undefined;
+            pull_request?: unknown;
+        } | null | undefined;
+    } | null | undefined;
+    sha?: string | null | undefined;
+    created_at?: string | null | undefined;
+    html_url?: string | null | undefined;
+    node_id?: string | null | undefined;
+    actor?: {
+        login: string;
+        avatar_url?: string | null | undefined;
+    } | null | undefined;
+    assignee?: {
+        login: string;
+    } | null | undefined;
+}, {
+    event: string;
+    message?: string | null | undefined;
+    author?: {
+        name?: string | null | undefined;
+        date?: string | null | undefined;
+    } | null | undefined;
+    id?: number | null | undefined;
+    label?: {
+        name: string;
+        color?: string | null | undefined;
+    } | null | undefined;
+    url?: string | null | undefined;
+    rename?: {
+        from?: string | null | undefined;
+        to?: string | null | undefined;
+    } | null | undefined;
+    source?: {
+        issue?: {
+            number?: number | null | undefined;
+            title?: string | null | undefined;
+            html_url?: string | null | undefined;
+            pull_request?: unknown;
+        } | null | undefined;
+    } | null | undefined;
+    sha?: string | null | undefined;
+    created_at?: string | null | undefined;
+    html_url?: string | null | undefined;
+    node_id?: string | null | undefined;
+    actor?: {
+        login: string;
+        avatar_url?: string | null | undefined;
+    } | null | undefined;
+    assignee?: {
+        login: string;
+    } | null | undefined;
+}>;
 /** First 200 thread entries, then `truncated`; each body sliced to 8 000 chars (same cap as
  *  item bodies). */
 export declare const THREAD_ENTRY_CAP = 200;
@@ -80,6 +266,29 @@ export declare function normalizeComments(raw: unknown): ForgeComment[];
  *  COMMENTED/PENDING carry no signal in a flat thread and are dropped; the rest map to
  *  `kind: 'review'` (Q4). Exported for unit tests. */
 export declare function normalizeReviews(raw: unknown): ForgeComment[];
+/**
+ * `gh api …/issues/{n}/timeline` JSON → `ForgeTimelineEvent[]`, plus whether the cap fired.
+ *
+ * Returns `truncated` rather than just the array because the caller has no other way to learn it:
+ * `events.length === TIMELINE_EVENT_CAP` is ambiguous on a thread with exactly that many.
+ *
+ * Three details here are load-bearing and were verified against a real timeline, not assumed:
+ *
+ * 1. **`committed` rows return `created_at: null`** — the real timestamp is at `author.date`.
+ *    Mapping `created_at` naively yields `createdAt: null` on every commit, which string-sorts to
+ *    the top and silently reorders the entire thread.
+ * 2. **`committed` carries a git author, not a GitHub actor** — a name, no login, no avatar.
+ * 3. **The cap keeps the NEWEST events — `slice(-cap)`**, the opposite of the neighbouring
+ *    `mergeThread`, which head-slices. The timeline arrives oldest-first, so `slice(0, cap)` would
+ *    retain 200 stale day-one `labeled` rows and discard the merge and the recent commits — the
+ *    exact rows #525 asks for.
+ *
+ * Exported for unit tests.
+ */
+export declare function normalizeEvents(raw: unknown, cap?: number): {
+    events: ForgeTimelineEvent[];
+    truncated: boolean;
+};
 /** Merge comment/review lists chronologically (oldest first) and apply the entry cap. Exported
  *  for unit tests. */
 export declare function mergeThread(parts: ForgeComment[][], cap?: number): {
@@ -88,10 +297,44 @@ export declare function mergeThread(parts: ForgeComment[][], cap?: number): {
 };
 /** Test-only: drop the per-thread cache so cases don't leak state into each other. */
 export declare function __clearCommentsCacheForTests(): void;
+/** What the bounded timeline page loop returns. `stoppedShort` means "the timeline may have more
+ *  rows than we fetched" and has exactly three causes — the page cap, the budget floor, and a
+ *  failure on page ≥ 2. All three shorten the `commented` stream the same way, so all three feed
+ *  `truncated` and arm the comments top-up; the cause does not change the remedy. A short page is
+ *  the one exit that does NOT set it: that is the timeline genuinely ending. */
+type TimelinePages = {
+    rows: unknown[];
+    stoppedShort: boolean;
+};
+/**
+ * Walk `/issues/{n}/timeline` under ONE shared time budget.
+ *
+ * `gh api --paginate` is not used here: it pages *"until there are no more pages of results"* and
+ * exposes no page-limit flag, so the only way to bound the walk is to hand-roll it. The cap that
+ * `paginateCounts` gets comes from being a JS cursor loop, not from a `gh` flag.
+ *
+ * The budget is a **total**, not a per-page allowance. `gh()` takes its timeout per invocation, so
+ * ten sequential spawns at the 15 s default would put the ceiling at 150 s — an order of magnitude
+ * worse than the single `--paginate` spawn this replaces. The loop tracks a deadline and passes
+ * each page whatever remains.
+ *
+ * Exported for unit tests; `run` is injected so the loop is testable without shelling out.
+ */
+export declare function fetchTimelinePages(run: (page: number, timeoutMs: number) => Promise<string>, opts?: {
+    maxPages?: number;
+    budgetMs?: number;
+    minPageMs?: number;
+    now?: () => number;
+}): Promise<TimelinePages>;
 /**
  * The conversation thread for one issue/PR, lazily. `{owner}`/`{repo}` in the gh api paths are
  * filled from the worktree's remote by gh itself, so no extra handle lookup. Everything degrades:
  * gh missing/offline → `{ available: false, reason }`, a 404 → a "not found" hint — never a throw.
+ *
+ * Since #525 the thread is sourced from `/issues/{n}/timeline`, which returns comments AND events
+ * in one stream: `commented` rows go through the unchanged `normalizeComments`, the rest through
+ * `normalizeEvents`. `comments[]` therefore keeps its exact pre-#525 shape, contents and cap
+ * (BACKWARD_COMPATIBILITY.md §2) — see the top-up below for the one case that needed defending.
  */
 export declare function fetchGithubComments(repoRoot: string, kind: 'issue' | 'pr', number: number, refresh?: boolean): Promise<ForgeCommentsData>;
 export declare function createDraftPr(input: DraftPrInput): Promise<DraftPrOutcome>;

package/dist/server/forge/github.js

@@ -288,6 +288,82 @@ const ghReviewSchema = z.object({
     submitted_at: z.string().nullish(),
     html_url: z.string(),
 });
+// ---- timeline events (#525) -------------------------------------------------
+// The thread's non-comment history — commits, label changes, assignments, merges, force-pushes,
+// cross-references. Sourced from `/issues/{n}/timeline`, which returns comments AND events in one
+// chronological stream, so the `commented` rows keep flowing through `normalizeComments` unchanged
+// and `comments[]` stays exactly what BACKWARD_COMPATIBILITY.md §2 promises.
+/** The event kinds rendered in v1 — an allowlist, so a new GitHub event type is dropped rather
+ *  than rendered and can never crash or clutter the thread. Real timelines carry plenty that
+ *  github.com itself doesn't surface (`subscribed`, `mentioned`, `review_requested`).
+ *
+ *  `reviewed` is deliberately absent: timeline `reviewed` rows DO carry a body and would work,
+ *  but `/pulls/{n}/reviews` is already normalized, chipped and empty-body-filtered, so sourcing
+ *  both would render every review twice. */
+export const TIMELINE_EVENT_KINDS = new Set([
+    'committed',
+    'labeled',
+    'unlabeled',
+    'assigned',
+    'unassigned',
+    'merged',
+    'closed',
+    'reopened',
+    'head_ref_force_pushed',
+    'cross-referenced',
+    'renamed',
+]);
+/** Events get their OWN cap, independent of `THREAD_ENTRY_CAP`. A combined cap would mean a
+ *  thread with 150 comments and 100 events returns ~120 comments — silently removing contents
+ *  from a §2-protected response. */
+export const TIMELINE_EVENT_CAP = 200;
+/** `gh api --paginate` has no page limit, so the timeline fetch hand-rolls a bounded loop. */
+export const TIMELINE_MAX_PAGES = 10;
+/** ONE budget shared by every page. `gh()`'s timeout is per invocation, so ten pages at the 15 s
+ *  default would put the ceiling at 150 s — an order of magnitude worse than the single
+ *  `--paginate` spawn this replaces. The loop tracks a deadline and passes what's left. */
+export const TIMELINE_BUDGET_MS = 15_000;
+/** Never spawn a page that cannot finish. A bare `remaining <= 0` guard catches only the exact
+ *  boundary; the realistic case is 300 ms left, which spawns `gh` with a 300 ms timeout, throws,
+ *  and is indistinguishable from a real endpoint failure. */
+export const TIMELINE_MIN_PAGE_MS = 2_000;
+/** `committed` messages are trimmed to their first line, then this. */
+const COMMIT_MESSAGE_CAP = 120;
+/** One timeline row. `event` stays a loose `z.string()` so unknown kinds parse and are dropped by
+ *  the allowlist rather than throwing the whole page. Extras are stripped by default — notably
+ *  `author.email`, which is read for nothing and must not reach the wire type. */
+export const ghTimelineEventSchema = z.object({
+    event: z.string(),
+    id: z.number().nullish(),
+    node_id: z.string().nullish(),
+    created_at: z.string().nullish(),
+    actor: z.object({ login: z.string(), avatar_url: z.string().nullish() }).nullish(),
+    url: z.string().nullish(),
+    html_url: z.string().nullish(),
+    // `committed`
+    sha: z.string().nullish(),
+    message: z.string().nullish(),
+    author: z.object({ name: z.string().nullish(), date: z.string().nullish() }).nullish(),
+    // `labeled` / `unlabeled`
+    label: z.object({ name: z.string(), color: z.string().nullish() }).nullish(),
+    // `assigned` / `unassigned`
+    assignee: z.object({ login: z.string() }).nullish(),
+    // `renamed`
+    rename: z.object({ from: z.string().nullish(), to: z.string().nullish() }).nullish(),
+    // `cross-referenced`
+    source: z
+        .object({
+        issue: z
+            .object({
+            number: z.number().nullish(),
+            title: z.string().nullish(),
+            html_url: z.string().nullish(),
+            pull_request: z.unknown().nullish(),
+        })
+            .nullish(),
+    })
+        .nullish(),
+});
 const REVIEW_STATE = {
     APPROVED: 'approved',
     CHANGES_REQUESTED: 'changes_requested',
@@ -333,6 +409,111 @@ export function normalizeReviews(raw) {
         url: r.html_url,
     }));
 }
+/**
+ * `gh api …/issues/{n}/timeline` JSON → `ForgeTimelineEvent[]`, plus whether the cap fired.
+ *
+ * Returns `truncated` rather than just the array because the caller has no other way to learn it:
+ * `events.length === TIMELINE_EVENT_CAP` is ambiguous on a thread with exactly that many.
+ *
+ * Three details here are load-bearing and were verified against a real timeline, not assumed:
+ *
+ * 1. **`committed` rows return `created_at: null`** — the real timestamp is at `author.date`.
+ *    Mapping `created_at` naively yields `createdAt: null` on every commit, which string-sorts to
+ *    the top and silently reorders the entire thread.
+ * 2. **`committed` carries a git author, not a GitHub actor** — a name, no login, no avatar.
+ * 3. **The cap keeps the NEWEST events — `slice(-cap)`**, the opposite of the neighbouring
+ *    `mergeThread`, which head-slices. The timeline arrives oldest-first, so `slice(0, cap)` would
+ *    retain 200 stale day-one `labeled` rows and discard the merge and the recent commits — the
+ *    exact rows #525 asks for.
+ *
+ * Exported for unit tests.
+ */
+export function normalizeEvents(raw, cap = TIMELINE_EVENT_CAP) {
+    const rows = z.array(ghTimelineEventSchema).parse(raw);
+    const mapped = [];
+    rows.forEach((row, index) => {
+        const kind = row.event;
+        if (!TIMELINE_EVENT_KINDS.has(kind))
+            return; // unknown//noise → dropped, never rendered
+        // Per-kind timestamp resolution — see (1) above.
+        const rawAt = kind === 'committed' ? row.author?.date : row.created_at;
+        if (!rawAt)
+            return; // no resolvable timestamp → drop, rather than merge at an arbitrary spot
+        // `author.date` arrives with a numeric offset (`+02:00`); normalize so the string compare the
+        // thread sorts by stays correct across zones.
+        const parsedAt = new Date(rawAt);
+        if (Number.isNaN(parsedAt.getTime()))
+            return;
+        const createdAt = parsedAt.toISOString();
+        // Per-kind actor resolution — see (2) above.
+        const actor = (kind === 'committed' ? row.author?.name : row.actor?.login) ?? '?';
+        // Identity: `sha` sits ahead of `node_id` deliberately. `committed` rows carry both, and a
+        // node_id-first order would key commits by an opaque `C_kwDO…` blob instead of the SHA, which
+        // is the natural, debuggable identifier and is already the rollup key. The bare-index fallback
+        // reaches only `cross-referenced`, the one kind with no identity at all — as a general scheme
+        // it would be wrong, since the id becomes the React key and an index over the post-sort array
+        // shifts for every row below an insertion, remounting them on each 60 s refetch.
+        const identity = row.id ?? row.sha ?? row.node_id ?? index;
+        const event = {
+            id: `evt-${identity}`,
+            kind,
+            actor,
+            createdAt,
+        };
+        // A git author has no avatar, so `committed` deliberately carries none.
+        if (kind !== 'committed' && row.actor?.avatar_url)
+            event.avatarUrl = row.actor.avatar_url;
+        switch (kind) {
+            case 'committed': {
+                if (row.sha)
+                    event.sha = row.sha;
+                if (row.message)
+                    event.message = (row.message.split('\n')[0] ?? '').slice(0, COMMIT_MESSAGE_CAP);
+                if (row.html_url)
+                    event.url = row.html_url;
+                break;
+            }
+            case 'labeled':
+            case 'unlabeled': {
+                if (row.label) {
+                    event.label = { name: row.label.name };
+                    if (row.label.color)
+                        event.label.color = row.label.color;
+                }
+                break;
+            }
+            case 'assigned':
+            case 'unassigned': {
+                if (row.assignee?.login)
+                    event.subject = row.assignee.login;
+                break;
+            }
+            case 'renamed': {
+                if (row.rename?.to)
+                    event.subject = row.rename.to;
+                break;
+            }
+            case 'cross-referenced': {
+                const issue = row.source?.issue;
+                if (issue?.number != null)
+                    event.refNumber = issue.number;
+                if (issue?.title)
+                    event.refTitle = issue.title;
+                if (issue)
+                    event.refIsPr = Boolean(issue.pull_request);
+                if (issue?.html_url)
+                    event.url = issue.html_url;
+                break;
+            }
+            default:
+                break;
+        }
+        mapped.push(event);
+    });
+    const truncated = mapped.length > cap;
+    // slice(-cap), NOT slice(0, cap) — see (3) above.
+    return { events: truncated ? mapped.slice(-cap) : mapped, truncated };
+}
 /** Merge comment/review lists chronologically (oldest first) and apply the entry cap. Exported
  *  for unit tests. */
 export function mergeThread(parts, cap = THREAD_ENTRY_CAP) {
@@ -358,10 +539,70 @@ function cacheComments(key, data) {
 export function __clearCommentsCacheForTests() {
     commentsCache.clear();
 }
+const TIMELINE_PER_PAGE = 100;
+/**
+ * Walk `/issues/{n}/timeline` under ONE shared time budget.
+ *
+ * `gh api --paginate` is not used here: it pages *"until there are no more pages of results"* and
+ * exposes no page-limit flag, so the only way to bound the walk is to hand-roll it. The cap that
+ * `paginateCounts` gets comes from being a JS cursor loop, not from a `gh` flag.
+ *
+ * The budget is a **total**, not a per-page allowance. `gh()` takes its timeout per invocation, so
+ * ten sequential spawns at the 15 s default would put the ceiling at 150 s — an order of magnitude
+ * worse than the single `--paginate` spawn this replaces. The loop tracks a deadline and passes
+ * each page whatever remains.
+ *
+ * Exported for unit tests; `run` is injected so the loop is testable without shelling out.
+ */
+export async function fetchTimelinePages(run, opts = {}) {
+    const maxPages = opts.maxPages ?? TIMELINE_MAX_PAGES;
+    const budgetMs = opts.budgetMs ?? TIMELINE_BUDGET_MS;
+    const minPageMs = opts.minPageMs ?? TIMELINE_MIN_PAGE_MS;
+    const now = opts.now ?? Date.now;
+    const deadline = now() + budgetMs;
+    const rows = [];
+    let stoppedShort = false;
+    let page = 1;
+    for (; page <= maxPages; page++) {
+        const remaining = deadline - now();
+        // Never spawn a page that cannot finish. A bare `remaining <= 0` guard catches only the exact
+        // boundary; the realistic case is 300 ms left, which spawns gh with a 300 ms timeout, throws,
+        // and looks indistinguishable from a real endpoint failure.
+        if (remaining < minPageMs) {
+            stoppedShort = true;
+            break;
+        }
+        let parsed;
+        try {
+            parsed = z.array(z.unknown()).parse(JSON.parse(await run(page, remaining)));
+        }
+        catch (err) {
+            // Page 1 rethrows so the caller's inner catch can decide whether substitution helps —
+            // nothing was fetched, so there is nothing to lose. A failure on any later page keeps the
+            // pages already in hand: discarding nine good pages to re-fetch comments-only is strictly
+            // worse than what the loop already holds.
+            if (page === 1)
+                throw err;
+            stoppedShort = true;
+            break;
+        }
+        rows.push(...parsed);
+        if (parsed.length < TIMELINE_PER_PAGE)
+            break; // short page — the real end of the timeline
+    }
+    if (page > maxPages)
+        stoppedShort = true; // fell out on the page cap
+    return { rows, stoppedShort };
+}
 /**
  * The conversation thread for one issue/PR, lazily. `{owner}`/`{repo}` in the gh api paths are
  * filled from the worktree's remote by gh itself, so no extra handle lookup. Everything degrades:
  * gh missing/offline → `{ available: false, reason }`, a 404 → a "not found" hint — never a throw.
+ *
+ * Since #525 the thread is sourced from `/issues/{n}/timeline`, which returns comments AND events
+ * in one stream: `commented` rows go through the unchanged `normalizeComments`, the rest through
+ * `normalizeEvents`. `comments[]` therefore keeps its exact pre-#525 shape, contents and cap
+ * (BACKWARD_COMPATIBILITY.md §2) — see the top-up below for the one case that needed defending.
  */
 export async function fetchGithubComments(repoRoot, kind, number, refresh = false) {
     if (process.env.CEZ_DRY_RUN === '1')
@@ -370,16 +611,81 @@ export async function fetchGithubComments(repoRoot, kind, number, refresh = fals
     const hit = commentsCache.get(key);
     if (!refresh && hit && Date.now() - hit.at < CACHE_MS)
         return hit.data;
+    // PR conversation comments live on the issues endpoint too — always use it for the body thread.
+    const legacyComments = () => gh(repoRoot, ['api', `repos/{owner}/{repo}/issues/${number}/comments`, '--paginate']);
     try {
-        // PR conversation comments live on the issues endpoint too — always use it for the body thread.
-        const commentsOut = await gh(repoRoot, ['api', `repos/{owner}/{repo}/issues/${number}/comments`, '--paginate']);
-        const parts = [normalizeComments(JSON.parse(commentsOut))];
+        let commentRows = [];
+        let events;
+        let eventsTruncated = false;
+        let stoppedShort = false;
+        try {
+            const pages = await fetchTimelinePages((page, timeoutMs) => gh(repoRoot, [
+                'api',
+                '-H',
+                'Accept: application/vnd.github+json',
+                `repos/{owner}/{repo}/issues/${number}/timeline?per_page=${TIMELINE_PER_PAGE}&page=${page}`,
+            ], timeoutMs));
+            stoppedShort = pages.stoppedShort;
+            commentRows = pages.rows.filter((r) => r?.event === 'commented');
+            const normalized = normalizeEvents(pages.rows);
+            events = normalized.events;
+            eventsTruncated = normalized.truncated;
+            // Comments top-up. The two ENTRY caps are independent, but the FETCH budget is not: today's
+            // call is an unbounded --paginate over a comments-only endpoint, so every comment is fetched
+            // and mergeThread picks the oldest 200 from the complete set. Under the timeline those same
+            // 200 slots are filled from at most 1000 rows in which events compete with comments — so on
+            // a 1500-row thread with 250 interleaved comments, comments[] would return ~167 where today
+            // it returns 200. Same §2 defect class as a combined entry cap, arriving via the source set.
+            //
+            // The trigger deliberately over-fires: it cannot distinguish "comments were cut off" from
+            // "this thread just has few comments", because the second is only knowable by fetching them.
+            // So on an event-heavy thread with 30 comments it re-fetches 30 complete comments. Accepted
+            // — it fires only past ~1000 timeline rows, behind the 60 s LRU, and the alternative is a §2
+            // regression. In the other direction the threshold is provably sound: with ≥200 commented
+            // rows already in the oldest-first prefix, mergeThread's oldest-200 cut lies inside it.
+            if (stoppedShort && commentRows.length < THREAD_ENTRY_CAP) {
+                // Its OWN nested catch. The inner handler's remedy is the fallback — which is this very
+                // call — and the outer handler returns { available: false, comments: [] }, emptying a
+                // thread that was about to render. So a thrown top-up is swallowed: keep the commented
+                // rows the timeline already returned and carry on. That is at worst the short list the
+                // safeguard existed to avoid, never worse than not having attempted it.
+                try {
+                    commentRows = z.array(z.unknown()).parse(JSON.parse(await legacyComments()));
+                }
+                catch {
+                    // keep the timeline's own commented rows
+                }
+            }
+        }
+        catch (timelineErr) {
+            // Scoped INSIDE the existing outer catch on purpose: the outer handler's /404|not found/i
+            // branch would otherwise turn a timeline 404 into an empty thread. ENOENT is the one failure
+            // the fallback cannot rescue — nothing will work, and a second spawn fails identically.
+            const message = timelineErr instanceof Error ? timelineErr.message : String(timelineErr);
+            if (/ENOENT/.test(message))
+                throw timelineErr;
+            // Every other endpoint-level failure substitutes the legacy comments call. It is a
+            // substitution, not a retry — a different endpoint, which typically still answers. (A 403
+            // attaches to the token rather than the endpoint, so it cannot succeed either; not
+            // special-cased, since rate-limit replies are immediate and it costs one fast spawn.)
+            commentRows = z.array(z.unknown()).parse(JSON.parse(await legacyComments()));
+            events = undefined;
+        }
+        const parts = [normalizeComments(commentRows)];
         if (kind === 'pr') {
             const reviewsOut = await gh(repoRoot, ['api', `repos/{owner}/{repo}/pulls/${number}/reviews`, '--paginate']);
             parts.push(normalizeReviews(JSON.parse(reviewsOut)));
         }
         const { comments, truncated } = mergeThread(parts);
-        const data = { available: true, comments, truncated: truncated || undefined };
+        const data = {
+            available: true,
+            comments,
+            // OR-folded exactly as before, so the pre-existing >200-comments trigger is preserved
+            // rather than replaced.
+            truncated: truncated || eventsTruncated || stoppedShort || undefined,
+        };
+        if (events)
+            data.events = events;
         cacheComments(key, data);
         return data;
     }