[codex] harden heartbeat run summaries and recovery context (#3742)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies
> - Heartbeat runs are the control-plane record of what agents did, why
they woke up, and what operators should see next
> - Run lists, stranded issue comments, and live log polling all depend
on compact but accurate heartbeat summaries
> - The current branch had a focused backend slice that improves how run
result JSON is summarized, how stale process recovery comments are
written, and how live log polling resolves the active run
> - This pull request isolates that heartbeat/runtime reliability work
from the unrelated UI and dev-tooling changes
> - The benefit is more reliable issue context and cheaper run lookups
without dragging unrelated board UI changes into the same review

## What Changed

- Include the latest run failure in stranded issue comments during
orphaned process recovery.
- Bound heartbeat `result_json` payloads for list responses while
preserving the raw stored payloads.
- Narrow heartbeat log endpoint lookups so issue polling resolves the
relevant active run with less unnecessary scanning.
- Add focused tests for heartbeat list summaries, live run polling,
orphaned process recovery, and the run context/result summary helpers.

## Verification

- `pnpm vitest run
server/src/__tests__/heartbeat-context-summary.test.ts
server/src/__tests__/heartbeat-list.test.ts
server/src/__tests__/agent-live-run-routes.test.ts
server/src/__tests__/heartbeat-process-recovery.test.ts`

## Risks

- The main risk is accidentally hiding a field that some client still
expects from summarized `result_json`, or over-constraining the live log
lookup path for edge-case run routing.
- Recovery comments now surface the latest failure more aggressively, so
wording changes may affect downstream expectations if anyone parses
those comments too strictly.

## Model Used

- OpenAI Codex, GPT-5-based coding agent in the Codex CLI environment.
Exact backend model deployment ID was not exposed in-session.
Tool-assisted editing and shell execution were used.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

server/src/__tests__/agent-live-run-routes.test.ts

@@ -9,6 +9,8 @@ const mockAgentService = vi.hoisted(() => ({
 const mockHeartbeatService = vi.hoisted(() => ({
   getRunIssueSummary: vi.fn(),
   getActiveRunIssueSummaryForAgent: vi.fn(),
+  getRunLogAccess: vi.fn(),
+  readLog: vi.fn(),
 }));
 
 const mockIssueService = vi.hoisted(() => ({
@@ -100,6 +102,19 @@ describe("agent live run routes", () => {
       issueId: "issue-1",
     });
     mockHeartbeatService.getActiveRunIssueSummaryForAgent.mockResolvedValue(null);
+    mockHeartbeatService.getRunLogAccess.mockResolvedValue({
+      id: "run-1",
+      companyId: "company-1",
+      logStore: "local_file",
+      logRef: "logs/run-1.ndjson",
+    });
+    mockHeartbeatService.readLog.mockResolvedValue({
+      runId: "run-1",
+      store: "local_file",
+      logRef: "logs/run-1.ndjson",
+      content: "chunk",
+      nextOffset: 5,
+    });
   });
 
   it("returns a compact active run payload for issue polling", async () => {
@@ -163,4 +178,27 @@ describe("agent live run routes", () => {
       adapterType: "codex_local",
     });
   });
+
+  it("uses narrow run log metadata lookups for log polling", async () => {
+    const res = await request(await createApp()).get("/api/heartbeat-runs/run-1/log?offset=12&limitBytes=64");
+
+    expect(res.status, JSON.stringify(res.body)).toBe(200);
+    expect(mockHeartbeatService.getRunLogAccess).toHaveBeenCalledWith("run-1");
+    expect(mockHeartbeatService.readLog).toHaveBeenCalledWith({
+      id: "run-1",
+      companyId: "company-1",
+      logStore: "local_file",
+      logRef: "logs/run-1.ndjson",
+    }, {
+      offset: 12,
+      limitBytes: 64,
+    });
+    expect(res.body).toEqual({
+      runId: "run-1",
+      store: "local_file",
+      logRef: "logs/run-1.ndjson",
+      content: "chunk",
+      nextOffset: 5,
+    });
+  });
 });

server/src/__tests__/heartbeat-context-summary.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import {
+  summarizeHeartbeatRunContextSnapshot,
+  summarizeHeartbeatRunListResultJson,
+} from "../services/heartbeat.js";
+
+describe("summarizeHeartbeatRunContextSnapshot", () => {
+  it("keeps only the small retry/linking fields needed by the client", () => {
+    const summarized = summarizeHeartbeatRunContextSnapshot({
+      issueId: "issue-1",
+      taskId: "task-1",
+      taskKey: "PAP-1",
+      commentId: "comment-1",
+      wakeCommentId: "comment-2",
+      wakeReason: "retry_failed_run",
+      wakeSource: "on_demand",
+      wakeTriggerDetail: "manual",
+      paperclipWake: {
+        comments: [
+          {
+            body: "x".repeat(50_000),
+          },
+        ],
+      },
+      executionStage: {
+        summary: "large nested object that should not be sent back in run lists",
+      },
+    });
+
+    expect(summarized).toEqual({
+      issueId: "issue-1",
+      taskId: "task-1",
+      taskKey: "PAP-1",
+      commentId: "comment-1",
+      wakeCommentId: "comment-2",
+      wakeReason: "retry_failed_run",
+      wakeSource: "on_demand",
+      wakeTriggerDetail: "manual",
+    });
+  });
+
+  it("returns null when no allowed fields are present", () => {
+    expect(
+      summarizeHeartbeatRunContextSnapshot({
+        paperclipWake: { comments: [{ body: "hello" }] },
+      }),
+    ).toBeNull();
+  });
+});
+
+describe("summarizeHeartbeatRunListResultJson", () => {
+  it("keeps only summary fields and parses numeric cost aliases", () => {
+    expect(
+      summarizeHeartbeatRunListResultJson({
+        summary: "Completed the task",
+        result: "Updated three files",
+        message: "",
+        error: null,
+        totalCostUsd: "1.25",
+        costUsd: "0.75",
+        costUsdCamel: "0.5",
+      }),
+    ).toEqual({
+      summary: "Completed the task",
+      result: "Updated three files",
+      total_cost_usd: 1.25,
+      cost_usd: 0.75,
+      costUsd: 0.5,
+    });
+  });
+
+  it("returns null when projected fields are empty", () => {
+    expect(
+      summarizeHeartbeatRunListResultJson({
+        summary: "",
+        result: null,
+        message: undefined,
+        error: "   ",
+        totalCostUsd: "abc",
+      }),
+    ).toBeNull();
+  });
+});

server/src/__tests__/heartbeat-list.test.ts

@@ -88,4 +88,105 @@ describeEmbeddedPostgres("heartbeat list", () => {
       }
     }
   });
+
+  it("returns small result json payloads unchanged from getRun", async () => {
+    const companyId = randomUUID();
+    const agentId = randomUUID();
+    const runId = randomUUID();
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+
+    await db.insert(agents).values({
+      id: agentId,
+      companyId,
+      name: "CodexCoder",
+      role: "engineer",
+      status: "running",
+      adapterType: "codex_local",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: {},
+    });
+
+    await db.insert(heartbeatRuns).values({
+      id: runId,
+      companyId,
+      agentId,
+      invocationSource: "assignment",
+      status: "succeeded",
+      resultJson: {
+        summary: "done",
+        structured: { ok: true },
+      },
+    });
+
+    const run = await heartbeatService(db).getRun(runId);
+
+    expect(run?.resultJson).toEqual({
+      summary: "done",
+      structured: { ok: true },
+    });
+  });
+
+  it("bounds oversized legacy result json payloads on getRun", async () => {
+    const companyId = randomUUID();
+    const agentId = randomUUID();
+    const runId = randomUUID();
+    const oversizedStdout = Array.from({ length: 8_000 }, (_, index) =>
+      `${index.toString(16).padStart(4, "0")}-${randomUUID()}`,
+    ).join("|");
+    const oversizedNestedPayload = Array.from({ length: 6_000 }, (_, index) =>
+      `${index.toString(16).padStart(4, "0")}:${randomUUID()}`,
+    ).join("|");
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+
+    await db.insert(agents).values({
+      id: agentId,
+      companyId,
+      name: "CodexCoder",
+      role: "engineer",
+      status: "running",
+      adapterType: "codex_local",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: {},
+    });
+
+    await db.insert(heartbeatRuns).values({
+      id: runId,
+      companyId,
+      agentId,
+      invocationSource: "assignment",
+      status: "succeeded",
+      resultJson: {
+        summary: "completed",
+        stdout: oversizedStdout,
+        nestedHuge: { payload: oversizedNestedPayload },
+      },
+    });
+
+    const run = await heartbeatService(db).getRun(runId);
+    const result = run?.resultJson as Record<string, unknown> | null;
+
+    expect(result).toMatchObject({
+      summary: "completed",
+      truncated: true,
+      truncationReason: "oversized_result_json",
+      stdoutTruncated: true,
+    });
+    expect(typeof result?.stdout).toBe("string");
+    expect((result?.stdout as string).length).toBeLessThan(oversizedStdout.length);
+    expect(result).not.toHaveProperty("nestedHuge");
+  });
 });

server/src/__tests__/heartbeat-process-recovery.test.ts

@@ -598,6 +598,7 @@ 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: `process_lost` - run failed before issue advanced.");
   });
 
   it("re-enqueues continuation for stranded in-progress work with no active run", async () => {
@@ -646,6 +647,7 @@ 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: `process_lost` - run failed before issue advanced.");
   });
 
   it("does not reconcile user-assigned work through the agent stranded-work recovery path", async () => {