refactor: route plugin SDK session entries through seam

[jalehman]

What

Routes the Plugin SDK and plugin runtime session entry helpers through the 3.1a session accessor seam for entry-level read/list/patch/update/upsert behavior, while preserving the existing public object-parameter API shape.

Refs #88838. Depends on #88840.

Why

This is one Path 3 3.1b caller-adoption slice: plugin-facing session entry APIs need to stop depending directly on file-backed store helpers before the session storage implementation can be validated and later flipped behind the seam.

Changes

• Route SDK entry reads
• Route runtime entry reads
• Route patch/update/upsert
• Preserve preserveActivity
• Refresh SDK API baseline

Scope

Included: entry-level SDK/runtime getSessionEntry, listSessionEntries, patchSessionEntry, updateSessionStoreEntry, and upsertSessionEntry, plus 3.1a seam support for preserveActivity.

Excluded: transcript identity, sessionFile identity, public whole-store compatibility modernization, SQLite validation branch wiring, storage flip, doctor migration, and runtime dual-read/fallback behavior.

Testing

• node scripts/run-vitest.mjs src/plugin-sdk/session-store-runtime.test.ts src/plugins/runtime/index.test.ts extensions/discord/src/monitor/native-command.plugin-dispatch.test.ts extensions/voice-call/src/response-generator.test.ts
• node scripts/run-vitest.mjs src/config/sessions/session-accessor.test.ts src/plugin-sdk/session-store-runtime.test.ts src/plugins/runtime/index.test.ts extensions/discord/src/monitor/native-command.plugin-dispatch.test.ts extensions/voice-call/src/response-generator.test.ts
• node scripts/run-vitest.mjs src/plugin-sdk/session-store-runtime.test.ts src/plugins/runtime/index.test.ts
• node scripts/run-oxlint.mjs src/config/sessions/session-accessor.ts src/config/sessions/session-accessor.test.ts src/plugin-sdk/config-runtime.ts src/plugin-sdk/session-store-runtime.ts src/plugin-sdk/session-store-runtime.test.ts src/plugins/runtime/runtime-agent.ts src/plugins/runtime/types-core.ts src/plugins/runtime/index.test.ts
• pnpm tsgo:core
• pnpm tsgo:core:test
• pnpm plugin-sdk:api:check
• git diff --check upstream/clawdbot-9c3/session-accessor-seam...HEAD
• Source branch autoreview passed after the last code change; disposable SQLite integration autoreview remains blocked and is intentionally out of this PR.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed June 1, 2026, 3:42 PM ET / 19:42 UTC.

Summary
The branch re-routes plugin SDK and plugin runtime session entry read/list/patch/update/upsert helpers through the session accessor seam and updates focused seam tests plus SDK API baseline hashes.

PR surface: Source +291, Tests +136, Generated 0. Total +427 across 8 files.

Reproducibility: not applicable. this is a refactor slice, not a bug report with a failing user scenario. Source inspection and the new focused tests show the intended compatibility paths, but I did not run tests in this read-only review.

Review metrics: 1 noteworthy metric.

• Public session helpers re-routed: 5 helpers re-routed. These entry-level plugin SDK/runtime helpers are compatibility-sensitive because third-party and bundled plugins can depend on their call shape and session-store semantics.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Finish review of the base accessor seam before landing this slice.
• Keep the focused SDK session tests and plugin SDK API check green after the stack is rebased.

Risk before merge

• [P1] This PR cannot land independently because it targets the unmerged session accessor seam branch rather than current main.
• [P1] It re-routes public plugin SDK and plugin runtime session entry helpers, so maintainers need stack-level confidence that replacement, patch, preserveActivity, and future SQLite-backed semantics remain compatible for bundled and third-party plugins.

Maintainer options:

1. Land In Stack Order (recommended)
   Merge only after the base accessor seam PR is reviewed and this slice's SDK compatibility tests are green on the final stack.
2. Pause If Seam Shape Changes
   If maintainers change the base seam contract, pause or refresh this PR rather than carrying a plugin SDK wrapper shape that no longer matches the canonical boundary.

Next step before merge

• [P1] Protected draft stack PR needs maintainer review of ordering and compatibility, not an automated repair branch.

Security
Cleared: The diff does not change workflows, dependencies, package resolution, secrets handling, or code-download paths; no concrete security or supply-chain issue was found.

Review details

Best possible solution:

Review and land this only in the planned stack order after the base seam PR is accepted, with focused plugin SDK compatibility validation as part of the broader #88838 migration.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a refactor slice, not a bug report with a failing user scenario. Source inspection and the new focused tests show the intended compatibility paths, but I did not run tests in this read-only review.

Is this the best way to solve the issue?

Acceptable, but not independently merge-ready. The linked migration plan explicitly calls for plugin runtime/SDK caller adoption before the SQLite flip, and this PR keeps the public object-parameter helper shape while moving the implementation behind the seam; the safer path is stack-level maintainer review after the base seam is settled.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 193988bc5ba4.

Label changes

Label changes:

• add P2: This is a normal-priority stacked refactor with limited immediate blast radius but a public plugin SDK/session-state surface.
• add merge-risk: 🚨 compatibility: The patch reimplements public plugin SDK helper exports through a new seam, so existing plugin compatibility must hold before merge.
• add merge-risk: 🚨 session-state: The patch changes session entry read/write routing, where semantic drift can affect stored session metadata and activity timestamps.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The PR carries the protected maintainer label and is an internal refactor slice, so the external contributor real-behavior proof gate is not applied; the body lists focused tests and checks but no separate live behavior proof.

Label justifications:

• P2: This is a normal-priority stacked refactor with limited immediate blast radius but a public plugin SDK/session-state surface.
• merge-risk: 🚨 compatibility: The patch reimplements public plugin SDK helper exports through a new seam, so existing plugin compatibility must hold before merge.
• merge-risk: 🚨 session-state: The patch changes session entry read/write routing, where semantic drift can affect stored session metadata and activity timestamps.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The PR carries the protected maintainer label and is an internal refactor slice, so the external contributor real-behavior proof gate is not applied; the body lists focused tests and checks but no separate live behavior proof.

Evidence reviewed

PR surface:

Source +291, Tests +136, Generated 0. Total +427 across 8 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	5	311	20	+291
Tests	2	136	0	+136
Docs	0	0	0	0
Config	0	0	0	0
Generated	1	2	2	0
Other	0	0	0	0
Total	8	449	22	+427

What I checked:

• Repository policy read: Read the full root AGENTS.md and the scoped src/plugin-sdk, src/plugins, and docs AGENTS.md files; plugin SDK public-surface and session-state compatibility guidance affected the review. (AGENTS.md, 193988bc5ba4)
• Live PR state: GitHub API shows this PR is open, draft, cleanly mergeable against the stack branch, labeled maintainer, and based on clawdbot-9c3/session-accessor-seam at be13ad1. (a617bb7580a2)
• Current main does not contain the seam: The current main checkout has no tracked src/config/sessions/session-accessor.ts and no session-accessor references in the inspected session/plugin runtime paths, so this stack slice is not implemented on main. (src/config/sessions/session-accessor.ts, 193988bc5ba4)
• SDK entry helpers routed through seam: PR head defines SDK-facing get/list/patch/update/upsert wrappers that preserve object-parameter call shapes while delegating to session-accessor helpers. (src/plugin-sdk/session-store-runtime.ts:63, a617bb7580a2)
• Runtime agent helpers routed through seam: PR head mirrors the SDK wrapper behavior in plugin runtime agent.session helpers while keeping the deprecated whole-store helpers on the legacy path. (src/plugins/runtime/runtime-agent.ts:83, a617bb7580a2)
• Base seam remains file-backed: The accessor seam on the PR head delegates session entry operations to the existing file-backed store helpers, including preserveActivity forwarding and updateSessionEntry using updateFileSessionStoreEntry. (src/config/sessions/session-accessor.ts:87, a617bb7580a2)

Likely related people:

• @jalehman: Authored this PR's three commits and the linked session/transcript SQLite migration tracker that explicitly includes this plugin SDK seam-adoption slice. (role: feature-stack owner; confidence: high; commits: 8726ea9e5135, 6a4468a75c33, a617bb7580a2; files: src/plugin-sdk/session-store-runtime.ts, src/plugins/runtime/runtime-agent.ts, src/config/sessions/session-accessor.ts)
• @vincentkoc: Current-main blame for the existing plugin SDK session runtime and plugin runtime session type surface points to commit 1fd2259, though the checkout history is shallow/grafted. (role: recent adjacent area contributor; confidence: medium; commits: 1fd2259e2872; files: src/plugin-sdk/session-store-runtime.ts, src/plugins/runtime/types-core.ts, src/config/sessions/store.ts)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.