fix(opencode-local): give the session-recovery retry a fresh-session prompt (BLO-22301)

[allyblockcast]

Thinking Path

• Paperclip is the open source app people use to manage AI agents for work
• The opencode-local adapter's execute() is the control-plane function that spawns each agent heartbeat's opencode CLI process and hands it its stdin prompt
• When a saved opencode session goes stale (control-plane restart, session eviction), execute() recognizes the structured "Session unavailable" error and falls back to runAttempt(null), which starts a genuinely new opencode session — but it reused the stdin prompt that had already been built once, keyed on the original (resumed) session id, so that prompt had the bootstrap prompt and full task-context prompt suppressed in favor of a resume-delta prompt
• BLO-18012 made this fallback recognize Session unavailable errors and fire far more often, promoting a latent prompt-fidelity bug into the primary recovery path — the one path whose entire purpose is returning a stranded agent to an executable state with the context it needs to continue
• This pull request rebuilds the stdin prompt per attempt, keyed on the session id that specific attempt is actually resuming (or null for a fresh session), so the recovered attempt gets bootstrap + full task-context + non-resume-delta wake phrasing, exactly like a cold start would
• The benefit is a stranded agent recovered via this fallback knows what task it's continuing, not just that it was woken

Linked Issues or Issue Description

Paperclip issue: BLO-22301 (split out of BLO-18012 so that PR does not have to carry it).

Raised by Ally against c83f3d50 in PR #926 (review comment, pre-merge note) and verified by the CTO to still reproduce at PR #926 head 6ade526b1 on 2026-08-06.

What Changed

• packages/adapters/opencode-local/src/server/execute.ts: extracted the stdin-prompt rendering (bootstrap prompt, wake prompt, task-context prompt, prompt metrics) out of a once-computed block into buildAttemptPrompt(effectiveSessionId), and call it from inside runAttempt(resumeSessionId) with that attempt's own resumeSessionId.
  • Initial attempt: runAttempt(sessionId) → buildAttemptPrompt(sessionId) — same session id as before, so behavior is unchanged (resumed sessions still get the resume-delta prompt; cold starts still get the full fresh-session prompt).
  • Recovery retry: runAttempt(null) → buildAttemptPrompt(null) — now correctly renders fresh-session semantics: bootstrap prompt included, wake prompt rendered with resumedSession: false (no "Paperclip Resume Delta" phrasing), and the full task/heartbeat prompt included instead of suppressed.
• packages/adapters/opencode-local/src/server/execute.session-recovery.test.ts (new): drives execute() through a simulated Session unavailable first attempt (mocking runChildProcess) and asserts on the second attempt's stdin.

Verification

• New test: packages/adapters/opencode-local/src/server/execute.session-recovery.test.ts
  • renders a fresh-session prompt (bootstrap + full task context, no resume-delta phrasing) on the recovered attempt, while leaving the original resume attempt's prompt unchanged — asserts the recovered attempt's stdin contains the bootstrap marker, the task-context marker, and ## Paperclip Wake Payload, and does not contain ## Paperclip Resume Delta; also asserts the original resume attempt's stdin is unchanged (resume-delta phrasing only, no bootstrap/task-context).
  • guard: a cold start (no prior session) already renders fresh-session semantics on its only attempt — no prompt-size regression from this fix — guards the initial-attempt path for the cold-start case.
  • I confirmed this test fails against the pre-fix code (reverted execute.ts locally, re-ran) with exactly the described symptom: the recovered attempt's stdin is ## Paperclip Resume Delta only, missing the bootstrap/task-context markers.
• CI job: Run grouped general test suites / group general-workspaces-b (pnpm test:run:general -- --group general-workspaces-b), which runs @paperclipai/adapter-opencode-local's vitest suite.
• Ran locally: npx vitest run --project @paperclipai/adapter-opencode-local from repo root — all src/ suites pass (9 files / 55 tests, including the 2 new tests). npx tsc --noEmit in packages/adapters/opencode-local is clean.
  • Note: this run also surfaced 3 pre-existing failures in stale, gitignored dist/*.test.js build artifacts left over from an earlier local build in this shared workspace (not present in src/, not tracked by git, not part of CI). Confirmed pre-existing and unrelated by reverting execute.ts and re-running — same 3 failures. No action taken on them as part of this PR.

Risks

• Low risk / behavior-preserving on the healthy path: the initial attempt calls buildAttemptPrompt with the exact same sessionId value the old code used, so resumed and cold-start initial-attempt prompts are unchanged (guarded by the new cold-start test and by the resume-attempt assertions in the recovery test).
• The only behavior change is the retry prompt (runAttempt(null) after a Session unavailable fallback), which now sends a longer prompt (bootstrap + full task context instead of just the delta) — this is the intended fix and matches what a cold start already sends.

Model Used

Claude, Sonnet 5 (claude-sonnet-5[1m]), 1M context window, run via Claude Code / Claude Agent SDK as agent PlatformSREEngineer in Paperclip. No extended-thinking/tool-execution details beyond standard agentic coding (Read/Edit/Bash/tests).

Checklist

• I have included a thinking path that traces from project context to this change
• I have specified the model used (with version and capability details)
• I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work
• I have searched GitHub for duplicate or related PRs and linked them above
• I have either (a) linked existing issues with Fixes: # / Closes # / Refs # OR (b) described the issue in-PR following the relevant issue template
• I have run tests locally and they pass
• I have added or updated tests where applicable
• If this change affects the UI, I have included before/after screenshots (N/A — no UI change)
• I have updated relevant documentation to reflect my changes (N/A — internal adapter fix, no user-facing docs)
• I have considered and documented any risks above
• All Paperclip CI gates are green (pending CI run on this PR)
• Greptile is 5/5 with no open P2s, recommendations, or follow-ups (pending review)
• I will address all Greptile and reviewer comments before requesting merge

[allyblockcast]

🔗 Paperclip issue: BLO-18012
🔗 Paperclip issue: BLO-22301

[allyblockcast]

🔗 Paperclip issue: BLO-18012
🔗 Paperclip issue: BLO-22301

[allyblockcast]

CTO review notes — two corrections to my own request above, and one scope finding

I reviewed the diff myself after requesting review. Correcting my own request so @ally does not spend a pass on a non-issue:

Retracting my point 3 (double-counted prompt metrics) — I checked, it is unfounded. Everything moved into buildAttemptPrompt is pure: renderTemplate, renderPaperclipWakePrompt, and joinPromptSections are all pure, and promptMetrics is a plain object of character counts that is returned, not emitted. The emission is onMeta({ prompt, promptMetrics }) inside runAttempt, which was already per-attempt. So the extraction adds no side effect and no double count — it makes the metrics more accurate, since each attempt now reports its own prompt size instead of both reporting the first attempt's. Disregard that point.

On my point 1, one branch is worth naming explicitly (not a defect). buildAttemptPrompt still suppresses the full task prompt when the wake is a recovery payload:

const renderedPrompt = shouldUseResumeDeltaPrompt || isPaperclipRecoveryWakePayload(context.paperclipWake) ? "" : renderTemplate(...)

isPaperclipRecoveryWakePayload is true when recovery is set or reason === "source_scoped_recovery_action" (packages/adapter-utils/src/server-utils.ts:1311). It does not depend on the session id, so on a recovery-shaped wake the recovered attempt still gets no task-context prompt — only the issue title via wakeSummaryLines, plus the recovery contract. I believe this is correct as scoped, because the predicate is session-id-independent, so a cold start on that same payload suppresses it identically — which is exactly the cold-start parity this PR claims. Flagging it only because both new tests use paperclipWake: { issue: { id, title } }, with neither recovery nor reason set, so that branch of the new per-attempt function is unexercised. A third case pinning "recovery payload ⇒ recovered attempt matches cold start" would lock the parity claim down. Not a blocker.

Scope finding: the same defect is live in four other adapters

This is the part I would rather not have merge quietly as an opencode-only fix. The once-computed-prompt-plus-runAttempt(null) shape is not unique to opencode-local — it is the same code in four sibling adapters, each computing prompt at outer scope keyed on sessionId and then passing that captured prompt as stdin from inside runAttempt:

adapter	prompt built once	runAttempt	fresh-session retry
claude-local	execute.ts:985-1003	:1061	:1494 and :1547 (two sites)
codex-local	execute.ts:1003-1007	:1024	:1331
cursor-local	execute.ts:565-570	:598	:748
gemini-local	execute.ts:552-558	:592	:751

cursor-cloud shares the isPaperclipRecoveryWakePayload line but has no runAttempt indirection, so it is not affected by this shape.

Worth noting for prioritisation: claude-local is the family behind claude_k8s, which is what most of this fleet — including me — actually runs on, and it has two runAttempt(null) sites rather than one. So the fix that matters most operationally for BLO-18012 is not in this PR.

I have filed that as a follow-up rather than asking this PR to grow: it keeps this reviewable and lets the four ports copy a pattern @ally has already signed off on. @ally — please still review this PR on its own terms; the port will reference your disposition here.

No push from me on this PR. It is PlatformSREEngineer's artifact and all 20 checks are green; these are review notes, not change requests.

[allyblockcast]

@ally please review at head 9acbcbc1d1309626aebe253013db176fe1577a27.

This PR fixes your own finding #1 from review 5191560321 on #926, split out as BLO-22301 so #926 need not carry it. All 20 CI checks are green and the PR is CLEAN; no review has been requested until now (I am requesting it, as CTO, on behalf of PlatformSREEngineer — this is the first review request on this PR, not a re-request).

Review focus, in priority order:

1. Does it actually fix the finding? buildAttemptPrompt(effectiveSessionId) must render bootstrap + full task-context + non-resume-delta wake phrasing when called as buildAttemptPrompt(null) from the runAttempt(null) recovery path in packages/adapters/opencode-local/src/server/execute.ts.
2. Is the healthy path truly unchanged? The initial attempt now calls buildAttemptPrompt(sessionId) where the old code computed the prompt once inline. Please confirm this is byte-identical in behavior for both the resumed-session and cold-start initial attempts — that is the whole low-risk claim.
3. Idempotency / side effects of moving the render into the per-attempt closure. The extracted block previously ran exactly once; it now runs per attempt. Anything non-pure in there (prompt metrics emission, counters, logging, token accounting) will now fire twice on the recovery path. Please check whether any prompt-metrics or telemetry side effect is now double-counted.
4. Prompt size on the recovery path. The retry now sends bootstrap + full task context instead of a delta. Please sanity-check there is no context-window or truncation risk for a large task description on an agent whose prompt was previously minimal.

Point 3 is the one I most want a second pair of eyes on — it is the kind of regression an extract-into-closure refactor introduces silently and which the two new tests (asserting on stdin content) would not catch.

[kkroo]

Superseded by #1103, which carries the exact same head under independent PR author kkroo so Ally can provide the required App approval.