Claim a branch

At the start of an agent run you usually want:

1. A fresh branch off the parent DB.
2. A scoped token pinned to that branch.
3. Both to expire when the run ends so you don’t accumulate forks.

claim_branch is the single call that does all three.

SDK

const lease = await db.branches.claim({
  purpose: "agent-run-fix-issue-742",
  ttlSec: 60 * 60,        // 1 hour, default
  role: "write",
});

// lease.branchRef       -> "agent-run-fix-issue-742-h7q2k"  (auto-generated)
// lease.token           -> "psql_live_…"  (returned once)
// lease.expiresAt       -> ISO timestamp; branch + token reach expire together

const sandbox = new PerSQL({ token: lease.token })
  .database(lease.namespaceSlug, lease.databaseSlug);
await sandbox.query("…");

Walk away when done. The branch’s expiresAt cleans up the DO; the scoped token, having no other branch to reach, becomes inert.

MCP

{
  "tool": "claim_branch",
  "input": {
    "database": "orders",
    "purpose": "agent-run-fix-issue-742",
    "ttlSec": 3600,
    "role": "write"
  }
}

Returns the same shape as the SDK.

Defaults

• ttlSec — 3600 (1 hour). Min 60, max 30 days (the existing branch TTL cap).
• role — write. Use read for analysis-only runs; admin if the agent needs to ALTER schema in the sandbox.
• ref — auto-generated from purpose + a 6-char random suffix. Pass ref explicitly if you want a deterministic name (e.g. pr-${prNumber} for CI).

Permissions

The minting bearer must be admin-role. The minted token is pinned to (databaseId, branchRef, role) via a token_scope row — even if the plaintext leaks, it can’t reach other branches in the namespace.