borgmcp 2.0.1 → 2.0.3

package/docs/LOCAL_SERVER.md

@@ -4,52 +4,92 @@ Install and initialize the server in the human operator's terminal:
 
 ```bash
 npm install -g borgmcp-server
-borg-mcp-server setup
-borg-mcp-server start
+borg server setup
+borg server start
 ```
 
-Keep the server running. Open a second operator terminal in the project checkout
-and run:
+The client owns the `borg server` facade. It forwards commands and renders
+verified server evidence. It does not infer a checkout, activate an artifact,
+create a service, or claim a build identity by itself. The server owns artifact
+verification, activation, data and identity preservation, runtime build
+identity, rollback, and explicit Linux/macOS service adapters. The server
+executable remains the direct foreground authority.
+
+`borg server start` and `borg-mcp-server start` are foreground commands. They
+must never imply that a daemon, LaunchAgent, or systemd service was installed.
+Ctrl-C stops the foreground process. Managed persistence is a separate explicit
+handoff.
+
+The available lifecycle facade commands are:
+
+```text
+Usage: borg server <command> [arguments]
+
+Commands:
+  setup    Prepare local server identity and data; does not start the server.
+  start    Start the verified server in the foreground.
+  status   Report verified runtime evidence.
+  update   Verify and activate a local server artifact.
+  invite   Create a single-use invitation in an interactive terminal.
+
+Run borg server <command> --help for server command options.
+```
+
+Local server client credentials are stored in the owner-controlled
+`~/.borg/credentials` file with mode 0600. Fresh same-machine setup provisions
+the first owner record there, so bare `borg assimilate` can use it without an
+invitation prompt. Use `borg server invite` explicitly when another client or
+device needs a single-use invitation; its output is owned by the server.
+
+Status reports only runtime evidence supplied by the server: running/stopped
+state, exact running artifact and immutable build identity when available,
+endpoint, process mode, and data-identity availability. If the running build
+identity is unavailable, status says it is unavailable. It never substitutes a
+source checkout, package cache, or guessed version.
+
+Update has four visible phases: verification, activation, result, and next
+action. Only a verified artifact may activate. A verification failure says no
+activation occurred and that the last verified runtime remains available.
+
+Keep the foreground server running. Open a second operator terminal in the
+project checkout and run:
 
 ```bash
-borg assimilate --host 127.0.0.1:7091 --enroll
+borg assimilate
 ```
 
-The labeled hidden prompt awaits the owner enrollment invitation (single-use,
-shown once). An owner enrollment invitation comes from setup or the offline
-`borg-mcp-server owner-invite` recovery command. A later ordinary client uses a
-client enrollment invitation from `borg-mcp-server client-invite`. Never put an
-enrollment invitation in argv, environment variables, logs, or diagnostics.
-The offline replacement commands visibly prompt for the recovery credential;
-never put that credential in argv or environment variables either.
-
-Before sending the invitation,
-the client generates a 256-bit credential and UUID retry key and persists the
-exact tuple as `PENDING` in the local seat store on this machine — a
-0600-permission file store, parity with the server's TLS keys. An ambiguous
-exchange retries that tuple exactly; the credential becomes active only after the
-versioned response is decoded and the authenticated protocol handshake succeeds.
-A new process resumes that pending enrollment before displaying another
-invitation prompt.
+Setup provisions the first same-machine owner credential directly, so this flow
+does not ask for an invitation. For another client or device, run `borg server
+invite` in the server operator's interactive terminal. On the intended recipient,
+run `borg assimilate --host <server> --enroll` and enter the single-use invitation
+at the labeled hidden prompt. Never put an invitation in argv, environment
+variables, logs, or diagnostics.
+
+For explicit invitation enrollment, the client generates a 256-bit credential
+and UUID retry key and persists the exact tuple as `PENDING` in the 0600
+credential file before network I/O. An ambiguous exchange retries that tuple
+exactly; the credential becomes active only after the versioned response is
+decoded and the authenticated protocol handshake succeeds. A new process
+resumes that pending enrollment before displaying another invitation prompt.
 
 `--cube-name <name>` explicitly selects the repository cube name. Without an
 explicit name, Borg uses the `origin` repository name or, when `origin` is
-absent, proposes the sanitized repository-directory basename before consuming
-an enrollment invitation. Confirm interactively or pass `--yes`; bare
-repositories fail closed.
+absent, proposes the sanitized repository-directory basename. Confirm
+interactively or pass `--yes`; bare repositories fail closed.
 
 The connection is HTTPS-only. Borg validates the server trust material, stores
-enrollment and session credentials in the local seat store on this machine (a
-0600-permission file store), and persists only an opaque credential reference
-with the active cube. Local requests
+parent enrollment credentials in `~/.borg/credentials` and session credentials
+in the existing 0600 seat store, and persists only an opaque credential
+reference with the active cube. Local requests
 use the server's `/api/cubes/*` coordination routes. They cannot use hosted OAuth
 credentials or change authority implicitly.
 
-The current client does not install or start `borgmcp-server`. The server must
-already be running and trusted. An owner enrollment carrying the persisted
-`create_cube` capability creates one idempotent cube per repository during
-normal assimilation, using the server-owned `default` role template; repeating
-an ambiguous request does not duplicate the cube, and distinct repositories can
+The lifecycle facade invokes the separately installed `borgmcp-server`; it does
+not bundle the server into the client. The server must be running and trusted
+before assimilation. An owner enrollment carrying the persisted `create_cube`
+capability creates one idempotent cube per repository during normal
+assimilation, using the server-owned `default` role template; repeating an
+ambiguous request does not duplicate the cube, and distinct repositories can
 create distinct bounded cubes. An ordinary enrolled client is denied before a
 create request is sent. Cloud-only capabilities fail explicitly rather than
 being redirected.
@@ -73,20 +113,19 @@ The default discovery endpoint is `https://127.0.0.1:7091`. Explicit `--host` va
 
 ## Recovery commands
 
-- No saved or rejected enrollment: rerun `borg assimilate --host <server> --enroll`
-  from the operator's interactive terminal.
+- No saved or rejected enrollment: generate a single-use invitation with
+  `borg server invite`, then run `borg assimilate --host <server> --enroll` from
+  the intended recipient's interactive terminal.
 - Rejected or expired invitation: keep the server running and mint a replacement
-  scoped invitation with `borg-mcp-server owner-invite` for an unclaimed owner
-  client or `borg-mcp-server client-invite` for an ordinary client, then rerun
-  `borg assimilate --host <server> --enroll` with the replacement invitation.
+  invitation with `borg server invite`, then rerun `borg assimilate --host
+  <server> --enroll` with the replacement invitation.
 - Rejected or unloadable local seat: run `borg reset-local-seat --host <server>`
-  to clear ONLY this worktree's saved local seat, then — with the server still
-  running — ask the operator for a fresh scoped invitation and rerun
-  `borg assimilate --host <server> --enroll`.
-- Unreachable server: start or restart it with `borg-mcp-server start`, then
+  to clear ONLY this worktree's saved local seat, then rerun `borg assimilate
+  --host <server>` with the server still running.
+- Unreachable server: start or restart it with `borg server start`, then
   rerun `borg assimilate --host <server>`.
 - Trust mismatch after an intentional server re-initialization: verify the
-  expected server identity, stop and restart `borg-mcp-server start`, then retry.
+  expected server identity, stop and restart `borg server start`, then retry.
 - Busy local seat store: wait for the other Borg process to finish, then rerun
   the same command. If the local seat store cannot be read or written, ensure its
   directory on this machine is readable and writable, then rerun.
@@ -96,7 +135,7 @@ The default discovery endpoint is `https://127.0.0.1:7091`. Explicit `--host` va
 
 ## Release status
 
-This self-hosted path consumes the published `borgmcp-shared@0.4.2` v2 registry
+This self-hosted path consumes the published `borgmcp-shared@0.4.3` v2 registry
 release. The matching server owner-enrollment, cube-create, attach, restart, log,
 and SSE implementation must also pass the full process-level local dogfood gate.
 Until that gate opens the self-hosted path remains preview-only, and the client

package/docs/RELEASING.md

@@ -4,15 +4,33 @@ The GitHub Actions workflow publishes one immutable, reviewed `borgmcp` version
 from a protected annotated tag. The protected publish job uses npm Trusted
 Publishing; no long-lived npm token is stored or exposed.
 
-## Immutable Failed Release Evidence
+## Immutable Release Evidence
 
 The existing lightweight `v2.0.0` tag points to
 `90a078264f4d61c0140ad0a30357a4df42c34ab0`. Immutable workflow run
 `29693915689` rejected it at annotated-tag verification and failed before package
 creation or npm publication; the publish job was skipped and
 `borgmcp@2.0.0` remains absent from npm. Never delete, move, replace, reuse, or
-rerun that tag or run. Recovery uses the unused `v2.0.1` identity from a fresh
-reviewed protected-main commit and requires the complete release gate again.
+rerun that tag or run.
+
+The annotated `v2.0.1` tag object
+`def12ee40af665fc6c3af4873a7d566b3f844fc1` peels to protected-main commit
+`b30fc54a4d73bda98db4630864cca796c8923dd9`. Workflow run `29748931957`
+successfully published that exact source as `borgmcp@2.0.1`; the registry records
+integrity
+`sha512-Ah8IY2izZ774gYLKthRL9lfrV+JBk2o9HSlrWUplyZgoGqwVjVboHNon0hWWF5i/fObiCGikFOMY6qZ+vaeyCw==`.
+Never move, replace, reuse, or rerun that tag or workflow. The next candidate
+must use a fresh unused identity and requires the complete release gate again.
+
+The annotated `v2.0.2` tag object
+`a1fc1f8f05c3f1b4d7ccbef86e244955642165b5` peels to protected-main commit
+`aced84956fdf41315904c8901e50a345f628152c`. Workflow run `29840120451`
+successfully published that exact source as `borgmcp@2.0.2`; the registry records
+integrity
+`sha512-w0O0t/2wzeJpXEqb4jQGuqZeavEkfFKdz6poRT8q1TxDKHTlOlwo3auctE+X1kWU2s5JkSDcUiUdQdyLwu84IA==`.
+Never move, replace, reuse, or rerun that tag or workflow. The next candidate
+uses the unused `v2.0.3` identity from a fresh reviewed protected-main commit
+and requires the complete release gate again.
 
 ## Release Prerequisites
 
@@ -23,7 +41,7 @@ Before creating the release tag, independently verify all of these conditions:
 - the extraction review confirms no private backend secrets, deployment
   configuration, customer data, local state, or duplicated shared contracts
   entered the public package;
-- the exact audited registry dependency `borgmcp-shared@0.4.2` remains locked to
+- the exact audited registry dependency `borgmcp-shared@0.4.3` remains locked to
   its canonical tarball and integrity;
 - the client and matching server pass the complete local dogfood gate;
 - the selected stable client version is unused and the exact release commit is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "Coordinate AI coding agents in shared cubes. Works with Claude Code, Codex, and OpenCode.",
   "type": "module",
   "main": "./dist/index.js",
@@ -68,7 +68,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
-    "borgmcp-shared": "0.4.2",
+    "borgmcp-shared": "0.4.3",
     "chalk": "^5.3.0",
     "prompts": "^2.4.2",
     "which": "^4.0.0"

package/src/claude.ts

@@ -14,6 +14,7 @@
  *                         fresh drone inside it (see spawn.ts)
  *   borg sync           → Advance the current worktree across the 5
  *                         lifecycle states (see sync.ts, gh#33)
+ *   borg server <cmd>   → Forward a lifecycle command to borg-mcp-server
  */
 
 import { spawn } from 'child_process';
@@ -78,8 +79,12 @@ import { ensureCliMcpConfigured } from './ensure-mcp-config.js';
 import { installBorgPlugin } from './opencode-plugin.js';
 import { connectOpenCodeDrone, computeOpenCodePort, createOpenCodeLaunchKickoff, injectInitialKickoff } from './opencode-drone.js';
 import { buildOpenCodeLaunchArgs, defaultApprovalIo, resolveLaunchBorgApprovals } from './cli-tool-approval.js';
+import { runEarlyServerFacade } from './server-facade.js';
 
 async function main() {
+  const serverExitCode = await runEarlyServerFacade(process.argv);
+  if (serverExitCode !== null) process.exit(serverExitCode);
+
   // `--debug` / BORG_DEBUG: enable HTTP request/response logging to stderr
   // (observability for failures like the cross-account assimilate 404).
   // Done first so debug covers everything below; strips `--debug` from argv

package/src/cli-help.ts

@@ -36,12 +36,27 @@ export function topLevelHelpText(version: string): string {
     `  borg launch-all [cube]   Launch all drone worktrees of a cube (default: active cube)\n` +
     `  borg launch-all [cube] --cli claude|codex|opencode\n` +
     `                           Launch all drone worktrees with that agent CLI\n` +
+    `  borg server <command> [arguments]\n` +
     `  borg --cli claude|codex|opencode  Launch that agent CLI directly\n` +
     `  borg --version           Show installed version\n\n` +
     `All other arguments are passed through to the selected agent CLI.\n`
   );
 }
 
+/** Product Design-approved client-owned copy for `borg server --help`. */
+export function serverHelpText(): string {
+  return (
+    `Usage: borg server <command> [arguments]\n\n` +
+    `Commands:\n` +
+    `  setup    Prepare local server identity and data; does not start the server.\n` +
+    `  start    Start the verified server in the foreground.\n` +
+    `  status   Report verified runtime evidence.\n` +
+    `  update   Verify and activate a local server artifact.\n` +
+    `  invite   Create a single-use invitation in an interactive terminal.\n\n` +
+    `Run borg server <command> --help for server command options.\n`
+  );
+}
+
 /**
  * Help text for `borg assimilate --help` — the home for the full assimilate flag
  * set. Model/provider configuration belongs to the selected agent CLI.

package/src/codex-app-wake.ts

@@ -1,6 +1,12 @@
-import { getActiveCube, getCodexWakeTarget, setCodexWakeTarget } from './cubes.js';
+import {
+  getActiveCube,
+  getCodexWakeTarget,
+  setCodexWakeTarget,
+  type ActiveCube,
+} from './cubes.js';
 import { CodexAppServerClient } from './codex-app-server.js';
 import { checkCodexBridgeHealthy } from './codex-remote.js';
+import { hasPendingWakeActivity } from './remote-client.js';
 import {
   BORG_CODEX_REMOTE_WAKE_ENV,
   resolveSessionAgentKind,
@@ -176,6 +182,10 @@ export interface CodexWakeDeps {
   // WAKE_RETRY_MAX_ATTEMPTS); small values let tests prove the loop terminates
   // under a non-advancing clock without running thousands of iterations.
   maxAttempts?: number;
+  // client#76: token-free, non-mutating preflight for the periodic backstop.
+  // Per-entry and retry-drain paths do not use this: their pending obligation is
+  // already established by a concrete delivered/deferred event.
+  hasPendingWork?: (active: ActiveCube) => Promise<boolean>;
   // gh#861 finding 2: lease-ownership gate for the heartbeat tick — a lease-LOSING
   // duplicate child must NOT tick/inject (symmetry with the per-entry path, which
   // only fires inside an SSE session that holds the stream lease). Heartbeat-only;
@@ -403,16 +413,13 @@ async function runRetryDrainLoop(deps: CodexWakeDeps): Promise<void> {
 export const CODEX_HEARTBEAT_CADENCE_MS = 20 * 60_000;
 
 /**
- * gh#857 WI-2: one tick of the codex /loop-equivalent heartbeat — a periodic,
- * independent re-engagement that injects a borg_read-log (unread_only=true) DRAIN turn so an
- * idle codex drone re-syncs even if every per-entry wake was missed. SKIPS when a
- * delivery (per-entry wake, retry-drain, or a prior heartbeat) already landed
- * within the cadence window (shouldFireHeartbeat), so an active cube with flowing
- * wakes never gets a redundant injection. Unlike the per-entry path it does NOT
- * consult deliveredWakeKeys — the cadence gate is the throttle, and the static
- * drain prompt is intentionally re-delivered each idle window. Best-effort: a
- * mid-turn thread / transient error / unresolved target just skips this tick (the
- * next tick retries). Never throws.
+ * gh#857/client#76: one tick of the codex catch-up backstop. The cadence only
+ * initiates a token-free unread-state preflight; a DRAIN turn is injected when
+ * that authoritative scan finds real work that a per-entry wake missed. Recent
+ * delivery still suppresses redundant preflights. Unlike the per-entry path it
+ * does not consult deliveredWakeKeys because the unread cursor is authoritative.
+ * Best-effort: a failed preflight, mid-turn thread, transient error, or unresolved
+ * target skips this tick and lets the next cadence retry. Never throws.
  */
 export async function fireCodexHeartbeatTick(
   deps: CodexWakeDeps = {},
@@ -434,6 +441,11 @@ export async function fireCodexHeartbeatTick(
   try {
     const active = await (deps.getActiveCube ?? getActiveCube)();
     if (!active) return;
+    // Elapsed time alone must never cross the model boundary. Query the
+    // authoritative unread state without advancing its cursor; only then touch
+    // the app-server socket or resolve a thread.
+    const hasPendingWork = deps.hasPendingWork ?? hasPendingWakeActivity;
+    if (!(await hasPendingWork(active))) return;
     const resolved = await resolveFreshCodexWakeTarget(active, deps);
     if (!resolved) return; // thread not loaded yet → next tick retries
     const client = makeCodexClient(resolved.socketPath, deps);

package/src/codex-wake-resolve.ts

@@ -140,10 +140,10 @@ export function wakeRetryExpired(
 }
 
 /**
- * WI-2 double-fire avoidance: the periodic heartbeat fires only when no wake (or
- * prior heartbeat) delivery landed within the cadence window — so an active cube
- * with flowing per-entry wakes doesn't get redundant heartbeat injections. A
- * never-delivered seat (null) always fires.
+ * WI-2 double-fire avoidance: the periodic catch-up preflight runs only when no
+ * wake delivery landed within the cadence window. A never-delivered seat (null)
+ * is eligible for preflight; client#76 separately requires pending unread work
+ * before a model turn can start.
  */
 export function shouldFireHeartbeat(
   lastDeliveredAt: number | null,

package/src/config.ts

@@ -1,14 +1,11 @@
 /**
  * Secure local-server credential storage.
  *
- * The self-hosted-server credential group (enrollment credentials, pending
- * enrollment/cube-creation records, and the per-seat drone-session bearers)
- * rests ONLY in the 0600 credential file store (Queen rescope) — parity with the
- * server's own TLS private keys. The OS keychain is gone; the raw secret never
- * leaves the 0600 file, and a single store flock serializes every read-compare-write.
+ * Parent enrollment credentials and pending enrollment/cube-creation records
+ * rest ONLY in the canonical 0600 credential file. Per-seat session credentials
+ * remain in the separate seat store. A single flock serializes every parent-store
+ * read-compare-write shared by client enrollment and same-machine server setup.
  */
-import os from 'os';
-import path from 'path';
 import { createHash, randomBytes, randomUUID } from 'crypto';
 import type { ServerCapability } from 'borgmcp-shared/protocol';
 import { withStoreLock } from './seat-store.js';
@@ -16,14 +13,15 @@ import {
   makeFileBackend,
   type TokenBackend,
 } from './token-store.js';
+import { BORG_USER_ROOT, SERVER_CREDENTIALS_FILE } from './credential-paths.js';
 
 const SERVER_CREDENTIAL_RECORD_VERSION = 2 as const;
 const SERVER_PENDING_ENROLLMENT_RECORD_VERSION = 1 as const;
 const SERVER_CUBE_RETRY_RECORD_VERSION = 1 as const;
 // The 0600 credential store (Queen rescope: replaces the OS keychain). A single
-// file holds every server credential/session/enrollment record; a single flock
+// file holds every parent credential/enrollment record; a single flock
 // serializes every mutator + observer that must (SR-seven #4).
-const CREDENTIALS_FILE = path.join(os.homedir(), '.config', 'borgmcp', 'credentials.json');
+const CREDENTIALS_FILE = SERVER_CREDENTIALS_FILE;
 const CREDENTIALS_LOCK = `${CREDENTIALS_FILE}.lock`;
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
@@ -199,15 +197,39 @@ function serverCubeRetryAccount(
 // parity with the server's TLS keys; no OS keychain, no obfuscation-grade
 // fallback). The single store lock (CREDENTIALS_LOCK) serializes the RCW.
 let serverCredentialBackendPromise: Promise<TokenBackend> | null = null;
+let testBackendInjected = false;
+let testLockTail: Promise<void> = Promise.resolve();
+async function withCredentialStoreLock<T>(operation: () => Promise<T>): Promise<T> {
+  if (!testBackendInjected) {
+    return withStoreLock(CREDENTIALS_LOCK, operation, {
+      secureRoot: BORG_USER_ROOT,
+      rootMode: 'owner-controlled',
+    });
+  }
+  const prior = testLockTail;
+  let release!: () => void;
+  testLockTail = new Promise<void>((resolveLock) => { release = resolveLock; });
+  await prior;
+  try {
+    return await operation();
+  } finally {
+    release();
+  }
+}
 async function getServerCredentialBackend(): Promise<TokenBackend> {
   if (!serverCredentialBackendPromise) {
-    serverCredentialBackendPromise = Promise.resolve(makeFileBackend(CREDENTIALS_FILE));
+    serverCredentialBackendPromise = Promise.resolve(makeFileBackend(CREDENTIALS_FILE, {
+      secureRoot: BORG_USER_ROOT,
+      rootMode: 'owner-controlled',
+    }));
   }
   return serverCredentialBackendPromise;
 }
 
 /** Test-only credential-store backend injection. */
 export function __setServerCredentialBackendForTest(backend: TokenBackend | null): void {
+  testBackendInjected = backend !== null;
+  testLockTail = Promise.resolve();
   serverCredentialBackendPromise = backend ? Promise.resolve(backend) : null;
 }
 
@@ -252,7 +274,7 @@ async function writeServerCredentialRecord(
  */
 export async function storeServerCredential(record: ServerCredentialRecord): Promise<void> {
   const backend = await getServerCredentialBackend();
-  await withStoreLock(CREDENTIALS_LOCK, () => writeServerCredentialRecord(backend, record));
+  await withCredentialStoreLock(() => writeServerCredentialRecord(backend, record));
 }
 
 /** Read an authority-bound active client record, failing closed on corruption. */
@@ -346,7 +368,7 @@ export async function getPendingServerEnrollment(
   validateServerCredentialBinding(origin, trustIdentity);
   const backend = await getServerCredentialBackend();
   const account = serverPendingEnrollmentAccount(origin, trustIdentity);
-  return withStoreLock(CREDENTIALS_LOCK, async () => {
+  return withCredentialStoreLock(async () => {
     const stored = await backend.get(account);
     if (!stored) return null;
     try {
@@ -375,7 +397,7 @@ export async function getOrCreatePendingServerEnrollment(
   validateClientName(input.clientName);
   const backend = await getServerCredentialBackend();
   const account = serverPendingEnrollmentAccount(input.origin, input.trustIdentity);
-  return withStoreLock(CREDENTIALS_LOCK, async () => {
+  return withCredentialStoreLock(async () => {
     const stored = await backend.get(account);
     if (stored) {
       try {
@@ -432,7 +454,7 @@ export async function activatePendingServerEnrollment(
   const serverCapabilities = validateServerCapabilities(input.serverCapabilities);
   const backend = await getServerCredentialBackend();
   const pendingAccount = serverPendingEnrollmentAccount(input.origin, input.trustIdentity);
-  await withStoreLock(CREDENTIALS_LOCK, async () => {
+  await withCredentialStoreLock(async () => {
     const stored = await backend.get(pendingAccount);
     if (!stored) throw new Error('pending Borg server enrollment is missing');
     try {
@@ -469,7 +491,7 @@ export async function clearPendingServerEnrollment(
   validateUuid(retryKey, 'enrollment retry key');
   const backend = await getServerCredentialBackend();
   const account = serverPendingEnrollmentAccount(origin, trustIdentity);
-  await withStoreLock(CREDENTIALS_LOCK, async () => {
+  await withCredentialStoreLock(async () => {
     const stored = await backend.get(account);
     if (!stored) return;
     try {
@@ -510,7 +532,7 @@ export async function getOrCreatePendingServerCubeCreation(
     input.clientId,
     repositoryBinding,
   );
-  return withStoreLock(CREDENTIALS_LOCK, async () => {
+  return withCredentialStoreLock(async () => {
     const stored = await backend.get(account);
     if (stored) {
       try {
@@ -572,7 +594,7 @@ export async function clearPendingServerCubeCreation(
     record.clientId,
     record.repositoryBinding,
   );
-  await withStoreLock(CREDENTIALS_LOCK, async () => {
+  await withCredentialStoreLock(async () => {
     const stored = await backend.get(account);
     if (!stored) return;
     try {
@@ -588,7 +610,7 @@ export async function clearPendingServerCubeCreation(
 export async function clearServerCredential(origin: string, trustIdentity: string): Promise<void> {
   const backend = await getServerCredentialBackend();
   const pendingAccount = serverPendingEnrollmentAccount(origin, trustIdentity);
-  await withStoreLock(CREDENTIALS_LOCK, async () => {
+  await withCredentialStoreLock(async () => {
     await backend.delete(serverCredentialAccount(origin, trustIdentity));
     await backend.delete(pendingAccount);
   });

package/src/credential-paths.ts

@@ -0,0 +1,8 @@
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const canonicalHome = realpathSync(homedir());
+
+export const BORG_USER_ROOT = join(canonicalHome, '.borg');
+export const SERVER_CREDENTIALS_FILE = join(BORG_USER_ROOT, 'credentials');