feat(custody): /claude-account custody on|off for vault-served fallbacks

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 This repo is a CortexKit-maintained Anthropic auth monorepo for OpenCode and Pi. The OpenCode package is a fork of the original `@ex-machina/opencode-anthropic-auth` plugin, so older entries below the initial CortexKit release are inherited from upstream package history.
 
+## Unreleased
+
+### Patch Changes
+
+- Document `/claude-account custody <id> on|off`, including its fail-closed OpenCode behavior and Pi refusal.
+
 ## 1.22.0
 
 ### Minor Changes

README.md

@@ -303,6 +303,13 @@ OpenCode can obtain an opted-in fallback OAuth account's access credential from
 
 The request path reads only a resident in-memory credential. Startup warming and periodic custody ticks perform vault I/O and keep idle credentials refreshed; a cold or unavailable vault falls back to the sidecar credential path. Vault-served 401 reports carry the exact record version and response provenance, including relay-stream 401s, so a sidecar-served failure cannot invalidate a healthy vault credential. `/claude-account` and the OpenCode account modal show the gate, current vault service, and vault reauthentication state without exposing capability handles.
 
+Use `/claude-account custody <id> on|off` to change an eligible fallback OAuth account.
+`on` verifies a usable vault credential under the account refresh lock, then persists the gate. A failed check leaves the gate off.
+`off` persists first, invalidates the resident credential, and returns the account to sidecar service.
+Refusals are explicit: `Cannot change custody for the main account.`, `Custody requires an OAuth fallback account.`, and `Cannot enable custody for disabled account "<id>".`
+Vault failures report `No custody handle for <id>.`, `Claustrum is not available (...)`, `Vault reports the handle as unknown or revoked.`, `Vault credential needs re-login (...)`, or `Vault unavailable: ... Retry.`
+Pi accepts the command but refuses it with `Custody is OpenCode-only in this version.`
+
 Custody currently applies only to fallback OAuth accounts. Main-account vault service is not implemented. If Claustrum has replaced the main host credential with its provider-bound tombstone, the plugin rejects refresh locally without contacting Anthropic or persisting a permanent `invalid_grant` state.
 
 ## Quota-aware routing

packages/core/src/accounts.ts

@@ -1514,6 +1514,44 @@ export function isClaustrumEnabledForAccount(
   return storage.claustrum?.accounts?.[accountId]?.enabled === true
 }
 
+export async function setClaustrumAccountGatePersistent(input: {
+  id: string
+  enabled: boolean
+  path?: string
+}): Promise<'updated' | 'unchanged' | 'missing' | 'ineligible'> {
+  const path = input.path ?? getAccountStoragePath()
+  return enqueueSave(async () => {
+    const lock = await acquireAccountConfigWriteLock(path)
+    try {
+      const storage = await loadAccounts(path)
+      if (!storage) {
+        return 'missing'
+      }
+      const account = storage.accounts.find(
+        (candidate) => candidate.id === input.id,
+      )
+      if (!account) return 'missing'
+      if (!isOAuthAccount(account)) return 'ineligible'
+      if (isClaustrumEnabledForAccount(storage, input.id) === input.enabled) {
+        return 'unchanged'
+      }
+
+      const accounts = storage.claustrum?.accounts ?? {}
+      storage.claustrum = {
+        ...storage.claustrum,
+        accounts: {
+          ...accounts,
+          [input.id]: { ...accounts[input.id], enabled: input.enabled },
+        },
+      }
+      await saveAccountsWithConfigLock(storage, path, {})
+      return 'updated'
+    } finally {
+      await lock.release()
+    }
+  })
+}
+
 // ---------------------------------------------------------------------------
 // In-process save mutex — serializes all account-store writes so concurrent
 // read-modify-write callers (background timers that call saveAccountState with
@@ -1688,35 +1726,43 @@ async function saveAccountsLocked(
 ) {
   const lock = await acquireAccountConfigWriteLock(path)
   try {
-    const current = await loadAccounts(path)
-    const nextStorage: AccountStorage = {
-      ...storage,
-      accounts: mergeAccountsForSave(
-        current?.accounts ?? [],
-        storage.accounts,
-        options,
-      ),
-    }
-    const existing = await loadExistingTopLevelFields(path)
-    const nextConfig = { ...existing, ...configFromStorage(nextStorage) }
-    await writeJsonAtomic(path, nextConfig)
-    // Config precedes state everywhere both locks are needed; reversing this
-    // order can deadlock profile mutations against full account saves.
-    const stateLock = await acquireAccountStateWriteLock(path)
-    try {
-      await saveAccountStateUnlocked(nextStorage, path, {
-        mainQuota: true,
-        mainRefresh: true,
-        accounts: true,
-      })
-    } finally {
-      await stateLock.release()
-    }
+    await saveAccountsWithConfigLock(storage, path, options)
   } finally {
     await lock.release()
   }
 }
 
+async function saveAccountsWithConfigLock(
+  storage: AccountStorage,
+  path: string,
+  options: SaveAccountsOptions,
+) {
+  const current = await loadAccounts(path)
+  const nextStorage: AccountStorage = {
+    ...storage,
+    accounts: mergeAccountsForSave(
+      current?.accounts ?? [],
+      storage.accounts,
+      options,
+    ),
+  }
+  const existing = await loadExistingTopLevelFields(path)
+  const nextConfig = { ...existing, ...configFromStorage(nextStorage) }
+  await writeJsonAtomic(path, nextConfig)
+  // Config precedes state everywhere both locks are needed; reversing this
+  // order can deadlock profile mutations against full account saves.
+  const stateLock = await acquireAccountStateWriteLock(path)
+  try {
+    await saveAccountStateUnlocked(nextStorage, path, {
+      mainQuota: true,
+      mainRefresh: true,
+      accounts: true,
+    })
+  } finally {
+    await stateLock.release()
+  }
+}
+
 function applyMainProfileStatePatch(
   state: AccountRuntimeState,
   storage: AccountStorage,
@@ -3811,6 +3857,7 @@ export class FallbackAccountManager {
   private readonly fetchImpl: typeof fetch
   private readonly configPath: string
   private readonly refreshPromises = new Map<string, Promise<OAuthAccount>>()
+  private readonly custodyVerificationAccounts = new Set<string>()
   private refreshTimer: ReturnType<typeof setInterval> | null = null
   private quotaTimer: ReturnType<typeof setInterval> | null = null
   readonly quotaManager: import('./quota-manager.ts').QuotaManager | null
@@ -3921,6 +3968,27 @@ export class FallbackAccountManager {
     this.quotaTimer = null
   }
 
+  async withAccountRefreshLock<T>(
+    accountId: string,
+    fn: () => Promise<T>,
+  ): Promise<T> {
+    const lock = await acquireRefreshFileLock({
+      name: fallbackRefreshLockName(accountId),
+      ttlMs: FALLBACK_REFRESH_LOCK_TTL_MS,
+      path: this.configPath,
+      now: this.now,
+      renew: true,
+    })
+    if (!lock) throw new Error('Fallback OAuth refresh is already in progress')
+    this.custodyVerificationAccounts.add(accountId)
+    try {
+      return await fn()
+    } finally {
+      this.custodyVerificationAccounts.delete(accountId)
+      await lock.release()
+    }
+  }
+
   async getUsableFallbackAccounts(
     existingStorage?: AccountStorage | null,
     options: { modelId?: string } = {},
@@ -4078,6 +4146,16 @@ export class FallbackAccountManager {
     let changed = false
     for (const account of storage.accounts) {
       if (account.enabled === false || !isOAuthAccount(account)) continue
+      if (this.custodyVerificationAccounts.has(account.id)) {
+        logger.debug(
+          'refresh',
+          'fallback oauth background skipped custody verification',
+          {
+            accountId: account.id,
+          },
+        )
+        continue
+      }
       if (
         !tokenNeedsRefresh(account, storage, this.now()) ||
         this.isFallbackAccountVaultEnabled(account.id, storage) ||

packages/core/src/claustrum.ts

@@ -638,6 +638,7 @@ export class ClaustrumCredentialCache {
   async get(
     handle: string,
     minTtlMs = this.#minTtlMs,
+    options: { cacheIf?: () => boolean } = {},
   ): Promise<ClaustrumCredential> {
     if (!Number.isSafeInteger(minTtlMs) || minTtlMs < 0) {
       throw new RangeError('minTtlMs must be a non-negative safe integer')
@@ -658,7 +659,7 @@ export class ClaustrumCredentialCache {
     const pending = this.#inFlight.get(handle)
     if (pending) return pending
 
-    const load = this.#load(handle, minTtlMs)
+    const load = this.#load(handle, minTtlMs, options.cacheIf)
     this.#inFlight.set(handle, load)
     try {
       return await load
@@ -671,6 +672,10 @@ export class ClaustrumCredentialCache {
     return this.#cache.get(handle)
   }
 
+  abandonPending(handle: string): void {
+    this.#inFlight.delete(handle)
+  }
+
   seedForTest(handle: string, credential: ClaustrumCredential): void {
     this.#cache.set(handle, credential)
   }
@@ -787,7 +792,11 @@ export class ClaustrumCredentialCache {
       })
   }
 
-  async #load(handle: string, minTtlMs: number): Promise<ClaustrumCredential> {
+  async #load(
+    handle: string,
+    minTtlMs: number,
+    cacheIf?: () => boolean,
+  ): Promise<ClaustrumCredential> {
     let response: unknown
     try {
       response = await this.#client.call(
@@ -813,7 +822,8 @@ export class ClaustrumCredentialCache {
     }
     if (
       credential.expiresAtMs !== null &&
-      credential.expiresAtMs > this.#now()
+      credential.expiresAtMs > this.#now() &&
+      (cacheIf?.() ?? true)
     ) {
       this.#cache.set(handle, credential)
     }