refactor(server): route session stragglers through effect services

[Astro-Han]

Summary

Routes the listed session owner facade stragglers through the shared Effect runtime boundary:

• Adds Session.Service.list while preserving the legacy Session.list generator facade for existing callers.
• Moves GET /session, share/unshare session fetches, summarize post-loop message reads, and the deprecated session permission response route onto AppRuntime + Session.Service / Permission.Service.
• Records the partial session route straggler cleanup without claiming full session route migration.

Why

This is part of the non-UI backend Effect migration lane. The current session route owner still had a few raw facade calls in otherwise Effect-aware route code; this PR clears those specific stragglers without expanding into session processor, prompt, or run-state internals.

Related Issue

Related to #936

Human Review Status

Pending

Review Focus

Please focus on whether the new Session.Service.list boundary preserves the legacy list query behavior and whether the route handlers still return the same HTTP responses while using the shared runtime.

Risk Notes

Low risk backend migration. Permission surface touched only for the deprecated session permission response route; behavior is covered by a focused route test and the reply schema is unchanged. Migration docs were updated only to record this partial straggler cleanup. No UI/copy, platform/packaging, dependency, credential, generated-content, or deletion behavior was changed.

How To Verify

Baseline focused routes: 20 passed before implementation.
Focused server routes: bun test test/server/session-core-routes.test.ts test/server/session-runtime-routes.test.ts test/server/session-messages.test.ts test/server/permission-routes.test.ts -> 21 passed.
Session list compatibility: bun test test/server/session-list.test.ts -> 8 passed.
Typecheck: bun run typecheck -> tsgo --noEmit passed.
Diff check: git diff --check -> passed.
Route facade inventory: rg -n "Session\.(list|get|messages)\(|Permission\.reply\(" packages/opencode/src/server/instance/session.ts -> no matches.
Fresh-eye review: no blocking findings.
Claude read-only review: no P0/P1 findings; optional P3 notes did not require code changes.

Screenshots or Recordings

Not applicable. No visible UI changes.

Checklist

How to use this checklist:

• Tick a box by replacing [ ] with [x]. Do not edit, add, or remove items.
• The bot-applied label items can only be honestly ticked AFTER the PR is opened and the labeler / priority-triage bots have run — return to the PR description and tick them then.
• Most items are required. The few that are conditional are explicitly marked (conditional); for those, leave unticked if they truly do not apply and explain why in Risk Notes. All other items must be ticked before requesting human review.

• Type label — this PR carries exactly one of bug, enhancement, task, documentation. Type labels are author-added; the labeler bot does NOT assign them. Add the label in the GitHub UI, then tick this.
• Routing labels — this PR carries at least one of app, ui, platform, harness, ci. The labeler bot assigns these on PR open based on changed paths. Confirm the bot's choice (or override if wrong), then tick this.
• Priority label — this PR carries exactly one of P0, P1, P2, P3. The priority-triage bot suggests one on PR open. Confirm or override, then tick this.
• Human Review Status above is set to Pending, Approved by @<reviewer>, or Not required: <reason> (default is Pending; "not required" is restricted to bot-authored low-risk PRs).
• I linked the related issue, or stated in Summary why there is no issue.
• I described the review focus and any meaningful risks.
• I replaced the example block in How To Verify with the real verification steps and the key result for each.
• I did not introduce unrelated refactors, dependencies, generated files, or file changes beyond the stated scope.
• (conditional) I manually checked visible UI or copy changes when needed, with screenshots or recordings. Leave unticked only if no visible UI or copy changed.
• (conditional) I considered macOS and Windows impact for platform, packaging, updater, signing, paths, shell, or permissions changes. Leave unticked only if no platform/packaging surface was touched.
• (conditional) I called out docs, release notes, dependencies, permissions, credentials, deletion behavior, generated content, or local file changes when relevant. Leave unticked only if none of those surfaces was touched.
• I reviewed the final diff for unrelated changes and suspicious dependency changes.
• I am targeting dev, and my PR title and commit messages use Conventional Commits in English.

Summary by CodeRabbit

• Refactor
  • Session route handlers refactored to use standardized effect-based execution for enhanced reliability and consistency across session operations.
  • Session service extended with improved list functionality for better session management.
  • Test coverage updated to verify session permission and sharing operations.

[github-actions]

Suggested priority: P2 (includes non-doc, non-test paths outside the low-risk bucket).

P1/P0 are reserved for maintainer confirmation. Please relabel manually if this is a release blocker, security issue, data-loss risk, or updater/runtime failure.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: a686f9e7-5086-40a1-b7a6-78990dfa4a5e

📥 Commits

Reviewing files that changed from the base of the PR and between f99d4ea and 30c2b94.

📒 Files selected for processing (5)

• packages/opencode/specs/effect-migration.md
• packages/opencode/src/server/instance/session.ts
• packages/opencode/src/session/session.ts
• packages/opencode/test/server/permission-routes.test.ts
• packages/opencode/test/server/session-runtime-routes.test.ts

---

📝 Walkthrough

Walkthrough

Five session route handlers in server/instance/session.ts are migrated from direct static calls to Effect-based service calls via AppRuntime.runPromise. A new list method and ListInput type are added to Session.Service, backed by a listForProject helper. Tests for the deprecated permission route and share route are updated, and effect-migration.md records the completed scope.

Changes

Session Effect Migration — straggler pass

Layer / File(s)	Summary
Session.Service list contract and implementation packages/opencode/src/session/session.ts	Introduces ListInput type, adds list(input?: ListInput): Effect<Info[]> to Interface, implements it via a new listForProject project-scoped helper, wires it into Service.of, and refactors the exported list generator to delegate to that helper.
Route handler effectification packages/opencode/src/server/instance/session.ts	Replaces direct static calls in five handlers — GET /session list, share/unshare session lookup, summarize message fetch, and deprecated permission reply — with AppRuntime.runPromise(Effect.gen(...)) using Session.Service and Permission.Service.
Tests and migration docs packages/opencode/test/server/permission-routes.test.ts, packages/opencode/test/server/session-runtime-routes.test.ts, packages/opencode/specs/effect-migration.md	Adds a new test exercising the deprecated session permission route via a sessionApp() Hono helper; fixes the share route test mock to use an explicit share object; records the completed straggler pass and out-of-scope boundaries in effect-migration.md.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Astro-Han/pawwork#1032: Effectifies a deprecated session permission "reply" handler using the same Permission.Service.reply(...) via AppRuntime.runPromise(Effect.gen(...)) pattern introduced in this PR.
• Astro-Han/pawwork#1319: Refactors packages/opencode/src/server/instance/session.ts session route handlers to use AppRuntime.runPromise(Effect.gen(...)) and Session.Service injection, directly preceding this straggler pass.

Poem

🐇 Hop, hop through the Effect chain,
No more for await loops remain!
Session.Service.list now leads the way,
AppRuntime.runPromise saves the day.
The rabbit refactors, test by test,
And marks the migration — done with zest! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'refactor(server): route session stragglers through effect services' accurately describes the main change—moving session route handlers to use Effect-based services through the shared runtime.
Description check	✅ Passed	The description is substantially complete with all major sections filled out: Summary, Why, Related Issue, Human Review Status, Review Focus, Risk Notes, How To Verify, and a mostly-ticked Checklist with conditional items appropriately left unticked and explained.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/i936-session-route-effect-stragglers

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install failed. For unrecoverable errors, disable the tool in CodeRabbit configuration.

---

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 and usage tips.}

[gemini-code-assist]

Code Review

This pull request migrates several session-related route handlers in packages/opencode/src/server/instance/session.ts to use the Effect-based AppRuntime.runPromise pattern, including listing sessions, sharing/unsharing sessions, summarizing, and replying to permissions. It also introduces the list method to the Session.Service interface and updates corresponding tests. Feedback on the changes suggests renaming the resolved Session.Service variable in the GET /session handler to sessionService to avoid naming conflicts with the outer sessions array and to maintain consistency across the codebase.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.