borgmcp 2.14.2 → 2.16.0

package/src/private-root.ts

@@ -1,8 +1,68 @@
+import { lstatSync, realpathSync } from 'node:fs';
 import { chmod, lstat, mkdir } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { isAbsolute, join, resolve } from 'node:path';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 
-export const borgConfigRoot = (): string => join(homedir(), '.config', 'borgmcp');
+/**
+ * Optional alternate home root for isolated client runs. The value is the
+ * replacement home directory, not the `.config/borgmcp` directory itself, so
+ * every client-owned path (credentials, seats, worktrees, and agent config)
+ * stays under one root.
+ */
+export const BORG_STATE_ROOT_ENV = 'BORG_STATE_ROOT';
+
+function invalidStateRoot(): Error {
+  return new Error(`${BORG_STATE_ROOT_ENV} must be an absolute canonical path`);
+}
+
+/** Return whether a path and every existing ancestor are free of symlinks. */
+export function isCanonicalPath(root: string): boolean {
+  if (!isAbsolute(root) || resolve(root) !== root) return false;
+  let candidate = root;
+  while (true) {
+    try {
+      const metadata = lstatSync(candidate);
+      return !metadata.isSymbolicLink() && realpathSync(candidate) === candidate;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      const parent = dirname(candidate);
+      if (parent === candidate) return false;
+      candidate = parent;
+    }
+  }
+}
+
+function configuredStateRoot(env: NodeJS.ProcessEnv = process.env): string | null {
+  const configured = env[BORG_STATE_ROOT_ENV];
+  if (configured === undefined) return null;
+  if (configured.length === 0 || !isCanonicalPath(configured)) {
+    throw invalidStateRoot();
+  }
+  return configured;
+}
+
+/** Resolve the effective home root used by all Borg-owned local state. */
+export function borgHomeRoot(env: NodeJS.ProcessEnv = process.env): string {
+  return configuredStateRoot(env) ?? realpathSync(homedir());
+}
+
+export const borgConfigRoot = (): string => join(borgHomeRoot(), '.config', 'borgmcp');
+
+/**
+ * Environment used when a native agent CLI registers Borg. The CLI must write
+ * its own config under the same effective root that config-utils reads; the
+ * eventual MCP child receives BORG_STATE_ROOT separately via its registration.
+ */
+export function borgAgentConfigEnv(env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  if (env[BORG_STATE_ROOT_ENV] === undefined) return { ...env };
+  const root = borgHomeRoot(env);
+  return {
+    ...env,
+    HOME: root,
+    CODEX_HOME: join(root, '.codex'),
+    XDG_CONFIG_HOME: join(root, '.config'),
+  };
+}
 
 /** Ensure Borg's local state root exists with owner-only directory permissions. */
 export async function ensurePrivateBorgConfigRoot(root = borgConfigRoot()): Promise<void> {

package/src/regen-format.ts

@@ -243,7 +243,7 @@ export function markArrivalAnnouncedThisProcess(): void {
 export function getDronePlaybook(): string {
   const arrivalInstruction = arrivalAnnouncedThisProcess
     ? ''
-    : '\n**When this MCP session first starts:** post one `ARRIVAL: <your-label> (<your-role>) online on <hostname> at <project-path>` (run `hostname`; use cwd for the path). After the post succeeds, the client suppresses this instruction until the MCP process restarts; an explicit `/mcp` reconnect may show it again.\n';
+    : '\n**When this MCP session first starts:** post one `ARRIVAL: <your-label> (<your-role>) online on <hostname>` (run `hostname`). After the post succeeds, the client suppresses this instruction until the MCP process restarts; an explicit `/mcp` reconnect may show it again.\n';
   return `## How to operate as a Drone
 
 You're a Drone in a Cube. Coordinate with other drones through the activity log.

package/src/resolved-cli-config.ts

@@ -0,0 +1,40 @@
+import type { BorgCli } from './cubes.js';
+
+export interface ResolvedCliConfigDeps {
+  ensureMcp(cli: BorgCli): void;
+  addClaudeProjectSessionStartHook(): void;
+  removeClaudeGlobalSessionStartHook(): void;
+  addClaudeUserPromptSubmitHook(): void;
+  addCodexSessionStartHook(): void;
+  addCodexUserPromptSubmitHook(): void;
+}
+/**
+ * Apply only the integration writes for the CLI the launcher resolved.
+ * In particular, a Claude installation must not cause Codex or OpenCode
+ * configuration to be repaired as a side effect of a bare `borg` launch.
+ */
+export function configureResolvedCli(
+  cli: BorgCli,
+  deps: ResolvedCliConfigDeps,
+): void {
+  if (cli === 'claude') {
+    deps.ensureMcp('claude');
+    // The project-local SessionStart hook is the launch-time self-heal for
+    // the CLI actually being launched. Remove only the obsolete global hook
+    // after the local hook is in place, then keep the Claude prompt hook in
+    // its existing global location.
+    deps.addClaudeProjectSessionStartHook();
+    deps.removeClaudeGlobalSessionStartHook();
+    deps.addClaudeUserPromptSubmitHook();
+    return;
+  }
+
+  if (cli === 'codex') {
+    deps.ensureMcp('codex');
+    deps.addCodexSessionStartHook();
+    deps.addCodexUserPromptSubmitHook();
+    return;
+  }
+
+  deps.ensureMcp('opencode');
+}

package/src/seat-store.ts

@@ -32,9 +32,10 @@
  */
 
 import { constants } from 'node:fs';
-import { open, link, lstat, mkdir, readFile, realpath, rename, stat, unlink } from 'node:fs/promises';
+import { open, link, lstat, mkdir, readFile, rename, stat, unlink } from 'node:fs/promises';
 import { dirname, isAbsolute, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
+import { isCanonicalPath } from './private-root.js';
 
 const LOCK_WAIT_MS = 10;
 const LOCK_ATTEMPTS = 500;
@@ -58,7 +59,7 @@ async function assertSecureRoot(
   root: string,
   rootMode: SecureStoreOptions['rootMode'] = 'private',
 ): Promise<void> {
-  if (!isAbsolute(root) || resolve(root) !== root) {
+  if (!isCanonicalPath(root)) {
     throw new Error(`Borg credential store path ${root} is not canonical`);
   }
   let metadata: Awaited<ReturnType<typeof lstat>>;
@@ -83,7 +84,7 @@ async function assertSecureRoot(
   if (uid !== null && metadata.uid !== uid) {
     throw new Error(`Borg credential store root ${root} is not owned by the current user`);
   }
-  if (await realpath(root) !== root) {
+  if (!isCanonicalPath(root)) {
     throw new Error(`Borg credential store root ${root} is not canonical or contains a symlink`);
   }
 }

package/src/seats.ts

@@ -17,13 +17,13 @@
  * hydration reader; every other observation is digest-only.
  */
 
-import os from 'os';
 import path from 'path';
 import { createHash } from 'node:crypto';
 import { readStoreFile, withStore } from './seat-store.js';
 import { LegacySessionCredentialCollisionError } from './server-errors.js';
+import { borgConfigRoot } from './private-root.js';
 
-export const SEATS_FILE = path.join(os.homedir(), '.config', 'borgmcp', 'seats.json');
+export const SEATS_FILE = path.join(borgConfigRoot(), 'seats.json');
 const SEATS_VERSION = 1 as const;
 const REF_RE = /^borg-server-session:[a-f0-9]{64}$/;
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

package/src/self-path.ts

@@ -49,3 +49,8 @@ export function resolveClearRewakePath(): string {
 export function resolveLogAuditPath(): string {
   return resolveSelfBinPath('log-audit.js');
 }
+
+/** Absolute path to the optional pre-tool foreign-path reminder hook. */
+export function resolveForeignPathReminderPath(): string {
+  return resolveSelfBinPath('foreign-path-reminder.js');
+}

package/src/server-trust.ts

@@ -4,7 +4,6 @@ import { constants } from 'node:fs';
 import { access, lstat, mkdir, open, rename, rm, unlink, writeFile } from 'node:fs/promises';
 import { request as httpsRequest } from 'node:https';
 import { connect as tlsConnect } from 'node:tls';
-import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { Readable } from 'node:stream';
 import { BorgServerTrustError } from './server-errors.js';
@@ -27,6 +26,7 @@ import type {
   EnrollmentArtifactBinding,
   EnrollmentTrustPointer,
 } from './enrollment-types.js';
+import { borgHomeRoot } from './private-root.js';
 
 // CR5 TLS LATTICE: OpenSSL/Node TLS certificate-verification error codes. A raw
 // CA / cert-chain / SAN failure from the pinned transport is a potential MITM and
@@ -102,12 +102,12 @@ function invalidateOriginTrustCache(origin: string): void {
 }
 
 function serverDataDirectory(): string {
-  return resolve(process.env.BORG_SERVER_DATA_DIR ?? join(homedir(), '.borg', 'server'));
+  return resolve(process.env.BORG_SERVER_DATA_DIR ?? join(borgHomeRoot(), '.borg', 'server'));
 }
 
 function remoteTrustDirectory(origin: string): string {
   const key = createHash('sha256').update(origin).digest('hex');
-  return join(homedir(), '.borg', 'server-trust', key);
+  return join(borgHomeRoot(), '.borg', 'server-trust', key);
 }
 
 function trustGenerationsDirectory(origin: string): string {

package/src/setup-confirm.ts

@@ -4,7 +4,7 @@
  * Step-1 of the setup wizard writes the user's GLOBAL agent config
  * (registers the borg MCP server + hooks). Before gh#818 this happened
  * silently on first run. This module adds informed-consent disclosure:
- * it lists WHICH files will be written (well-known `os.homedir()` paths)
+ * it lists WHICH files will be written (well-known home-relative paths)
  * and asks to continue before the first mutation.
  *
  * Pure / dep-injected (mirrors `resolveCliChoice` + `setup-action.ts`) so

package/src/setup-selection.ts

@@ -0,0 +1,87 @@
+import type { BorgCli } from './cubes.js';
+
+export interface SetupAgentChoice {
+  title: string;
+  value: BorgCli;
+  selected: boolean;
+  disabled?: boolean;
+}
+
+export type SetupAgentSelection =
+  | { kind: 'selected'; agents: BorgCli[] }
+  | { kind: 'empty' }
+  | { kind: 'cancelled' };
+
+export interface EmptySetupOutcome {
+  kind: 'empty';
+  agentConfigurationChanged: false;
+  localServerInitializationStarted: false;
+  recovery: {
+    kind: 'rerun-setup';
+    command: 'borg setup';
+  };
+}
+
+const CLI_TITLES: Record<BorgCli, string> = {
+  claude: 'Claude Code',
+  codex: 'Codex',
+  opencode: 'OpenCode',
+};
+
+/** Build the first-run choices from the CLIs that are actually installed. */
+export function setupAgentChoices(
+  detected: readonly BorgCli[],
+  alreadyConfigured: ReadonlySet<BorgCli> = new Set(),
+): SetupAgentChoice[] {
+  return [...new Set(detected)].map((cli) => ({
+    title: alreadyConfigured.has(cli)
+      ? `${CLI_TITLES[cli]} (already configured)`
+      : CLI_TITLES[cli],
+    value: cli,
+    selected: !alreadyConfigured.has(cli),
+    ...(alreadyConfigured.has(cli) ? { disabled: true } : {}),
+  }));
+}
+
+/** The agent names whose newly selected setup needs a restart notice. */
+export function setupRestartInstruction(selected: readonly BorgCli[]): string {
+  const labels = selected.map((cli) => CLI_TITLES[cli]);
+  return `🔄 Restart ${labels.join(' / ')} (or open a new session) for the changes to take effect.`;
+}
+
+/** Describe the accepted zero-selection result and its recovery path. */
+export function emptySetupOutcome(): EmptySetupOutcome {
+  return {
+    kind: 'empty',
+    agentConfigurationChanged: false,
+    localServerInitializationStarted: false,
+    recovery: {
+      kind: 'rerun-setup',
+      command: 'borg setup',
+    },
+  };
+}
+
+/**
+ * Keep only detected agents and return them in detection order. The selected
+ * set is invocation-local; it is deliberately never persisted.
+ */
+export function normalizeSetupAgentSelection(
+  detected: readonly BorgCli[],
+  selected: readonly unknown[] | undefined,
+): BorgCli[] {
+  if (!Array.isArray(selected)) return [];
+  const selectedSet = new Set(selected);
+  return [...new Set(detected)].filter((cli) => selectedSet.has(cli));
+}
+
+/** Turn the prompt result into the terminal outcome used by the wizard. */
+export function resolveSetupAgentSelection(
+  detected: readonly BorgCli[],
+  selected: readonly unknown[] | undefined,
+  cancelled = false,
+): SetupAgentSelection {
+  if (cancelled) return { kind: 'cancelled' };
+  const agents = normalizeSetupAgentSelection(detected, selected);
+  return agents.length === 0 ? { kind: 'empty' } : { kind: 'selected', agents };
+}

package/src/setup.ts

@@ -39,6 +39,13 @@ import { initDebugFromArgv } from './debug.js';
 import { defaultApprovalIo, setupApprovalWarnings } from './cli-tool-approval.js';
 import { offerFirstRunServerInstall } from './first-run-server.js';
 import { setupNextStepsText } from './cli-help.js';
+import {
+  emptySetupOutcome,
+  resolveSetupAgentSelection,
+  setupAgentChoices,
+  setupRestartInstruction,
+} from './setup-selection.js';
+import type { BorgCli } from './cubes.js';
 
 /**
  * Main setup wizard
@@ -69,18 +76,8 @@ async function main() {
     process.exit(1);
   }
 
-  // Resolve the separately published local server before setup writes agent
-  // configuration. Decline/non-interactive/failure paths therefore leave no
-  // partial setup state behind.
-  console.log(chalk.blue('◼ Local Server'));
-  const serverInstall = await offerFirstRunServerInstall(undefined, undefined, { initializeServer: true });
-  if (serverInstall.kind !== 'present' && serverInstall.kind !== 'installed') {
-    process.exit(serverInstall.kind === 'declined' ? 0 : 1);
-  }
-  console.log('');
-  console.log('◼ Local server initialized');
-
-  // Step 1: Configure every detected agent CLI
+  // Step 1: Choose which detected agent CLIs to configure. The choice is
+  // first-run/invocation-local; it is never persisted as an opt-out.
   console.log(chalk.blue('◼ Agent CLI Integration'));
 
   const yes = parseYesFlag(process.argv);
@@ -88,6 +85,12 @@ async function main() {
   const claudeDetected = claudeCliPath !== null;
   const codexDetected = codexCliPath !== null;
   const opencodeDetected = opencodeCliPath !== null;
+  const detectedClis: BorgCli[] = [
+    ...(claudeDetected ? ['claude' as const] : []),
+    ...(codexDetected ? ['codex' as const] : []),
+    ...(opencodeDetected ? ['opencode' as const] : []),
+  ];
+
   const claudeMcpConfigured = isMcpServerConfigured();
   const codexMcpConfigured = isCodexMcpServerConfigured();
   const opencodeMcpConfigured = isOpenCodeMcpServerConfigured();
@@ -95,14 +98,73 @@ async function main() {
   const claudeUpsHookPending = claudeDetected && !isUserPromptSubmitHookRegistered();
   const codexSessionHookPending = codexDetected && !isCodexSessionStartHookRegistered();
   const codexUpsHookPending = codexDetected && !isCodexUserPromptSubmitHookRegistered();
-  const claudeHookPending = claudeLegacyHookPending || claudeUpsHookPending;
-  const codexHookPending = codexSessionHookPending || codexUpsHookPending;
+  const alreadyConfigured = new Set<BorgCli>([
+    ...(claudeDetected && claudeMcpConfigured && !claudeLegacyHookPending && !claudeUpsHookPending
+      ? ['claude' as const]
+      : []),
+    ...(codexDetected && codexMcpConfigured && !codexSessionHookPending && !codexUpsHookPending
+      ? ['codex' as const]
+      : []),
+    ...(opencodeDetected && opencodeMcpConfigured ? ['opencode' as const] : []),
+  ]);
+
+  const allDetectedMutationPending = setupMutationPending({
+    claude: claudeDetected,
+    codex: codexDetected,
+    opencode: opencodeDetected,
+    claudeMcpConfigured,
+    codexMcpConfigured,
+    opencodeMcpConfigured,
+    claudeHookPending: claudeLegacyHookPending || claudeUpsHookPending,
+    codexHookPending: codexSessionHookPending || codexUpsHookPending,
+  });
+
+  let selectedClis = detectedClis;
+  if (allDetectedMutationPending && !yes && process.stdin.isTTY === true) {
+    let cancelled = false;
+    const answer = await prompts(
+      {
+        type: 'multiselect',
+        name: 'selected',
+        message: 'Which detected agent CLIs should Borg configure?',
+        hint: 'Space toggles selection; Enter accepts the checked agents',
+        choices: setupAgentChoices(detectedClis, alreadyConfigured),
+        instructions: false,
+      },
+      {
+        onCancel: () => {
+          cancelled = true;
+        },
+      },
+    );
+    const selection = resolveSetupAgentSelection(detectedClis, answer.selected, cancelled);
+    if (selection.kind === 'cancelled') {
+      console.log(chalk.yellow('\n◼ Setup cancelled — no changes made.\n'));
+      return;
+    }
+    if (selection.kind === 'empty') {
+      const outcome = emptySetupOutcome();
+      console.log(chalk.yellow(
+        `\n◼ No agent CLIs selected — agent configuration and local-server initialization were skipped. ` +
+        `Run \`${outcome.recovery.command}\` again to choose an agent and continue setup.\n`,
+      ));
+      return;
+    }
+    selectedClis = selection.agents;
+  }
+
+  const selected = new Set(selectedClis);
+  const claudeSelected = selected.has('claude');
+  const codexSelected = selected.has('codex');
+  const opencodeSelected = selected.has('opencode');
+  const claudeHookPending = claudeSelected && (claudeLegacyHookPending || claudeUpsHookPending);
+  const codexHookPending = codexSelected && (codexSessionHookPending || codexUpsHookPending);
 
   if (
     setupMutationPending({
-      claude: claudeDetected,
-      codex: codexDetected,
-      opencode: opencodeDetected,
+      claude: claudeSelected,
+      codex: codexSelected,
+      opencode: opencodeSelected,
       claudeMcpConfigured,
       codexMcpConfigured,
       opencodeMcpConfigured,
@@ -112,7 +174,7 @@ async function main() {
   ) {
     console.log(
       formatConfigMutationDisclosure(
-        configMutationTargets({ claude: claudeDetected, codex: codexDetected, opencode: opencodeDetected })
+        configMutationTargets({ claude: claudeSelected, codex: codexSelected, opencode: opencodeSelected })
       )
     );
     const mutationDecision = await confirmConfigMutation({
@@ -135,7 +197,19 @@ async function main() {
   }
   console.log('');
 
-  if (claudeCliPath) {
+  // Resolve the separately published local server only after the complete
+  // agent selection and the existing single config-mutation confirmation.
+  // Esc/zero-selection/decline therefore leave both agent and server setup
+  // untouched.
+  console.log(chalk.blue('◼ Local Server'));
+  const serverInstall = await offerFirstRunServerInstall(undefined, undefined, { initializeServer: true });
+  if (serverInstall.kind !== 'present' && serverInstall.kind !== 'installed') {
+    process.exit(serverInstall.kind === 'declined' ? 0 : 1);
+  }
+  console.log('');
+  console.log('◼ Local server initialized');
+
+  if (claudeSelected) {
     try {
       ensureCliMcpConfigured('claude');
       if (claudeLegacyHookPending) removeSessionStartHook();
@@ -146,7 +220,7 @@ async function main() {
       process.exit(1);
     }
   }
-  if (codexCliPath) {
+  if (codexSelected) {
     try {
       ensureCliMcpConfigured('codex');
       if (codexSessionHookPending) addCodexSessionStartHook();
@@ -157,7 +231,7 @@ async function main() {
       process.exit(1);
     }
   }
-  if (opencodeCliPath) {
+  if (opencodeSelected) {
     try {
       ensureCliMcpConfigured('opencode');
       console.log(chalk.green('◼ borg configured for OpenCode'));
@@ -172,8 +246,8 @@ async function main() {
     codexArgs: [],
   });
   for (const warning of await setupApprovalWarnings(approvalIo, {
-    codex: codexDetected,
-    opencode: opencodeDetected,
+    codex: codexSelected,
+    opencode: opencodeSelected,
   })) {
     console.log(chalk.yellow(`warning: ${warning}`));
   }
@@ -185,7 +259,7 @@ async function main() {
 
   // Success message
   console.log(chalk.green.bold('\nSetup complete!\n'));
-  console.log(chalk.yellow('🔄 Restart Claude Code / Codex / OpenCode (or open a new session) for the changes to take effect.\n'));
+  console.log(chalk.yellow(`${setupRestartInstruction(selectedClis)}\n`));
   if (!serverInstall.suppressClientNextSteps) {
     console.log(chalk.gray(setupNextStepsText()));
   }

package/src/stream-owner.ts

@@ -1,10 +1,10 @@
 import { randomUUID } from 'node:crypto';
 import { promises as fs } from 'node:fs';
-import { homedir } from 'node:os';
 import path from 'node:path';
+import { borgConfigRoot } from './private-root.js';
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const STREAM_LOCKS_DIR = path.join(homedir(), '.config', 'borgmcp', 'stream-locks');
+const STREAM_LOCKS_DIR = path.join(borgConfigRoot(), 'stream-locks');
 const OWNER_FILE = 'owner.json';
 const TAKEOVER_FILE = 'takeover.json';
 const SCHEMA_VERSION = 1;