patchrelay 0.15.0 → 0.17.0

package/README.md

@@ -1,8 +1,8 @@
 # PatchRelay
 
-PatchRelay is a self-hosted harness for Linear-driven Codex work on your own machine.
+PatchRelay is a self-hosted harness for running a controlled coding loop per Linear issue on your own machine.
 
-It receives Linear webhooks, routes issues to the right local repository, prepares durable issue worktrees, runs Codex sessions through `codex app-server`, and keeps the whole run observable and resumable from the CLI. GitHub webhooks drive reactive loops for CI repair, review fixes, and merge queue failures.
+It receives Linear webhooks, routes issues to the right local repository, prepares durable issue worktrees, runs Codex sessions through `codex app-server`, and keeps the whole issue loop observable and resumable from the CLI. GitHub webhooks drive reactive loops for CI repair, review fixes, and merge queue failures.
 
 PatchRelay is the system around the model:
 
@@ -10,7 +10,7 @@ PatchRelay is the system around the model:
 - Linear OAuth and workspace installations
 - issue-to-repo routing
 - issue worktree and branch lifecycle
-- run orchestration and thread continuity
+- context packaging, run orchestration, and thread continuity
 - reactive CI repair, review fix, and merge queue repair loops
 - native Linear agent input forwarding into active runs
 - read-only inspection and run reporting
@@ -21,7 +21,7 @@ If you want Codex to work inside your real repos with your real tools, secrets,
 
 - Keep the agent in the real environment instead of rebuilding that environment in a hosted sandbox.
 - Use your existing machine, repos, secrets, SSH config, shell tools, and deployment access.
-- Keep deterministic workflow logic outside the model: routing, run orchestration, worktree ownership, and reporting.
+- Keep deterministic workflow logic outside the model: context packaging, routing, run orchestration, worktree ownership, verification, and reporting.
 - Choose the Codex approval and sandbox settings that match your risk tolerance.
 - Let Linear drive the loop through delegation and native agent sessions.
 - Let GitHub drive reactive loops through PR reviews and CI check events.
@@ -33,6 +33,7 @@ PatchRelay does the deterministic harness work that you do not want to re-implem
 
 - verifies and deduplicates Linear and GitHub webhooks
 - maps issue events to the correct local project
+- packages the right issue, repo, review, and failure context for each loop
 - creates and reuses one durable worktree and branch per issue lifecycle
 - starts Codex threads for implementation runs
 - triggers reactive runs for CI failures, review feedback, and merge queue failures
@@ -50,7 +51,7 @@ PatchRelay works best when read as five layers with clear ownership:
 - integration layer: Linear webhooks, GitHub webhooks, OAuth, project routing, and state sync
 - observability layer: CLI inspection, reports, event trails, and operator endpoints
 
-That separation is intentional. PatchRelay is not the policy itself and it is not the coding agent. It is the harness that keeps those pieces coordinated in a real repository with real operational state.
+That separation is intentional. PatchRelay is not the policy itself and it is not the coding agent. It is the harness that keeps context, action, verification, and repair coordinated in a real repository with real operational state.
 
 ## Runtime Model
 
@@ -75,10 +76,10 @@ You will also need:
 ## How It Works
 
 1. A human delegates PatchRelay on an issue to start automation.
-2. PatchRelay verifies the webhook and routes the issue to the right local project.
+2. PatchRelay verifies the webhook, routes the issue to the right local project, and packages the issue context for the first loop.
 3. Delegated issues create or reuse the issue worktree and launch an implementation run through `codex app-server`.
 4. PatchRelay persists thread ids, run state, and observations so the work stays inspectable and resumable.
-5. GitHub webhooks drive reactive loops: CI repair on check failures, review fix on changes requested, and merge queue repair on queue failures.
+5. GitHub webhooks drive reactive verification and repair loops: CI repair on check failures, review fix on changes requested, and merge queue repair on queue failures.
 6. Native agent prompts and Linear comments can steer the active run. An operator can take over from the exact same worktree when needed.
 
 ## Factory State Machine
@@ -101,6 +102,8 @@ Run types:
 - `ci_repair` — fix failing CI checks
 - `queue_repair` — fix merge queue failures
 
+PatchRelay treats these as distinct loop types with different context, entry conditions, and success criteria rather than as one generic "ask the agent again" workflow.
+
 ## Restart And Reconciliation
 
 PatchRelay treats restart safety as part of the harness contract, not as a best-effort extra.
@@ -122,7 +125,7 @@ PatchRelay uses repo-local workflow files as prompts for Codex runs:
 - `IMPLEMENTATION_WORKFLOW.md` — used for implementation, CI repair, and queue repair runs
 - `REVIEW_WORKFLOW.md` — used for review fix runs
 
-These files define how the agent should work in that repository. Keep them short and action-oriented.
+These files define how the agent should work in that repository. Keep them short, action-oriented, and human-authored.
 
 ## Access Control
 

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "service": "patchrelay",
-  "version": "0.15.0",
-  "commit": "55a384ed81ec",
-  "builtAt": "2026-03-25T12:16:29.541Z"
+  "version": "0.17.0",
+  "commit": "972d51f6e0da",
+  "builtAt": "2026-03-25T12:55:22.635Z"
 }

package/dist/cli/watch/App.js

@@ -1,11 +1,21 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useReducer, useMemo } from "react";
+import { useReducer, useMemo, useCallback } from "react";
 import { Box, useApp, useInput } from "ink";
 import { watchReducer, initialWatchState, filterIssues } from "./watch-state.js";
 import { useWatchStream } from "./use-watch-stream.js";
 import { useDetailStream } from "./use-detail-stream.js";
 import { IssueListView } from "./IssueListView.js";
 import { IssueDetailView } from "./IssueDetailView.js";
+async function postRetry(baseUrl, issueKey, bearerToken) {
+    const headers = { "content-type": "application/json" };
+    if (bearerToken)
+        headers.authorization = `Bearer ${bearerToken}`;
+    await fetch(new URL(`/api/issues/${encodeURIComponent(issueKey)}/retry`, baseUrl), {
+        method: "POST",
+        headers,
+        signal: AbortSignal.timeout(5000),
+    }).catch(() => { });
+}
 export function App({ baseUrl, bearerToken, initialIssueKey }) {
     const { exit } = useApp();
     const [state, dispatch] = useReducer(watchReducer, {
@@ -15,6 +25,11 @@ export function App({ baseUrl, bearerToken, initialIssueKey }) {
     const filtered = useMemo(() => filterIssues(state.issues, state.filter), [state.issues, state.filter]);
     useWatchStream({ baseUrl, bearerToken, dispatch });
     useDetailStream({ baseUrl, bearerToken, issueKey: state.activeDetailKey, dispatch });
+    const handleRetry = useCallback(() => {
+        if (state.activeDetailKey) {
+            void postRetry(baseUrl, state.activeDetailKey, bearerToken);
+        }
+    }, [baseUrl, bearerToken, state.activeDetailKey]);
     useInput((input, key) => {
         if (input === "q") {
             exit();
@@ -44,7 +59,10 @@ export function App({ baseUrl, bearerToken, initialIssueKey }) {
             else if (input === "f") {
                 dispatch({ type: "toggle-follow" });
             }
+            else if (input === "r") {
+                handleRetry();
+            }
         }
     });
-    return (_jsx(Box, { flexDirection: "column", children: state.view === "list" ? (_jsx(IssueListView, { issues: filtered, selectedIndex: state.selectedIndex, connected: state.connected, filter: state.filter, totalCount: state.issues.length })) : (_jsx(IssueDetailView, { issue: state.issues.find((i) => i.issueKey === state.activeDetailKey), thread: state.thread, report: state.report, follow: state.follow })) }));
+    return (_jsx(Box, { flexDirection: "column", children: state.view === "list" ? (_jsx(IssueListView, { issues: filtered, selectedIndex: state.selectedIndex, connected: state.connected, filter: state.filter, totalCount: state.issues.length })) : (_jsx(IssueDetailView, { issue: state.issues.find((i) => i.issueKey === state.activeDetailKey), timeline: state.timeline, follow: state.follow, activeRunStartedAt: state.activeRunStartedAt, tokenUsage: state.tokenUsage, diffSummary: state.diffSummary, plan: state.plan })) }));
 }

package/dist/cli/watch/HelpBar.js

@@ -3,5 +3,5 @@ import { Box, Text } from "ink";
 export function HelpBar({ view, follow }) {
     return (_jsx(Box, { children: _jsx(Text, { dimColor: true, children: view === "list"
                 ? "j/k: navigate  Enter: detail  Tab: filter  q: quit"
-                : `Esc: back  f: follow ${follow ? "on" : "off"}  q: quit` }) }));
+                : `Esc: back  f: follow ${follow ? "on" : "off"}  r: retry  q: quit` }) }));
 }

package/dist/cli/watch/IssueDetailView.js

@@ -1,11 +1,8 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useReducer } from "react";
 import { Box, Text } from "ink";
-import { ThreadView } from "./ThreadView.js";
+import { Timeline } from "./Timeline.js";
 import { HelpBar } from "./HelpBar.js";
-function truncate(text, max) {
-    const line = text.replace(/\n/g, " ").trim();
-    return line.length > max ? `${line.slice(0, max - 3)}...` : line;
-}
 function formatTokens(n) {
     if (n >= 1_000_000)
         return `${(n / 1_000_000).toFixed(1)}M`;
@@ -13,16 +10,35 @@ function formatTokens(n) {
         return `${(n / 1_000).toFixed(1)}k`;
     return String(n);
 }
-function ThreadStatusBar({ thread, follow }) {
-    return (_jsxs(Box, { gap: 2, children: [thread.tokenUsage && (_jsxs(Text, { dimColor: true, children: ["tokens: ", formatTokens(thread.tokenUsage.inputTokens), " in / ", formatTokens(thread.tokenUsage.outputTokens), " out"] })), thread.diffSummary && thread.diffSummary.filesChanged > 0 && (_jsxs(Text, { dimColor: true, children: ["diff: ", thread.diffSummary.filesChanged, " file", thread.diffSummary.filesChanged !== 1 ? "s" : "", " ", "+", thread.diffSummary.linesAdded, " -", thread.diffSummary.linesRemoved] })), follow && _jsx(Text, { color: "yellow", children: "follow" })] }));
+function ElapsedTime({ startedAt }) {
+    const [, tick] = useReducer((c) => c + 1, 0);
+    useEffect(() => {
+        const id = setInterval(tick, 1000);
+        return () => clearInterval(id);
+    }, []);
+    const elapsed = Math.max(0, Math.floor((Date.now() - new Date(startedAt).getTime()) / 1000));
+    const minutes = Math.floor(elapsed / 60);
+    const seconds = elapsed % 60;
+    return _jsxs(Text, { dimColor: true, children: [minutes, "m ", String(seconds).padStart(2, "0"), "s"] });
+}
+function planStepSymbol(status) {
+    if (status === "completed")
+        return "\u2713";
+    if (status === "inProgress")
+        return "\u25b8";
+    return " ";
 }
-function ReportView({ report }) {
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { gap: 2, children: [_jsx(Text, { dimColor: true, children: "Latest run:" }), _jsx(Text, { bold: true, children: report.runType }), _jsx(Text, { color: report.status === "completed" ? "green" : "red", children: report.status })] }), report.summary && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Summary:" }), _jsx(Text, { wrap: "wrap", children: truncate(report.summary, 300) })] })), report.commands.length > 0 && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Text, { bold: true, children: ["Commands (", report.commands.length, "):"] }), report.commands.slice(-10).map((cmd, i) => (_jsxs(Box, { gap: 1, children: [_jsx(Text, { color: cmd.exitCode === 0 ? "green" : cmd.exitCode !== undefined ? "red" : "white", children: cmd.exitCode === 0 ? "\u2713" : cmd.exitCode !== undefined ? "\u2717" : " " }), _jsx(Text, { dimColor: true, children: "$ " }), _jsx(Text, { children: truncate(cmd.command, 60) }), cmd.durationMs !== undefined && _jsxs(Text, { dimColor: true, children: [" ", (cmd.durationMs / 1000).toFixed(1), "s"] })] }, `cmd-${i}`)))] })), _jsxs(Box, { marginTop: 1, gap: 2, children: [report.fileChanges > 0 && _jsxs(Text, { dimColor: true, children: [report.fileChanges, " file change", report.fileChanges !== 1 ? "s" : ""] }), report.toolCalls > 0 && _jsxs(Text, { dimColor: true, children: [report.toolCalls, " tool call", report.toolCalls !== 1 ? "s" : ""] }), report.assistantMessages.length > 0 && _jsxs(Text, { dimColor: true, children: [report.assistantMessages.length, " message", report.assistantMessages.length !== 1 ? "s" : ""] })] })] }));
+function planStepColor(status) {
+    if (status === "completed")
+        return "green";
+    if (status === "inProgress")
+        return "yellow";
+    return "white";
 }
-export function IssueDetailView({ issue, thread, report, follow }) {
+export function IssueDetailView({ issue, timeline, follow, activeRunStartedAt, tokenUsage, diffSummary, plan, }) {
     if (!issue) {
         return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: "red", children: "Issue not found." }), _jsx(HelpBar, { view: "detail", follow: follow })] }));
     }
     const key = issue.issueKey ?? issue.projectId;
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { gap: 2, children: [_jsx(Text, { bold: true, children: key }), _jsx(Text, { color: "cyan", children: issue.factoryState }), issue.activeRunType && _jsx(Text, { color: "yellow", children: issue.activeRunType }), issue.prNumber !== undefined && _jsxs(Text, { dimColor: true, children: ["PR #", issue.prNumber] })] }), issue.title && _jsx(Text, { dimColor: true, children: issue.title }), thread && _jsx(ThreadStatusBar, { thread: thread, follow: follow }), _jsx(Text, { dimColor: true, children: "─".repeat(72) }), thread ? (_jsx(ThreadView, { thread: thread, follow: follow })) : report ? (_jsx(ReportView, { report: report })) : (_jsx(Text, { dimColor: true, children: "Loading..." })), _jsx(Text, { dimColor: true, children: "─".repeat(72) }), _jsx(HelpBar, { view: "detail", follow: follow })] }));
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { gap: 2, children: [_jsx(Text, { bold: true, children: key }), _jsx(Text, { color: "cyan", children: issue.factoryState }), issue.activeRunType && _jsx(Text, { color: "yellow", children: issue.activeRunType }), issue.prNumber !== undefined && _jsxs(Text, { dimColor: true, children: ["PR #", issue.prNumber] }), activeRunStartedAt && _jsx(ElapsedTime, { startedAt: activeRunStartedAt })] }), issue.title && _jsx(Text, { dimColor: true, children: issue.title }), _jsxs(Box, { gap: 2, children: [tokenUsage && (_jsxs(Text, { dimColor: true, children: ["tokens: ", formatTokens(tokenUsage.inputTokens), " in / ", formatTokens(tokenUsage.outputTokens), " out"] })), diffSummary && diffSummary.filesChanged > 0 && (_jsxs(Text, { dimColor: true, children: ["diff: ", diffSummary.filesChanged, " file", diffSummary.filesChanged !== 1 ? "s" : "", " ", "+", diffSummary.linesAdded, " -", diffSummary.linesRemoved] })), follow && _jsx(Text, { color: "yellow", children: "follow" })] }), plan && plan.length > 0 && (_jsx(Box, { flexDirection: "column", children: plan.map((entry, i) => (_jsxs(Box, { gap: 1, children: [_jsxs(Text, { color: planStepColor(entry.status), children: ["[", planStepSymbol(entry.status), "]"] }), _jsx(Text, { children: entry.step })] }, `plan-${i}`))) })), _jsx(Text, { dimColor: true, children: "─".repeat(72) }), _jsx(Timeline, { entries: timeline, follow: follow }), _jsx(Text, { dimColor: true, children: "─".repeat(72) }), _jsx(HelpBar, { view: "detail", follow: follow })] }));
 }

package/dist/cli/watch/Timeline.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import { TimelineRow } from "./TimelineRow.js";
+const FOLLOW_TAIL_SIZE = 20;
+export function Timeline({ entries, follow }) {
+    const visible = follow && entries.length > FOLLOW_TAIL_SIZE
+        ? entries.slice(-FOLLOW_TAIL_SIZE)
+        : entries;
+    const skipped = entries.length - visible.length;
+    if (entries.length === 0) {
+        return _jsx(Text, { dimColor: true, children: "No timeline events yet." });
+    }
+    return (_jsxs(Box, { flexDirection: "column", children: [skipped > 0 && _jsxs(Text, { dimColor: true, children: ["  ... ", skipped, " earlier events"] }), visible.map((entry) => (_jsx(TimelineRow, { entry: entry }, entry.id)))] }));
+}

package/dist/cli/watch/TimelineRow.js

@@ -0,0 +1,62 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import { ItemLine } from "./ItemLine.js";
+function formatTime(iso) {
+    return new Date(iso).toLocaleTimeString("en-GB", { hour12: false });
+}
+function formatDuration(startedAt, endedAt) {
+    const ms = new Date(endedAt).getTime() - new Date(startedAt).getTime();
+    const seconds = Math.floor(ms / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = seconds % 60;
+    return `${minutes}m ${remainingSeconds}s`;
+}
+const CHECK_SYMBOLS = {
+    passed: "\u2713",
+    failed: "\u2717",
+    pending: "\u25cf",
+};
+const CHECK_COLORS = {
+    passed: "green",
+    failed: "red",
+    pending: "yellow",
+};
+function FeedRow({ entry }) {
+    const feed = entry.feed;
+    const statusLabel = feed.status ?? feed.feedKind;
+    return (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: formatTime(entry.at) }), _jsx(Text, { color: "cyan", children: statusLabel.padEnd(16) }), _jsx(Text, { children: feed.summary })] }));
+}
+function RunStartRow({ entry }) {
+    const run = entry.run;
+    return (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: formatTime(entry.at) }), _jsx(Text, { bold: true, color: "yellow", children: run.runType.padEnd(16) }), _jsx(Text, { bold: true, children: "run started" })] }));
+}
+function RunEndRow({ entry }) {
+    const run = entry.run;
+    const color = run.status === "completed" ? "green" : "red";
+    const duration = run.endedAt ? formatDuration(run.startedAt, run.endedAt) : "";
+    return (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: formatTime(entry.at) }), _jsx(Text, { bold: true, color: color, children: run.runType.padEnd(16) }), _jsx(Text, { bold: true, color: color, children: run.status }), duration ? _jsxs(Text, { dimColor: true, children: ["(", duration, ")"] }) : null] }));
+}
+function ItemRow({ entry }) {
+    const item = entry.item;
+    return (_jsx(Box, { paddingLeft: 2, children: _jsx(ItemLine, { item: item, isLast: false }) }));
+}
+function CIChecksRow({ entry }) {
+    const ci = entry.ciChecks;
+    return (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: formatTime(entry.at) }), _jsx(Text, { color: CHECK_COLORS[ci.overall] ?? "white", children: "ci_checks".padEnd(16) }), ci.checks.map((check, i) => (_jsxs(Text, { children: [_jsx(Text, { color: CHECK_COLORS[check.status] ?? "white", children: CHECK_SYMBOLS[check.status] ?? " " }), _jsxs(Text, { dimColor: true, children: [" ", check.name, "  "] })] }, `check-${i}`)))] }));
+}
+export function TimelineRow({ entry }) {
+    switch (entry.kind) {
+        case "feed":
+            return _jsx(FeedRow, { entry: entry });
+        case "run-start":
+            return _jsx(RunStartRow, { entry: entry });
+        case "run-end":
+            return _jsx(RunEndRow, { entry: entry });
+        case "item":
+            return _jsx(ItemRow, { entry: entry });
+        case "ci-checks":
+            return _jsx(CIChecksRow, { entry: entry });
+    }
+}

package/dist/cli/watch/timeline-builder.js

@@ -0,0 +1,363 @@
+// ─── Build Timeline from Rehydration Data ─────────────────────────
+export function buildTimelineFromRehydration(runs, feedEvents, liveThread, activeRunId) {
+    const entries = [];
+    // 1. Add run boundaries and items from reports
+    for (const run of runs) {
+        entries.push({
+            id: `run-start-${run.id}`,
+            at: run.startedAt,
+            kind: "run-start",
+            runId: run.id,
+            run: { runType: run.runType, status: run.status, startedAt: run.startedAt, endedAt: run.endedAt },
+        });
+        if (run.endedAt) {
+            entries.push({
+                id: `run-end-${run.id}`,
+                at: run.endedAt,
+                kind: "run-end",
+                runId: run.id,
+                run: { runType: run.runType, status: run.status, startedAt: run.startedAt, endedAt: run.endedAt },
+            });
+        }
+        // Items from completed run reports
+        if (run.report && run.id !== activeRunId) {
+            entries.push(...itemsFromReport(run.id, run.report, run.startedAt, run.endedAt));
+        }
+    }
+    // 2. Items from live thread (active run)
+    if (liveThread && activeRunId) {
+        entries.push(...itemsFromThread(activeRunId, liveThread));
+    }
+    // 3. Feed events → feed entries + CI check aggregation
+    entries.push(...feedEventsToEntries(feedEvents));
+    // 4. Sort by timestamp, then by entry order for stability
+    entries.sort((a, b) => {
+        const cmp = a.at.localeCompare(b.at);
+        if (cmp !== 0)
+            return cmp;
+        // Within same timestamp: run-start before items, items before run-end
+        return kindOrder(a.kind) - kindOrder(b.kind);
+    });
+    return entries;
+}
+function kindOrder(kind) {
+    switch (kind) {
+        case "run-start": return 0;
+        case "feed": return 1;
+        case "ci-checks": return 2;
+        case "item": return 3;
+        case "run-end": return 4;
+    }
+}
+// ─── Items from Report ────────────────────────────────────────────
+function itemsFromReport(runId, report, startedAt, endedAt) {
+    const entries = [];
+    const start = new Date(startedAt).getTime();
+    const end = endedAt ? new Date(endedAt).getTime() : start + 60000;
+    let idx = 0;
+    const total = report.commands.length + report.assistantMessages.length + report.toolCalls.length;
+    for (const msg of report.assistantMessages) {
+        entries.push({
+            id: `report-${runId}-msg-${idx}`,
+            at: syntheticTimestamp(start, end, idx, total),
+            kind: "item",
+            runId,
+            item: { id: `report-${runId}-msg-${idx}`, type: "agentMessage", status: "completed", text: msg },
+        });
+        idx++;
+    }
+    for (const cmd of report.commands) {
+        entries.push({
+            id: `report-${runId}-cmd-${idx}`,
+            at: syntheticTimestamp(start, end, idx, total),
+            kind: "item",
+            runId,
+            item: {
+                id: `report-${runId}-cmd-${idx}`,
+                type: "commandExecution",
+                status: "completed",
+                command: cmd.command,
+                ...(typeof cmd.exitCode === "number" ? { exitCode: cmd.exitCode } : {}),
+                ...(typeof cmd.durationMs === "number" ? { durationMs: cmd.durationMs } : {}),
+            },
+        });
+        idx++;
+    }
+    for (const tool of report.toolCalls) {
+        entries.push({
+            id: `report-${runId}-tool-${idx}`,
+            at: syntheticTimestamp(start, end, idx, total),
+            kind: "item",
+            runId,
+            item: {
+                id: `report-${runId}-tool-${idx}`,
+                type: tool.type === "mcp" ? "mcpToolCall" : "dynamicToolCall",
+                status: "completed",
+                toolName: tool.name,
+                ...(typeof tool.durationMs === "number" ? { durationMs: tool.durationMs } : {}),
+            },
+        });
+        idx++;
+    }
+    if (report.fileChanges.length > 0) {
+        entries.push({
+            id: `report-${runId}-files`,
+            at: syntheticTimestamp(start, end, idx, total),
+            kind: "item",
+            runId,
+            item: {
+                id: `report-${runId}-files`,
+                type: "fileChange",
+                status: "completed",
+                changes: report.fileChanges,
+            },
+        });
+    }
+    return entries;
+}
+function syntheticTimestamp(startMs, endMs, index, total) {
+    if (total <= 1)
+        return new Date(startMs).toISOString();
+    const fraction = index / (total - 1);
+    return new Date(startMs + fraction * (endMs - startMs)).toISOString();
+}
+// ─── Items from Live Thread ───────────────────────────────────────
+function itemsFromThread(runId, thread) {
+    const entries = [];
+    for (const turn of thread.turns) {
+        for (const item of turn.items) {
+            entries.push({
+                id: `live-${item.id}`,
+                at: new Date().toISOString(), // live items don't have timestamps; they'll sort to the end
+                kind: "item",
+                runId,
+                item: materializeItem(item),
+            });
+        }
+    }
+    return entries;
+}
+function materializeItem(item) {
+    const r = item;
+    const id = String(r.id ?? "unknown");
+    const type = String(r.type ?? "unknown");
+    const base = { id, type, status: "completed" };
+    switch (type) {
+        case "agentMessage":
+            return { ...base, text: String(r.text ?? "") };
+        case "commandExecution":
+            return {
+                ...base,
+                command: String(r.command ?? ""),
+                status: String(r.status ?? "completed"),
+                ...(typeof r.exitCode === "number" ? { exitCode: r.exitCode } : {}),
+                ...(typeof r.durationMs === "number" ? { durationMs: r.durationMs } : {}),
+                ...(typeof r.aggregatedOutput === "string" ? { output: r.aggregatedOutput } : {}),
+            };
+        case "fileChange":
+            return { ...base, status: String(r.status ?? "completed"), changes: Array.isArray(r.changes) ? r.changes : [] };
+        case "mcpToolCall":
+            return {
+                ...base,
+                status: String(r.status ?? "completed"),
+                toolName: `${String(r.server ?? "")}/${String(r.tool ?? "")}`,
+                ...(typeof r.durationMs === "number" ? { durationMs: r.durationMs } : {}),
+            };
+        case "dynamicToolCall":
+            return {
+                ...base,
+                status: String(r.status ?? "completed"),
+                toolName: String(r.tool ?? ""),
+                ...(typeof r.durationMs === "number" ? { durationMs: r.durationMs } : {}),
+            };
+        case "plan":
+            return { ...base, text: String(r.text ?? "") };
+        case "reasoning":
+            return { ...base, text: Array.isArray(r.summary) ? r.summary.join("\n") : "" };
+        default:
+            return base;
+    }
+}
+// ─── Feed Events to Timeline Entries ──────────────────────────────
+function feedEventsToEntries(feedEvents) {
+    const entries = [];
+    const ciAggregator = new CICheckAggregator();
+    for (const event of feedEvents) {
+        // GitHub check events get aggregated
+        if (event.kind === "github" && (event.status === "check_passed" || event.status === "check_failed") && event.detail) {
+            const ciEntry = ciAggregator.add(event);
+            if (ciEntry) {
+                // Replace the last ci-checks entry if it was updated
+                const lastIdx = entries.findLastIndex((e) => e.kind === "ci-checks" && e.id === ciEntry.id);
+                if (lastIdx >= 0) {
+                    entries[lastIdx] = ciEntry;
+                }
+                else {
+                    entries.push(ciEntry);
+                }
+            }
+            continue;
+        }
+        entries.push({
+            id: `feed-${event.id}`,
+            at: event.at,
+            kind: "feed",
+            feed: {
+                feedKind: event.kind,
+                ...(event.status ? { status: event.status } : {}),
+                summary: event.summary,
+                ...(event.detail ? { detail: event.detail } : {}),
+            },
+        });
+    }
+    return entries;
+}
+// ─── CI Check Aggregation ─────────────────────────────────────────
+const CI_CHECK_WINDOW_MS = 60_000;
+class CICheckAggregator {
+    currentGroup = null;
+    groupCounter = 0;
+    add(event) {
+        const name = event.detail ?? "unknown";
+        const status = event.status === "check_passed" ? "passed" : "failed";
+        const eventMs = new Date(event.at).getTime();
+        if (this.currentGroup && eventMs - this.currentGroup.windowStart < CI_CHECK_WINDOW_MS) {
+            this.currentGroup.checks.set(name, status);
+            return this.toEntry();
+        }
+        this.groupCounter++;
+        this.currentGroup = {
+            id: `ci-checks-${this.groupCounter}`,
+            at: event.at,
+            checks: new Map([[name, status]]),
+            windowStart: eventMs,
+        };
+        return this.toEntry();
+    }
+    toEntry() {
+        const group = this.currentGroup;
+        const checks = [...group.checks.entries()].map(([name, status]) => ({ name, status }));
+        const overall = checks.every((c) => c.status === "passed") ? "passed"
+            : checks.some((c) => c.status === "failed") ? "failed"
+                : "pending";
+        return {
+            id: group.id,
+            at: group.at,
+            kind: "ci-checks",
+            ciChecks: { checks, overall },
+        };
+    }
+}
+// ─── Live Append Helpers ──────────────────────────────────────────
+export function appendFeedToTimeline(timeline, event) {
+    // GitHub check events: aggregate into existing ci-checks entry
+    if (event.kind === "github" && (event.status === "check_passed" || event.status === "check_failed") && event.detail) {
+        return aggregateCICheckIntoTimeline(timeline, event);
+    }
+    return [...timeline, {
+            id: `feed-${event.id}`,
+            at: event.at,
+            kind: "feed",
+            feed: {
+                feedKind: event.kind,
+                ...(event.status ? { status: event.status } : {}),
+                summary: event.summary,
+                ...(event.detail ? { detail: event.detail } : {}),
+            },
+        }];
+}
+function aggregateCICheckIntoTimeline(timeline, event) {
+    const name = event.detail ?? "unknown";
+    const status = event.status === "check_passed" ? "passed" : "failed";
+    const eventMs = new Date(event.at).getTime();
+    // Find the most recent ci-checks entry within the window
+    for (let i = timeline.length - 1; i >= 0; i--) {
+        const entry = timeline[i];
+        if (entry.kind === "ci-checks" && entry.ciChecks) {
+            const entryMs = new Date(entry.at).getTime();
+            if (eventMs - entryMs < CI_CHECK_WINDOW_MS) {
+                const updatedChecks = [...entry.ciChecks.checks.filter((c) => c.name !== name), { name, status }];
+                const overall = updatedChecks.every((c) => c.status === "passed") ? "passed"
+                    : updatedChecks.some((c) => c.status === "failed") ? "failed"
+                        : "pending";
+                const updated = [...timeline];
+                updated[i] = { ...entry, ciChecks: { checks: updatedChecks, overall } };
+                return updated;
+            }
+            break;
+        }
+    }
+    // No recent ci-checks entry; create new one
+    return [...timeline, {
+            id: `ci-checks-live-${event.id}`,
+            at: event.at,
+            kind: "ci-checks",
+            ciChecks: { checks: [{ name, status }], overall: status },
+        }];
+}
+export function appendCodexItemToTimeline(timeline, params, activeRunId) {
+    const itemObj = params.item;
+    if (!itemObj)
+        return timeline;
+    const id = typeof itemObj.id === "string" ? itemObj.id : "unknown";
+    const type = typeof itemObj.type === "string" ? itemObj.type : "unknown";
+    const status = typeof itemObj.status === "string" ? itemObj.status : "inProgress";
+    const item = { id, type, status };
+    if (type === "agentMessage" && typeof itemObj.text === "string")
+        item.text = itemObj.text;
+    if (type === "commandExecution") {
+        const cmd = itemObj.command;
+        item.command = Array.isArray(cmd) ? cmd.join(" ") : typeof cmd === "string" ? cmd : undefined;
+    }
+    if (type === "mcpToolCall") {
+        item.toolName = `${String(itemObj.server ?? "")}/${String(itemObj.tool ?? "")}`;
+    }
+    if (type === "dynamicToolCall") {
+        item.toolName = typeof itemObj.tool === "string" ? itemObj.tool : undefined;
+    }
+    return [...timeline, {
+            id: `live-${id}`,
+            at: new Date().toISOString(),
+            kind: "item",
+            runId: activeRunId ?? undefined,
+            item,
+        }];
+}
+export function completeCodexItemInTimeline(timeline, params) {
+    const itemObj = params.item;
+    if (!itemObj)
+        return timeline;
+    const id = typeof itemObj.id === "string" ? itemObj.id : undefined;
+    if (!id)
+        return timeline;
+    const status = typeof itemObj.status === "string" ? itemObj.status : "completed";
+    const exitCode = typeof itemObj.exitCode === "number" ? itemObj.exitCode : undefined;
+    const durationMs = typeof itemObj.durationMs === "number" ? itemObj.durationMs : undefined;
+    const text = typeof itemObj.text === "string" ? itemObj.text : undefined;
+    const changes = Array.isArray(itemObj.changes) ? itemObj.changes : undefined;
+    return timeline.map((entry) => {
+        if (entry.kind !== "item" || entry.item?.id !== id)
+            return entry;
+        return {
+            ...entry,
+            item: {
+                ...entry.item,
+                status,
+                ...(exitCode !== undefined ? { exitCode } : {}),
+                ...(durationMs !== undefined ? { durationMs } : {}),
+                ...(text !== undefined ? { text } : {}),
+                ...(changes !== undefined ? { changes } : {}),
+            },
+        };
+    });
+}
+export function appendDeltaToTimelineItem(timeline, itemId, field, delta) {
+    return timeline.map((entry) => {
+        if (entry.kind !== "item" || entry.item?.id !== itemId)
+            return entry;
+        return {
+            ...entry,
+            item: { ...entry.item, [field]: (entry.item[field] ?? "") + delta },
+        };
+    });
+}