borgmcp 2.8.0 → 2.10.0

package/src/config.ts

@@ -48,6 +48,7 @@ export interface PendingServerEnrollmentRecord {
   retryKey: string;
   credential: string;
   clientName?: string;
+  replacementCapability?: string;
 }
 
 export interface PendingServerCubeCreationRecord {
@@ -244,6 +245,7 @@ export function __setServerCredentialBackendForTest(backend: TokenBackend | null
 async function writeServerCredentialRecord(
   backend: TokenBackend,
   record: ServerCredentialRecord,
+  allowReplacement = false,
 ): Promise<void> {
   validateServerCredentialBinding(record.origin, record.trustIdentity);
   validateEnrollmentCredential(record.credential);
@@ -251,6 +253,49 @@ async function writeServerCredentialRecord(
     validateUuid(record.clientId, 'client identity');
   }
   const serverCapabilities = validateServerCapabilities(record.serverCapabilities ?? []);
+  const targetAccount = serverCredentialAccount(record.origin, record.trustIdentity);
+  const exactExisting = await backend.get(targetAccount);
+  if (exactExisting !== null && !allowReplacement) {
+    throw new Error('local Borg server enrollment already exists for this origin and replacement was not confirmed');
+  }
+  if (backend.entries) {
+    const accounts = await backend.entries();
+    const conflicts = Object.entries(accounts).filter(([account, value]) => {
+      try {
+        const parsed = JSON.parse(value) as { version?: unknown; origin?: unknown };
+        return parsed.version === SERVER_CREDENTIAL_RECORD_VERSION && parsed.origin === record.origin;
+      } catch {
+        return false;
+      }
+    });
+    if (conflicts.length > 0 && !allowReplacement) {
+      throw new Error('local Borg server enrollment already exists for this origin and replacement was not confirmed');
+    }
+    if (allowReplacement && conflicts.length > 0) {
+      const target = targetAccount;
+      const value = JSON.stringify({
+        version: SERVER_CREDENTIAL_RECORD_VERSION,
+        origin: record.origin,
+        trustIdentity: record.trustIdentity,
+        credential: record.credential,
+        clientId: record.clientId ?? null,
+        serverCapabilities,
+      });
+      if (backend.replaceAccounts) {
+        const next = { ...accounts };
+        for (const [account] of conflicts) delete next[account];
+        next[target] = value;
+        await backend.replaceAccounts(next);
+        return;
+      }
+      // Set first so an injected write failure cannot remove the prior record.
+      await backend.set(target, value);
+      for (const [account] of conflicts) {
+        if (account !== target) await backend.delete(account);
+      }
+      return;
+    }
+  }
   await backend.set(
     serverCredentialAccount(record.origin, record.trustIdentity),
     JSON.stringify({
@@ -264,6 +309,17 @@ async function writeServerCredentialRecord(
   );
 }
 
+function encodeServerCredentialRecord(record: ServerCredentialRecord, serverCapabilities: ServerCapability[]): string {
+  return JSON.stringify({
+    version: SERVER_CREDENTIAL_RECORD_VERSION,
+    origin: record.origin,
+    trustIdentity: record.trustIdentity,
+    credential: record.credential,
+    clientId: record.clientId ?? null,
+    serverCapabilities,
+  });
+}
+
 /**
  * Persist one self-hosted server credential in the dedicated 0600 credential store.
  *
@@ -274,9 +330,12 @@ async function writeServerCredentialRecord(
  * not credential sources. CR3b: the load→set→rename runs inside ONE hold of the
  * single store lock so a concurrent writer cannot lose an unrelated account.
  */
-export async function storeServerCredential(record: ServerCredentialRecord): Promise<void> {
+export async function storeServerCredential(
+  record: ServerCredentialRecord,
+  options: { allowReplacement?: boolean } = {},
+): Promise<void> {
   const backend = await getServerCredentialBackend();
-  await withCredentialStoreLock(() => writeServerCredentialRecord(backend, record));
+  await withCredentialStoreLock(() => writeServerCredentialRecord(backend, record, options.allowReplacement === true));
 }
 
 /** Read an authority-bound active client record, failing closed on corruption. */
@@ -329,6 +388,20 @@ export async function getServerCredential(
   return (await getServerCredentialRecord(origin, trustIdentity))?.credential ?? null;
 }
 
+export async function hasServerCredentialForOrigin(origin: string): Promise<boolean> {
+  const backend = await getServerCredentialBackend();
+  if (!backend.entries) return false;
+  const accounts = await backend.entries();
+  return Object.values(accounts).some((value) => {
+    try {
+      const record = JSON.parse(value) as { version?: unknown; origin?: unknown };
+      return record.version === SERVER_CREDENTIAL_RECORD_VERSION && record.origin === origin;
+    } catch {
+      return false;
+    }
+  });
+}
+
 function decodePendingServerEnrollment(
   stored: string,
   origin: string,
@@ -347,6 +420,7 @@ function decodePendingServerEnrollment(
     typeof record.retryKey !== 'string' || !UUID_RE.test(record.retryKey) ||
     typeof record.credential !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(record.credential) ||
     (record.clientName !== undefined && typeof record.clientName !== 'string')
+    || (record.replacementCapability !== undefined && !UUID_RE.test(record.replacementCapability))
   ) {
     throw new Error('invalid');
   }
@@ -359,6 +433,7 @@ function decodePendingServerEnrollment(
     retryKey: record.retryKey,
     credential: record.credential,
     ...(record.clientName === undefined ? {} : { clientName: record.clientName }),
+    ...(record.replacementCapability === undefined ? {} : { replacementCapability: record.replacementCapability }),
   };
 }
 
@@ -381,6 +456,30 @@ export async function getPendingServerEnrollment(
   });
 }
 
+/** Find the sole pending enrollment so artifact-only retries need no invitation. */
+export async function findPendingServerEnrollment(): Promise<PendingServerEnrollmentRecord | null> {
+  const backend = await getServerCredentialBackend();
+  if (!backend.entries) return null;
+  return withCredentialStoreLock(async () => {
+    const matches: PendingServerEnrollmentRecord[] = [];
+    for (const value of Object.values(await backend.entries!())) {
+      try {
+        const raw = JSON.parse(value) as Partial<PendingServerEnrollmentRecord> & {
+          version?: unknown;
+          state?: unknown;
+        };
+        if (raw.version !== SERVER_PENDING_ENROLLMENT_RECORD_VERSION || raw.state !== 'pending') continue;
+        if (typeof raw.origin !== 'string' || typeof raw.trustIdentity !== 'string') continue;
+        matches.push(decodePendingServerEnrollment(value, raw.origin, raw.trustIdentity));
+      } catch {
+        // Ignore unrelated or corrupt records; the keyed resume path remains fail-closed.
+      }
+    }
+    if (matches.length > 1) throw new Error('multiple pending Borg server enrollments require an explicit server endpoint');
+    return matches[0] ?? null;
+  });
+}
+
 /**
  * Generate and persist an exact enrollment tuple before network I/O. A
  * pre-existing PENDING tuple must match the invitation and presentation name;
@@ -392,11 +491,13 @@ export async function getOrCreatePendingServerEnrollment(
     trustIdentity: string;
     invitation: string;
     clientName?: string;
+    replacementCapability?: string;
   },
 ): Promise<PendingServerEnrollmentRecord> {
   validateServerCredentialBinding(input.origin, input.trustIdentity);
   validateInvitation(input.invitation);
   validateClientName(input.clientName);
+  if (input.replacementCapability !== undefined) validateUuid(input.replacementCapability, 'replacement capability');
   const backend = await getServerCredentialBackend();
   const account = serverPendingEnrollmentAccount(input.origin, input.trustIdentity);
   return withCredentialStoreLock(async () => {
@@ -411,6 +512,7 @@ export async function getOrCreatePendingServerEnrollment(
         if (
           record.invitation !== input.invitation ||
           record.clientName !== input.clientName
+          || record.replacementCapability !== input.replacementCapability
         ) {
           throw new Error('mismatch');
         }
@@ -427,6 +529,7 @@ export async function getOrCreatePendingServerEnrollment(
       retryKey: randomUUID(),
       credential: randomBytes(32).toString('base64url'),
       ...(input.clientName === undefined ? {} : { clientName: input.clientName }),
+      ...(input.replacementCapability === undefined ? {} : { replacementCapability: input.replacementCapability }),
     };
     validateEnrollmentCredential(record.credential);
     await backend.set(account, JSON.stringify({
@@ -447,6 +550,8 @@ export async function activatePendingServerEnrollment(
     credential: string;
     clientId: string;
     serverCapabilities: ServerCapability[];
+    allowReplacement?: boolean;
+    replacementCapability?: string;
   },
 ): Promise<void> {
   validateServerCredentialBinding(input.origin, input.trustIdentity);
@@ -465,22 +570,56 @@ export async function activatePendingServerEnrollment(
         input.origin,
         input.trustIdentity,
       );
-      if (pending.retryKey !== input.retryKey || pending.credential !== input.credential) {
+      if (pending.retryKey !== input.retryKey || pending.credential !== input.credential ||
+          pending.replacementCapability !== input.replacementCapability) {
         throw new Error('mismatch');
       }
     } catch {
       throw new Error('pending Borg server enrollment does not match the verified response');
     }
-    // Already inside the single store lock — use the UNLOCKED write body so we do
-    // not re-acquire (and self-deadlock on) CREDENTIALS_LOCK (CR3b).
-    await writeServerCredentialRecord(backend, {
+    if (!input.allowReplacement) {
+      const existing = backend.entries
+        ? Object.values(await backend.entries()).some((value) => {
+          try {
+            const record = JSON.parse(value) as { version?: unknown; origin?: unknown };
+            return record.version === SERVER_CREDENTIAL_RECORD_VERSION && record.origin === input.origin;
+          } catch {
+            return false;
+          }
+        })
+        : await backend.get(serverCredentialAccount(input.origin, input.trustIdentity)) !== null;
+      if (existing) throw new Error('local Borg server enrollment already exists');
+    }
+    const activeRecord: ServerCredentialRecord = {
       origin: input.origin,
       trustIdentity: input.trustIdentity,
       credential: input.credential,
       clientId: input.clientId,
       serverCapabilities,
-    });
-    await backend.delete(pendingAccount);
+    };
+    // Replace the active record and retire the pending tuple in one account-map
+    // write. A failed map write therefore preserves the old active + pending state.
+    if (backend.entries && backend.replaceAccounts) {
+      const accounts = await backend.entries();
+      const target = serverCredentialAccount(input.origin, input.trustIdentity);
+      const next = { ...accounts };
+      for (const [account, value] of Object.entries(accounts)) {
+        try {
+          const parsed = JSON.parse(value) as { version?: unknown; origin?: unknown };
+          if (parsed.version === SERVER_CREDENTIAL_RECORD_VERSION && parsed.origin === input.origin) {
+            delete next[account];
+          }
+        } catch {
+          // Preserve unrelated malformed records; the backend's normal validation remains fail-closed.
+        }
+      }
+      next[target] = encodeServerCredentialRecord(activeRecord, serverCapabilities);
+      delete next[pendingAccount];
+      await backend.replaceAccounts(next);
+    } else {
+      await writeServerCredentialRecord(backend, activeRecord, input.allowReplacement === true);
+      await backend.delete(pendingAccount);
+    }
   });
 }
 
@@ -637,3 +776,23 @@ export async function clearServerCredential(origin: string, trustIdentity: strin
     await backend.delete(pendingAccount);
   });
 }
+
+/** Clear only the failed enrollment transaction for one origin/identity. */
+export async function clearEnrollmentTransaction(origin: string, trustIdentity: string): Promise<void> {
+  validateServerCredentialBinding(origin, trustIdentity);
+  const backend = await getServerCredentialBackend();
+  const pendingAccount = serverPendingEnrollmentAccount(origin, trustIdentity);
+  const credentialAccount = serverCredentialAccount(origin, trustIdentity);
+  await withCredentialStoreLock(async () => {
+    if (backend.entries && backend.replaceAccounts) {
+      const accounts = await backend.entries();
+      const next = { ...accounts };
+      delete next[pendingAccount];
+      delete next[credentialAccount];
+      await backend.replaceAccounts(next);
+      return;
+    }
+    await backend.delete(pendingAccount);
+    await backend.delete(credentialAccount);
+  });
+}

package/src/first-run-server.ts

@@ -1,3 +1,4 @@
+import { spawn } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -14,10 +15,12 @@ const CLIENT_PACKAGE = 'borgmcp';
 const SERVER_PACKAGE = 'borgmcp-server';
 const SHARED_PACKAGE = 'borgmcp-shared';
 const DEFAULT_CONNECT_COMMAND = 'borg assimilate --host <host>';
+const CLIENT_ONBOARDING_ENV = 'BORG_CLIENT_ONBOARDING';
+export const HINT_SUPPORTED_FROM = '0.8.1';
 
 export type FirstRunServerInstallResult =
-  | { kind: 'present'; server: InstalledPackage }
-  | { kind: 'installed'; server: InstalledPackage }
+  | { kind: 'present'; server: InstalledPackage; suppressClientNextSteps?: boolean }
+  | { kind: 'installed'; server: InstalledPackage; suppressClientNextSteps?: boolean }
   | { kind: 'declined' | 'non-interactive' | 'failed' };
 
 export interface FirstRunServerInstallDeps {
@@ -32,7 +35,8 @@ export interface FirstRunServerInstallDeps {
     version: string,
     options?: { ignoreScripts?: boolean },
   ): Promise<void>;
-  confirm(message: string): Promise<'yes' | 'no' | 'eof' | 'interrupted'>;
+  runServerSetup(server: InstalledPackage, options?: { onboardingHint?: boolean }): Promise<number>;
+  confirm(message: string, defaultYes?: boolean): Promise<'yes' | 'no' | 'eof' | 'interrupted'>;
   isTTY(): boolean;
   stdout(text: string): void;
   stderr(text: string): void;
@@ -84,6 +88,18 @@ export function buildDefaultFirstRunServerInstallDeps(): FirstRunServerInstallDe
     publishedPackage: update.publishedPackage,
     publishedVersions: update.publishedVersions,
     installGlobal: update.installGlobal,
+    runServerSetup: (server, options = {}) => new Promise((resolve) => {
+      const childEnv = { ...process.env };
+      delete childEnv[CLIENT_ONBOARDING_ENV];
+      if (options.onboardingHint) childEnv[CLIENT_ONBOARDING_ENV] = '1';
+      const child = spawn(server.binPath, ['setup'], {
+        stdio: 'inherit',
+        shell: false,
+        env: childEnv,
+      });
+      child.once('error', () => resolve(1));
+      child.once('exit', (code) => resolve(code ?? 1));
+    }),
     confirm: update.confirm,
     isTTY: update.isTTY,
     stdout: update.stdout,
@@ -100,6 +116,7 @@ export function buildDefaultFirstRunServerInstallDeps(): FirstRunServerInstallDe
 export async function offerFirstRunServerInstall(
   deps: FirstRunServerInstallDeps = buildDefaultFirstRunServerInstallDeps(),
   connectCommand = DEFAULT_CONNECT_COMMAND,
+  options: { initializeServer?: boolean } = {},
 ): Promise<FirstRunServerInstallResult> {
   let installed: InstalledPackage | null;
   try {
@@ -112,7 +129,15 @@ export async function offerFirstRunServerInstall(
     );
     return { kind: 'failed' };
   }
-  if (installed) return { kind: 'present', server: installed };
+  if (installed) {
+    return initializeServerIfRequested(
+      installed,
+      deps,
+      options.initializeServer,
+      'present',
+      shouldSuppressClientNextSteps(installed.version),
+    );
+  }
 
   if (!deps.isTTY()) {
     deps.stderr(
@@ -140,9 +165,11 @@ export async function offerFirstRunServerInstall(
   const command = exactInstallCommand(target.version);
   const decision = await deps.confirm(
     `No local ${SERVER_PACKAGE} installation was found. ` +
-    `Install ${SERVER_PACKAGE}@${target.version}, which uses ${SHARED_PACKAGE}@${target.sharedVersion}, now?\n` +
+      `Install ${SERVER_PACKAGE}@${target.version}, the local coordination server, ` +
+      `which uses ${SHARED_PACKAGE}@${target.sharedVersion}, now?\n` +
     `Command: ${command}\n` +
-    `Continue? [y/N] `,
+      `Install it now? [Y/n] `,
+      true,
   );
   if (decision !== 'yes') {
     const reason = decision === 'interrupted'
@@ -172,7 +199,43 @@ export async function offerFirstRunServerInstall(
 
   deps.stdout(
     `Installed ${SERVER_PACKAGE}@${target.version} with ${SHARED_PACKAGE}@${target.sharedVersion}.\n` +
-    `Next, run \`borg server setup\`, then run \`borg server start\` in a terminal you keep open.\n`,
+    (options.initializeServer
+      ? `The local server package is ready.\n`
+      : `Next, run \`borg server setup\`, then run \`borg server start\` in a terminal you keep open.\n`),
+  );
+  return initializeServerIfRequested(installed, deps, options.initializeServer, 'installed');
+}
+
+async function initializeServerIfRequested(
+  server: InstalledPackage,
+  deps: FirstRunServerInstallDeps,
+  requested: boolean | undefined,
+  kind: 'present' | 'installed',
+  suppressClientNextSteps = false,
+): Promise<FirstRunServerInstallResult> {
+  if (!requested) return { kind, server, ...(suppressClientNextSteps ? { suppressClientNextSteps: true } : {}) };
+  try {
+    const exitCode = await deps.runServerSetup(server, { onboardingHint: !suppressClientNextSteps });
+    if (exitCode === 0) {
+      return { kind, server, ...(suppressClientNextSteps ? { suppressClientNextSteps: true } : {}) };
+    }
+  } catch (error) {
+    deps.stderr(`Local server setup could not be completed. ${error instanceof Error ? error.message : String(error)}\n`);
+  }
+  deps.stderr(
+    'Run `borg server setup` to retry local server initialization, then run `borg server start`.\n',
   );
-  return { kind: 'installed', server: installed };
+  return { kind: 'failed' };
+}
+
+function shouldSuppressClientNextSteps(version: unknown): boolean {
+  if (!isExactSemver(version)) return false;
+  const installedParts = version.split('.').slice(0, 3).map(Number);
+  const supportedParts = HINT_SUPPORTED_FROM.split('.').map(Number);
+  for (let index = 0; index < 3; index += 1) {
+    if (installedParts[index] !== supportedParts[index]) {
+      return installedParts[index] < supportedParts[index];
+    }
+  }
+  return false;
 }

package/src/invitation-artifact.ts

@@ -0,0 +1,116 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import {
+  decodeInvitationArtifact,
+  encodeInvitationArtifact,
+  getInvitationArtifactIntegrityInput,
+  type InvitationArtifact,
+} from 'borgmcp-shared/protocol';
+
+export const COMPATIBILITY_INVITATION_ERROR =
+  'This server did not present the certificate chain required for cross-machine enrollment. Update the Borg server on that machine and restart it, then run this command again. No invitation or credential was sent and no local trust or credential state was changed.';
+
+export const TRUST_INVITATION_ERROR =
+  'Borg could not verify the server identity named by this invitation. No invitation or credential was sent and no local trust or credential state was changed. Ask the server operator for a current invitation, then retry.';
+
+export const FORMAT_INVITATION_ERROR =
+  'This enrollment invitation is invalid or incomplete. No invitation or credential was sent and no local trust or credential state was changed. Ask the server operator for a new invitation, then retry.';
+
+export const TRANSPORT_INVITATION_ERROR =
+  'Borg could not reach the server named by this invitation. No invitation or credential was sent and no local trust or credential state was changed. Check that the server is running and that this machine can reach the invitation endpoint, then retry.';
+
+export const STORAGE_INVITATION_ERROR =
+  'Borg could not prepare local trust state for this invitation. No invitation or credential was sent and no local trust or credential state was changed. Check that Borg can write its private local state, then retry.';
+
+export const RECOVERY_INVITATION_ERROR =
+  'Borg could not complete or undo the enrollment change. Prior local access may be unavailable. Run `borg recover-enrollment` to clear only this server enrollment transaction. The invitation used for this attempt has been consumed; after recovery, ask the server operator for a fresh invitation and retry.';
+
+export class InvitationArtifactCompatibilityError extends Error {
+  constructor(message = COMPATIBILITY_INVITATION_ERROR) {
+    super(message);
+    this.name = 'InvitationArtifactCompatibilityError';
+  }
+}
+
+export class InvitationArtifactLegacyError extends Error {
+  constructor() {
+    super(
+      'This invitation uses an older format. Update the Borg server on that machine and restart it, then ask the server operator for a new invitation and retry. No invitation or credential was sent and no local trust or credential state was changed.',
+    );
+    this.name = 'InvitationArtifactLegacyError';
+  }
+}
+
+export class InvitationArtifactFormatError extends Error {
+  constructor(message = FORMAT_INVITATION_ERROR) {
+    super(message);
+    this.name = 'InvitationArtifactFormatError';
+  }
+}
+
+export class InvitationArtifactEndpointMismatchError extends Error {
+  constructor(selectedEndpoint: string, invitationEndpoint: string) {
+    super(
+      `The enrollment invitation endpoint (${invitationEndpoint}) does not match the selected \`--host\` (${selectedEndpoint}). No invitation or credential was sent and no local trust or credential state was changed. Omit \`--host\` or select the exact invitation endpoint, then retry.`,
+    );
+    this.name = 'InvitationArtifactEndpointMismatchError';
+  }
+}
+
+export class InvitationArtifactStorageError extends Error {
+  constructor(message = STORAGE_INVITATION_ERROR) {
+    super(message);
+    this.name = 'InvitationArtifactStorageError';
+  }
+}
+
+export class InvitationArtifactRecoveryError extends Error {
+  constructor(message = RECOVERY_INVITATION_ERROR) {
+    super(message);
+    this.name = 'InvitationArtifactRecoveryError';
+  }
+}
+
+export class InvitationArtifactTransportError extends Error {
+  constructor(message = TRANSPORT_INVITATION_ERROR) {
+    super(message);
+    this.name = 'InvitationArtifactTransportError';
+  }
+}
+
+export class InvitationArtifactTrustError extends Error {
+  constructor(message = TRUST_INVITATION_ERROR) {
+    super(message);
+    this.name = 'InvitationArtifactTrustError';
+  }
+}
+
+function invitationIntegrity(artifact: InvitationArtifact): string {
+  return createHmac('sha256', artifact.secret)
+    .update(getInvitationArtifactIntegrityInput({
+      ...artifact,
+      integrity: 'p'.repeat(43),
+    }))
+    .digest('base64url');
+}
+
+export function decodeAndVerifyInvitationArtifact(value: unknown): InvitationArtifact {
+  let artifact: InvitationArtifact;
+  try {
+    artifact = decodeInvitationArtifact(
+      typeof value === 'string' ? value : encodeInvitationArtifact(value as InvitationArtifact),
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : '';
+    if (typeof value === 'string' && value.length === 43) throw new InvitationArtifactLegacyError();
+    if (/legacy|unsupported/i.test(message)) throw new InvitationArtifactLegacyError();
+    if (/certificate chain/i.test(message)) throw new InvitationArtifactCompatibilityError();
+    throw new InvitationArtifactFormatError();
+  }
+  const expected = Buffer.from(invitationIntegrity(artifact), 'utf8');
+  const actual = Buffer.from(artifact.integrity, 'utf8');
+  if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) {
+    if (typeof value === 'string' && value.length === 43) throw new InvitationArtifactLegacyError();
+    throw new InvitationArtifactFormatError();
+  }
+  return artifact;
+}

package/src/launch-gate.ts

@@ -11,7 +11,7 @@
  *   2. the borg-regen SessionStart hook bin — exit-0 no-op;
  *   3. the borg-clear-rewake clear-only hook bin — exit-0 no-op;
  *   4. the borg-log-audit UserPromptSubmit hook bin — exit-0 no-op.
- * Result: `claude` launched directly is vanilla Claude Code; `borg`
+ * Result: direct agent launches keep the Borg surface inactive; `borg`
  * launches get the full surface.
  *
  * Codex (V2/V2b probes): codex does NOT forward parent env to MCP
@@ -36,6 +36,8 @@ import { envToggleOn } from './auth-env.js';
 import { debugLog } from './debug.js';
 
 export const BORG_SESSION_ENV = 'BORG_SESSION';
+/** Presence-based local opt-out for the plain-session launch reminder. */
+export const BORG_LAUNCH_REMINDER_DISABLED_ENV = 'BORG_DISABLE_LAUNCH_REMINDER';
 
 /** True when this process runs inside a borg-launched session. */
 export function isBorgSession(env: NodeJS.ProcessEnv = process.env): boolean {
@@ -43,16 +45,13 @@ export function isBorgSession(env: NodeJS.ProcessEnv = process.env): boolean {
 }
 
 /**
- * The non-silent per-tool notice a vanilla (non-borg-launched) session
- * receives when invoking a borg_* tool. Explains the state — nothing is
- * wrong with the cube — and points at the borg launch path.
+ * The non-silent per-tool notice a non-borg-launched session receives when
+ * invoking a borg_* tool. Outcome first; no CLI-specific or seat language.
  */
 export function borgSessionToolNotice(toolName: string): string {
   return (
-    `◼ ${toolName} is inactive: this session wasn't launched via \`borg\`, so the borg ` +
-    `coordination surface is dormant (vanilla Claude Code). To use cube coordination, ` +
-    `re-launch from a terminal with \`borg\` (or \`borg assimilate\` to set up a seat first). ` +
-    `Power users can opt in manually by launching with BORG_SESSION=1.`
+    `◼ ${toolName} did not run: Borg tools are inactive because this session was not ` +
+    `launched with \`borg\`. Relaunch this session with \`borg\` to use cube coordination.`
   );
 }
 

package/src/parse-assimilate-args.ts

@@ -1,4 +1,8 @@
 import type { AssimilateFlags } from './assimilate-cmd.js';
+import { validateName } from './name-validator.js';
+
+const ENROLLMENT_POSITIONAL_INPUT_ERROR =
+  'That argument was not accepted. If you meant a role name, use lowercase letters, digits, hyphens, or underscores, up to 48 characters. If you meant an enrollment invitation, it must be entered at the hidden prompt — re-run the same command without it.';
 
 export interface ParseAssimilateResult {
   ok: true;
@@ -18,6 +22,7 @@ export type ParseResult =
 export function parseAssimilateArgs(rawArgs: string[]): ParseResult {
   let role: string | undefined;
   const flags: AssimilateFlags = {};
+  const enrollmentRequested = rawArgs.includes('--enroll');
 
   for (let i = 0; i < rawArgs.length; i += 1) {
     const arg = rawArgs[i];
@@ -105,8 +110,14 @@ export function parseAssimilateArgs(rawArgs: string[]): ParseResult {
       };
     } else {
       if (role !== undefined) {
+        if (enrollmentRequested) {
+          return { ok: false, error: ENROLLMENT_POSITIONAL_INPUT_ERROR };
+        }
         return { ok: false, error: `unexpected extra argument: ${arg} (already have role "${role}")` };
       }
+      if (enrollmentRequested && !validateName(arg).ok) {
+        return { ok: false, error: ENROLLMENT_POSITIONAL_INPUT_ERROR };
+      }
       role = arg;
     }
   }
@@ -119,9 +130,5 @@ export function parseAssimilateArgs(rawArgs: string[]): ParseResult {
   if (flags.template !== undefined && flags.noTemplate) {
     return { ok: false, error: '--template and --no-template are mutually exclusive' };
   }
-  if (flags.enroll && flags.server === undefined) {
-    return { ok: false, error: '--enroll requires --host <host>' };
-  }
-
   return { ok: true, role, flags };
 }

package/src/recover-enrollment-cmd.ts

@@ -0,0 +1,63 @@
+import { normalizeServerEndpoint } from './server-endpoint.js';
+import { clearEnrollmentTransaction, findPendingServerEnrollment } from './config.js';
+import { clearBorgServerTrust } from './server-trust.js';
+
+export interface RecoverEnrollmentFlags {
+  host?: string;
+  yes: boolean;
+}
+
+export function parseRecoverEnrollmentArgs(argv: string[]):
+  { ok: true; flags: RecoverEnrollmentFlags } | { ok: false; error: string } {
+  let host: string | undefined;
+  let yes = false;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--yes' || arg === '-y') { yes = true; continue; }
+    if (arg === '--host' || arg === '-h') {
+      const value = argv[++index];
+      if (!value) return { ok: false, error: 'missing value for --host' };
+      host = value;
+      continue;
+    }
+    if (arg?.startsWith('--host=')) { host = arg.slice('--host='.length); continue; }
+    if (arg === '--help') return { ok: false, error: 'help' };
+    return { ok: false, error: `unexpected argument: ${arg}` };
+  }
+  return { ok: true, flags: { ...(host === undefined ? {} : { host }), yes } };
+}
+
+export async function runRecoverEnrollment(
+  flags: RecoverEnrollmentFlags,
+  deps: { prompt: (message: string) => Promise<string>; stderr: (line: string) => void; stdout: (line: string) => void },
+): Promise<number> {
+  const pending = await findPendingServerEnrollment();
+  if (!pending) {
+    deps.stderr('No recoverable Borg enrollment transaction was found. No state was changed.\n');
+    return 1;
+  }
+  let origin = pending.origin;
+  if (flags.host !== undefined) {
+    try { origin = normalizeServerEndpoint(flags.host); } catch (error) {
+      deps.stderr(`${error instanceof Error ? error.message : String(error)}\n`);
+      return 1;
+    }
+    if (origin !== pending.origin) {
+      deps.stderr('The recovery host does not match the failed enrollment transaction. No state was changed.\n');
+      return 1;
+    }
+  }
+  if (!flags.yes) {
+    const answer = await deps.prompt(
+      `Clear only the failed enrollment for ${origin}? Other server enrollments and accounts will not be touched. [y/N]: `,
+    );
+    if (!/^y(?:es)?$/i.test(answer.trim())) {
+      deps.stderr('Enrollment recovery was not confirmed. No state was changed.\n');
+      return 1;
+    }
+  }
+  await clearEnrollmentTransaction(origin, pending.trustIdentity);
+  await clearBorgServerTrust(origin);
+  deps.stdout(`Cleared the failed enrollment transaction for ${origin}; other server enrollments and accounts were left unchanged.\n`);
+  return 0;
+}