@oar-sh/oar 0.9.0

package/server/services/usage-snapshot-helpers.mjs

@@ -0,0 +1,209 @@
+'use strict';
+
+export function safeUsageNumber(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : null;
+}
+
+export function computeUsedPercent(remaining, entitlement, percentRemaining) {
+  const explicitRemainingPct = safeUsageNumber(percentRemaining);
+  if (explicitRemainingPct != null) return Math.max(0, Math.min(100, 100 - explicitRemainingPct));
+  const rem = safeUsageNumber(remaining);
+  const ent = safeUsageNumber(entitlement);
+  if (rem == null || ent == null || ent <= 0) return null;
+  return Math.max(0, Math.min(100, ((ent - rem) / ent) * 100));
+}
+
+export function computePercentRemaining(remaining, entitlement, percentRemaining) {
+  const rem = safeUsageNumber(remaining);
+  const ent = safeUsageNumber(entitlement);
+  const explicit = safeUsageNumber(percentRemaining);
+  if (explicit != null) {
+    // Some API payloads report 0 with no denominator context; treat that as unknown.
+    const hasDenominatorContext = (ent != null && ent > 0) || rem != null;
+    if (!hasDenominatorContext && explicit === 0) return null;
+    return Math.max(0, Math.min(100, explicit));
+  }
+  if (rem == null || ent == null || ent <= 0) return null;
+  return Math.max(0, Math.min(100, (rem / ent) * 100));
+}
+
+export function computeDeltaMonthlyPercent(currentBucket = {}, previousBucket = {}) {
+  const currentUsed = safeUsageNumber(currentBucket.usedPercent);
+  const previousUsed = safeUsageNumber(previousBucket.usedPercent);
+  if (currentUsed != null && previousUsed != null) {
+    const delta = currentUsed - previousUsed;
+    return Number.isFinite(delta) ? Math.max(0, delta) : null;
+  }
+  const deltaUsed = safeUsageNumber(currentBucket.deltaUsed);
+  const entitlement = safeUsageNumber(currentBucket.entitlement);
+  if (deltaUsed != null && entitlement != null && entitlement > 0) {
+    return Math.max(0, (deltaUsed / entitlement) * 100);
+  }
+  return null;
+}
+
+export function normalizeUsageBucket(bucket = {}, previousBucket = {}) {
+  const remaining = safeUsageNumber(bucket?.remaining);
+  const entitlement = safeUsageNumber(bucket?.entitlement);
+  const usedPercent = computeUsedPercent(remaining, entitlement, bucket?.percentRemaining);
+  const percentRemaining = computePercentRemaining(remaining, entitlement, bucket?.percentRemaining);
+  const previousRemaining = safeUsageNumber(previousBucket?.remaining);
+  const deltaUsed = (remaining != null && previousRemaining != null) ? (previousRemaining - remaining) : null;
+  return { remaining, entitlement, usedPercent, percentRemaining, deltaUsed };
+}
+
+export function usageSnapshotFromSummary(summary = {}, previousSnapshot = null, {
+  source = 'live',
+  stale = false,
+  capturedAt = new Date().toISOString(),
+} = {}) {
+  const previous = previousSnapshot || {};
+  const premiumBase = normalizeUsageBucket(summary?.premiumInteractions || {}, previous.premium || {});
+  const chat = normalizeUsageBucket(summary?.chat || {}, previous.chat || {});
+  const planBase = normalizeUsageBucket(summary?.planQuota || {}, previous.plan || {});
+  const premium = {
+    ...premiumBase,
+    deltaCredits: premiumBase.deltaUsed,
+  };
+  const plan = {
+    ...planBase,
+    deltaMonthlyPercent: computeDeltaMonthlyPercent(planBase, previous.plan || {}),
+  };
+  return {
+    source,
+    stale,
+    capturedAt,
+    premium,
+    chat,
+    plan,
+  };
+}
+
+export function usageSnapshotFromRow(row = null) {
+  if (!row) return null;
+  const premiumRemaining = safeUsageNumber(row.premium_remaining);
+  const premiumEntitlement = safeUsageNumber(row.premium_entitlement);
+  const chatRemaining = safeUsageNumber(row.chat_remaining);
+  const chatEntitlement = safeUsageNumber(row.chat_entitlement);
+  const planRemaining = safeUsageNumber(row.plan_remaining);
+  const planEntitlement = safeUsageNumber(row.plan_entitlement);
+  return {
+    premium: {
+      remaining: premiumRemaining,
+      entitlement: premiumEntitlement,
+      usedPercent: safeUsageNumber(row.premium_used_percent),
+      percentRemaining: computePercentRemaining(premiumRemaining, premiumEntitlement, null),
+    },
+    chat: {
+      remaining: chatRemaining,
+      entitlement: chatEntitlement,
+      usedPercent: safeUsageNumber(row.chat_used_percent),
+      percentRemaining: computePercentRemaining(chatRemaining, chatEntitlement, null),
+    },
+    plan: {
+      remaining: planRemaining,
+      entitlement: planEntitlement,
+      usedPercent: safeUsageNumber(row.plan_used_percent),
+      percentRemaining: computePercentRemaining(planRemaining, planEntitlement, null),
+    },
+  };
+}
+
+export function staleUsageSnapshotFromRow(row = null, {
+  source = 'stale-cache',
+  capturedAt = new Date().toISOString(),
+} = {}) {
+  const previous = usageSnapshotFromRow(row);
+  if (!previous) return null;
+  return {
+    source,
+    stale: true,
+    capturedAt,
+    premium: {
+      remaining: previous.premium.remaining,
+      entitlement: previous.premium.entitlement,
+      usedPercent: computeUsedPercent(previous.premium.remaining, previous.premium.entitlement, null),
+      percentRemaining: computePercentRemaining(previous.premium.remaining, previous.premium.entitlement, null),
+      deltaUsed: null,
+      deltaCredits: null,
+    },
+    chat: {
+      remaining: previous.chat.remaining,
+      entitlement: previous.chat.entitlement,
+      usedPercent: computeUsedPercent(previous.chat.remaining, previous.chat.entitlement, null),
+      percentRemaining: computePercentRemaining(previous.chat.remaining, previous.chat.entitlement, null),
+      deltaUsed: null,
+    },
+    plan: {
+      remaining: previous.plan.remaining,
+      entitlement: previous.plan.entitlement,
+      usedPercent: computeUsedPercent(previous.plan.remaining, previous.plan.entitlement, null),
+      percentRemaining: computePercentRemaining(previous.plan.remaining, previous.plan.entitlement, null),
+      deltaUsed: null,
+      deltaMonthlyPercent: null,
+    },
+  };
+}
+
+export function mapUsageSnapshotRow(row) {
+  if (!row) return null;
+  const premiumRemaining = safeUsageMetric(row.premium_remaining);
+  const premiumEntitlement = safeUsageMetric(row.premium_entitlement);
+  const planRemaining = safeUsageMetric(row.plan_remaining);
+  const planEntitlement = safeUsageMetric(row.plan_entitlement);
+  const planDeltaUsed = safeUsageMetric(row.plan_delta_used);
+  const premiumDeltaUsed = safeUsageMetric(row.premium_delta_used);
+  const planDeltaMonthlyPercent = planDeltaUsed != null && planEntitlement != null && planEntitlement > 0
+    ? Math.max(0, (planDeltaUsed / planEntitlement) * 100)
+    : null;
+  return {
+    source: row.source || 'live',
+    stale: !!row.stale,
+    capturedAt: row.captured_at || null,
+    premium: {
+      remaining: premiumRemaining,
+      entitlement: premiumEntitlement,
+      usedPercent: safeUsageMetric(row.premium_used_percent),
+      percentRemaining: computePercentRemaining(premiumRemaining, premiumEntitlement, null),
+      deltaUsed: premiumDeltaUsed,
+      deltaCredits: premiumDeltaUsed,
+    },
+    chat: {
+      remaining: safeUsageMetric(row.chat_remaining),
+      entitlement: safeUsageMetric(row.chat_entitlement),
+      usedPercent: safeUsageMetric(row.chat_used_percent),
+      percentRemaining: computePercentRemaining(
+        safeUsageMetric(row.chat_remaining),
+        safeUsageMetric(row.chat_entitlement),
+        null,
+      ),
+      deltaUsed: safeUsageMetric(row.chat_delta_used),
+    },
+    plan: {
+      remaining: planRemaining,
+      entitlement: planEntitlement,
+      usedPercent: safeUsageMetric(row.plan_used_percent),
+      percentRemaining: computePercentRemaining(planRemaining, planEntitlement, null),
+      deltaUsed: planDeltaUsed,
+      deltaMonthlyPercent: planDeltaMonthlyPercent,
+    },
+  };
+}
+
+function safeUsageMetric(value) {
+  return safeUsageNumber(value);
+}
+
+export function fetchUsageSummaryPromise(fetchUsageSummary) {
+  return new Promise((resolve, reject) => {
+    fetchUsageSummary((error, summary) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve(summary || {});
+    });
+  });
+}

package/server/services/windows-autostart-service.mjs

@@ -0,0 +1,115 @@
+import fs from 'fs';
+import path from 'path';
+import { randomUUID } from 'crypto';
+
+export const WINDOWS_AUTOSTART_FILENAME = 'copilot-remote-web-relay.cmd';
+
+function escapeBatchValue(value) {
+  return String(value || '').replaceAll('%', '%%');
+}
+
+export function resolveWindowsStartupDirectory(env = process.env, pathImpl = path) {
+  const appData = String(env?.APPDATA || '').trim();
+  if (!appData) {
+    throw new Error('Windows autostart requires the current user APPDATA directory.');
+  }
+  return pathImpl.join(appData, 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Startup');
+}
+
+export function buildWindowsAutostartScript({
+  packageRoot,
+  nodePath = process.execPath,
+  configPath = '',
+  pathImpl = path,
+} = {}) {
+  const resolvedPackageRoot = pathImpl.resolve(String(packageRoot || ''));
+  if (!String(packageRoot || '').trim()) {
+    throw new Error('Windows autostart requires the copilot-remote package root.');
+  }
+  const resolvedNodePath = pathImpl.resolve(String(nodePath || ''));
+  if (!String(nodePath || '').trim()) {
+    throw new Error('Windows autostart requires the Node.js executable path.');
+  }
+  const serverPath = pathImpl.join(resolvedPackageRoot, 'server', 'server.js');
+  const lines = [
+    '@echo off',
+    'title Copilot Remote Web Relay',
+  ];
+  if (String(configPath || '').trim()) {
+    lines.push(`set "COPILOT_WEB_RELAY_CONFIG=${escapeBatchValue(pathImpl.resolve(configPath))}"`);
+  }
+  lines.push(
+    `cd /d "${escapeBatchValue(resolvedPackageRoot)}"`,
+    `"${escapeBatchValue(resolvedNodePath)}" "${escapeBatchValue(serverPath)}"`,
+    '',
+  );
+  return lines.join('\r\n');
+}
+
+export function createWindowsAutostartService({
+  platform = process.platform,
+  env = process.env,
+  packageRoot,
+  nodePath = process.execPath,
+  configPath = '',
+  fsImpl = fs,
+  pathImpl = path,
+} = {}) {
+  const supported = platform === 'win32';
+
+  function entryPath() {
+    return pathImpl.join(
+      resolveWindowsStartupDirectory(env, pathImpl),
+      WINDOWS_AUTOSTART_FILENAME,
+    );
+  }
+
+  function getState() {
+    return {
+      supported,
+      enabled: supported ? fsImpl.existsSync(entryPath()) : false,
+      platform,
+    };
+  }
+
+  function setEnabled(enabled) {
+    if (!supported) {
+      throw new Error('Windows autostart is only available on Windows.');
+    }
+    if (typeof enabled !== 'boolean') {
+      throw new TypeError('Windows autostart enabled state must be a boolean.');
+    }
+
+    const targetPath = entryPath();
+    const existed = fsImpl.existsSync(targetPath);
+    if (!enabled) {
+      if (existed) fsImpl.unlinkSync(targetPath);
+      return { ...getState(), changed: existed };
+    }
+
+    const script = buildWindowsAutostartScript({
+      packageRoot,
+      nodePath,
+      configPath,
+      pathImpl,
+    });
+    if (existed && fsImpl.readFileSync(targetPath, 'utf8') === script) {
+      return { ...getState(), changed: false };
+    }
+
+    fsImpl.mkdirSync(pathImpl.dirname(targetPath), { recursive: true });
+    const temporaryPath = `${targetPath}.${randomUUID()}.tmp`;
+    try {
+      fsImpl.writeFileSync(temporaryPath, script, { encoding: 'utf8', flag: 'wx' });
+      fsImpl.renameSync(temporaryPath, targetPath);
+    } finally {
+      if (fsImpl.existsSync(temporaryPath)) fsImpl.unlinkSync(temporaryPath);
+    }
+    return { ...getState(), changed: true };
+  }
+
+  return {
+    getState,
+    setEnabled,
+  };
+}

package/server/services/workspace-root-defaults-service.mjs

@@ -0,0 +1,34 @@
+export function resolveDefaultSessionWorkspaceRootState({
+  storedPath = '',
+  normalizePath = null,
+} = {}) {
+  const stored = String(storedPath || '').trim();
+  if (!stored) return { path: null, warning: null };
+  const normalized = typeof normalizePath === 'function' ? normalizePath(stored) : stored;
+  const normalizedText = String(normalized || '').trim();
+  if (normalizedText) {
+    return {
+      path: normalizedText,
+      warning: null,
+    };
+  }
+  return {
+    path: null,
+    warning: 'Saved default CWD is unavailable. Update it in Settings.',
+  };
+}
+
+export function resolveLaunchWorkspaceRootPath({
+  configuredWorkspaceRootPath = '',
+  pendingSessionWorkspaceRootPath = '',
+  defaultSessionWorkspaceRootPath = '',
+  workspaceRootPath = '',
+} = {}) {
+  const configured = String(configuredWorkspaceRootPath || '').trim();
+  if (configured) return configured;
+  const pending = String(pendingSessionWorkspaceRootPath || '').trim();
+  if (pending) return pending;
+  const configuredDefault = String(defaultSessionWorkspaceRootPath || '').trim();
+  if (configuredDefault) return configuredDefault;
+  return String(workspaceRootPath || '').trim();
+}

package/server/services/workspace-root-path-policy.mjs

@@ -0,0 +1,196 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Workspace-root path policy
+//
+// The canonical home for CWD path normalization and for the *strict* validation
+// applied to the REST endpoints that let a client choose a session's launch
+// directory. Deliberately separate from server-runtime's lenient
+// normalizeWorkspaceRootPath(), which must keep accepting whatever a CLI
+// reports about itself.
+// ---------------------------------------------------------------------------
+
+// Characters rejected outright. Mirrors parseCdCommandTarget in workspace-root.mjs
+// so the REST endpoints are no laxer than the chat `cd` command.
+const REJECTED_PATH_CHARS = /[;&|\0\r\n]/;
+
+function pathFor(platform) {
+  return platform === 'win32' ? path.win32 : path.posix;
+}
+
+/**
+ * "D:" -> "D:\". Without the trailing separator, path.resolve("D:") returns the
+ * process's remembered per-drive CWD rather than the drive root.
+ *
+ * This is the canonical copy; server-runtime.mjs, workspace-root.mjs and
+ * drives-path-helpers.mjs all delegate here. The browser has its own copy in
+ * public/app/cwd-picker.js because server/ modules are not served to the client.
+ */
+export function normalizeDriveLetterOnlyPath(value) {
+  const stripped = String(value ?? '').trim();
+  if (/^[A-Za-z]:$/.test(stripped)) return `${stripped}\\`;
+  return stripped;
+}
+
+/**
+ * A comparison key for two paths that name the same directory.
+ * Windows is case-insensitive across every segment, not just the drive letter,
+ * so the whole string folds there. POSIX paths are left alone.
+ */
+export function normalizeWorkspaceRootKey(value, platform = process.platform) {
+  let stripped = String(value ?? '').trim();
+  if (!stripped) return '';
+  // Keep the separator that *is* the root ("C:\", "/").
+  const trimmed = stripped.replace(/[\\/]+$/, '');
+  stripped = trimmed || stripped.slice(0, 1);
+  if (/^[A-Za-z]:$/.test(stripped)) stripped = `${stripped}\\`;
+  return platform === 'win32' ? stripped.toLowerCase() : stripped;
+}
+
+/**
+ * Segment-boundary containment check. Never a bare startsWith: the prefix
+ * "C:\work" must not admit "C:\work-secrets".
+ */
+export function isWithinAllowedPrefix(candidatePath, prefixes = [], platform = process.platform) {
+  const list = Array.isArray(prefixes) ? prefixes : [];
+  if (!list.length) return true;
+  const sep = platform === 'win32' ? '\\' : '/';
+  const key = normalizeWorkspaceRootKey(candidatePath, platform);
+  if (!key) return false;
+  return list.some((prefix) => {
+    const prefixKey = normalizeWorkspaceRootKey(prefix, platform);
+    if (!prefixKey) return false;
+    if (key === prefixKey) return true;
+    // A root prefix ("C:\", "/") already ends in the separator.
+    const withSep = prefixKey.endsWith(sep) ? prefixKey : `${prefixKey}${sep}`;
+    return key.startsWith(withSep);
+  });
+}
+
+/**
+ * Strict validation for client-supplied launch directories.
+ * Returns { ok, path, realPath } or { ok: false, code, error }.
+ *
+ * Codes: missing-root-path | invalid-root-path | relative-root-path
+ *      | root-path-not-found | root-path-not-allowed
+ */
+export function validateRequestedWorkspaceRoot(candidatePath, {
+  platform = process.platform,
+  allowList = [],
+  statSyncImpl = fs.statSync,
+  realpathSyncImpl = fs.realpathSync.native,
+} = {}) {
+  const pathApi = pathFor(platform);
+  const raw = String(candidatePath ?? '').trim();
+  if (!raw) {
+    return { ok: false, code: 'missing-root-path', error: 'Missing rootPath' };
+  }
+  if (REJECTED_PATH_CHARS.test(raw)) {
+    return { ok: false, code: 'invalid-root-path', error: 'The path contains characters that are not allowed.' };
+  }
+
+  const withDriveRoot = normalizeDriveLetterOnlyPath(raw);
+  if (platform === 'win32') {
+    // Drive-relative ("C:foo") resolves against a per-drive CWD we do not control.
+    if (/^[A-Za-z]:[^\\/]/.test(withDriveRoot)) {
+      return { ok: false, code: 'relative-root-path', error: 'Use an absolute path (for example C:\\projects\\app).' };
+    }
+    // Extended-length and device namespaces bypass normalization entirely.
+    if (/^\\\\[?.]\\/.test(withDriveRoot)) {
+      return { ok: false, code: 'invalid-root-path', error: 'Extended-length and device paths are not supported.' };
+    }
+  }
+  if (!pathApi.isAbsolute(withDriveRoot)) {
+    return {
+      ok: false,
+      code: 'relative-root-path',
+      error: platform === 'win32'
+        ? 'Use an absolute path (for example C:\\projects\\app).'
+        : 'Use an absolute path (for example /home/user/projects/app).',
+    };
+  }
+
+  const resolved = pathApi.resolve(withDriveRoot);
+  try {
+    if (!statSyncImpl(resolved).isDirectory()) {
+      return { ok: false, code: 'root-path-not-found', error: `Not a directory: ${resolved}` };
+    }
+  } catch {
+    return { ok: false, code: 'root-path-not-found', error: `Directory not found: ${resolved}` };
+  }
+
+  // Resolve symlinks before the allowlist check so an alias cannot smuggle a
+  // request past it, and so the recent-CWD list stops collecting aliases.
+  let realPath = resolved;
+  try {
+    realPath = realpathSyncImpl(resolved);
+    if (!statSyncImpl(realPath).isDirectory()) {
+      return { ok: false, code: 'root-path-not-found', error: `Not a directory: ${realPath}` };
+    }
+  } catch {
+    realPath = resolved;
+  }
+
+  if (!isWithinAllowedPrefix(realPath, allowList, platform)) {
+    return { ok: false, code: 'root-path-not-allowed', error: 'That directory is outside the configured workspace allow list.' };
+  }
+
+  return { ok: true, path: resolved, realPath };
+}
+
+/**
+ * Config/env parsing for the opt-in allow list.
+ * Absent, null, empty or malformed input disables the allow list entirely, so
+ * deployments that never set it behave exactly as they did before.
+ * Entries that do not resolve to a directory are dropped with a warning rather
+ * than failing closed — a typo must not brick a relay.
+ */
+export function normalizeWorkspaceRootAllowList(value, {
+  statSyncImpl = fs.statSync,
+  realpathSyncImpl = fs.realpathSync.native,
+  warn = console.warn,
+} = {}) {
+  let entries = [];
+  if (Array.isArray(value)) entries = value;
+  else if (typeof value === 'string' && value.trim()) entries = value.split(path.delimiter);
+  else return [];
+
+  const normalized = [];
+  for (const entry of entries) {
+    const raw = normalizeDriveLetterOnlyPath(entry);
+    if (!raw) continue;
+    let resolved = '';
+    try {
+      resolved = path.resolve(raw);
+      if (!statSyncImpl(resolved).isDirectory()) {
+        warn(`[workspace-root] ignoring allow-list entry (not a directory): ${raw}`);
+        continue;
+      }
+      try {
+        resolved = realpathSyncImpl(resolved);
+      } catch {
+        // Keep the resolved path when realpath is unavailable.
+      }
+    } catch {
+      warn(`[workspace-root] ignoring allow-list entry (not found): ${raw}`);
+      continue;
+    }
+    if (!normalized.includes(resolved)) normalized.push(resolved);
+  }
+  return normalized;
+}
+
+/**
+ * Shared body-alias reader so both CWD endpoints accept the same payload shape.
+ * `||` rather than `??` preserves the existing fall-through-on-empty-string.
+ */
+export function readWorkspaceRootPathFromBody(body) {
+  return String(
+    body?.rootPath
+    || body?.workspaceRootPath
+    || body?.workspace_root_path
+    || body?.cwd
+    || '',
+  ).trim();
+}

package/server/services/workspace-root-relaunch-service.mjs

@@ -0,0 +1,132 @@
+import { normalizeWorkspaceRootKey } from './workspace-root-path-policy.mjs';
+
+// ---------------------------------------------------------------------------
+// Workspace-root relaunch policy
+//
+// Pure, express-free helpers behind POST /api/conversation/:id/relaunch-with-workspace-root.
+// Kept separate from the route so the concurrency and reporting rules can be
+// tested without an HTTP server.
+// ---------------------------------------------------------------------------
+
+// Mirrors DUPLICATE_USER_MESSAGE_WINDOW_MS in routes/messages-routes.mjs: a
+// repeated request inside this window is treated as the same user intent.
+export const RELAUNCH_COALESCE_WINDOW_MS = 5_000;
+
+/**
+ * Decide whether a relaunch may proceed and whether the running CLI must be stopped first.
+ *
+ * `workerPidAlive` / `liveProcessDetected` matter because a session whose status
+ * is anything but 'ready' (e.g. 'error', or missing from the registry entirely)
+ * can still have a live process. Without them the route would skip the stop and
+ * the launch would silently reuse that process — in the *old* directory.
+ *
+ * The return shape is deliberately just { ok, stopWorker }.
+ */
+export function evaluateWorkspaceRootRelaunch({
+  workerStatus = '',
+  activeQueueCount = 0,
+  workerPidAlive = false,
+  liveProcessDetected = false,
+} = {}) {
+  const normalizedStatus = String(workerStatus || '').trim().toLowerCase();
+  if (Number(activeQueueCount) > 0 || normalizedStatus === 'processing' || normalizedStatus === 'starting') {
+    return {
+      ok: false,
+      statusCode: 409,
+      error: 'Wait for the active turn to finish before changing CWD.',
+    };
+  }
+  return {
+    ok: true,
+    stopWorker: normalizedStatus === 'ready' || workerPidAlive === true || liveProcessDetected === true,
+  };
+}
+
+/**
+ * Identity of a relaunch request. Two requests with the same key are the same
+ * user intent and may share one result; two with different keys must not.
+ */
+export function buildRelaunchRequestKey({
+  conversationId = '',
+  rootPath = '',
+  idempotencyKey = '',
+  platform = process.platform,
+} = {}) {
+  const explicit = String(idempotencyKey || '').trim();
+  if (explicit) return `idem:${explicit}`;
+  const conv = String(conversationId || '').trim();
+  return `${conv}|${normalizeWorkspaceRootKey(rootPath, platform)}`;
+}
+
+/**
+ * Per-session request coalescer.
+ *
+ * - same key, in flight   -> await and return the same body
+ * - same key, just settled -> replay the cached body
+ * - different key, in flight -> busy
+ */
+export function createRelaunchCoalescer({
+  nowMs = Date.now,
+  windowMs = RELAUNCH_COALESCE_WINDOW_MS,
+} = {}) {
+  /** @type {Map<string, { key: string, promise: Promise<unknown>|null, result: unknown, settledAtMs: number }>} */
+  const bySession = new Map();
+
+  function prune(reference = nowMs()) {
+    for (const [sessionId, entry] of bySession) {
+      if (entry.promise) continue;
+      if (reference - entry.settledAtMs > windowMs) bySession.delete(sessionId);
+    }
+  }
+
+  function peek(sessionId, key) {
+    prune();
+    const entry = bySession.get(String(sessionId || ''));
+    if (!entry) return { state: 'idle' };
+    if (entry.key !== key) {
+      return entry.promise ? { state: 'busy' } : { state: 'idle' };
+    }
+    if (entry.promise) return { state: 'in-flight', promise: entry.promise };
+    if (nowMs() - entry.settledAtMs <= windowMs) return { state: 'cached', result: entry.result };
+    return { state: 'idle' };
+  }
+
+  function begin(sessionId, key) {
+    const sid = String(sessionId || '');
+    let settle;
+    const promise = new Promise((resolve) => { settle = resolve; });
+    bySession.set(sid, { key, promise, result: undefined, settledAtMs: 0 });
+    return { settle };
+  }
+
+  function settle(sessionId, key, result) {
+    const sid = String(sessionId || '');
+    const entry = bySession.get(sid);
+    if (!entry || entry.key !== key) return;
+    entry.promise = null;
+    entry.result = result;
+    entry.settledAtMs = nowMs();
+  }
+
+  function forget(sessionId) {
+    bySession.delete(String(sessionId || ''));
+  }
+
+  return { peek, begin, settle, forget, prune, size: () => bySession.size };
+}
+
+/**
+ * Did a relaunch actually apply the requested directory?
+ * `comparable` is false when the running CLI's directory is unknown, in which
+ * case the caller must not claim success either way.
+ */
+export function evaluateReuseCwdMismatch({
+  requestedRootPath = '',
+  observedRootPath = '',
+  platform = process.platform,
+} = {}) {
+  const requested = normalizeWorkspaceRootKey(requestedRootPath, platform);
+  const observed = normalizeWorkspaceRootKey(observedRootPath, platform);
+  if (!requested || !observed) return { comparable: false, mismatch: false };
+  return { comparable: true, mismatch: requested !== observed };
+}