test: unit tests can no longer write a developer's real agent or Orca settings

config/scripts/bun-profile-change-scope.mjs

@@ -19,7 +19,8 @@ const BUILD_SCRIPTS = [
   'config/vitest.config.ts',
   'config/scripts/happy-dom-offscreen-canvas.ts',
   'config/scripts/happy-dom-mutation-observer-retention.ts',
-  'config/scripts/vitest-host-ports-setup.ts'
+  'config/scripts/vitest-host-ports-setup.ts',
+  'config/scripts/vitest-real-agent-home-write-guard.ts'
 ]
 const ALWAYS_FILES = new Set([
   'package.json',

config/scripts/vitest-real-agent-home-write-guard.test.ts

@@ -0,0 +1,84 @@
+import { randomUUID } from 'node:crypto'
+import { existsSync, mkdirSync, mkdtempSync, openSync, rmSync, writeFileSync } from 'node:fs'
+import { writeFile } from 'node:fs/promises'
+import { homedir, tmpdir, userInfo } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { takeRealAgentHomeWriteViolations } from './vitest-real-agent-home-write-guard'
+
+// Why never-created paths: each sits under a missing folder or is a forced no-op removal, so even
+// with the guard off (the ablation) nothing lands in the real home.
+const missingRealFolder = (entry: string) =>
+  join(userInfo().homedir, entry, `orca-vitest-guard-${randomUUID()}`)
+
+afterEach(() => {
+  takeRealAgentHomeWriteViolations()
+  vi.unstubAllEnvs()
+})
+
+describe('vitest real-agent-home write guard', () => {
+  it('refuses a named-import sync write under the real ~/.codex', () => {
+    const target = join(missingRealFolder('.codex'), 'config.toml')
+    expect(() => writeFileSync(target, '[projects."/tmp/x"]\n')).toThrow(/real-agent-home guard/)
+    expect(existsSync(target)).toBe(false)
+  })
+
+  it('refuses a promise write under a ~/.claude.json sibling', async () => {
+    const target = join(missingRealFolder('.claude.json'), 'x.tmp')
+    await expect(writeFile(target, '{}')).rejects.toThrow(/real-agent-home guard/)
+    expect(existsSync(target)).toBe(false)
+  })
+
+  it('refuses a removal that would otherwise succeed silently', () => {
+    expect(() => rmSync(missingRealFolder('.orca'), { recursive: true, force: true })).toThrow(
+      /real-agent-home guard/
+    )
+  })
+
+  it('still records a refusal the writer swallowed, so the test fails afterwards', () => {
+    try {
+      mkdirSync(join(missingRealFolder('.cursor'), 'projects'))
+    } catch {
+      // Trust writers swallow their errors like this.
+    }
+    expect(takeRealAgentHomeWriteViolations()).toEqual([expect.stringContaining('fs.mkdirSync')])
+  })
+
+  it('protects the account home even when HOME points elsewhere', () => {
+    const tempHome = mkdtempSync(join(tmpdir(), 'orca-vitest-guard-home-'))
+    vi.stubEnv('HOME', tempHome)
+    vi.stubEnv('USERPROFILE', tempHome)
+    try {
+      expect(homedir()).not.toBe(userInfo().homedir)
+      expect(() => rmSync(missingRealFolder('.copilot'), { force: true })).toThrow(
+        /real-agent-home guard/
+      )
+    } finally {
+      rmSync(tempHome, { recursive: true, force: true })
+    }
+  })
+
+  it('leaves a sibling that only shares an agent folder prefix alone', () => {
+    const sibling = join(userInfo().homedir, `.codex-orca-vitest-guard-${randomUUID()}`)
+    expect(() => rmSync(sibling, { force: true })).not.toThrow()
+  })
+
+  it('stands down while an opted-in real-agent suite switch is set', () => {
+    vi.stubEnv('ORCA_CODEX_TRUST_CONTRACT_BINARY', '/opt/codex')
+    expect(() => rmSync(missingRealFolder('.codex'), { force: true })).not.toThrow()
+  })
+
+  it('allows reads there and writes under a temp home', () => {
+    expect(() => openSync(join(missingRealFolder('.codex'), 'config.toml'), 'r')).toThrow(/ENOENT/)
+    const tempHome = mkdtempSync(join(tmpdir(), 'orca-vitest-guard-home-'))
+    try {
+      const target = join(tempHome, '.codex', 'config.toml')
+      mkdirSync(join(tempHome, '.codex'))
+      writeFileSync(target, 'x')
+      expect(existsSync(target)).toBe(true)
+    } finally {
+      rmSync(tempHome, { recursive: true, force: true })
+    }
+    expect(takeRealAgentHomeWriteViolations()).toEqual([])
+  })
+})

config/scripts/vitest-real-agent-home-write-guard.ts

@@ -0,0 +1,212 @@
+import fs from 'node:fs'
+import { syncBuiltinESMExports } from 'node:module'
+import { userInfo } from 'node:os'
+import { isAbsolute, join, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterAll, afterEach } from 'vitest'
+
+/**
+ * Why: agent trust and hook writers resolve `~` at write time, so a unit test that reaches one
+ * edits the developer's real Codex, Claude or Orca config. Any write there fails the test instead.
+ * Child processes a test spawns are outside this guard.
+ */
+
+type GuardState = { roots: string[]; violations: string[] }
+
+const AGENT_HOME_ENTRIES = [
+  '.codex',
+  '.claude',
+  '.orca',
+  '.cursor',
+  '.copilot',
+  '.gemini',
+  '.qoder'
+]
+// Why a bare prefix: Claude's config file and its atomic-write temp siblings sit beside `~/.claude`.
+const AGENT_HOME_FILE_PREFIXES = ['.claude.json']
+// Why: an Orca terminal exports these pointing at the live app and agent state; guarded, then unset.
+const INHERITED_STATE_ENV = [
+  'ORCA_USER_DATA_PATH',
+  'CODEX_HOME',
+  'ORCA_CODEX_HOME',
+  'CLAUDE_CONFIG_DIR'
+]
+// Why: an Orca terminal points this at the live app's CLI, which a test's child shell would run.
+const INHERITED_LIVE_CLI_ENV = ['ORCA_CODEX_LAUNCH_PREFLIGHT']
+// Why: opted-in real-agent suites point a real CLI at its own home on purpose; each suite's own switch.
+const REAL_AGENT_SUITE_SWITCHES = [
+  'ORCA_REAL_CLAUDE_SUPERVISED_STOP',
+  'ORCA_CODEX_CONTRACT_BINARY',
+  'ORCA_CODEX_NO_DAEMON_CONTRACT_BINARY',
+  'ORCA_CODEX_TRUST_CONTRACT_BINARY',
+  'ORCA_REPRO_CODEX_BINARY'
+]
+const realAgentSuiteOptedIn = () => REAL_AGENT_SUITE_SWITCHES.some((name) => process.env[name])
+const foldCase = process.platform === 'darwin' || process.platform === 'win32'
+
+function normalize(path: string): string {
+  const resolved = resolve(path)
+  return foldCase ? resolved.toLowerCase() : resolved
+}
+
+function realHomes(): string[] {
+  const homes = [process.env.HOME, process.env.USERPROFILE]
+  try {
+    // Why: HOME does not move this one, so a test that swaps HOME cannot hide the real home.
+    homes.unshift(userInfo().homedir)
+  } catch {
+    // No passwd entry (some containers): HOME is all there is.
+  }
+  return homes.filter((home): home is string => Boolean(home))
+}
+
+/** Folder roots end in a separator so `~/.orca` never covers `~/.orca-relay`; file prefixes do not. */
+function protectedRoots(): string[] {
+  const folders = realHomes().flatMap((home) => [
+    ...AGENT_HOME_ENTRIES.map((entry) => join(home, entry)),
+    join(home, 'Library', 'Application Support', 'orca'),
+    join(home, '.config', 'orca'),
+    join(home, 'AppData', 'Roaming', 'orca')
+  ])
+  for (const name of INHERITED_STATE_ENV) {
+    const value = process.env[name]
+    if (value && isAbsolute(value)) {
+      folders.push(value)
+    }
+  }
+  const filePrefixes = realHomes().flatMap((home) =>
+    AGENT_HOME_FILE_PREFIXES.map((entry) => normalize(join(home, entry)))
+  )
+  return [...new Set([...folders.map((folder) => normalize(folder) + sep), ...filePrefixes])]
+}
+
+function targetPath(target: unknown): string | null {
+  if (typeof target === 'string') {
+    return target.startsWith('file:') ? fileURLToPath(target) : target
+  }
+  if (target instanceof URL) {
+    return fileURLToPath(target)
+  }
+  if (Buffer.isBuffer(target)) {
+    return target.toString()
+  }
+  return null
+}
+
+function assertOutsideRealHome(state: GuardState, operation: string, target: unknown): void {
+  const path = targetPath(target)
+  if (path === null || realAgentSuiteOptedIn()) {
+    return
+  }
+  const normalized = normalize(path) + sep
+  const root = state.roots.find((candidate) => normalized.startsWith(candidate))
+  if (!root) {
+    return
+  }
+  const error = new Error(
+    `[vitest real-agent-home guard] ${operation}(${path}) would write the real agent home under ${root}; give the test a temp home`
+  )
+  // Why the stack: the writer that swallowed this is what the failing test has to fix.
+  state.violations.push(error.stack?.split('\n').slice(0, 12).join('\n') ?? error.message)
+  throw error
+}
+
+const WRITE_OPEN_FLAGS = fs.constants.O_WRONLY | fs.constants.O_RDWR | fs.constants.O_CREAT
+
+function opensForWrite(flags: unknown): boolean {
+  if (typeof flags === 'number') {
+    return (flags & WRITE_OPEN_FLAGS) !== 0
+  }
+  return typeof flags === 'string' && /[wa+]/.test(flags)
+}
+
+// Argument positions each mutating call writes to; `open` counts only when its flags write.
+const GUARDED_TARGETS: Record<string, readonly number[]> = {
+  writeFile: [0],
+  appendFile: [0],
+  mkdir: [0],
+  mkdtemp: [0],
+  rename: [0, 1],
+  copyFile: [1],
+  cp: [1],
+  symlink: [1],
+  link: [1],
+  rm: [0],
+  rmdir: [0],
+  unlink: [0],
+  truncate: [0],
+  open: [0]
+}
+
+function guard(
+  state: GuardState,
+  api: typeof fs | typeof fs.promises,
+  name: string,
+  positions: readonly number[],
+  label: string
+): void {
+  const descriptor = Object.getOwnPropertyDescriptor(api, name)
+  const original: unknown = descriptor?.value
+  if (!descriptor || typeof original !== 'function') {
+    return
+  }
+  const target = original
+  function guarded(this: unknown, ...args: unknown[]): unknown {
+    try {
+      if (!name.startsWith('open') || opensForWrite(args[1] ?? 'r')) {
+        for (const position of positions) {
+          assertOutsideRealHome(state, label, args[position])
+        }
+      }
+    } catch (error) {
+      if (api === fs.promises) {
+        return Promise.reject(error)
+      }
+      throw error
+    }
+    return target.apply(this, args)
+  }
+  Object.defineProperty(api, name, { ...descriptor, value: guarded })
+}
+
+function install(): GuardState {
+  const state: GuardState = { roots: protectedRoots(), violations: [] }
+  for (const [name, positions] of Object.entries(GUARDED_TARGETS)) {
+    guard(state, fs, name, positions, `fs.${name}`)
+    guard(state, fs, `${name}Sync`, positions, `fs.${name}Sync`)
+    guard(state, fs.promises, name, positions, `fs.promises.${name}`)
+  }
+  guard(state, fs, 'createWriteStream', [0], 'fs.createWriteStream')
+  // Why: named ESM imports of node:fs keep the originals until the builtin exports are re-synced.
+  syncBuiltinESMExports()
+  return state
+}
+
+declare global {
+  // Why once per process: re-wrapping per test file would stack wrappers around wrappers.
+  var orcaRealAgentHomeWriteGuard: GuardState | undefined
+}
+const state = (globalThis.orcaRealAgentHomeWriteGuard ??= install())
+// Why after install: the guard keeps the inherited paths as roots; tests that need one set their own.
+const inheritedEnvToUnset = realAgentSuiteOptedIn()
+  ? []
+  : [...INHERITED_STATE_ENV, ...INHERITED_LIVE_CLI_ENV]
+for (const name of inheritedEnvToUnset) {
+  delete process.env[name]
+}
+
+/** Drains recorded violations; only the guard's own self-test should need this. */
+export function takeRealAgentHomeWriteViolations(): string[] {
+  return state.violations.splice(0)
+}
+
+function failOnViolations(): void {
+  const violations = takeRealAgentHomeWriteViolations()
+  if (violations.length > 0) {
+    // Why rethrow here: trust writers swallow errors, so the throw at the call site can vanish.
+    throw new Error(`[vitest real-agent-home guard]\n${violations.join('\n')}`)
+  }
+}
+
+afterEach(failOnViolations)
+afterAll(failOnViolations)

config/tsconfig.node.json

@@ -5,6 +5,7 @@
     "./build-plugins/**/*",
     "./scripts/vitest-host-ports-setup.ts",
     "./scripts/vitest-caller-identity-env-setup.ts",
+    "./scripts/vitest-real-agent-home-write-guard.ts",
     "../src/main/**/*",
     "../src/renderer/src/lib/skill-freshness-display-status.ts",
     "../src/renderer/src/components/native-chat/native-chat-resolution-receipt.ts",

config/vitest.config.ts

@@ -30,6 +30,7 @@ export default defineConfig({
     execArgv: ['--no-experimental-webstorage', '--expose-gc'],
     // Why: happy-dom drops MutationObserver callbacks on GC; keep them alive like a browser does.
     setupFiles: [
+      resolve('config/scripts/vitest-real-agent-home-write-guard.ts'),
       resolve('config/scripts/happy-dom-offscreen-canvas.ts'),
       resolve('config/scripts/happy-dom-mutation-observer-retention.ts'),
       resolve('config/scripts/vitest-host-ports-setup.ts'),