evolcore 0.0.1 → 0.0.3

package/dist/utils/npm-ops.js

@@ -0,0 +1,210 @@
+/**
+ * npm operations
+ *
+ * 集中管理本仓库所有 `npm install -g` / `npm view` 相关的子进程调用：
+ *  - tryUpgrade()       — evolcore 自我升级
+ *  - requireOptional()  — 可选依赖动态加载 + 自动安装
+ *  - npmInstallGlobal() — 全局安装（含 EACCES → sudo 回退、Windows npm.cmd）
+ */
+import fs from 'fs';
+import path from 'path';
+import { execFile, execSync } from 'child_process';
+import { promisify } from 'util';
+import { getPackageRoot } from '../paths.js';
+import { isWindows } from './cross-platform.js';
+const execFileAsync = promisify(execFile);
+// ── npm install -g (shared) ────────────────────────────────────────────────
+export async function npmInstallGlobal(pkg) {
+    let cmd;
+    let args;
+    // Windows: run via cmd /c to avoid shell:true deprecation warning on Node 22.
+    // Unix: npm directly, no shell needed.
+    if (isWindows) {
+        cmd = 'cmd';
+        args = ['/c', 'npm', 'install', '-g', pkg];
+    }
+    else {
+        cmd = 'npm';
+        args = ['install', '-g', pkg];
+    }
+    try {
+        await execFileAsync(cmd, args, { timeout: 180000 });
+    }
+    catch (e) {
+        if (e.stderr?.includes('EACCES') || e.message?.includes('EACCES')) {
+            if (isWindows) {
+                throw new Error('权限不足。请以管理员身份运行 PowerShell 或 CMD，然后重试');
+            }
+            await execFileAsync('sudo', ['npm', 'install', '-g', pkg], { timeout: 180000 });
+        }
+        else {
+            throw e;
+        }
+    }
+}
+/** Dynamic import with auto-install fallback for optional dependencies */
+export async function requireOptional(pkg, autoInstall = true) {
+    try {
+        return await import(pkg);
+    }
+    catch (e) {
+        if (e.code !== 'ERR_MODULE_NOT_FOUND' && e.code !== 'MODULE_NOT_FOUND')
+            throw e;
+        if (!autoInstall)
+            throw new Error(`依赖 ${pkg} 未安装。请运行: npm install -g ${pkg}`);
+        const { logger } = await import('./logger.js');
+        logger.info(`正在安装可选依赖 ${pkg}...`);
+        await npmInstallGlobal(pkg);
+        return await import(pkg);
+    }
+}
+/**
+ * 比较两个 semver 版本号 (a.b.c 格式)
+ * 返回 -1 (a < b), 0 (a == b), 1 (a > b)
+ * 自动剥离 pre-release 标签 (e.g. 2.6.0-beta.1 → 2.6.0)
+ */
+export function compareVersions(a, b) {
+    const pa = a.split('-')[0].split('.').map(Number);
+    const pb = b.split('-')[0].split('.').map(Number);
+    const len = Math.max(pa.length, pb.length);
+    for (let i = 0; i < len; i++) {
+        const na = pa[i] ?? 0;
+        const nb = pb[i] ?? 0;
+        if (na < nb)
+            return -1;
+        if (na > nb)
+            return 1;
+    }
+    return 0;
+}
+/**
+ * 检查当前安装是否为 npm link 开发模式。
+ * 正式全局安装的路径结构为 .../node_modules/evolcore，
+ * 而 npm link 指向项目源码目录，其父目录不是 node_modules。
+ */
+export function isLinkedInstall() {
+    const pkgRoot = getPackageRoot();
+    return path.basename(path.dirname(pkgRoot)) !== 'node_modules';
+}
+/** 获取本地 package.json 中的版本号 */
+export function getLocalVersion() {
+    const pkgPath = path.join(getPackageRoot(), 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    return pkg.version;
+}
+/**
+ * 解析全局安装包的已装版本（通过 `npm root -g` 定位全局 node_modules）。
+ * 用于 EC Web 这类独立全局命令包——它们不在主包的依赖树里。
+ * 未安装或查询失败返回 null。
+ */
+export function resolveGlobalPkg(pkgName) {
+    try {
+        // 命令完全静态（npm root -g，无用户输入），用 execSync 传完整命令字符串，
+        // 避免 "args 数组 + shell:true" 组合触发 Node DeprecationWarning，且无注入风险。
+        const npmCmd = isWindows ? 'npm.cmd' : 'npm';
+        const globalRoot = execSync(`${npmCmd} root -g`, {
+            encoding: 'utf-8', timeout: 10000,
+        }).trim();
+        const pkgPath = path.join(globalRoot, ...pkgName.split('/'), 'package.json');
+        if (fs.existsSync(pkgPath)) {
+            const data = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+            return { version: data.version, path: pkgPath };
+        }
+    }
+    catch { /* not found */ }
+    return null;
+}
+/**
+ * 查询 npm registry 上指定包的最新版本。
+ * 使用 HTTP fetch 直接查 registry API，不依赖 npm CLI。
+ * 超时 10 秒，失败返回 null。
+ */
+export async function checkLatestVersion(pkg = 'evolcore') {
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 10000);
+        const res = await fetch(`https://registry.npmjs.org/${pkg}/latest`, {
+            signal: controller.signal,
+            headers: { 'Accept': 'application/json' },
+        });
+        clearTimeout(timer);
+        if (!res.ok)
+            return null;
+        const data = await res.json();
+        return data.version || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 完整升级流程：检查 → 比较 → 安装（失败重试一次）
+ */
+export async function tryUpgrade() {
+    // 开发模式跳过
+    if (isLinkedInstall()) {
+        return { status: 'skipped' };
+    }
+    const localVer = getLocalVersion();
+    // 查询 registry
+    const remoteVer = await checkLatestVersion();
+    if (!remoteVer) {
+        return { status: 'skipped', error: 'Failed to check remote version' };
+    }
+    // 版本比较
+    if (compareVersions(localVer, remoteVer) >= 0) {
+        return { status: 'no-update', from: localVer };
+    }
+    // 有新版本，执行升级（失败重试一次）
+    let lastError;
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            await npmInstallGlobal('evolcore@latest');
+            return { status: 'upgraded', from: localVer, to: remoteVer };
+        }
+        catch (e) {
+            lastError = e.stderr || e.message || String(e);
+        }
+    }
+    return { status: 'failed', from: localVer, to: remoteVer, error: lastError };
+}
+/**
+ * 通用全局包升级流程：检查 → 比较 → 安装（失败重试一次）。
+ * 仅在包已安装时检查升级，未安装则跳过（resolveFn 返回 null）。
+ * fastaun / EC Web 等独立全局包共用此逻辑。
+ */
+export async function tryUpgradeGlobalPkg(resolveInstalled, pkgName) {
+    if (isLinkedInstall()) {
+        return { status: 'skipped' };
+    }
+    const installed = resolveInstalled();
+    if (!installed) {
+        return { status: 'skipped' }; // not installed, skip
+    }
+    const localVer = installed.version;
+    const remoteVer = await checkLatestVersion(pkgName);
+    if (!remoteVer) {
+        return { status: 'skipped', error: 'Failed to check remote version' };
+    }
+    if (compareVersions(localVer, remoteVer) >= 0) {
+        return { status: 'no-update', from: localVer };
+    }
+    let lastError;
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            await npmInstallGlobal(`${pkgName}@latest`);
+            return { status: 'upgraded', from: localVer, to: remoteVer };
+        }
+        catch (e) {
+            lastError = e.stderr || e.message || String(e);
+        }
+    }
+    return { status: 'failed', from: localVer, to: remoteVer, error: lastError };
+}
+/**
+ * AUN SDK 升级流程：检查 → 比较 → 安装
+ * 仅在 SDK 已安装时检查升级，未安装则跳过。
+ */
+export async function tryUpgradeAunSdk(resolveAunCoreSdkPkg, AUN_CORE_SDK_PKG) {
+    return tryUpgradeGlobalPkg(resolveAunCoreSdkPkg, AUN_CORE_SDK_PKG);
+}

package/dist/utils/process-introspect.js

@@ -0,0 +1,133 @@
+/**
+ * Cross-platform process introspection.
+ *
+ * Provides process start time retrieval for PID reuse detection.
+ * Returns null when start time cannot be obtained — callers should treat
+ * this as "do not match" (conservative: prefer leaving an orphan over
+ * killing the wrong process).
+ */
+import fs from 'fs';
+import { spawnSync } from 'child_process';
+import { isWindows } from './cross-platform.js';
+const isMacOS = process.platform === 'darwin';
+/** 容差：2 秒（覆盖 macOS 秒级精度 + 时钟漂移） */
+export const START_TIME_TOLERANCE_MS = 2000;
+/**
+ * 获取进程启动时间（Unix 毫秒）。
+ * 拿不到时返回 null，调用方应保守处理（不杀该 PID）。
+ */
+export function getProcessStartTime(pid) {
+    try {
+        if (isWindows)
+            return getStartTimeWindows(pid);
+        if (isMacOS)
+            return getStartTimeMacOS(pid);
+        return getStartTimeLinux(pid);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 比对记录的启动时间与实际启动时间是否匹配（容差 2 秒）。
+ * actual === null 时返回 false（保守不匹配）。
+ */
+export function startTimeMatches(recorded, actual) {
+    if (actual === null)
+        return false;
+    return Math.abs(recorded - actual) < START_TIME_TOLERANCE_MS;
+}
+/**
+ * 只读关联进程校验：允许记录时间晚于进程实际启动时间，但拒绝实际进程明显更新。
+ * 部分启动器会在子进程就绪后才写 instance 记录；此时 recorded 比 actual 晚是正常的。
+ */
+export function isSameOrOlderProcess(recorded, actual) {
+    if (actual === null)
+        return true;
+    return actual - recorded < START_TIME_TOLERANCE_MS;
+}
+// ── Linux ──
+function getStartTimeLinux(pid) {
+    let stat;
+    try {
+        stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    const tail = stat.slice(stat.lastIndexOf(')') + 2);
+    const fields = tail.split(' ');
+    const starttimeJiffies = parseInt(fields[19], 10);
+    if (isNaN(starttimeJiffies))
+        return null;
+    let btimeSec;
+    try {
+        const m = fs.readFileSync('/proc/stat', 'utf-8').match(/^btime (\d+)/m);
+        if (!m)
+            return null;
+        btimeSec = parseInt(m[1], 10);
+    }
+    catch {
+        return null;
+    }
+    if (isNaN(btimeSec))
+        return null;
+    const clkTck = 100;
+    return (btimeSec + starttimeJiffies / clkTck) * 1000;
+}
+// ── macOS ──
+function getStartTimeMacOS(pid) {
+    const result = spawnSync('ps', ['-p', String(pid), '-o', 'lstart='], {
+        encoding: 'utf-8',
+        timeout: 5000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const out = result.stdout?.trim();
+    if (!out)
+        return null;
+    const t = Date.parse(out);
+    return isNaN(t) ? null : t;
+}
+// ── Windows ──
+function getStartTimeWindows(pid) {
+    const fromPwsh = winPowerShellCreationDate(pid);
+    if (fromPwsh !== null)
+        return fromPwsh;
+    return winWmicCreationDate(pid);
+}
+function winPowerShellCreationDate(pid) {
+    const result = spawnSync('powershell', [
+        '-NoProfile',
+        '-Command',
+        `(Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}').CreationDate`,
+    ], { encoding: 'utf-8', timeout: 8000, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+    const out = result.stdout?.trim();
+    if (!out)
+        return null;
+    return parseCimDate(out);
+}
+function winWmicCreationDate(pid) {
+    const result = spawnSync('wmic', ['process', 'where', `ProcessId=${pid}`, 'get', 'CreationDate', '/value'], { encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+    const out = result.stdout || '';
+    const m = out.match(/CreationDate=([^\r\n]+)/);
+    if (!m)
+        return null;
+    return parseCimDate(m[1].trim());
+}
+/**
+ * 解析 CIM/WMI 日期格式：yyyyMMddHHmmss.ffffff±TZZZ
+ * TZZZ 是相对 UTC 的分钟偏移（中国是 +480）
+ */
+export function parseCimDate(s) {
+    if (!s)
+        return null;
+    const m = s.match(/^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})\.(\d{6})([+-]\d+)$/);
+    if (!m)
+        return null;
+    const [, y, mo, d, h, mi, sec, us, tz] = m;
+    const tzMin = parseInt(tz, 10);
+    if (isNaN(tzMin))
+        return null;
+    const localUtcMs = Date.UTC(+y, +mo - 1, +d, +h, +mi, +sec, Math.floor(+us / 1000));
+    return localUtcMs - tzMin * 60 * 1000;
+}

package/dist/utils/process-tree-stats.js

@@ -0,0 +1,271 @@
+import fs from 'fs';
+import { spawnSync } from 'child_process';
+function runnerKind(name) {
+    const normalized = name.toLowerCase();
+    if (normalized.includes('codex'))
+        return 'codex-app-server';
+    if (normalized.includes('claude'))
+        return 'claude-runner';
+    if (normalized.includes('gemini'))
+        return 'gemini-runner';
+    return null;
+}
+export function classifyProcessTree(processes, rootPid, explicitKinds = new Map()) {
+    const byPid = new Map(processes.map(process => [process.pid, process]));
+    const children = new Map();
+    for (const process of processes) {
+        const list = children.get(process.ppid) ?? [];
+        list.push(process.pid);
+        children.set(process.ppid, list);
+    }
+    const branchKinds = new Map();
+    const resolveBranchKind = (pid, visiting = new Set()) => {
+        if (branchKinds.has(pid))
+            return branchKinds.get(pid) ?? null;
+        if (visiting.has(pid))
+            return null;
+        visiting.add(pid);
+        const process = byPid.get(pid);
+        let kind = process ? runnerKind(process.name) : null;
+        if (!kind) {
+            for (const childPid of children.get(pid) ?? []) {
+                kind = resolveBranchKind(childPid, visiting);
+                if (kind)
+                    break;
+            }
+        }
+        visiting.delete(pid);
+        branchKinds.set(pid, kind);
+        return kind;
+    };
+    const resolveAncestorKind = (process) => {
+        let parent = byPid.get(process.ppid);
+        const visited = new Set();
+        while (parent && !visited.has(parent.pid)) {
+            visited.add(parent.pid);
+            const kind = runnerKind(parent.name) ?? resolveBranchKind(parent.pid);
+            if (kind)
+                return kind;
+            parent = byPid.get(parent.ppid);
+        }
+        return null;
+    };
+    return processes.map(process => {
+        const explicit = explicitKinds.get(process.pid);
+        const normalized = process.name.toLowerCase();
+        let kind;
+        if (process.pid === rootPid)
+            kind = 'daemon';
+        else if (explicit)
+            kind = explicit;
+        else if (normalized === 'bwrap' || normalized.includes('bubblewrap'))
+            kind = 'sandbox';
+        else if (normalized === 'socat')
+            kind = 'runner-helper';
+        else
+            kind = runnerKind(process.name) ?? resolveBranchKind(process.pid) ?? resolveAncestorKind(process) ?? 'child';
+        return { ...process, kind };
+    });
+}
+const linuxClockTicks = readPositiveInt('getconf', ['CLK_TCK'], 100);
+const linuxPageSize = readPositiveInt('getconf', ['PAGESIZE'], 4096);
+function readPositiveInt(command, args, fallback) {
+    if (process.platform !== 'linux')
+        return fallback;
+    try {
+        const result = spawnSync(command, args, { encoding: 'utf8', timeout: 1000, stdio: ['ignore', 'pipe', 'ignore'] });
+        const value = Number.parseInt(result.stdout?.trim() || '', 10);
+        return value > 0 ? value : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+function round1(value) {
+    return Math.round(value * 10) / 10;
+}
+export function parseLinuxProcStat(stat, pageSize = linuxPageSize, clockTicks = linuxClockTicks) {
+    const open = stat.indexOf('(');
+    const close = stat.lastIndexOf(')');
+    if (open < 1 || close <= open)
+        return null;
+    const pid = Number.parseInt(stat.slice(0, open).trim(), 10);
+    const fields = stat.slice(close + 2).trim().split(/\s+/);
+    const ppid = Number.parseInt(fields[1], 10);
+    const userTicks = Number.parseInt(fields[11], 10);
+    const systemTicks = Number.parseInt(fields[12], 10);
+    const startTicks = Number.parseInt(fields[19], 10);
+    const rssPages = Number.parseInt(fields[21], 10);
+    if (![pid, ppid, userTicks, systemTicks, rssPages].every(Number.isFinite))
+        return null;
+    return {
+        pid,
+        ppid,
+        name: stat.slice(open + 1, close),
+        cumulativeCpuMs: (userTicks + systemTicks) * 1000 / clockTicks,
+        rss: Math.max(0, rssPages) * pageSize,
+        startId: Number.isFinite(startTicks) ? startTicks : undefined,
+    };
+}
+function readLinuxMetrics() {
+    const metrics = [];
+    let entries;
+    try {
+        entries = fs.readdirSync('/proc');
+    }
+    catch {
+        return metrics;
+    }
+    for (const entry of entries) {
+        if (!/^\d+$/.test(entry))
+            continue;
+        try {
+            const metric = parseLinuxProcStat(fs.readFileSync(`/proc/${entry}/stat`, 'utf8'));
+            if (metric)
+                metrics.push(metric);
+        }
+        catch { }
+    }
+    return metrics;
+}
+export function parseProcessTime(value) {
+    const match = value.trim().match(/^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+(?:\.\d+)?)$/);
+    if (!match)
+        return 0;
+    const days = Number(match[1] || 0);
+    const hours = Number(match[2] || 0);
+    const minutes = Number(match[3] || 0);
+    const seconds = Number(match[4] || 0);
+    return (((days * 24 + hours) * 60 + minutes) * 60 + seconds) * 1000;
+}
+function readUnixPsMetrics() {
+    const result = spawnSync('ps', ['-axo', 'pid=,ppid=,rss=,time=,comm='], {
+        encoding: 'utf8',
+        timeout: 3000,
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (result.status !== 0)
+        return [];
+    const metrics = [];
+    for (const line of (result.stdout || '').split('\n')) {
+        const match = line.match(/^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(.+?)\s*$/);
+        if (!match)
+            continue;
+        metrics.push({
+            pid: Number(match[1]),
+            ppid: Number(match[2]),
+            rss: Number(match[3]) * 1024,
+            cumulativeCpuMs: parseProcessTime(match[4]),
+            name: match[5],
+        });
+    }
+    return metrics;
+}
+function readWindowsMetrics() {
+    const command = [
+        'Get-CimInstance Win32_Process',
+        'Select-Object ProcessId,ParentProcessId,Name,WorkingSetSize,KernelModeTime,UserModeTime,CreationDate',
+        'ConvertTo-Json -Compress',
+    ].join(' | ');
+    const result = spawnSync('powershell', ['-NoProfile', '-Command', command], {
+        encoding: 'utf8',
+        timeout: 5000,
+        windowsHide: true,
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (result.status !== 0 || !result.stdout?.trim())
+        return [];
+    try {
+        const parsed = JSON.parse(result.stdout);
+        const rows = Array.isArray(parsed) ? parsed : [parsed];
+        return rows.map((row) => ({
+            pid: Number(row.ProcessId),
+            ppid: Number(row.ParentProcessId),
+            name: String(row.Name || 'unknown'),
+            rss: Number(row.WorkingSetSize) || 0,
+            cumulativeCpuMs: ((Number(row.KernelModeTime) || 0) + (Number(row.UserModeTime) || 0)) / 10_000,
+            startId: row.CreationDate ? String(row.CreationDate) : undefined,
+        })).filter((row) => row.pid > 0);
+    }
+    catch {
+        return [];
+    }
+}
+export function readProcessMetrics() {
+    if (process.platform === 'linux')
+        return readLinuxMetrics();
+    if (process.platform === 'win32')
+        return readWindowsMetrics();
+    return readUnixPsMetrics();
+}
+export class ProcessTreeSampler {
+    rootPid;
+    readMetrics;
+    now;
+    previous = new Map();
+    previousTs = null;
+    constructor(rootPid = process.pid, readMetrics = readProcessMetrics, now = Date.now) {
+        this.rootPid = rootPid;
+        this.readMetrics = readMetrics;
+        this.now = now;
+    }
+    sample(associatedRootPids = []) {
+        const timestamp = this.now();
+        const metrics = this.readMetrics();
+        const byPid = new Map(metrics.map(metric => [metric.pid, metric]));
+        const children = new Map();
+        for (const metric of metrics) {
+            const list = children.get(metric.ppid) ?? [];
+            list.push(metric.pid);
+            children.set(metric.ppid, list);
+        }
+        const rootPids = [...new Set([this.rootPid, ...associatedRootPids])].filter(pid => byPid.has(pid));
+        const selected = new Set();
+        const pending = [...rootPids];
+        while (pending.length > 0) {
+            const pid = pending.pop();
+            if (selected.has(pid))
+                continue;
+            selected.add(pid);
+            pending.push(...(children.get(pid) ?? []));
+        }
+        const elapsedMs = this.previousTs === null ? 0 : timestamp - this.previousTs;
+        const processes = [];
+        for (const pid of selected) {
+            const metric = byPid.get(pid);
+            if (!metric)
+                continue;
+            const previous = this.previous.get(pid);
+            const sameProcess = previous && (previous.startId === undefined || metric.startId === undefined || previous.startId === metric.startId);
+            const cpuDelta = sameProcess ? metric.cumulativeCpuMs - previous.cumulativeCpuMs : 0;
+            const cpuPercent = elapsedMs > 0 && cpuDelta > 0 ? cpuDelta * 100 / elapsedMs : 0;
+            processes.push({
+                pid: metric.pid,
+                ppid: metric.ppid,
+                name: metric.name,
+                cpuPercent: round1(cpuPercent),
+                rss: metric.rss,
+            });
+        }
+        this.previous = new Map(metrics.map(metric => [metric.pid, {
+                cumulativeCpuMs: metric.cumulativeCpuMs,
+                startId: metric.startId,
+            }]));
+        this.previousTs = timestamp;
+        processes.sort((left, right) => {
+            if (left.pid === this.rootPid)
+                return -1;
+            if (right.pid === this.rootPid)
+                return 1;
+            return left.pid - right.pid;
+        });
+        return {
+            rootPid: this.rootPid,
+            rootPids,
+            processCount: processes.length,
+            cpuPercent: round1(processes.reduce((sum, metric) => sum + metric.cpuPercent, 0)),
+            rss: processes.reduce((sum, metric) => sum + metric.rss, 0),
+            processes,
+        };
+    }
+}

package/dist/utils/project-path.js

@@ -0,0 +1,74 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+function pathForPlatform(platform) {
+    return platform === 'win32' ? path.win32 : path.posix;
+}
+function trimTrailingSeparators(value, root) {
+    let out = value;
+    while (out.length > root.length && /[\\/]$/.test(out)) {
+        out = out.slice(0, -1);
+    }
+    return out;
+}
+function normalizeForCompare(value, platform) {
+    const pathImpl = pathForPlatform(platform);
+    const resolved = pathImpl.resolve(value);
+    const trimmed = trimTrailingSeparators(resolved, pathImpl.parse(resolved).root);
+    return platform === 'win32' ? trimmed.toLowerCase() : trimmed;
+}
+function isWindowsUnsafeProjectRoot(rootPath, homeDir) {
+    const win = path.win32;
+    const root = normalizeForCompare(rootPath, 'win32');
+    const parsed = win.parse(win.resolve(rootPath));
+    if (root === normalizeForCompare(parsed.root, 'win32'))
+        return true;
+    const userProfileRoot = win.dirname(win.resolve(homeDir));
+    if (win.basename(userProfileRoot).toLowerCase() !== 'users')
+        return false;
+    return root === normalizeForCompare(userProfileRoot, 'win32');
+}
+export function sanitizeProjectRoot(rootPath, options = {}) {
+    const platform = options.platform ?? process.platform;
+    if (platform !== 'win32')
+        return rootPath;
+    const homeDir = options.homeDir ?? os.homedir();
+    if (!homeDir)
+        return rootPath;
+    return isWindowsUnsafeProjectRoot(rootPath, homeDir)
+        ? path.win32.join(homeDir, 'Projects')
+        : rootPath;
+}
+export function defaultProjectsRoot(evolcoreRoot, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const pathImpl = pathForPlatform(platform);
+    if (platform === 'win32') {
+        const homeDir = options.homeDir ?? os.homedir();
+        if (homeDir && isWindowsUnsafeProjectRoot(evolcoreRoot, homeDir)) {
+            return path.win32.join(homeDir, 'Projects');
+        }
+    }
+    return pathImpl.join(evolcoreRoot, 'projects');
+}
+export function agentProjectRootFromDefaults(defaults, evolcoreRoot, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const pathImpl = pathForPlatform(platform);
+    const configuredRoot = defaults?.projects?.rootPath
+        || (defaults?.projects?.defaultPath && pathImpl.dirname(defaults.projects.defaultPath))
+        || defaultProjectsRoot(evolcoreRoot, options);
+    return sanitizeProjectRoot(configuredRoot, options);
+}
+export function deriveAgentProjectPath(rootPath, aid, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const pathImpl = pathForPlatform(platform);
+    const existsSync = options.existsSync ?? fs.existsSync;
+    const baseName = aid.split('.')[0];
+    const safeRootPath = sanitizeProjectRoot(rootPath, options);
+    let candidate = pathImpl.join(safeRootPath, baseName);
+    if (!existsSync(candidate))
+        return candidate;
+    let i = 1;
+    while (existsSync(`${candidate}~${i}`))
+        i++;
+    return `${candidate}~${i}`;
+}