borgmcp 5.4.0 → 5.5.0

package/src/representative-mcp.ts

@@ -0,0 +1,209 @@
+/**
+ * Restricted stdio MCP facade for the human representative.
+ *
+ * A Borg server speaks pinned-TLS HTTPS, not MCP, so a generic MCP host reaches
+ * it through this local stdio process. The surface is four tools: status, send
+ * (to the ONE bound Coordinator), read (that Coordinator's replies) and ack.
+ * There is deliberately no log/broadcast/dispatch, roster-management, grant,
+ * evict, release, regen or server-lifecycle tool, and no dispatcher escape hatch.
+ *
+ * The connection context is resolved per call and injected, so the same facade
+ * runs over the real seat-scoped backend or a controlled test backend.
+ */
+
+import { ErrorCode } from 'borgmcp-shared/protocol';
+import type { Readable, Writable } from 'node:stream';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import {
+  REPRESENTATIVE_DELIVERY_NOTE,
+  REPRESENTATIVE_MESSAGE_LIMIT_BYTES,
+  RepresentativeError,
+  ackRepresentativeReply,
+  readRepresentativeReplies,
+  representativeStatus,
+  sendRepresentativeMessage,
+  type RepresentativeContext,
+} from './representative-core.js';
+import { RepresentativeStoreError } from './representative-store.js';
+import { createRepresentativeOwner } from './representative-owner.js';
+
+export const REPRESENTATIVE_TOOL_NAMES = [
+  'borg_representative-status',
+  'borg_representative-send',
+  'borg_representative-read',
+  'borg_representative-ack',
+] as const;
+
+export const REPRESENTATIVE_INSTRUCTIONS =
+  'You are connected as the human representative of one Borg cube: an automated delegate that relays the ' +
+  'human\'s requests, questions and decisions to ONE bound Coordinator drone and reads its replies. You are not the ' +
+  'Coordinator and not the human: never plan or dispatch work for other drones — the Coordinator does that. ' +
+  'Mark content user_authorized ONLY when the human explicitly said it; everything you originate is model_advice. ' +
+  'A relayed decision authorizes only its own text, never broader approval. ' +
+  REPRESENTATIVE_DELIVERY_NOTE;
+
+const TOOLS = [
+  {
+    name: 'borg_representative-status',
+    description:
+      'Show which cube, representative drone and Coordinator this connection is bound to, whether the live cube still matches, ' +
+      'any unresolved (ambiguous) sends, process ownership and the delivery limits. Read-only; never takes ownership.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'borg_representative-send',
+    description:
+      'Relay ONE human request, question or decision to the bound Coordinator. The recipient is fixed; workers and broadcast ' +
+      'are not addressable. Returns a request_id. If the outcome is "ambiguous" (the result names the cause), retry only ' +
+      'with the SAME request_id and identical content (server-deduplicated); never re-send under a new id. A ' +
+      'SEND_REJECTED error names the refusal and its recovery. Do not issue overlapping sends of the same content.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        kind: { type: 'string', enum: ['request', 'question', 'decision'] },
+        authorization: {
+          type: 'string',
+          enum: ['user_authorized', 'model_advice'],
+          description:
+            'user_authorized: the human explicitly said/approved this exact content. model_advice: your own suggestion. ' +
+            'A decision must be user_authorized.',
+        },
+        message: { type: 'string', description: `Plain text, at most ${REPRESENTATIVE_MESSAGE_LIMIT_BYTES} bytes.` },
+        request_id: {
+          type: 'string',
+          description: 'Omit for a new request. To retry, pass the request_id returned earlier with identical content.',
+        },
+      },
+      required: ['kind', 'authorization', 'message'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'borg_representative-read',
+    description:
+      'Read unread replies from the bound Coordinator addressed to this representative. Replies arrive only when this tool ' +
+      'is called; there is no background wake. Each call DRAINS the whole fetched unread page for this drone — returned ' +
+      'replies and ignored entries alike (other drones\' entries are counted, never returned) — so they will not appear ' +
+      'unread again: persist the result, then route each reply by in_reply_to to its conversation or hold it for the human. If the host stops before persisting, the reply ' +
+      'is no longer in the unread view.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        include_broadcast: { type: 'boolean', description: 'Also return the Coordinator\'s cube-wide broadcasts (marked as such).' },
+        limit: {
+          type: 'integer', minimum: 1, maximum: 200,
+          description: 'Page-size hint, not a hard cap: a large unread backlog may return (and drain) more entries.',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'borg_representative-ack',
+    description:
+      'Signal to the Coordinator that one of its direct replies (entry_id from borg_representative-read) was received. ' +
+      'It is only that signal: it does not make delivery reliable, does not move or restore the unread cursor, and is ' +
+      'not needed for reading.',
+    inputSchema: {
+      type: 'object',
+      properties: { entry_id: { type: 'string' } },
+      required: ['entry_id'],
+      additionalProperties: false,
+    },
+  },
+] as const;
+
+function errorBody(error: unknown): { error: { code: string; message: string; details?: unknown } } {
+  if (error instanceof RepresentativeError || error instanceof RepresentativeStoreError) {
+    const details = error instanceof RepresentativeError ? error.details : undefined;
+    return { error: { code: error.code, message: error.message, ...(details ? { details } : {}) } };
+  }
+  const code = (error as { code?: unknown } | null)?.code;
+  return {
+    error: {
+      code: typeof code === 'string' ? code : 'BACKEND_ERROR',
+      message: error instanceof Error ? error.message : 'Unknown error',
+    },
+  };
+}
+
+const toolResult = (body: unknown, isError = false) => ({
+  content: [{ type: 'text' as const, text: JSON.stringify(body, null, 2) }],
+  ...(isError ? { isError: true } : {}),
+});
+
+export interface ServeRepresentativeOptions {
+  /** Resolved on every call; a throw fails that call closed. */
+  context: () => Promise<RepresentativeContext>;
+  version: string;
+  stdin?: Readable;
+  stdout?: Writable;
+  /** Internal timing seam for heartbeat controls; production uses 20 seconds. */
+  heartbeatIntervalMs?: number;
+}
+
+export async function serveRepresentativeMcp(
+  options: ServeRepresentativeOptions,
+): Promise<{ close: () => Promise<void>; closed: Promise<void> }> {
+  const owner = createRepresentativeOwner(options.heartbeatIntervalMs);
+  const server = new Server(
+    { name: 'borg-human-representative', version: options.version },
+    { capabilities: { tools: {} }, instructions: REPRESENTATIVE_INSTRUCTIONS },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS.map((tool) => ({ ...tool })) }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const name = request.params.name;
+    const args = request.params.arguments ?? {};
+    try {
+      if (!(REPRESENTATIVE_TOOL_NAMES as readonly string[]).includes(name)) {
+        throw new RepresentativeError(ErrorCode.INVALID_INPUT, `Unknown tool ${JSON.stringify(name)}; this connection exposes only the representative tools.`);
+      }
+      const ctx = await options.context();
+      if (name === 'borg_representative-status') {
+        return toolResult({ ...await representativeStatus(ctx), ownership: await owner.snapshot(ctx.binding) });
+      }
+      await owner.ensure(ctx.binding);
+      // Recheck at each network boundary, not just at tool dispatch: a process
+      // may have paused or lost its lease while awaiting live verification.
+      const backend = ctx.backend;
+      const guarded = { ...ctx, backend: Object.fromEntries(['whoami', 'roster', 'append', 'readUnread', 'readEntry', 'ack'].map((key) => [key, async (...args: unknown[]) => {
+        await owner.ensure(ctx.binding);
+        if (key === 'readUnread') args[1] = () => owner.ensure(ctx.binding);
+        const result = await (backend[key as keyof typeof backend] as (...args: unknown[]) => Promise<unknown>).apply(backend, args);
+        await owner.ensure(ctx.binding);
+        return result;
+      }])) as unknown as typeof backend };
+      switch (name) {
+        case 'borg_representative-send': {
+          const sent = await sendRepresentativeMessage(guarded, args);
+          return toolResult(sent, sent.outcome === 'ambiguous');
+        }
+        case 'borg_representative-read':
+          return toolResult(await readRepresentativeReplies(guarded, args));
+        default:
+          return toolResult(await ackRepresentativeReply(guarded, args));
+      }
+    } catch (error) {
+      return toolResult(errorBody(error), true);
+    }
+  });
+
+  const transport = new StdioServerTransport(options.stdin, options.stdout);
+  let finish!: () => void;
+  const closed = new Promise<void>((resolve) => { finish = resolve; });
+  const shutdown = async () => {
+    process.removeListener('SIGTERM', signalClose);
+    process.removeListener('SIGINT', signalClose);
+    try { await owner.close(); } finally { finish(); }
+  };
+  const signalClose = () => { void server.close(); };
+  server.onclose = () => { void shutdown().catch(() => {}); };
+  process.once('SIGTERM', signalClose);
+  process.once('SIGINT', signalClose);
+  try { await server.connect(transport); } catch (error) { await shutdown(); throw error; }
+  return { close: async () => { await server.close(); await closed; }, closed };
+}

package/src/representative-owner.ts

@@ -0,0 +1,105 @@
+/** Lifecycle adapter for the existing stream lease; no separate lock protocol. */
+import { createHash, randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { borgConfigRoot, borgHomeRoot } from './private-root.js';
+import {
+  acquireStreamLease, readOwnershipSnapshot, STREAM_OWNER_STALE_MS,
+  type StreamLease, type StreamOwnerDeps, type StreamOwnershipSnapshot,
+} from './stream-owner.js';
+import { RepresentativeError } from './representative-core.js';
+import type { RepresentativeBinding } from './representative-store.js';
+
+export function representativeOwnerDeps(binding: RepresentativeBinding): StreamOwnerDeps {
+  const authority = createHash('sha256').update(JSON.stringify([binding.origin, binding.trustIdentity])).digest('hex');
+  return {
+    // Separate from stream-locks, which borg_stream-status inspects. One lease
+    // across all worktrees using this authority/cube/drone, never one per host.
+    locksDir: join(borgConfigRoot(), 'representative-host-locks', authority),
+    privateRoot: { root: borgConfigRoot(), boundary: borgHomeRoot() },
+    worktree: binding.worktree, droneLabel: binding.representativeLabel, cubeName: binding.cubeName,
+  };
+}
+
+export function representativeOwnership(binding: RepresentativeBinding): Promise<StreamOwnershipSnapshot> {
+  return privateStorage(() => readOwnershipSnapshot(binding.cubeId, binding.representativeDroneId, representativeOwnerDeps(binding)));
+}
+
+async function privateStorage<T>(operation: () => Promise<T>): Promise<T> {
+  try { return await operation(); }
+  catch (error) {
+    if (error instanceof RepresentativeError) throw error;
+    const message = error instanceof Error ? error.message : 'invalid private state';
+    // Only this exact directory-mode refusal permits manual permission recovery.
+    // Symlink, ownership and other failures must not suggest chmod through a path.
+    const looseDirectory = /^Borg credential store root (.+) has insecure permissions; expected 0700$/s.exec(message);
+    const detail = looseDirectory
+      ? `directory ${looseDirectory[1]} has insecure permissions; expected 0700. ` +
+        'Check that the named path is a real directory you own and not a symlink, then set it to 0700 and retry. ' +
+        'Restart a process that had already lost ownership.'
+      : message.replace(/^Borg credential store /, '');
+    throw new RepresentativeError('REPRESENTATIVE_OWNERSHIP_REQUIRED',
+      'Representative lease storage refused: ' + detail);
+  }
+}
+
+export function createRepresentativeOwner(heartbeatIntervalMs = 20_000) {
+  let lease: StreamLease | null = null;
+  let selected: RepresentativeBinding | undefined;
+  let deps: StreamOwnerDeps;
+  let lost = false, closed = false;
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let tail: Promise<unknown> = Promise.resolve();
+  const processNonce = randomUUID();
+  // Serialize lease mutations, including heartbeats, but NOT tool execution:
+  // overlapping sends still use the existing atomic request reservation.
+  const serial = <T>(op: () => Promise<T>): Promise<T> => {
+    const result = tail.then(op);
+    tail = result.catch(() => {});
+    return result;
+  };
+  const snapshot = (binding: RepresentativeBinding) => privateStorage(() => readOwnershipSnapshot(
+    binding.cubeId, binding.representativeDroneId,
+    { ...representativeOwnerDeps(binding), processNonce },
+  ));
+  const refuse = async (binding: RepresentativeBinding): Promise<never> => {
+    const owner = await snapshot(binding);
+    throw new RepresentativeError(
+      'REPRESENTATIVE_OWNERSHIP_REQUIRED',
+      `This representative is owned by another MCP process (pid ${owner.pid ?? 'unknown'}, started ${owner.startedAt ?? 'unknown'}), ` +
+      'or this process lost its lease. Use the owning host; after it exits or its lease expires, retry from the intended host. ' +
+      'Restart a process that lost ownership before using it again. Status remains available.',
+      { owner },
+    );
+  };
+  const refresh = async () => {
+    try {
+      if (!lease || !await lease.refresh()) lost = true;
+    } catch { lost = true; }
+    if (lost && timer) { clearInterval(timer); timer = undefined; }
+  };
+  return {
+    snapshot,
+    ensure: (binding: RepresentativeBinding) => serial(async () => {
+      if (selected && (selected.origin !== binding.origin || selected.trustIdentity !== binding.trustIdentity ||
+          selected.cubeId !== binding.cubeId || selected.representativeDroneId !== binding.representativeDroneId)) lost = true;
+      if (closed || lost) return refuse(binding);
+      if (lease) {
+        await refresh();
+        if (lost) return refuse(binding);
+        return;
+      }
+      deps = { ...representativeOwnerDeps(binding), processNonce };
+      lease = await privateStorage(() => acquireStreamLease(binding.cubeId, binding.representativeDroneId, STREAM_OWNER_STALE_MS, deps));
+      if (!lease) return refuse(binding);
+      selected = binding;
+      timer = setInterval(() => { void serial(refresh); }, heartbeatIntervalMs);
+      timer.unref();
+    }),
+    close: () => serial(async () => {
+      closed = true;
+      if (timer) { clearInterval(timer); timer = undefined; }
+      await lease?.release();
+      lease = null;
+    }),
+  };
+}

package/src/representative-store.ts

@@ -0,0 +1,208 @@
+/**
+ * Private on-disk state for the human representative connection.
+ *
+ * One 0600 file under the Borg config root holds, per representative worktree:
+ * - the BINDING: the one explicit cube + Coordinator drone this worktree's
+ *   dedicated seat may talk to. Changing it requires an explicit operator rebind.
+ * - the REQUEST LEDGER: one record per sent request id, so a retry never becomes
+ *   a second message and an ambiguous send survives a reconnect.
+ *
+ * The file never holds a bearer (the seat store owns credentials) and never
+ * holds message text (only a payload digest).
+ */
+
+import { decodeUuid } from 'borgmcp-shared/protocol';
+import { join } from 'node:path';
+import { borgConfigRoot } from './private-root.js';
+import { shellEscape } from './shell-escape.js';
+import { readStoreFile, withStore } from './seat-store.js';
+
+export function isRepresentativeUuid(value: unknown): value is string {
+  try { decodeUuid(value); return true; } catch { return false; }
+}
+const SETTLED_REQUEST_LIMIT = 200;
+
+export interface RepresentativeBinding {
+  /** Canonical worktree holding the dedicated representative seat. */
+  worktree: string;
+  origin: string;
+  trustIdentity: string;
+  cubeId: string;
+  cubeName: string;
+  representativeDroneId: string;
+  representativeLabel: string;
+  representativeRoleName: string;
+  coordinatorDroneId: string;
+  coordinatorLabel: string;
+  coordinatorRoleName: string;
+  repositoryOrigin?: string;
+  boundAt: string;
+}
+
+export function representativeRecoveryCommand(binding: RepresentativeBinding): string {
+  return `cd ${shellEscape(binding.worktree)} && borg representative prepare --coordinator ${shellEscape(binding.coordinatorLabel)} --role ${shellEscape(binding.representativeRoleName)} --rebind`;
+}
+
+export type RepresentativeRequestState = 'pending' | 'ambiguous' | 'sent' | 'rejected';
+
+export interface RepresentativeRequestRecord {
+  /** Stable request identity; also the protocol `post_id` idempotency key. */
+  requestId: string;
+  /** sha256 of kind, authorization, message, cube and Coordinator — never the text. */
+  payloadDigest: string;
+  kind: string;
+  authorization: string;
+  state: RepresentativeRequestState;
+  entryId?: string;
+  /** An attempt under this id may have reached the log; a later refusal must not clear that. */
+  maybeStored?: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface RepresentativeFile {
+  version: 1;
+  bindings: Record<string, RepresentativeBinding>;
+  requests: Record<string, RepresentativeRequestRecord[]>;
+}
+
+export class RepresentativeStoreError extends Error {
+  constructor(readonly code: 'BINDING_CONFLICT', message: string) {
+    super(message);
+    this.name = 'RepresentativeStoreError';
+  }
+}
+
+export interface RepresentativeStore {
+  getBinding(worktree: string): Promise<RepresentativeBinding | null>;
+  readRequests(worktree: string): Promise<RepresentativeRequestRecord[]>;
+  saveBinding(
+    binding: RepresentativeBinding,
+    options: { rebind: boolean },
+  ): Promise<'created' | 'unchanged' | 'rebound'>;
+  /** Read-compare-write over one worktree's ledger under the store lock. */
+  transactRequests<T>(
+    worktree: string,
+    op: (records: RepresentativeRequestRecord[]) => T,
+  ): Promise<T>;
+}
+
+const BINDING_STRING_FIELDS = [
+  'worktree', 'origin', 'trustIdentity', 'cubeId', 'cubeName',
+  'representativeDroneId', 'representativeLabel', 'representativeRoleName',
+  'coordinatorDroneId', 'coordinatorLabel', 'coordinatorRoleName', 'boundAt',
+] as const;
+
+function validBinding(value: unknown, key: string): value is RepresentativeBinding {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const binding = value as Record<string, unknown>;
+  return BINDING_STRING_FIELDS.every((field) => typeof binding[field] === 'string' && binding[field] !== '') &&
+    binding.worktree === key &&
+    isRepresentativeUuid(binding.cubeId as string) &&
+    isRepresentativeUuid(binding.representativeDroneId as string) &&
+    isRepresentativeUuid(binding.coordinatorDroneId as string) &&
+    binding.representativeDroneId !== binding.coordinatorDroneId &&
+    (binding.repositoryOrigin === undefined || typeof binding.repositoryOrigin === 'string');
+}
+
+function validRequest(value: unknown): value is RepresentativeRequestRecord {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  return isRepresentativeUuid(String(record.requestId ?? '')) &&
+    typeof record.payloadDigest === 'string' &&
+    typeof record.kind === 'string' &&
+    typeof record.authorization === 'string' &&
+    ['pending', 'ambiguous', 'sent', 'rejected'].includes(record.state as string) &&
+    (record.entryId === undefined || typeof record.entryId === 'string') &&
+    (record.maybeStored === undefined || typeof record.maybeStored === 'boolean') &&
+    typeof record.createdAt === 'string' &&
+    typeof record.updatedAt === 'string';
+}
+
+function parseFile(raw: string): RepresentativeFile | null {
+  const parsed = JSON.parse(raw) as Partial<RepresentativeFile> | null;
+  if (
+    parsed === null || typeof parsed !== 'object' || parsed.version !== 1 ||
+    parsed.bindings === null || typeof parsed.bindings !== 'object' || Array.isArray(parsed.bindings) ||
+    parsed.requests === null || typeof parsed.requests !== 'object' || Array.isArray(parsed.requests)
+  ) return null;
+  for (const [key, binding] of Object.entries(parsed.bindings)) {
+    if (!validBinding(binding, key)) return null;
+  }
+  for (const records of Object.values(parsed.requests)) {
+    if (!Array.isArray(records) || !records.every(validRequest)) return null;
+  }
+  return parsed as RepresentativeFile;
+}
+
+const emptyFile = (): RepresentativeFile => ({ version: 1, bindings: {}, requests: {} });
+
+function sameSelection(a: RepresentativeBinding, b: RepresentativeBinding): boolean {
+  return a.origin === b.origin &&
+    a.trustIdentity === b.trustIdentity &&
+    a.cubeId === b.cubeId &&
+    a.representativeDroneId === b.representativeDroneId &&
+    a.coordinatorDroneId === b.coordinatorDroneId;
+}
+
+/** Settled history is bounded; unresolved (pending/ambiguous) records are never dropped. */
+function pruneSettled(records: RepresentativeRequestRecord[]): RepresentativeRequestRecord[] {
+  const settled = records.filter((record) => record.state === 'sent' || record.state === 'rejected');
+  if (settled.length <= SETTLED_REQUEST_LIMIT) return records;
+  const drop = new Set(settled.slice(0, settled.length - SETTLED_REQUEST_LIMIT).map((record) => record.requestId));
+  return records.filter((record) => !drop.has(record.requestId));
+}
+
+export function representativeStorePath(): string {
+  return join(borgConfigRoot(), 'representative.json');
+}
+
+export function createRepresentativeStore(storePath: string = representativeStorePath()): RepresentativeStore {
+  // Atomic writer renames make a single read a complete snapshot, without a
+  // store-lock write or pruning settled history during read-only status.
+  const read = async () => {
+    const raw = await readStoreFile(storePath);
+    if (raw === null) return emptyFile();
+    let data: RepresentativeFile | null;
+    try { data = parseFile(raw); } catch { data = null; }
+    if (!data) throw new Error('Borg representative store is malformed or unsupported; refusing to read it');
+    return data;
+  };
+  return {
+    getBinding: async (worktree) => (await read()).bindings[worktree] ?? null,
+    readRequests: async (worktree) => (await read()).requests[worktree] ?? [],
+
+    saveBinding: (binding, options) => withStore(storePath, emptyFile, parseFile, async (txn) => {
+      if (!validBinding(binding, binding.worktree)) {
+        throw new Error('Refusing to save an invalid representative binding');
+      }
+      const existing = txn.data.bindings[binding.worktree];
+      if (existing && sameSelection(existing, binding)) return 'unchanged' as const;
+      if (existing && !options.rebind) {
+        throw new RepresentativeStoreError(
+          'BINDING_CONFLICT',
+          `This worktree is already bound to Coordinator ${existing.coordinatorLabel} in cube ${existing.cubeName}. ` +
+            `To confirm the new selection, run \`${representativeRecoveryCommand(binding)}\`.`,
+        );
+      }
+      txn.data.bindings[binding.worktree] = binding;
+      // A different selection invalidates the old ledger: its post ids belong to
+      // another cube/Coordinator conversation.
+      if (existing) delete txn.data.requests[binding.worktree];
+      await txn.commit();
+      return existing ? 'rebound' as const : 'created' as const;
+    }),
+
+    transactRequests: (worktree, op) => withStore(storePath, emptyFile, parseFile, async (txn) => {
+      const records = txn.data.requests[worktree] ?? [];
+      const before = JSON.stringify(records);
+      const result = op(records);
+      const next = pruneSettled(records);
+      if (JSON.stringify(next) !== before) {
+        txn.data.requests[worktree] = next;
+        await txn.commit();
+      }
+      return result;
+    }),
+  };
+}

package/src/seat-store.ts

@@ -49,16 +49,24 @@ interface LockPayload {
 export interface SecureStoreOptions {
   secureRoot?: string;
   rootMode?: 'private' | 'owner-controlled';
+  /** Harden leaf publication for private lease records; default store behavior is unchanged. */
+  verifyLeafIdentity?: boolean;
+  /** Publish without replacing an existing leaf (lease takeover marker). */
+  exclusive?: boolean;
+  /** Read-only lease inspection must not recreate a directory moved by its owner. */
+  createRoot?: boolean;
 }
 
 function expectedUid(): number | null {
   return typeof process.getuid === 'function' ? process.getuid() : null;
 }
 
-async function assertSecureRoot(
+/** Shared directory policy; create=false validates without mutating and returns false if absent. */
+export async function assertSecureRoot(
   root: string,
   rootMode: SecureStoreOptions['rootMode'] = 'private',
-): Promise<void> {
+  create = true,
+): Promise<boolean> {
   if (!isCanonicalPath(root)) {
     throw new Error(`Borg credential store path ${root} is not canonical`);
   }
@@ -67,6 +75,7 @@ async function assertSecureRoot(
     metadata = await lstat(root);
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    if (!create) return false;
     await mkdir(root, { recursive: true, mode: 0o700 });
     metadata = await lstat(root);
   }
@@ -87,6 +96,7 @@ async function assertSecureRoot(
   if (!isCanonicalPath(root)) {
     throw new Error(`Borg credential store root ${root} is not canonical or contains a symlink`);
   }
+  return true;
 }
 
 async function assertSecureFile(filePath: string): Promise<Awaited<ReturnType<typeof lstat>> | null> {
@@ -115,7 +125,9 @@ async function assertSecurePath(filePath: string, options: SecureStoreOptions):
   if (!isAbsolute(filePath) || resolve(filePath) !== filePath || dirname(filePath) !== secureRoot) {
     throw new Error(`Borg credential store file path ${filePath} is not canonical`);
   }
-  await assertSecureRoot(secureRoot, options.rootMode);
+  if (!await assertSecureRoot(secureRoot, options.rootMode, options.createRoot !== false)) {
+    throw Object.assign(new Error('Borg private store directory disappeared'), { code: 'ENOENT' });
+  }
 }
 
 /**
@@ -223,13 +235,28 @@ export async function atomicWrite0600(
   else await ensureParentDir(filePath);
   if (options.secureRoot) await assertSecureFile(filePath);
   const tmp = `${filePath}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
-  const handle = await open(tmp, 'wx', 0o600);
+  const handle = await open(tmp, options.verifyLeafIdentity
+    ? constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW
+    : 'wx', 0o600);
+  let opened: Awaited<ReturnType<typeof handle.stat>> | null = null;
+  const cleanup = async () => {
+    if (options.verifyLeafIdentity) {
+      const current = await lstat(tmp).catch(() => null);
+      if (!opened || !current || current.dev !== opened.dev || current.ino !== opened.ino) return;
+    }
+    await unlink(tmp).catch(() => {});
+  };
   try {
+    opened = options.verifyLeafIdentity ? await handle.stat() : null;
+    if (opened && (!opened.isFile() || (opened.mode & 0o777) !== 0o600 ||
+        (expectedUid() !== null && opened.uid !== expectedUid()))) {
+      throw new Error('Borg private store temporary file is not private');
+    }
     await handle.writeFile(data);
     await handle.sync();
   } catch (err) {
     await handle.close().catch(() => {});
-    await unlink(tmp).catch(() => {});
+    await cleanup();
     throw err;
   }
   await handle.close();
@@ -238,7 +265,17 @@ export async function atomicWrite0600(
       await assertSecurePath(filePath, options);
       await assertSecureFile(filePath);
     }
-    await rename(tmp, filePath);
+    if (opened) {
+      const current = await lstat(tmp);
+      if (!current.isFile() || current.dev !== opened.dev || current.ino !== opened.ino ||
+          current.uid !== opened.uid || (current.mode & 0o777) !== 0o600) {
+        throw new Error('Borg private store temporary file identity changed');
+      }
+    }
+    if (options.exclusive) {
+      await link(tmp, filePath);
+      await unlink(tmp);
+    } else await rename(tmp, filePath);
     const parent = await open(dirname(filePath), 'r');
     try {
       await parent.sync();
@@ -246,7 +283,7 @@ export async function atomicWrite0600(
       await parent.close();
     }
   } catch (err) {
-    await unlink(tmp).catch(() => {});
+    await cleanup();
     throw err;
   }
 }
@@ -283,6 +320,20 @@ async function assertSecureStorePerms(
   }
 }
 
+/** Identity drift is retryable only when inspecting an acquisition lock. */
+export class StoreFileIdentityChangedError extends Error {
+  readonly code = 'STORE_FILE_IDENTITY_CHANGED';
+
+  constructor() {
+    super('Borg credential store file changed while it was being opened');
+  }
+}
+
+function isLockTurnover(error: unknown): boolean {
+  const code = (error as NodeJS.ErrnoException).code;
+  return code === 'ENOENT' || code === 'STORE_FILE_IDENTITY_CHANGED';
+}
+
 /**
  * Read the store file, or null when it does not exist (ONLY the missing-file
  * no-op path initializes empty). When the file exists, the 0600-store + 0700-parent
@@ -310,7 +361,7 @@ export async function readStoreFile(
     try {
       const opened = await handle.stat();
       if (opened.dev !== before.dev || opened.ino !== before.ino) {
-        throw new Error('Borg credential store file changed while it was being opened');
+        throw new StoreFileIdentityChangedError();
       }
       const raw = await handle.readFile('utf8');
       const after = await handle.stat();
@@ -399,7 +450,7 @@ export async function withStoreLock<T>(
           if (stored === null) continue;
           raw = stored;
         } catch (readErr) {
-          if ((readErr as NodeJS.ErrnoException).code === 'ENOENT') continue; // released — retry
+          if (isLockTurnover(readErr)) continue; // released or replaced — retry
           throw readErr;
         }
         const held = parseLockPayload(raw);
@@ -422,7 +473,7 @@ export async function withStoreLock<T>(
               : {},
           );
         } catch (readErr) {
-          if ((readErr as NodeJS.ErrnoException).code === 'ENOENT') continue;
+          if (isLockTurnover(readErr)) continue;
           throw readErr;
         }
         if (currentRaw === null || currentRaw !== raw) continue;