From 30b5ab4c8b5e949ac7282e90985dd9aad61c68ee Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Krzysztof=20W=C3=B3jt?= <k.wojt@accenture.com>
Date: Fri, 10 Jul 2026 12:13:20 +0200
Subject: [PATCH] fix: normalize macOS paths and isolate tests

---
 CHANGELOG.md                     |  5 +++++
 src/doc_compact.ts               |  7 ++++---
 src/install.ts                   |  4 +++-
 src/paths.ts                     | 18 ++++++++++++++++++
 src/project.ts                   | 12 ++++++++++--
 src/text_commands.ts             |  5 +++--
 tests/cli.test.ts                |  9 ++++++++-
 tests/helpers/tsx_process.ts     |  6 ++++++
 tests/install.test.ts            |  3 ++-
 tests/paths.test.ts              | 22 +++++++++++++++++++++-
 tests/session_store_race.test.ts | 10 ++++------
 tests/setup/isolate-home.ts      |  7 +++++++
 tests/util.test.ts               | 17 +++++++++--------
 tests/worker_daemon_e2e.test.ts  |  8 +++++++-
 tests/worker_index_e2e.test.ts   | 14 +++++++++++---
 15 files changed, 118 insertions(+), 29 deletions(-)
 create mode 100644 tests/helpers/tsx_process.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c8ea83af..9432d62b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,11 @@ All notable changes to Token-Goat are documented in this file. Format follows Ke
 
 ## [Unreleased]
 
+### Fixed
+
+- **macOS `/var` and `/private/var` aliases could produce different cache and index keys for the same file.** Path canonicalization now normalizes the Darwin system alias consistently, restoring relative `skeleton`/`outline`, trace frame detection, project discovery, settings paths, and doc-compact reuse for temporary paths.
+- **The test harness could touch the live macOS data directory or fail to start TypeScript race helpers in restricted sandboxes.** Darwin tests now isolate `HOME`/`USERPROFILE`, and subprocess fixtures load `tsx` without its IPC-based CLI.
+
 ## [2.6.12] - 2026-07-10
 
 ### Fixed
diff --git a/src/doc_compact.ts b/src/doc_compact.ts
index 818dae79..0155ac82 100644
--- a/src/doc_compact.ts
+++ b/src/doc_compact.ts
@@ -12,7 +12,7 @@ import * as path from 'path'
 
 import { dataDir } from './constants.js'
 import { atomicWriteText } from './util.js'
-import { normalizePath } from './paths.js'
+import { resolveIndexPath } from './paths.js'
 
 const defaultSentencesPerSection = 2
 const headerPrefix = '<!-- token-goat doc-compact source-hash:'
@@ -56,8 +56,9 @@ function _compactSlug(absPathStr: string): string {
  * so same-named docs in different projects never collide.
  */
 export function compactPathFor(sourcePath: string): string {
-  // Route through normalizePath (not just path.resolve) so the sidecar key is identical whether the caller passes a raw path (cmdCompactDoc) or one already normalized upstream (preReadHandler) -- notably including 8.3 short-name expansion, which path.resolve alone does not perform.
-  const abs = normalizePath(path.resolve(sourcePath))
+  // Use the same absolute filesystem identity as the symbol index so aliases
+  // such as macOS /var and /private/var cannot create duplicate sidecars.
+  const abs = resolveIndexPath(sourcePath)
   return path.join(dataDir(), compactSubdir, `${_compactSlug(abs)}.md`)
 }
 
diff --git a/src/install.ts b/src/install.ts
index 6b180c40..6e5f0d54 100644
--- a/src/install.ts
+++ b/src/install.ts
@@ -17,6 +17,7 @@ import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
 
+import { resolveIndexPath } from './paths.js'
 import { atomicWriteText, backupFile, ensureDirSync } from './util.js'
 
 /** Where to install: the user's home `~/.claude` or the project's `.claude`. */
@@ -95,7 +96,8 @@ function hookCommand(eventArg: string): string {
 
 /** Return the `~/.claude` or `<cwd>/.claude` settings path for `scope`. */
 export function settingsPath(scope: HookScope): string {
-  const base = scope === 'user' ? path.join(os.homedir(), '.claude') : path.join(process.cwd(), '.claude')
+  const root = scope === 'user' ? os.homedir() : resolveIndexPath(process.cwd())
+  const base = path.join(root, '.claude')
   return path.join(base, 'settings.json')
 }
 
diff --git a/src/paths.ts b/src/paths.ts
index 2aff0da6..a7a299ef 100644
--- a/src/paths.ts
+++ b/src/paths.ts
@@ -109,9 +109,27 @@ export function normalizePath(p: string): string {
   // Step 3: lowercase the drive-letter prefix (C: -> c:) on all platforms. WSL processes emit Windows-format paths on Linux; both must produce the same cache key, so lowercasing is unconditional.
   s = lowercaseDriveLetter(s)
 
+  // Step 4: macOS reports the same temp path with two system aliases depending
+  // on whether it came from os.tmpdir() or process.cwd().
+  s = normalizeDarwinSystemAlias(s)
+
   return s
 }
 
+/**
+ * Normalize macOS's public `/var` alias to its physical `/private/var` path.
+ *
+ * `os.tmpdir()` commonly returns `/var/...`, while `process.cwd()` returns
+ * `/private/var/...` after chdir. Keep this lexical so deleted/future paths
+ * normalize too, without resolving arbitrary user symlinks.
+ */
+export function normalizeDarwinSystemAlias(p: string): string {
+  if (process.platform !== 'darwin') return p
+  if (p.toLowerCase() === '/var') return `/private${p}`
+  if (p.slice(0, 5).toLowerCase() === '/var/') return `/private${p}`
+  return p
+}
+
 /**
  * Resolve a user-supplied path to the canonical key form the symbol index uses.
  *
diff --git a/src/project.ts b/src/project.ts
index e6d30481..6892a8cf 100644
--- a/src/project.ts
+++ b/src/project.ts
@@ -7,7 +7,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { extractErrorMessage, foldPath } from './util.js';
-import { lowercaseDriveLetter, expandShortPath } from './paths.js';
+import { lowercaseDriveLetter, expandShortPath, normalizeDarwinSystemAlias } from './paths.js';
 
 /**
  * Windows drive prefixes that resolve to the same NTFS location.
@@ -93,6 +93,10 @@ export function canonicalize(inputPath: string | URL, baseDir?: string): string
   // Expand a Windows 8.3 short-name segment (e.g. `JOHNDO~1.ACM`) to its long form: %TEMP%/%USERPROFILE% can be pinned to short form, which every os.tmpdir()-based path inherits, while git always emits long form, so without this the same physical path canonicalizes two different ways depending on its source. Shared with normalizePath (paths.ts) via expandShortPath so the rule can't drift between the two call sites.
   normalized = expandShortPath(normalized);
 
+  // macOS exposes /var as /private/var after chdir. Normalize that system alias
+  // so existing, deleted, and future paths all have one canonical form.
+  normalized = normalizeDarwinSystemAlias(normalized);
+
   // Lowercase drive letter on Windows (e.g., "C:/foo" → "c:/foo"). Shared with
   // normalizePath (paths.ts) via lowercaseDriveLetter so the rule can't drift.
   normalized = lowercaseDriveLetter(normalized);
@@ -240,7 +244,11 @@ export function findProject(cwd: string): Project | null {
     // comparing -- matching the platform-gated convention used elsewhere (isUnderBlockedRoot,
     // assertWalkableRoot, pruneDeletedFiles) -- or this guard silently stops matching and the
     // walk continues past the temp boundary.
-    if (sysTemp && foldPath(current) === foldPath(sysTemp)) {
+    if (
+      sysTemp &&
+      normalizeDarwinSystemAlias(foldPath(current)) ===
+        normalizeDarwinSystemAlias(foldPath(sysTemp))
+    ) {
       break;
     }
 
diff --git a/src/text_commands.ts b/src/text_commands.ts
index 2e019c0f..cf3b01b9 100644
--- a/src/text_commands.ts
+++ b/src/text_commands.ts
@@ -12,6 +12,7 @@ import { walkProject } from './baseline.js'
 import { loadConfig } from './config.js'
 import { tokenGoatHome } from './disk_cache.js'
 import { FILTERS } from './filters.js'
+import { normalizeDarwinSystemAlias } from './paths.js'
 import { canonicalize, findProject } from './project.js'
 import { clearAll, loadEntries, setEntry, unsetEntry } from './project_memory.js'
 import { getSessionFiles } from './session.js'
@@ -232,8 +233,8 @@ function isProjectFrame(framePath: string, cwd: string): boolean {
   // canonicalize only lowercases the drive letter, not the rest of the path, so fold both
   // sides through foldPath (util.ts) to restore case-insensitive comparison on Windows/macOS
   // (matching the platform-gated convention used elsewhere, e.g. isUnderBlockedRoot).
-  const normalCwd = foldPath(canonicalize(cwd))
-  const normalAbs = foldPath(canonicalize(framePath, cwd))
+  const normalCwd = normalizeDarwinSystemAlias(foldPath(canonicalize(cwd)))
+  const normalAbs = normalizeDarwinSystemAlias(foldPath(canonicalize(framePath, cwd)))
   if (normalAbs.startsWith(normalCwd)) {
     // Ensure it's a real directory boundary: the path is either exactly the cwd,
     // or the next character after cwd is a path separator. This prevents false matches
diff --git a/tests/cli.test.ts b/tests/cli.test.ts
index 2df315bd..48324bad 100644
--- a/tests/cli.test.ts
+++ b/tests/cli.test.ts
@@ -901,7 +901,14 @@ describe('skill-compact --path / skill-list --json (isolated data dir)', () => {
   function runIsolated(args: string[], dataDir: string, extraEnv?: Record<string, string>): RunResult {
     const res = spawnSync(process.execPath, [BUNDLE, ...args], {
       encoding: 'utf8',
-      env: { ...process.env, LOCALAPPDATA: dataDir, XDG_DATA_HOME: dataDir, ...extraEnv },
+      env: {
+        ...process.env,
+        HOME: dataDir,
+        USERPROFILE: dataDir,
+        LOCALAPPDATA: dataDir,
+        XDG_DATA_HOME: dataDir,
+        ...extraEnv,
+      },
     })
     return { status: res.status, stdout: res.stdout ?? '', stderr: res.stderr ?? '' }
   }
diff --git a/tests/helpers/tsx_process.ts b/tests/helpers/tsx_process.ts
new file mode 100644
index 00000000..4e009f75
--- /dev/null
+++ b/tests/helpers/tsx_process.ts
@@ -0,0 +1,6 @@
+/** Build Node args for a TypeScript child without invoking tsx's IPC-based CLI. */
+export function tsxProcessArgs(entry: string, ...args: string[]): string[] {
+  // --import is unavailable on early Node 18 releases still allowed by package.json.
+  const loaderFlag = process.allowedNodeEnvironmentFlags.has('--import') ? '--import' : '--loader'
+  return [loaderFlag, 'tsx', entry, ...args]
+}
diff --git a/tests/install.test.ts b/tests/install.test.ts
index 86bbb9c3..750d3653 100644
--- a/tests/install.test.ts
+++ b/tests/install.test.ts
@@ -5,6 +5,7 @@ import * as path from 'node:path'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 
 import { installHooks, isInstalled, settingsPath, uninstallHooks } from '../src/install.js'
+import { resolveIndexPath } from '../src/paths.js'
 
 let TMP: string
 let origCwd: string
@@ -30,7 +31,7 @@ describe('settingsPath', () => {
 
   it('project scope ends in settings.json under cwd/.claude', () => {
     const p = settingsPath('project')
-    expect(p).toBe(path.join(TMP, '.claude', 'settings.json'))
+    expect(p).toBe(path.join(resolveIndexPath(TMP), '.claude', 'settings.json'))
   })
 })
 
diff --git a/tests/paths.test.ts b/tests/paths.test.ts
index 79d56660..31ad3cab 100644
--- a/tests/paths.test.ts
+++ b/tests/paths.test.ts
@@ -3,7 +3,13 @@ import * as path from 'node:path'
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 
-import { lowercaseDriveLetter, normalizePath, resolveIndexPath, safeJoin } from '../src/paths.js'
+import {
+  lowercaseDriveLetter,
+  normalizeDarwinSystemAlias,
+  normalizePath,
+  resolveIndexPath,
+  safeJoin,
+} from '../src/paths.js'
 
 describe('safeJoin', () => {
   it('joins normally when no part contains a colon', () => {
@@ -205,6 +211,20 @@ describe('lowercaseDriveLetter', () => {
   })
 })
 
+describe('normalizeDarwinSystemAlias', () => {
+  it('normalizes only the /var path boundary on macOS', () => {
+    const expectedRoot = process.platform === 'darwin' ? '/private/var' : '/var'
+    const expectedChild = process.platform === 'darwin' ? '/private/var/folders/example' : '/var/folders/example'
+    expect(normalizeDarwinSystemAlias('/var')).toBe(expectedRoot)
+    expect(normalizeDarwinSystemAlias('/var/folders/example')).toBe(expectedChild)
+    expect(normalizeDarwinSystemAlias('/VAR/FOLDERS/example')).toBe(
+      process.platform === 'darwin' ? '/private/VAR/FOLDERS/example' : '/VAR/FOLDERS/example',
+    )
+    expect(normalizeDarwinSystemAlias('/private/var/folders/example')).toBe('/private/var/folders/example')
+    expect(normalizeDarwinSystemAlias('/variant/example')).toBe('/variant/example')
+  })
+})
+
 describe('resolveIndexPath', () => {
   // These assert on WHICH resolver is invoked (path.win32.resolve vs the ambient, host-native
   // path.resolve), not just the output value: on a real Windows host, the ambient path.resolve
diff --git a/tests/session_store_race.test.ts b/tests/session_store_race.test.ts
index 1d3e5eed..556a75e3 100644
--- a/tests/session_store_race.test.ts
+++ b/tests/session_store_race.test.ts
@@ -20,14 +20,10 @@ import { fileURLToPath } from 'node:url'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 
 import { ROOT } from './helpers/bundle.js'
+import { tsxProcessArgs } from './helpers/tsx_process.js'
 
 const HERE = path.dirname(fileURLToPath(import.meta.url))
 const WORKER = path.join(HERE, 'fixtures', 'session_race_worker.ts')
-// Spawn tsx's own CLI entry via `node`, not the node_modules/.bin/tsx(.cmd) shim -- the
-// shim is a shell script / batch file on POSIX/Windows respectively, and Node's spawn()
-// cannot exec those directly without shell:true.
-const TSX_CLI = path.join(ROOT, 'node_modules', 'tsx', 'dist', 'cli.mjs')
-
 let tmpHome: string
 
 beforeEach(() => {
@@ -45,7 +41,9 @@ afterEach(() => {
 /** Spawn one race worker process; resolves on a clean exit, rejects otherwise. */
 function runWorker(sessionId: string, prefix: string, count: number): Promise<void> {
   return new Promise((resolve, reject) => {
-    const child = spawn(process.execPath, [TSX_CLI, WORKER, sessionId, prefix, String(count)], {
+    // Loading tsx through Node avoids the tsx CLI's IPC socket, which is denied
+    // in restricted macOS sandboxes even though the worker itself needs no IPC.
+    const child = spawn(process.execPath, tsxProcessArgs(WORKER, sessionId, prefix, String(count)), {
       cwd: ROOT,
       env: { ...process.env, TOKEN_GOAT_HOME: tmpHome },
       stdio: ['ignore', 'pipe', 'pipe'],
diff --git a/tests/setup/isolate-home.ts b/tests/setup/isolate-home.ts
index e1a2da4b..a1fd1917 100644
--- a/tests/setup/isolate-home.ts
+++ b/tests/setup/isolate-home.ts
@@ -50,6 +50,13 @@ try {
 }
 process.env['LOCALAPPDATA'] = dataHome
 process.env['XDG_DATA_HOME'] = dataHome
+// macOS ignores LOCALAPPDATA/XDG_DATA_HOME and derives Application Support
+// from HOME. Redirect it too so DATA_DIR never points at the developer's live
+// index or worker. USERPROFILE keeps spawned cross-platform tests consistent.
+if (process.platform === 'darwin') {
+  process.env['HOME'] = dataHome
+  process.env['USERPROFILE'] = dataHome
+}
 process.on('exit', () => {
   try {
     fs.rmSync(dataHome, { recursive: true, force: true })
diff --git a/tests/util.test.ts b/tests/util.test.ts
index 630007eb..42b6dbcf 100644
--- a/tests/util.test.ts
+++ b/tests/util.test.ts
@@ -36,13 +36,10 @@ import type * as fs from 'node:fs'
 
 import { atomicWriteBytes, atomicWriteText, ensureDirSync, runGit, sleepSync, noWindowCreationFlags, withFileLock } from '../src/util.js'
 import { ROOT } from './helpers/bundle.js'
+import { tsxProcessArgs } from './helpers/tsx_process.js'
 
 const HERE = path.dirname(fileURLToPath(import.meta.url))
 const LOCK_HOLDER = path.join(HERE, 'fixtures', 'lock_holder.ts')
-// Spawn tsx's own CLI entry via `node`, not the node_modules/.bin/tsx(.cmd) shim -- the shim
-// is a shell script / batch file on POSIX/Windows respectively, and Node's spawn() cannot
-// exec those directly without shell:true (same rationale as tests/session_store_race.test.ts).
-const TSX_CLI = path.join(ROOT, 'node_modules', 'tsx', 'dist', 'cli.mjs')
 
 describe('sleepSync', () => {
   it('blocks for approximately the requested duration', () => {
@@ -230,10 +227,14 @@ describe('withFileLock', () => {
       const holdMs = 8000
       const staleMs = 4000
       const holderExit = new Promise<string>((resolve, reject) => {
-        const child = spawn(process.execPath, [TSX_CLI, LOCK_HOLDER, lockPath, String(holdMs), String(staleMs)], {
-          cwd: ROOT,
-          stdio: ['ignore', 'pipe', 'pipe'],
-        })
+        const child = spawn(
+          process.execPath,
+          tsxProcessArgs(LOCK_HOLDER, lockPath, String(holdMs), String(staleMs)),
+          {
+            cwd: ROOT,
+            stdio: ['ignore', 'pipe', 'pipe'],
+          },
+        )
         let stdout = ''
         let stderr = ''
         child.stdout.on('data', (d: Buffer) => (stdout += d.toString()))
diff --git a/tests/worker_daemon_e2e.test.ts b/tests/worker_daemon_e2e.test.ts
index 5f8edfb5..7d57fdaa 100644
--- a/tests/worker_daemon_e2e.test.ts
+++ b/tests/worker_daemon_e2e.test.ts
@@ -49,7 +49,13 @@ function runBundle(args: string[], env: NodeJS.ProcessEnv, cwd: string): RunResu
 }
 
 function tgEnv(base: string): NodeJS.ProcessEnv {
-  return { ...process.env, LOCALAPPDATA: base, XDG_DATA_HOME: base }
+  return {
+    ...process.env,
+    HOME: base,
+    USERPROFILE: base,
+    LOCALAPPDATA: base,
+    XDG_DATA_HOME: base,
+  }
 }
 
 /**
diff --git a/tests/worker_index_e2e.test.ts b/tests/worker_index_e2e.test.ts
index 63b3d170..d5e71f18 100644
--- a/tests/worker_index_e2e.test.ts
+++ b/tests/worker_index_e2e.test.ts
@@ -270,7 +270,13 @@ describe('built bundle keys a relative-root index on the absolute path', () => {
   let relData: string
 
   function relEnv(): NodeJS.ProcessEnv {
-    return { ...process.env, LOCALAPPDATA: relData, XDG_DATA_HOME: relData }
+    return {
+      ...process.env,
+      HOME: relData,
+      USERPROFILE: relData,
+      LOCALAPPDATA: relData,
+      XDG_DATA_HOME: relData,
+    }
   }
 
   function runRel(args: string[]): { status: number | null; stdout: string; stderr: string } {
@@ -285,6 +291,9 @@ describe('built bundle keys a relative-root index on the absolute path', () => {
   // Mirror constants.ts::defaultDataDir so the test can open the same global DB the bundle wrote to under the redirected data dir.
   function globalDbFor(base: string): string {
     if (process.platform === 'win32') return path.join(base, 'dfk-helper', 'token-goat', 'global.db')
+    if (process.platform === 'darwin') {
+      return path.join(base, 'Library', 'Application Support', 'token-goat', 'global.db')
+    }
     return path.join(base, 'token-goat', 'global.db')
   }
 
@@ -312,8 +321,7 @@ describe('built bundle keys a relative-root index on the absolute path', () => {
     if (relRepo) fs.rmSync(relRepo, { recursive: true, force: true })
   })
 
-  // The darwin data dir ignores LOCALAPPDATA/XDG_DATA_HOME, so the DB would live in the real home dir; skip the direct-DB probe there. CI runs Windows.
-  it.skipIf(process.platform === 'darwin')(
+  it(
     'stores the symbol file_path as the absolute-normalized key',
     () => {
       const dbPath = globalDbFor(relData)