docs(design): agent mounts, one derived durable folder per agent

[mmabrouk]

Today an agent has no storage of its own: every run's files live in the session's mount (or an ephemeral temp dir for sessionless runs) and are invisible to the agent's other conversations. After this project, every agent has one durable folder, mounted into all of its runs next to the session cwd, browsable from the frontend.

This PR is the design workspace, no code. It captures the mechanism JP settled in his voice note (2026-07-11) plus the review that sharpened it:

• Identity by reserved slug, not schema. Same trick session mounts already use: the slug is minted deterministically (__ag__agent__<artifact_id>__default), upserted on the existing unique(project_id, slug) constraint, session_id stays NULL. No migration, no new column, no uniqueness machinery.
• No wire change. The runner already receives runContext.workflow.artifact.id; it signs the agent mount best-effort and mounts it at <cwd>-agent, local and Daytona, exposing the path via one env var.
• Two thin endpoints mirror the session shape: POST /mounts/agents/sign (runner) and POST /mounts/agents/query (frontend lookup; read never creates). The frontend reuses the existing mount file browser.
• Deliberate limitations (no reverse lookup machinery, no FK/cascade, shared-prefix last-writer-wins) are documented in context.md with the graduation path if they ever start to matter.

How to review: plan.md is the document to comment on; it ends with six open questions (slug shape, endpoint placement, mount point constant, query semantics, frontend slice ownership, run-type coverage). context.md holds the why and the rejected alternatives; research.md the code facts with file:line pointers.

Depends on nothing; builds on the transcript-mounts pattern from #5197 (applied to the tree, unmerged), so the runner slice tracks that PR's final shape.

https://claude.ai/code/session_01QHXdTFZjipBCPX3PkeWbh6

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jul 12, 2026 11:02am

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 71eb5d20-aee8-48d1-82eb-3ed751d4d144

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/agent-mounts-plan

---

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

[mmabrouk]

Pushed a review round from tonight's session with Mahmoud (55ba4f9): discovery is now part of D3.

The env var alone is plumbing, not discovery — neither Pi nor Claude inspects env or lists the cwd's parent unprompted, so the mount would sit unused until an instructions change ships. And the instructions file can't carry the signal without a policy change: for pi_core and claude the rendered AGENTS.md/CLAUDE.md is the author's text verbatim (only pi_agenta composes a platform preamble). So the filesystem carries it instead:

1. <cwd>/agent-files -> <cwd>-agent symlink — visible in the one discovery action every harness performs (listing its cwd). Not the rejected dir-inside-cwd: that was about nesting FUSE in FUSE; a symlink is a pointer. Needs a geesefs-symlink-support check (the session cwd is itself geesefs); failure is logged and non-fatal.
2. A seeded README.md in the agent mount, write-if-absent, stating the persistence rule (agent folder outlives sessions; cwd doesn't). Also gives the D4 panel real content on first open.

Open question 3 widens accordingly: agent-files and the README wording are now model-visible names — naming opinions welcome.

[mmabrouk]

Implementation up as a draft: #5247 (api + runner + web + docs). See its base note for the stacked-on-unmerged-work situation.