[docs] Plan durable managed-resource reconciliation

[mmabrouk]

Context

PR #5277 deliberately keeps Daytona Secret ownership inside the runner process. That solves plaintext credential delivery without changing the API, but a hard runner crash can leave external Secrets behind.

The original PR #5242 addressed durability with a Daytona-specific lease API and migration. Before shipping that control-plane surface, we need agreement on whether the same primitives should reconcile other external resources such as Composio trigger subscriptions and future MCP authorization relationships.

Changes

This stacked PR adds a design workspace only. It proposes a reusable managed_resources domain with product-owned intent, desired and observed state, idempotent reservation, optimistic versions, generation-fenced worker claims, bounded retries, and typed provider controllers.

The documents cover:

• the boundary between product records, the reconciliation kernel, and provider controllers;
• the proposed API and Postgres model;
• workload identity and tenant attestation without global middleware exceptions;
• Daytona as the first controller and Composio triggers as the strongest reuse candidate;
• migration policy for the unshipped Daytona-specific migration;
• implementation sequencing, failure injection, acceptance tests, and explicit non-goals.

No API code, migration, worker, runner behavior, or deployment configuration is included. Implementation stays paused until the domain, workload-auth, ownership, and fencing decisions are approved.

Review focus

• Is managed_resources the right reusable boundary, or should durability remain controller-specific?
• Should the aggregate be called a resource set, realization, or something else?
• Which existing workload identity should authorize runner and worker control-plane calls?
• Which recovery facts may be stored as typed safe attributes without becoming arbitrary provider metadata?
• Who owns blocked-resource operations and alerting?

Tests / notes

• This branch is stacked on feat/daytona-secret-materialization, the head of PR [feat] Deliver agent credentials through Daytona Secrets #5277.
• The PR diff contains exactly seven new planning files under docs/design/agent-workflows/projects/managed-resource-reconciliation/.
• No production test suite was run because this PR changes documentation only.

[vercel]

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

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

[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: ab73a32d-2ff0-4eb3-ac50-75a99af9046d

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/managed-resource-reconciliation-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.}