@baique/pi-web-sky 0.1.35 → 0.1.37

package/lib/process-lifecycle.test.mjs

@@ -0,0 +1,83 @@
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import test from "node:test";
+import { setTimeout as delay } from "node:timers/promises";
+
+import { wireChildProcessLifecycle } from "../bin/process-lifecycle.js";
+
+function createProcesses() {
+  const parent = new EventEmitter();
+  const child = new EventEmitter();
+  const forwardedSignals = [];
+  const exitCodes = [];
+
+  child.kill = (signal) => {
+    forwardedSignals.push(signal);
+    return true;
+  };
+  parent.exit = (code) => {
+    exitCodes.push(code);
+  };
+
+  return { parent, child, forwardedSignals, exitCodes };
+}
+
+test("forwards the first shutdown signal and force-kills on repeated signals", () => {
+  const { parent, child, forwardedSignals } = createProcesses();
+
+  wireChildProcessLifecycle(child, parent);
+  parent.emit("SIGTERM");
+  parent.emit("SIGTERM");
+  parent.emit("SIGINT");
+
+  assert.deepEqual(forwardedSignals, ["SIGTERM", "SIGKILL", "SIGKILL"]);
+  child.emit("exit", null, "SIGKILL");
+});
+
+test("propagates a child exit code and clears its shutdown wiring", async () => {
+  const { parent, child, forwardedSignals, exitCodes } = createProcesses();
+  const existingSigtermListener = () => {};
+  parent.on("SIGTERM", existingSigtermListener);
+
+  wireChildProcessLifecycle(child, parent, 10);
+  assert.equal(parent.listenerCount("SIGINT"), 1);
+  assert.equal(parent.listenerCount("SIGTERM"), 2);
+
+  parent.emit("SIGTERM");
+  child.emit("exit", 23, null);
+  await delay(20);
+
+  assert.deepEqual(exitCodes, [23]);
+  assert.equal(parent.listenerCount("SIGINT"), 0);
+  assert.deepEqual(parent.listeners("SIGTERM"), [existingSigtermListener]);
+
+  parent.emit("SIGTERM");
+  assert.deepEqual(forwardedSignals, ["SIGTERM"]);
+});
+
+test("force-kills the child when graceful shutdown times out", async () => {
+  const { parent, child, forwardedSignals } = createProcesses();
+
+  wireChildProcessLifecycle(child, parent, 10);
+  parent.emit("SIGINT");
+  assert.deepEqual(forwardedSignals, ["SIGINT"]);
+
+  await delay(20);
+
+  assert.deepEqual(forwardedSignals, ["SIGINT", "SIGKILL"]);
+  child.emit("exit", null, "SIGKILL");
+});
+
+test("uses conventional exit statuses for known child signals", () => {
+  for (const [signal, expectedExitCode] of [
+    ["SIGTERM", 143],
+    ["SIGKILL", 137],
+  ]) {
+    const { parent, child, exitCodes } = createProcesses();
+
+    wireChildProcessLifecycle(child, parent);
+    child.emit("exit", null, signal);
+
+    assert.deepEqual(exitCodes, [expectedExitCode]);
+  }
+});

package/lib/project-command-env.test.mjs

@@ -0,0 +1,298 @@
+import assert from "node:assert/strict";
+import { delimiter, join } from "node:path";
+import test from "node:test";
+import {
+  DefaultResourceLoader,
+  createLocalBashOperations,
+  getAgentDir,
+} from "@earendil-works/pi-coding-agent";
+import { createJiti } from "jiti";
+
+const {
+  createProjectCommandBashExtension,
+  createProjectCommandBashOperations,
+  preferUserBashExtension,
+  sanitizeProjectCommandEnvironment,
+} = await createJiti(import.meta.url).import("./project-command-env.ts");
+
+const HOST_ENVIRONMENT = {
+  PORT: "30141",
+  NODE_ENV: "production",
+  NEXT_RUNTIME: "nodejs",
+  NEXT_PRIVATE_WORKER: "1",
+  PATH: "/usr/local/bin:/usr/bin",
+  HOME: "/home/pi",
+  HTTPS_PROXY: "http://proxy.example",
+  OPENROUTER_API_KEY: "secret",
+  PI_USER_SETTING: "preserved",
+};
+
+test("sanitizes host variables using platform casing rules", () => {
+  assert.deepEqual(
+    sanitizeProjectCommandEnvironment(HOST_ENVIRONMENT, "linux"),
+    {
+      PATH: HOST_ENVIRONMENT.PATH,
+      HOME: HOST_ENVIRONMENT.HOME,
+      HTTPS_PROXY: HOST_ENVIRONMENT.HTTPS_PROXY,
+      OPENROUTER_API_KEY: HOST_ENVIRONMENT.OPENROUTER_API_KEY,
+      PI_USER_SETTING: HOST_ENVIRONMENT.PI_USER_SETTING,
+    },
+  );
+  assert.deepEqual(
+    sanitizeProjectCommandEnvironment(
+      {
+        Port: "30141",
+        node_env: "production",
+        Next_Runtime: "nodejs",
+        NEXT_PUBLIC_FLAG: "1",
+        Path: "C:\\Windows",
+      },
+      "win32",
+    ),
+    { Path: "C:\\Windows" },
+  );
+  assert.deepEqual(
+    sanitizeProjectCommandEnvironment(
+      {
+        PORT: "30141",
+        Port: "project-value",
+        NODE_ENV: "production",
+        node_env: "project-mode",
+        NEXT_RUNTIME: "nodejs",
+        Next_Runtime: "project-runtime",
+      },
+      "linux",
+    ),
+    {
+      Port: "project-value",
+      node_env: "project-mode",
+      Next_Runtime: "project-runtime",
+    },
+  );
+});
+
+test("agent bash removes host variables while preserving SDK and user environment", async () => {
+  const original = {
+    PORT: process.env.PORT,
+    NODE_ENV: process.env.NODE_ENV,
+    NEXT_RUNTIME: process.env.NEXT_RUNTIME,
+    NEXT_PRIVATE_WORKER: process.env.NEXT_PRIVATE_WORKER,
+    PI_USER_SETTING: process.env.PI_USER_SETTING,
+  };
+  Object.assign(process.env, {
+    PORT: "30141",
+    NODE_ENV: "production",
+    NEXT_RUNTIME: "nodejs",
+    NEXT_PRIVATE_WORKER: "1",
+    PI_USER_SETTING: "preserved",
+  });
+
+  try {
+    const extension = createProjectCommandBashExtension({
+      cwd: process.cwd(),
+      settings: {
+        getShellCommandPrefix: () => undefined,
+        getShellPath: () => undefined,
+      },
+    });
+    let registeredTool;
+    await extension.factory({
+      registerTool(tool) {
+        registeredTool = tool;
+      },
+    });
+
+    const result = await registeredTool.execute(
+      "issue-484",
+      {
+        command: `node -e 'console.log(JSON.stringify({PORT:process.env.PORT,NODE_ENV:process.env.NODE_ENV,NEXT_RUNTIME:process.env.NEXT_RUNTIME,NEXT_PRIVATE_WORKER:process.env.NEXT_PRIVATE_WORKER,PI_USER_SETTING:process.env.PI_USER_SETTING,PI_SESSION_ID:process.env.PI_SESSION_ID,PATH:process.env.PATH}))'`,
+      },
+      undefined,
+      undefined,
+      {
+        model: undefined,
+        thinkingLevel: "off",
+        sessionManager: {
+          getSessionId: () => "session-484",
+          getSessionFile: () => undefined,
+        },
+      },
+    );
+    const childEnvironment = JSON.parse(result.content[0].text);
+
+    assert.equal(childEnvironment.PORT, undefined);
+    assert.equal(childEnvironment.NODE_ENV, undefined);
+    assert.equal(childEnvironment.NEXT_RUNTIME, undefined);
+    assert.equal(childEnvironment.NEXT_PRIVATE_WORKER, undefined);
+    assert.equal(childEnvironment.PI_USER_SETTING, "preserved");
+    assert.equal(childEnvironment.PI_SESSION_ID, "session-484");
+    assert.ok(childEnvironment.PATH.split(delimiter).includes(join(getAgentDir(), "bin")));
+  } finally {
+    for (const [name, value] of Object.entries(original)) {
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+  }
+});
+
+test("agent bash reads current shell settings for every execution", async () => {
+  let commandPrefix = "export PI_WEB_PREFIX=first";
+  const extension = createProjectCommandBashExtension({
+    cwd: process.cwd(),
+    settings: {
+      getShellCommandPrefix: () => commandPrefix,
+      getShellPath: () => undefined,
+    },
+  });
+  let registeredTool;
+  await extension.factory({
+    registerTool(tool) {
+      registeredTool = tool;
+    },
+  });
+  const execute = () => registeredTool.execute(
+    "settings-reload",
+    { command: "printf %s \"$PI_WEB_PREFIX\"" },
+    undefined,
+    undefined,
+    undefined,
+  );
+
+  assert.equal((await execute()).content[0].text, "first");
+  commandPrefix = "export PI_WEB_PREFIX=second";
+  assert.equal((await execute()).content[0].text, "second");
+});
+
+test("direct bash removes host variables and allows explicit project values", async () => {
+  const agentBinDir = join(process.cwd(), ".test-agent", "bin");
+  const operations = createProjectCommandBashOperations({
+    agentBinDir,
+    baseEnvironment: {
+      ...HOST_ENVIRONMENT,
+      PATH: process.env.PATH,
+      PI_SESSION_ID: "stale-host-value",
+    },
+    localOperations: createLocalBashOperations(),
+  });
+  let output = "";
+
+  await operations.exec(
+    `NODE_ENV=test PORT=3200 node -e 'console.log(JSON.stringify({PORT:process.env.PORT,NODE_ENV:process.env.NODE_ENV,NEXT_RUNTIME:process.env.NEXT_RUNTIME,PI_USER_SETTING:process.env.PI_USER_SETTING,PATH:process.env.PATH}))'`,
+    process.cwd(),
+    { onData: (chunk) => { output += chunk.toString(); } },
+  );
+  const childEnvironment = JSON.parse(output);
+
+  assert.equal(childEnvironment.PORT, "3200");
+  assert.equal(childEnvironment.NODE_ENV, "test");
+  assert.equal(childEnvironment.NEXT_RUNTIME, undefined);
+  assert.equal(childEnvironment.PI_USER_SETTING, "preserved");
+  assert.ok(childEnvironment.PATH.split(delimiter).includes(agentBinDir));
+});
+
+test("direct bash preserves execution controls and streaming callbacks", async () => {
+  const signal = new AbortController().signal;
+  let received;
+  let streamed = "";
+  const operations = createProjectCommandBashOperations({
+    baseEnvironment: HOST_ENVIRONMENT,
+    localOperations: {
+      async exec(command, cwd, options) {
+        received = { command, cwd, options };
+        options.onData(Buffer.from("streamed"));
+        return { exitCode: 0 };
+      },
+    },
+  });
+
+  await operations.exec("echo ready", "/project", {
+    onData: (chunk) => { streamed += chunk.toString(); },
+    signal,
+    timeout: 12,
+  });
+
+  assert.equal(received.command, "echo ready");
+  assert.equal(received.cwd, "/project");
+  assert.equal(received.options.signal, signal);
+  assert.equal(received.options.timeout, 12);
+  assert.equal(streamed, "streamed");
+});
+
+async function captureOperationEnvironment(options) {
+  let environment;
+  const operations = createProjectCommandBashOperations({
+    ...options,
+    localOperations: {
+      async exec(_command, _cwd, executionOptions) {
+        environment = executionOptions.env;
+        return { exitCode: 0 };
+      },
+    },
+  });
+  await operations.exec("echo ready", "/project", {
+    onData() {},
+  });
+  return environment;
+}
+
+test("direct bash updates the platform PATH key", async () => {
+  const agentBinDir = join(process.cwd(), ".test-agent", "bin");
+  const cases = [
+    {
+      options: { agentBinDir, baseEnvironment: { Path: "project-metadata", PATH: "/usr/bin" }, platform: "linux" },
+      expected: { Path: "project-metadata", PATH: `${agentBinDir}${delimiter}/usr/bin` },
+    },
+    {
+      options: { agentBinDir: "C:\\pi-agent\\bin", baseEnvironment: { Path: "C:\\Windows" }, platform: "win32" },
+      expected: { Path: "C:\\pi-agent\\bin;C:\\Windows" },
+    },
+  ];
+
+  for (const { options, expected } of cases) {
+    assert.deepEqual(await captureOperationEnvironment(options), expected);
+  }
+});
+
+test("a user extension keeps priority over the Pi Web fallback bash tool", async () => {
+  const userBash = {
+    name: "user-bash",
+    factory: (pi) => {
+      pi.registerTool({
+        name: "bash",
+        label: "user bash",
+        description: "user override",
+        parameters: { type: "object", properties: {} },
+        async execute() {
+          return { content: [{ type: "text", text: "user override" }], details: undefined };
+        },
+      });
+    },
+  };
+  const hostBash = createProjectCommandBashExtension({
+    cwd: process.cwd(),
+    settings: {
+      getShellCommandPrefix: () => undefined,
+      getShellPath: () => undefined,
+    },
+  });
+  const loader = new DefaultResourceLoader({
+    cwd: process.cwd(),
+    agentDir: join(process.cwd(), ".test-agent"),
+    extensionFactories: [userBash, hostBash],
+    noExtensions: true,
+    noSkills: true,
+    noPromptTemplates: true,
+    noThemes: true,
+    noContextFiles: true,
+    extensionsOverride: (base) => preferUserBashExtension(base),
+  });
+  await loader.reload();
+  const extensions = loader.getExtensions();
+  const bashDefinitions = extensions.extensions
+    .map((extension) => extension.tools.get("bash")?.definition)
+    .filter(Boolean);
+
+  assert.equal(bashDefinitions.length, 1);
+  assert.equal(bashDefinitions[0].description, "user override");
+  assert.deepEqual(extensions.errors, []);
+});

package/lib/project-command-env.ts

@@ -0,0 +1,129 @@
+import {
+  createBashToolDefinition,
+  createLocalBashOperations,
+  getAgentDir,
+  type BashOperations,
+  type InlineExtension,
+  type LoadExtensionsResult,
+} from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+
+const HOST_EXTENSION_NAME = "pi-web-project-command-environment";
+const HOST_EXTENSION_PATH = `<inline:${HOST_EXTENSION_NAME}>`;
+
+type ProjectShellSettings = {
+  getShellCommandPrefix(): string | undefined;
+  getShellPath(): string | undefined;
+};
+
+type ProjectCommandBashOperationsOptions = {
+  agentBinDir?: string;
+  baseEnvironment?: NodeJS.ProcessEnv;
+  localOperations?: BashOperations;
+  platform?: NodeJS.Platform;
+  shellPath?: string;
+};
+
+function isHostRuntimeVariable(name: string, platform: NodeJS.Platform): boolean {
+  const comparableName = platform === "win32" ? name.toUpperCase() : name;
+  return comparableName === "PORT"
+    || comparableName === "NODE_ENV"
+    || comparableName.startsWith("NEXT_");
+}
+
+export function sanitizeProjectCommandEnvironment(
+  baseEnvironment: NodeJS.ProcessEnv,
+  platform: NodeJS.Platform = process.platform,
+): NodeJS.ProcessEnv {
+  const environment = { ...baseEnvironment };
+  for (const name of Object.keys(environment)) {
+    if (isHostRuntimeVariable(name, platform)) delete environment[name];
+  }
+  return environment;
+}
+
+function withAgentBinDirectory(
+  environment: NodeJS.ProcessEnv,
+  agentBinDir: string,
+  platform: NodeJS.Platform,
+): NodeJS.ProcessEnv {
+  const pathKey = platform === "win32"
+    ? Object.keys(environment).find((name) => name.toUpperCase() === "PATH") ?? "PATH"
+    : "PATH";
+  const pathDelimiter = platform === "win32" ? ";" : ":";
+  const currentPath = environment[pathKey] ?? "";
+  const pathEntries = currentPath.split(pathDelimiter).filter(Boolean);
+  if (!pathEntries.includes(agentBinDir)) {
+    environment[pathKey] = [agentBinDir, currentPath].filter(Boolean).join(pathDelimiter);
+  }
+  return environment;
+}
+
+export function createProjectCommandBashOperations(
+  options: ProjectCommandBashOperationsOptions = {},
+): BashOperations {
+  const {
+    agentBinDir = join(getAgentDir(), "bin"),
+    baseEnvironment = process.env,
+    localOperations = createLocalBashOperations({ shellPath: options.shellPath }),
+    platform = process.platform,
+  } = options;
+
+  return {
+    exec(command, cwd, executionOptions) {
+      const environment = withAgentBinDirectory(
+        sanitizeProjectCommandEnvironment(executionOptions.env ?? baseEnvironment, platform),
+        agentBinDir,
+        platform,
+      );
+      return localOperations.exec(command, cwd, {
+        ...executionOptions,
+        env: environment,
+      });
+    },
+  };
+}
+
+export function createProjectCommandBashExtension(options: {
+  cwd: string;
+  settings: ProjectShellSettings;
+}): InlineExtension {
+  return {
+    name: HOST_EXTENSION_NAME,
+    hidden: true,
+    factory: (pi) => {
+      const displayDefinition = createBashToolDefinition(options.cwd);
+      pi.registerTool({
+        ...displayDefinition,
+        execute(toolCallId, params, signal, onUpdate, context) {
+          const executionDefinition = createBashToolDefinition(options.cwd, {
+            commandPrefix: options.settings.getShellCommandPrefix(),
+            operations: createProjectCommandBashOperations({
+              shellPath: options.settings.getShellPath(),
+            }),
+          });
+          return executionDefinition.execute(toolCallId, params, signal, onUpdate, context);
+        },
+      });
+    },
+  };
+}
+
+export function preferUserBashExtension(base: LoadExtensionsResult): LoadExtensionsResult {
+  const hostExtensionIndex = base.extensions.findIndex((extension) => extension.path === HOST_EXTENSION_PATH);
+  if (hostExtensionIndex < 0) return base;
+
+  const userBashOwner = base.extensions
+    .slice(0, hostExtensionIndex)
+    .find((extension) => extension.tools.has("bash"));
+  if (!userBashOwner) return base;
+
+  return {
+    ...base,
+    extensions: base.extensions.filter((_, index) => index !== hostExtensionIndex),
+    errors: base.errors.filter((error) => !(
+      error.path === HOST_EXTENSION_PATH
+      && error.error === `Tool "bash" conflicts with ${userBashOwner.path}`
+    )),
+  };
+}

package/lib/project-groups.test.mjs

@@ -0,0 +1,60 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createJiti } from "jiti";
+
+const jiti = createJiti(import.meta.url);
+const { projectIdentityKey } = await jiti.import("./project-identity.ts");
+const {
+  getProjectActivity,
+  getRecentProjects,
+  sessionsForProject,
+} = await jiti.import("./project-groups.ts");
+
+function session(id, projectRoot, modified) {
+  return {
+    id,
+    path: `${id}.jsonl`,
+    cwd: projectRoot,
+    projectRoot,
+    projectKey: projectIdentityKey(projectRoot, "win32"),
+    created: modified,
+    modified,
+    messageCount: 1,
+    firstMessage: id,
+  };
+}
+
+test("Windows path variants form one recent project using the newest display path", () => {
+  const older = session("older", "C:\\Users\\Alex\\Project\\Study\\ELM", "2026-08-12T00:00:00.000Z");
+  const newer = session("newer", "c:/users/ALEX/project/study/elm", "2026-08-13T00:00:00.000Z");
+
+  assert.deepEqual(getRecentProjects([older, newer]), [{
+    key: older.projectKey,
+    root: newer.projectRoot,
+  }]);
+});
+
+test("project filtering includes every session with the stable identity", () => {
+  const first = session("first", "C:\\Users\\Alex\\Project", "2026-08-12T00:00:00.000Z");
+  const second = session("second", "c:/users/alex/project/", "2026-08-13T00:00:00.000Z");
+  const other = session("other", "D:\\Elsewhere", "2026-08-13T01:00:00.000Z");
+
+  assert.deepEqual(
+    sessionsForProject([first, second, other], first.projectKey).map((item) => item.id),
+    ["first", "second"],
+  );
+});
+
+test("running and unread counts aggregate under the stable project identity", () => {
+  const first = session("first", "C:\\Users\\Alex\\Project", "2026-08-12T00:00:00.000Z");
+  const second = session("second", "c:/users/alex/project/", "2026-08-13T00:00:00.000Z");
+
+  const activity = getProjectActivity(
+    [first, second],
+    new Set(["first", "second"]),
+    new Set(["second"]),
+  );
+
+  assert.deepEqual(activity.get(first.projectKey), { running: 2, unread: 1 });
+  assert.equal(activity.size, 1);
+});

package/lib/project-groups.ts

@@ -0,0 +1,53 @@
+import type { SessionInfo } from "./types";
+import { workspaceKeyOf } from "./workspace-memory";
+
+export interface RecentProject {
+  /** Stable server-provided identity used for comparison and Map keys. */
+  key: string;
+  /** Original project path used for display and filesystem operations. */
+  root: string;
+}
+
+/** Projects sorted by most recent activity and deduplicated by stable key. */
+export function getRecentProjects(sessions: readonly SessionInfo[]): RecentProject[] {
+  const latestByProject = new Map<string, { root: string; modified: string }>();
+  for (const session of sessions) {
+    const root = session.projectRoot ?? session.cwd;
+    if (!root) continue;
+    const key = workspaceKeyOf(session);
+    const previous = latestByProject.get(key);
+    if (!previous || session.modified > previous.modified) {
+      latestByProject.set(key, { root, modified: session.modified });
+    }
+  }
+  return [...latestByProject.entries()]
+    .sort((a, b) => b[1].modified.localeCompare(a[1].modified))
+    .map(([key, { root }]) => ({ key, root }));
+}
+
+export function getProjectActivity(
+  sessions: readonly SessionInfo[],
+  runningSessionIds: ReadonlySet<string>,
+  unreadSessionIds: ReadonlySet<string>,
+): Map<string, { running: number; unread: number }> {
+  const counts = new Map<string, { running: number; unread: number }>();
+  for (const session of sessions) {
+    const key = workspaceKeyOf(session);
+    if (!key) continue;
+    let entry = counts.get(key);
+    if (!entry) {
+      entry = { running: 0, unread: 0 };
+      counts.set(key, entry);
+    }
+    if (runningSessionIds.has(session.id)) entry.running++;
+    if (unreadSessionIds.has(session.id)) entry.unread++;
+  }
+  return counts;
+}
+
+export function sessionsForProject(
+  sessions: readonly SessionInfo[],
+  projectKey: string,
+): SessionInfo[] {
+  return sessions.filter((session) => workspaceKeyOf(session) === projectKey);
+}

package/lib/project-identity.test.mjs

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+async function loadSubject() {
+  const { createJiti } = await import("jiti");
+  return createJiti(import.meta.url).import("./project-identity.ts");
+}
+
+test("Windows project identity ignores full-path casing and separator style", async () => {
+  const { projectIdentityKey } = await loadSubject();
+
+  const expected = projectIdentityKey("C:\\Users\\Alex\\Project\\Study\\ELM", "win32");
+  assert.equal(projectIdentityKey("c:/users/ALEX/project/study/elm", "win32"), expected);
+  assert.equal(projectIdentityKey("c:\\Users\\Alex\\Project\\Study\\.\\ELM\\", "win32"), expected);
+});
+
+test("Windows project identity handles UNC casing and separators", async () => {
+  const { projectIdentityKey } = await loadSubject();
+
+  assert.equal(
+    projectIdentityKey("\\\\Server\\Share\\Team\\Agent", "win32"),
+    projectIdentityKey("//server/share/team/AGENT/", "win32"),
+  );
+});
+
+test("project identity preserves case on case-sensitive platforms", async () => {
+  const { projectIdentityKey } = await loadSubject();
+
+  assert.notEqual(
+    projectIdentityKey("/Users/Alex/Project", "linux"),
+    projectIdentityKey("/users/alex/project", "linux"),
+  );
+  assert.notEqual(
+    projectIdentityKey("/a\\b", "linux"),
+    projectIdentityKey("/a/b", "linux"),
+  );
+});

package/lib/project-identity.ts

@@ -0,0 +1,26 @@
+import path from "node:path";
+
+/**
+ * Stable, internal identity for a project path.
+ *
+ * Keep the original cwd/projectRoot for display and filesystem operations.
+ * This key is only for grouping and equality: Windows paths are normalized
+ * with win32 rules and case-folded because the default Windows filesystem is
+ * case-insensitive. The explicit platform argument keeps those semantics
+ * testable on non-Windows CI.
+ */
+export function projectIdentityKey(
+  projectRoot: string,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  if (!projectRoot) return projectRoot;
+  const pathApi = platform === "win32" ? path.win32 : path.posix;
+  const normalized = pathApi.normalize(projectRoot);
+  const rootLength = pathApi.parse(normalized).root.length;
+  let end = normalized.length;
+  while (end > rootLength && normalized[end - 1] === pathApi.sep) end--;
+  const withoutTrailingSeparators = normalized.slice(0, end);
+  return platform === "win32"
+    ? withoutTrailingSeparators.toLowerCase()
+    : withoutTrailingSeparators;
+}