[codex] Recover unavailable OpenCode sessions (BLO-18012)

[kkroo]

Thinking Path

• Paperclip is the open source control plane people use to manage AI agents for work.
• Its OpenCode adapters persist task-scoped session identifiers between heartbeat runs.
• A control-plane or worker restart can leave an opencode_k8s task pointing at a missing backend session.
• Current master retries a missing session in-process, but it lacks the typed failure classification, bounded heartbeat backstop, and startup reconciliation needed when that retry cannot complete.
• fix(heartbeat): recover unavailable opencode sessions #926 implements that lifecycle but is authored by the Ally GitHub App and cannot provide its own required independent review path.
• This independently authored, master-based successor ports the finalized behavior without changing lockfiles or healthy-session execution.
• The result is bounded recovery from unavailable sessions rather than waiting for the normal heartbeat interval or retaining stale task-session state.

Linked Issues or Issue Description

Supersedes #926.

Refs #926 and BLO-18012.

No independently authored successor or equivalent implementation was found. #1103, already merged, supplies the related fresh-session prompt only; this PR adds the typed heartbeat recovery and startup-reconciliation lifecycle absent from current master.

What Changed

• Classifies trusted OpenCode Session unavailable failures as session_unavailable while preserving the existing fresh-session attempt.
• Schedules bounded 30-second heartbeat retries with retry identity, execution locking, and duplicate/coalescing protection.
• Carries typed recovery evidence through zero-token classification, adapter-change safeguards, and terminal retry accounting.
• Clears stale task-session state only when the matching recovery wake is promoted, and cancels superseded deferred resets.
• Adds parser, heartbeat retry, stale-queue, recovery classifier, stale-lock-sweep, and startup reconciliation regression coverage.

Verification

Passed locally after rebasing onto 08b6f449:

• pnpm --filter @paperclipai/adapter-opencode-local typecheck
• pnpm --filter @paperclipai/server typecheck
• pnpm exec vitest run --no-file-parallelism packages/adapters/opencode-local/src/server/parse.test.ts — 4/4 passed
• pnpm --filter @paperclipai/server exec vitest run --no-file-parallelism src/__tests__/recovery-classifiers.test.ts src/__tests__/heartbeat-retry-scheduling.test.ts src/__tests__/heartbeat-stale-queue-invalidation.test.ts src/__tests__/recovery-stale-issue-lock-sweep.test.ts src/__tests__/heartbeat-process-recovery.test.ts
• git diff --check origin/master...HEAD

The server suite emitted the known optional external-adapter warning for the absent taalas-chatjimmy-wrapper; it exited successfully. pnpm-lock.yaml is unchanged.

Risks

Medium: this changes recovery timing and session-reset coordination around failed OpenCode runs. The main risk is an incorrectly replayed or suppressed retry; bounded attempts, retry identity, supersession checks, and focused lifecycle tests cover those paths. No migration, API change, or healthy-session behavior change is included.

Model Used

OpenAI Codex (GPT-5), using GitHub inspection, isolated local code changes, and focused TypeScript/Vitest verification.

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 — not applicable; server-only
• I have updated relevant documentation to reflect my changes — not applicable; no public contract changed
• I have considered and documented any risks above
• All Paperclip CI gates are green
• Greptile is 5/5 with no open P2s, recommendations, or follow-ups
• I will address all Greptile and reviewer comments before requesting merge

[allyblockcast]

🔗 Paperclip issue: BLO-18012

[allyblockcast]

🔗 Paperclip issue: BLO-18012

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[allyblockcast]

Ally — Consolidated PR Review

Lenses: pr-review-toolkit (code, tests, comments, errors, types) + gstack/review + native-codex.
Reviewed head: 9fd70e9

Critical Issues (0)

Important Issues (0)

Suggestions (0)

Strengths

• The retry lineage, bounded attempts, and stale deferred-wake checks preserve task-scoped recovery semantics across normal dispatch and startup reconciliation.
• Parser coverage separates structured OpenCode session errors from incidental text, reducing false reset triggers.

Recommended Action

1. Ready to merge once the required checks pass.

[allyblockcast]

Ally — Consolidated PR Review

Lenses: pr-review-toolkit (code, tests, comments, errors, types) + gstack/review + native-codex.
Reviewed head: 9fd70e9

Critical Issues (0)

Important Issues (0)

Suggestions (0)

Strengths

• The retry lineage, bounded attempts, and stale deferred-wake checks preserve task-scoped recovery semantics across normal dispatch and startup reconciliation.
• Parser coverage separates structured OpenCode session errors from incidental text, reducing false reset triggers.

Recommended Action

1. Ready to merge once the required checks pass.