Summary

Adds a narrow storage-neutral session accessor boundary for gateway session reset/delete lifecycle mutations so entry changes and transcript artifact transitions are represented as one backend-owned operation.

Why

The SQLite migration needs reset/delete to be expressed as logical storage operations instead of gateway code mutating the session entry and then separately archiving or creating transcript artifacts. This PR keeps the current file-backed behavior while giving the future SQLite adapter a single operation to implement transactionally.

Changes

• Expose reset/delete lifecycle operations from session-accessor.ts
• Keep file-backed lifecycle implementation in store.ts
• Route public session barrel/runtime exports through accessor
• Preserve gateway hook/runtime cleanup outside storage
• Add focused reset/delete lifecycle tests

Testing

• node scripts/run-vitest.mjs src/config/sessions/store.session-lifecycle-mutation.test.ts src/gateway/server.sessions.reset-hooks.test.ts src/gateway/server.sessions.reset-cleanup.test.ts src/gateway/server.sessions.delete-lifecycle.test.ts test/scripts/check-session-accessor-boundary.test.ts
• node scripts/check-session-accessor-boundary.mjs
• git diff --check upstream/main...HEAD
• node scripts/run-tsgo.mjs --noEmit --pretty false
• node scripts/run-oxlint.mjs --tsconfig config/tsconfig/oxlint.core.json src/config/sessions.ts src/config/sessions/session-accessor.ts src/config/sessions/store.runtime.ts src/config/sessions/store.session-lifecycle-mutation.test.ts src/config/sessions/store.ts src/gateway/server-methods/sessions.ts src/gateway/session-reset-service.ts
• pnpm exec oxfmt --check --threads=1 src/config/sessions.ts src/config/sessions/session-accessor.ts src/config/sessions/store.runtime.ts src/config/sessions/store.session-lifecycle-mutation.test.ts src/config/sessions/store.ts src/gateway/server-methods/sessions.ts src/gateway/session-reset-service.ts scripts/check-session-accessor-boundary.mjs test/scripts/check-session-accessor-boundary.test.ts
• /Users/phaedrus/Projects/prompts/skills/autoreview/scripts/autoreview --mode branch --base upstream/main --no-web-search --thinking codex=low
• pnpm build

Real behavior proof

Behavior addressed: Gateway sessions.reset and sessions.delete now route persisted entry mutation plus transcript artifact transition through the storage-neutral session lifecycle accessor seam while preserving file-backed behavior.

Real environment tested: local live gateway from /Users/phaedrus/Projects/clawdbot at 57b810c7c60cecfdabd3773575e54f573c2a98d7 (pnpm openclaw --version reported OpenClaw 2026.6.8 (57b810c)) on port 18789.

Exact steps or command run after this patch:

pnpm build
pnpm openclaw gateway restart
pnpm openclaw --version
curl -fsS http://127.0.0.1:18789/readyz
pnpm openclaw gateway call health --json --timeout 30000
pnpm openclaw gateway call sessions.create --params '{"key":"agent:main:dashboard:path3-proof-reset","label":"Path 3 reset proof final"}' --json --timeout 30000
pnpm openclaw gateway call sessions.create --params '{"key":"agent:main:dashboard:path3-proof-delete","label":"Path 3 delete proof final"}' --json --timeout 30000
pnpm openclaw gateway call sessions.reset --params '{"key":"agent:main:dashboard:path3-proof-reset","reason":"reset"}' --json --timeout 30000
pnpm openclaw gateway call sessions.delete --params '{"key":"agent:main:dashboard:path3-proof-delete","deleteTranscript":true}' --json --timeout 30000
node <persisted-state inspection script>
pnpm openclaw gateway call sessions.delete --params '{"key":"agent:main:dashboard:path3-proof-reset","deleteTranscript":true}' --json --timeout 30000
curl -fsS http://127.0.0.1:18789/readyz
rm <exact proof transcript archives and temporary sessions.json backup>
node <proof-key cleanup inspection script>

Evidence after fix: sessions.reset changed agent:main:dashboard:path3-proof-reset from session id e7aa69e2-89cd-4c9a-b26c-6cf574903406 to d53d7988-268e-4477-9674-0c9d74017d89; sessions.json pointed that key at /Users/phaedrus/.openclaw/agents/main/sessions/d53d7988-268e-4477-9674-0c9d74017d89.jsonl; the old transcript was archived as e7aa69e2-89cd-4c9a-b26c-6cf574903406.jsonl.reset.2026-06-17T16-26-31.278Z; the new transcript header contained id d53d7988-268e-4477-9674-0c9d74017d89. sessions.delete removed agent:main:dashboard:path3-proof-delete and archived 96c88b65-00a2-4b9e-9390-1bda35f90eee.jsonl.deleted.2026-06-17T16-26-31.379Z. Cleanup then deleted the reset proof session through sessions.delete, removed only the proof transcript archives, and verified both proof keys were absent from sessions.json. Final /readyz returned {"ready":true,"failing":[]}.

Observed result after fix: The live gateway successfully performed reset and delete through the new lifecycle seam; persisted session metadata, reset transcript header creation, transcript archive naming, delete removal, and cleanup all matched the existing file-backed behavior.

What was not tested: future SQLite adapter implementation, doctor/import migration, runtime storage flip, SDK compatibility surfaces, runtime JSON fallback or dual-read behavior, and off-machine Crabbox/Testbox proof.

Current Review State

Ready for review. Latest head 57b810c7c6 is rebased onto current upstream/main; SQLite implementation remains a separate 3.2 adapter/foundation concern.

Related #88838.