borgmcp 2.14.2 → 2.16.0

package/src/config-utils.ts

@@ -6,7 +6,6 @@
 
 import { execSync } from 'child_process';
 import fs from 'fs';
-import os from 'os';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
@@ -20,8 +19,11 @@ import {
   resolveRegenPath,
   resolveClearRewakePath,
   resolveLogAuditPath,
+  resolveForeignPathReminderPath,
 } from './self-path.js';
 import { shellEscape } from './shell-escape.js';
+import { BORG_STATE_ROOT_ENV, borgAgentConfigEnv, borgHomeRoot } from './private-root.js';
+import type { LaunchAccessPaths } from './launch-access.js';
 
 // Get __dirname equivalent in ESM
 const __filename = fileURLToPath(import.meta.url);
@@ -33,6 +35,7 @@ const __dirname = dirname(__filename);
 const HOOK_COMMAND = shellEscape(resolveRegenPath());
 const CLEAR_REWAKE_HOOK_COMMAND = shellEscape(resolveClearRewakePath());
 const AUDIT_HOOK_COMMAND = shellEscape(resolveLogAuditPath());
+const FOREIGN_PATH_REMINDER_HOOK_COMMAND = shellEscape(resolveForeignPathReminderPath());
 const MCP_BINARY = resolveMcpBinaryPath();
 
 /**
@@ -44,14 +47,15 @@ const MCP_BINARY = resolveMcpBinaryPath();
  * `~/Library/Application Support/Claude/claude_desktop_config.json`,
  * which is the Claude Desktop app's config (different product).
  */
-const CLAUDE_CONFIG_PATH = path.join(os.homedir(), '.claude.json');
-const CODEX_CONFIG_PATH = path.join(os.homedir(), '.codex', 'config.toml');
-const CODEX_HOOKS_PATH = path.join(os.homedir(), '.codex', 'hooks.json');
-const OPENCODE_CONFIG_PATH = path.join(os.homedir(), '.config', 'opencode', 'opencode.json');
+const CONFIG_HOME = borgHomeRoot();
+const CLAUDE_CONFIG_PATH = path.join(CONFIG_HOME, '.claude.json');
+const CODEX_CONFIG_PATH = path.join(CONFIG_HOME, '.codex', 'config.toml');
+const CODEX_HOOKS_PATH = path.join(CONFIG_HOME, '.codex', 'hooks.json');
+const OPENCODE_CONFIG_PATH = path.join(CONFIG_HOME, '.config', 'opencode', 'opencode.json');
 const MCP_SERVER_NAME = 'borg';
 
 function settingsPath(): string {
-  return path.join(os.homedir(), '.claude', 'settings.json');
+  return path.join(CONFIG_HOME, '.claude', 'settings.json');
 }
 
 function readSettings(): any {
@@ -106,6 +110,77 @@ export function addProjectSessionStartHook(projectRoot: string): boolean {
   return addSessionStartHookAt(projectSettingsPath(projectRoot), true);
 }
 
+/**
+ * Pre-authorize the exact worktree + scratch paths for a Claude seat and add
+ * the native PreToolUse reminder. The permission layer remains authoritative;
+ * the reminder is deliberately advisory and cannot veto a tool call.
+ */
+export function addClaudeLaunchAccess(
+  projectRoot: string,
+  paths: LaunchAccessPaths,
+): boolean {
+  const settingsFile = projectSettingsPath(projectRoot);
+  let settings: any;
+  try {
+    settings = readJsonFile(settingsFile);
+  } catch (err: any) {
+    throw new Error(`Could not parse ${settingsFile}: ${err.message}`);
+  }
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+    throw new Error(`Claude settings ${settingsFile} is not an object`);
+  }
+
+  if (!settings.permissions || typeof settings.permissions !== 'object' || Array.isArray(settings.permissions)) {
+    if (settings.permissions !== undefined) {
+      throw new Error(`Claude settings permissions in ${settingsFile} are not an object`);
+    }
+    settings.permissions = {};
+  }
+  const additionalDirectories = settings.permissions.additionalDirectories;
+  if (additionalDirectories !== undefined && !Array.isArray(additionalDirectories)) {
+    throw new Error(`Claude settings permissions.additionalDirectories in ${settingsFile} is not an array`);
+  }
+
+  const directories = [paths.worktree, paths.scratch].map((value) => path.resolve(value));
+  const existingDirectories: unknown[] = Array.isArray(additionalDirectories)
+    ? additionalDirectories
+    : [];
+  let changed = false;
+  for (const directory of directories) {
+    if (!existingDirectories.includes(directory)) {
+      existingDirectories.push(directory);
+      changed = true;
+    }
+  }
+  if (settings.permissions.additionalDirectories !== existingDirectories) {
+    settings.permissions.additionalDirectories = existingDirectories;
+    changed = true;
+  }
+
+  if (!settings.hooks || typeof settings.hooks !== 'object' || Array.isArray(settings.hooks)) {
+    if (settings.hooks !== undefined) {
+      throw new Error(`Claude settings hooks in ${settingsFile} are not an object`);
+    }
+    settings.hooks = {};
+  }
+  settings.hooks.PreToolUse ??= [];
+  if (!Array.isArray(settings.hooks.PreToolUse)) {
+    throw new Error(`Claude settings hooks.PreToolUse in ${settingsFile} is not an array`);
+  }
+  const entries = settings.hooks.PreToolUse;
+  changed = migrateAndDedupOwnedHooks(entries) || changed;
+  if (!hasCommandHook(entries, FOREIGN_PATH_REMINDER_HOOK_COMMAND)) {
+    entries.push({
+      matcher: '*',
+      hooks: [{ type: 'command', command: FOREIGN_PATH_REMINDER_HOOK_COMMAND }],
+    });
+    changed = true;
+  }
+
+  if (changed) writeJsonFile(settingsFile, settings);
+  return changed;
+}
+
 /** Peek variant of addProjectSessionStartHook — no mutation. */
 export function isProjectSessionStartHookRegistered(projectRoot: string): boolean {
   return sessionStartHookRegisteredAt(projectSettingsPath(projectRoot), true);
@@ -190,12 +265,14 @@ function ownedCanonical(command: string): string | null {
   if (stripped === BARE_BORG_REGEN) return HOOK_COMMAND;
   if (stripped === BARE_CLEAR_REWAKE) return CLEAR_REWAKE_HOOK_COMMAND;
   if (stripped === BARE_LOG_AUDIT) return AUDIT_HOOK_COMMAND;
+  if (stripped === BARE_FOREIGN_PATH_REMINDER) return FOREIGN_PATH_REMINDER_HOOK_COMMAND;
 
   // (b) Exact match of THIS installation's canonical command (raw or escaped)
   // — always owned, no marker check required
   if (command === HOOK_COMMAND || stripped === resolveRegenPath()) return HOOK_COMMAND;
   if (command === CLEAR_REWAKE_HOOK_COMMAND || stripped === resolveClearRewakePath()) return CLEAR_REWAKE_HOOK_COMMAND;
   if (command === AUDIT_HOOK_COMMAND || stripped === resolveLogAuditPath()) return AUDIT_HOOK_COMMAND;
+  if (command === FOREIGN_PATH_REMINDER_HOOK_COMMAND || stripped === resolveForeignPathReminderPath()) return FOREIGN_PATH_REMINDER_HOOK_COMMAND;
 
   // (c) Foreign-install heuristic: absolute path + owned basename + borg marker
   if (stripped.startsWith('/') && (stripped.includes('borgmcp') || stripped.includes('borg-mcp'))) {
@@ -203,6 +280,7 @@ function ownedCanonical(command: string): string | null {
     if (name === 'regen.js') return HOOK_COMMAND;
     if (name === 'clear-rewake.js') return CLEAR_REWAKE_HOOK_COMMAND;
     if (name === 'log-audit.js') return AUDIT_HOOK_COMMAND;
+    if (name === 'foreign-path-reminder.js') return FOREIGN_PATH_REMINDER_HOOK_COMMAND;
   }
 
   return null;
@@ -272,6 +350,7 @@ function isCanonicalCommand(entryCommand: string, canonical: string): boolean {
 const BARE_BORG_REGEN = 'borg-regen';
 const BARE_CLEAR_REWAKE = 'borg-clear-rewake';
 const BARE_LOG_AUDIT = 'borg-log-audit';
+const BARE_FOREIGN_PATH_REMINDER = 'borg-foreign-path-reminder';
 
 function hasCommandHook(entries: any[], command: string): boolean {
   return entries.some((entry: any) =>
@@ -282,7 +361,7 @@ function hasCommandHook(entries: any[], command: string): boolean {
       // maps to the SAME canonical as the target. This correctly distinguishes
       // regen from clear-rewake from audit — a clear-rewake hook does NOT
       // satisfy the dedup check for a regen target, and vice versa.
-      if (command === HOOK_COMMAND || command === CLEAR_REWAKE_HOOK_COMMAND || command === AUDIT_HOOK_COMMAND) {
+      if (command === HOOK_COMMAND || command === CLEAR_REWAKE_HOOK_COMMAND || command === AUDIT_HOOK_COMMAND || command === FOREIGN_PATH_REMINDER_HOOK_COMMAND) {
         return ownedCanonical(h.command) === command;
       }
       return h.command === command;
@@ -616,9 +695,10 @@ export function getBinaryPath(): string {
  */
 export function addMcpServer(): void {
   try {
+    const agentConfigEnv = borgAgentConfigEnv(process.env);
     // First, remove any existing borg configuration (ignore errors if not found)
     try {
-      execSync('claude mcp remove --scope user borg', { stdio: 'ignore' });
+      execSync('claude mcp remove --scope user borg', { stdio: 'ignore', env: agentConfigEnv });
     } catch {
       // Ignore - server might not exist yet
     }
@@ -631,7 +711,7 @@ export function addMcpServer(): void {
       stdio: 'inherit', // Show output to user
       // No hosted-URL injection: BORG_API_URL passes through from the
       // environment only when the operator has explicitly set it.
-      env: process.env,
+      env: agentConfigEnv,
     });
   } catch (error: any) {
     if (error.message?.includes('command not found')) {
@@ -643,8 +723,9 @@ export function addMcpServer(): void {
 
 export function addCodexMcpServer(): void {
   try {
+    const codexConfigEnv = withAgentRuntimeEnv(borgAgentConfigEnv(process.env), 'codex');
     try {
-      execSync('codex mcp remove borg', { stdio: 'ignore' });
+      execSync('codex mcp remove borg', { stdio: 'ignore', env: codexConfigEnv });
     } catch {
       // Ignore - server might not exist yet.
     }
@@ -656,10 +737,14 @@ export function addCodexMcpServer(): void {
     // transport capability. Do not persist a transport marker here: a future
     // Codex child may launch without a live --remote socket.
     // gh#client#18: use absolute path to THIS installation's binary.
-    const codexConfigEnv = withAgentRuntimeEnv(process.env, 'codex');
     const apiUrlEnvArg = apiUrl ? ` --env BORG_API_URL=${shellQuote(apiUrl)}` : '';
+    const stateRoot = process.env[BORG_STATE_ROOT_ENV];
+    const stateRootEnvArg = stateRoot
+      ? ` --env ${BORG_STATE_ROOT_ENV}=${shellQuote(stateRoot)}`
+      : '';
     execSync('codex mcp add borg' +
       apiUrlEnvArg +
+      stateRootEnvArg +
       ` --env ${BORG_AGENT_KIND_ENV}=codex` +
       ` -- ${shellQuote(MCP_BINARY)}`, {
       stdio: 'inherit',
@@ -677,12 +762,17 @@ function shellQuote(value: string): string {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
-function addCodexHook(eventName: 'SessionStart' | 'UserPromptSubmit', command: string, options: { matcher?: string; timeout?: number } = {}): boolean {
+function addCodexHook(
+  eventName: 'SessionStart' | 'UserPromptSubmit' | 'PreToolUse',
+  command: string,
+  options: { matcher?: string; timeout?: number } = {},
+  hooksPath: string = CODEX_HOOKS_PATH,
+): boolean {
   let hooksFile: any;
   try {
-    hooksFile = readJsonFile(CODEX_HOOKS_PATH);
+    hooksFile = readJsonFile(hooksPath);
   } catch (err: any) {
-    console.error(`⚠ Could not parse ${CODEX_HOOKS_PATH}: ${err.message}. Skipping Codex hook registration.`);
+    console.error(`⚠ Could not parse ${hooksPath}: ${err.message}. Skipping Codex hook registration.`);
     return false;
   }
 
@@ -705,7 +795,7 @@ function addCodexHook(eventName: 'SessionStart' | 'UserPromptSubmit', command: s
     entries.push(entry);
     changed = true;
   }
-  if (changed) writeJsonFile(CODEX_HOOKS_PATH, hooksFile);
+  if (changed) writeJsonFile(hooksPath, hooksFile);
   return changed;
 }
 
@@ -717,8 +807,13 @@ export function addCodexUserPromptSubmitHook(): boolean {
   return addCodexHook('UserPromptSubmit', AUDIT_HOOK_COMMAND, { timeout: 10 });
 }
 
+/** Register the advisory foreign-path reminder on Codex's native hook surface. */
+export function addCodexForeignPathReminderHook(hooksPath: string = CODEX_HOOKS_PATH): boolean {
+  return addCodexHook('PreToolUse', FOREIGN_PATH_REMINDER_HOOK_COMMAND, {}, hooksPath);
+}
+
 export function isCodexHookRegistered(
-  eventName: 'SessionStart' | 'UserPromptSubmit' | 'Stop',
+  eventName: 'SessionStart' | 'UserPromptSubmit' | 'PreToolUse' | 'Stop',
   command: string,
   hooksPath: string = CODEX_HOOKS_PATH
 ): boolean {
@@ -783,6 +878,75 @@ export function isOpenCodeMcpServerConfigured(
   }
 }
 
+/**
+ * Pre-authorize the exact worktree + scratch paths in the launch-root
+ * OpenCode config. This intentionally writes only the project-local
+ * `.opencode/opencode.json`; the user-global config is shared by every seat.
+ */
+export function addOpenCodeLaunchAccess(
+  projectRoot: string,
+  paths: LaunchAccessPaths,
+): boolean {
+  const configPath = path.join(projectRoot, '.opencode', 'opencode.json');
+  let config: any;
+  try {
+    config = readJsonFile(configPath);
+  } catch (err: any) {
+    throw new Error(`Could not parse ${configPath}: ${err.message}`);
+  }
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error(`OpenCode config ${configPath} is not an object`);
+  }
+
+  const before = JSON.stringify(config);
+  const permission = config.permission;
+  let permissionObject: Record<string, unknown>;
+  if (permission === undefined) {
+    permissionObject = {};
+  } else if (permission === 'allow' || permission === 'ask' || permission === 'deny') {
+    permissionObject = { '*': permission };
+  } else if (permission && typeof permission === 'object' && !Array.isArray(permission)) {
+    permissionObject = { ...(permission as Record<string, unknown>) };
+  } else {
+    throw new Error(`OpenCode permission in ${configPath} has an unsupported shape`);
+  }
+
+  const existingExternal = permissionObject.external_directory;
+  let external: Record<string, unknown>;
+  if (existingExternal === undefined) {
+    external = {};
+  } else if (existingExternal === 'allow' || existingExternal === 'ask' || existingExternal === 'deny') {
+    external = { '*': existingExternal };
+  } else if (existingExternal && typeof existingExternal === 'object' && !Array.isArray(existingExternal)) {
+    external = { ...(existingExternal as Record<string, unknown>) };
+  } else {
+    throw new Error(`OpenCode permission.external_directory in ${configPath} has an unsupported shape`);
+  }
+
+  for (const directory of [paths.worktree, paths.scratch].map((value) => path.resolve(value))) {
+    // OpenCode matches external_directory patterns against the requested path,
+    // so a literal directory key does not authorize files below that directory.
+    // The exact `allow` shape is the literal form written by the predecessor;
+    // migrate only that owned key. Never replace an existing subtree decision
+    // or exact decision supplied by the operator.
+    const subtree = `${directory}/**`;
+    const hasExact = Object.prototype.hasOwnProperty.call(external, directory);
+    const hasSubtree = Object.prototype.hasOwnProperty.call(external, subtree);
+    if (external[directory] === 'allow') {
+      delete external[directory];
+      if (!hasSubtree) external[subtree] = 'allow';
+    } else if (!hasExact && !hasSubtree) {
+      external[subtree] = 'allow';
+    }
+  }
+  permissionObject.external_directory = external;
+  config.permission = permissionObject;
+
+  const changed = JSON.stringify(config) !== before;
+  if (changed) writeJsonFile(configPath, config);
+  return changed;
+}
+
 /**
  * Add borg MCP server to OpenCode using `opencode mcp add` CLI.
  * Pins BORG_SESSION=1, BORG_AGENT_KIND=opencode, the legacy BORG_OPENCODE=1,
@@ -797,10 +961,14 @@ export function addOpenCodeMcpServer(): void {
     // No hosted-URL fallback: only forward BORG_API_URL when explicitly set.
     const apiUrl = process.env.BORG_API_URL;
     const apiUrlEnvArg = apiUrl ? ` --env BORG_API_URL=${shellQuote(apiUrl)}` : '';
+    const stateRoot = process.env[BORG_STATE_ROOT_ENV];
+    const stateRootEnvArg = stateRoot
+      ? ` --env ${BORG_STATE_ROOT_ENV}=${shellQuote(stateRoot)}`
+      : '';
     // gh#client#18: use absolute path to THIS installation's binary.
     execSync(
-      `opencode mcp add borg --env BORG_SESSION=1 --env BORG_AGENT_KIND=opencode --env BORG_OPENCODE=1${apiUrlEnvArg} -- ${shellQuote(MCP_BINARY)}`,
-      { stdio: 'inherit' }
+      `opencode mcp add borg --env BORG_SESSION=1 --env BORG_AGENT_KIND=opencode --env BORG_OPENCODE=1${apiUrlEnvArg}${stateRootEnvArg} -- ${shellQuote(MCP_BINARY)}`,
+      { stdio: 'inherit', env: borgAgentConfigEnv(process.env) }
     );
   } catch (error: any) {
     if (error.message?.includes('command not found')) {

package/src/credential-paths.ts

@@ -1,8 +1,7 @@
-import { realpathSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { borgHomeRoot } from './private-root.js';
 
-const canonicalHome = realpathSync(homedir());
+const canonicalHome = borgHomeRoot();
 
 export const BORG_USER_ROOT = join(canonicalHome, '.borg');
 export const SERVER_CREDENTIALS_FILE = join(BORG_USER_ROOT, 'credentials');

package/src/cubes.ts

@@ -17,9 +17,9 @@
 
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { pruneDeadWakeTargets } from './codex-wake-resolve.js';
+import { borgConfigRoot } from './private-root.js';
 import {
   getActiveSeatCredential,
   getActiveSeatForWorktree,
@@ -44,7 +44,7 @@ import {
 /** Re-exported from seats.ts for call-site parity (the retired cross-store name). */
 export type { SeatExpectation as ExpectedBinding } from './seats.js';
 
-const CUBES_DIR = join(homedir(), '.config', 'borgmcp');
+const CUBES_DIR = borgConfigRoot();
 const LAUNCH_FILE = join(CUBES_DIR, 'launch.json');
 const CODEX_WAKE_TARGETS_FILE = join(CUBES_DIR, 'codex-wake-targets.json');
 const INBOX_DIR = join(CUBES_DIR, 'inboxes');
@@ -611,9 +611,14 @@ export async function readAllProjectIdentities(): Promise<
   );
 }
 
-export async function setProjectCliPreference(cli: BorgCli): Promise<void> {
+/**
+ * Save the CLI preference for the current project, or for an explicitly named
+ * worktree. The explicit path is used when assimilate has just created a
+ * sibling worktree but the process still began in the invoking checkout.
+ */
+export async function setProjectCliPreference(cli: BorgCli, dir?: string): Promise<void> {
   const existing = (await readLaunchFile()) ?? { projects: {} };
-  existing.projects[findProjectRoot()] = { cli };
+  existing.projects[findProjectRoot(dir)] = { cli };
   await writeLaunchFile(existing);
 }
 

package/src/foreign-path-reminder.ts

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+/**
+ * Non-blocking pre-tool reminder for a Borg-launched seat.
+ *
+ * Claude Code and Codex pass a JSON hook payload on stdin. The hook only
+ * emits a reminder when the payload names a working directory or target path
+ * outside the two paths Borg granted to this seat. It never returns a deny
+ * decision and exits successfully for malformed, missing, or unconfigured
+ * input so the harness permission layer remains the enforcement point.
+ */
+
+import { isAbsolute, relative, resolve } from 'node:path';
+import {
+  BORG_LAUNCH_CLI_ENV,
+  BORG_LAUNCH_SCRATCH_ENV,
+  BORG_LAUNCH_WORKTREE_ENV,
+} from './launch-access.js';
+
+const REMINDER = 'Reminder: this seat is scoped to its own worktree and scratch root; coordinate before working on a foreign path.';
+
+const PATH_KEYS = new Set([
+  'cwd',
+  'workdir',
+  'working_directory',
+  'directory',
+  'dir',
+  'path',
+  'file_path',
+  'target_path',
+  'source_path',
+  'destination_path',
+  'old_path',
+  'new_path',
+]);
+
+const COMMAND_KEYS = new Set(['command', 'cmd', 'shell_command']);
+
+interface HookPayload {
+  cwd?: unknown;
+  tool_input?: unknown;
+  input?: unknown;
+  [key: string]: unknown;
+}
+
+function readStdin(): Promise<string> {
+  if (process.stdin.isTTY) return Promise.resolve('');
+  return new Promise((resolveInput) => {
+    const chunks: Buffer[] = [];
+    process.stdin.on('data', (chunk: Buffer | string) => chunks.push(Buffer.from(chunk)));
+    process.stdin.on('end', () => resolveInput(Buffer.concat(chunks).toString('utf8')));
+    process.stdin.on('error', () => resolveInput(''));
+  });
+}
+
+function configuredRoots(): string[] {
+  return [process.env[BORG_LAUNCH_WORKTREE_ENV], process.env[BORG_LAUNCH_SCRATCH_ENV]]
+    .filter((root): root is string => typeof root === 'string' && isAbsolute(root))
+    .map((root) => resolve(root));
+}
+
+function isInsideAnyRoot(candidate: string, roots: string[]): boolean {
+  const absolute = resolve(candidate);
+  return roots.some((root) => {
+    const suffix = relative(root, absolute);
+    return suffix === '' || (!suffix.startsWith('..') && !isAbsolute(suffix));
+  });
+}
+
+function pathFromValue(value: string, baseCwd: string): string {
+  return isAbsolute(value) ? resolve(value) : resolve(baseCwd, value);
+}
+
+function absolutePathsInCommand(command: string): string[] {
+  const paths: string[] = [];
+  const pattern = /(?:^|[\s"'=])((?:\/|[A-Za-z]:[\\/])[^\s"'`;&|<>]*)/g;
+  for (const match of command.matchAll(pattern)) {
+    const value = match[1]?.replace(/[),.]+$/, '');
+    if (value) paths.push(value);
+  }
+  return paths;
+}
+
+function containsForeignTarget(value: unknown, key: string, baseCwd: string, roots: string[]): boolean {
+  if (typeof value === 'string') {
+    if (PATH_KEYS.has(key)) return !isInsideAnyRoot(pathFromValue(value, baseCwd), roots);
+    if (COMMAND_KEYS.has(key)) {
+      return absolutePathsInCommand(value).some((path) => !isInsideAnyRoot(path, roots));
+    }
+    return false;
+  }
+  if (Array.isArray(value)) {
+    return value.some((item) => containsForeignTarget(item, key, baseCwd, roots));
+  }
+  if (!value || typeof value !== 'object') return false;
+  return Object.entries(value as Record<string, unknown>).some(([childKey, childValue]) =>
+    containsForeignTarget(childValue, childKey, baseCwd, roots)
+  );
+}
+
+function shouldRemind(payload: HookPayload, roots: string[]): boolean {
+  const baseCwd = typeof payload.cwd === 'string' && payload.cwd.length > 0
+    ? resolve(payload.cwd)
+    : roots[0];
+  if (!isInsideAnyRoot(baseCwd, roots)) return true;
+  return containsForeignTarget(payload.tool_input ?? payload.input ?? payload, 'input', baseCwd, roots);
+}
+
+async function main(): Promise<void> {
+  const roots = configuredRoots();
+  if (roots.length === 0) return;
+
+  const raw = await readStdin();
+  if (!raw.trim()) return;
+  let payload: HookPayload;
+  try {
+    payload = JSON.parse(raw) as HookPayload;
+  } catch {
+    return;
+  }
+  if (!shouldRemind(payload, roots)) return;
+
+  // Claude Code consumes both fields: systemMessage displays the advisory and
+  // hookSpecificOutput.additionalContext delivers it to the model. Codex's
+  // PreToolUse parser accepts systemMessage but rejects the Claude-only nested
+  // additionalContext field, so keep that branch deliberately narrower.
+  const output = process.env[BORG_LAUNCH_CLI_ENV] === 'codex'
+    ? { systemMessage: REMINDER }
+    : {
+      systemMessage: REMINDER,
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        additionalContext: REMINDER,
+      },
+    };
+  process.stdout.write(`${JSON.stringify(output)}\n`);
+}
+
+main().catch(() => {
+  // A reminder hook is advisory only and must never block a tool call.
+});

package/src/launch-access.ts

@@ -0,0 +1,40 @@
+import { createHash } from 'node:crypto';
+import { join, resolve } from 'node:path';
+import { validateName } from './name-validator.js';
+
+/** Environment names consumed by the optional foreign-path reminder hooks. */
+export const BORG_LAUNCH_WORKTREE_ENV = 'BORG_LAUNCH_WORKTREE';
+export const BORG_LAUNCH_SCRATCH_ENV = 'BORG_LAUNCH_SCRATCH';
+export const BORG_LAUNCH_CLI_ENV = 'BORG_LAUNCH_CLI';
+
+export interface LaunchAccessPaths {
+  /** The repository root whose subtree is granted to the launched harness. */
+  worktree: string;
+  /** The disposable scratch root reserved for this seat. */
+  scratch: string;
+}
+
+/**
+ * Resolve the canonical per-seat scratch root.
+ *
+ * Drone labels are server-derived path components in the normal flow. Keep a
+ * defensive fallback for malformed labels anyway: a server value must never
+ * be allowed to escape the scratch parent, and the drone id gives a stable
+ * collision-resistant directory name when the label is unusable.
+ */
+export function scratchRootForSeat(
+  homeDir: string,
+  droneLabel: string,
+  droneId: string,
+): string {
+  const label = validateName(droneLabel).ok
+    ? droneLabel
+    : `seat-${createHash('sha256').update(`${droneLabel}\0${droneId}`).digest('hex').slice(0, 24)}`;
+  return join(resolve(homeDir), '.borg', 'scratch', label);
+}
+
+/** Build Codex's native launch-time additional-directory flags. */
+export function codexLaunchDirectoryArgs(paths: LaunchAccessPaths): string[] {
+  const directories = [...new Set([paths.worktree, paths.scratch].map((path) => resolve(path)))];
+  return directories.flatMap((directory) => ['--add-dir', directory]);
+}

package/src/launch-all-deps.ts

@@ -15,7 +15,6 @@ import {
   statSync,
   readdirSync,
 } from 'node:fs';
-import { homedir as osHomedir } from 'node:os';
 import { createInterface } from 'node:readline/promises';
 import type { ActiveCube } from './cubes.js';
 import {
@@ -26,6 +25,7 @@ import {
 } from './cubes.js';
 import { getRoster, getCube } from './remote-client.js';
 import { defaultProbeSeat, type SeatStatus } from './seat-probe.js';
+import { borgHomeRoot } from './private-root.js';
 
 /** Subprocess runner — sync, returns stdout, THROWS on non-zero exit or ENOENT. */
 export type RunSyncFn = (cmd: string, args: string[]) => string;
@@ -122,7 +122,7 @@ export function buildDefaultLaunchAllDeps(): LaunchAllDeps {
     },
     cwd: () => process.cwd(),
     pathExists: (p) => existsSync(p),
-    homedir: () => osHomedir(),
+    homedir: () => borgHomeRoot(),
     mkdirp: (dir) => {
       mkdirSync(dir, { recursive: true });
     },

package/src/lifecycle-log-guard.ts

@@ -1,8 +1,8 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { borgConfigRoot } from './private-root.js';
 
-const STATE_FILE = join(homedir(), '.config', 'borgmcp', 'lifecycle-log-state.json');
+const STATE_FILE = join(borgConfigRoot(), 'lifecycle-log-state.json');
 const ARRIVAL_DUPLICATE_WINDOW_MS = 10 * 60 * 1000;
 
 export type LifecycleSignal = 'arrival' | 'ready';

package/src/local-server-cursor.ts

@@ -1,9 +1,9 @@
 import { createHash } from 'node:crypto';
 import { mkdir, open, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { borgConfigRoot } from './private-root.js';
 
-const CURSOR_FILE = join(homedir(), '.config', 'borgmcp', 'local-server-cursors.json');
+const CURSOR_FILE = join(borgConfigRoot(), 'local-server-cursors.json');
 const CURSOR_LOCK = `${CURSOR_FILE}.lock`;
 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/opencode-plugin.ts

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
+import { borgHomeRoot } from './private-root.js';
 
 /**
  * Plugin source that preserves borg cube context across session compaction.
@@ -24,7 +24,7 @@ export default function () {
 const PLUGIN_REL_PATH = path.join('.config', 'opencode', 'plugins', 'borg-orient.js');
 
 export function installBorgPlugin(): void {
-  const pluginPath = path.join(os.homedir(), PLUGIN_REL_PATH);
+  const pluginPath = path.join(borgHomeRoot(), PLUGIN_REL_PATH);
   try {
     if (fs.existsSync(pluginPath)) {
       const existing = fs.readFileSync(pluginPath, 'utf-8');

package/src/parse-assimilate-args.ts

@@ -115,7 +115,13 @@ export function parseAssimilateArgs(rawArgs: string[]): ParseResult {
         if (enrollmentRequested) {
           return { ok: false, error: ENROLLMENT_POSITIONAL_INPUT_ERROR };
         }
-        return { ok: false, error: `unexpected extra argument: ${arg} (already have role "${role}")` };
+        return {
+          ok: false,
+          error:
+            `unexpected extra argument: ${arg} (already have role "${role}"). ` +
+            'Multi-word role names must be quoted (for example, `borg assimilate "Code Reviewer"`) ' +
+            'or written with hyphens.',
+        };
       }
       if (enrollmentRequested && !validateName(arg).ok) {
         return { ok: false, error: ENROLLMENT_POSITIONAL_INPUT_ERROR };