fix(host-kit): resolve the code-signature root so a symlinked checkout stamps its own files (#2429)

walkDaemonCodeGraph resolved manifests through realpath but left the root
and the entry as given. Under a symlinked prefix — macOS /tmp, a symlinked
checkout — the two then sat on either side of the link: every workspace
package was labelled by the route out of the repository and back in
(../../../private/tmp/...), and isInstalledDependencyPath read every
installed dependency as a workspace package and walked its whole closure.

Route the root, the entry, and the manifest through one resolver, and give
the cache the same resolved pair so a document's entry label still matches
the walk that wrote it. The cache's private copy of that resolver goes away.

The fixtures now build a resolved root, which is the shape a production
caller passes (findProjectRoot derives it from an already-resolved
import.meta.url). Naming a root through a link is covered on purpose
instead, by two tests that fail without this change on any platform.

Author: thymikee

packages/host-kit/src/code-signature-cache.test.ts

@@ -5,8 +5,7 @@ import path from 'node:path';
 import { afterEach, test, vi } from 'vitest';
 import { computeDaemonCodeSignature } from './code-signature.ts';
 import { resolveCachedDaemonCodeSignature } from './code-signature-cache.ts';
-import { writeWorkspaceFixture } from './code-signature.fixtures.ts';
-import { mkdtempForTestSync } from './internal/tmp-dir.fixtures.ts';
+import { createCheckoutRootForTest, writeWorkspaceFixture } from './code-signature.fixtures.ts';
 
 afterEach(() => {
   vi.restoreAllMocks();
@@ -38,7 +37,7 @@ function writeGraphFixture(
   depPath: string;
   cacheHome: string;
 } {
-  const root = mkdtempForTestSync(prefix);
+  const root = createCheckoutRootForTest(prefix);
   const entryPath = path.join(root, 'src', 'daemon.ts');
   const depPath = path.join(root, 'src', dependency.fileName);
   fs.mkdirSync(path.dirname(entryPath), { recursive: true });
@@ -314,7 +313,7 @@ test('resolveCachedDaemonCodeSignature ignores a cache document another user wro
 });
 
 test('resolveCachedDaemonCodeSignature reports an unreadable entry as unknown', () => {
-  const root = mkdtempForTestSync('agent-device-signature-cache-missing-');
+  const root = createCheckoutRootForTest('agent-device-signature-cache-missing-');
   try {
     assert.equal(
       resolveCachedDaemonCodeSignature(path.join(root, 'src', 'daemon.ts'), root),

packages/host-kit/src/code-signature-cache.ts

@@ -6,6 +6,7 @@ import { publishFileSync } from './file.ts';
 import {
   buildDaemonCodeFileLabel,
   formatDaemonCodeSignature,
+  resolveDaemonCodePath,
   walkDaemonCodeGraph,
   type DaemonCodeFileStamp,
   type DaemonCodeGraphWalk,
@@ -57,14 +58,18 @@ type CacheDocument = {
  * toolchain cache: failing to read or write one only costs the walk.
  */
 export function resolveCachedDaemonCodeSignature(entryPath: string, root: string): string {
-  const cachePath = resolveCachePath(entryPath, root);
-  const entryLabel = buildDaemonCodeFileLabel(root, entryPath);
-  const validated = readValidatedWalk(cachePath, root, entryLabel);
+  // The walk names every file from the resolved root down, so a document is
+  // read and written under those same names or its entry never matches.
+  const realRoot = resolveDaemonCodePath(root);
+  const realEntryPath = resolveDaemonCodePath(entryPath);
+  const cachePath = resolveCachePath(realEntryPath, realRoot);
+  const entryLabel = buildDaemonCodeFileLabel(realRoot, realEntryPath);
+  const validated = readValidatedWalk(cachePath, realRoot, entryLabel);
   if (validated) return formatDaemonCodeSignature(validated.files);
 
   let walk: DaemonCodeGraphWalk;
   try {
-    walk = walkDaemonCodeGraph(entryPath, root);
+    walk = walkDaemonCodeGraph(realEntryPath, realRoot);
   } catch {
     return 'unknown';
   }
@@ -195,21 +200,13 @@ function publishWalk(cachePath: string, walk: DaemonCodeGraphWalk): void {
   }
 }
 
-/** One document per (entry, root) pair, so sibling checkouts never share one. */
+/**
+ * One document per (entry, root) pair, so sibling checkouts never share one.
+ * Both arrive resolved, so symlinked routes to one checkout are one checkout,
+ * as in `buildSourceCheckoutStateDirName`.
+ */
 function resolveCachePath(entryPath: string, root: string): string {
-  const key = crypto
-    .createHash('sha1')
-    .update(`${resolveRealPath(root)} ${resolveRealPath(entryPath)}`)
-    .digest('hex');
+  const key = crypto.createHash('sha1').update(`${root} ${entryPath}`).digest('hex');
   const directory = `${CACHE_DIRECTORY_PREFIX}-${process.getuid?.() ?? 'user'}`;
   return path.join(os.tmpdir(), directory, `${key}.json`);
 }
-
-/** Symlinked paths to one checkout are one checkout, as in `buildSourceCheckoutStateDirName`. */
-function resolveRealPath(filePath: string): string {
-  try {
-    return fs.realpathSync.native(filePath);
-  } catch {
-    return path.resolve(filePath);
-  }
-}

packages/host-kit/src/code-signature.fixtures.ts

@@ -2,6 +2,18 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { mkdtempForTestSync } from './internal/tmp-dir.fixtures.ts';
 
+/**
+ * A temporary checkout root named the way a real one is: with its symlinks
+ * resolved. A production root comes from `import.meta.url`, which the loader
+ * resolved before the walk ever sees it. On macOS `os.tmpdir()` is `/tmp`,
+ * itself a link to `/private/tmp`, so an unresolved fixture root would be a
+ * shape no caller passes — and the shape every fixture passed. Naming a root
+ * through a link is covered on purpose instead, by its own test.
+ */
+export function createCheckoutRootForTest(prefix: string): string {
+  return fs.realpathSync.native(mkdtempForTestSync(prefix));
+}
+
 /**
  * A source checkout that imports its own implementation the way this one does:
  * an entry under `src/`, a workspace package under `packages/`, and the
@@ -16,7 +28,7 @@ export function writeWorkspaceFixture(prefix: string): {
   manifestPath: string;
   ownedPath: string;
 } {
-  const root = mkdtempForTestSync(prefix);
+  const root = createCheckoutRootForTest(prefix);
   const entryPath = path.join(root, 'src', 'daemon.ts');
   const packageDir = path.join(root, 'packages', 'kit');
   const ownedPath = path.join(packageDir, 'src', 'owned.ts');
@@ -40,3 +52,28 @@ export function writeWorkspaceFixture(prefix: string): {
   fs.symlinkSync(packageDir, path.join(linkDir, 'kit'), 'dir');
   return { root, entryPath, packageDir, manifestPath, ownedPath };
 }
+
+/**
+ * A checkout whose `@scope/vendor` is installed rather than linked: the
+ * package directory is written inside `node_modules` in place, which is the
+ * whole difference the walk keys the two cases on.
+ */
+export function writeInstalledDependencyFixture(prefix: string): {
+  root: string;
+  entryPath: string;
+} {
+  const root = createCheckoutRootForTest(prefix);
+  const entryPath = path.join(root, 'src', 'daemon.ts');
+  const packageDir = path.join(root, 'node_modules', '@scope', 'vendor');
+
+  fs.mkdirSync(path.dirname(entryPath), { recursive: true });
+  fs.mkdirSync(path.join(packageDir, 'src'), { recursive: true });
+  fs.writeFileSync(entryPath, "import '@scope/vendor/thing';\n", 'utf8');
+  fs.writeFileSync(path.join(packageDir, 'src', 'thing.js'), 'export const thing = 1;\n', 'utf8');
+  fs.writeFileSync(
+    path.join(packageDir, 'package.json'),
+    JSON.stringify({ name: '@scope/vendor', exports: { './thing': './src/thing.js' } }),
+    'utf8',
+  );
+  return { root, entryPath };
+}

packages/host-kit/src/code-signature.test.ts

@@ -3,13 +3,27 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { test } from 'vitest';
 import { computeDaemonCodeSignature, walkDaemonCodeGraph } from './code-signature.ts';
-import { writeWorkspaceFixture } from './code-signature.fixtures.ts';
-import { mkdtempForTestSync } from './internal/tmp-dir.fixtures.ts';
+import {
+  createCheckoutRootForTest,
+  writeInstalledDependencyFixture,
+  writeWorkspaceFixture,
+} from './code-signature.fixtures.ts';
 
 function labelsOf(entryPath: string, root: string): string[] {
   return walkDaemonCodeGraph(entryPath, root).files.map(([label]) => label);
 }
 
+/**
+ * The same checkout named through a symlink, which is how a real one is
+ * routinely named: macOS resolves `/tmp` to `/private/tmp`, and a checkout
+ * under a symlinked parent directory reaches every file the same way.
+ */
+function linkTo(root: string): string {
+  const linkPath = `${root}-link`;
+  fs.symlinkSync(root, linkPath, 'dir');
+  return linkPath;
+}
+
 test('a workspace subpath is walked, and its file is stamped under the package path', () => {
   const { root, entryPath } = writeWorkspaceFixture('agent-device-signature-workspace-');
   try {
@@ -60,28 +74,56 @@ test('retargeting the exports map moves the edge without either endpoint changin
 });
 
 test('an installed dependency is not followed into', () => {
-  const root = mkdtempForTestSync('agent-device-signature-installed-');
+  const { root, entryPath } = writeInstalledDependencyFixture('agent-device-signature-installed-');
   try {
-    const entryPath = path.join(root, 'src', 'daemon.ts');
-    const packageDir = path.join(root, 'node_modules', '@scope', 'vendor');
-    fs.mkdirSync(path.dirname(entryPath), { recursive: true });
-    fs.mkdirSync(path.join(packageDir, 'src'), { recursive: true });
-    fs.writeFileSync(entryPath, "import '@scope/vendor/thing';\n", 'utf8');
-    fs.writeFileSync(path.join(packageDir, 'src', 'thing.js'), 'export const thing = 1;\n', 'utf8');
-    fs.writeFileSync(
-      path.join(packageDir, 'package.json'),
-      JSON.stringify({ name: '@scope/vendor', exports: { './thing': './src/thing.js' } }),
-      'utf8',
-    );
-
     assert.deepEqual(labelsOf(entryPath, root), ['src/daemon.ts']);
   } finally {
     fs.rmSync(root, { recursive: true, force: true });
   }
 });
 
+/**
+ * A root named through a symlink is the same root, and every label is still
+ * repository-relative. Resolving the manifests but not the root would put the
+ * two on either side of the link, so a workspace package would be labelled by
+ * the route out of the repository and back in.
+ */
+test('a checkout named through a symlink stamps the same repository-relative labels', () => {
+  const { root } = writeWorkspaceFixture('agent-device-signature-linked-workspace-');
+  const linkedRoot = linkTo(root);
+  try {
+    assert.deepEqual(labelsOf(path.join(linkedRoot, 'src', 'daemon.ts'), linkedRoot).sort(), [
+      'packages/kit/package.json',
+      'packages/kit/src/owned.ts',
+      'src/daemon.ts',
+    ]);
+  } finally {
+    fs.rmSync(linkedRoot, { force: true });
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+/**
+ * The workspace/installed test is `node_modules` containment, so it answers
+ * only while the root and the manifest are named the same way. Under an
+ * unresolved root every installed dependency reads as a workspace package and
+ * the walk follows its whole closure.
+ */
+test('an installed dependency is not followed into through a symlinked root', () => {
+  const { root } = writeInstalledDependencyFixture('agent-device-signature-linked-installed-');
+  const linkedRoot = linkTo(root);
+  try {
+    assert.deepEqual(labelsOf(path.join(linkedRoot, 'src', 'daemon.ts'), linkedRoot), [
+      'src/daemon.ts',
+    ]);
+  } finally {
+    fs.rmSync(linkedRoot, { force: true });
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test('a workspace package linked after the walk is an absent path, not a silent miss', () => {
-  const root = mkdtempForTestSync('agent-device-signature-absent-');
+  const root = createCheckoutRootForTest('agent-device-signature-absent-');
   try {
     const entryPath = path.join(root, 'src', 'daemon.ts');
     fs.mkdirSync(path.dirname(entryPath), { recursive: true });

packages/host-kit/src/code-signature.ts

@@ -87,8 +87,8 @@ export function computeDaemonCodeSignature(
  * format guard relies on being inside the graph it walks.
  */
 export function walkDaemonCodeGraph(entryPath: string, root: string): DaemonCodeGraphWalk {
-  const normalizedRoot = path.resolve(root);
-  const queue = [path.resolve(entryPath)];
+  const normalizedRoot = resolveDaemonCodePath(root);
+  const queue = [resolveDaemonCodePath(entryPath)];
   const visited = new Set<string>();
   const files: DaemonCodeFileStamp[] = [];
   const absentPaths = new Set<string>();
@@ -176,6 +176,26 @@ export function buildDaemonCodeFileLabel(root: string, filePath: string): string
   return path.relative(path.resolve(root), resolvedPath) || resolvedPath;
 }
 
+/**
+ * A path with its symlinks resolved, falling back to a plain resolve for a
+ * path that names nothing yet.
+ *
+ * Every root, entry, and manifest a walk compares or labels goes through here,
+ * so all of them name a file the same way. Two spellings of one path is not a
+ * cosmetic difference: under a symlinked prefix — macOS `/tmp`, a symlinked
+ * checkout — a root left unresolved sits outside the resolved tree beneath it,
+ * so `buildDaemonCodeFileLabel` walks back out of the repository instead of
+ * naming `packages/kit/...` and `isInstalledDependencyPath` reads every
+ * installed dependency as a workspace package and walks its whole closure.
+ */
+export function resolveDaemonCodePath(filePath: string): string {
+  try {
+    return fs.realpathSync.native(filePath);
+  } catch {
+    return path.resolve(filePath);
+  }
+}
+
 /** The wire form of a signature; identical for a walked and a cache-validated stamp list. */
 export function formatDaemonCodeSignature(stamps: readonly DaemonCodeFileStamp[]): string {
   const fingerprint = stamps
@@ -244,7 +264,9 @@ function readWorkspacePackage(
     absentPaths.add(buildDaemonCodeFileLabel(root, linkedManifestPath));
     return null;
   }
-  const manifestPath = realManifestPath(linkedManifestPath);
+  // Both routes to the manifest name the same inode, so stamping it under the
+  // package's own path keeps one label per file rather than one per route.
+  const manifestPath = resolveDaemonCodePath(linkedManifestPath);
   if (isInstalledDependencyPath(root, manifestPath)) return null;
   try {
     return { manifestPath, manifest: JSON.parse(fs.readFileSync(manifestPath, 'utf8')) };
@@ -253,19 +275,6 @@ function readWorkspacePackage(
   }
 }
 
-/**
- * The manifest's own path, so a package reached through its workspace link is
- * stamped under one label. Both routes name the same inode, so either would
- * revalidate; two labels for one file would just inflate every document.
- */
-function realManifestPath(manifestPath: string): string {
-  try {
-    return fs.realpathSync.native(manifestPath);
-  } catch {
-    return manifestPath;
-  }
-}
-
 function isInstalledDependencyPath(root: string, filePath: string): boolean {
   const relative = path.relative(path.join(root, 'node_modules'), filePath);
   return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);