patchrelay 0.7.5 → 0.7.7

package/README.md

@@ -11,7 +11,7 @@ PatchRelay is the system around the model:
 - issue-to-repo routing
 - issue worktree and branch lifecycle
 - stage orchestration and thread continuity
-- comment forwarding into active runs
+- native Linear agent input forwarding into active runs
 - read-only inspection and stage reporting
 
 If you want Codex to work inside your real repos with your real tools, secrets, SSH access, and deployment surface, PatchRelay is the harness that makes that loop reliable.
@@ -22,7 +22,7 @@ If you want Codex to work inside your real repos with your real tools, secrets,
 - Use your existing machine, repos, secrets, SSH config, shell tools, and deployment access.
 - Keep deterministic workflow logic outside the model: routing, staging, worktree ownership, and reporting.
 - Choose the Codex approval and sandbox settings that match your risk tolerance.
-- Let Linear drive the loop through delegation, workflow stages, and comments.
+- Let Linear drive the loop through delegation, mentions, and workflow stages.
 - Drop into the exact issue worktree and resume control manually when needed.
 
 ## What PatchRelay Owns
@@ -34,7 +34,7 @@ PatchRelay does the deterministic harness work that you do not want to re-implem
 - creates and reuses one durable worktree and branch per issue lifecycle
 - starts or forks Codex threads for the workflows you bind to Linear states
 - persists enough state to correlate the Linear issue, local workspace, stage run, and Codex thread
-- reports progress back to Linear and forwards follow-up comments into active runs
+- reports progress back to Linear and forwards follow-up agent input into active runs
 - exposes CLI and optional read-only inspection surfaces so operators can understand what happened
 
 ## System Layers
@@ -77,7 +77,7 @@ For the exact OAuth app settings and webhook categories, use the Linear onboardi
 2. PatchRelay verifies the webhook and routes the issue to the right local project.
 3. Delegated issues create or reuse the issue worktree and launch the matching workflow through `codex app-server`.
 4. PatchRelay persists thread ids, run state, and observations so the work stays inspectable and resumable.
-5. Mentions stay conversational, while delegated sessions and issue comments can steer the active run. An operator can take over from the exact same worktree when needed.
+5. Mentions stay conversational, while delegated sessions and native agent prompts can steer the active run. An operator can take over from the exact same worktree when needed.
 
 ## Restart And Reconciliation
 
@@ -221,7 +221,7 @@ Important:
 1. Delegate a Linear issue to the PatchRelay app.
 2. PatchRelay reads the current Linear state like `Start`, `Ready for QA`, or `Deploy` to choose the matching workflow.
 3. Linear sends the delegation and agent-session webhooks to PatchRelay, which creates or reuses the issue worktree and launches the matching workflow.
-4. Follow up in the issue comments to steer the active run or wake it with fresh input while it remains delegated.
+4. Follow up in the Linear agent session to steer the active run or wake it with fresh input while it remains delegated.
 5. Watch progress from the terminal or open the same worktree and take over manually.
 
 Useful commands:

package/dist/agent-session-plan.js

@@ -0,0 +1,34 @@
+function formatStageLabel(stage) {
+    return stage.replace(/[-_]+/g, " ");
+}
+function titleCase(value) {
+    return value
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((word) => word[0].toUpperCase() + word.slice(1))
+        .join(" ");
+}
+function buildPlan(stage, statuses) {
+    const stageLabel = titleCase(formatStageLabel(stage));
+    return [
+        { content: "Prepare workspace", status: statuses[0] },
+        { content: `Run ${stageLabel} workflow`, status: statuses[1] },
+        { content: "Review next Linear step", status: statuses[2] },
+    ];
+}
+export function buildPreparingSessionPlan(stage) {
+    return buildPlan(stage, ["inProgress", "pending", "pending"]);
+}
+export function buildRunningSessionPlan(stage) {
+    return buildPlan(stage, ["completed", "inProgress", "pending"]);
+}
+export function buildCompletedSessionPlan(stage) {
+    return buildPlan(stage, ["completed", "completed", "completed"]);
+}
+export function buildAwaitingHandoffSessionPlan(stage) {
+    return buildPlan(stage, ["completed", "completed", "inProgress"]);
+}
+export function buildFailedSessionPlan(stage, stageRun) {
+    const workflowStepStatus = stageRun?.threadId || stageRun?.turnId ? "completed" : "inProgress";
+    return buildPlan(stage, ["completed", workflowStepStatus, "pending"]);
+}

package/dist/agent-session-presentation.js

@@ -0,0 +1,22 @@
+import { buildSessionStatusUrl, createSessionStatusToken, deriveSessionStatusSigningSecret, } from "./public-agent-session-status.js";
+const SESSION_STATUS_TTL_SECONDS = 60 * 60 * 24 * 7;
+export function buildAgentSessionExternalUrls(config, issueKey) {
+    if (!issueKey || !config.server.publicBaseUrl) {
+        return undefined;
+    }
+    const token = createSessionStatusToken({
+        issueKey,
+        secret: deriveSessionStatusSigningSecret(config.linear.tokenEncryptionKey),
+        ttlSeconds: SESSION_STATUS_TTL_SECONDS,
+    });
+    return [
+        {
+            label: "PatchRelay status",
+            url: buildSessionStatusUrl({
+                publicBaseUrl: config.server.publicBaseUrl,
+                issueKey,
+                token: token.token,
+            }),
+        },
+    ];
+}

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "service": "patchrelay",
-  "version": "0.7.5",
-  "commit": "884a7bfd9ef3",
-  "builtAt": "2026-03-14T22:19:40.569Z"
+  "version": "0.7.7",
+  "commit": "b39ec3de1f37",
+  "builtAt": "2026-03-17T09:39:30.228Z"
 }

package/dist/config.js

@@ -101,7 +101,7 @@ const configSchema = z.object({
 });
 function defaultTriggerEvents(actor) {
     if (actor === "app") {
-        return ["issueCreated", "agentSessionCreated", "agentPrompted", "statusChanged"];
+        return ["agentSessionCreated", "agentPrompted"];
     }
     return ["statusChanged"];
 }

package/dist/http.js

@@ -177,6 +177,36 @@ export async function buildHttpServer(config, service, logger) {
         });
         return reply.code(result.status).send(result.body);
     });
+    app.get("/agent/session/:issueKey", async (request, reply) => {
+        const issueKey = request.params.issueKey;
+        const token = getQueryParam(request, "token");
+        if (!token) {
+            return reply
+                .code(401)
+                .type("text/html; charset=utf-8")
+                .send(renderAgentSessionStatusErrorPage("Missing access token."));
+        }
+        const status = await service.getPublicAgentSessionStatus({ issueKey, token });
+        if (status.status === "invalid_token") {
+            return reply
+                .code(401)
+                .type("text/html; charset=utf-8")
+                .send(renderAgentSessionStatusErrorPage("The access token is invalid or expired."));
+        }
+        if (status.status === "issue_not_found") {
+            return reply
+                .code(404)
+                .type("text/html; charset=utf-8")
+                .send(renderAgentSessionStatusErrorPage("Issue status is not available."));
+        }
+        return reply
+            .type("text/html; charset=utf-8")
+            .send(renderAgentSessionStatusPage({
+            issueKey,
+            expiresAt: status.expiresAt,
+            sessionStatus: status.sessionStatus,
+        }));
+    });
     if (config.operatorApi.enabled) {
         app.addHook("onRequest", async (request, reply) => {
             if (!request.url.startsWith("/api/")) {
@@ -218,6 +248,19 @@ export async function buildHttpServer(config, service, logger) {
             }
             return reply.send({ ok: true, ...result });
         });
+        app.get("/api/issues/:issueKey/session-url", async (request, reply) => {
+            const issueKey = request.params.issueKey;
+            const ttlSeconds = getPositiveIntegerQueryParam(request, "ttlSeconds");
+            const issue = await service.getIssueOverview(issueKey);
+            if (!issue) {
+                return reply.code(404).send({ ok: false, reason: "issue_not_found" });
+            }
+            const link = service.createPublicAgentSessionStatusLink(issueKey, ttlSeconds ? { ttlSeconds } : undefined);
+            if (!link) {
+                return reply.code(503).send({ ok: false, reason: "public_base_url_not_configured" });
+            }
+            return reply.send({ ok: true, ...link });
+        });
     }
     if (managementRoutesEnabled) {
         app.get("/api/feed", async (request, reply) => {
@@ -371,3 +414,140 @@ function renderOAuthResult(message) {
   </body>
 </html>`;
 }
+function renderAgentSessionStatusErrorPage(message) {
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>PatchRelay Agent Status</title>
+    <style>
+      body { font-family: Georgia, "Times New Roman", serif; background: #f7f4ef; color: #1f1d1a; margin: 0; padding: 32px; }
+      main { max-width: 720px; margin: 10vh auto; background: rgba(255,255,255,0.86); border: 1px solid rgba(31,29,26,0.12); border-radius: 20px; padding: 32px; box-shadow: 0 28px 80px rgba(49,42,30,0.10); }
+      p { font-size: 18px; line-height: 1.6; color: #4d483f; }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>PatchRelay Agent Session</h1>
+      <p>${escapeHtml(message)}</p>
+    </main>
+  </body>
+</html>`;
+}
+function renderAgentSessionStatusPage(params) {
+    const issueTitle = params.sessionStatus.issue.title ?? params.sessionStatus.issue.issueKey ?? params.issueKey;
+    const issueUrl = params.sessionStatus.issue.issueUrl;
+    const activeStage = formatStageChip(params.sessionStatus.activeStageRun);
+    const latestStage = formatStageChip(params.sessionStatus.latestStageRun);
+    const threadInfo = formatThread(params.sessionStatus.liveThread);
+    const stagesRows = params.sessionStatus.stages.slice(-8).map((entry) => formatStageRow(entry.stageRun)).join("");
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>PatchRelay Agent Session ${escapeHtml(params.issueKey)}</title>
+    <style>
+      :root {
+        color-scheme: light;
+        --bg: #f5f1e8;
+        --panel: rgba(255,255,255,0.84);
+        --ink: #1f1d1a;
+        --muted: #5b554b;
+        --accent: #1f6d57;
+        --line: rgba(31,29,26,0.15);
+      }
+      * { box-sizing: border-box; }
+      body {
+        margin: 0;
+        min-height: 100vh;
+        font-family: Georgia, "Times New Roman", serif;
+        color: var(--ink);
+        background:
+          radial-gradient(circle at top left, rgba(184, 139, 68, 0.22), transparent 36%),
+          radial-gradient(circle at bottom right, rgba(31, 109, 87, 0.16), transparent 30%),
+          linear-gradient(150deg, #eee3cf 0%, var(--bg) 52%, #f8f6f1 100%);
+        padding: 24px;
+      }
+      main {
+        width: min(920px, 100%);
+        margin: 0 auto;
+        background: var(--panel);
+        border: 1px solid var(--line);
+        border-radius: 22px;
+        padding: 32px;
+        box-shadow: 0 30px 86px rgba(49,42,30,0.12);
+      }
+      h1 { margin: 0; font-size: clamp(34px, 7vw, 52px); line-height: 1.05; }
+      p { color: var(--muted); font-size: 17px; line-height: 1.6; margin: 12px 0 0; }
+      a { color: var(--accent); text-decoration: none; }
+      a:hover { text-decoration: underline; }
+      .chips { display: flex; flex-wrap: wrap; gap: 10px; margin: 20px 0 6px; }
+      .chip { border: 1px solid var(--line); border-radius: 999px; padding: 9px 14px; background: rgba(255,255,255,0.74); font-size: 14px; }
+      .section { margin-top: 24px; padding-top: 18px; border-top: 1px solid var(--line); }
+      .section h2 { margin: 0; font-size: 22px; }
+      table { width: 100%; border-collapse: collapse; margin-top: 14px; }
+      th, td { text-align: left; border-bottom: 1px solid var(--line); padding: 10px 8px; vertical-align: top; }
+      th { font-size: 12px; text-transform: uppercase; letter-spacing: 0.08em; color: #5f594e; }
+      td { font-size: 15px; color: #2a2622; }
+      code { font-family: "SFMono-Regular", "Cascadia Code", "Fira Code", monospace; font-size: 0.95em; }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>${escapeHtml(issueTitle)}</h1>
+      <p>PatchRelay read-only agent session status for <code>${escapeHtml(params.issueKey)}</code>.</p>
+      ${issueUrl ? `<p><a href="${escapeHtml(issueUrl)}" target="_blank" rel="noopener noreferrer">Open issue in Linear</a></p>` : ""}
+      <div class="chips">
+        <span class="chip"><strong>Active:</strong> ${activeStage}</span>
+        <span class="chip"><strong>Latest:</strong> ${latestStage}</span>
+        <span class="chip"><strong>Thread:</strong> ${threadInfo}</span>
+      </div>
+      <div class="section">
+        <h2>Recent Stages</h2>
+        <table>
+          <thead>
+            <tr>
+              <th>Stage</th>
+              <th>Status</th>
+              <th>Started</th>
+              <th>Ended</th>
+            </tr>
+          </thead>
+          <tbody>
+            ${stagesRows || '<tr><td colspan="4">No completed stage runs yet.</td></tr>'}
+          </tbody>
+        </table>
+      </div>
+      <p>Snapshot generated at <code>${escapeHtml(params.sessionStatus.generatedAt)}</code>. Link valid until <code>${escapeHtml(params.expiresAt)}</code>.</p>
+    </main>
+  </body>
+</html>`;
+}
+function formatStageChip(stageRun) {
+    if (!stageRun) {
+        return "none";
+    }
+    const stage = stageRun.stage ?? "unknown";
+    const status = stageRun.status ?? "unknown";
+    return `<code>${escapeHtml(stage)}</code> (${escapeHtml(status)})`;
+}
+function formatThread(liveThread) {
+    if (!liveThread) {
+        return "idle";
+    }
+    const threadId = liveThread.threadId ?? "unknown";
+    const status = liveThread.threadStatus ?? "unknown";
+    return `<code>${escapeHtml(threadId)}</code> (${escapeHtml(status)})`;
+}
+function formatStageRow(stageRun) {
+    if (!stageRun) {
+        return '<tr><td colspan="4">Unknown stage record</td></tr>';
+    }
+    const stage = stageRun.stage ?? "unknown";
+    const status = stageRun.status ?? "unknown";
+    const startedAt = stageRun.startedAt ?? "-";
+    const endedAt = stageRun.endedAt ?? "-";
+    return `<tr><td><code>${escapeHtml(stage)}</code></td><td>${escapeHtml(status)}</td><td><code>${escapeHtml(startedAt)}</code></td><td><code>${escapeHtml(endedAt)}</code></td></tr>`;
+}

package/dist/issue-query-service.js

@@ -65,4 +65,19 @@ export class IssueQueryService {
     async getActiveStageStatus(issueKey) {
         return await this.stageFinalizer.getActiveStageStatus(issueKey);
     }
+    async getPublicAgentSessionStatus(issueKey) {
+        const overview = await this.getIssueOverview(issueKey);
+        if (!overview) {
+            return undefined;
+        }
+        const report = await this.getIssueReport(issueKey);
+        return {
+            issue: overview.issue,
+            ...(overview.activeStageRun ? { activeStageRun: overview.activeStageRun } : {}),
+            ...(overview.latestStageRun ? { latestStageRun: overview.latestStageRun } : {}),
+            ...(overview.liveThread ? { liveThread: overview.liveThread } : {}),
+            stages: report?.stages ?? [],
+            generatedAt: new Date().toISOString(),
+        };
+    }
 }

package/dist/linear-client.js

@@ -156,6 +156,32 @@ export class LinearGraphqlClient {
         }
         return response.agentActivityCreate.agentActivity;
     }
+    async updateAgentSession(params) {
+        const input = {};
+        if ("externalUrls" in params) {
+            input.externalUrls = params.externalUrls;
+        }
+        if ("plan" in params) {
+            input.plan = params.plan;
+        }
+        const response = await this.request(`
+      mutation PatchRelayUpdateAgentSession($id: String!, $input: AgentSessionUpdateInput!) {
+        agentSessionUpdate(id: $id, input: $input) {
+          success
+          agentSession {
+            id
+          }
+        }
+      }
+      `, {
+            id: params.agentSessionId,
+            input,
+        });
+        if (!response.agentSessionUpdate.success || !response.agentSessionUpdate.agentSession) {
+            throw new Error(`Linear rejected agent session update for session ${params.agentSessionId}`);
+        }
+        return response.agentSessionUpdate.agentSession;
+    }
     async updateIssueLabels(params) {
         const issue = await this.getIssue(params.issueId);
         const addIds = this.resolveLabelIds(issue, params.addNames ?? []);

package/dist/project-resolution.js

@@ -7,12 +7,6 @@ export function resolveProject(config, issue) {
     return undefined;
 }
 export function triggerEventAllowed(project, triggerEvent) {
-    if (project.triggerEvents.includes(triggerEvent)) {
-        return true;
-    }
-    if (triggerEvent === "agentSessionCreated") {
-        return project.triggerEvents.includes("delegateChanged") || project.triggerEvents.includes("statusChanged");
-    }
     return project.triggerEvents.includes(triggerEvent);
 }
 function normalizeTrustValue(value) {

package/dist/public-agent-session-status.js

@@ -0,0 +1,77 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+const TOKEN_VERSION = 1;
+const DEFAULT_TTL_SECONDS = 60 * 60 * 24;
+const PURPOSE = "patchrelay-agent-session-status";
+export function createSessionStatusToken(params) {
+    const nowSeconds = Math.floor((params.nowMs ?? Date.now()) / 1000);
+    const ttlSeconds = Number.isFinite(params.ttlSeconds) ? Math.max(60, Math.floor(params.ttlSeconds ?? DEFAULT_TTL_SECONDS)) : DEFAULT_TTL_SECONDS;
+    const payload = {
+        v: TOKEN_VERSION,
+        i: params.issueKey,
+        exp: nowSeconds + ttlSeconds,
+    };
+    const payloadEncoded = encodeBase64Url(Buffer.from(JSON.stringify(payload), "utf8"));
+    const signature = signPayload(payloadEncoded, params.secret);
+    return {
+        token: `${payloadEncoded}.${signature}`,
+        issueKey: payload.i,
+        expiresAt: new Date(payload.exp * 1000).toISOString(),
+    };
+}
+export function verifySessionStatusToken(token, secret, nowMs) {
+    const [payloadEncoded, signatureEncoded] = token.split(".", 2);
+    if (!payloadEncoded || !signatureEncoded) {
+        return undefined;
+    }
+    const expectedSignature = signPayload(payloadEncoded, secret);
+    if (!timingSafeEqualUtf8(signatureEncoded, expectedSignature)) {
+        return undefined;
+    }
+    const payload = parsePayload(payloadEncoded);
+    if (!payload || payload.v !== TOKEN_VERSION || typeof payload.i !== "string" || typeof payload.exp !== "number") {
+        return undefined;
+    }
+    const nowSeconds = Math.floor((nowMs ?? Date.now()) / 1000);
+    if (payload.exp < nowSeconds) {
+        return undefined;
+    }
+    return {
+        issueKey: payload.i,
+        expiresAt: new Date(payload.exp * 1000).toISOString(),
+    };
+}
+export function buildSessionStatusUrl(params) {
+    const url = new URL(`/agent/session/${encodeURIComponent(params.issueKey)}`, params.publicBaseUrl);
+    url.searchParams.set("token", params.token);
+    return url.toString();
+}
+export function deriveSessionStatusSigningSecret(tokenEncryptionKey) {
+    return `${PURPOSE}:${tokenEncryptionKey}`;
+}
+function signPayload(payloadEncoded, secret) {
+    const digest = createHmac("sha256", secret).update(payloadEncoded).digest();
+    return encodeBase64Url(digest);
+}
+function parsePayload(payloadEncoded) {
+    try {
+        const decoded = decodeBase64Url(payloadEncoded).toString("utf8");
+        return JSON.parse(decoded);
+    }
+    catch {
+        return undefined;
+    }
+}
+function encodeBase64Url(value) {
+    return value.toString("base64url");
+}
+function decodeBase64Url(value) {
+    return Buffer.from(value, "base64url");
+}
+function timingSafeEqualUtf8(left, right) {
+    const leftBuffer = Buffer.from(left, "utf8");
+    const rightBuffer = Buffer.from(right, "utf8");
+    if (leftBuffer.length !== rightBuffer.length) {
+        return false;
+    }
+    return timingSafeEqual(leftBuffer, rightBuffer);
+}

package/dist/service-queue.js

@@ -10,12 +10,17 @@ export class SerialWorkQueue {
         this.logger = logger;
         this.getKey = getKey;
     }
-    enqueue(item) {
+    enqueue(item, options) {
         const key = this.getKey?.(item);
         if (key && this.queuedKeys.has(key)) {
             return;
         }
-        this.items.push(item);
+        if (options?.priority) {
+            this.items.unshift(item);
+        }
+        else {
+            this.items.push(item);
+        }
         if (key) {
             this.queuedKeys.add(key);
         }

package/dist/service-runtime.js

@@ -80,8 +80,8 @@ export class ServiceRuntime {
         this.ready = false;
         void this.codex.stop();
     }
-    enqueueWebhookEvent(eventId) {
-        this.webhookQueue.enqueue(eventId);
+    enqueueWebhookEvent(eventId, options) {
+        this.webhookQueue.enqueue(eventId, options);
     }
     enqueueIssue(projectId, issueId) {
         this.issueQueue.enqueue({ projectId, issueId });

package/dist/service-stage-runner.js

@@ -133,8 +133,10 @@ export class ServiceStageRunner {
             failureMessage: "Failed to deliver queued Linear comment during stage startup",
             ...(claim.issue.issueKey ? { issueKey: claim.issue.issueKey } : {}),
         });
-        await this.lifecyclePublisher.refreshRunningStatusComment(item.projectId, item.issueId, claim.stageRun.id, issue.issueKey);
-        await this.lifecyclePublisher.publishStageStarted(claim.issue, claim.stageRun.stage);
+        const deliveredToSession = await this.lifecyclePublisher.publishStageStarted(claim.issue, claim.stageRun.stage);
+        if (!deliveredToSession) {
+            await this.lifecyclePublisher.refreshRunningStatusComment(item.projectId, item.issueId, claim.stageRun.id, issue.issueKey);
+        }
         this.logger.info({
             issueKey: issue.issueKey,
             stage: claim.stageRun.stage,

package/dist/service-webhook-processor.js

@@ -24,7 +24,7 @@ export class ServiceWebhookProcessor {
         this.logger = logger;
         this.feed = feed;
         const turnInputDispatcher = new StageTurnInputDispatcher(stores, codex, logger);
-        const agentActivity = new StageAgentActivityPublisher(linearProvider, logger);
+        const agentActivity = new StageAgentActivityPublisher(config, linearProvider, logger);
         this.desiredStageRecorder = new WebhookDesiredStageRecorder(stores);
         this.agentSessionHandler = new AgentSessionWebhookHandler(stores, turnInputDispatcher, agentActivity, feed);
         this.commentHandler = new CommentWebhookHandler(stores, turnInputDispatcher, feed);

package/dist/service.js

@@ -1,6 +1,7 @@
 import { IssueQueryService } from "./issue-query-service.js";
 import { LinearOAuthService } from "./linear-oauth-service.js";
 import { OperatorEventFeed } from "./operator-feed.js";
+import { buildSessionStatusUrl, createSessionStatusToken, deriveSessionStatusSigningSecret, verifySessionStatusToken, } from "./public-agent-session-status.js";
 import { ServiceRuntime } from "./service-runtime.js";
 import { ServiceStageFinalizer } from "./service-stage-finalizer.js";
 import { ServiceStageRunner } from "./service-stage-runner.js";
@@ -111,7 +112,9 @@ export class PatchRelayService {
             rawBody: params.rawBody,
         });
         if (result.accepted) {
-            this.runtime.enqueueWebhookEvent(result.accepted.id);
+            this.runtime.enqueueWebhookEvent(result.accepted.id, {
+                priority: result.accepted.normalized.triggerEvent === "agentSessionCreated",
+            });
         }
         return {
             status: result.status,
@@ -136,6 +139,44 @@ export class PatchRelayService {
     async getActiveStageStatus(issueKey) {
         return await this.queryService.getActiveStageStatus(issueKey);
     }
+    createPublicAgentSessionStatusLink(issueKey, options) {
+        if (!this.config.server.publicBaseUrl) {
+            return undefined;
+        }
+        const signingSecret = deriveSessionStatusSigningSecret(this.config.linear.tokenEncryptionKey);
+        const token = createSessionStatusToken({
+            issueKey,
+            secret: signingSecret,
+            ...(options?.nowMs !== undefined ? { nowMs: options.nowMs } : {}),
+            ...(options?.ttlSeconds !== undefined ? { ttlSeconds: options.ttlSeconds } : {}),
+        });
+        return {
+            url: buildSessionStatusUrl({
+                publicBaseUrl: this.config.server.publicBaseUrl,
+                issueKey,
+                token: token.token,
+            }),
+            issueKey: token.issueKey,
+            expiresAt: token.expiresAt,
+        };
+    }
+    async getPublicAgentSessionStatus(params) {
+        const signingSecret = deriveSessionStatusSigningSecret(this.config.linear.tokenEncryptionKey);
+        const parsed = verifySessionStatusToken(params.token, signingSecret, params.nowMs);
+        if (!parsed || parsed.issueKey.trim().toLowerCase() !== params.issueKey.trim().toLowerCase()) {
+            return { status: "invalid_token" };
+        }
+        const sessionStatus = await this.queryService.getPublicAgentSessionStatus(params.issueKey);
+        if (!sessionStatus) {
+            return { status: "issue_not_found" };
+        }
+        return {
+            status: "ok",
+            issueKey: params.issueKey,
+            expiresAt: parsed.expiresAt,
+            sessionStatus,
+        };
+    }
 }
 function toLinearClientProvider(linear) {
     if (linear && typeof linear.forProject === "function") {

package/dist/stage-agent-activity-publisher.js

@@ -1,7 +1,10 @@
+import { buildAgentSessionExternalUrls } from "./agent-session-presentation.js";
 export class StageAgentActivityPublisher {
+    config;
     linearProvider;
     logger;
-    constructor(linearProvider, logger) {
+    constructor(config, linearProvider, logger) {
+        this.config = config;
         this.linearProvider = linearProvider;
         this.logger = logger;
     }
@@ -30,4 +33,27 @@ export class StageAgentActivityPublisher {
         }
         await this.publishForSession(issue.projectId, issue.activeAgentSessionId, content);
     }
+    async updateSession(params) {
+        const linear = await this.linearProvider.forProject(params.projectId);
+        if (!linear?.updateAgentSession) {
+            return;
+        }
+        const externalUrls = buildAgentSessionExternalUrls(this.config, params.issueKey);
+        if (!externalUrls && !params.plan) {
+            return;
+        }
+        try {
+            await linear.updateAgentSession({
+                agentSessionId: params.agentSessionId,
+                ...(externalUrls ? { externalUrls } : {}),
+                ...(params.plan ? { plan: params.plan } : {}),
+            });
+        }
+        catch (error) {
+            this.logger.warn({
+                agentSessionId: params.agentSessionId,
+                error: error instanceof Error ? error.message : String(error),
+            }, "Failed to update Linear agent session");
+        }
+    }
 }

package/dist/stage-failure.js

@@ -1,3 +1,4 @@
+import { buildFailedSessionPlan } from "./agent-session-plan.js";
 import { buildStageFailedComment, resolveActiveLinearState, resolveFallbackLinearState, resolveWorkflowLabelCleanup, } from "./linear-workflow.js";
 function normalizeStateName(value) {
     const trimmed = value?.trim();
@@ -48,31 +49,44 @@ export async function syncFailedStageToLinear(params) {
             lifecycleStatus: "failed",
         });
     }
-    const result = await linear
-        .upsertIssueComment({
-        issueId: params.stageRun.linearIssueId,
-        ...(params.issue.statusCommentId ? { commentId: params.issue.statusCommentId } : {}),
-        body: buildStageFailedComment({
-            issue: params.issue,
-            stageRun: params.stageRun,
-            message: params.message,
-            ...(fallbackState ? { fallbackState } : {}),
-            ...(params.mode ? { mode: params.mode } : {}),
-        }),
-    })
-        .catch(() => undefined);
-    if (result) {
-        params.stores.workflowCoordinator.setIssueStatusComment(params.stageRun.projectId, params.stageRun.linearIssueId, result.id);
-    }
+    let deliveredToSession = false;
     if (params.issue.activeAgentSessionId) {
-        await linear
-            .createAgentActivity({
-            agentSessionId: params.issue.activeAgentSessionId,
-            content: {
-                type: "error",
-                body: `PatchRelay could not complete the ${params.stageRun.stage} workflow: ${params.message}`,
-            },
+        deliveredToSession =
+            (await linear
+                .updateAgentSession?.({
+                agentSessionId: params.issue.activeAgentSessionId,
+                plan: buildFailedSessionPlan(params.stageRun.stage, params.stageRun),
+            })
+                .then(() => true)
+                .catch(() => false)) ?? false;
+        deliveredToSession =
+            (await linear
+                .createAgentActivity({
+                agentSessionId: params.issue.activeAgentSessionId,
+                content: {
+                    type: "error",
+                    body: `PatchRelay could not complete the ${params.stageRun.stage} workflow: ${params.message}`,
+                },
+            })
+                .then(() => true)
+                .catch(() => false)) || deliveredToSession;
+    }
+    if (!deliveredToSession) {
+        const result = await linear
+            .upsertIssueComment({
+            issueId: params.stageRun.linearIssueId,
+            ...(params.issue.statusCommentId ? { commentId: params.issue.statusCommentId } : {}),
+            body: buildStageFailedComment({
+                issue: params.issue,
+                stageRun: params.stageRun,
+                message: params.message,
+                ...(fallbackState ? { fallbackState } : {}),
+                ...(params.mode ? { mode: params.mode } : {}),
+            }),
         })
             .catch(() => undefined);
+        if (result) {
+            params.stores.workflowCoordinator.setIssueStatusComment(params.stageRun.projectId, params.stageRun.linearIssueId, result.id);
+        }
     }
 }

package/dist/stage-lifecycle-publisher.js

@@ -1,3 +1,5 @@
+import { buildAwaitingHandoffSessionPlan, buildCompletedSessionPlan, buildRunningSessionPlan, } from "./agent-session-plan.js";
+import { buildAgentSessionExternalUrls } from "./agent-session-presentation.js";
 import { buildAwaitingHandoffComment, buildRunningStatusComment, resolveActiveLinearState, resolveWorkflowLabelCleanup, resolveWorkflowLabelNames, } from "./linear-workflow.js";
 import { sanitizeDiagnosticText } from "./utils.js";
 export class StageLifecyclePublisher {
@@ -71,12 +73,13 @@ export class StageLifecyclePublisher {
     }
     async publishStageStarted(issue, stage) {
         if (!issue.activeAgentSessionId) {
-            return;
+            return false;
         }
         const linear = await this.linearProvider.forProject(issue.projectId);
         if (!linear) {
-            return;
+            return false;
         }
+        const sessionUpdated = await this.updateAgentSession(linear, issue, buildRunningSessionPlan(stage), stage);
         try {
             await linear.createAgentActivity({
                 agentSessionId: issue.activeAgentSessionId,
@@ -88,6 +91,7 @@ export class StageLifecyclePublisher {
                 },
                 ephemeral: true,
             });
+            return true;
         }
         catch (error) {
             this.logger.warn({
@@ -96,6 +100,7 @@ export class StageLifecyclePublisher {
                 agentSessionId: issue.activeAgentSessionId,
                 error: error instanceof Error ? error.message : String(error),
             }, "Failed to publish Linear agent activity after stage startup");
+            return sessionUpdated;
         }
     }
     async publishStageCompletion(stageRun, enqueueIssue) {
@@ -134,16 +139,10 @@ export class StageLifecyclePublisher {
                     }
                     this.stores.workflowCoordinator.setIssueLifecycleStatus(stageRun.projectId, stageRun.linearIssueId, "paused");
                     const finalStageRun = this.stores.issueWorkflows.getStageRun(stageRun.id) ?? stageRun;
-                    const result = await linear.upsertIssueComment({
-                        issueId: stageRun.linearIssueId,
-                        ...(refreshedIssue.statusCommentId ? { commentId: refreshedIssue.statusCommentId } : {}),
-                        body: buildAwaitingHandoffComment({
-                            issue: refreshedIssue,
-                            stageRun: finalStageRun,
-                            activeState,
-                        }),
-                    });
-                    this.stores.workflowCoordinator.setIssueStatusComment(stageRun.projectId, stageRun.linearIssueId, result.id);
+                    let deliveredToSession = false;
+                    if (refreshedIssue.activeAgentSessionId) {
+                        deliveredToSession = await this.updateAgentSession(linear, refreshedIssue, buildAwaitingHandoffSessionPlan(stageRun.stage));
+                    }
                     this.feed?.publish({
                         level: "info",
                         kind: "stage",
@@ -154,10 +153,23 @@ export class StageLifecyclePublisher {
                         summary: `Completed ${stageRun.stage} workflow`,
                         detail: `Waiting for a Linear state change or follow-up input while the issue remains in ${activeState}.`,
                     });
-                    await this.publishAgentCompletion(refreshedIssue, {
-                        type: "elicitation",
-                        body: `PatchRelay finished the ${stageRun.stage} workflow. Move the issue to its next workflow state or leave a follow-up prompt to continue.`,
-                    });
+                    deliveredToSession =
+                        (await this.publishAgentCompletion(refreshedIssue, {
+                            type: "elicitation",
+                            body: `PatchRelay finished the ${stageRun.stage} workflow. Move the issue to its next workflow state or leave a follow-up prompt to continue.`,
+                        })) || deliveredToSession;
+                    if (!deliveredToSession) {
+                        const result = await linear.upsertIssueComment({
+                            issueId: stageRun.linearIssueId,
+                            ...(refreshedIssue.statusCommentId ? { commentId: refreshedIssue.statusCommentId } : {}),
+                            body: buildAwaitingHandoffComment({
+                                issue: refreshedIssue,
+                                stageRun: finalStageRun,
+                                activeState,
+                            }),
+                        });
+                        this.stores.workflowCoordinator.setIssueStatusComment(stageRun.projectId, stageRun.linearIssueId, result.id);
+                    }
                     return;
                 }
                 const cleanup = resolveWorkflowLabelCleanup(project);
@@ -179,6 +191,9 @@ export class StageLifecyclePublisher {
             }
         }
         if (refreshedIssue) {
+            if (refreshedIssue.activeAgentSessionId && linear) {
+                await this.updateAgentSession(linear, refreshedIssue, buildCompletedSessionPlan(stageRun.stage));
+            }
             this.feed?.publish({
                 level: "info",
                 kind: "stage",
@@ -194,20 +209,46 @@ export class StageLifecyclePublisher {
             });
         }
     }
+    async updateAgentSession(linear, issue, plan, stage) {
+        if (!issue.activeAgentSessionId) {
+            return false;
+        }
+        try {
+            const externalUrls = buildAgentSessionExternalUrls(this.config, issue.issueKey);
+            await linear.updateAgentSession?.({
+                agentSessionId: issue.activeAgentSessionId,
+                ...(externalUrls ? { externalUrls } : {}),
+                plan,
+            });
+            return true;
+        }
+        catch (error) {
+            this.logger.warn({
+                issueKey: issue.issueKey,
+                issueId: issue.linearIssueId,
+                ...(stage ? { stage } : {}),
+                agentSessionId: issue.activeAgentSessionId,
+                error: sanitizeDiagnosticText(error instanceof Error ? error.message : String(error)),
+            }, "Failed to update Linear agent session");
+            return false;
+        }
+    }
     async publishAgentCompletion(issue, content) {
         if (!issue.activeAgentSessionId) {
-            return;
+            return false;
         }
         const linear = await this.linearProvider.forProject(issue.projectId);
         if (!linear) {
-            return;
+            return false;
         }
-        await linear
-            .createAgentActivity({
-            agentSessionId: issue.activeAgentSessionId,
-            content,
-        })
-            .catch((error) => {
+        try {
+            await linear.createAgentActivity({
+                agentSessionId: issue.activeAgentSessionId,
+                content,
+            });
+            return true;
+        }
+        catch (error) {
             this.logger.warn({
                 issueKey: issue.issueKey,
                 issueId: issue.linearIssueId,
@@ -215,6 +256,7 @@ export class StageLifecyclePublisher {
                 activityType: content.type,
                 error: sanitizeDiagnosticText(error instanceof Error ? error.message : String(error)),
             }, "Failed to publish Linear agent activity");
-        });
+            return false;
+        }
     }
 }

package/dist/webhook-agent-session-handler.js

@@ -1,10 +1,19 @@
 import { createHash } from "node:crypto";
+import { buildPreparingSessionPlan, buildRunningSessionPlan } from "./agent-session-plan.js";
 import { triggerEventAllowed } from "./project-resolution.js";
 import { listRunnableStates, resolveWorkflowStage } from "./workflow-policy.js";
 function trimPrompt(value) {
     const trimmed = value?.trim();
     return trimmed ? trimmed : undefined;
 }
+function buildSessionUpdateParams(projectId, agentSessionId, issueKey, plan) {
+    return {
+        projectId,
+        agentSessionId,
+        ...(issueKey ? { issueKey } : {}),
+        plan,
+    };
+}
 export class AgentSessionWebhookHandler {
     stores;
     turnInputDispatcher;
@@ -30,6 +39,7 @@ export class AgentSessionWebhookHandler {
         if (normalized.triggerEvent === "agentSessionCreated") {
             if (!delegatedToPatchRelay) {
                 if (activeStage) {
+                    await this.agentActivity.updateSession(buildSessionUpdateParams(project.id, normalized.agentSession.id, issue?.issueKey ?? normalized.issue?.identifier, buildRunningSessionPlan(activeStage)));
                     await this.agentActivity.publishForSession(project.id, normalized.agentSession.id, {
                         type: "thought",
                         body: `PatchRelay is already running the ${activeStage} workflow for this issue. Delegate it to PatchRelay if you want automation to own the workflow, or keep replying here to steer the active run.`,
@@ -54,15 +64,17 @@ export class AgentSessionWebhookHandler {
                 return;
             }
             if (desiredStage) {
+                await this.agentActivity.updateSession(buildSessionUpdateParams(project.id, normalized.agentSession.id, issue?.issueKey ?? normalized.issue?.identifier, buildPreparingSessionPlan(desiredStage)));
                 await this.agentActivity.publishForSession(project.id, normalized.agentSession.id, {
-                    type: "thought",
-                    body: `PatchRelay received the delegation and is preparing the ${desiredStage} workflow.`,
+                    type: "response",
+                    body: `PatchRelay picked this up and is preparing the ${desiredStage} workflow.`,
                 });
                 return;
             }
             if (activeStage) {
+                await this.agentActivity.updateSession(buildSessionUpdateParams(project.id, normalized.agentSession.id, issue?.issueKey ?? normalized.issue?.identifier, buildRunningSessionPlan(activeStage)));
                 await this.agentActivity.publishForSession(project.id, normalized.agentSession.id, {
-                    type: "thought",
+                    type: "response",
                     body: `PatchRelay is already running the ${activeStage} workflow for this issue.`,
                 });
             }
@@ -123,8 +135,9 @@ export class AgentSessionWebhookHandler {
             return;
         }
         if (!activeRunLease && desiredStage) {
+            await this.agentActivity.updateSession(buildSessionUpdateParams(project.id, normalized.agentSession.id, issue?.issueKey ?? normalized.issue?.identifier, buildPreparingSessionPlan(desiredStage)));
             await this.agentActivity.publishForSession(project.id, normalized.agentSession.id, {
-                type: "thought",
+                type: "response",
                 body: `PatchRelay received your prompt and is preparing the ${desiredStage} workflow.`,
             });
             return;

package/dist/webhook-desired-stage-recorder.js

@@ -27,6 +27,8 @@ export class WebhookDesiredStageRecorder {
         const stageAllowed = triggerEventAllowed(project, normalized.triggerEvent);
         const desiredStage = this.resolveDesiredStage(project, normalized, issue, activeStageRun, delegatedToPatchRelay);
         const launchInput = this.resolveLaunchInput(normalized.agentSession);
+        const activeAgentSessionId = normalized.agentSession?.id ??
+            (!activeStageRun && (desiredStage || (normalized.triggerEvent === "delegateChanged" && !delegatedToPatchRelay)) ? null : undefined);
         const refreshedIssue = this.stores.workflowCoordinator.recordDesiredStage({
             projectId: project.id,
             linearIssueId: normalizedIssue.id,
@@ -36,7 +38,7 @@ export class WebhookDesiredStageRecorder {
             ...(normalizedIssue.stateName ? { currentLinearState: normalizedIssue.stateName } : {}),
             ...(desiredStage ? { desiredStage } : {}),
             ...(options?.eventReceiptId !== undefined ? { desiredReceiptId: options.eventReceiptId } : {}),
-            ...(normalized.agentSession?.id ? { activeAgentSessionId: normalized.agentSession.id } : {}),
+            ...(activeAgentSessionId !== undefined ? { activeAgentSessionId } : {}),
             lastWebhookAt: new Date().toISOString(),
         });
         if (launchInput && !activeStageRun && delegatedToPatchRelay && stageAllowed) {
@@ -74,27 +76,14 @@ export class WebhookDesiredStageRecorder {
         if (!normalizedIssue) {
             return undefined;
         }
-        const stageAllowed = triggerEventAllowed(project, normalized.triggerEvent);
-        let desiredStage;
-        if (normalized.triggerEvent === "delegateChanged") {
-            desiredStage = delegatedToPatchRelay ? resolveWorkflowStage(project, normalizedIssue.stateName) : undefined;
-            if (!desiredStage) {
-                return undefined;
-            }
-            if (!stageAllowed && !project.triggerEvents.includes("statusChanged")) {
-                return undefined;
-            }
-        }
-        else if (normalized.triggerEvent === "agentSessionCreated" || normalized.triggerEvent === "agentPrompted") {
-            if (!delegatedToPatchRelay || !stageAllowed) {
-                return undefined;
-            }
-            desiredStage = resolveWorkflowStage(project, normalizedIssue.stateName);
+        if (normalized.triggerEvent !== "agentSessionCreated" && normalized.triggerEvent !== "agentPrompted") {
+            return undefined;
         }
-        else if (stageAllowed) {
-            desiredStage = resolveWorkflowStage(project, normalizedIssue.stateName);
+        if (!delegatedToPatchRelay || !triggerEventAllowed(project, normalized.triggerEvent)) {
+            return undefined;
         }
-        else {
+        const desiredStage = resolveWorkflowStage(project, normalizedIssue.stateName);
+        if (!desiredStage) {
             return undefined;
         }
         if (activeStageRun && desiredStage === activeStageRun.stage) {

package/package.json

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