Document safe profile writer coordination

[IlyaasK]

What

• explain that profile saves replace the complete stored state rather than merging it
• document that the browser session ending last wins when multiple sessions save the same profile
• show how to find active writers with GET /browsers?status=active&query=<profileId> and profile_save_changes
• require an exact profile.id match because query searches multiple browser fields
• call out that concurrent workers still need a lock or lease around the check and browser creation

Why

kernel/kernel#3177 exposes profile_save_changes in browser responses. Customers can now identify active sessions that may overwrite a profile, but the Profiles guide did not explain the overwrite semantics or how to use the new field safely.

Customer impact

Customers get a concrete TypeScript, Python, and Go pattern for detecting active profile writers and guidance for preventing two workers from writing the same profile concurrently.

Related

• KERNEL-1687 — Expose active save_changes writers for a profile via the sessions API

Verification

• npx --yes mint@latest broken-links
• git diff --check

The generated API reference is unchanged and continues to update from the deployed OpenAPI specification.

---

Note

Low Risk
Documentation-only changes with no runtime, auth, or data-path impact.

Overview
Adds a Prevent concurrent profile writes section to the Profiles guide that explains full-profile overwrite semantics (no merge; last session to end wins) and how to detect active writers via GET /browsers?status=active&query=<profileId> plus profile_save_changes, with exact profile.id filtering because query is broad.

Includes TypeScript, Python, and Go examples that list active browsers and fail if another writer exists, plus guidance to use a lock or lease around the check and browser creation when workers run concurrently.

The Notes bullet on parallel profile use is tightened to describe overwrite behavior instead of vague “corruption” wording.

^{Reviewed by Cursor Bugbot for commit 16c91fd. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Kernel	🟢 Ready	View Preview	Aug 10, 2026, 7:14 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs	Error		Aug 11, 2026 1:27pm

[cursor]

Risk assessment: Very Low

Verdict: Risk unchanged after synchronize — prior approval stands (not re-approving).

Evidence (from diff only)

• 1 file changed vs main: auth/profiles.mdx (+63 / −1)
• Documentation-only update: new “Prevent concurrent profile writes” section with TypeScript/Python/Go examples for listing active writers via profile_save_changes, plus a Notes bullet clarifying last-write-wins overwrite semantics
• Latest push is a merge of main into the branch plus a one-line Notes wording tweak (save_changes: true on post-acquire attach); no new production/runtime surface in this PR’s delta vs main
• No application code, API implementation, config, CI, or infrastructure changes

Risk factors

Factor	Assessment
Codepaths / production logic	None modified
Blast radius	Docs site content only
Complexity	Straightforward guide + examples
Infra / security / auth model	Unaffected
User-facing surface	Documentation only

Re-evaluation after update

Previously approved at 431755f. Re-checked head 16c91fd after synchronize. Risk remains Very Low; no approval dismissal needed. No CODEOWNERS file requiring ownership review. Already approved — not submitting a new approval.

  

_{Sent by Cursor Automation: Assign PR reviewers}