patchrelay 0.14.2 → 0.16.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.14.2",
-  "commit": "c132666b1710",
-  "builtAt": "2026-03-25T11:31:53.145Z"
+  "version": "0.16.0",
+  "commit": "396ce21398c4",
+  "builtAt": "2026-03-25T12:29:18.014Z"
 }

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();
@@ -41,7 +56,13 @@ export function App({ baseUrl, bearerToken, initialIssueKey }) {
             if (key.escape || key.backspace || key.delete) {
                 dispatch({ type: "exit-detail" });
             }
+            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 })) }));
+    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, feedEntries: state.detailFeed })) }));
 }

package/dist/cli/watch/FeedTimeline.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+const KIND_COLORS = {
+    stage: "cyan",
+    turn: "yellow",
+    github: "green",
+    webhook: "blue",
+    workflow: "magenta",
+    hook: "white",
+};
+function kindColor(kind) {
+    return KIND_COLORS[kind] ?? "white";
+}
+function formatTime(iso) {
+    return new Date(iso).toLocaleTimeString("en-GB", { hour12: false });
+}
+export function FeedTimeline({ entries, maxEntries }) {
+    const visible = maxEntries ? entries.slice(-maxEntries) : entries;
+    if (visible.length === 0) {
+        return _jsx(Text, { dimColor: true, children: "No events yet." });
+    }
+    return (_jsx(Box, { flexDirection: "column", children: visible.map((entry, i) => (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: formatTime(entry.at) }), _jsx(Text, { color: kindColor(entry.kind), children: (entry.status ?? entry.kind).padEnd(15) }), _jsx(Text, { children: entry.summary })] }, `feed-${i}`))) }));
+}

package/dist/cli/watch/HelpBar.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Box, Text } from "ink";
-export function HelpBar({ view }) {
+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  q: quit" }) }));
+                : `Esc: back  f: follow ${follow ? "on" : "off"}  r: retry  q: quit` }) }));
 }

package/dist/cli/watch/IssueDetailView.js

@@ -1,18 +1,29 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
 import { Box, Text } from "ink";
 import { ThreadView } from "./ThreadView.js";
+import { FeedTimeline } from "./FeedTimeline.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`;
+    if (n >= 1_000)
+        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 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" : ""] })] })] }));
 }
-export function IssueDetailView({ issue, thread, report }) {
+export function IssueDetailView({ issue, thread, report, follow, feedEntries }) {
     if (!issue) {
-        return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: "red", children: "Issue not found." }), _jsx(HelpBar, { view: "detail" })] }));
+        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 }), _jsx(Text, { dimColor: true, children: "─".repeat(72) }), thread ? (_jsx(ThreadView, { thread: thread })) : report ? (_jsx(ReportView, { report: report })) : (_jsx(Text, { dimColor: true, children: "Loading..." })), _jsx(Text, { dimColor: true, children: "─".repeat(72) }), _jsx(HelpBar, { view: "detail" })] }));
+    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..." })), feedEntries.length > 0 && (_jsxs(_Fragment, { children: [_jsx(Text, { dimColor: true, children: "─".repeat(72) }), _jsx(Text, { bold: true, dimColor: true, children: "Events:" }), _jsx(FeedTimeline, { entries: feedEntries, maxEntries: follow ? 5 : undefined })] })), _jsx(Text, { dimColor: true, children: "─".repeat(72) }), _jsx(HelpBar, { view: "detail", follow: follow })] }));
 }

package/dist/cli/watch/ThreadView.js

@@ -15,6 +15,12 @@ function planStepColor(status) {
         return "yellow";
     return "white";
 }
-export function ThreadView({ thread }) {
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { gap: 2, children: [_jsxs(Text, { dimColor: true, children: ["Thread: ", thread.threadId.slice(0, 16)] }), _jsxs(Text, { dimColor: true, children: ["Status: ", thread.status] }), _jsxs(Text, { dimColor: true, children: ["Turns: ", thread.turns.length] })] }), thread.plan && thread.plan.length > 0 && (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { bold: true, children: "Plan:" }), thread.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(Box, { flexDirection: "column", marginTop: 1, children: thread.turns.map((turn, i) => (_jsx(TurnSection, { turn: turn, index: i }, turn.id))) })] }));
+export function ThreadView({ thread, follow }) {
+    const visibleTurns = follow && thread.turns.length > 1
+        ? thread.turns.slice(-1)
+        : thread.turns;
+    const turnOffset = follow && thread.turns.length > 1
+        ? thread.turns.length - 1
+        : 0;
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { gap: 2, children: [_jsxs(Text, { dimColor: true, children: ["Thread: ", thread.threadId.slice(0, 16)] }), _jsxs(Text, { dimColor: true, children: ["Status: ", thread.status] }), _jsxs(Text, { dimColor: true, children: ["Turns: ", thread.turns.length] })] }), thread.plan && thread.plan.length > 0 && (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { bold: true, children: "Plan:" }), thread.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(Box, { flexDirection: "column", marginTop: 1, children: visibleTurns.map((turn, i) => (_jsx(TurnSection, { turn: turn, index: i + turnOffset, follow: follow }, turn.id))) })] }));
 }

package/dist/cli/watch/TurnSection.js

@@ -10,6 +10,11 @@ function turnStatusColor(status) {
         return "yellow";
     return "white";
 }
-export function TurnSection({ turn, index }) {
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { gap: 1, children: [_jsxs(Text, { bold: true, children: ["Turn #", index + 1] }), _jsx(Text, { color: turnStatusColor(turn.status), children: turn.status }), _jsxs(Text, { dimColor: true, children: ["(", turn.items.length, " items)"] })] }), turn.items.map((item, i) => (_jsx(ItemLine, { item: item, isLast: i === turn.items.length - 1 }, item.id)))] }));
+const FOLLOW_TAIL_SIZE = 8;
+export function TurnSection({ turn, index, follow }) {
+    const items = follow && turn.items.length > FOLLOW_TAIL_SIZE
+        ? turn.items.slice(-FOLLOW_TAIL_SIZE)
+        : turn.items;
+    const skipped = turn.items.length - items.length;
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { gap: 1, children: [_jsxs(Text, { bold: true, children: ["Turn #", index + 1] }), _jsx(Text, { color: turnStatusColor(turn.status), children: turn.status }), _jsxs(Text, { dimColor: true, children: ["(", turn.items.length, " items)"] })] }), skipped > 0 && _jsxs(Text, { dimColor: true, children: ["  ... ", skipped, " earlier items"] }), items.map((item, i) => (_jsx(ItemLine, { item: item, isLast: i === items.length - 1 }, item.id)))] }));
 }

package/dist/cli/watch/watch-state.js

@@ -7,6 +7,8 @@ export const initialWatchState = {
     thread: null,
     report: null,
     filter: "non-done",
+    follow: true,
+    detailFeed: [],
 };
 const TERMINAL_FACTORY_STATES = new Set(["done", "failed"]);
 export function filterIssues(issues, filter) {
@@ -46,9 +48,9 @@ export function watchReducer(state, action) {
                 selectedIndex: Math.max(0, Math.min(action.index, state.issues.length - 1)),
             };
         case "enter-detail":
-            return { ...state, view: "detail", activeDetailKey: action.issueKey, thread: null, report: null };
+            return { ...state, view: "detail", activeDetailKey: action.issueKey, thread: null, report: null, detailFeed: [] };
         case "exit-detail":
-            return { ...state, view: "list", activeDetailKey: null, thread: null, report: null };
+            return { ...state, view: "list", activeDetailKey: null, thread: null, report: null, detailFeed: [] };
         case "thread-snapshot":
             return { ...state, thread: action.thread };
         case "report-snapshot":
@@ -57,6 +59,8 @@ export function watchReducer(state, action) {
             return applyCodexNotification(state, action.method, action.params);
         case "cycle-filter":
             return { ...state, filter: nextFilter(state.filter), selectedIndex: 0 };
+        case "toggle-follow":
+            return { ...state, follow: !state.follow };
     }
 }
 // ─── Feed Event Application ───────────────────────────────────────
@@ -89,7 +93,17 @@ function applyFeedEvent(state, event) {
     }
     issue.updatedAt = event.at;
     updated[index] = issue;
-    return { ...state, issues: updated };
+    // Append to detail feed if this event matches the active detail issue
+    const detailFeed = state.view === "detail" && state.activeDetailKey === event.issueKey
+        ? [...state.detailFeed, {
+                at: event.at,
+                kind: event.kind,
+                summary: event.summary,
+                ...(event.status ? { status: event.status } : {}),
+                ...(event.detail ? { detail: event.detail } : {}),
+            }]
+        : state.detailFeed;
+    return { ...state, issues: updated, detailFeed };
 }
 // ─── Codex Notification Application ───────────────────────────────
 function applyCodexNotification(state, method, params) {
@@ -123,6 +137,8 @@ function applyCodexNotification(state, method, params) {
             return withThread(state, appendItemText(state.thread, params));
         case "thread/status/changed":
             return withThread(state, updateThreadStatus(state.thread, params));
+        case "thread/tokenUsage/updated":
+            return withThread(state, updateTokenUsage(state.thread, params));
         default:
             return state;
     }
@@ -185,7 +201,34 @@ function updatePlan(thread, params) {
 }
 function updateDiff(thread, params) {
     const diff = typeof params.diff === "string" ? params.diff : undefined;
-    return { ...thread, diff };
+    return { ...thread, diff, diffSummary: diff ? parseDiffSummary(diff) : undefined };
+}
+function parseDiffSummary(diff) {
+    const files = new Set();
+    let added = 0;
+    let removed = 0;
+    for (const line of diff.split("\n")) {
+        if (line.startsWith("+++ b/")) {
+            files.add(line.slice(6));
+        }
+        else if (line.startsWith("+") && !line.startsWith("+++")) {
+            added += 1;
+        }
+        else if (line.startsWith("-") && !line.startsWith("---")) {
+            removed += 1;
+        }
+    }
+    return { filesChanged: files.size, linesAdded: added, linesRemoved: removed };
+}
+function updateTokenUsage(thread, params) {
+    const usage = params.usage;
+    if (!usage)
+        return thread;
+    const inputTokens = typeof usage.inputTokens === "number" ? usage.inputTokens
+        : typeof usage.input_tokens === "number" ? usage.input_tokens : 0;
+    const outputTokens = typeof usage.outputTokens === "number" ? usage.outputTokens
+        : typeof usage.output_tokens === "number" ? usage.output_tokens : 0;
+    return { ...thread, tokenUsage: { inputTokens, outputTokens } };
 }
 function updateThreadStatus(thread, params) {
     const statusObj = params.status;

package/dist/config.js

@@ -95,7 +95,7 @@ const configSchema = z.object({
             approval_policy: z.enum(["never", "on-request", "on-failure", "untrusted"]).default("never"),
             sandbox_mode: z.enum(["danger-full-access", "workspace-write", "read-only"]).default("danger-full-access"),
             persist_extended_history: z.boolean().default(false),
-            experimental_raw_events: z.boolean().default(false),
+            experimental_raw_events: z.boolean().default(true),
         }),
     }),
     projects: z.array(projectSchema).default([]),

package/dist/db/migrations.js

@@ -131,6 +131,8 @@ export function runPatchRelayMigrations(connection) {
     connection.prepare("UPDATE webhook_events SET processing_status = 'processed' WHERE processing_status = 'pending' AND payload_json IS NULL").run();
     // Add pending_merge_prep column for merge queue stewardship
     addColumnIfMissing(connection, "issues", "pending_merge_prep", "INTEGER NOT NULL DEFAULT 0");
+    // Add merge_prep_attempts for retry budget / escalation
+    addColumnIfMissing(connection, "issues", "merge_prep_attempts", "INTEGER NOT NULL DEFAULT 0");
 }
 function addColumnIfMissing(connection, table, column, definition) {
     const cols = connection.prepare(`PRAGMA table_info(${table})`).all();

package/dist/db.js

@@ -149,6 +149,10 @@ export class PatchRelayDatabase {
                 sets.push("queue_repair_attempts = @queueRepairAttempts");
                 values.queueRepairAttempts = params.queueRepairAttempts;
             }
+            if (params.mergePrepAttempts !== undefined) {
+                sets.push("merge_prep_attempts = @mergePrepAttempts");
+                values.mergePrepAttempts = params.mergePrepAttempts;
+            }
             if (params.pendingMergePrep !== undefined) {
                 sets.push("pending_merge_prep = @pendingMergePrep");
                 values.pendingMergePrep = params.pendingMergePrep ? 1 : 0;
@@ -385,6 +389,7 @@ function mapIssueRow(row) {
         ...(row.pr_check_status !== null && row.pr_check_status !== undefined ? { prCheckStatus: String(row.pr_check_status) } : {}),
         ciRepairAttempts: Number(row.ci_repair_attempts ?? 0),
         queueRepairAttempts: Number(row.queue_repair_attempts ?? 0),
+        mergePrepAttempts: Number(row.merge_prep_attempts ?? 0),
         pendingMergePrep: Boolean(row.pending_merge_prep),
     };
 }

package/dist/http.js

@@ -290,6 +290,17 @@ export async function buildHttpServer(config, service, logger) {
         });
     }
     if (managementRoutesEnabled) {
+        app.post("/api/issues/:issueKey/retry", async (request, reply) => {
+            const issueKey = request.params.issueKey;
+            const result = service.retryIssue(issueKey);
+            if (!result) {
+                return reply.code(404).send({ ok: false, reason: "issue_not_found" });
+            }
+            if ("error" in result) {
+                return reply.code(409).send({ ok: false, reason: result.error });
+            }
+            return reply.send({ ok: true, ...result });
+        });
         app.get("/api/feed", async (request, reply) => {
             const feedQuery = {
                 limit: getPositiveIntegerQueryParam(request, "limit") ?? 50,

package/dist/linear-session-reporting.js

@@ -82,6 +82,12 @@ export function buildRunFailureActivity(runType, reason) {
         body: reason ? `${label} failed.\n\n${reason}` : `${label} failed.`,
     };
 }
+export function buildStopConfirmationActivity() {
+    return {
+        type: "response",
+        body: "PatchRelay has stopped work as requested. Delegate the issue again or provide new instructions to resume.",
+    };
+}
 export function buildGitHubStateActivity(newState, event) {
     switch (newState) {
         case "pr_open": {
@@ -119,6 +125,28 @@ export function buildGitHubStateActivity(newState, event) {
             return undefined;
     }
 }
+export function buildMergePrepActivity(step, detail) {
+    switch (step) {
+        case "auto_merge":
+            return { type: "action", action: "Enabling", parameter: "auto-merge" };
+        case "branch_update":
+            return { type: "action", action: "Updating", parameter: detail ? `branch to latest ${detail}` : "branch to latest base" };
+        case "conflict":
+            return { type: "action", action: "Repairing", parameter: "merge conflict with base branch" };
+        case "blocked":
+            return { type: "error", body: "Branch is up to date but auto-merge could not be enabled — check repository settings." };
+        case "fetch_retry":
+            return { type: "thought", body: "Merge prep: fetch failed, will retry." };
+        case "push_retry":
+            return { type: "thought", body: "Merge prep: push failed, will retry." };
+    }
+}
+export function buildMergePrepEscalationActivity(attempts) {
+    return {
+        type: "error",
+        body: `Merge preparation failed ${attempts} times due to infrastructure issues. PatchRelay needs human help to continue.`,
+    };
+}
 export function summarizeIssueStateForLinear(issue) {
     switch (issue.factoryState) {
         case "awaiting_review":

package/dist/merge-queue.js

@@ -1,4 +1,6 @@
+import { buildMergePrepActivity, buildMergePrepEscalationActivity } from "./linear-session-reporting.js";
 import { execCommand } from "./utils.js";
+const DEFAULT_MERGE_PREP_BUDGET = 3;
 /**
  * Merge queue steward — keeps PatchRelay-managed PR branches up to date
  * with the base branch and enables auto-merge so GitHub merges when CI passes.
@@ -14,12 +16,14 @@ export class MergeQueue {
     enqueueIssue;
     logger;
     feed;
-    constructor(config, db, enqueueIssue, logger, feed) {
+    onLinearActivity;
+    constructor(config, db, enqueueIssue, logger, feed, onLinearActivity) {
         this.config = config;
         this.db = db;
         this.enqueueIssue = enqueueIssue;
         this.logger = logger;
         this.feed = feed;
+        this.onLinearActivity = onLinearActivity;
     }
     /**
      * Prepare the front-of-queue issue for merge:
@@ -43,11 +47,37 @@ export class MergeQueue {
             this.db.upsertIssue({ projectId: issue.projectId, linearIssueId: issue.linearIssueId, pendingMergePrep: false });
             return;
         }
+        // Retry budget — escalate after repeated infrastructure failures
+        const attempts = issue.mergePrepAttempts + 1;
+        this.db.upsertIssue({ projectId: issue.projectId, linearIssueId: issue.linearIssueId, mergePrepAttempts: attempts });
+        if (attempts > DEFAULT_MERGE_PREP_BUDGET) {
+            this.logger.warn({ issueKey: issue.issueKey, attempts }, "Merge prep budget exhausted, escalating");
+            this.db.upsertIssue({
+                projectId: issue.projectId,
+                linearIssueId: issue.linearIssueId,
+                factoryState: "escalated",
+                pendingMergePrep: false,
+            });
+            this.feed?.publish({
+                level: "error",
+                kind: "workflow",
+                issueKey: issue.issueKey,
+                projectId: issue.projectId,
+                stage: "awaiting_queue",
+                status: "escalated",
+                summary: `Merge prep failed ${attempts - 1} times — escalating for human help`,
+            });
+            this.onLinearActivity?.(issue, buildMergePrepEscalationActivity(attempts - 1));
+            return;
+        }
         const repoFullName = project.github?.repoFullName;
         const baseBranch = project.github?.baseBranch ?? "main";
         const gitBin = this.config.runner.gitBin;
         // Enable auto-merge (idempotent)
         const autoMergeOk = repoFullName ? await this.enableAutoMerge(issue, repoFullName) : false;
+        if (autoMergeOk) {
+            this.onLinearActivity?.(issue, buildMergePrepActivity("auto_merge"), { ephemeral: true });
+        }
         // Fetch latest base branch
         const fetchResult = await execCommand(gitBin, ["-C", issue.worktreePath, "fetch", "origin", baseBranch], {
             timeoutMs: 60_000,
@@ -55,6 +85,7 @@ export class MergeQueue {
         if (fetchResult.exitCode !== 0) {
             // Transient failure — leave pendingMergePrep set so the next event retries.
             this.logger.warn({ issueKey: issue.issueKey, stderr: fetchResult.stderr?.slice(0, 300) }, "Merge prep: fetch failed, will retry on next event");
+            this.onLinearActivity?.(issue, buildMergePrepActivity("fetch_retry"), { ephemeral: true });
             return;
         }
         // Merge base branch into the PR branch
@@ -72,6 +103,7 @@ export class MergeQueue {
                 pendingRunType: "queue_repair",
                 pendingRunContextJson: JSON.stringify({ failureReason: "merge_conflict" }),
                 pendingMergePrep: false,
+                mergePrepAttempts: 0,
             });
             this.enqueueIssue(issue.projectId, issue.linearIssueId);
             this.feed?.publish({
@@ -83,12 +115,13 @@ export class MergeQueue {
                 status: "conflict",
                 summary: `Merge conflict with ${baseBranch} — queue repair enqueued`,
             });
+            this.onLinearActivity?.(issue, buildMergePrepActivity("conflict"));
             return;
         }
         // Check if merge was a no-op (already up to date)
         if (mergeResult.stdout?.includes("Already up to date")) {
             this.logger.debug({ issueKey: issue.issueKey }, "Merge prep: branch already up to date");
-            this.db.upsertIssue({ projectId: issue.projectId, linearIssueId: issue.linearIssueId, pendingMergePrep: false });
+            this.db.upsertIssue({ projectId: issue.projectId, linearIssueId: issue.linearIssueId, pendingMergePrep: false, mergePrepAttempts: 0 });
             if (!autoMergeOk) {
                 this.feed?.publish({
                     level: "warn",
@@ -99,6 +132,7 @@ export class MergeQueue {
                     status: "blocked",
                     summary: "Branch up to date but auto-merge not enabled — check gh auth and repo settings",
                 });
+                this.onLinearActivity?.(issue, buildMergePrepActivity("blocked"));
             }
             return;
         }
@@ -109,10 +143,11 @@ export class MergeQueue {
         if (pushResult.exitCode !== 0) {
             // Push failed — leave pendingMergePrep set so the next event retries.
             this.logger.warn({ issueKey: issue.issueKey, stderr: pushResult.stderr?.slice(0, 300) }, "Merge prep: push failed, will retry on next event");
+            this.onLinearActivity?.(issue, buildMergePrepActivity("push_retry"), { ephemeral: true });
             return;
         }
         this.logger.info({ issueKey: issue.issueKey, baseBranch }, "Merge prep: branch updated and pushed");
-        this.db.upsertIssue({ projectId: issue.projectId, linearIssueId: issue.linearIssueId, pendingMergePrep: false });
+        this.db.upsertIssue({ projectId: issue.projectId, linearIssueId: issue.linearIssueId, pendingMergePrep: false, mergePrepAttempts: 0 });
         this.feed?.publish({
             level: "info",
             kind: "workflow",
@@ -122,6 +157,7 @@ export class MergeQueue {
             status: "prepared",
             summary: `Branch updated to latest ${baseBranch} — CI will run`,
         });
+        this.onLinearActivity?.(issue, buildMergePrepActivity("branch_update", baseBranch), { ephemeral: true });
     }
     /**
      * Seed the merge queue on startup: for each project, ensure the front-of-queue

package/dist/run-orchestrator.js

@@ -304,7 +304,7 @@ export class RunOrchestrator {
                 postRunState = "done";
             }
             else {
-                postRunState = "pr_open";
+                postRunState = "awaiting_review";
             }
         }
         this.db.transaction(() => {

package/dist/service.js

@@ -35,7 +35,27 @@ export class PatchRelayService {
             throw new Error("Service runtime enqueueIssue is not initialized");
         };
         this.orchestrator = new RunOrchestrator(config, db, codex, this.linearProvider, (projectId, issueId) => enqueueIssue(projectId, issueId), logger, this.feed);
-        this.mergeQueue = new MergeQueue(config, db, (projectId, issueId) => enqueueIssue(projectId, issueId), logger, this.feed);
+        this.mergeQueue = new MergeQueue(config, db, (projectId, issueId) => enqueueIssue(projectId, issueId), logger, this.feed, (issue, content, options) => {
+            if (!issue.agentSessionId)
+                return;
+            void (async () => {
+                try {
+                    const linear = await this.linearProvider.forProject(issue.projectId);
+                    if (!linear)
+                        return;
+                    const allowEphemeral = content.type === "thought" || content.type === "action";
+                    await linear.createAgentActivity({
+                        agentSessionId: issue.agentSessionId,
+                        content,
+                        ...(options?.ephemeral && allowEphemeral ? { ephemeral: true } : {}),
+                    });
+                }
+                catch (error) {
+                    const msg = error instanceof Error ? error.message : String(error);
+                    logger.warn({ issueKey: issue.issueKey, type: content.type, error: msg }, "Failed to emit merge-prep Linear activity");
+                }
+            })();
+        });
         this.webhookHandler = new WebhookHandler(config, db, this.linearProvider, codex, (projectId, issueId) => enqueueIssue(projectId, issueId), logger, this.feed);
         this.githubWebhookHandler = new GitHubWebhookHandler(config, db, this.linearProvider, (projectId, issueId) => enqueueIssue(projectId, issueId), this.mergeQueue, logger, this.feed);
         const runtime = new ServiceRuntime(codex, logger, this.orchestrator, { listIssuesReadyForExecution: () => db.listIssuesReadyForExecution() }, this.webhookHandler, {
@@ -198,6 +218,22 @@ export class PatchRelayService {
         this.codex.on("notification", handler);
         return () => { this.codex.off("notification", handler); };
     }
+    retryIssue(issueKey) {
+        const issue = this.db.getIssueByKey(issueKey);
+        if (!issue)
+            return undefined;
+        if (issue.activeRunId)
+            return { error: "Issue already has an active run" };
+        const runType = "implementation";
+        this.db.upsertIssue({
+            projectId: issue.projectId,
+            linearIssueId: issue.linearIssueId,
+            pendingRunType: runType,
+            factoryState: "delegated",
+        });
+        this.runtime.enqueueIssue(issue.projectId, issue.linearIssueId);
+        return { issueKey, runType };
+    }
     listOperatorFeed(options) {
         return this.feed.list(options);
     }

package/dist/webhook-handler.js

@@ -1,6 +1,6 @@
 import { buildAgentSessionPlanForIssue, } from "./agent-session-plan.js";
 import { buildAgentSessionExternalUrls } from "./agent-session-presentation.js";
-import { buildAlreadyRunningThought, buildDelegationThought, buildPromptDeliveredThought, } from "./linear-session-reporting.js";
+import { buildAlreadyRunningThought, buildDelegationThought, buildPromptDeliveredThought, buildStopConfirmationActivity, } from "./linear-session-reporting.js";
 import { resolveProject, triggerEventAllowed, trustedActorAllowed } from "./project-resolution.js";
 import { normalizeWebhook } from "./webhooks.js";
 import { InstallationWebhookHandler } from "./webhook-installation-handler.js";
@@ -210,6 +210,11 @@ export class WebhookHandler {
             });
             return;
         }
+        // Stop signal — halt active work and confirm disengagement
+        if (normalized.triggerEvent === "agentSignal" && normalized.agentSession.signal === "stop") {
+            await this.handleStopSignal(normalized, project, trackedIssue, existingIssue, activeRun, linear);
+            return;
+        }
         if (normalized.triggerEvent !== "agentPrompted")
             return;
         if (!triggerEventAllowed(project, normalized.triggerEvent))
@@ -251,6 +256,43 @@ export class WebhookHandler {
             await this.publishAgentActivity(linear, normalized.agentSession.id, buildDelegationThought(desiredStage, "prompt"), { ephemeral: true });
         }
     }
+    // ─── Stop signal handling ────────────────────────────────────────
+    async handleStopSignal(normalized, project, trackedIssue, existingIssue, activeRun, linear) {
+        const issueId = normalized.issue.id;
+        const sessionId = normalized.agentSession.id;
+        // Best-effort halt: steer the active Codex turn with a stop instruction
+        if (activeRun?.threadId && activeRun.turnId) {
+            try {
+                await this.codex.steerTurn({
+                    threadId: activeRun.threadId,
+                    turnId: activeRun.turnId,
+                    input: "STOP: The user has requested you stop working immediately. Do not make further changes. Wrap up and exit.",
+                });
+            }
+            catch (error) {
+                this.logger.warn({ issueKey: trackedIssue?.issueKey, error: error instanceof Error ? error.message : String(error) }, "Failed to steer Codex turn for stop signal");
+            }
+            this.db.finishRun(activeRun.id, { status: "released", threadId: activeRun.threadId, turnId: activeRun.turnId });
+        }
+        this.db.upsertIssue({
+            projectId: project.id,
+            linearIssueId: issueId,
+            activeRunId: null,
+            factoryState: "awaiting_input",
+            agentSessionId: sessionId,
+        });
+        this.feed?.publish({
+            level: "info",
+            kind: "agent",
+            projectId: project.id,
+            issueKey: trackedIssue?.issueKey,
+            status: "stopped",
+            summary: "Stop signal received — work halted",
+        });
+        const updatedIssue = this.db.getIssue(project.id, issueId);
+        await this.publishAgentActivity(linear, sessionId, buildStopConfirmationActivity());
+        await this.syncAgentSession(linear, sessionId, updatedIssue ?? trackedIssue);
+    }
     // ─── Comment handling (inlined) ───────────────────────────────────
     async handleComment(normalized, project, trackedIssue) {
         if ((normalized.triggerEvent !== "commentCreated" && normalized.triggerEvent !== "commentUpdated") ||

package/dist/webhooks.js

@@ -46,6 +46,18 @@ function deriveTriggerEvent(payload) {
         ["resource", "agentSession"],
     ])) || Boolean(getString(data, "agentSessionId"));
     if (payload.type === "AgentSessionEvent" || payload.type === "AgentSession" || hasAgentSession) {
+        // Detect signal-bearing payloads (e.g. stop signal from Linear)
+        const agentActivityForSignal = getFirstNestedRecord(data, [
+            ["agentActivity"],
+            ["agentSession", "agentActivity"],
+            ["session", "agentActivity"],
+            ["agentSessionEvent", "agentActivity"],
+            ["payload", "agentActivity"],
+            ["resource", "agentActivity"],
+        ]);
+        if (agentActivityForSignal && getString(agentActivityForSignal, "signal")) {
+            return "agentSignal";
+        }
         if (payload.action === "created" || payload.action === "create") {
             return "agentSessionCreated";
         }
@@ -310,11 +322,15 @@ function extractAgentSessionMetadata(payload) {
         getString(commentRecord ?? {}, "body") ??
         getString(data, "body");
     const issueCommentId = getString(commentRecord ?? {}, "id") ?? getString(data, "issueCommentId");
+    const signal = getString(agentActivity ?? {}, "signal");
+    const signalMetadata = asRecord((agentActivity ?? {}).signalMetadata);
     return {
         id,
         ...(promptContext ? { promptContext } : {}),
         ...(promptBody ? { promptBody } : {}),
         ...(issueCommentId ? { issueCommentId } : {}),
+        ...(signal ? { signal } : {}),
+        ...(signalMetadata ? { signalMetadata } : {}),
     };
 }
 function extractInstallationMetadata(payload) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchrelay",
-  "version": "0.14.2",
+  "version": "0.16.0",
   "license": "MIT",
   "type": "module",
   "repository": {