The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat: structure and humanize recovery notices (#11075)
scotttongcc35c3c395ae
diff --git a/packages/shared/src/types/issue.ts b/packages/shared/src/types/issue.tsindex 36c8bc309a..cf79698b3f 100644--- a/packages/shared/src/types/issue.ts+++ b/packages/shared/src/types/issue.ts@@ -992,6 +992,7 @@ export interface IssueCommentMetadataAgentLinkRow extends IssueCommentMetadataRoexport interface IssueCommentMetadataRunLinkRow extends IssueCommentMetadataRowBase {type: "run_link";runId: string;+ agentId?: string | null;title?: string | null;}diff --git a/packages/shared/src/validators/issue.test.ts b/packages/shared/src/validators/issue.test.tsindex 762d4538bf..20161a2094 100644--- a/packages/shared/src/validators/issue.test.ts+++ b/packages/shared/src/validators/issue.test.ts@@ -277,7 +277,12 @@ describe("issue validators", () => {rows: [{ type: "key_value", label: "Cause", value: "successful_run_missing_state" },{ type: "issue_link", label: "Source issue", identifier: "PAP-3440" },- { type: "run_link", label: "Run", runId: "11111111-1111-4111-8111-111111111111" },+ {+ type: "run_link",+ label: "Run",+ runId: "11111111-1111-4111-8111-111111111111",+ agentId: "22222222-2222-4222-8222-222222222222",+ },],},],@@ -288,6 +293,10 @@ describe("issue validators", () => {expect(parsed.presentation?.density).toBe("compact");expect(parsed.metadata?.sourceRunId).toBe("11111111-1111-4111-8111-111111111111");expect(parsed.metadata?.sections[0]?.rows).toHaveLength(3);+ expect(parsed.metadata?.sections[0]?.rows[2]).toMatchObject({+ type: "run_link",+ agentId: "22222222-2222-4222-8222-222222222222",+ });});it("rejects unknown issue comment presentation densities", () => {diff --git a/packages/shared/src/validators/issue.ts b/packages/shared/src/validators/issue.tsindex b67d7e1ae6..557519c213 100644--- a/packages/shared/src/validators/issue.ts+++ b/packages/shared/src/validators/issue.ts@@ -631,6 +631,7 @@ const issueCommentMetadataAgentLinkRowSchema = issueCommentMetadataBaseRowSchemaconst issueCommentMetadataRunLinkRowSchema = issueCommentMetadataBaseRowSchema.extend({type: z.literal("run_link"),runId: z.string().uuid(),+ agentId: z.string().uuid().nullable().optional(),title: z.string().trim().min(1).max(160).nullable().optional(),}).strict();diff --git a/server/src/__tests__/heartbeat-process-recovery.test.ts b/server/src/__tests__/heartbeat-process-recovery.test.tsindex 789c28552d..84ba03a1b5 100644--- a/server/src/__tests__/heartbeat-process-recovery.test.ts+++ b/server/src/__tests__/heartbeat-process-recovery.test.ts@@ -116,6 +116,7 @@ import {SUCCESSFUL_RUN_HANDOFF_EXHAUSTED_NOTICE_BODY,SUCCESSFUL_RUN_HANDOFF_REQUIRED_NOTICE_BODY,SUCCESSFUL_RUN_MISSING_STATE_REASON,+ noticeMetadataReferencesRecoveryAction,} from "../services/recovery/index.ts";import {UNMANAGED_BACKGROUND_TASK_LIVENESS_REASON,@@ -130,6 +131,11 @@ if (!embeddedPostgresSupport.supported) {);}+function commentMetadataRows(comment: { metadata?: unknown } | null | undefined) {+ const metadata = comment?.metadata as { sections?: Array<{ rows?: unknown[] }> } | null | undefined;+ return (metadata?.sections ?? []).flatMap((section) => section.rows ?? []) as Array<Record<string, unknown>>;+}+function spawnAliveProcess() {return spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"], {stdio: "ignore",@@ -2489,8 +2495,11 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {});expect(comments).toHaveLength(1);expect(comments[0]?.body).toContain("retried continuation");- expect(comments[0]?.body).toContain(`Recovery action: \`${recoveryAction.id}\``);- expect(comments[0]?.body).toContain("Recovery owner: [CodexCoder]");+ expect(comments[0]?.presentation).toMatchObject({ kind: "system_notice", tone: "danger" });+ expect(noticeMetadataReferencesRecoveryAction(comments[0]?.metadata, recoveryAction.id)).toBe(true);+ expect(commentMetadataRows(comments[0]).some((row) =>+ row.type === "agent_link" && row.label === "Recovery owner" && row.name === "CodexCoder",+ )).toBe(true);});it("blocks failed recovery work in place during immediate terminal-run cleanup", async () => {@@ -2565,6 +2574,7 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {expect(comments[0]?.body).toContain("recovery issues do not create nested `stranded_issue_recovery` issues");expect(comments[0]?.body).toContain("Latest retry failure details were withheld from the issue thread");expect(comments[0]?.body).not.toContain("sk-test-recovery-secret");+ expect(JSON.stringify(comments[0]?.metadata)).not.toContain("sk-test-recovery-secret");expect(comments[0]?.presentation).toMatchObject({kind: "system_notice",tone: "warning",@@ -2944,7 +2954,7 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {authorType: "system",body: expect.stringContaining("Agent failed to resume after approval: `adapter_failed` — needs attention"),});- expect(comments[0]?.body).toContain("Recovery action:");+ expect(commentMetadataRows(comments[0]).some((row) => row.label === "Recovery action")).toBe(true);const interaction = await db.select({ result: issueThreadInteractions.result })@@ -4697,7 +4707,7 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {const comments = await db.select().from(issueComments).where(eq(issueComments.issueId, issueId));const recoveryComment = comments.find((comment) =>comment.body.includes("pending execution-review participant once") &&- comment.body.includes(`Recovery action: \`${recoveryAction.id}\``),+ noticeMetadataReferencesRecoveryAction(comment.metadata, recoveryAction.id),);expect(recoveryComment).toBeTruthy();@@ -5511,25 +5521,18 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {const comments = await db.select().from(issueComments).where(eq(issueComments.issueId, issueId));expect(comments).toHaveLength(1);expect(comments[0]?.body).toContain("retried dispatch");- expect(comments[0]?.body).toContain("Latest retry failure details were withheld from the issue thread");- expect(comments[0]?.body).toContain(`Recovery action: \`${recoveryAction.id}\``);- expect(comments[0]?.body).toContain(`Recovery owner: [${longRecoveryOwnerName}]`);- expect(comments[0]?.presentation).toMatchObject({- kind: "system_notice",- tone: "warning",- title: `${`Recovery: retries exhausted — moved to blocked (owner: ${longRecoveryOwnerName})`.slice(0, 159)}…`,- density: "compact",- });- expect(comments[0]?.metadata).toMatchObject({- version: 1,- sections: [expect.objectContaining({- rows: expect.arrayContaining([- expect.objectContaining({ type: "key_value", label: "Recovery action", value: recoveryAction.id }),- expect.objectContaining({ type: "key_value", label: "Cause", value: "process_lost" }),- expect.objectContaining({ type: "agent_link", label: "Recovery owner", name: "R".repeat(160) }),- ]),- })],- });+ expect(comments[0]?.body).not.toContain("sk-test-recovery-secret");+ expect(JSON.stringify(comments[0]?.metadata)).not.toContain("sk-test-recovery-secret");+ const failureSummary = commentMetadataRows(comments[0]).find((row) =>+ row.type === "key_value" && row.label === "Failure summary"+ );+ expect(failureSummary).toMatchObject({ type: "key_value", label: "Failure summary" });+ expect(failureSummary?.type === "key_value" ? failureSummary.value : "").toContain("Authorization");+ expect(comments[0]?.presentation).toMatchObject({ kind: "system_notice", tone: "danger" });+ expect(noticeMetadataReferencesRecoveryAction(comments[0]?.metadata, recoveryAction.id)).toBe(true);+ expect(commentMetadataRows(comments[0]).some((row) =>+ row.type === "agent_link" && row.label === "Recovery owner" && row.name === longRecoveryOwnerName.slice(0, 160),+ )).toBe(true);});it("blocks an already stranded recovery issue without creating a recovery child", async () => {@@ -5933,9 +5936,11 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {const comments = await db.select().from(issueComments).where(eq(issueComments.issueId, issueId));expect(comments).toHaveLength(1);expect(comments[0]?.body).toContain("retried continuation");- expect(comments[0]?.body).toContain("Latest retry failure details were withheld from the issue thread");- expect(comments[0]?.body).toContain(`Recovery action: \`${recoveryAction.id}\``);- expect(comments[0]?.body).toContain("Recovery owner: [CodexCoder]");+ expect(comments[0]?.presentation).toMatchObject({ kind: "system_notice", tone: "danger" });+ expect(noticeMetadataReferencesRecoveryAction(comments[0]?.metadata, recoveryAction.id)).toBe(true);+ expect(commentMetadataRows(comments[0]).some((row) =>+ row.type === "agent_link" && row.label === "Recovery owner" && row.name === "CodexCoder",+ )).toBe(true);});it("redacts error-code-only stranded recovery failures in issue copy", async () => {@@ -5966,8 +5971,15 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {const comments = await db.select().from(issueComments).where(eq(issueComments.issueId, issueId));expect(comments).toHaveLength(1);- expect(comments[0]?.body).toContain("Latest retry failure details were withheld from the issue thread");+ // The short structured body carries no failure details; the normalized+ // failure code surfaces only as a metadata row.+ expect(comments[0]?.body).not.toContain("adapter_exit_code");expect(comments[0]?.body).not.toContain("- Failure: none recorded");+ expect(commentMetadataRows(comments[0])).toContainEqual({+ type: "key_value",+ label: "Failure code",+ value: "adapter_exit_code",+ });});it("keeps retrying transient adapter_failed continuation runs before the cap", async () => {@@ -6060,7 +6072,11 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {expect(comments).toHaveLength(1);expect(comments[0]?.body).toContain("retried continuation");expect(comments[0]?.body).toContain("3× attempts");- expect(comments[0]?.body).toContain("Latest cause: `adapter_failed`");+ expect(commentMetadataRows(comments[0])).toContainEqual({+ type: "key_value",+ label: "Failure code",+ value: "adapter_failed",+ });});it("does not count mixed-cause continuation failures toward the transient cap", async () => {@@ -6687,8 +6703,10 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {expect(comments).toHaveLength(1);expect(comments[0]?.body).toContain("automatically retried continuation");expect(comments[0]?.body).toContain("still has no live execution path");- expect(comments[0]?.body).toContain(`Recovery action: \`${recoveryAction.id}\``);- expect(comments[0]?.body).toContain("Recovery owner: [CodexCoder]");+ expect(noticeMetadataReferencesRecoveryAction(comments[0]?.metadata, recoveryAction.id)).toBe(true);+ expect(commentMetadataRows(comments[0]).some((row) =>+ row.type === "agent_link" && row.label === "Recovery owner" && row.name === "CodexCoder",+ )).toBe(true);});it("allows one productive-terminal recovery after regular continuation recovery made progress", async () => {diff --git a/server/src/__tests__/heartbeat-workspace-branch-containment.test.ts b/server/src/__tests__/heartbeat-workspace-branch-containment.test.tsindex ed899e0dfc..38394581ea 100644--- a/server/src/__tests__/heartbeat-workspace-branch-containment.test.ts+++ b/server/src/__tests__/heartbeat-workspace-branch-containment.test.ts@@ -37,6 +37,7 @@ import {} from "./helpers/embedded-postgres.js";import { drainHeartbeatRunsToQuiescence } from "./helpers/drain-heartbeat-runs.js";import { heartbeatService } from "../services/heartbeat.ts";+import { noticeMetadataReferencesRecoveryAction } from "../services/recovery/index.ts";import { instanceSettingsService } from "../services/instance-settings.ts";import {WORKSPACE_WORKTREE_REQUIRES_PROJECT_CODE,@@ -221,7 +222,7 @@ async function waitForContainmentSideEffects(input: {const hasRecoveryActionComment = recoveryActionId? comments.some((comment) =>comment.issueId === input.sourceIssueId &&- comment.body.includes(`Recovery action: \`${recoveryActionId}\``))+ noticeMetadataReferencesRecoveryAction(comment.metadata, recoveryActionId)): false;if (source?.status === "blocked" &&@@ -685,7 +686,10 @@ async function expectContainedWorkspaceBranchFailure(input: {}),});- expect(comments.filter((comment) => comment.issueId === input.sourceIssueId && comment.body.includes(`Recovery action: \`${action.id}\``))).toHaveLength(1);+ expect(comments.filter((comment) =>+ comment.issueId === input.sourceIssueId &&+ noticeMetadataReferencesRecoveryAction(comment.metadata, action.id),+ )).toHaveLength(1);expect(comments.filter((comment) => comment.issueId === input.sameWorkspaceSiblingId)).toHaveLength(0);expect(comments.filter((comment) => comment.issueId === input.otherWorkspaceSiblingId)).toHaveLength(0);}@@ -812,14 +816,10 @@ async function expectForwardBranchReconciled(input: {]),);if (resolvedRecoveryActionId) {- expect(comments).toEqual(- expect.arrayContaining([- expect.objectContaining({- authorType: "system",- body: expect.stringContaining(`Recovery action: \`${resolvedRecoveryActionId}\``),- }),- ]),- );+ expect(comments.some((comment) =>+ comment.authorType === "system" &&+ noticeMetadataReferencesRecoveryAction(comment.metadata, resolvedRecoveryActionId),+ )).toBe(true);}const activities = await input.dbdiff --git a/server/src/__tests__/issue-recovery-actions.test.ts b/server/src/__tests__/issue-recovery-actions.test.tsindex 236f884c34..f5a2d036dd 100644--- a/server/src/__tests__/issue-recovery-actions.test.ts+++ b/server/src/__tests__/issue-recovery-actions.test.ts@@ -27,6 +27,7 @@ import { issueRoutes } from "../routes/issues.js";import { buildPaperclipWakePayload } from "../services/heartbeat.js";import { issueRecoveryActionService } from "../services/issue-recovery-actions.js";import { recoveryService } from "../services/recovery/service.js";+import { noticeMetadataReferencesRecoveryAction } from "../services/recovery/successful-run-handoff.js";const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;@@ -1143,21 +1144,14 @@ describeEmbeddedPostgres("issue recovery actions", () => {});const comments = await db.select().from(issueComments).where(eq(issueComments.issueId, sourceIssue.id));- expect(comments).toHaveLength(1);- expect(comments[0]?.presentation).toMatchObject({+ const escalationComments = comments.filter((comment) =>+ noticeMetadataReferencesRecoveryAction(comment.metadata, actionRows[0]!.id),+ );+ expect(escalationComments).toHaveLength(1);+ expect(escalationComments[0]?.presentation).toMatchObject({kind: "system_notice",- tone: "warning",- title: "Recovery: workspace validation failed — moved to blocked (owner: CTO)",- density: "compact",- });- expect(comments[0]?.metadata).toMatchObject({- version: 1,- sections: [expect.objectContaining({- rows: expect.arrayContaining([- expect.objectContaining({ type: "key_value", label: "Recovery action", value: actionRows[0]?.id }),- expect.objectContaining({ type: "key_value", label: "Cause", value: "workspace_validation_failed" }),- ]),- })],+ tone: "danger",+ title: "Workspace validation failed",});expect(enqueueWakeup).toHaveBeenCalledTimes(2);expect(enqueueWakeup).toHaveBeenCalledWith(@@ -1231,7 +1225,11 @@ describeEmbeddedPostgres("issue recovery actions", () => {const comments = await db.select().from(issueComments).where(eq(issueComments.issueId, sourceIssue.id));expect(comments).toHaveLength(1);- expect(comments[0]?.body).toContain("Recovery action:");+ // Dedupe for structured notices is metadata-based: the short body no longer+ // carries the `Recovery action: \`id\`` marker line.+ expect(comments[0]?.body).not.toContain("Recovery action:");+ expect(noticeMetadataReferencesRecoveryAction(comments[0]?.metadata, actionRows[0]!.id)).toBe(true);+ expect(comments[0]?.presentation).toMatchObject({ kind: "system_notice", tone: "danger" });});it("does not create nested recovery artifacts when issue-backed fallback work itself fails", async () => {diff --git a/server/src/services/heartbeat.ts b/server/src/services/heartbeat.tsindex f9eddcbd5b..5ffbfe143b 100644--- a/server/src/services/heartbeat.ts+++ b/server/src/services/heartbeat.ts@@ -224,6 +224,12 @@ import {readContinuationAttempt,} from "./recovery/index.js";import { isAutomaticRecoverySuppressedByPauseHold } from "./recovery/pause-hold-guard.js";+import {+ buildConfigurationIncompleteRecoveryNoticeSeed,+ buildExecutionReviewParticipantRecoveryNoticeSeed,+ buildImmediateExecutionPathRecoveryNoticeSeed,+ buildWorkspaceValidationRecoveryNoticeSeed,+} from "./recovery/stranded-notice.js";import {recoveryAssigneeAdapterOverrides,withRecoveryModelProfileHint,@@ -3616,30 +3622,6 @@ export function summarizeHeartbeatRunListResultJson(input: {return Object.keys(summary).length > 0 ? summary : null;}-function summarizeRunFailureForIssueComment(- run: Pick<typeof heartbeatRuns.$inferSelect, "error" | "errorCode"> | null | undefined,-) {- if (!run) return null;-- const errorCode = readNonEmptyString(run.errorCode)?.trim() ?? null;- const rawError = readNonEmptyString(run.error)?.trim() ?? null;- const apiMessageMatch = rawError?.match(/"message"\s*:\s*"([^"]+)"/);- const firstLine = rawError- ?.split(/\r?\n/)- .map((line) => line.trim())- .find(Boolean) ?? null;- const summarySource = apiMessageMatch?.[1] ?? firstLine;- const summary =- summarySource && summarySource.length > 240- ? `${summarySource.slice(0, 237)}...`- : summarySource;-- if (errorCode && summary) return ` Latest retry failure: \`${errorCode}\` - ${summary}.`;- if (errorCode) return ` Latest retry failure: \`${errorCode}\`.`;- if (summary) return ` Latest retry failure: ${summary}.`;- return null;-}-function didAutomaticRecoveryFail(latestRun: Pick<typeof heartbeatRuns.$inferSelect, "status" | "contextSnapshot"> | null,expectedRetryReason:@@ -16379,73 +16361,6 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})}}- function buildImmediateExecutionPathRecoveryComment(input: {- status: "todo" | "in_progress";- latestRun: Pick<typeof heartbeatRuns.$inferSelect, "error" | "errorCode"> | null | undefined;- }) {- const failureSummary = summarizeRunFailureForIssueComment(input.latestRun);- if (input.status === "todo") {- return (- "Paperclip automatically retried dispatch for this assigned `todo` issue during terminal run recovery, " +- `but it still has no live execution path.${failureSummary ?? ""} ` +- "Moving it to `blocked` so it is visible for intervention."- );- }-- return (- "Paperclip automatically retried continuation for this assigned `in_progress` issue during terminal run " +- `recovery, but it still has no live execution path.${failureSummary ?? ""} ` +- "Moving it to `blocked` so it is visible for intervention."- );- }-- function buildWorkspaceValidationRecoveryComment(input: {- latestRun:- | Pick<typeof heartbeatRuns.$inferSelect, "error" | "errorCode" | "resultJson">- | null- | undefined;- }) {- const failureSummary = summarizeRunFailureForIssueComment(input.latestRun);- const validationReason = readNonEmptyString(- readWorkspaceValidationPayloadFromRun(input.latestRun).reason,- );- if (validationReason === "git_worktree_base_materialization_failed") {- return (- "Paperclip stopped before launching the local adapter because the project workspace checkout could not be prepared " +- `(for example the repository clone failed).${failureSummary ?? ""} ` +- "Moving it to `blocked` with a source-scoped recovery action so the repository URL, clone access, or configured local cwd can be repaired before resuming."- );- }- return (- "Paperclip stopped before launching the local adapter because the issue workspace failed validation. " +- `This prevents git-sensitive adapters from running in an unrelated fallback cwd.${failureSummary ?? ""} ` +- "Moving it to `blocked` with a source-scoped recovery action so the workspace link, cwd, or git checkout can be repaired before resuming."- );- }-- function buildConfigurationIncompleteRecoveryComment(input: {- latestRun: Pick<typeof heartbeatRuns.$inferSelect, "error" | "errorCode"> | null | undefined;- }) {- const failureSummary = summarizeRunFailureForIssueComment(input.latestRun);- return (- "Paperclip stopped before dispatching the adapter because required secret/env bindings are missing. " +- `Resolving them as a runtime failure would only produce repeated opaque setup failures.${failureSummary ?? ""} ` +- "Moving it to `blocked` with a source-scoped recovery action so an operator can bind the missing secret(s) before resuming."- );- }-- function buildExecutionReviewParticipantRecoveryComment(input: {- latestRun: Pick<typeof heartbeatRuns.$inferSelect, "error" | "errorCode"> | null | undefined;- }) {- const failureSummary = summarizeRunFailureForIssueComment(input.latestRun);- return (- "Paperclip retried the pending execution-review participant once, but the review stage still has no completed decision " +- `or live reviewer run.${failureSummary ?? ""} ` +- "Moving it to `blocked` with a source-scoped recovery action so the recovery owner can repair the reviewer runtime, " +- "restore the review stage, or record an intentional manual resolution."- );- }-async function releaseIssueExecutionAndPromote(run: typeof heartbeatRuns.$inferSelect,options: { suppressImmediateRecovery?: boolean } = {},@@ -16579,9 +16494,9 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})kind: "blocked" as const,issue,previousStatus: issue.status,- comment: configurationIncomplete- ? buildConfigurationIncompleteRecoveryComment({ latestRun: run })- : buildWorkspaceValidationRecoveryComment({ latestRun: run }),+ notice: configurationIncomplete+ ? buildConfigurationIncompleteRecoveryNoticeSeed()+ : buildWorkspaceValidationRecoveryNoticeSeed(),recoveryCause: configurationIncomplete? CONFIGURATION_INCOMPLETE_RECOVERY_CAUSE: WORKSPACE_VALIDATION_RECOVERY_CAUSE,@@ -16925,7 +16840,7 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})kind: "blocked" as const,issue,previousStatus: issue.status,- comment: buildExecutionReviewParticipantRecoveryComment({ latestRun: run }),+ notice: buildExecutionReviewParticipantRecoveryNoticeSeed(),recoveryCause: EXECUTION_REVIEW_PARTICIPANT_RECOVERY_CAUSE,recoveryOwnerAgentId: currentParticipant.agentId,};@@ -17046,19 +16961,18 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})if (shouldBlockImmediately) {const workspaceValidationFailure = isWorkspaceValidationFailedRun(run);const configurationIncompleteFailure = isConfigurationIncompleteFailedRun(run);- const comment = workspaceValidationFailure- ? buildWorkspaceValidationRecoveryComment({ latestRun: run })+ const notice = workspaceValidationFailure+ ? buildWorkspaceValidationRecoveryNoticeSeed(): configurationIncompleteFailure- ? buildConfigurationIncompleteRecoveryComment({ latestRun: run })- : buildImmediateExecutionPathRecoveryComment({+ ? buildConfigurationIncompleteRecoveryNoticeSeed()+ : buildImmediateExecutionPathRecoveryNoticeSeed({status: issue.status as "todo" | "in_progress",- latestRun: run,});return {kind: "blocked" as const,issue,previousStatus: issue.status,- comment,+ notice,recoveryCause: workspaceValidationFailure? WORKSPACE_VALIDATION_RECOVERY_CAUSE: configurationIncompleteFailure@@ -17168,7 +17082,7 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})issue: promotionResult.issue,previousStatus: promotionResult.previousStatus as "todo" | "in_progress" | "in_review",latestRun: run,- comment: promotionResult.comment,+ notice: promotionResult.notice,recoveryCause:promotionResult.recoveryCause === WORKSPACE_VALIDATION_RECOVERY_CAUSE? WORKSPACE_VALIDATION_RECOVERY_CAUSEdiff --git a/server/src/services/recovery/index.ts b/server/src/services/recovery/index.tsindex 245aa707e0..6d35159ed3 100644--- a/server/src/services/recovery/index.ts+++ b/server/src/services/recovery/index.ts@@ -58,8 +58,22 @@ export {findExistingFinishSuccessfulRunHandoffWake,isSuccessfulRunHandoffValidPathSkip,isSuccessfulRunHandoffRequiredNoticeBody,+ noticeMetadataReferencesRecoveryAction,} from "./successful-run-handoff.js";export type {SuccessfulRunHandoffNotice,SuccessfulRunHandoffDecision,} from "./successful-run-handoff.js";+export {+ DEFAULT_STRANDED_RECOVERY_NOTICE_BODY,+ buildConfigurationIncompleteRecoveryNoticeSeed,+ buildExecutionReviewParticipantRecoveryNoticeSeed,+ buildExecutionReviewParticipantUnavailableNoticeSeed,+ buildImmediateExecutionPathRecoveryNoticeSeed,+ buildStrandedRecoveryEscalationNotice,+ buildWorkspaceValidationRecoveryNoticeSeed,+} from "./stranded-notice.js";+export type {+ StrandedRecoveryEscalationNotice,+ StrandedRecoveryNoticeSeed,+} from "./stranded-notice.js";diff --git a/server/src/services/recovery/notice-format.ts b/server/src/services/recovery/notice-format.tsnew file mode 100644index 0000000000..520be52ec9--- /dev/null+++ b/server/src/services/recovery/notice-format.ts@@ -0,0 +1,68 @@+import type { IssueCommentMetadata, IssueCommentPresentation } from "@paperclipai/shared";++export type NoticeMetadataRow = IssueCommentMetadata["sections"][number]["rows"][number];+export type NoticeMetadataSection = IssueCommentMetadata["sections"][number];++export function metadataText(value: unknown, fallback = "unknown") {+ const text = typeof value === "string" ? value.trim() : value == null ? "" : String(value).trim();+ const resolved = text.length > 0 ? text : fallback;+ return resolved.length > 2000 ? `${resolved.slice(0, 1997)}...` : resolved;+}++export function keyValueRow(label: string, value: unknown): NoticeMetadataRow {+ return { type: "key_value", label, value: metadataText(value) };+}++export function issueLinkRow(+ label: string,+ issue: { id: string; identifier: string | null; title: string } | null | undefined,+): NoticeMetadataRow {+ if (!issue) return keyValueRow(label, "unknown");+ return {+ type: "issue_link",+ label,+ issueId: issue.id,+ identifier: issue.identifier,+ title: issue.title,+ };+}++export function runLinkRow(+ label: string,+ run: { id: string; status: string; agentId?: string | null } | null | undefined,+): NoticeMetadataRow {+ if (!run) return keyValueRow(label, "unknown");+ return {+ type: "run_link",+ label,+ runId: run.id,+ ...(run.agentId ? { agentId: run.agentId } : {}),+ title: run.status,+ };+}++export function agentLinkRow(+ label: string,+ agent: { id: string; name: string | null } | null | undefined,+): NoticeMetadataRow {+ if (!agent) return keyValueRow(label, "unknown");+ return {+ type: "agent_link",+ label,+ agentId: agent.id,+ // Issue-comment metadata constrains link names to 160 characters.+ name: agent.name?.slice(0, 160) ?? null,+ };+}++export function systemNoticePresentation(input: {+ tone: IssueCommentPresentation["tone"];+ title: string;+}): IssueCommentPresentation {+ return {+ kind: "system_notice",+ tone: input.tone,+ title: input.title,+ detailsDefaultOpen: false,+ };+}diff --git a/server/src/services/recovery/service.ts b/server/src/services/recovery/service.tsindex c0f2a5e032..9cfe392197 100644--- a/server/src/services/recovery/service.ts+++ b/server/src/services/recovery/service.ts@@ -61,6 +61,12 @@ import {noticeMetadataReferencesRecoveryAction,type SuccessfulRunHandoffNotice,} from "./successful-run-handoff.js";+import {+ buildExecutionReviewParticipantRecoveryNoticeSeed,+ buildExecutionReviewParticipantUnavailableNoticeSeed,+ buildStrandedRecoveryEscalationNotice,+ type StrandedRecoveryNoticeSeed,+} from "./stranded-notice.js";import {RECOVERY_ORIGIN_KINDS,buildIssueGraphLivenessLeafKey,@@ -312,25 +318,6 @@ function summarizeRunFailureForIssueComment(run: LatestIssueRun) {return null;}-function buildExecutionReviewParticipantRecoveryComment(latestRun: LatestIssueRun) {- const failureSummary = summarizeRunFailureForIssueComment(latestRun);- return (- "Paperclip retried the pending execution-review participant once, but the review stage still has no completed decision " +- `or live reviewer run.${failureSummary ?? ""} ` +- "Moving it to `blocked` with a source-scoped recovery action so the recovery owner can repair the reviewer runtime, " +- "restore the review stage, or record an intentional manual resolution."- );-}--function buildExecutionReviewParticipantUnavailableComment(latestRun: LatestIssueRun) {- const failureSummary = summarizeRunFailureForIssueComment(latestRun);- return (- "Paperclip cannot continue the pending execution-review participant because the participant is not invokable " +- `and the review stage has no completed decision or live reviewer run.${failureSummary ?? ""} ` +- "Moving it to `blocked` with a source-scoped recovery action so the recovery owner can repair the reviewer runtime, " +- "restore the review stage, or record an intentional manual resolution."- );-}function didAutomaticRecoveryFail(latestRun: LatestIssueRun,@@ -3315,6 +3302,7 @@ export function recoveryService(db: Db, deps: { enqueueWakeup: RecoveryWakeup })previousStatus: StrandedPreviousStatus;latestRun: LatestIssueRun;comment?: string;+ notice?: StrandedRecoveryNoticeSeed | null;recoveryCause?: StrandedRecoveryCause;recoveryOwnerAgentId?: string | null;successfulRunHandoffEvidence?: SuccessfulRunHandoffRecoveryEvidence | null;@@ -3356,17 +3344,30 @@ export function recoveryService(db: Db, deps: { enqueueWakeup: RecoveryWakeup })if (!updated) return null;if (isProviderQuotaWait) return updated;- const prefix = await getCompanyIssuePrefix(input.issue.companyId);const recoveryOwner = recoveryAction.ownerAgentId ? await getAgent(recoveryAction.ownerAgentId) : null;const sourceAssignee = input.issue.assigneeAgentId ? await getAgent(input.issue.assigneeAgentId) : null;let notice: SuccessfulRunHandoffNotice | null = null;if (input.recoveryCause === SUCCESSFUL_RUN_MISSING_STATE_REASON && input.successfulRunHandoffEvidence) {+ const [sourceRun] = input.successfulRunHandoffEvidence.sourceRunId+ ? await db+ .select({+ id: heartbeatRuns.id,+ status: heartbeatRuns.status,+ agentId: heartbeatRuns.agentId,+ })+ .from(heartbeatRuns)+ .where(and(+ eq(heartbeatRuns.id, input.successfulRunHandoffEvidence.sourceRunId),+ eq(heartbeatRuns.companyId, input.issue.companyId),+ ))+ .limit(1)+ : [];notice = buildSuccessfulRunHandoffExhaustedNotice({issue: input.issue,- sourceRun: input.successfulRunHandoffEvidence.sourceRunId- ? { id: input.successfulRunHandoffEvidence.sourceRunId, status: "succeeded" }+ sourceRun: sourceRun ?? null,+ correctiveRun: input.latestRun+ ? { id: input.latestRun.id, status: input.latestRun.status, agentId: input.latestRun.agentId }: null,- correctiveRun: input.latestRun ? { id: input.latestRun.id, status: input.latestRun.status } : null,sourceAssignee,recoveryIssue: null,recoveryActionId: recoveryAction.id,@@ -3376,19 +3377,24 @@ export function recoveryService(db: Db, deps: { enqueueWakeup: RecoveryWakeup })missingDisposition: input.successfulRunHandoffEvidence.missingDisposition,});}- const recoveryLine = recoveryAction.ownerAgentId- ? [- "",- `- Recovery action: \`${recoveryAction.id}\``,- `- Recovery owner: ${agentUiLink(recoveryOwner, prefix)}`,- "- Next action: the recovery owner should either restore a live execution path or record the manual resolution on the source issue.",- ].join("\n")- : [- "",- `- Recovery action: \`${recoveryAction.id}\``,- "- Recovery owner: board escalation, because Paperclip could not find an invokable manager, creator, or executive owner with budget available.",- "- Next action: a board operator should assign an invokable recovery owner, fix the agent/runtime state, or record an intentional manual resolution.",- ].join("\n");+ const escalationNotice = buildStrandedRecoveryEscalationNotice({+ seed: input.notice,+ fallbackBody: input.comment,+ recoveryCause,+ recoveryActionId: recoveryAction.id,+ recoveryOwner: recoveryAction.ownerAgentId && recoveryOwner+ ? { id: recoveryOwner.id, name: recoveryOwner.name }+ : null,+ sourceRun: input.latestRun+ ? {+ id: input.latestRun.id,+ agentId: input.latestRun.agentId,+ status: input.latestRun.status,+ errorCode: input.latestRun.errorCode,+ errorSummary: input.latestRun.error ? redactSensitiveText(input.latestRun.error) : null,+ }+ : null,+ });const shouldPostEscalationComment =recoveryAction.attemptCount === 1 ||@@ -3421,19 +3427,10 @@ export function recoveryService(db: Db, deps: { enqueueWakeup: RecoveryWakeup })metadata: notice.metadata,});} else {- await issuesSvc.addComment(input.issue.id, `${input.comment ?? ""}${recoveryLine}`, {}, {+ await issuesSvc.addComment(input.issue.id, escalationNotice.body, {}, {authorType: "system",- presentation: compactRecoveryPresentation(- `Recovery: ${recoveryCauseTitle(recoveryCause)} — moved to blocked ` +- `(owner: ${recoveryOwner?.name ?? "board"})`,- ),- metadata: recoveryNoticeMetadata({- cause: recoveryCause,- latestRun: input.latestRun,- recoveryActionId: recoveryAction.id,- previousStatus: input.previousStatus,- recoveryOwner,- }),+ presentation: escalationNotice.presentation,+ metadata: escalationNotice.metadata,});}}@@ -3907,7 +3904,7 @@ export function recoveryService(db: Db, deps: { enqueueWakeup: RecoveryWakeup })issue,previousStatus: "in_review",latestRun: participantLatestRun,- comment: buildExecutionReviewParticipantUnavailableComment(participantLatestRun),+ notice: buildExecutionReviewParticipantUnavailableNoticeSeed(),recoveryCause: EXECUTION_REVIEW_PARTICIPANT_RECOVERY_REASON,recoveryOwnerAgentId: participantAgentId,});@@ -3974,7 +3971,7 @@ export function recoveryService(db: Db, deps: { enqueueWakeup: RecoveryWakeup })issue,previousStatus: "in_review",latestRun: participantLatestRun,- comment: buildExecutionReviewParticipantUnavailableComment(participantLatestRun),+ notice: buildExecutionReviewParticipantUnavailableNoticeSeed(),recoveryCause: EXECUTION_REVIEW_PARTICIPANT_RECOVERY_REASON,recoveryOwnerAgentId: participantAgentId,});@@ -3992,7 +3989,7 @@ export function recoveryService(db: Db, deps: { enqueueWakeup: RecoveryWakeup })issue,previousStatus: "in_review",latestRun: participantLatestRun,- comment: buildExecutionReviewParticipantRecoveryComment(participantLatestRun),+ notice: buildExecutionReviewParticipantRecoveryNoticeSeed(),recoveryCause: EXECUTION_REVIEW_PARTICIPANT_RECOVERY_REASON,recoveryOwnerAgentId: participantAgentId,});@@ -4069,15 +4066,18 @@ export function recoveryService(db: Db, deps: { enqueueWakeup: RecoveryWakeup })}if (didAutomaticRecoveryFail(latestRun, "assignment_recovery")) {- const failureSummary = summarizeRunFailureForIssueComment(latestRun);const updated = await escalateStrandedAssignedIssue({issue,previousStatus: "todo",latestRun,- comment:- "Paperclip automatically retried dispatch for this assigned `todo` issue after a lost wake/run, " +- `but it still has no live execution path.${failureSummary ?? ""} ` +- "Moving it to `blocked` so it is visible for intervention.",+ notice: {+ body:+ "Paperclip automatically retried dispatch for this assigned `todo` issue after a lost wake/run, " ++ "but it still has no live execution path. " ++ "Moving it to `blocked` so it is visible for intervention.",+ title: "No live execution path",+ tone: "danger",+ },});if (updated) {result.escalated += 1;@@ -4210,15 +4210,18 @@ export function recoveryService(db: Db, deps: { enqueueWakeup: RecoveryWakeup })}if (classification.kind === "non_retryable") {- const failureSummary = summarizeRunFailureForIssueComment(latestRun);const updated = await escalateStrandedAssignedIssue({issue,previousStatus: "in_progress",latestRun,- comment:- "Paperclip detected a non-retryable failure on this issue's continuation run " +- `(\`${classification.errorCode}\`). Skipping automatic retries and moving it to \`blocked\` ` +- `so it is visible for intervention.${failureSummary ?? ""}`,+ notice: {+ body:+ "Paperclip detected a non-retryable failure on this issue's continuation run " ++ `(\`${classification.errorCode}\`). Skipping automatic retries and moving it to \`blocked\` ` ++ "so it is visible for intervention.",+ title: "Continuation failed",+ tone: "danger",+ },});if (updated) {result.escalated += 1;@@ -4237,19 +4240,19 @@ export function recoveryService(db: Db, deps: { enqueueWakeup: RecoveryWakeup })classification.errorCode,);if (consecutive >= classification.maxAttempts) {- const failureSummary = summarizeRunFailureForIssueComment(latestRun);const attemptCopy = consecutive <= 1 ? "" : ` (${consecutive}× attempts)`;- const causeCopy = classification.errorCode- ? ` Latest cause: \`${classification.errorCode}\`.`- : "";const updated = await escalateStrandedAssignedIssue({issue,previousStatus: "in_progress",latestRun,- comment:- "Paperclip automatically retried continuation for this assigned `in_progress` issue after its live " +- `execution disappeared, but it still has no live execution path${attemptCopy}.${causeCopy}${failureSummary ?? ""} ` +- "Moving it to `blocked` so it is visible for intervention.",+ notice: {+ body:+ "Paperclip automatically retried continuation for this assigned `in_progress` issue after its live " ++ `execution disappeared, but it still has no live execution path${attemptCopy}. ` ++ "Moving it to `blocked` so it is visible for intervention.",+ title: "No live execution path",+ tone: "danger",+ },});if (updated) {result.escalated += 1;diff --git a/server/src/services/recovery/stranded-notice.test.ts b/server/src/services/recovery/stranded-notice.test.tsnew file mode 100644index 0000000000..3fff23b5fc--- /dev/null+++ b/server/src/services/recovery/stranded-notice.test.ts@@ -0,0 +1,176 @@+import { describe, expect, it } from "vitest";+import { noticeMetadataReferencesRecoveryAction } from "./successful-run-handoff.js";+import {+ DEFAULT_STRANDED_RECOVERY_NOTICE_BODY,+ buildConfigurationIncompleteRecoveryNoticeSeed,+ buildExecutionReviewParticipantRecoveryNoticeSeed,+ buildExecutionReviewParticipantUnavailableNoticeSeed,+ buildImmediateExecutionPathRecoveryNoticeSeed,+ buildStrandedRecoveryEscalationNotice,+ buildWorkspaceValidationRecoveryNoticeSeed,+} from "./stranded-notice.js";++function allRows(metadata: { sections: Array<{ rows: unknown[] }> }) {+ return metadata.sections.flatMap((section) => section.rows) as Array<Record<string, unknown>>;+}++describe("stranded recovery notice seeds", () => {+ it.each([+ ["todo dispatch", buildImmediateExecutionPathRecoveryNoticeSeed({ status: "todo" }), "No live execution path"],+ ["in_progress continuation", buildImmediateExecutionPathRecoveryNoticeSeed({ status: "in_progress" }), "No live execution path"],+ ["workspace validation", buildWorkspaceValidationRecoveryNoticeSeed(), "Workspace validation failed"],+ ["configuration incomplete", buildConfigurationIncompleteRecoveryNoticeSeed(), "Configuration incomplete"],+ ["review participant recovery", buildExecutionReviewParticipantRecoveryNoticeSeed(), "Review recovery stalled"],+ ["review participant unavailable", buildExecutionReviewParticipantUnavailableNoticeSeed(), "Review recovery stalled"],+ ])("%s seed has a short body plus title and tone", (_label, seed, expectedTitle) => {+ expect(seed.title).toBe(expectedTitle);+ expect(seed.tone).toBe("danger");+ expect(seed.body.length).toBeGreaterThan(0);+ // Failure details now live in metadata rows, never inline in the body.+ expect(seed.body).not.toContain("Latest retry failure");+ expect(seed.body).not.toContain("Recovery action:");+ });++ it("distinguishes todo dispatch from in_progress continuation copy", () => {+ expect(buildImmediateExecutionPathRecoveryNoticeSeed({ status: "todo" }).body).toContain("retried dispatch");+ expect(buildImmediateExecutionPathRecoveryNoticeSeed({ status: "in_progress" }).body).toContain(+ "retried continuation",+ );+ });+});++describe("buildStrandedRecoveryEscalationNotice", () => {+ const actionId = "6a2f8e64-6f5e-4b58-b7fd-111111111111";+ const owner = { id: "9b1c2d3e-4f50-4a61-8b72-222222222222", name: "CTO" };+ const sourceRun = {+ id: "0c1d2e3f-4a5b-4c6d-8e7f-333333333333",+ agentId: "4d5e6f70-8a9b-4c1d-8e2f-444444444444",+ status: "failed",+ errorCode: "workspace_validation_failed",+ errorSummary: "Expected project worktree but resolved the agent fallback directory.",+ };++ it("emits system_notice presentation and the required metadata rows", () => {+ const seed = buildWorkspaceValidationRecoveryNoticeSeed();+ const notice = buildStrandedRecoveryEscalationNotice({+ seed,+ recoveryActionId: actionId,+ recoveryOwner: owner,+ sourceRun,+ });++ expect(notice.body).toBe(seed.body);+ expect(notice.presentation).toMatchObject({+ kind: "system_notice",+ tone: "danger",+ title: "Workspace validation failed",+ });+ expect(notice.metadata.version).toBe(1);+ expect(notice.metadata.sourceRunId).toBe(sourceRun.id);++ const rows = allRows(notice.metadata);+ expect(rows).toContainEqual({ type: "key_value", label: "Recovery action", value: actionId });+ expect(rows).toContainEqual({ type: "agent_link", label: "Recovery owner", agentId: owner.id, name: owner.name });+ expect(rows).toContainEqual({+ type: "run_link",+ label: "Source run",+ runId: sourceRun.id,+ agentId: sourceRun.agentId,+ title: "failed",+ });+ expect(rows).toContainEqual({+ type: "key_value",+ label: "Failure code",+ value: "workspace_validation_failed",+ });+ expect(rows).toContainEqual({+ type: "key_value",+ label: "Failure summary",+ value: sourceRun.errorSummary,+ });+ expect(rows.some((row) => row.label === "Next action")).toBe(true);+ });++ it("records board escalation when there is no invokable recovery owner", () => {+ const notice = buildStrandedRecoveryEscalationNotice({+ seed: buildConfigurationIncompleteRecoveryNoticeSeed(),+ recoveryActionId: actionId,+ recoveryOwner: null,+ sourceRun,+ });++ const ownerRow = allRows(notice.metadata).find((row) => row.label === "Recovery owner");+ expect(ownerRow?.type).toBe("key_value");+ expect(String(ownerRow?.value)).toContain("Board escalation");+ });++ it("derives title from the recovery cause and body from the plain-comment fallback", () => {+ const notice = buildStrandedRecoveryEscalationNotice({+ fallbackBody: "Legacy plain comment body.",+ recoveryCause: "configuration_incomplete",+ recoveryActionId: actionId,+ recoveryOwner: owner,+ sourceRun: null,+ });++ expect(notice.body).toBe("Legacy plain comment body.");+ expect(notice.presentation.title).toBe("Configuration incomplete");+ expect(notice.metadata.sourceRunId).toBeNull();+ expect(notice.metadata.sections).toHaveLength(1);+ });++ it("falls back to the default body and title when no seed or comment is given", () => {+ const notice = buildStrandedRecoveryEscalationNotice({+ recoveryActionId: actionId,+ recoveryOwner: null,+ sourceRun: null,+ });++ expect(notice.body).toBe(DEFAULT_STRANDED_RECOVERY_NOTICE_BODY);+ expect(notice.presentation.title).toBe("Automatic recovery blocked");+ });++ it("omits the failure code row when the source run has no error code", () => {+ const notice = buildStrandedRecoveryEscalationNotice({+ seed: buildImmediateExecutionPathRecoveryNoticeSeed({ status: "in_progress" }),+ recoveryActionId: actionId,+ recoveryOwner: owner,+ sourceRun: {+ id: sourceRun.id,+ agentId: sourceRun.agentId,+ status: "cancelled",+ errorCode: null,+ errorSummary: null,+ },+ });++ const rows = allRows(notice.metadata);+ expect(rows).toContainEqual({+ type: "run_link",+ label: "Source run",+ runId: sourceRun.id,+ agentId: sourceRun.agentId,+ title: "cancelled",+ });+ expect(rows.some((row) => row.label === "Failure code")).toBe(false);+ expect(rows.some((row) => row.label === "Failure summary")).toBe(false);+ });++ it("is matched by the metadata-based escalation dedupe matcher", () => {+ const notice = buildStrandedRecoveryEscalationNotice({+ seed: buildImmediateExecutionPathRecoveryNoticeSeed({ status: "todo" }),+ recoveryActionId: actionId,+ recoveryOwner: owner,+ sourceRun,+ });++ // The escalation dedupe in recovery/service.ts no longer relies on the+ // `Recovery action: \`id\`` body marker for new comments; the metadata+ // matcher must recognize every notice this builder produces.+ expect(notice.body).not.toContain(actionId);+ expect(noticeMetadataReferencesRecoveryAction(notice.metadata, actionId)).toBe(true);+ expect(+ noticeMetadataReferencesRecoveryAction(notice.metadata, "1f2e3d4c-5b6a-4798-8899-444444444444"),+ ).toBe(false);+ });+});diff --git a/server/src/services/recovery/stranded-notice.ts b/server/src/services/recovery/stranded-notice.tsnew file mode 100644index 0000000000..7705ba328f--- /dev/null+++ b/server/src/services/recovery/stranded-notice.ts@@ -0,0 +1,158 @@+import type { IssueCommentMetadata, IssueCommentPresentation } from "@paperclipai/shared";+import {+ agentLinkRow,+ keyValueRow,+ runLinkRow,+ systemNoticePresentation,+ type NoticeMetadataRow,+ type NoticeMetadataSection,+} from "./notice-format.js";++// Short human-readable body plus the presentation header for one recovery+// family. The escalation path merges in the metadata rows only it knows+// (recovery action, owner, source run) via buildStrandedRecoveryEscalationNotice.+export type StrandedRecoveryNoticeSeed = {+ body: string;+ title: string;+ tone: IssueCommentPresentation["tone"];+};++export type StrandedRecoveryEscalationNotice = {+ body: string;+ presentation: IssueCommentPresentation;+ metadata: IssueCommentMetadata;+};++export const DEFAULT_STRANDED_RECOVERY_NOTICE_BODY =+ "Paperclip could not restore a live execution path for this issue automatically. " ++ "Moving it to `blocked` so it is visible for intervention.";++const DEFAULT_STRANDED_RECOVERY_NOTICE_TITLE = "Automatic recovery blocked";++const STRANDED_RECOVERY_NOTICE_TITLES_BY_CAUSE: Record<string, string> = {+ workspace_validation_failed: "Workspace validation failed",+ configuration_incomplete: "Configuration incomplete",+ execution_review_participant_recovery: "Review recovery stalled",+};++export function buildImmediateExecutionPathRecoveryNoticeSeed(input: {+ status: "todo" | "in_progress";+}): StrandedRecoveryNoticeSeed {+ const retryDescription = input.status === "todo"+ ? "Paperclip automatically retried dispatch for this assigned `todo` issue during terminal run recovery"+ : "Paperclip automatically retried continuation for this assigned `in_progress` issue during terminal run recovery";+ return {+ body:+ `${retryDescription}, but it still has no live execution path. ` ++ "Moving it to `blocked` so it is visible for intervention.",+ title: "No live execution path",+ tone: "danger",+ };+}++export function buildWorkspaceValidationRecoveryNoticeSeed(): StrandedRecoveryNoticeSeed {+ return {+ body:+ "Paperclip stopped before launching the local adapter because the issue workspace failed validation. " ++ "Moving it to `blocked` so the workspace link, cwd, or git checkout can be repaired before resuming.",+ title: "Workspace validation failed",+ tone: "danger",+ };+}++export function buildConfigurationIncompleteRecoveryNoticeSeed(): StrandedRecoveryNoticeSeed {+ return {+ body:+ "Paperclip stopped before dispatching the adapter because required secret/env bindings are missing. " ++ "Moving it to `blocked` so an operator can bind the missing secret(s) before resuming.",+ title: "Configuration incomplete",+ tone: "danger",+ };+}++export function buildExecutionReviewParticipantRecoveryNoticeSeed(): StrandedRecoveryNoticeSeed {+ return {+ body:+ "Paperclip retried the pending execution-review participant once, but the review stage still has no " ++ "completed decision or live reviewer run. Moving it to `blocked` so the recovery owner can repair the " ++ "reviewer runtime, restore the review stage, or record an intentional manual resolution.",+ title: "Review recovery stalled",+ tone: "danger",+ };+}++export function buildExecutionReviewParticipantUnavailableNoticeSeed(): StrandedRecoveryNoticeSeed {+ return {+ body:+ "Paperclip cannot continue the pending execution-review participant because the participant is not " ++ "invokable and the review stage has no completed decision or live reviewer run. Moving it to `blocked` " ++ "so the recovery owner can repair the reviewer runtime, restore the review stage, or record an " ++ "intentional manual resolution.",+ title: "Review recovery stalled",+ tone: "danger",+ };+}++// Escalation dedupe matches the `Recovery action` key_value row via+// noticeMetadataReferencesRecoveryAction, so this builder must always emit+// that row with the raw action id.+export function buildStrandedRecoveryEscalationNotice(input: {+ seed?: StrandedRecoveryNoticeSeed | null;+ fallbackBody?: string | null;+ recoveryCause?: string | null;+ recoveryActionId: string;+ recoveryOwner: { id: string; name: string | null } | null | undefined;+ sourceRun: {+ id: string;+ agentId?: string | null;+ status: string;+ errorCode?: string | null;+ errorSummary?: string | null;+ } | null | undefined;+}): StrandedRecoveryEscalationNotice {+ const fallbackBody = input.fallbackBody?.trim();+ const body = input.seed?.body ?? (fallbackBody || DEFAULT_STRANDED_RECOVERY_NOTICE_BODY);+ const title = input.seed?.title ??+ STRANDED_RECOVERY_NOTICE_TITLES_BY_CAUSE[input.recoveryCause ?? ""] ??+ DEFAULT_STRANDED_RECOVERY_NOTICE_TITLE;++ const recoveryRows: NoticeMetadataRow[] = [+ keyValueRow("Recovery action", input.recoveryActionId),+ input.recoveryOwner+ ? agentLinkRow("Recovery owner", input.recoveryOwner)+ : keyValueRow(+ "Recovery owner",+ "Board escalation - Paperclip could not find an invokable manager, creator, or executive owner with budget available",+ ),+ keyValueRow(+ "Next action",+ input.recoveryOwner+ ? "The recovery owner should either restore a live execution path or record the manual resolution on the source issue"+ : "A board operator should assign an invokable recovery owner, fix the agent/runtime state, or record an intentional manual resolution",+ ),+ ];++ const runRows: NoticeMetadataRow[] = [];+ if (input.sourceRun) {+ runRows.push(runLinkRow("Source run", input.sourceRun));+ const failureCode = input.sourceRun.errorCode?.trim();+ if (failureCode) runRows.push(keyValueRow("Failure code", failureCode));+ const failureSummary = input.sourceRun.errorSummary?.trim();+ if (failureSummary) runRows.push(keyValueRow("Failure summary", failureSummary));+ }++ const sections: NoticeMetadataSection[] = [+ { title: "Recovery", rows: recoveryRows },+ ...(runRows.length > 0 ? [{ title: "Run evidence", rows: runRows }] : []),+ ];++ return {+ body,+ presentation: systemNoticePresentation({ tone: input.seed?.tone ?? "danger", title }),+ metadata: {+ version: 1,+ sourceRunId: input.sourceRun?.id ?? null,+ sections,+ },+ };+}diff --git a/server/src/services/recovery/successful-run-handoff.test.ts b/server/src/services/recovery/successful-run-handoff.test.tsindex 46a36c6396..5aa042b041 100644--- a/server/src/services/recovery/successful-run-handoff.test.ts+++ b/server/src/services/recovery/successful-run-handoff.test.ts@@ -389,6 +389,7 @@ describe("successful run handoff decision", () => {run: {id: "22222222-2222-4222-8222-222222222222",status: "succeeded",+ agentId: "33333333-3333-4333-8333-333333333333",} as any,agent: {id: "33333333-3333-4333-8333-333333333333",@@ -417,7 +418,11 @@ describe("successful run handoff decision", () => {expect.objectContaining({title: "Run evidence",rows: expect.arrayContaining([- expect.objectContaining({ type: "run_link", runId: "22222222-2222-4222-8222-222222222222" }),+ expect.objectContaining({+ type: "run_link",+ runId: "22222222-2222-4222-8222-222222222222",+ agentId: "33333333-3333-4333-8333-333333333333",+ }),expect.objectContaining({ type: "key_value", label: "Normalized cause", value: SUCCESSFUL_RUN_MISSING_STATE_REASON }),expect.objectContaining({ type: "key_value", label: "Detected progress" }),]),@@ -433,8 +438,16 @@ describe("successful run handoff decision", () => {title: "Finish backend handoff",status: "in_progress",} as any,- sourceRun: { id: "22222222-2222-4222-8222-222222222222", status: "succeeded" } as any,- correctiveRun: { id: "44444444-4444-4444-8444-444444444444", status: "failed" } as any,+ sourceRun: {+ id: "22222222-2222-4222-8222-222222222222",+ status: "succeeded",+ agentId: "33333333-3333-4333-8333-333333333333",+ } as any,+ correctiveRun: {+ id: "44444444-4444-4444-8444-444444444444",+ status: "failed",+ agentId: "66666666-6666-4666-8666-666666666666",+ } as any,sourceAssignee: { id: "33333333-3333-4333-8333-333333333333", name: "CodexCoder" } as any,recoveryIssue: {id: "55555555-5555-4555-8555-555555555555",@@ -467,7 +480,16 @@ describe("successful run handoff decision", () => {expect.objectContaining({title: "Run evidence",rows: expect.arrayContaining([- expect.objectContaining({ type: "run_link", label: "Source run" }),+ expect.objectContaining({+ type: "run_link",+ label: "Source run",+ agentId: "33333333-3333-4333-8333-333333333333",+ }),+ expect.objectContaining({+ type: "run_link",+ label: "Corrective handoff run",+ agentId: "66666666-6666-4666-8666-666666666666",+ }),expect.objectContaining({ type: "run_link", label: "Corrective handoff run" }),expect.objectContaining({ type: "key_value", label: "Missing disposition", value: "clear_next_step" }),]),diff --git a/server/src/services/recovery/successful-run-handoff.ts b/server/src/services/recovery/successful-run-handoff.tsindex d415ccde20..e6a3533586 100644--- a/server/src/services/recovery/successful-run-handoff.ts+++ b/server/src/services/recovery/successful-run-handoff.ts@@ -3,6 +3,13 @@ import type { Db } from "@paperclipai/db";import { agentWakeupRequests, agents, heartbeatRuns, issues } from "@paperclipai/db";import type { IssueCommentMetadata, IssueCommentPresentation, RunLivenessState } from "@paperclipai/shared";import { withRecoveryModelProfileHint } from "./model-profile-hint.js";+import {+ agentLinkRow,+ issueLinkRow,+ keyValueRow,+ runLinkRow,+ systemNoticePresentation,+} from "./notice-format.js";export const FINISH_SUCCESSFUL_RUN_HANDOFF_REASON = "finish_successful_run_handoff";export const SUCCESSFUL_RUN_MISSING_STATE_REASON = "successful_run_missing_state";@@ -57,7 +64,7 @@ type IssueRow = Pick<>;type AgentRow = Pick<typeof agents.$inferSelect, "id" | "companyId" | "status">;type NoticeIssue = Pick<typeof issues.$inferSelect, "id" | "identifier" | "title" | "status">;-type NoticeRun = Pick<typeof heartbeatRuns.$inferSelect, "id" | "status">;+type NoticeRun = Pick<typeof heartbeatRuns.$inferSelect, "id" | "status" | "agentId">;type NoticeAgent = Pick<typeof agents.$inferSelect, "id" | "name">;type NullableNoticeAgent = NoticeAgent | null | undefined;type NullableNoticeIssue = NoticeIssue | null | undefined;@@ -115,58 +122,6 @@ export function isSuccessfulRunHandoffValidPathSkip(return decision.kind === "skip" && SUCCESSFUL_RUN_HANDOFF_VALID_PATH_SKIP_REASONS.has(decision.reason);}-function metadataText(value: unknown, fallback = "unknown") {- const text = typeof value === "string" ? value.trim() : value == null ? "" : String(value).trim();- const resolved = text.length > 0 ? text : fallback;- return resolved.length > 2000 ? `${resolved.slice(0, 1997)}...` : resolved;-}--function keyValueRow(label: string, value: unknown): IssueCommentMetadata["sections"][number]["rows"][number] {- return { type: "key_value", label, value: metadataText(value) };-}--function issueLinkRow(- label: string,- issue: NullableNoticeIssue,-): IssueCommentMetadata["sections"][number]["rows"][number] {- if (!issue) return keyValueRow(label, "unknown");- return {- type: "issue_link",- label,- issueId: issue.id,- identifier: issue.identifier,- title: issue.title,- };-}--function runLinkRow(- label: string,- run: NullableNoticeRun,-): IssueCommentMetadata["sections"][number]["rows"][number] {- if (!run) return keyValueRow(label, "unknown");- return { type: "run_link", label, runId: run.id, title: run.status };-}--function agentLinkRow(- label: string,- agent: NullableNoticeAgent,-): IssueCommentMetadata["sections"][number]["rows"][number] {- if (!agent) return keyValueRow(label, "unknown");- return { type: "agent_link", label, agentId: agent.id, name: agent.name };-}--function systemNoticePresentation(input: {- tone: IssueCommentPresentation["tone"];- title: string;-}): IssueCommentPresentation {- return {- kind: "system_notice",- tone: input.tone,- title: input.title,- detailsDefaultOpen: false,- };-}-export function isSuccessfulRunHandoffRequiredNoticeBody(body: string) {const trimmed = body.trim();return trimmed === SUCCESSFUL_RUN_HANDOFF_REQUIRED_NOTICE_BODY ||diff --git a/ui/src/components/SystemNotice.tsx b/ui/src/components/SystemNotice.tsxindex 343c397694..291e380d26 100644--- a/ui/src/components/SystemNotice.tsx+++ b/ui/src/components/SystemNotice.tsx@@ -206,6 +206,38 @@ function MetadataRow({ row, tone }: { row: SystemNoticeMetadataRow; tone: ToneTo);}+/**+ * The structured metadata rows shared by the boxed SystemNotice details panel+ * and the chat shell's expandable system row (TaskChatSystemNotice, PAP-443).+ */+export function SystemNoticeMetadataSections({+ sections,+ tone = "neutral",+}: {+ sections: SystemNoticeMetadataSection[];+ tone?: SystemNoticeTone;+}) {+ const tokens = TONE_TOKENS[tone];+ return (+ <div className="divide-y divide-border/50 px-1 py-1">+ {sections.map((section, sectionIdx) => (+ <div key={sectionIdx} className="py-1.5 first:pt-2 last:pb-2">+ {section.title ? (+ <div className="px-3 pb-1 pt-0.5 text-(length:--text-nano) font-semibold uppercase tracking-(--tracking-caps) text-muted-foreground">+ {section.title}+ </div>+ ) : null}+ <div>+ {section.rows.map((row, rowIdx) => (+ <MetadataRow key={rowIdx} row={row} tone={tokens} />+ ))}+ </div>+ </div>+ ))}+ </div>+ );+}+export function SystemNotice({tone = "neutral",label,@@ -312,22 +344,7 @@ export function SystemNotice({tokens.divider,)}>- <div className="divide-y divide-border/50 px-1 py-1">- {metadata!.map((section, sectionIdx) => (- <div key={sectionIdx} className="py-1.5 first:pt-2 last:pb-2">- {section.title ? (- <div className="px-3 pb-1 pt-0.5 text-(length:--text-nano) font-semibold uppercase tracking-(--tracking-caps) text-muted-foreground">- {section.title}- </div>- ) : null}- <div>- {section.rows.map((row, rowIdx) => (- <MetadataRow key={rowIdx} row={row} tone={tokens} />- ))}- </div>- </div>- ))}- </div>+ <SystemNoticeMetadataSections sections={metadata!} tone={tone} /></div>) : null}</section>diff --git a/ui/src/components/task-chat/TaskChatBubble.tsx b/ui/src/components/task-chat/TaskChatBubble.tsxindex 528fbc985c..89584df89f 100644--- a/ui/src/components/task-chat/TaskChatBubble.tsx+++ b/ui/src/components/task-chat/TaskChatBubble.tsx@@ -14,6 +14,7 @@ import {AttachmentTrigger,} from "@/components/ui/attachment";import { extractAttachmentRefs, fileKindForName } from "./task-chat-attachments";+import { TaskChatSystemNotice } from "./TaskChatSystemNotice";import type { TaskChatMessageItem } from "./task-chat-model";interface TaskChatBubbleProps {@@ -58,11 +59,8 @@ export function TaskChatBubble({ item, attachedTurn, actions }: TaskChatBubblePr}if (item.author === "system") {- return (- <div className="tc-enter-bubble flex justify-center py-1">- <p className="max-w-(--pct-85) text-center text-xs text-muted-foreground">{item.text}</p>- </div>- );+ // Collapsed humanized one-liner, expandable to the full detail (PAP-443).+ return <TaskChatSystemNotice item={item} />;}const isHuman = item.author === "human";diff --git a/ui/src/components/task-chat/TaskChatSystemNotice.test.tsx b/ui/src/components/task-chat/TaskChatSystemNotice.test.tsxnew file mode 100644index 0000000000..6d34d7b45e--- /dev/null+++ b/ui/src/components/task-chat/TaskChatSystemNotice.test.tsx@@ -0,0 +1,123 @@+// @vitest-environment jsdom++import { flushSync } from "react-dom";+import { createRoot, type Root } from "react-dom/client";+import { afterEach, beforeEach, describe, expect, it } from "vitest";+import { ThemeProvider } from "@/context/ThemeContext";+import { TaskChatSystemNotice } from "./TaskChatSystemNotice";+import type { TaskChatMessageItem } from "./task-chat-model";++describe("TaskChatSystemNotice (PAP-443)", () => {+ let container: HTMLDivElement;+ let root: Root | null = null;++ beforeEach(() => {+ container = document.createElement("div");+ document.body.appendChild(container);+ root = createRoot(container);+ });++ afterEach(() => {+ flushSync(() => root?.unmount());+ root = null;+ container.remove();+ });++ const recoveryBody =+ "Paperclip stopped before dispatching the adapter because required secret/env bindings are missing. " ++ "Latest retry failure: `configuration_incomplete`. Moving it to `blocked` with a source-scoped recovery action.";++ function renderNotice(overrides: Partial<TaskChatMessageItem> = {}) {+ const item: TaskChatMessageItem = {+ id: "sys-1",+ kind: "message",+ author: "system",+ text: recoveryBody,+ createdAtIso: new Date(Date.now() - 5 * 60_000).toISOString(),+ ...overrides,+ };+ flushSync(() =>+ root!.render(+ <ThemeProvider>+ <TaskChatSystemNotice item={item} />+ </ThemeProvider>,+ ),+ );+ }++ function toggleButton() {+ return container.querySelector<HTMLButtonElement>(+ '[data-testid="task-chat-system-notice"] button',+ )!;+ }++ it("collapses to a humanized one-liner with relative time and hides the raw body", () => {+ renderNotice();+ const button = toggleButton();+ expect(button.getAttribute("aria-expanded")).toBe("false");+ expect(button.textContent).toContain("Task paused — a secret/config binding is missing");+ expect(button.textContent).toContain("5m ago");+ expect(container.textContent).not.toContain("source-scoped recovery action");+ expect(+ container.querySelector('[data-testid="task-chat-system-notice-details"]'),+ ).toBeNull();+ });++ it("expands on click to the full markdown body and metadata sections", () => {+ renderNotice({+ metadata: {+ version: 1,+ sections: [+ { title: "Failure", rows: [{ type: "code", label: "Code", code: "configuration_incomplete" }] },+ ],+ },+ });+ flushSync(() => toggleButton().click());++ expect(toggleButton().getAttribute("aria-expanded")).toBe("true");+ const details = container.querySelector('[data-testid="task-chat-system-notice-details"]');+ expect(details).not.toBeNull();+ expect(details!.textContent).toContain("required secret/env bindings are missing");+ expect(details!.textContent).toContain("Failure");+ expect(details!.textContent).toContain("configuration_incomplete");++ // Collapses back — presentation-only fold, nothing lost.+ flushSync(() => toggleButton().click());+ expect(+ container.querySelector('[data-testid="task-chat-system-notice-details"]'),+ ).toBeNull();+ });++ it("links source-run metadata when the comment carries its run agent", () => {+ renderNotice({+ metadata: {+ version: 1,+ sections: [+ {+ title: "Run",+ rows: [{ type: "run_link", label: "Source run", runId: "run-1", agentId: "agent-1", title: "failed" }],+ },+ ],+ },+ });+ flushSync(() => toggleButton().click());++ expect(container.querySelector('a[href="/agents/agent-1/runs/run-1"]')).not.toBeNull();+ });++ it("respects presentation.detailsDefaultOpen", () => {+ renderNotice({+ presentation: {+ kind: "system_notice",+ tone: "warning",+ title: "Run recovery",+ detailsDefaultOpen: true,+ },+ });+ expect(toggleButton().getAttribute("aria-expanded")).toBe("true");+ expect(toggleButton().textContent).toContain("Run recovery");+ expect(+ container.querySelector('[data-testid="task-chat-system-notice-details"]'),+ ).not.toBeNull();+ });+});diff --git a/ui/src/components/task-chat/TaskChatSystemNotice.tsx b/ui/src/components/task-chat/TaskChatSystemNotice.tsxnew file mode 100644index 0000000000..da9c40bd1b--- /dev/null+++ b/ui/src/components/task-chat/TaskChatSystemNotice.tsx@@ -0,0 +1,100 @@+import { useId, useState } from "react";+import {+ ChevronDown,+ CircleCheck,+ Info,+ OctagonAlert,+ TriangleAlert,+ type LucideIcon,+} from "lucide-react";+import { cn } from "@/lib/utils";+import { MarkdownBody } from "@/components/MarkdownBody";+import {+ SystemNoticeMetadataSections,+ type SystemNoticeTone,+} from "@/components/SystemNotice";+import { humanizeSystemNotice } from "@/lib/system-notice-humanizer";+import { mapCommentMetadataToSystemNoticeSections } from "@/lib/system-notice-comment";+import { timeAgo } from "@/lib/timeAgo";+import type { TaskChatMessageItem } from "./task-chat-model";++const TONE_ICON: Record<SystemNoticeTone, LucideIcon> = {+ neutral: Info,+ info: Info,+ success: CircleCheck,+ warning: TriangleAlert,+ danger: OctagonAlert,+};++const TONE_ICON_CLASS: Record<SystemNoticeTone, string> = {+ neutral: "text-muted-foreground",+ info: "text-(--status-task-icon-in_progress)",+ success: "text-(--status-task-icon-done)",+ warning: "text-(--status-task-icon-todo)",+ danger: "text-(--status-task-icon-blocked)",+};++/**+ * System comment row in the chat shell (PAP-443 / PAP-442 Phase 1): collapsed,+ * it reads as a quiet centered one-liner in TaskChatMarker's register — tone+ * icon + humanized plain-English title + relative time + chevron — instead of+ * a large gray paragraph of raw text. Expanding reveals the full+ * markdown-rendered body plus any structured metadata sections; nothing is+ * suppressed, only folded.+ */+export function TaskChatSystemNotice({ item }: { item: TaskChatMessageItem }) {+ const [open, setOpen] = useState(Boolean(item.presentation?.detailsDefaultOpen));+ const detailsId = useId();+ const { title, tone, detail } = humanizeSystemNotice({+ body: item.text,+ presentation: item.presentation,+ });+ const sections = mapCommentMetadataToSystemNoticeSections(item.metadata, {+ runAgentId: item.runAgentId,+ });+ const ToneIcon = TONE_ICON[tone];+ const relative = item.createdAtIso ? timeAgo(item.createdAtIso) : undefined;++ return (+ <div className="tc-enter-bubble flex flex-col items-center py-1" data-testid="task-chat-system-notice">+ <button+ type="button"+ onClick={() => setOpen((v) => !v)}+ aria-expanded={open}+ aria-controls={detailsId}+ className={cn(+ "flex max-w-(--pct-85) items-center gap-1.5 rounded-md px-2 py-0.5 text-xs text-muted-foreground",+ "hover:bg-muted/50 hover:text-foreground",+ "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50",+ )}+ >+ <ToneIcon className={cn("h-3.5 w-3.5 shrink-0", TONE_ICON_CLASS[tone])} aria-hidden />+ <span className="truncate font-medium">{title}</span>+ {detail ? <span className="hidden truncate sm:inline">· {detail}</span> : null}+ {relative ? <span className="shrink-0 text-muted-foreground/70">· {relative}</span> : null}+ <ChevronDown+ className={cn("tc-notice-chevron h-3.5 w-3.5 shrink-0 transition-transform", open && "rotate-180")}+ aria-hidden+ />+ </button>+ {open ? (+ <div+ id={detailsId}+ data-testid="task-chat-system-notice-details"+ className="mt-1 w-full max-w-(--pct-85) overflow-hidden rounded-lg border border-border bg-muted/25 text-left text-sm dark:bg-muted/15"+ >+ <div className="px-3 py-2.5 text-foreground/90">+ <MarkdownBody softBreaks linkIssueReferences>+ {item.text}+ </MarkdownBody>+ </div>+ {sections.length > 0 ? (+ <div className="border-t border-border/70 bg-background/50 dark:bg-background/30">+ <SystemNoticeMetadataSections sections={sections} tone={tone} />+ </div>+ ) : null}+ </div>+ ) : null}+ </div>+ );+}diff --git a/ui/src/components/task-chat/task-chat-adapter.test.ts b/ui/src/components/task-chat/task-chat-adapter.test.tsindex 3af1b5b707..27e0ad3b53 100644--- a/ui/src/components/task-chat/task-chat-adapter.test.ts+++ b/ui/src/components/task-chat/task-chat-adapter.test.ts@@ -22,4 +22,67 @@ describe("commentsToTaskChatItems", () => {expect(item.author).toBe("agent");expect(item.interstitial).toBeUndefined();});++ it("classifies system comments as system even with a derivable run→agent linkage (PAP-443)", () => {+ const comments = [+ {+ id: "c-sys",+ body: "Paperclip automatically retried dispatch, but it still has no live execution path.",+ authorType: "system",+ authorAgentId: null,+ derivedAuthorAgentId: "agent-1",+ createdAt: "2026-08-07T09:00:00.000Z",+ } as unknown as IssueChatComment,+ ];+ const items = commentsToTaskChatItems(comments);+ expect(items).toHaveLength(1);+ const item = items[0];+ if (item.kind !== "message") throw new Error("expected message item");+ expect(item.author).toBe("system");+ });++ it("carries presentation, metadata, and the raw timestamp for system comments", () => {+ const presentation = {+ kind: "system_notice",+ tone: "warning",+ title: "Run recovery",+ detailsDefaultOpen: true,+ };+ const metadata = {+ version: 1,+ sections: [{ rows: [{ type: "text", label: "Reason", text: "quota" }] }],+ };+ const comments = [+ {+ id: "c-sys",+ body: "Recovery notice.",+ authorType: "system",+ presentation,+ metadata,+ runAgentId: "agent-1",+ createdAt: new Date("2026-08-07T09:00:00.000Z"),+ } as unknown as IssueChatComment,+ {+ id: "c-agent",+ body: "Agent reply.",+ authorType: "agent",+ authorAgentId: "agent-1",+ presentation: null,+ metadata,+ createdAt: "2026-08-07T09:01:00.000Z",+ } as unknown as IssueChatComment,+ ];+ const items = commentsToTaskChatItems(comments);+ const [sys, agent] = items;+ if (sys.kind !== "message" || agent.kind !== "message") throw new Error("expected messages");+ expect(sys.presentation).toEqual(presentation);+ expect(sys.metadata).toEqual(metadata);+ expect(sys.runAgentId).toBe("agent-1");+ expect(sys.createdAtIso).toBe("2026-08-07T09:00:00.000Z");+ // Non-system authors keep the item lean — no structured notice fields.+ expect(agent.presentation).toBeUndefined();+ expect(agent.metadata).toBeUndefined();+ expect(agent.runAgentId).toBeUndefined();+ expect(agent.createdAtIso).toBeUndefined();+ });});diff --git a/ui/src/components/task-chat/task-chat-adapter.ts b/ui/src/components/task-chat/task-chat-adapter.tsindex 552b5099cc..db3edebbf7 100644--- a/ui/src/components/task-chat/task-chat-adapter.ts+++ b/ui/src/components/task-chat/task-chat-adapter.ts@@ -34,10 +34,13 @@ function effectiveAgentId(comment: IssueChatComment): string | null {}function authorKind(comment: IssueChatComment): TaskChatAuthorKind {+ // System authorship wins over any derivable run→agent linkage (PAP-443):+ // recovery notices carry a derivedAuthorAgentId but must not render as+ // agent bubbles.+ if (comment.authorType === "system") return "system";if (effectiveAgentId(comment)) return "agent";if (comment.authorType === "user") return "human";- if (comment.authorType === "agent") return "agent";- return "system";+ return "agent";}/** Shared bubble-footer time format ("2:34 PM") — also used by the description bubble (PAP-375). */@@ -79,6 +82,12 @@ export function commentsToTaskChatItems(: comment.clientStatus === "pending"? "pending": undefined;+ const createdAtIso =+ comment.createdAt instanceof Date+ ? comment.createdAt.toISOString()+ : comment.createdAt+ ? String(comment.createdAt)+ : undefined;items.push({id: comment.id || comment.clientId || `${comment.createdAt}`,kind: "message",@@ -90,6 +99,12 @@ export function commentsToTaskChatItems(agentIcon,onBehalfOfUserName,modeLabel: kind === "agent" ? ctx.agentModeLabelFor?.(comment) : undefined,+ // System notices carry their structured hints through to the render+ // layer (PAP-443); other authors keep the item lean.+ presentation: kind === "system" ? comment.presentation ?? null : undefined,+ metadata: kind === "system" ? comment.metadata ?? null : undefined,+ runAgentId: kind === "system" ? comment.runAgentId ?? null : undefined,+ createdAtIso: kind === "system" ? createdAtIso : undefined,});}return items;diff --git a/ui/src/components/task-chat/task-chat-model.ts b/ui/src/components/task-chat/task-chat-model.tsindex bbf42b6459..e465c8044c 100644--- a/ui/src/components/task-chat/task-chat-model.ts+++ b/ui/src/components/task-chat/task-chat-model.ts@@ -12,6 +12,7 @@* inventory for the mapping. No timing/motion values live here — those are* CSS motion tokens in ui/src/index.css.*/+import type { IssueCommentMetadata, IssueCommentPresentation } from "@paperclipai/shared";import type { IssueThreadInteraction } from "@/lib/issue-thread-interactions";/** Who authored a thread row — the primary legibility signal. */@@ -100,6 +101,17 @@ export interface TaskChatMessageItem {* Expanding still nests the tool history beneath the bubble.*/attachedTurn?: TaskChatTurnItem;+ /**+ * Structured system-notice fields (PAP-443), carried only for+ * author === "system": the comment's server-authored presentation hints and+ * metadata sections drive the collapsed one-line row + expandable detail.+ */+ presentation?: IssueCommentPresentation | null;+ metadata?: IssueCommentMetadata | null;+ /** Agent that owns the source run, used to build run-detail links in metadata rows. */+ runAgentId?: string | null;+ /** Raw comment timestamp (ISO) — the collapsed system row shows relative time. */+ createdAtIso?: string;}/** Collapsed chain-of-thought (ACP agent_thought_chunk). */diff --git a/ui/src/index.css b/ui/src/index.cssindex 3b4b143346..b68251e0c7 100644--- a/ui/src/index.css+++ b/ui/src/index.css@@ -581,6 +581,7 @@.tc-enter-tool { animation: tc-fade-rise var(--motion-tool-enter) var(--motion-ease-out-expo) both; }.tc-enter-status { animation: tc-status-in var(--motion-status-enter) var(--motion-ease-out-expo) both; }.tc-enter-cot-line { animation: tc-fade-rise var(--motion-duration-fast) var(--motion-ease-standard) both; }+.tc-notice-chevron { transition-duration: var(--motion-duration-fast); }.tc-reveal-diff { animation: tc-fade-in var(--motion-diff-reveal) var(--motion-ease-standard) both; }.tc-approval { animation: tc-approval-pulse var(--motion-approval-pulse) var(--motion-ease-standard) infinite; }.tc-cursor { animation: tc-cursor-blink var(--motion-streaming-cursor-blink) step-end infinite; }diff --git a/ui/src/lib/system-notice-comment.ts b/ui/src/lib/system-notice-comment.tsindex c06e21e78f..6d3bd46336 100644--- a/ui/src/lib/system-notice-comment.ts+++ b/ui/src/lib/system-notice-comment.ts@@ -57,7 +57,7 @@ function mapMetadataRow(};}case "run_link": {- const runAgentId = ctx.runAgentId ?? null;+ const runAgentId = row.agentId ?? ctx.runAgentId ?? null;const href = runAgentId ? `/agents/${runAgentId}/runs/${row.runId}` : undefined;return {kind: "run",diff --git a/ui/src/lib/system-notice-humanizer.test.ts b/ui/src/lib/system-notice-humanizer.test.tsnew file mode 100644index 0000000000..88d8787dce--- /dev/null+++ b/ui/src/lib/system-notice-humanizer.test.ts@@ -0,0 +1,100 @@+import { describe, expect, it } from "vitest";+import { humanizeSystemNotice } from "./system-notice-humanizer";++describe("humanizeSystemNotice", () => {+ it("uses presentation title and tone when present", () => {+ const result = humanizeSystemNotice({+ body: "Paperclip automatically retried dispatch but it still has no live execution path.",+ presentation: {+ kind: "system_notice",+ tone: "danger",+ title: "Run recovery exhausted",+ detailsDefaultOpen: false,+ },+ });+ expect(result).toEqual({ title: "Run recovery exhausted", tone: "danger" });+ });++ it("classifies claude_auth_required retry failures", () => {+ const result = humanizeSystemNotice({+ body:+ "Paperclip automatically retried continuation for this assigned `in_progress` issue during terminal run " ++ "recovery, but it still has no live execution path. Latest retry failure: `claude_auth_required` - adapter " ++ "handshake failed. Moving it to `blocked` so it is visible for intervention.",+ });+ expect(result.title).toBe("Task paused — Claude needs re-authentication");+ expect(result.tone).toBe("warning");+ });++ it("classifies configuration_incomplete failures", () => {+ const result = humanizeSystemNotice({+ body:+ "Paperclip stopped before dispatching the adapter because required secret/env bindings are missing. " ++ "Latest retry failure: `configuration_incomplete`. Moving it to `blocked` with a source-scoped recovery action.",+ });+ expect(result.title).toBe("Task paused — a secret/config binding is missing");+ expect(result.tone).toBe("warning");+ });++ it("classifies missing secret bindings even without a failure code", () => {+ const result = humanizeSystemNotice({+ body:+ "Paperclip stopped before dispatching the adapter because required secret/env bindings are missing. " ++ "Moving it to `blocked` so an operator can bind the missing secret(s).",+ });+ expect(result.title).toBe("Task paused — a secret/config binding is missing");+ });++ it("classifies workspace validation failures", () => {+ const result = humanizeSystemNotice({+ body:+ "Paperclip stopped before launching the local adapter because the issue workspace failed validation. " ++ "This prevents git-sensitive adapters from running in an unrelated fallback cwd.",+ });+ expect(result.title).toBe("Task paused — workspace problem");+ expect(result.tone).toBe("warning");+ });++ it("names the recovery owner from the markdown link for generic no-live-execution-path notices", () => {+ const result = humanizeSystemNotice({+ body:+ "Paperclip automatically retried dispatch for this assigned `todo` issue during terminal run recovery, " ++ "but it still has no live execution path. Moving it to `blocked` so it is visible for intervention.\n\n" ++ "- Recovery action: `ra-123`\n" ++ "- Recovery owner: [Dana the Manager](/PAP/agents/agent-9)\n" ++ "- Next action: the recovery owner should restore a live execution path.",+ });+ expect(result.title).toBe("Task paused — waiting on Dana the Manager");+ expect(result.tone).toBe("warning");+ });++ it("still humanizes no-live-execution-path notices without an owner link", () => {+ const result = humanizeSystemNotice({+ body:+ "Paperclip automatically retried dispatch, but it still has no live execution path. " ++ "Moving it to `blocked` so it is visible for intervention.",+ });+ expect(result.title).toBe("Task paused — waiting on a recovery owner");+ });++ it("falls back to System update plus a truncated first sentence", () => {+ const longFirstSentence =+ "The heartbeat scheduler observed an unusual condition while reconciling this issue's run ledger against the " ++ "control plane state and recorded the discrepancy for later review.";+ const result = humanizeSystemNotice({ body: `${longFirstSentence} Second sentence here.` });+ expect(result.title).toBe("System update");+ expect(result.tone).toBe("neutral");+ expect(result.detail).toBeDefined();+ expect(result.detail!.length).toBeLessThanOrEqual(80);+ expect(result.detail!.endsWith("…")).toBe(true);+ });++ it("keeps a short first sentence untruncated in the fallback detail", () => {+ const result = humanizeSystemNotice({ body: "Run rescheduled. More context follows." });+ expect(result).toEqual({+ title: "System update",+ tone: "neutral",+ detail: "Run rescheduled.",+ });+ });+});diff --git a/ui/src/lib/system-notice-humanizer.ts b/ui/src/lib/system-notice-humanizer.tsnew file mode 100644index 0000000000..6b2177eada--- /dev/null+++ b/ui/src/lib/system-notice-humanizer.ts@@ -0,0 +1,92 @@+import type { IssueCommentPresentation } from "@paperclipai/shared";+import type { SystemNoticeTone } from "../components/SystemNotice";++/**+ * Pure classifier for system comments in the chat shell (PAP-443 / PAP-442+ * Phase 1): derive a short plain-English one-liner + tone for the collapsed+ * row. Server-authored presentation hints win when present; otherwise the+ * known recovery families are pattern-matched from the comment body. Nothing+ * here suppresses data — the full body stays available behind the expand.+ */+export interface HumanizedSystemNotice {+ title: string;+ tone: SystemNoticeTone;+ /** Optional muted trailing snippet for the generic fallback row. */+ detail?: string;+}++const FALLBACK_TITLE = "System update";+const DETAIL_MAX_CHARS = 80;++/** Failure code the recovery comments embed as "Latest retry failure: `code`". */+function retryFailureCode(body: string): string | null {+ const match = body.match(/Latest retry failure: `([^`]+)`/);+ return match ? match[1] : null;+}++/** Owner display name from a "Recovery owner: [Name](/…/agents/…)" markdown link. */+function recoveryOwnerName(body: string): string | null {+ const match = body.match(/Recovery owner: \[([^\]]+)\]\(/);+ const name = match?.[1]?.trim();+ return name && name.length > 0 ? name : null;+}++function firstSentence(body: string): string | undefined {+ const firstLine = body+ .split("\n")+ .map((line) => line.trim())+ .find((line) => line.length > 0);+ if (!firstLine) return undefined;+ const sentenceEnd = firstLine.search(/[.!?](\s|$)/);+ const sentence = sentenceEnd >= 0 ? firstLine.slice(0, sentenceEnd + 1) : firstLine;+ if (sentence.length <= DETAIL_MAX_CHARS) return sentence;+ return `${sentence.slice(0, DETAIL_MAX_CHARS - 1).trimEnd()}…`;+}++export function humanizeSystemNotice(input: {+ body: string;+ presentation?: IssueCommentPresentation | null;+}): HumanizedSystemNotice {+ const presentationTitle = input.presentation?.title?.trim();+ const presentationTone = input.presentation?.tone;+ if (presentationTitle) {+ return { title: presentationTitle, tone: presentationTone ?? "neutral" };+ }++ const body = input.body ?? "";+ const code = retryFailureCode(body);++ if (code === "claude_auth_required") {+ return {+ title: "Task paused — Claude needs re-authentication",+ tone: presentationTone ?? "warning",+ };+ }+ if (code === "configuration_incomplete" || body.includes("secret/env bindings are missing")) {+ return {+ title: "Task paused — a secret/config binding is missing",+ tone: presentationTone ?? "warning",+ };+ }+ if (code === "workspace_validation_failed" || body.includes("workspace failed validation")) {+ return {+ title: "Task paused — workspace problem",+ tone: presentationTone ?? "warning",+ };+ }+ if (body.includes("no live execution path")) {+ const owner = recoveryOwnerName(body);+ return {+ title: owner+ ? `Task paused — waiting on ${owner}`+ : "Task paused — waiting on a recovery owner",+ tone: presentationTone ?? "warning",+ };+ }++ return {+ title: FALLBACK_TITLE,+ tone: presentationTone ?? "neutral",+ detail: firstSentence(body),+ };+}