fix(agent): recover or flag pending attachments that fail to reach the cloud agent (#3039)

## Problem

Closes GROW-99

Pasting a prompt into PostHog Code auto-converts it to a `pasted-text.txt` attachment. On **cloud** tasks the file is uploaded as a run artifact and the sandbox agent reads it from `.posthog/attachments/…`. Intermittently the agent instead received the bare task description `Attached files: pasted-text.txt` as plain text — no file, no inline content — and replied that it *"can't find the file… no text was included inline"*, unable to do the task. (The task title also stayed **Untitled**.)

## Root cause

In `agent-server.ts → sendInitialTaskMessage`, when `getPendingUserPrompt()` returns `null` (no pending message **and** no *resolvable* artifacts) it falls back to `task.description`. For a pasted-text-only task that description is just the `Attached files: …` summary, so the agent is handed a prompt naming a file it was never given. The artifact fails to resolve when the run's `artifacts` manifest doesn't yet contain the just-uploaded `pending_user_artifact_ids` — most likely a transient manifest lag at run start.

## Fix

Hardened `getPendingUserPrompt`:

1. **Best-effort recovery** — refetch the run manifest once when a declared attachment isn't listed yet, so a transient lag doesn't drop the attachment (the pasted text then reaches the agent).
2. **Safe degraded prompt** — if an attachment still can't be hydrated, append an explicit *"the attachment didn't come through, ask the user to paste it directly or re-send"* notice instead of the misleading bare description. Skill bundles (installed silently) are excluded from the count.
3. Adds a `warn("Pending user attachments could not be loaded", …)` log with resolved/expected counts, so a *consistent* failure (artifact genuinely missing server-side) is obvious in run logs.

The misleading `task.description` fallback in `sendInitialTaskMessage` is now bypassed for this case, and the resume paths benefit too since they share `getPendingUserPrompt`.

## Tests

New `AgentServer pending user attachments` suite in `agent-server.test.ts`:

- missing attachment (refetch also empty) → explicit notice appended, not `null`
- refetch recovers the artifact → `resource_link` block, no notice
- no pending artifacts → `null`, and no refetch

Typecheck and Biome are clean.

> The file's existing **HTTP-mode** tests run a `git commit` in `createTestRepo`, which is blocked in the signed-commits sandbox this was authored in — so I couldn't run them locally. The new tests are deliberately self-contained (no git/HTTP) and pass; CI covers the rest.

## Notes

- This was seen as a **one-off**, so the change hardens the degraded path and adds recovery rather than chasing a root cause I couldn't confirm. If it reproduces every time, the new warn log points at the artifact genuinely not landing in `taskRun.artifacts` server-side.
- The earlier title fix (#2850) is unrelated — it only touched name generation, not how the file reaches the agent.

Closes GROW-99

Author: fercgomes

packages/agent/src/server/agent-server.test.ts

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import { readFile } from "node:fs/promises";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { ContentBlock } from "@agentclientprotocol/sdk";
 import { zipSync } from "fflate";
@@ -2376,3 +2377,179 @@ describe("AgentServer HTTP Mode", () => {
     });
   });
 });
+
+// Exercises getPendingUserPrompt directly (no HTTP server / git repo) so we can
+// assert how the initial cloud prompt degrades when an attached file can't be
+// hydrated — the case behind a pasted-text task reaching the agent as a bare
+// "Attached files: …" description with no readable file.
+describe("AgentServer pending user attachments", () => {
+  interface PendingPromptInternals {
+    posthogAPI: {
+      getTaskRun: (taskId: string, runId: string) => Promise<TaskRun>;
+      downloadArtifact: (
+        taskId: string,
+        runId: string,
+        storagePath: string,
+      ) => Promise<ArrayBuffer | null>;
+    };
+    getPendingUserPrompt(
+      taskRun: TaskRun | null,
+    ): Promise<{ prompt: ContentBlock[] } | null>;
+  }
+
+  let tempDir: string;
+  let server: AgentServer | undefined;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), "agent-pending-"));
+  });
+
+  afterEach(async () => {
+    await server?.stop();
+    server = undefined;
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  const buildInternals = (): PendingPromptInternals => {
+    server = new AgentServer({
+      port: getNextTestPort(),
+      jwtPublicKey: TEST_PUBLIC_KEY,
+      repositoryPath: tempDir,
+      apiUrl: "http://localhost:8000",
+      apiKey: "test-api-key",
+      projectId: 1,
+      mode: "interactive",
+      taskId: "test-task-id",
+      runId: "test-run-id",
+    });
+    return server as unknown as PendingPromptInternals;
+  };
+
+  it("appends an explicit notice when a pending attachment never reaches the manifest", async () => {
+    const internals = buildInternals();
+    // Refetch still can't see the attachment (truly absent, not just lagging).
+    const getTaskRun = vi.fn(async () =>
+      createTaskRun({
+        state: { pending_user_artifact_ids: ["missing-attachment"] },
+        artifacts: [],
+      }),
+    );
+    internals.posthogAPI.getTaskRun = getTaskRun;
+
+    const result = await internals.getPendingUserPrompt(
+      createTaskRun({
+        state: { pending_user_artifact_ids: ["missing-attachment"] },
+        artifacts: [],
+      }),
+    );
+
+    // Refetched once to recover a lagging manifest, then — still missing —
+    // surfaced an explicit notice instead of returning null (which would let the
+    // caller fall back to the misleading "Attached files: …" description).
+    expect(getTaskRun).toHaveBeenCalledTimes(1);
+    expect(result).not.toBeNull();
+    expect(result?.prompt).toHaveLength(1);
+    const [block] = result?.prompt ?? [];
+    expect(block?.type).toBe("text");
+    expect((block as { text: string }).text).toContain("could not be loaded");
+  });
+
+  it("recovers a pending attachment from a refetched run manifest", async () => {
+    const internals = buildInternals();
+    internals.posthogAPI.getTaskRun = vi.fn(async () =>
+      createTaskRun({
+        state: { pending_user_artifact_ids: ["att-1"] },
+        artifacts: [
+          {
+            id: "att-1",
+            name: "pasted-text.txt",
+            type: "user_attachment",
+            storage_path: "tasks/artifacts/pasted-text.txt",
+            content_type: "text/plain",
+          },
+        ],
+      }),
+    );
+    const downloadArtifact = vi.fn(async () =>
+      exactArrayBuffer(new TextEncoder().encode("pasted body")),
+    );
+    internals.posthogAPI.downloadArtifact = downloadArtifact;
+
+    const result = await internals.getPendingUserPrompt(
+      createTaskRun({
+        state: { pending_user_artifact_ids: ["att-1"] },
+        artifacts: [],
+      }),
+    );
+
+    expect(downloadArtifact).toHaveBeenCalledWith(
+      "task-1",
+      "run-1",
+      "tasks/artifacts/pasted-text.txt",
+    );
+    const resourceLinks = result?.prompt.filter(
+      (block) => block.type === "resource_link",
+    );
+    expect(resourceLinks).toHaveLength(1);
+    // No "couldn't load" notice once the attachment is recovered.
+    const hasNotice = result?.prompt.some(
+      (block) =>
+        block.type === "text" &&
+        (block as { text: string }).text.includes("could not be loaded"),
+    );
+    expect(hasNotice).toBe(false);
+  });
+
+  it("returns null without refetching when no pending artifacts were declared", async () => {
+    const internals = buildInternals();
+    const getTaskRun = vi.fn();
+    internals.posthogAPI.getTaskRun = getTaskRun;
+
+    const result = await internals.getPendingUserPrompt(
+      createTaskRun({ state: {}, artifacts: [] }),
+    );
+
+    expect(result).toBeNull();
+    expect(getTaskRun).not.toHaveBeenCalled();
+  });
+
+  it("warns once (not twice) about a missing artifact across the speculative and post-refetch resolves", async () => {
+    const internals = buildInternals();
+    // A non-empty manifest that never lists the requested id — so getArtifactsById
+    // reaches its per-id "missing" warning on both the pre- and post-refetch calls
+    // (an empty manifest would short-circuit before warning at all).
+    const decoyManifest = [
+      {
+        id: "unrelated-artifact",
+        name: "other.txt",
+        type: "user_attachment" as const,
+      },
+    ];
+    internals.posthogAPI.getTaskRun = vi.fn(async () =>
+      createTaskRun({
+        state: { pending_user_artifact_ids: ["missing-attachment"] },
+        artifacts: decoyManifest,
+      }),
+    );
+    const loggerHost = internals as unknown as {
+      logger: { warn: (...args: unknown[]) => void };
+    };
+    const warnSpy = vi
+      .spyOn(loggerHost.logger, "warn")
+      .mockImplementation(() => {});
+
+    await internals.getPendingUserPrompt(
+      createTaskRun({
+        state: { pending_user_artifact_ids: ["missing-attachment"] },
+        artifacts: decoyManifest,
+      }),
+    );
+
+    // The speculative pre-refetch resolve stays quiet (a miss there is expected);
+    // only the post-refetch resolve emits the per-id "missing" warning.
+    const manifestWarnings = warnSpy.mock.calls.filter(
+      ([message]) => message === "Pending artifact missing from run manifest",
+    );
+    expect(manifestWarnings).toHaveLength(1);
+  });
+});

packages/agent/src/server/agent-server.ts

@@ -277,6 +277,22 @@ function getTaskRunStateString(
   return typeof value === "string" ? value : null;
 }
 
+// Prompt block we hand the agent when the user attached files but we could not
+// load any of them into the session (missing from the run manifest, no storage
+// path, etc.). Without this the caller falls back to the bare task description —
+// e.g. "Attached files: pasted-text.txt" — which points the agent at files it
+// was never given and makes it hunt the filesystem in vain. Be explicit instead.
+function buildMissingAttachmentNotice(count: number): string {
+  const subject = count === 1 ? "A file" : `${count} files`;
+  const pronoun = count === 1 ? "it" : "they";
+  const noun = count === 1 ? "attachment" : "attachments";
+  return (
+    `${subject} the user attached to this message could not be loaded into the session, ` +
+    `so ${pronoun} are unavailable here. Do not guess at the contents. Tell the user the ` +
+    `${noun} didn't come through, and ask them to paste the text directly or send ${pronoun} again.`
+  );
+}
+
 export class AgentServer {
   private config: AgentServerConfig;
   private sessionReadyBootMs?: number;
@@ -1800,20 +1816,95 @@ export class AgentServer {
             typeof artifactId === "string" && artifactId.trim().length > 0,
         )
       : [];
+
+    // The run's artifact manifest can momentarily lag the pending-artifact ids
+    // when a run starts right after the attachments were uploaded. If we were
+    // asked for artifacts the manifest doesn't list yet, refetch the run once so
+    // a transient gap doesn't drop the attachment and send the agent the bare
+    // "Attached files: …" description instead of the file it was promised.
+    let manifest = taskRun.artifacts ?? [];
+    let resolvedArtifacts = this.getArtifactsById(manifest, artifactIds, {
+      warnOnMissing: false,
+    });
+    if (
+      artifactIds.length > 0 &&
+      resolvedArtifacts.length < artifactIds.length
+    ) {
+      const refreshed = await this.refetchRunArtifacts(taskRun);
+      if (refreshed) {
+        manifest = refreshed;
+        resolvedArtifacts = this.getArtifactsById(manifest, artifactIds);
+      }
+    }
+
     const prompt = await this.buildPromptFromContentAndArtifacts({
       content: typeof message === "string" ? message : undefined,
-      artifacts: this.getArtifactsById(taskRun.artifacts, artifactIds),
+      artifacts: resolvedArtifacts,
       taskId: taskRun.task,
       runId: taskRun.id,
     });
+
+    // Skill bundles are installed silently, so only non-skill attachments are
+    // expected to surface as content (hydrated into resource_link blocks). Ids
+    // the manifest still can't account for are treated as attachments, not
+    // skills — better to over-warn than to silently mislead. `message` here is
+    // plain text, so every resource_link block is a hydrated attachment.
+    const expectedAttachmentCount = artifactIds.filter((artifactId) => {
+      const known = manifest.find((artifact) => artifact.id === artifactId);
+      return known ? known.type !== "skill_bundle" : true;
+    }).length;
+    const hydratedAttachmentCount = prompt.prompt.filter(
+      (block) => block.type === "resource_link",
+    ).length;
+    const lostAttachmentCount =
+      expectedAttachmentCount - hydratedAttachmentCount;
+
+    if (lostAttachmentCount > 0) {
+      this.logger.warn("Pending user attachments could not be loaded", {
+        taskId: taskRun.task,
+        runId: taskRun.id,
+        requestedArtifactCount: artifactIds.length,
+        expectedAttachmentCount,
+        hydratedAttachmentCount,
+        lostAttachmentCount,
+      });
+      prompt.prompt.push({
+        type: "text",
+        text: buildMissingAttachmentNotice(lostAttachmentCount),
+      });
+    }
+
     this.logger.debug("Built pending user prompt", {
       hasMessage: typeof message === "string" && message.trim().length > 0,
       requestedArtifactCount: artifactIds.length,
+      hydratedAttachmentCount,
+      lostAttachmentCount,
       blockTypes: prompt.prompt.map((block) => block.type),
     });
     return prompt.prompt.length > 0 ? prompt : null;
   }
 
+  // Best-effort refetch of a run's artifact manifest. Returns null on any error
+  // so the caller can fall back to the manifest it already has.
+  private async refetchRunArtifacts(
+    taskRun: TaskRun,
+  ): Promise<TaskRunArtifact[] | null> {
+    try {
+      const refreshed = await this.posthogAPI.getTaskRun(
+        taskRun.task,
+        taskRun.id,
+      );
+      return refreshed.artifacts ?? null;
+    } catch (error) {
+      this.logger.debug("Failed to refetch run artifacts for pending prompt", {
+        taskId: taskRun.task,
+        runId: taskRun.id,
+        error,
+      });
+      return null;
+    }
+  }
+
   private getClearedPendingUserState(taskRun: TaskRun | null): string[] | null {
     const state =
       taskRun?.state && typeof taskRun.state === "object"
@@ -1886,6 +1977,10 @@ export class AgentServer {
   private getArtifactsById(
     artifacts: TaskRunArtifact[] | undefined,
     artifactIds: string[],
+    // The speculative pre-refetch resolve passes false: a miss there is expected
+    // (it's what triggers the refetch), so warning would be premature and would
+    // double up with the post-refetch warning for a genuinely missing artifact.
+    { warnOnMissing = true }: { warnOnMissing?: boolean } = {},
   ): TaskRunArtifact[] {
     if (!artifacts?.length || artifactIds.length === 0) {
       return [];
@@ -1903,9 +1998,11 @@ export class AgentServer {
     return artifactIds.flatMap((artifactId) => {
       const artifact = artifactsById.get(artifactId);
       if (!artifact) {
-        this.logger.warn("Pending artifact missing from run manifest", {
-          artifactId,
-        });
+        if (warnOnMissing) {
+          this.logger.warn("Pending artifact missing from run manifest", {
+            artifactId,
+          });
+        }
         return [];
       }