borgmcp 2.14.2 → 2.15.0

package/docs/RELEASING.md

@@ -216,7 +216,7 @@ Never move, replace, reuse, or rerun that tag or workflow. The annotated `v2.14.
 successfully published that exact source as `borgmcp@2.14.1`; the same-run artifact report records integrity
 `sha512-VqkOp3jo/KnzgusCk98TFj/U8U7Q/gt8agvIbjiSWrV0lIHnsD+A+7w3C+GMQeyA08KXxRuZDF3No9sDomqMTQ==`.
 Never move, replace, reuse, or rerun that tag or workflow. The next candidate
-uses the unused `v2.14.2` identity from a fresh reviewed protected-main commit
+uses the unused `v2.15.0` identity from a fresh reviewed protected-main commit
 and requires the complete release gate again.
 
 ## Release Prerequisites
@@ -340,6 +340,128 @@ Before preparing a candidate, independently verify:
 
 ## Release Workflow
 
+### Clean-environment rig lifecycle
+
+Every clean-environment verification rig has an explicit identity and an
+explicit end-of-life. Keep filesystem workspaces under the seat's disposable
+`~/.borg/scratch/<seat>/` root, and give each workspace a name beginning with
+`borg-rig-` followed by the seat, purpose, and a unique suffix. Before the
+first command that can create files, anchor the rig as its own npm project:
+
+```sh
+BORG_SEAT_LABEL="${BORG_SEAT_LABEL:?set the seat label}"
+BORG_SCRATCH_ROOT="${BORG_SCRATCH_ROOT:-$HOME/.borg/scratch/$BORG_SEAT_LABEL}"
+RIG_NONCE="${RIG_NONCE:-$(date +%Y%m%d%H%M%S)-$$}"
+RIG_ID="borg-rig-${BORG_SEAT_LABEL}-release-${RIG_NONCE}"
+RIG_ROOT="$BORG_SCRATCH_ROOT/$RIG_ID"
+mkdir -p "$RIG_ROOT"
+printf '%s\n' '{"private":true}' > "$RIG_ROOT/package.json"
+```
+
+The manifest anchor is required before any `npm install`, `npm update`, or
+other npm command. Without it, npm can walk up from an empty scratch directory
+and write the operator's `package.json` instead of creating project-local
+state. The committed `release:exercise` follows this rule for its temporary
+consumer; other QA scripts and manual rigs must do the same.
+
+The system temporary root is shared with the whole machine, so an unbounded
+listing there is not an inspectable cleanup check. Bound that leg by the
+invoking user and the run-window markers, which select directories whose
+timestamps fall within this run window without requiring a prefix inventory.
+New `mkdtemp` prefixes therefore require no documentation change. Keep both
+time predicates and the ownership predicate: removing the run-window bound
+turns a populated shared temp root back into an uninspectable listing.
+
+On a machine where several runs share one user account, this listing can
+include another run's live workspace. Removal is scoped to paths created by
+this run; anything else in the output is reported, not deleted. Unrelated
+same-user temporary directories created during the window can therefore
+appear in the result, so never remove a path merely because this listing found
+it.
+
+```sh
+TEMP_ROOT="${TMPDIR:-/tmp}"
+TEMP_OWNER="$(id -un)"
+TEMP_SCAN_START="$TEMP_ROOT/.${RIG_ID}-temp-scan-start"
+TEMP_SCAN_END="$TEMP_ROOT/.${RIG_ID}-temp-scan-end"
+
+list_recent_owned_temp_rigs() {
+  find "$TEMP_ROOT" -mindepth 1 -prune \
+    -type d \
+    -user "$TEMP_OWNER" \
+    -newer "$TEMP_SCAN_START" \
+    ! -newer "$TEMP_SCAN_END" \
+    -print
+}
+
+touch "$TEMP_SCAN_START"
+```
+
+Container-backed rigs use the same `RIG_ID` as the container name and carry
+both labels below. `--rm` is preferred; a runtime without automatic removal
+must remove the exact `RIG_ID` in its cleanup path and retain the labels for a
+bounded sweep:
+
+```sh
+RIG_IMAGE="${RIG_IMAGE:?set the rig image}"
+docker run --rm \
+  --name "$RIG_ID" \
+  --label borg-rig=1 \
+  --label "borg-rig-owner=$BORG_SEAT_LABEL" \
+  "$RIG_IMAGE"
+```
+
+Register the exact-target cleanup before launching the rig:
+
+```sh
+cleanup_done=0
+cleanup() {
+  [ "$cleanup_done" -eq 0 ] || return
+  cleanup_done=1
+  trap - EXIT HUP INT TERM
+  docker container rm --force "$RIG_ID" >/dev/null 2>&1 || true
+  rm -rf -- "$RIG_ROOT"
+  if [ -e "$TEMP_SCAN_START" ]; then
+    touch "$TEMP_SCAN_END"
+    list_recent_owned_temp_rigs
+  fi
+  rm -f -- "$TEMP_SCAN_START" "$TEMP_SCAN_END"
+}
+trap cleanup EXIT
+trap 'exit 129' HUP
+trap 'exit 130' INT
+trap 'exit 143' TERM
+```
+
+List before starting and after cleanup. The filters distinguish this seat's
+rigs from unrelated containers on a shared host:
+
+```sh
+docker container ls --all \
+  --filter label=borg-rig=1 \
+  --filter "label=borg-rig-owner=${BORG_SEAT_LABEL:?}" \
+  --format '{{.ID}}\t{{.Names}}\t{{.Status}}'
+find "$BORG_SCRATCH_ROOT" -mindepth 1 -print
+find "$BORG_SCRATCH_ROOT" -name 'borg-rig-*' -print
+```
+
+The unfiltered filesystem listings expose legacy names as well as conforming
+rigs. The bounded temporary-directory function covers tools that use `mkdtemp`
+instead of the seat scratch root. Run the container and scratch listings before
+launch and again from the cleanup path; the temporary-directory function runs
+after cleanup, between the start and end markers. Inspect its results and do
+not remove unrelated temporary files.
+
+Register cleanup before launching any process, run it on success and failure,
+and do not deliver a verdict until the container listing, both scratch listings,
+and the bounded temporary-directory listing show no rig owned by the seat from
+this run. For a non-`--rm` container runtime,
+remove only the named rig or the same owner label; never prune unrelated
+containers. A completed verification
+therefore implies zero running or stopped rig containers and no rig workspace
+created by this run left in either the seat scratch root or the system temporary
+directory.
+
 ### Pre-tag composed exercise
 
 Before creating a release tag, exercise the packed client against the selected

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp",
-  "version": "2.14.2",
+  "version": "2.15.0",
   "description": "Coordinate AI coding agents in shared cubes. Works with Claude Code, Codex, and OpenCode.",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,6 +19,7 @@
     "borg-regen": "./dist/regen.js",
     "borg-clear-rewake": "./dist/clear-rewake.js",
     "borg-log-audit": "./dist/log-audit.js",
+    "borg-foreign-path-reminder": "./dist/foreign-path-reminder.js",
     "borg-inbox-monitor": "./dist/inbox-monitor.js"
   },
   "scripts": {

package/src/agent-runtime.ts

@@ -5,6 +5,8 @@
  * agent_kind without re-assimilating.
  */
 
+import { BORG_STATE_ROOT_ENV } from './private-root.js';
+
 export type AgentKind = 'claude' | 'codex' | 'opencode';
 
 /** Pinned into MCP-child environments by Borg launch paths. */
@@ -74,3 +76,18 @@ export function codexRemoteWakeConfigArgs(enabled: boolean = true): string[] {
     `mcp_servers.borg.env.${BORG_CODEX_REMOTE_WAKE_ENV}="${enabled ? '1' : '0'}"`,
   ];
 }
+
+/**
+ * Codex MCP children do not inherit the wrapper environment. Pin the explicit
+ * Borg state root into the per-launch child environment when one is active.
+ */
+export function codexStateRootConfigArgs(
+  env: NodeJS.ProcessEnv = process.env
+): string[] {
+  const stateRoot = env[BORG_STATE_ROOT_ENV];
+  if (stateRoot === undefined) return [];
+  return [
+    '-c',
+    `mcp_servers.borg.env.${BORG_STATE_ROOT_ENV}=${JSON.stringify(stateRoot)}`,
+  ];
+}

package/src/assimilate-cmd.ts

@@ -23,6 +23,7 @@ import { codexBorgSessionConfigArgs } from './launch-gate.js';
 import {
   codexAgentKindConfigArgs,
   codexRemoteWakeConfigArgs,
+  codexStateRootConfigArgs,
   withAgentRuntimeEnv,
 } from './agent-runtime.js';
 import type { BorgCli } from './cubes.js';
@@ -74,6 +75,14 @@ import type { SeatBinding, BindPendingSeatOutcome } from './seats.js';
 import { createHash } from 'node:crypto';
 import { buildOpenCodeLaunchArgs, type LaunchApprovalDecision } from './cli-tool-approval.js';
 import { resolveWorkingRepo, type WorkingRepo } from './working-repo.js';
+import {
+  BORG_LAUNCH_CLI_ENV,
+  BORG_LAUNCH_SCRATCH_ENV,
+  BORG_LAUNCH_WORKTREE_ENV,
+  codexLaunchDirectoryArgs,
+  scratchRootForSeat,
+  type LaunchAccessPaths,
+} from './launch-access.js';
 import type {
   AssociateRepositoryCubeResponse,
   CreateCubeRepository,
@@ -287,6 +296,12 @@ export interface AssimilateDeps {
   // launch root's .claude/settings.local.json (project-local; idempotent).
   // Real wiring = config-utils addProjectSessionStartHook.
   installProjectSessionHook: (projectRoot: string) => void;
+  /** Pre-authorize only the launched seat's worktree + scratch paths. */
+  provisionLaunchAccess?: (
+    cli: BorgCli,
+    projectRoot: string,
+    paths: LaunchAccessPaths,
+  ) => void;
 
   /** gh#27: optional test seam — when set, selectAssimilationAuthority uses
    *  this instead of prompting/failing. Not wired in production. */
@@ -1807,6 +1822,22 @@ export async function runAssimilate(
     spawnedWorktreePath = deps.cwd();
   }
 
+  // ----- Step 7b: provision launch access before persisting/launching -----
+  // The launched process gets exactly its current worktree plus a stable,
+  // disposable per-seat scratch root. Provision this before FINALIZE so a
+  // failed config write cannot produce a saved seat that launches without
+  // its promised path grants.
+  const agentCwd = deps.cwd(); // post-chdir if step 3 spawned a worktree
+  const seatWorktree = deps.findProjectRoot(agentCwd);
+  const monitorStateRoot = monitorStateRootForWorktree(seatWorktree);
+  const scratchRoot = scratchRootForSeat(deps.homedir(), result.drone_label, result.drone_id);
+  const launchAccessPaths: LaunchAccessPaths = {
+    // Access is granted at the repository root even when the harness starts in
+    // a nested package. The launch cwd remains the operator's chosen subdir.
+    worktree: seatWorktree,
+    scratch: scratchRoot,
+  };
+
   // ----- Step 8: persist the binding (narrow rollback — worktree exists if spawned) -----
   const activeCube: ActiveCube = {
     cubeId: result.cube_id,
@@ -1836,6 +1867,19 @@ export async function runAssimilate(
     }
   };
 
+  try {
+    deps.mkdirp(scratchRoot);
+    deps.provisionLaunchAccess?.(cli, seatWorktree, launchAccessPaths);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    deps.stderr(
+      `Borg could not pre-authorize the ${cli} launch paths: ${message}. ` +
+      'No agent was launched; correct the local configuration and retry.\n',
+    );
+    rollbackWorktree();
+    return 1;
+  }
+
   // Local-server authority: drive the COMPOSITE cube-owned FINALIZE (Race 2).
   // The cube lock is held OUTER across revalidate → binding-write → activate; the
   // typed expectation is declared HERE at the orchestration layer (reattach =
@@ -1945,13 +1989,6 @@ export async function runAssimilate(
     }
   }
 
-  // The worktree, not a reminted drone UUID, is the stable local seat identity
-  // for monitor runtime state. Capture it once before the lazy GC and launch
-  // paths so both use the exact same explicit root.
-  const agentCwd = deps.cwd(); // post-chdir if step 3 spawned a worktree
-  const seatWorktree = deps.findProjectRoot(agentCwd);
-  const monitorStateRoot = monitorStateRootForWorktree(seatWorktree);
-
   // gh#793: best-effort GC of orphaned inbox files (evicted/dead drones) in the
   // cube just joined — lazy-on-assimilate, no cron/new command. NEVER blocks or
   // fails the assimilate (whole call swallowed). Local-only signal (CubeDetail
@@ -2082,6 +2119,9 @@ export async function runAssimilate(
     ...(withAgentRuntimeEnv(process.env, cli) as Record<string, string>),
     ...modelEnv.set,
     BORG_SESSION: '1',
+    [BORG_LAUNCH_CLI_ENV]: cli,
+    [BORG_LAUNCH_WORKTREE_ENV]: seatWorktree,
+    [BORG_LAUNCH_SCRATCH_ENV]: scratchRoot,
   };
   if (cli === 'opencode' && launchApproval.openCodePermission) {
     childEnv.OPENCODE_PERMISSION = launchApproval.openCodePermission;
@@ -2127,10 +2167,12 @@ export async function runAssimilate(
     // off when no socket is available, overriding legacy static configs that
     // formerly used this transport marker as Codex identity.
     launchArgs = [
+      ...codexLaunchDirectoryArgs(launchAccessPaths),
       ...launchApproval.codexArgs,
       ...codexBorgSessionConfigArgs(),
       ...codexAgentKindConfigArgs(),
       ...codexRemoteWakeConfigArgs(codexSocketPath !== null),
+      ...codexStateRootConfigArgs(),
       ...remoteArgs,
       ...withCodexCwdArg(launchArgs, agentCwd),
     ];

package/src/assimilate-deps.ts

@@ -11,7 +11,7 @@
 import { spawnSync, spawn as spawnChild } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { existsSync, mkdirSync } from 'node:fs';
-import { hostname as osHostname, homedir as osHomedir } from 'node:os';
+import { hostname as osHostname } from 'node:os';
 import { createInterface } from 'node:readline/promises';
 import prompts from 'prompts';
 import { readinessProbeEnv } from './readiness-probe.js';
@@ -62,7 +62,13 @@ import {
   inboxPathForDrone,
   setCodexWakeTarget,
 } from './cubes.js';
-import { addProjectSessionStartHook } from './config-utils.js';
+import {
+  addClaudeLaunchAccess,
+  addCodexForeignPathReminderHook,
+  addOpenCodeLaunchAccess,
+  addProjectSessionStartHook,
+} from './config-utils.js';
+import type { LaunchAccessPaths } from './launch-access.js';
 import { findPendingServerEnrollment } from './config.js';
 import { setTerminalTitle as setTitle } from './terminal-title.js';
 import { defaultCliChoiceDeps, resolveCliChoice } from './cli-platform.js';
@@ -77,6 +83,7 @@ import {
   saveRepositoryAssociation,
 } from './repository-identity.js';
 import { PromptInterruptedError } from './repository-cube-init.js';
+import { borgHomeRoot } from './private-root.js';
 
 /**
  * Wraps the readline question operation with the production interruption
@@ -126,7 +133,7 @@ export function buildDefaultAssimilateDeps(
     // gh#556 Part 1: ~/.borg/worktrees relocation. homedir seams $HOME;
     // mkdirp is a plain recursive create (NO chmod of existing parents — the
     // ~/.borg credentials file's perms stay untouched).
-    homedir: () => osHomedir(),
+    homedir: () => borgHomeRoot(),
     mkdirp: (dir) => mkdirSync(dir, { recursive: true }),
     preparePrivateRoot: () => ensurePrivateBorgConfigRoot(),
     exec: (cmd, args, cwd, env) =>
@@ -235,6 +242,17 @@ export function buildDefaultAssimilateDeps(
     installProjectSessionHook: (projectRoot) => {
       addProjectSessionStartHook(projectRoot);
     },
+    provisionLaunchAccess: (cli, projectRoot, paths: LaunchAccessPaths) => {
+      if (cli === 'claude') {
+        addClaudeLaunchAccess(projectRoot, paths);
+      } else if (cli === 'codex') {
+        // Codex receives the path grant on the launch command itself. Its
+        // native PreToolUse hook is global but reads this launch's scoped env.
+        addCodexForeignPathReminderHook();
+      } else {
+        addOpenCodeLaunchAccess(projectRoot, paths);
+      }
+    },
 
     // #1015: discovery is advisory but still verifies the server-owned CA.
     detectLocalServer: async () =>

package/src/claude.ts

@@ -62,6 +62,7 @@ import {
   BORG_CODEX_REMOTE_WAKE_ENV,
   codexAgentKindConfigArgs,
   codexRemoteWakeConfigArgs,
+  codexStateRootConfigArgs,
   withAgentRuntimeEnv,
 } from './agent-runtime.js';
 import { findLoadedCodexThread } from './codex-app-server.js';
@@ -531,6 +532,7 @@ async function main() {
       ...codexBorgSessionConfigArgs(),
       ...codexAgentKindConfigArgs(),
       ...codexRemoteWakeConfigArgs(codexSocketPath !== null),
+      ...codexStateRootConfigArgs(),
       ...remoteArgs,
       ...withCodexCwdArg([...passthroughArgs, kickoff], process.cwd()),
     ];

package/src/cleanup-cmd.ts

@@ -36,7 +36,6 @@
 import { spawnSync } from 'node:child_process';
 import { realpathSync } from 'node:fs';
 import { sep, basename, dirname } from 'node:path';
-import { homedir } from 'node:os';
 import chalk from 'chalk';
 import {
   classifyDirty,
@@ -51,6 +50,7 @@ import {
   type ActiveCube,
 } from './cubes.js';
 import { defaultProbeSeat, type SeatStatus } from './seat-probe.js';
+import { borgHomeRoot } from './private-root.js';
 
 // ------------------------------------------------------------------
 // Types
@@ -208,7 +208,7 @@ const defaultDeps: Required<CleanupDeps> = {
     const r = spawnSync(cmd, args, { cwd, encoding: 'utf-8' });
     return { status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
   },
-  homeDir: () => homedir(),
+  homeDir: () => borgHomeRoot(),
   cwd: () => process.cwd(),
   listSeats: () => readAllProjectIdentities(),
   probeSeat: defaultProbeSeat,

package/src/cli-tool-approval.ts

@@ -1,8 +1,9 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { chmod, copyFile, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
-import { homedir, tmpdir } from 'node:os';
+import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import type { BorgCli } from './cubes.js';
+import { borgHomeRoot } from './private-root.js';
 
 /**
  * Client #20: the narrow coordination surface a borg-launched agent needs
@@ -360,7 +361,7 @@ async function withNativeCodexProfileLayer<T>(
   env: NodeJS.ProcessEnv,
   query: (profileCwd: string, trustOverride: string) => Promise<CodexConfigSnapshot>
 ): Promise<T> {
-  const codexHome = resolve(env.CODEX_HOME || join(homedir(), '.codex'));
+  const codexHome = resolve(env.CODEX_HOME || join(borgHomeRoot(), '.codex'));
   const profilePath = resolve(codexHome, `${profile}.config.toml`);
   if (dirname(profilePath) !== codexHome) {
     throw new Error('Codex profile path was invalid');

package/src/codex-remote.ts

@@ -1,5 +1,4 @@
 import { mkdirSync, chmodSync, readdirSync, rmSync, writeFileSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { spawn } from 'node:child_process';
@@ -11,7 +10,9 @@ import {
   BORG_CODEX_REMOTE_WAKE_ENV,
   codexAgentKindConfigArgs,
   codexRemoteWakeConfigArgs,
+  codexStateRootConfigArgs,
 } from './agent-runtime.js';
+import { borgConfigRoot } from './private-root.js';
 
 /**
  * gh#528 — npm-managed Codex remote-wake.
@@ -75,7 +76,7 @@ export interface PrepareCodexRemoteDeps {
   isAlive?: (pid: number) => boolean;
 }
 
-export const DEFAULT_CODEX_REMOTE_DIR = join(homedir(), '.config', 'borgmcp', 'codex-remote');
+export const DEFAULT_CODEX_REMOTE_DIR = join(borgConfigRoot(), 'codex-remote');
 const DEFAULT_CODEX_REMOTE_READY_TIMEOUT_MS = 30_000;
 const MAX_CODEX_APP_SERVER_STDERR_CHARS = 16_384;
 
@@ -426,6 +427,7 @@ export function defaultCodexRemoteDeps(): Pick<
           ...codexBorgSessionConfigArgs(),
           ...codexAgentKindConfigArgs(),
           ...codexRemoteWakeConfigArgs(),
+          ...codexStateRootConfigArgs(),
           ...codexAppServerSocketConfigArgs(socketPath),
           '--listen',
           `unix://${socketPath}`,