borgmcp 2.9.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({
@@ -448,6 +551,7 @@ export async function activatePendingServerEnrollment(
     clientId: string;
     serverCapabilities: ServerCapability[];
     allowReplacement?: boolean;
+    replacementCapability?: string;
   },
 ): Promise<void> {
   validateServerCredentialBinding(input.origin, input.trustIdentity);
@@ -466,25 +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');
     }
-    if (!input.allowReplacement && await backend.get(serverCredentialAccount(input.origin, input.trustIdentity))) {
-      throw new Error('local Borg server enrollment already exists');
+    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');
     }
-    // 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, {
+    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);
+    }
   });
 }
 
@@ -641,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/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;
+}

package/src/regen-format.ts

@@ -19,6 +19,7 @@ import {
 import { shellEscape } from './shell-escape.js';
 import { resolveInboxMonitorPath } from './self-path.js';
 import { OPENCODE_WAKE_PATH_GUIDANCE } from './opencode-wake-copy.js';
+import { isBorgSession } from './launch-gate.js';
 
 /**
  * Extract the SessionStart `source` from a Claude Code hook payload (gh#926).
@@ -46,6 +47,30 @@ export function parseHookSource(raw: string): string | null {
   }
 }
 
+/** Best-effort relay directive for a plain Claude/Codex session. */
+export function formatPlainSessionReminder(): string {
+  return [
+    'Relay exactly this one line to the user once, without paraphrasing:',
+    'This repository is connected to a Borg cube, but this session was not launched with `borg`; cube coordination is inactive for this session. Relaunch with `borg` to use cube coordination.',
+  ].join('\n');
+}
+
+export function shouldRelayPlainSessionReminder(args: {
+  source: string | null;
+  agentKind: AgentKind;
+  hasActiveCube: boolean;
+  borgSession: string | undefined;
+  disabled: string | undefined;
+}): boolean {
+  return (
+    args.source === 'startup' &&
+    args.agentKind !== 'opencode' &&
+    args.hasActiveCube &&
+    !isBorgSession({ BORG_SESSION: args.borgSession }) &&
+    args.disabled === undefined
+  );
+}
+
 /** The agent runtime a session runs under — drives the wake-path branch. */
 export type AgentKind = 'claude' | 'codex' | 'opencode';
 

package/src/regen.ts

@@ -22,12 +22,18 @@ import { monitorStateRootForWorktree } from './inbox-monitor.js';
 import {
   parseHookSource,
   formatLeanOrientation,
+  formatPlainSessionReminder,
+  shouldRelayPlainSessionReminder,
   type AgentKind,
 } from './regen-format.js';
 import { resolveSessionAgentKind } from './codex-app-wake.js';
 import { resolveReportableSessionAgentKind } from './agent-runtime.js';
 import { handleVersionFlag } from './version.js';
-import { gateAllowsActivation } from './launch-gate.js';
+import {
+  BORG_LAUNCH_REMINDER_DISABLED_ENV,
+  BORG_SESSION_ENV,
+  gateAllowsActivation,
+} from './launch-gate.js';
 import { resolveWorkingRepo } from './working-repo.js';
 import {
   confirmDisplayIdentity,
@@ -56,18 +62,40 @@ async function readStdin(): Promise<string> {
 
 async function main(): Promise<void> {
   handleVersionFlag();
+  const hookSource = parseHookSource(await readStdin());
   // gh#673 P1 (WI-4): the SessionStart orientation only activates in
   // borg-launched sessions — a vanilla `claude` anywhere (including an
   // assimilated repo) stays vanilla. Exit-0 no-op: a hook must never
   // block session start. ACTIVATION-only, never a security gate.
   if (!gateAllowsActivation('borg-regen SessionStart hook')) {
+    // launch-reminder-ux: plain sessions get one model-mediated relay only on
+    // the initial SessionStart event. No repo connection means no output.
+    let hasActiveCube = false;
+    try {
+      hasActiveCube = (await getActiveCube()) !== null;
+    } catch {
+      hasActiveCube = false;
+    }
+    if (shouldRelayPlainSessionReminder({
+      source: hookSource,
+      agentKind: resolveSessionAgentKind(),
+      hasActiveCube,
+      borgSession: process.env[BORG_SESSION_ENV],
+      disabled: process.env[BORG_LAUNCH_REMINDER_DISABLED_ENV],
+    })) {
+      try {
+        process.stdout.write(`${formatPlainSessionReminder()}\n`);
+      } catch {
+        // Plain-session discovery is best-effort and must stay silent on failure.
+      }
+    }
     return;
   }
   // gh#926/gh#927: the SessionStart `source` (startup/resume/clear/compact)
   // tags the orientation; on `/clear` Claude Code has cleared the
   // session-scoped `/loop` + `ScheduleWakeup`, and the kickoff prompt is
   // gone, so the lean orientation adds a "re-establish your wake path" note.
-  const source = parseHookSource(await readStdin());
+  const source = hookSource;
 
   const active = await getActiveCube();
   if (!active) {

package/src/seat-store.ts

@@ -238,6 +238,12 @@ export async function atomicWrite0600(
       await assertSecureFile(filePath);
     }
     await rename(tmp, filePath);
+    const parent = await open(dirname(filePath), 'r');
+    try {
+      await parent.sync();
+    } finally {
+      await parent.close();
+    }
   } catch (err) {
     await unlink(tmp).catch(() => {});
     throw err;