fix(pi): bind writes to acknowledged runtime sessions

[dnlrsls]

🔗 Linked Issue

Closes #733

---

🏷️ PR Type

• type:bug — Bug fix
• type:feature — New feature
• type:docs — Documentation only
• type:refactor — Code refactoring (no behavior change)
• type:chore — Maintenance, dependencies, tooling
• type:breaking-change — Breaking change

---

📝 Summary

• Bind Pi session-attributed writes only to its native runtime session ID.
• Require acknowledged registration before writing and keep failed registration retryable.
• Remove model-supplied session identity from the four native write schemas.

📂 Changes

File	Change
plugin/pi/index.ts	Enforce acknowledged native runtime identity and case-local write declarations.
plugin/pi/test/index-source.test.mjs	Cover schema, acknowledgement cache, retry, and runtime identity contracts.
plugin/pi/test/native-tool-contract.test.mjs	Exercise native writes against failed and successful registration.
docs/AGENT-SETUP.md	Document Pi native runtime binding.

🧪 Test Plan

• npm test in plugin/pi — 44/44 pass
• npx --yes @biomejs/biome@2.5.6 lint plugin/pi/index.ts — 0 errors
• go test -tags e2e ./internal/server/... -count=1
• git diff --check

---

🔗 Chain Context

Strategy: sequential PRs to main

main
└── PR #730 OpenCode authoritative ownership
    └── Pi runtime binding 📍 (this PR, independent diff)
        └── Core attribution and lifecycle follow-up

• Start: main at 8058269
• End: Pi writes use only acknowledged native runtime identity
• Dependency: no code dependency on PR fix(opencode): bind writes to authoritative runtime sessions #730; merge after it to preserve review order
• Follow-up: core cardinality, store errors, activity, and session-end semantics
• Out of scope: OpenCode, Go core, migrations, handles, flags, heartbeats
• Review budget: 204 authored changed lines
• Rollback boundary: revert this commit to restore only Pi binding behavior

---

✅ Contributor Checklist

• I linked approved issue fix(pi): bind writes to acknowledged runtime sessions #733
• I added exactly one type:* label
• I ran Pi and affected E2E tests
• Docs match this PR slice
• Commit follows Conventional Commits
• No Co-Authored-By trailers

💬 Notes for Reviewers

Pi native wrappers intentionally remain for their UI. This slice removes lifecycle policy from model arguments: the host runtime ID is authoritative, registration must be acknowledged, and failures stop the write without poisoning retry state.

Summary by CodeRabbit

• Bug Fixes

  • Improved session handling for memory and observation tools by requiring confirmed runtime sessions.
  • Prevented writes when session registration fails or the runtime session is unavailable.
  • Removed support for manually supplied session IDs, ensuring writes use the active runtime session.
  • Failed session registration can now be retried safely.
  • Improved concurrent session registration handling.

• Documentation

  • Clarified session attribution and safe write behavior in the setup and architecture documentation.
  • Added documentation for Pi integration, installation, and native memory tools.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: bdc5be5b-a65b-414c-972a-5340fcca265d

📥 Commits

Reviewing files that changed from the base of the PR and between fc198ad and 72366f0.

📒 Files selected for processing (7)

• docs/AGENT-SETUP.md
• docs/ARCHITECTURE.md
• docs/PLUGINS.md
• plugin/pi/README.md
• plugin/pi/index.ts
• plugin/pi/test/index-source.test.mjs
• plugin/pi/test/native-tool-contract.test.mjs

Included review availability: Your plan includes up to 8 reviews per rolling hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

Pi native session-attributed writes now use only acknowledged runtime session IDs. Registration failures remain retryable, unavailable runtime identity stops writes, and model-supplied session_id fields are removed from the affected tools.

Changes

Pi runtime session binding

Layer / File(s)	Summary
Require acknowledged session registration plugin/pi/index.ts	ensureSession caches sessions only after acknowledgement. Failed registration rejects and remains retryable.
Bind native writes to runtime sessions plugin/pi/index.ts, plugin/pi/README.md, docs/AGENT-SETUP.md, docs/ARCHITECTURE.md	The four session-attributed tools remove session_id, require the Pi runtime session ID, ensure registration, and use that ID for writes. Documentation defines Pi and OpenCode identity binding.
Validate and document session binding plugin/pi/test/*, docs/PLUGINS.md, docs/AGENT-SETUP.md	Tests cover failed registration, retries, concurrent registration, acknowledgement caching, rejected model IDs, missing runtime identity, and summary session usage. Setup documentation describes the Pi extension and OpenCode session binding.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to 72366

This change restricts Pi writes to acknowledged native runtime sessions and makes failed registration retryable; no actionable merge-blocking risk remains.

Sequence Diagram(s)

sequenceDiagram
  participant PiNativeTool
  participant SessionManager
  participant ensureSession
  participant EngramSessionAPI
  participant EngramWriteAPI
  PiNativeTool->>SessionManager: getSessionId()
  PiNativeTool->>ensureSession: ensure runtime session
  ensureSession->>EngramSessionAPI: register session
  EngramSessionAPI-->>ensureSession: acknowledgement
  PiNativeTool->>EngramWriteAPI: persist with runtime session ID

Loading

Suggested reviewers: alan-thegentleman, gentleman-programming

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.67% 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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes binding Pi writes to acknowledged runtime sessions, which is the primary change.
Linked Issues check	✅ Passed	The changes implement runtime-only identity, acknowledged registration, retryable failures, schema removal, fail-closed behavior, and related coverage for issue #733.
Out of Scope Changes check	✅ Passed	The code, tests, and documentation changes remain within the linked issue scope and do not modify excluded OpenCode, Go core, schema, handle, flag, or fallback areas.

✨ 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.}

[Alan-TheGentleman]

The runtime-owned identity direction is correct, but the first-use registration path at plugin/pi/index.ts:419-428 still needs concurrency coordination. Two parallel writes can both miss knownSessions, issue separate registrations, and let one call fail after the other has already acknowledged and cached the same session, which rejects a valid write; the focused probe reproduced two registration attempts with only one completed write. Use one in-flight promise per project/session key, cache only successful acknowledgement, clear the promise after failure, and add parallel success plus failure-retry coverage. Please also narrow docs/AGENT-SETUP.md:89 to the four wrappers covered by #733, then rebase after #730 and retain both runtime-binding paragraphs.

[dnlrsls]

Addressed your requested changes in 72366f0:

• Added one in-flight registration promise per project/session key, with acknowledged-only caching and identity-safe cleanup after failures.
• Added deterministic parallel-success and shared-failure/later-retry coverage.
• Narrowed the setup guidance to the four Pi wrappers, integrated fix(opencode): bind writes to authoritative runtime sessions #730, and retained both Pi and OpenCode runtime-binding paragraphs.

Validation is green: 46/46 Pi tests, repository unit and E2E checks, and CodeRabbit with no actionable comments. Could you take another look?