borgmcp 4.6.1 → 4.7.0

package/src/claude.ts

@@ -18,6 +18,7 @@
 import { spawn } from 'child_process';
 import { randomUUID } from 'node:crypto';
 import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { basename } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { fileURLToPath } from 'node:url';
@@ -102,6 +103,7 @@ import {
   addCodexUserPromptSubmitHook,
   addProjectSessionStartHook,
   addUserPromptSubmitHook,
+  provisionLaunchAccess,
   removeSessionStartHook,
 } from './config-utils.js';
 import { ensureCliMcpConfigured } from './ensure-mcp-config.js';
@@ -118,6 +120,7 @@ import { buildOpenCodeLaunchArgs, defaultApprovalIo, resolveLaunchBorgApprovals
 import { isClientOwnedCubeInitArgv, runEarlyServerFacade } from './server-facade.js';
 import { runEarlyUpdate } from './update-cmd.js';
 import { runDoctor, warnIfAgentIntegrationUnhealthy } from './agent-integration-health.js';
+import { scratchRootForSeat } from './launch-access.js';
 
 export type AssimilateDepsBuilder = typeof buildDefaultAssimilateDeps;
 
@@ -148,7 +151,7 @@ export function createOpenCodeLaunchPlan(
   };
 }
 
-export function launchOpenCodeProcess(options: {
+export async function launchOpenCodeProcess(options: {
   cwd: string;
   port: number;
   prompt: string;
@@ -159,36 +162,76 @@ export function launchOpenCodeProcess(options: {
   kickoff: ReturnType<typeof createOpenCodeLaunchKickoff>;
   spawnProcess?: typeof spawn;
   connect?: typeof connectOpenCodeDrone;
-}): {
+  injectKickoff?: typeof injectInitialKickoff;
+  allocatePort?: typeof allocateOpenCodePort;
+}): Promise<{
   launchArgs: string[];
   launchEnv: NodeJS.ProcessEnv;
   process: ReturnType<typeof spawn>;
-} {
-  const plan = createOpenCodeLaunchPlan(options.cwd, options.port, options.prompt, options.passthroughArgs);
-  const launchEnv = {
-    ...options.env,
-    BORG_OPENCODE_PORT: plan.envPort,
-    [OPENCODE_SERVER_USERNAME_ENV]: OPENCODE_SERVER_USERNAME,
-    [OPENCODE_SERVER_PASSWORD_ENV]: options.kickoff.apiPassword,
-    [BORG_OPENCODE_LAUNCH_CORRELATION_ENV]: options.kickoff.correlationIdentity,
-  };
-  // OpenCode's bind can still race this allocation; client#298 tracks the
-  // residual pre-bind window outside this slice.
-  const child = (options.spawnProcess ?? spawn)('opencode', plan.launchArgs, {
-    stdio: 'inherit',
-    shell: false,
-    env: launchEnv,
-  });
-  (options.connect ?? connectOpenCodeDrone)({
-    serverUrl: plan.serverUrl,
-    apiPassword: options.kickoff.apiPassword,
-    directory: options.cwd,
-    droneLabel: options.droneLabel,
-    cubeName: options.cubeName,
-  })
-    .then(() => injectInitialKickoff(options.kickoff))
-    .catch(() => {});
-  return { launchArgs: plan.launchArgs, launchEnv, process: child };
+}> {
+  let port = options.port;
+  let lastExit: { code: number | null; signal: NodeJS.Signals | null } | null = null;
+  // Each child gets independent trust so a retry cannot bind a session or
+  // durable binding left by an earlier attempt.
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const attemptKickoff = attempt === 0
+      ? options.kickoff
+      : createOpenCodeLaunchKickoff(options.prompt);
+    const plan = createOpenCodeLaunchPlan(options.cwd, port, options.prompt, options.passthroughArgs);
+    const launchEnv = {
+      ...options.env,
+      BORG_OPENCODE_PORT: plan.envPort,
+      [OPENCODE_SERVER_USERNAME_ENV]: OPENCODE_SERVER_USERNAME,
+      [OPENCODE_SERVER_PASSWORD_ENV]: attemptKickoff.apiPassword,
+      [BORG_OPENCODE_LAUNCH_CORRELATION_ENV]: attemptKickoff.correlationIdentity,
+    };
+    const child = (options.spawnProcess ?? spawn)('opencode', plan.launchArgs, {
+      stdio: 'inherit',
+      shell: false,
+      env: launchEnv,
+    });
+    type Stopped =
+      | { kind: 'error'; error: NodeJS.ErrnoException }
+      | { kind: 'exit'; code: number | null; signal: NodeJS.Signals | null };
+    let markStopped: (outcome: Stopped) => void;
+    const stopped = new Promise<Stopped>((resolve) => { markStopped = resolve; });
+    const onError = (error: NodeJS.ErrnoException) => markStopped({ kind: 'error', error });
+    const onExit = (code: number | null, signal: NodeJS.Signals | null) => {
+      markStopped({ kind: 'exit', code, signal });
+    };
+    child.once('error', onError);
+    child.once('exit', onExit);
+    await (options.connect ?? connectOpenCodeDrone)({
+      serverUrl: plan.serverUrl,
+      apiPassword: attemptKickoff.apiPassword,
+      directory: options.cwd,
+      droneLabel: options.droneLabel,
+      cubeName: options.cubeName,
+      launchIdentity: attemptKickoff.correlationIdentity,
+    });
+    const outcome = await Promise.race([
+      (options.injectKickoff ?? injectInitialKickoff)(attemptKickoff).then(
+        (bound) => bound ? { kind: 'ready' as const } : { kind: 'unbound' as const },
+      ),
+      stopped,
+    ]);
+    child.off('error', onError);
+    child.off('exit', onExit);
+    if (outcome.kind === 'ready') {
+      return { launchArgs: plan.launchArgs, launchEnv, process: child };
+    }
+    if (outcome.kind === 'unbound') {
+      child.kill();
+      throw new Error('OpenCode started but its launch session could not be identified');
+    }
+    if (outcome.kind === 'error') throw outcome.error;
+    lastExit = outcome;
+    if (attempt < 2) port = await (options.allocatePort ?? allocateOpenCodePort)();
+  }
+  throw new Error(
+    `OpenCode exited before launch readiness after 3 attempts `
+    + `(code=${lastExit?.code ?? 'none'}, signal=${lastExit?.signal ?? 'none'})`,
+  );
 }
 
 export async function runAssimilateEntry(
@@ -510,7 +553,19 @@ async function main() {
   cli = configureSelectedLaunchCli(
     cli,
     launchAction,
-    (selectedCli) => ensureResolvedCliConfigured(selectedCli, active),
+    (selectedCli) => {
+      ensureResolvedCliConfigured(selectedCli, active);
+      if (selectedCli === 'opencode' && active) {
+        const worktree = findProjectRoot(process.cwd());
+        provisionLaunchAccess(selectedCli, worktree, {
+          worktree,
+          scratch: scratchRootForSeat(homedir(), active.droneLabel, active.droneId),
+          // OpenCode does not grant Git internals; this field is used only by
+          // the Codex launch-argument path.
+          commonDir: worktree,
+        });
+      }
+    },
   );
 
   if (active && !parsedCli.force) {
@@ -682,7 +737,7 @@ async function main() {
   console.error(`${consolePrefix()}${chalk.blue(`◼ Launching ${cliDisplayName}…`)}`);
 
   const agentProcess = cli === 'opencode' && openCodeKickoff && openCodePort !== undefined
-    ? launchOpenCodeProcess({
+    ? (await launchOpenCodeProcess({
         cwd: process.cwd(),
         port: openCodePort,
         prompt: openCodeKickoff.prompt,
@@ -691,7 +746,7 @@ async function main() {
         droneLabel: active?.droneLabel ?? 'opencode',
         cubeName: active?.name ?? 'borg',
         kickoff: openCodeKickoff,
-      }).process
+      })).process
     : spawn(cli, launchArgs, { stdio: 'inherit', shell: false, env: launchEnv });
 
   // gh#857 WI-2: wake-target recording is codex-only (app-server bridge).
@@ -807,6 +862,11 @@ if (isEntryInvocation()) {
       process.stderr.write(`${error.message}\n`);
       process.exit(1);
     }
+    if (error?.code === 'ENOENT' && error?.path === 'opencode') {
+      console.error(`${consolePrefix()}${chalk.red('\n◼ Failed to launch opencode')}`);
+      console.error(`${consolePrefix()}${chalk.gray('Make sure opencode is installed.\n')}`);
+      process.exit(1);
+    }
     console.error(`${consolePrefix()}${chalk.red(`\n◼ Error: ${error.message}\n`)}`);
     process.exit(1);
   });

package/src/cli-help.ts

@@ -172,6 +172,7 @@ export function topLevelHelpText(version: string): string {
     `  borg                     Show the launch menu in a repository root; resume directly in a linked worktree\n` +
     `  borg setup               Set up borg MCP server + agent CLI integration\n` +
     `  borg update              Update the client and installed local server together\n` +
+    `  borg upgrade             Alias for borg update\n` +
     `  borg doctor              Check agent hook commands, OpenCode integration, and startup diagnostics\n` +
     `  borg clone <url> [dir]   Clone a repository, then create and launch its cube\n` +
     `  borg quickstart          Create a cube and a drone for every role, then launch them\n` +

package/src/codex-launch.ts

@@ -1,5 +1,6 @@
 import type { BorgCli } from './cubes.js';
-import { wakePathArming, type AgentKind } from './regen-format.js';
+import type { AgentKind } from './agent-runtime.js';
+import { wakePathArming } from './regen-format.js';
 import { OPENCODE_WAKE_PATH_GUIDANCE } from './opencode-wake-copy.js';
 
 /**

package/src/config-utils.ts

@@ -5,6 +5,7 @@
  */
 
 import { execSync } from 'child_process';
+import { randomBytes } from 'node:crypto';
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
@@ -23,7 +24,7 @@ import {
 import { shellEscape } from './shell-escape.js';
 import { BORG_STATE_ROOT_ENV, borgAgentConfigEnv, borgHomeRoot } from './private-root.js';
 import type { LaunchAccessPaths } from './launch-access.js';
-import { BORG_LAUNCH_EXPECTED_SEAT_ENV } from './cubes.js';
+import { BORG_LAUNCH_EXPECTED_SEAT_ENV, type BorgCli } from './cubes.js';
 import {
   OPENCODE_SERVER_PASSWORD_ENV,
   OPENCODE_SERVER_PASSWORD_REFERENCE,
@@ -209,6 +210,132 @@ function writeJsonFile(p: string, data: any): void {
   fs.writeFileSync(p, JSON.stringify(data, null, 2) + '\n', 'utf-8');
 }
 
+interface OpenCodeProjectConfigSnapshot {
+  config: unknown;
+  identity: { dev: number; ino: number } | null;
+  mode: number;
+}
+
+function unsafeOpenCodeConfigPath(configPath: string, detail: string): Error {
+  return new Error(`OpenCode config path ${configPath} is unsafe: ${detail}`);
+}
+
+function assertOpenCodeProjectConfigDirectory(projectRoot: string, configPath: string): string {
+  const root = path.resolve(projectRoot);
+  let rootStat: fs.Stats;
+  try {
+    rootStat = fs.lstatSync(root);
+  } catch {
+    throw unsafeOpenCodeConfigPath(configPath, 'project root is missing or unreadable');
+  }
+  if (rootStat.isSymbolicLink() || !rootStat.isDirectory() || fs.realpathSync(root) !== root) {
+    throw unsafeOpenCodeConfigPath(configPath, 'project root must be a canonical real directory');
+  }
+
+  const configDir = path.join(root, '.opencode');
+  try {
+    fs.mkdirSync(configDir, { mode: 0o700 });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+  }
+  let directoryStat: fs.Stats;
+  try {
+    directoryStat = fs.lstatSync(configDir);
+  } catch {
+    throw unsafeOpenCodeConfigPath(configPath, '.opencode is missing or unreadable');
+  }
+  if (
+    directoryStat.isSymbolicLink()
+    || !directoryStat.isDirectory()
+    || fs.realpathSync(configDir) !== configDir
+  ) {
+    throw unsafeOpenCodeConfigPath(configPath, '.opencode must be a canonical real directory, not a symlink');
+  }
+  return configDir;
+}
+
+function inspectOpenCodeProjectConfigFile(configPath: string): fs.Stats | null {
+  let metadata: fs.Stats;
+  try {
+    metadata = fs.lstatSync(configPath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw error;
+  }
+  if (metadata.isSymbolicLink() || !metadata.isFile() || metadata.nlink !== 1) {
+    throw unsafeOpenCodeConfigPath(configPath, 'final path must be one regular file, not a symlink');
+  }
+  return metadata;
+}
+
+function readOpenCodeProjectConfig(projectRoot: string, configPath: string): OpenCodeProjectConfigSnapshot {
+  assertOpenCodeProjectConfigDirectory(projectRoot, configPath);
+  const metadata = inspectOpenCodeProjectConfigFile(configPath);
+  if (!metadata) return { config: {}, identity: null, mode: 0o600 };
+
+  let descriptor: number | null = null;
+  try {
+    descriptor = fs.openSync(configPath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    const opened = fs.fstatSync(descriptor);
+    if (!opened.isFile() || opened.nlink !== 1 || opened.dev !== metadata.dev || opened.ino !== metadata.ino) {
+      throw unsafeOpenCodeConfigPath(configPath, 'final file changed while opening');
+    }
+    const text = fs.readFileSync(descriptor, 'utf8');
+    return {
+      config: text.trim() ? JSON.parse(text) : {},
+      identity: { dev: opened.dev, ino: opened.ino },
+      mode: opened.mode & 0o777,
+    };
+  } finally {
+    if (descriptor !== null) fs.closeSync(descriptor);
+  }
+}
+
+function writeOpenCodeProjectConfig(
+  projectRoot: string,
+  configPath: string,
+  data: unknown,
+  snapshot: OpenCodeProjectConfigSnapshot,
+): void {
+  const configDir = assertOpenCodeProjectConfigDirectory(projectRoot, configPath);
+  const temporary = path.join(
+    configDir,
+    `.opencode.json.${process.pid}.${randomBytes(12).toString('hex')}.tmp`,
+  );
+  let descriptor: number | null = null;
+  try {
+    descriptor = fs.openSync(
+      temporary,
+      fs.constants.O_WRONLY
+        | fs.constants.O_CREAT
+        | fs.constants.O_EXCL
+        | (fs.constants.O_NOFOLLOW ?? 0),
+      snapshot.mode,
+    );
+    fs.writeFileSync(descriptor, JSON.stringify(data, null, 2) + '\n', 'utf8');
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = null;
+
+    assertOpenCodeProjectConfigDirectory(projectRoot, configPath);
+    const current = inspectOpenCodeProjectConfigFile(configPath);
+    const unchanged = snapshot.identity === null
+      ? current === null
+      : current !== null
+        && current.dev === snapshot.identity.dev
+        && current.ino === snapshot.identity.ino;
+    if (!unchanged) {
+      throw unsafeOpenCodeConfigPath(configPath, 'final file changed before replacement');
+    }
+    fs.renameSync(temporary, configPath);
+  } finally {
+    if (descriptor !== null) {
+      try { fs.closeSync(descriptor); } catch { /* Preserve the primary failure. */ }
+    }
+    try { fs.unlinkSync(temporary); } catch { /* Renamed or never created. */ }
+  }
+}
+
 /**
  * Register a Claude Code SessionStart hook that runs `borg-regen` at the
  * start of every session. Idempotent: re-running won't add duplicates.
@@ -1339,11 +1466,13 @@ export function addOpenCodeLaunchAccess(
   paths: LaunchAccessPaths,
 ): boolean {
   const configPath = path.join(projectRoot, '.opencode', 'opencode.json');
+  let snapshot: OpenCodeProjectConfigSnapshot;
   let config: any;
   try {
-    config = readJsonFile(configPath);
+    snapshot = readOpenCodeProjectConfig(projectRoot, configPath);
+    config = snapshot.config;
   } catch (err: any) {
-    throw new Error(`Could not parse ${configPath}: ${err.message}`);
+    throw new Error(`Could not safely read OpenCode config ${configPath}: ${err.message}`);
   }
   if (!config || typeof config !== 'object' || Array.isArray(config)) {
     throw new Error(`OpenCode config ${configPath} is not an object`);
@@ -1394,10 +1523,33 @@ export function addOpenCodeLaunchAccess(
   config.permission = permissionObject;
 
   const changed = JSON.stringify(config) !== before;
-  if (changed) writeJsonFile(configPath, config);
+  if (changed) {
+    try {
+      writeOpenCodeProjectConfig(projectRoot, configPath, config, snapshot);
+    } catch (err: any) {
+      throw new Error(`Could not safely update OpenCode config ${configPath}: ${err.message}`);
+    }
+  }
   return changed;
 }
 
+/** Provision the project-local path access required by the selected CLI. */
+export function provisionLaunchAccess(
+  cli: BorgCli,
+  projectRoot: string,
+  paths: LaunchAccessPaths,
+): void {
+  if (cli === 'claude') {
+    addClaudeLaunchAccess(projectRoot, paths);
+  } else if (cli === 'codex') {
+    // Codex receives path grants on its launch command. Its global hook reads
+    // the scoped launch environment and only supplies the reminder.
+    addCodexForeignPathReminderHook();
+  } else {
+    addOpenCodeLaunchAccess(projectRoot, paths);
+  }
+}
+
 /**
  * Add borg MCP server to OpenCode using `opencode mcp add` CLI.
  * Pins activation and agent-kind signals plus OpenCode config substitutions

package/src/config.ts

@@ -31,7 +31,8 @@ const SERVER_CREDENTIAL_RECORD_VERSION = 2 as const;
 const SERVER_PENDING_ENROLLMENT_RECORD_VERSION = 3 as const;
 const LEGACY_SERVER_PENDING_ENROLLMENT_RECORD_VERSION = 1 as const;
 const SERVER_ACCEPTED_ENROLLMENT_MARKER_VERSION = 1 as const;
-const SERVER_CUBE_RETRY_RECORD_VERSION = 2 as const;
+const SERVER_CUBE_RETRY_RECORD_VERSION = 3 as const;
+const LEGACY_SERVER_CUBE_RETRY_RECORD_VERSION = 2 as const;
 // The 0600 credential store (Queen rescope: replaces the OS keychain). A single
 // file holds every parent credential/enrollment record; a single flock
 // serializes every mutator + observer that must (SR-seven #4).
@@ -326,7 +327,7 @@ async function writeServerCredentialRecord(
   }
   if (backend.entries) {
     const accounts = await backend.entries();
-    const conflicts = Object.entries(accounts).filter(([account, value]) => {
+    const conflicts = Object.entries(accounts).filter(([, value]) => {
       try {
         const parsed = JSON.parse(value) as { version?: unknown; origin?: unknown };
         return parsed.version === SERVER_CREDENTIAL_RECORD_VERSION && parsed.origin === record.origin;
@@ -1106,39 +1107,74 @@ export async function getOrCreatePendingServerCubeCreation(
   return withCredentialStoreLock(async () => {
     const stored = await backend.get(account);
     if (stored) {
+      let record: Omit<Partial<PendingServerCubeCreationRecord>, 'template'> & {
+        version?: unknown;
+        state?: unknown;
+        template?: unknown;
+      };
       try {
-        const record = JSON.parse(stored) as Partial<PendingServerCubeCreationRecord> & {
-          version?: unknown;
-          state?: unknown;
+        const parsed: unknown = JSON.parse(stored);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('invalid record');
+        record = parsed as typeof record;
+      } catch {
+        throw new Error('pending Borg server cube creation does not match this repository');
+      }
+      const retryKey = typeof record.retryKey === 'string' && UUID_RE.test(record.retryKey)
+        ? record.retryKey
+        : null;
+      const sameOperation =
+        record.state === 'pending' &&
+        record.origin === input.origin &&
+        record.trustIdentity === input.trustIdentity &&
+        record.clientId === input.clientId &&
+        record.repositoryBinding === repositoryBinding &&
+        record.name === input.name &&
+        record.workingRepoName === input.workingRepoName &&
+        retryKey !== null;
+      if (sameOperation && record.version === SERVER_CUBE_RETRY_RECORD_VERSION && record.template === input.template) {
+        return {
+          origin: input.origin,
+          trustIdentity: input.trustIdentity,
+          clientId: input.clientId,
+          repositoryBinding,
+          retryKey,
+          name: input.name,
+          workingRepoName: input.workingRepoName,
+          repository: input.repository,
+          template: input.template,
         };
-        if (
-          record.version !== SERVER_CUBE_RETRY_RECORD_VERSION ||
-          record.state !== 'pending' ||
-          record.origin !== input.origin ||
-          record.trustIdentity !== input.trustIdentity ||
-          record.clientId !== input.clientId ||
-          record.repositoryBinding !== repositoryBinding ||
-          record.name !== input.name ||
-          record.workingRepoName !== input.workingRepoName ||
-          record.template !== input.template ||
-          typeof record.retryKey !== 'string' || !UUID_RE.test(record.retryKey)
-        ) {
-          throw new Error('mismatch');
+      }
+      if (sameOperation && record.version === LEGACY_SERVER_CUBE_RETRY_RECORD_VERSION) {
+        const preserveRetryKey = record.template === input.template;
+        if (!preserveRetryKey && record.template !== 'default') {
+          throw new Error('pending Borg server cube creation does not match this repository');
         }
-        return {
+        const replacement: PendingServerCubeCreationRecord = {
           origin: input.origin,
           trustIdentity: input.trustIdentity,
           clientId: input.clientId,
           repositoryBinding,
-          retryKey: record.retryKey,
+          retryKey: preserveRetryKey ? retryKey : randomUUID(),
           name: input.name,
           workingRepoName: input.workingRepoName,
           repository: input.repository,
           template: input.template,
         };
-      } catch {
-        throw new Error('pending Borg server cube creation does not match this repository');
+        await backend.set(account, JSON.stringify({
+          version: SERVER_CUBE_RETRY_RECORD_VERSION,
+          state: 'pending',
+          origin: replacement.origin,
+          trustIdentity: replacement.trustIdentity,
+          clientId: replacement.clientId,
+          repositoryBinding: replacement.repositoryBinding,
+          retryKey: replacement.retryKey,
+          name: replacement.name,
+          workingRepoName: replacement.workingRepoName,
+          template: replacement.template,
+        }));
+        return replacement;
       }
+      throw new Error('pending Borg server cube creation does not match this repository');
     }
     const record: PendingServerCubeCreationRecord = {
       origin: input.origin,

package/src/cubes.ts

@@ -498,16 +498,6 @@ export async function findRemainingActiveSeatForWorktree(worktree: string): Prom
   return record ? { apiUrl: record.origin, operation: record.operation } : null;
 }
 
-/**
- * Legacy binding-only writer. In the collapsed single-store model an ACTIVE seat is
- * created ONLY by the atomic mint→activate+bind path in seats.ts (driven by the
- * attach FINALIZE); there is no standalone binding write. Retained solely as a
- * fail-closed guard for incomplete session metadata.
- */
-export async function setActiveCube(_active: ActiveCubeInput): Promise<void> {
-  throw new Error('local Borg server session metadata is incomplete');
-}
-
 export function activeCubeWithFreshRegenIdentity(
   active: ActiveCube,
   result: {

package/src/gc-orphan-inboxes.ts

@@ -14,7 +14,7 @@
  * always err toward KEEPING.
  */
 import { spawnSync } from 'node:child_process';
-import { readFileSync, readdirSync, statSync, unlinkSync } from 'node:fs';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import {
   pidfilePathFor,