fix(opencode): resume the OpenCode session on follow-ups instead of starting an empty one

[vdmkotai]

Fixes #3604.

What

The OpenCode adapter never read or emitted a resume cursor, so the upstream ses_… id lived only in process memory. When that in-memory binding was lost — ProviderSessionReaper stopping an idle session (~30 min), or an app/server restart — the next follow-up in the same visible thread was sent to a brand-new, empty OpenCode session. t3code kept rendering its own projection DB, so the user still saw the full history while the model had no context.

This makes the OpenCode adapter resumable, mirroring the existing Grok/Cursor/Codex pattern, entirely within apps/server/src/provider/Layers/OpenCodeAdapter.ts:

• startSession now emits resumeCursor: { schemaVersion, sessionId } on the returned ProviderSession (and sendTurn echoes it), so ProviderService persists it into provider_session_runtime.resume_cursor_json.
• When a cursor is present, startSession validates the id with session.get and re-adopts that session instead of calling session.create. OpenCode scopes history by session id, so prompting the same id restores the full prior conversation.
• A missing/closed session (or any session.get failure) falls back to a fresh session, so a stale cursor can never wedge the thread.
• The start race-cleanup only aborts the upstream session when we actually created it — never one we merely resumed.

Why

This is the documented root cause in #3604 (with DB-level evidence of two OpenCode sessions per visible thread). The persistence/recovery plumbing is already provider-agnostic: ProviderService.startSession falls back to the stored binding cursor when the reactor passes none, so no changes are needed outside the adapter — it just needed the adapter to start producing and consuming a cursor like every other provider already does.

Scope

Intentionally small and focused — 2 files, no contract / persistence / orchestration changes:

• apps/server/src/provider/Layers/OpenCodeAdapter.ts (+118/-20)
• apps/server/src/provider/Layers/OpenCodeAdapter.test.ts (+147) — regression tests for: fresh-session cursor emission, resume re-adopting the persisted id (no create), follow-up turns targeting the resumed id, stale-cursor fallback to create, and malformed/foreign-cursor rejection.

Validation

• tsgo --noEmit clean; OpenCodeAdapter.test.ts (21 tests) plus the full src/provider + src/orchestration suites (531 tests) pass.
• Ran a desktop build carrying this fix for a full day across many OpenCode sessions, including idle-past-reaper and app-restart between turns — every follow-up retained full context, no regressions observed.

---

Note

Medium Risk
Changes core session lifecycle for OpenCode threads; misclassified errors could still wedge or reset context, but behavior is guarded by structured 404 detection and extensive adapter tests.

Overview
Fixes #3604 by making the OpenCode adapter produce and consume a persisted resumeCursor (schemaVersion + sessionId), like other providers, so follow-ups keep upstream conversation context after idle reaper or restart.

startSession now probes session.get when a valid cursor is present: reuse the session when cwd matches (with session.update for current runtimeMode permissions), fork into the requested directory when cwd changed (preserving history), or create only on a confirmed 404. Transient/auth errors from the probe fail instead of silently starting fresh. Race cleanup aborts only sessions this call created, not resumed ones.

sendTurn returns the cursor so persistence stays fresh. Helpers isOpenCodeNotFound and isSameOpenCodeDirectory classify SDK errors and path equivalence (symlinks, trailing slashes).

Tests extend the OpenCode mock with get/update/fork and cover resume, stale cursor, bad cursor, transient errors, cwd fork, and utility behavior.

^{Reviewed by Cursor Bugbot for commit 8bfeff6. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Resume existing OpenCode sessions on follow-up turns instead of creating empty ones

• startSession in OpenCodeAdapter.ts now parses a persisted resumeCursor and probes session.get to verify the session still exists before reusing it.
• If the session's working directory differs from the requested cwd, the session is forked into the new directory; permissions are re-applied via session.update on resume.
• Non-404 probe errors are propagated as failures rather than silently falling back to a new session; confirmed 404s fall back to creating a fresh session.
• sendTurn results now include the session's resumeCursor so callers can persist it for future follow-ups.
• Risk: sessions with a stale or wrong-version cursor emit a warning and fall back to a new session, discarding any prior conversation context.

^{Macroscope summarized 8bfeff6.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 28d89c9f-23bf-4ef7-90eb-4efb0c48336b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces substantial new runtime behavior: session resumption via durable cursors, session forking when directories change, and new external API calls (session.get/update/fork). While well-tested, these changes fundamentally alter how OpenCode sessions are managed and warrant human review.

^{You can customize Macroscope's approvability policy. Learn more.}

[vdmkotai]

Thanks for the reviews — addressed in 7be6629. Three hardening changes, all kept within the adapter:

1. Permission re-application on resume (Cursor Bugbot): session.create was the only place buildOpenCodePermissionRules(runtimeMode) was applied, so re-adopting a session via session.get left it on its original permissions — and ProviderCommandReactor restarts with the persisted cursor on a runtime-mode change. Resume now calls session.update({ sessionID, permission }), so a runtime-mode change takes effect on the re-adopted session.

2. Confirmed-not-found vs. transient errors (macroscope): the SDK client is created with throwOnError: true, so session.get rejects on any non-2xx. The fallback to a fresh session now fires only on a confirmed 404 / NotFoundError; transport/auth/server errors propagate instead of silently resetting a live thread to an empty session (matching [Bug]: OpenCode provider loses thread context on follow-up — t3code starts a new OpenCode session instead of resuming (no durable session binding) #3604's own "surface an explicit error" suggestion).

3. Directory-aware resume: OpenCode routes a prompt to the session's own stored directory, so resuming a session created under a different cwd would silently run there. Resume now starts a fresh session when the re-adopted session's directory differs from the requested cwd.

Tests updated to model throwOnError: true (get rejects, not a result tuple) and add coverage for permission re-application, the cwd-mismatch fallback, and transient-error propagation. Full server provider + orchestration suite green (534 passing).

[vdmkotai]

UPDATE:
Seems like this fix is not enough. Making more changes

[vdmkotai]

Pushed a follow-up correcting the directory-mismatch handling that was added during hardening.

Problem: the guard that started a fresh session when the resumed session's stored directory differed from the requested cwd was justified by "OpenCode routes a prompt to the session's own stored directory." That premise doesn't hold — OpenCode resolves tool execution, snapshots and file ops from the per-request directory param (instance context), not session.info.directory. So on any cwd change (most commonly a thread moving from the project root into a git worktree between turns) the whole conversation was stranded in the old session and the follow-up landed in an empty one — reproducing the exact #3604 symptom this PR fixes. I hit this in real use with a worktree-backed thread (turn 1 created the session in the project root before the worktree metadata settled; turn 2 requested the worktree cwd → empty session).

Fix: when the persisted session exists but was created under a different directory, client.session.fork({ sessionID, directory }) into the requested directory instead of creating an empty session. OpenCode clones the full history into a new session bound to the requested worktree, so the follow-up keeps context and tools still run on the correct tree. The fork id becomes the durable resume cursor. A genuinely missing (404) session still starts fresh.

Verified against the OpenCode source that fork copies all messages/parts with fresh ids and stamps the new session's directory/path from the request context. The former "starts fresh on directory mismatch" test now asserts fork-with-history.

[vdmkotai]

The single issue from Bugbot's Jul 19 review (raw string comparison of the resume directory against the session's stored directory) is fixed in 5741a3b and the inline thread is resolved: isSameOpenCodeDirectory now compares lexically resolved forms first and falls back to realpath on both sides (per-side lexical fallback when resolution fails), so a trailing slash or a symlinked cwd (macOS /tmp → /private/tmp) no longer spuriously forks the session or churns the durable cursor. Covered by an adapter-level regression test (slash-only difference → reused in place, no fork/create) and direct unit tests of the helper including a real symlink fixture. tsgo clean, full src/provider suite green.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 061be07. Configure here.}