borgmcp 2.8.0 → 2.10.0

package/src/assimilate-cmd.ts

@@ -56,6 +56,17 @@ import {
   RepositoryAssociationOutcomeUnknownError,
   RepositoryAssociationResolutionError,
 } from './server-errors.js';
+import {
+  decodeAndVerifyInvitationArtifact,
+  InvitationArtifactCompatibilityError,
+  InvitationArtifactEndpointMismatchError,
+  InvitationArtifactFormatError,
+  InvitationArtifactLegacyError,
+  InvitationArtifactRecoveryError,
+  InvitationArtifactStorageError,
+  InvitationArtifactTransportError,
+  InvitationArtifactTrustError,
+} from './invitation-artifact.js';
 import type { SeatStatus } from './seat-probe.js';
 import type { ServerSessionOperation } from './config.js';
 import type { ExpectedBinding, FinalizeServerSeatOutcome, PersistedLocalSeat } from './cubes.js';
@@ -67,6 +78,7 @@ import type {
   AssociateRepositoryCubeResponse,
   CreateCubeRepository,
   CubeTemplate,
+  InvitationArtifact,
 } from 'borgmcp-shared/protocol';
 import {
   initializeRepositoryCube,
@@ -277,7 +289,11 @@ export interface AssimilateDeps {
   detectLocalServer: () => Promise<string | null>;
   connectServer: (
     apiUrl: string,
-    enrollment?: { invitation: string },
+    enrollment?: {
+      invitation: string;
+      artifact?: import('borgmcp-shared/protocol').InvitationArtifact;
+      confirmReplacement?: () => Promise<boolean>;
+    },
   ) => Promise<{
     token: string;
     trustIdentity: string;
@@ -291,6 +307,17 @@ export interface AssimilateDeps {
     trustIdentity: string;
     serverCapabilities?: readonly string[];
   } | null>;
+  /** Read-only pending-artifact peek used to validate an explicit host before
+   * the normal resume path performs trust/credential work. */
+  peekPendingServerEnrollment?: () => Promise<{ origin: string; invitation: string } | null>;
+  resumePendingServerEnrollment?: (
+    onPending?: () => void,
+  ) => Promise<{
+    token: string;
+    apiUrl?: string;
+    trustIdentity: string;
+    serverCapabilities?: readonly string[];
+  } | null>;
 
   resolveRepositoryCube: (
     apiUrl: string,
@@ -361,6 +388,11 @@ function affirmative(answer: string): boolean {
   return normalized === '' || normalized === 'y' || normalized === 'yes';
 }
 
+function strictAffirmative(answer: string): boolean {
+  const normalized = answer.trim().toLowerCase();
+  return normalized === 'y' || normalized === 'yes';
+}
+
 async function selectAssimilationAuthority(
   flags: AssimilateFlags,
   deps: AssimilateDeps,
@@ -377,6 +409,11 @@ async function selectAssimilationAuthority(
 
   // Only a local self-hosted server authority exists. Non-TTY and --yes must
   // NOT infer an authority — fail closed with actionable guidance.
+  if (flags.enroll && deps.isTTY()) {
+    // The v2 enrollment artifact is itself the authority selector. Use the
+    // local origin only as a placeholder until the hidden artifact is decoded.
+    return { kind: 'server', apiUrl: DEFAULT_LOCAL_SERVER_ORIGIN };
+  }
   if (!deps.isTTY() || flags.yes) {
     if (deps.defaultAuthority) return deps.defaultAuthority;
     const command = mode === 'cube-init'
@@ -475,6 +512,14 @@ function reportServerFailure(
     );
     return 1;
   }
+  if (error instanceof BorgServerError && error.code === 'LOCAL_CREDENTIAL_EXISTS') {
+    deps.stderr(
+      `A local enrollment for ${apiUrl} already exists and was not replaced. ` +
+        `Re-run ${localAssimilateCommand(apiUrl, true, mode)} and explicitly confirm replacement ` +
+        'only if the first enrolled client should be abandoned.\n',
+    );
+    return 1;
+  }
   if (error instanceof LegacySessionCredentialCollisionError) {
     const recovery = mode === 'cube-init'
       ? localAssimilateCommand(error.origin, true, mode)
@@ -508,6 +553,38 @@ function reportServerFailure(
     );
     return 1;
   }
+  if (error instanceof InvitationArtifactCompatibilityError) {
+    deps.stderr(`${error.message}\n`);
+    return 1;
+  }
+  if (error instanceof InvitationArtifactLegacyError) {
+    deps.stderr(`${error.message}\n`);
+    return 1;
+  }
+  if (error instanceof InvitationArtifactFormatError) {
+    deps.stderr(`${error.message}\n`);
+    return 1;
+  }
+  if (error instanceof InvitationArtifactEndpointMismatchError) {
+    deps.stderr(`${error.message}\n`);
+    return 1;
+  }
+  if (error instanceof InvitationArtifactTransportError) {
+    deps.stderr(`${error.message}\n`);
+    return 1;
+  }
+  if (error instanceof InvitationArtifactStorageError) {
+    deps.stderr(`${error.message}\n`);
+    return 1;
+  }
+  if (error instanceof InvitationArtifactRecoveryError) {
+    deps.stderr(`${error.message}\n`);
+    return 1;
+  }
+  if (error instanceof InvitationArtifactTrustError) {
+    deps.stderr(`${error.message}\n`);
+    return 1;
+  }
   if (/HTTP 40[13]|auth(?:entication|orization)|credential.*(?:invalid|rejected)/i.test(message)) {
     deps.stderr(
       `The saved enrollment for ${apiUrl} was rejected. Re-run ` +
@@ -649,7 +726,117 @@ export async function runAssimilate(
     return 1;
   }
 
-  if (args.flags.server === undefined && deps.defaultAuthority === undefined) {
+  const artifactOnlyEnrollment = args.flags.enroll === true &&
+    args.flags.server === undefined && deps.defaultAuthority === undefined && deps.isTTY();
+  let preResumeAttempted = false;
+  let preResumedEnrollment: {
+    token: string;
+    trustIdentity: string;
+    serverCapabilities?: readonly string[];
+  } | null = null;
+
+  let prefetchedInvitation: string | undefined;
+  let prefetchedArtifact: InvitationArtifact | undefined;
+
+  // An explicit --host plus a new invitation must be rejected on the pure
+  // input path. Decode and compare the operator-presented artifact before any
+  // pending-enrollment lookup: the lookup enumerates the credential backend,
+  // so it must not precede this contradiction check. A matching artifact may
+  // then take the published pending-resume path until client#267 lands.
+  if (args.flags.enroll && args.flags.server !== undefined && deps.isTTY()) {
+    let preResumeOrigin: string;
+    try {
+      preResumeOrigin = normalizeServerEndpoint(args.flags.server);
+    } catch (error) {
+      deps.stderr(`${error instanceof Error ? error.message : String(error)}\n`);
+      return 1;
+    }
+
+    prefetchedInvitation = await deps.promptSecret('Enrollment invitation (single-use; hidden input):');
+    if (!prefetchedInvitation) {
+      deps.stderr('No enrollment invitation was entered. Ask the server operator for one, then retry.\n');
+      return 1;
+    }
+    try {
+      prefetchedArtifact = decodeAndVerifyInvitationArtifact(prefetchedInvitation);
+      if (prefetchedArtifact.endpoint !== preResumeOrigin) {
+        throw new InvitationArtifactEndpointMismatchError(
+          preResumeOrigin,
+          prefetchedArtifact.endpoint,
+        );
+      }
+    } catch (error) {
+      deps.stderr(`${error instanceof Error ? error.message : 'The enrollment invitation is invalid.'}\n`);
+      prefetchedInvitation = undefined;
+      prefetchedArtifact = undefined;
+      return 1;
+    }
+
+    let pendingForHost = false;
+    if (deps.peekPendingServerEnrollment !== undefined) {
+      let pending: { origin: string; invitation: string } | null = null;
+      try {
+        pending = await deps.peekPendingServerEnrollment();
+      } catch {
+        pending = null;
+      }
+      if (pending?.origin === preResumeOrigin) {
+        try {
+          const pendingArtifact = decodeAndVerifyInvitationArtifact(pending.invitation);
+          if (pendingArtifact.endpoint !== preResumeOrigin) {
+            throw new InvitationArtifactEndpointMismatchError(
+              preResumeOrigin,
+              pendingArtifact.endpoint,
+            );
+          }
+          pendingForHost = true;
+        } catch (error) {
+          deps.stderr(`${error instanceof Error ? error.message : 'The enrollment invitation is invalid.'}\n`);
+          return 1;
+        }
+      }
+    }
+
+    if (pendingForHost) {
+      try {
+        preResumeAttempted = true;
+        preResumedEnrollment = await deps.resumeServerEnrollment(preResumeOrigin, () => {
+          deps.stderr(
+            `Resuming the pending enrollment for \`${preResumeOrigin}\`; ` +
+            'do not enter another invitation unless the server certificate was reissued; ' +
+            'if it was, request a current invitation and rerun this command.\n',
+          );
+        });
+      } catch {
+        preResumeAttempted = false;
+      }
+    }
+  }
+  if (artifactOnlyEnrollment ||
+      preResumeAttempted && preResumedEnrollment === null) {
+    if (artifactOnlyEnrollment && deps.resumePendingServerEnrollment) {
+      preResumedEnrollment = await deps.resumePendingServerEnrollment(() => {
+        deps.stderr('Resuming the pending enrollment; no new invitation is required.\n');
+      });
+    }
+    if (artifactOnlyEnrollment && preResumedEnrollment) {
+      // The exact pending tuple was already redeemed or is being resumed.
+    } else {
+      prefetchedInvitation = await deps.promptSecret('Enrollment invitation (single-use; hidden input):');
+      if (!prefetchedInvitation) {
+        deps.stderr('No enrollment invitation was entered. Ask the server operator for one, then retry.\n');
+        return 1;
+      }
+      try {
+        prefetchedArtifact = decodeAndVerifyInvitationArtifact(prefetchedInvitation);
+      } catch (error) {
+        deps.stderr(`${error instanceof Error ? error.message : 'The enrollment invitation is invalid.'}\n`);
+        prefetchedInvitation = undefined;
+        return 1;
+      }
+    }
+  }
+  if (!artifactOnlyEnrollment && args.flags.server === undefined && deps.defaultAuthority === undefined) {
     const connectCommand = mode === 'cube-init'
       ? 'borg server cube init --host <host>'
       : 'borg assimilate --host <host>';
@@ -686,8 +873,9 @@ export async function runAssimilate(
   }
 
   // ----- Step 1: Select and authenticate the local server -----
-  const authority = await selectAssimilationAuthority(args.flags, deps, mode);
-  if (!authority) return 1;
+  const selectedAuthority = await selectAssimilationAuthority(args.flags, deps, mode);
+  if (!selectedAuthority) return 1;
+  let authority: AssimilationAuthority = selectedAuthority;
   if (localSeatReadError !== undefined) {
     return reportServerFailure(deps, authority.apiUrl, localSeatReadError, false, mode);
   }
@@ -710,27 +898,48 @@ export async function runAssimilate(
           );
           return 1;
         }
-        const resumed = await deps.resumeServerEnrollment(authority.apiUrl, () => {
-          deps.stderr(
-            `Resuming the pending enrollment for \`${authority.apiUrl}\`; ` +
-              'do not enter another invitation.\n',
-          );
-        });
+        let resumed = preResumedEnrollment;
+        if (!resumed && prefetchedArtifact === undefined && !preResumeAttempted && !artifactOnlyEnrollment) {
+          resumed = await deps.resumeServerEnrollment(authority.apiUrl, () => {
+            deps.stderr(
+              `Resuming the pending enrollment for \`${authority.apiUrl}\`; ` +
+              'do not enter another invitation unless the server certificate was reissued; ' +
+              'if it was, request a current invitation and rerun this command.\n',
+            );
+          });
+        }
         if (resumed) {
+          if ('apiUrl' in resumed && typeof resumed.apiUrl === 'string') {
+            authority = { kind: 'server', apiUrl: resumed.apiUrl };
+          }
           serverAuth = resumed;
         } else {
-          let invitation = await deps.promptSecret(
-            `Enrollment invitation for \`${authority.apiUrl}\` (single-use; hidden input):`,
+          let invitation = prefetchedInvitation ?? await deps.promptSecret(
+            artifactOnlyEnrollment
+              ? 'Enrollment invitation (single-use; hidden input):'
+              : `Enrollment invitation for \`${authority.apiUrl}\` (single-use; hidden input):`,
           );
           if (!invitation) {
-            deps.stderr(
-              `No enrollment invitation was entered for ${authority.apiUrl}. ` +
-                `Ask the server operator for one, then rerun ${localAssimilateCommand(authority.apiUrl, true, mode)}.\n`,
-            );
+            deps.stderr(artifactOnlyEnrollment
+              ? 'No enrollment invitation was entered. Ask the server operator for one, then rerun `borg assimilate --enroll`.\n'
+              : `No enrollment invitation was entered for ${authority.apiUrl}. ` +
+                `Ask the server operator for one, then rerun ${localAssimilateCommand(authority.apiUrl, true, mode)}.\n`);
             return 1;
           }
           try {
-            serverAuth = await deps.connectServer(authority.apiUrl, { invitation });
+            const artifact = prefetchedArtifact ?? decodeAndVerifyInvitationArtifact(invitation);
+            if (args.flags.server !== undefined && authority.apiUrl !== artifact.endpoint) {
+              throw new InvitationArtifactEndpointMismatchError(authority.apiUrl, artifact.endpoint);
+            }
+            authority = { kind: 'server', apiUrl: artifact.endpoint };
+            serverAuth = await deps.connectServer(authority.apiUrl, {
+              invitation,
+              artifact,
+              confirmReplacement: async () => strictAffirmative(await deps.prompt(
+                  `A local enrollment for ${authority.apiUrl} already exists. Replacing it will orphan ` +
+                    'the first enrolled client. Replace it? [y/N]: ',
+              )),
+            });
           } finally {
             // Strings cannot be zeroized in JavaScript, but drop this command's
             // reference immediately after the exchange instead of retaining the
@@ -758,6 +967,11 @@ export async function runAssimilate(
         serverTrustIdentity: serverAuth.trustIdentity,
         serverCapabilities: serverAuth.serverCapabilities ?? [],
       };
+      if (args.flags.enroll) {
+        deps.stderr(
+          `This machine (${deps.getHostname()}) is enrolled with Borg server \`${authority.apiUrl}\`.\n`,
+        );
+      }
     } catch (error) {
       return reportServerFailure(deps, authority.apiUrl, error, args.flags.enroll === true, mode);
     }
@@ -1492,7 +1706,7 @@ export async function runAssimilate(
       deps.stderr(
         'Borg could not enumerate this repository’s existing worktrees, so it did not risk creating a colliding sibling.\n' +
         'Run `git worktree list` from this repository and resolve the reported Git error, then rerun `borg assimilate`.\n' +
-        'A seat was reserved and remains pending; rerunning after fixing the worktree issue resumes that seat.\n',
+        'A local drone reservation was created and remains pending; rerunning after fixing the worktree issue resumes that reservation.\n',
       );
       return 1;
     }
@@ -1565,13 +1779,13 @@ export async function runAssimilate(
           ? `Git left branch ${residualBranch} without a registered worktree; Borg preserved it.\n`
           : '') +
         'Run `git worktree list` and `git status` to inspect repository state, resolve the reported Git error, then rerun `borg assimilate`.\n' +
-        'A seat was reserved and remains pending; rerunning after fixing the worktree issue resumes that seat.\n',
+        'A local drone reservation was created and remains pending; rerunning after fixing the worktree issue resumes that reservation.\n',
       );
       return 1;
     }
     deps.stderr(
       `spawned sibling worktree at ${candidate} on branch ${wtBranch} (${startRef}); ` +
-      `the original dir keeps its active seat — run \`borg reset-local-seat\` there if that binding is stale.\n`
+      `the original dir keeps its active drone binding — run \`borg reset-local-seat\` there if that binding is stale.\n`
     );
     deps.chdir(candidate);
     deps.stderr(renderWorktreeSteeringNote(candidate, wtBranch, projectRoot));

package/src/assimilate-deps.ts

@@ -34,6 +34,7 @@ import {
   connectLocalBorgServer,
   createLocalBorgServerCube,
   enrollLocalBorgServer,
+  enrollLocalBorgServerArtifact,
   probeLocalBorgServer,
   resolveLocalBorgServerRepositoryCube,
   resumeLocalBorgServerEnrollment,
@@ -62,6 +63,7 @@ import {
   setCodexWakeTarget,
 } from './cubes.js';
 import { addProjectSessionStartHook } from './config-utils.js';
+import { findPendingServerEnrollment } from './config.js';
 import { setTerminalTitle as setTitle } from './terminal-title.js';
 import { defaultCliChoiceDeps, resolveCliChoice } from './cli-platform.js';
 import { prepareCodexRemoteLaunch, defaultCodexRemoteDeps } from './codex-remote.js';
@@ -240,7 +242,19 @@ export function buildDefaultAssimilateDeps(
         : null,
     connectServer: async (apiUrl, enrollment) => {
       if (enrollment) {
+        if (enrollment.artifact) {
+          return enrollLocalBorgServerArtifact(enrollment.artifact, {
+            invitation: enrollment.invitation,
+            ...(enrollment.confirmReplacement === undefined
+              ? {}
+              : { confirmReplacement: enrollment.confirmReplacement }),
+            clientName: osHostname(),
+          });
+        }
         return enrollLocalBorgServer(apiUrl, enrollment.invitation, {
+          ...(enrollment.confirmReplacement === undefined
+            ? {}
+            : { confirmReplacement: enrollment.confirmReplacement }),
           clientName: osHostname(),
         });
       }
@@ -250,6 +264,21 @@ export function buildDefaultAssimilateDeps(
       resumeLocalBorgServerEnrollment(apiUrl, {
         ...(onPending === undefined ? {} : { onPending }),
       }),
+    peekPendingServerEnrollment: async () => {
+      const pending = await findPendingServerEnrollment();
+      return pending === null
+        ? null
+        : { origin: pending.origin, invitation: pending.invitation };
+    },
+    resumePendingServerEnrollment: async (onPending) =>
+      (async () => {
+        const pending = await findPendingServerEnrollment();
+        if (!pending) return null;
+        const result = await resumeLocalBorgServerEnrollment(pending.origin, {
+          ...(onPending === undefined ? {} : { onPending }),
+        });
+        return result ? { ...result, apiUrl: pending.origin } : null;
+      })(),
 
     resolveRepositoryCube: async (apiUrl, token, input, serverTrustIdentity) => {
       if (serverTrustIdentity === undefined) {

package/src/assimilate-welcome.ts

@@ -33,6 +33,7 @@ export function renderAssimilationWelcome(
     ``,
     `In the launched agent, run \`borg_whoami\` and \`borg_roster\` to verify the seat`,
     `and begin coordinating.`,
+    `Launch future sessions in this repository with \`borg\`.`,
     ...teammateLines,
     ``,
   ].join('\n');

package/src/claude.ts

@@ -43,6 +43,7 @@ import {
 } from './reset-local-seat-cmd.js';
 import { parseLaunchAllArgs } from './parse-launch-all-args.js';
 import { unknownSubcommand } from './unknown-subcommand.js';
+import { parseRecoverEnrollmentArgs, runRecoverEnrollment } from './recover-enrollment-cmd.js';
 import { runLaunchAll } from './launch-all-cmd.js';
 import { buildDefaultLaunchAllDeps } from './launch-all-deps.js';
 import { discoverDroneCandidates } from './launch-all-discovery.js';
@@ -173,6 +174,27 @@ async function main() {
     const code = await runResetLocalSeat(parsed.flags, buildDefaultResetLocalSeatDeps());
     process.exit(code);
   }
+  if (process.argv[2] === 'recover-enrollment') {
+    const parsed = parseRecoverEnrollmentArgs(process.argv.slice(3));
+    if (!parsed.ok) {
+      if (parsed.error === 'help') {
+        process.stdout.write(clientSubcommandHelpText('recover-enrollment', [], getPackageVersion()) ?? '');
+        process.exit(0);
+      }
+      process.stderr.write(chalk.red(`${consolePrefix()}◼ borg recover-enrollment: ${parsed.error}\n`));
+      process.exit(1);
+    }
+    const prompt = async (message: string): Promise<string> => {
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      try { return await rl.question(message); } finally { rl.close(); }
+    };
+    const code = await runRecoverEnrollment(parsed.flags, {
+      prompt,
+      stderr: (line) => process.stderr.write(line),
+      stdout: (line) => process.stdout.write(line),
+    });
+    process.exit(code);
+  }
   if (process.argv[2] === 'spawn') {
     // Deprecated; the stub prints a redirect message and exits 2.
     const code = await runSpawn();

package/src/cli-help.ts

@@ -64,6 +64,7 @@ export function clientSubcommandHelpText(
     case 'setup': return setupHelpText(version);
     case 'assimilate': return assimilateHelpText(version);
     case 'reset-local-seat': return resetLocalSeatHelpText(version);
+    case 'recover-enrollment': return recoverEnrollmentHelpText(version);
     case 'sync': return syncHelpText(version);
     case 'cleanup': return cleanupHelpText(version);
     case 'launch-all': return launchAllHelpText(version);
@@ -74,9 +75,8 @@ export function clientSubcommandHelpText(
 export function setupNextStepsText(): string {
   return (
     `◼ Next steps:\n` +
-    `1. Run \`borg server setup\` to prepare the local server.\n` +
-    `2. Run \`borg server start\` and leave that terminal open.\n` +
-    `3. In a second terminal, cd into your project and run \`borg assimilate\`.\n`
+    `1. Run \`borg server start\` and leave that terminal open.\n` +
+    `2. In a second terminal, cd into your project's Git repository and run \`borg assimilate\`.\n`
   );
 }
 
@@ -102,6 +102,7 @@ export function topLevelHelpText(version: string): string {
     `  borg assimilate --worktree <name>   Spawn a worktree drone (in ~/.borg/worktrees/<repo>/<name>)\n` +
     `  borg server cube init    Initialize this repository's cube without creating a drone\n` +
     `  borg reset-local-seat    Clear ONLY this worktree's saved local seat (offline; after a rejection)\n` +
+    `  borg recover-enrollment  Clear ONLY one failed server enrollment transaction\n` +
     `  borg sync [--prune]      Sync this worktree's branch to origin/main\n` +
     `  borg cleanup [--prune]   Report (or --prune) worktrees orphaned by evicted drones\n` +
     `  borg launch-all [cube]   Launch all drone worktrees of a cube (default: active cube)\n` +
@@ -114,6 +115,17 @@ export function topLevelHelpText(version: string): string {
   );
 }
 
+export function recoverEnrollmentHelpText(version: string): string {
+  return (
+    `borg recover-enrollment (borgmcp ${version}) — clear one failed server enrollment\n\n` +
+    `Usage:\n` +
+    `  borg recover-enrollment [--host <host>] [--yes]\n` +
+    `  borg recover-enrollment --help\n\n` +
+    `This operation clears only the failed enrollment transaction for one server.\n` +
+    `It does not touch other server enrollments or accounts. It never requires manual file editing.\n`
+  );
+}
+
 /** Help for the whole-product, npm-owned update journey. */
 export function updateHelpText(version: string): string {
   return (
@@ -144,6 +156,7 @@ export function serverHelpText(): string {
     `  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` +
+    `  cert-reissue  Widen the server certificate to cover another address without replacing the CA.\n` +
     `  dashboard   View the running local server dashboard.\n` +
     `  cube init   Initialize this Git repository's cube; does not create a drone.\n\n` +
     `Run borg server <command> --help for server command options.\n`