docs(agents): session model spec — the source-of-truth contract

[2witstudios]

Phase 0 of the Agent-Session Single Source of Truth epic. The agent-session model has so far lived only in PR prose (#2258's container model, #2336's resource-addressed re-model) and schema doc comments. This lands it as a durable spec: docs/2.0-architecture/agent-sessions.md.

What the doc pins

1. The model (shipped) — Drive → Session/Workspace (owns one Sprite sandbox) → many conversations + shells; write-once binding via conversations.sessionId with a single guarded claim path; ON DELETE SET NULL history preservation; global assistant = null driveId, owner-only by construction; ended sessions revivable via planSessionReopen(); sandbox status derived, never stored. Every invariant verified against current code (packages/db/src/schema/agent-sessions.ts, conversations.ts, decide-session-access.ts, plan-session-lifecycle.ts, session-tools.ts), not against the PR prose alone.
2. Authorization axioms (PR feat(agents): fully resource-addressed session orchestration — permission-gated, any surface, any workspace (#2335) #2336, product-locked) — verbs resource-addressed + permission-gated; binding/lifecycle/location never refuse a permitted operation; global assistant = the user's own authority from any surface; location supplies only defaults and pane placement; cross-workspace orchestration is legitimate.
3. The source-of-truth contract — clearly marked as the epic's target state: one server-side owner per fact, rev-carrying emission on every write, every surface a subscriber that can prove currency, tool actions indistinguishable from UI actions (read-your-writes for agents). Each clause states "today X / target Y (epic phase)". The one-sentence criterion: a feature needing a second copy of a fact derives at read time or doesn't ship.
4. Vocabulary — the five historical meanings of "sessionId" and their canonical names (workspaceId / conversationId / frozen wire sessionId / spriteExecId / auth sessions = unrelated).
5. Keeping this honest — names the recurring stale-tool-guidance bug class (the session-tools.ts header documented a guard feat(agents): fully resource-addressed session orchestration — permission-gated, any surface, any workspace (#2335) #2336 deleted for a full release) and pins the normative-source order: contract tests (forthcoming, epic Phase 1 task "Tool contract pin and typed refusals") + this doc; PRs touching session semantics must update both.

Verification

• Every file, column, function, and tool name cited was grepped against origin/master — including claimConversation, deriveSandboxStatus, planSessionReopen, canUserViewPage/checkAccessForSubject in the minting path, and the /api/agent-sessions/[sessionId] route tree.
• lint/knip:check are no-ops for this change by configuration: knip projects glob *.{ts,tsx,js} only and turbo lint runs eslint over app sources; a new docs/*.md is outside both.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XnzUuAixdTJ8xDpP5S92Ts

Summary by CodeRabbit

• Documentation
  • Added an architecture guide for agent sessions.
  • Documented session and workspace ownership, conversation and shell relationships, lifecycle rules, authorization, event handling, and source-of-truth requirements.
  • Clarified current behavior versus the intended target state.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

Agent Sessions architecture

Layer / File(s)	Summary
Architecture specification docs/2.0-architecture/agent-sessions.md	Adds normative rules for session and workspace ownership, conversation binding, lifecycle, authorization, source of truth, revision synchronization, terminology, migration phases, and contract tests.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• 2witstudios/PageSpace#2302: Implements conversation claiming and session binding described by this architecture document.
• 2witstudios/PageSpace#2304: Implements persisted session workspaces and pane or tab lifecycle behavior covered by the documented invariants.
• 2witstudios/PageSpace#2336: Implements Agent Sessions ownership, lifecycle, authorization, workspace, and conversation-binding behavior documented here.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the new agent session model specification and its source-of-truth role.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/session-model-spec

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/2.0-architecture/agent-sessions.md`:
- Line 13: Update the fenced diagram block in agent-sessions.md to specify the
text language by changing its opening fence to use text, while preserving the
existing ASCII diagram content and closing fence.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8e5ac248-b814-42c2-8845-2891c4537b8a

📥 Commits

Reviewing files that changed from the base of the PR and between 3f8f0a5 and 2c4de8c.

📒 Files selected for processing (1)

• docs/2.0-architecture/agent-sessions.md

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Specify a language for the diagram fence.

Line [13] opens a fenced block without a language. Add text to satisfy markdownlint MD040 and identify the ASCII diagram format.

Proposed fix

-```
+```text

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

```

🧰 Tools

🪛 markdownlint-cli2 (0.23.2)

[warning] 13-13: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/2.0-architecture/agent-sessions.md` at line 13, Update the fenced
diagram block in agent-sessions.md to specify the text language by changing its
opening fence to use text, while preserving the existing ASCII diagram content
and closing fence.

Source: Linters/SAST tools