borgmcp 2.0.1 → 2.0.3

package/src/seats.ts

@@ -55,6 +55,9 @@ export interface SeatRecord {
   roleName?: string;
   roleClass?: 'queen' | 'worker';
   isHumanSeat?: boolean;
+  // One crash-safe replacement may coexist with an ACTIVE session until the
+  // server confirms the same-seat restore. It is never hydratable or bound.
+  replacement?: { credential: string };
 }
 
 interface SeatsFile {
@@ -154,6 +157,19 @@ function isValidSeatRecord(ref: string, value: unknown): value is SeatRecord {
   ) {
     return false;
   }
+  if (r.replacement !== undefined) {
+    if (
+      r.state !== 'active' ||
+      r.replacement === null ||
+      typeof r.replacement !== 'object' ||
+      Array.isArray(r.replacement) ||
+      Object.keys(r.replacement as object).length !== 1 ||
+      typeof (r.replacement as { credential?: unknown }).credential !== 'string' ||
+      !/^[A-Za-z0-9_-]{43}$/.test((r.replacement as { credential: string }).credential)
+    ) {
+      return false;
+    }
+  }
   // State-consistency invariants (no inconsistent active|pending).
   if (r.state === 'active') {
     // An ACTIVE record MUST carry its full server session + worktree binding.
@@ -281,6 +297,17 @@ export async function getActiveSeatCredential(
   return record.credential;
 }
 
+/** Exact ACTIVE record for the internal continuity coordinator. */
+export async function getActiveSeat(
+  ref: string,
+  binding: { origin: string; trustIdentity: string; cubeId: string },
+): Promise<SeatRecord | null> {
+  if (!REF_RE.test(ref)) return null;
+  const store = await readStore();
+  const record = store.seats[ref];
+  return recordMatches(record, ref, binding) && record.state === 'active' ? record : null;
+}
+
 // ─── PREPARE / mint (no worktree yet) ────────────────────────────────────────
 
 /**
@@ -483,6 +510,149 @@ export async function activateAndBindSeat(input: {
   });
 }
 
+export type PrepareSeatReplacementOutcome =
+  | { ok: true; credential: string; digest: string }
+  | { ok: false; reason: 'expectation-mismatch' };
+
+/**
+ * Preserve the exact ACTIVE seat while preparing one durable replacement bearer.
+ * A lost response or process restart reuses the stored replacement; a changed
+ * authority, drone, or active bearer fails before any mutation.
+ */
+export async function prepareSeatReplacement(input: {
+  ref: string;
+  binding: { origin: string; trustIdentity: string; cubeId: string };
+  expectedDroneId: string;
+  expectedActiveDigest: string;
+  replacementCredential: string;
+}): Promise<PrepareSeatReplacementOutcome> {
+  if (!REF_RE.test(input.ref) || !/^[A-Za-z0-9_-]{43}$/.test(input.replacementCredential)) {
+    return { ok: false, reason: 'expectation-mismatch' };
+  }
+  return withStore<SeatsFile, PrepareSeatReplacementOutcome>(SEATS_FILE, emptyStore, parseStore, async (txn) => {
+    const record = txn.data.seats[input.ref];
+    if (
+      !recordMatches(record, input.ref, input.binding) ||
+      record.state !== 'active' ||
+      record.droneId !== input.expectedDroneId ||
+      digestOf(record.credential) !== input.expectedActiveDigest
+    ) {
+      return { ok: false as const, reason: 'expectation-mismatch' as const };
+    }
+    if (record.replacement) {
+      return {
+        ok: true as const,
+        credential: record.replacement.credential,
+        digest: digestOf(record.replacement.credential),
+      };
+    }
+    record.replacement = { credential: input.replacementCredential };
+    await txn.commit();
+    return {
+      ok: true as const,
+      credential: input.replacementCredential,
+      digest: digestOf(input.replacementCredential),
+    };
+  });
+}
+
+export type PromoteSeatReplacementOutcome = 'promoted' | 'missing' | 'replaced';
+
+/** Update only the committed expiry for an exact same-bearer session renewal. */
+export async function refreshActiveSeatSession(input: {
+  ref: string;
+  binding: { origin: string; trustIdentity: string; cubeId: string };
+  expectedDroneId: string;
+  expectedActiveDigest: string;
+  expectedSessionId: string;
+  expiresAt: string;
+}): Promise<boolean> {
+  if (!UUID_RE.test(input.expectedDroneId) || !UUID_RE.test(input.expectedSessionId)) {
+    throw new Error('invalid Borg server session identity');
+  }
+  if (!Number.isFinite(Date.parse(input.expiresAt))) {
+    throw new Error('invalid Borg server session expiry');
+  }
+  return withStore<SeatsFile, boolean>(SEATS_FILE, emptyStore, parseStore, async (txn) => {
+    const record = txn.data.seats[input.ref];
+    if (
+      !recordMatches(record, input.ref, input.binding) ||
+      record.state !== 'active' ||
+      record.droneId !== input.expectedDroneId ||
+      record.sessionId !== input.expectedSessionId ||
+      digestOf(record.credential) !== input.expectedActiveDigest
+    ) {
+      return false;
+    }
+    record.expiresAt = input.expiresAt;
+    await txn.commit();
+    return true;
+  });
+}
+
+/** Atomically promote only the response-bound replacement onto the same ACTIVE seat. */
+export async function promoteSeatReplacement(input: {
+  ref: string;
+  binding: { origin: string; trustIdentity: string; cubeId: string };
+  expectedDroneId: string;
+  expectedActiveDigest: string;
+  expectedReplacementDigest: string;
+  sessionId: string;
+  expiresAt: string;
+}): Promise<PromoteSeatReplacementOutcome> {
+  if (!UUID_RE.test(input.expectedDroneId) || !UUID_RE.test(input.sessionId)) {
+    throw new Error('invalid Borg server session identity');
+  }
+  if (!Number.isFinite(Date.parse(input.expiresAt))) {
+    throw new Error('invalid Borg server session expiry');
+  }
+  return withStore<SeatsFile, PromoteSeatReplacementOutcome>(SEATS_FILE, emptyStore, parseStore, async (txn) => {
+    const record = txn.data.seats[input.ref];
+    if (!recordMatches(record, input.ref, input.binding) || record.state !== 'active') return 'missing';
+    if (
+      record.droneId !== input.expectedDroneId ||
+      digestOf(record.credential) !== input.expectedActiveDigest ||
+      !record.replacement ||
+      digestOf(record.replacement.credential) !== input.expectedReplacementDigest
+    ) {
+      return 'replaced';
+    }
+    const { replacement, ...active } = record;
+    txn.data.seats[input.ref] = {
+      ...active,
+      credential: replacement.credential,
+      sessionId: input.sessionId,
+      expiresAt: input.expiresAt,
+    };
+    await txn.commit();
+    return 'promoted';
+  });
+}
+
+/** Remove only the caller's exact pending replacement, never the ACTIVE seat. */
+export async function scrubSeatReplacement(input: {
+  ref: string;
+  binding: { origin: string; trustIdentity: string; cubeId: string };
+  expectedActiveDigest: string;
+  expectedReplacementDigest: string;
+}): Promise<boolean> {
+  return withStore<SeatsFile, boolean>(SEATS_FILE, emptyStore, parseStore, async (txn) => {
+    const record = txn.data.seats[input.ref];
+    if (
+      !recordMatches(record, input.ref, input.binding) ||
+      record.state !== 'active' ||
+      digestOf(record.credential) !== input.expectedActiveDigest ||
+      !record.replacement ||
+      digestOf(record.replacement.credential) !== input.expectedReplacementDigest
+    ) {
+      return false;
+    }
+    delete record.replacement;
+    await txn.commit();
+    return true;
+  });
+}
+
 // ─── CR#2: bind a PENDING record to a preserved worktree (no activation) ─────
 
 export type BindPendingSeatOutcome = 'bound' | 'missing' | 'replaced';

package/src/server-errors.ts

@@ -4,7 +4,9 @@ export type BorgServerErrorCode =
   | 'INVITATION_REJECTED'
   | 'CREATE_CUBE_DENIED'
   | 'ATTACH_CONFLICT'
-  | 'SESSION_REJECTED';
+  | 'SESSION_REJECTED'
+  | 'SESSION_REVOKED'
+  | 'AUTH_EXPIRED';
 
 /** Safe, non-secret state code for deterministic authority recovery copy. */
 export class BorgServerError extends Error {

package/src/server-facade.ts

@@ -0,0 +1,192 @@
+import { spawn as spawnChild, type SpawnOptions } from 'node:child_process';
+import { constants } from 'node:os';
+import { serverHelpText } from './cli-help.js';
+
+export const SERVER_LIFECYCLE_COMMANDS = ['setup', 'start', 'status', 'update', 'invite'] as const;
+export type ServerLifecycleCommand = typeof SERVER_LIFECYCLE_COMMANDS[number];
+
+export type ParsedServerFacadeArgs =
+  | { kind: 'help' }
+  | { kind: 'command'; command: ServerLifecycleCommand; args: string[] }
+  | { kind: 'error'; reason: 'unknown-command'; command: string };
+
+export function parseServerFacadeArgs(args: readonly string[]): ParsedServerFacadeArgs {
+  const [command, ...rest] = args;
+  if (command === undefined || command === '--help' || command === '-h') {
+    return { kind: 'help' };
+  }
+  if (!(SERVER_LIFECYCLE_COMMANDS as readonly string[]).includes(command)) {
+    return { kind: 'error', reason: 'unknown-command', command };
+  }
+  return {
+    kind: 'command',
+    command: command as ServerLifecycleCommand,
+    args: rest,
+  };
+}
+
+interface ServerFacadeChild {
+  once(event: 'error', listener: (error: Error) => void): this;
+  once(
+    event: 'exit',
+    listener: (code: number | null, signal: NodeJS.Signals | null) => void,
+  ): this;
+  kill(signal: NodeJS.Signals): boolean;
+}
+
+export interface ServerFacadeProcessDeps {
+  spawn(
+    command: string,
+    args: readonly string[],
+    options: Pick<SpawnOptions, 'shell' | 'stdio'>,
+  ): ServerFacadeChild;
+  addSignalListener(signal: NodeJS.Signals, listener: () => void): void;
+  removeSignalListener(signal: NodeJS.Signals, listener: () => void): void;
+}
+
+export interface ServerFacadeOutputDeps {
+  writeStdout(text: string): void;
+  writeStderr(text: string): void;
+}
+
+export type ServerFacadeProcessResult =
+  | { kind: 'exited'; code: number }
+  | { kind: 'signaled'; signal: NodeJS.Signals }
+  | { kind: 'spawn-error'; error: Error };
+
+const defaultProcessDeps: ServerFacadeProcessDeps = {
+  spawn: (command, args, options) => spawnChild(command, [...args], options),
+  addSignalListener: (signal, listener) => process.on(signal, listener),
+  removeSignalListener: (signal, listener) => process.off(signal, listener),
+};
+
+const defaultOutputDeps: ServerFacadeOutputDeps = {
+  writeStdout: (text) => process.stdout.write(text),
+  writeStderr: (text) => process.stderr.write(text),
+};
+
+const MAX_RENDERED_COMMAND_CODE_POINTS = 80;
+
+function inertCommand(command: string): string {
+  const rendered: string[] = [];
+  let truncated = false;
+  for (const codePoint of command) {
+    if (rendered.length === MAX_RENDERED_COMMAND_CODE_POINTS) {
+      truncated = true;
+      break;
+    }
+    rendered.push(/\p{Cc}/u.test(codePoint) ? '?' : codePoint);
+  }
+  if (truncated) {
+    return `${rendered.slice(0, MAX_RENDERED_COMMAND_CODE_POINTS - 3).join('')}...`;
+  }
+  return rendered.join('');
+}
+
+export function unknownServerCommandText(command: string): string {
+  return (
+    `Unknown server command: ${inertCommand(command)}.\n` +
+    `Available commands: setup, start, status, update, invite.\n` +
+    `Next: run borg server --help.\n`
+  );
+}
+
+export function missingServerExecutableText(command: ServerLifecycleCommand): string {
+  return (
+    `Local server command is unavailable: borg-mcp-server was not found.\n` +
+    `Next: install a verified borgmcp-server release, then rerun borg server ${command}.\n` +
+    `No checkout fallback is attempted.\n`
+  );
+}
+
+export function serverCommandStartupFailureText(command: ServerLifecycleCommand): string {
+  return (
+    `Local server command could not be started.\n` +
+    `Next: check local permissions and system resources, then rerun borg server ${inertCommand(command)}.\n` +
+    `No server command was started.\n`
+  );
+}
+
+function isMissingServerExecutable(error: Error): boolean {
+  return (error as NodeJS.ErrnoException).code === 'ENOENT';
+}
+
+export function runServerFacadeProcess(
+  input: { command: ServerLifecycleCommand; args: readonly string[] },
+  deps: ServerFacadeProcessDeps = defaultProcessDeps,
+): Promise<ServerFacadeProcessResult> {
+  const child = deps.spawn(
+    'borg-mcp-server',
+    [input.command, ...input.args],
+    { shell: false, stdio: 'inherit' },
+  );
+  const signals = ['SIGINT', 'SIGTERM'] as const;
+
+  return new Promise((resolve) => {
+    let settled = false;
+    const forwarders = new Map<NodeJS.Signals, () => void>();
+    const cleanup = () => {
+      for (const [signal, listener] of forwarders) {
+        deps.removeSignalListener(signal, listener);
+      }
+      forwarders.clear();
+    };
+    const settle = (result: ServerFacadeProcessResult) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(result);
+    };
+
+    for (const signal of signals) {
+      const listener = () => {
+        child.kill(signal);
+      };
+      forwarders.set(signal, listener);
+      deps.addSignalListener(signal, listener);
+    }
+
+    child.once('error', (error) => settle({ kind: 'spawn-error', error }));
+    child.once('exit', (code, signal) => {
+      if (signal) {
+        settle({ kind: 'signaled', signal });
+        return;
+      }
+      settle({ kind: 'exited', code: code ?? 1 });
+    });
+  });
+}
+
+function processResultExitCode(result: ServerFacadeProcessResult): number {
+  if (result.kind === 'exited') return result.code;
+  if (result.kind === 'spawn-error') return isMissingServerExecutable(result.error) ? 127 : 1;
+  return 128 + (constants.signals[result.signal] ?? 1);
+}
+
+/** Routes every facade outcome before client initialization or network work. */
+export async function runEarlyServerFacade(
+  argv: readonly string[],
+  deps: ServerFacadeProcessDeps = defaultProcessDeps,
+  output: ServerFacadeOutputDeps = defaultOutputDeps,
+): Promise<number | null> {
+  if (argv[2] !== 'server') return null;
+  const parsed = parseServerFacadeArgs(argv.slice(3));
+  if (parsed.kind === 'help') {
+    output.writeStdout(serverHelpText());
+    return 0;
+  }
+  if (parsed.kind === 'error') {
+    output.writeStderr(unknownServerCommandText(parsed.command));
+    return 1;
+  }
+
+  const result = await runServerFacadeProcess(parsed, deps);
+  if (result.kind === 'spawn-error') {
+    output.writeStderr(
+      isMissingServerExecutable(result.error)
+        ? missingServerExecutableText(parsed.command)
+        : serverCommandStartupFailureText(parsed.command),
+    );
+  }
+  return processResultExitCode(result);
+}

package/src/server-handshake.ts

@@ -40,7 +40,12 @@ import {
   type SeatBinding,
   type SeatOperation as ServerSessionOperation,
 } from './seats.js';
-import { BorgServerError } from './server-errors.js';
+import {
+  BorgServerError,
+  BorgServerTrustError,
+  BorgServerUnreachableError,
+} from './server-errors.js';
+import { DroneEvictedError, DRONE_EVICTED_CODE } from './drone-lifecycle.js';
 import { readBoundedResponseBody } from './server-response.js';
 import {
   loadBorgServerTrust,
@@ -255,30 +260,36 @@ export async function sendBorgServerAttach(
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), HANDSHAKE_TIMEOUT_MS);
   try {
-    const response = await (deps.fetchImpl ?? fetch)(handshakeUrl(origin, ATTACH_PATH), {
-      method: 'POST',
-      redirect: 'error',
-      signal: controller.signal,
-      headers: {
-        Accept: 'application/json',
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${parentCredential}`,
-      },
-      body: JSON.stringify(createAttachRequestEnvelope(randomUUID(), {
-        cube_id: request.cubeId,
-        role_id: request.roleId,
-        session_credential: pending.credential,
-        ...(request.priorDroneId === undefined
-          ? {}
-          : { prior_drone_id: request.priorDroneId }),
-      })),
-    });
-    if (response.status === 401 || response.status === 403) {
+    let response: Response;
+    try {
+      response = await (deps.fetchImpl ?? fetch)(handshakeUrl(origin, ATTACH_PATH), {
+        method: 'POST',
+        redirect: 'error',
+        signal: controller.signal,
+        headers: {
+          Accept: 'application/json',
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${parentCredential}`,
+        },
+        body: JSON.stringify(createAttachRequestEnvelope(randomUUID(), {
+          cube_id: request.cubeId,
+          role_id: request.roleId,
+          session_credential: pending.credential,
+          ...(request.priorDroneId === undefined
+            ? {}
+            : { prior_drone_id: request.priorDroneId }),
+        })),
+      });
+    } catch (error) {
+      if (error instanceof BorgServerTrustError) throw error;
+      throw new BorgServerUnreachableError('Borg server attach transport failed', { cause: error });
+    }
+    if (response.status === 401 || response.status === 403 || response.status === 410) {
       // A typed SESSION_REJECTED body means the presented bearer targets a seat
       // already bound to a different session (takeover), distinct from a rejected
       // parent enrollment credential. Decode defensively; any anomaly falls back
       // to the generic credential rejection below. Never echo the response body.
-      if (response.status === 401) {
+      if (response.status === 401 || response.status === 410) {
         let rejectedCode: ErrorCode | undefined;
         try {
           rejectedCode = decodeProtocolErrorEnvelope(
@@ -293,7 +304,23 @@ export async function sendBorgServerAttach(
             'Borg server rejected the session: the seat is already bound to another session',
           );
         }
+        if (rejectedCode === ErrorCode.AUTH_EXPIRED) {
+          throw new BorgServerError(
+            'AUTH_EXPIRED',
+            'Borg server session expired',
+          );
+        }
+        if (rejectedCode === ErrorCode.SESSION_REVOKED) {
+          throw new BorgServerError(
+            'SESSION_REVOKED',
+            'Borg server session was revoked',
+          );
+        }
+        if (response.status === 410 && rejectedCode === DRONE_EVICTED_CODE) {
+          throw new DroneEvictedError();
+        }
       }
+      if (response.status === 410) throw new Error('Borg server attach failed (HTTP 410)');
       throw new BorgServerError('CREDENTIAL_REJECTED', 'Borg server enrollment was rejected');
     }
     if (response.status === 409) {
@@ -381,6 +408,12 @@ export async function sendBorgServerAttach(
           ...(binding.isHumanSeat !== undefined ? { isHumanSeat: binding.isHumanSeat } : {}),
         }),
     };
+  } catch (error) {
+    if (error instanceof BorgServerTrustError) throw error;
+    if (controller.signal.aborted && !(error instanceof BorgServerUnreachableError)) {
+      throw new BorgServerUnreachableError('Borg server attach transport timed out', { cause: error });
+    }
+    throw error;
   } finally {
     clearTimeout(timeout);
   }