patchrelay 0.7.4 → 0.7.6

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 [
+        { label: "Prepare workspace", status: statuses[0] },
+        { label: `Run ${stageLabel} workflow`, status: statuses[1] },
+        { label: "Review next Linear step", status: statuses[2] },
+    ];
+}
+export function buildPreparingSessionPlan(stage) {
+    return buildPlan(stage, ["in_progress", "pending", "pending"]);
+}
+export function buildRunningSessionPlan(stage) {
+    return buildPlan(stage, ["completed", "in_progress", "pending"]);
+}
+export function buildCompletedSessionPlan(stage) {
+    return buildPlan(stage, ["completed", "completed", "completed"]);
+}
+export function buildAwaitingHandoffSessionPlan(stage) {
+    return buildPlan(stage, ["completed", "completed", "in_progress"]);
+}
+export function buildFailedSessionPlan(stage, stageRun) {
+    const workflowStepStatus = stageRun?.threadId || stageRun?.turnId ? "completed" : "in_progress";
+    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.4",
-  "commit": "3a0fe6ac72e2",
-  "builtAt": "2026-03-14T16:59:43.147Z"
+  "version": "0.7.6",
+  "commit": "cd9193b4a7b1",
+  "builtAt": "2026-03-17T08:05:09.587Z"
 }

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/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) {

package/package.json

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