@getpaseo/server 0.1.100 → 0.1.102-beta.2

package/dist/server/server/session/daemon/diagnostics.js

@@ -0,0 +1,431 @@
+import { open, statfs } from "node:fs/promises";
+import { cpus, freemem, loadavg, platform, release, totalmem, type } from "node:os";
+import path from "node:path";
+import { execCommand } from "../../../utils/spawn.js";
+const TOOL_TIMEOUT_MS = 3000;
+const TOOL_OUTPUT_LIMIT = 512;
+const LOG_TAIL_LINES = 80;
+const LOG_TAIL_MAX_BYTES = 64 * 1024;
+export async function collectDaemonDiagnostics(options) {
+    const sections = [
+        formatSection("Paseo diagnostics", [
+            { label: "Collected at", value: new Date().toISOString() },
+            { label: "Server ID", value: options.serverId ?? "unknown" },
+            { label: "Daemon version", value: options.daemonVersion ?? "unknown" },
+        ]),
+    ];
+    sections.push(await safeSection("Daemon process", () => collectProcessEntries(options), options.logger));
+    sections.push(await safeSection("Runtime config", () => collectRuntimeConfigEntries(options), options.logger));
+    sections.push(await safeSection("System", collectSystemEntries, options.logger));
+    sections.push(await safeSection("Disk", () => collectDiskEntries(options), options.logger));
+    sections.push(await safeSection("Agents", () => collectAgentEntries(options), options.logger));
+    sections.push(await safeSection("Workspaces", () => collectWorkspaceEntries(options), options.logger));
+    sections.push(await safeSection("Providers", () => collectProviderEntries(options), options.logger));
+    sections.push(await safeSection("WebSocket runtime metrics", () => collectWebSocketRuntimeEntries(options), options.logger));
+    sections.push(await safeSection("Tools", collectToolEntries, options.logger));
+    sections.push(await safeLogTailSection(options));
+    return redactDiagnostic(sections.filter(Boolean).join("\n\n"), options);
+}
+async function safeSection(title, collect, logger) {
+    try {
+        return formatSection(title, await collect());
+    }
+    catch (error) {
+        logger.debug({ err: error, title }, "diagnostic section failed");
+        return formatSection(title, [{ label: "Error", value: toErrorMessage(error) }]);
+    }
+}
+function formatSection(title, entries) {
+    return [title, ...entries.map((entry) => `  ${entry.label}: ${entry.value}`)].join("\n");
+}
+function collectProcessEntries(options) {
+    const memory = process.memoryUsage();
+    return [
+        { label: "PID", value: String(process.pid) },
+        { label: "Node", value: process.version },
+        { label: "Node path", value: process.execPath },
+        { label: "PATH", value: getEnvValue("PATH", "Path") ?? "unset" },
+        { label: "Shell", value: formatDaemonShell() },
+        { label: "Uptime", value: formatDurationMs(process.uptime() * 1000) },
+        { label: "Paseo home", value: options.paseoHome },
+        { label: "RSS", value: formatBytes(memory.rss) },
+        {
+            label: "Heap used",
+            value: `${formatBytes(memory.heapUsed)} / ${formatBytes(memory.heapTotal)}`,
+        },
+        { label: "External", value: formatBytes(memory.external) },
+    ];
+}
+function collectRuntimeConfigEntries(options) {
+    const relay = options.daemonRuntimeConfig?.relay ?? null;
+    return [
+        { label: "Listen", value: formatListenKind(options.daemonRuntimeConfig?.listen ?? null) },
+        { label: "Relay enabled", value: relay ? String(relay.enabled) : "false" },
+        { label: "Relay endpoint configured", value: relay?.endpoint ? "true" : "false" },
+        { label: "Relay public endpoint configured", value: relay?.publicEndpoint ? "true" : "false" },
+        { label: "Relay TLS", value: relay ? String(relay.useTls) : "n/a" },
+        { label: "Relay public TLS", value: relay ? String(relay.publicUseTls) : "n/a" },
+    ];
+}
+function collectSystemEntries() {
+    const loads = loadavg();
+    return [
+        { label: "OS", value: `${type()} ${release()}` },
+        { label: "Platform", value: `${platform()} ${process.arch}` },
+        { label: "CPU cores", value: String(cpus().length) },
+        { label: "Load avg", value: loads.map((value) => value.toFixed(2)).join(", ") },
+        { label: "Memory free", value: `${formatBytes(freemem())} / ${formatBytes(totalmem())}` },
+    ];
+}
+async function collectDiskEntries(options) {
+    const stats = await statfs(options.paseoHome);
+    const freeBytes = stats.bavail * stats.bsize;
+    const totalBytes = stats.blocks * stats.bsize;
+    return [
+        { label: "Path", value: options.paseoHome },
+        { label: "Free", value: `${formatBytes(freeBytes)} / ${formatBytes(totalBytes)}` },
+    ];
+}
+function collectAgentEntries(options) {
+    const agents = options.listAgents();
+    return [
+        { label: "Total", value: String(agents.length) },
+        { label: "By provider", value: formatCountMap(countBy(agents, (agent) => agent.provider)) },
+        { label: "By lifecycle", value: formatCountMap(countBy(agents, (agent) => agent.lifecycle)) },
+        {
+            label: "Pending permissions",
+            value: String(agents.reduce((total, agent) => total + (agent.pendingPermissions?.size ?? 0), 0)),
+        },
+    ];
+}
+async function collectWorkspaceEntries(options) {
+    const [projects, workspaces] = await Promise.all([
+        options.listProjects(),
+        options.listWorkspaces(),
+    ]);
+    const activeProjects = projects.filter((project) => !project.archivedAt);
+    const activeWorkspaces = workspaces.filter((workspace) => !workspace.archivedAt);
+    return [
+        { label: "Projects", value: `${activeProjects.length} active / ${projects.length} total` },
+        {
+            label: "Workspaces",
+            value: `${activeWorkspaces.length} active / ${workspaces.length} total`,
+        },
+        {
+            label: "Workspaces by kind",
+            value: formatCountMap(countBy(activeWorkspaces, (workspace) => workspace.kind)),
+        },
+    ];
+}
+async function collectProviderEntries(options) {
+    const providers = await options.listProviderAvailability();
+    return [
+        { label: "Total", value: String(providers.length) },
+        {
+            label: "Available",
+            value: String(providers.filter((provider) => provider.available).length),
+        },
+        {
+            label: "Unavailable",
+            value: providers
+                .filter((provider) => !provider.available)
+                .map((provider) => provider.error ? `${provider.provider} (${provider.error})` : provider.provider)
+                .join(", ") || "none",
+        },
+    ];
+}
+async function collectToolEntries() {
+    const [git, gh] = await Promise.all([
+        checkTool("git", ["--version"]),
+        checkTool("gh", ["--version"]),
+    ]);
+    return [
+        { label: "git", value: git },
+        { label: "gh", value: gh },
+    ];
+}
+function collectWebSocketRuntimeEntries(options) {
+    const snapshot = options.getWebSocketRuntimeMetrics();
+    if (!snapshot) {
+        return [{ label: "Status", value: "no runtime metrics window has been flushed yet" }];
+    }
+    const runtime = snapshot.runtime;
+    const agents = snapshot.agents;
+    return [
+        { label: "Collected at", value: snapshot.collectedAt },
+        { label: "Window", value: formatDurationMs(snapshot.windowMs) },
+        { label: "Process uptime", value: formatDurationMs(snapshot.uptimeSeconds * 1000) },
+        {
+            label: "Process memory",
+            value: [
+                `rss=${formatBytes(snapshot.memory.rss)}`,
+                `heap=${formatBytes(snapshot.memory.heapUsed)} / ${formatBytes(snapshot.memory.heapTotal)}`,
+                `external=${formatBytes(snapshot.memory.external)}`,
+                `arrayBuffers=${formatBytes(snapshot.memory.arrayBuffers)}`,
+            ].join(", "),
+        },
+        { label: "Final", value: String(snapshot.final) },
+        {
+            label: "Sessions",
+            value: [
+                `active=${snapshot.sessions.activeConnections}`,
+                `externalKeys=${snapshot.sessions.externalSessionKeys}`,
+                `reconnectGrace=${snapshot.sessions.reconnectGraceSessions}`,
+            ].join(", "),
+        },
+        {
+            label: "Sockets",
+            value: [
+                `active=${snapshot.sockets.activeSockets}`,
+                `pending=${snapshot.sockets.pendingConnections}`,
+            ].join(", "),
+        },
+        {
+            label: "Runtime requests",
+            value: [
+                `inflight=${formatNumberMetric(runtime.inflightRequests)}`,
+                `peakInflight=${formatNumberMetric(runtime.peakInflightRequests)}`,
+            ].join(", "),
+        },
+        {
+            label: "Terminal subscriptions",
+            value: [
+                `terminals=${formatNumberMetric(runtime.terminalSubscriptionCount)}`,
+                `directories=${formatNumberMetric(runtime.terminalDirectorySubscriptionCount)}`,
+            ].join(", "),
+        },
+        {
+            label: "Checkout diff",
+            value: [
+                `targets=${formatNumberMetric(runtime.checkoutDiffTargetCount)}`,
+                `subscriptions=${formatNumberMetric(runtime.checkoutDiffSubscriptionCount)}`,
+                `watchers=${formatNumberMetric(runtime.checkoutDiffWatcherCount)}`,
+                `fallbackRefreshTargets=${formatNumberMetric(runtime.checkoutDiffFallbackRefreshTargetCount)}`,
+            ].join(", "),
+        },
+        {
+            label: "Buffered amount",
+            value: `p95=${formatBytes(snapshot.bufferedAmount.p95)}, max=${formatBytes(snapshot.bufferedAmount.max)}`,
+        },
+        { label: "Event loop delay", value: formatEventLoopDelay(snapshot.eventLoopDelay) },
+        { label: "Latency", value: formatLatencyStats(snapshot.latency) },
+        { label: "Inbound messages", value: formatTopCounts(snapshot.inboundMessageTypesTop) },
+        {
+            label: "Inbound session requests",
+            value: formatTopCounts(snapshot.inboundSessionRequestTypesTop),
+        },
+        { label: "Outbound messages", value: formatTopCounts(snapshot.outboundMessageTypesTop) },
+        {
+            label: "Outbound session messages",
+            value: formatTopCounts(snapshot.outboundSessionMessageTypesTop),
+        },
+        { label: "Agent streams", value: formatTopCounts(snapshot.outboundAgentStreamTypesTop) },
+        { label: "Agent stream agents", value: formatTopCounts(snapshot.outboundAgentStreamAgentsTop) },
+        { label: "Binary frames", value: formatTopCounts(snapshot.outboundBinaryFrameTypesTop) },
+        { label: "Counters", value: formatNonZeroNumberRecord(snapshot.counters) },
+        {
+            label: "Agent metrics",
+            value: [
+                `total=${formatNumberMetric(agents.total)}`,
+                `activeForegroundTurns=${formatNumberMetric(agents.withActiveForegroundTurn)}`,
+            ].join(", "),
+        },
+        { label: "Agent lifecycle", value: formatNumberRecord(agents.byLifecycle) },
+        {
+            label: "Agent timelines",
+            value: [
+                `items=${formatNumberMetric(agents.timelineStats?.totalItems)}`,
+                `maxPerAgent=${formatNumberMetric(agents.timelineStats?.maxItemsPerAgent)}`,
+            ].join(", "),
+        },
+    ];
+}
+function formatTopCounts(counts) {
+    if (counts.length === 0)
+        return "none";
+    return counts.map(([key, count]) => `${key}=${count}`).join(", ");
+}
+function formatLatencyStats(stats) {
+    if (stats.length === 0)
+        return "none";
+    return stats
+        .map((stat) => `${stat.type} count=${stat.count} p50=${formatMilliseconds(stat.p50Ms)} max=${formatMilliseconds(stat.maxMs)} total=${formatMilliseconds(stat.totalMs)}`)
+        .join("; ");
+}
+function formatEventLoopDelay(stats) {
+    if (!stats)
+        return "unavailable";
+    return `p50=${formatMilliseconds(stats.p50Ms)}, p99=${formatMilliseconds(stats.p99Ms)}, max=${formatMilliseconds(stats.maxMs)}`;
+}
+function formatNumberRecord(record) {
+    if (!record)
+        return "unknown";
+    const entries = Object.entries(record).filter(([, value]) => Number.isFinite(value));
+    if (entries.length === 0)
+        return "none";
+    return entries
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, value]) => `${key}=${value}`)
+        .join(", ");
+}
+function formatNonZeroNumberRecord(record) {
+    const entries = Object.entries(record).filter(([, value]) => Number.isFinite(value) && value !== 0);
+    if (entries.length === 0)
+        return "none";
+    return entries
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, value]) => `${key}=${value}`)
+        .join(", ");
+}
+function formatNumberMetric(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return "unknown";
+    return String(value);
+}
+function formatMilliseconds(ms) {
+    if (!Number.isFinite(ms) || ms < 0)
+        return "unknown";
+    return `${Math.round(ms)}ms`;
+}
+async function checkTool(command, args) {
+    try {
+        const result = await execCommand(command, args, {
+            timeout: TOOL_TIMEOUT_MS,
+            maxBuffer: TOOL_OUTPUT_LIMIT * 2,
+        });
+        const output = truncateForDiagnostic((result.stdout || result.stderr).trim(), TOOL_OUTPUT_LIMIT);
+        return output || "ok";
+    }
+    catch (error) {
+        return `error: ${truncateForDiagnostic(toErrorMessage(error), TOOL_OUTPUT_LIMIT)}`;
+    }
+}
+async function safeLogTailSection(options) {
+    const logPath = path.join(options.paseoHome, "daemon.log");
+    try {
+        const tail = await tailFile(logPath, LOG_TAIL_LINES, LOG_TAIL_MAX_BYTES);
+        return ["Daemon log tail", `  Path: ${logPath}`, tail ? tail : "  No log lines found"].join("\n");
+    }
+    catch (error) {
+        options.logger.debug({ err: error, logPath }, "diagnostic log tail failed");
+        return ["Daemon log tail", `  Path: ${logPath}`, `  Error: ${toErrorMessage(error)}`].join("\n");
+    }
+}
+async function tailFile(filePath, lines, maxBytes) {
+    const handle = await open(filePath, "r");
+    try {
+        const stats = await handle.stat();
+        const length = Math.min(stats.size, maxBytes);
+        const buffer = Buffer.alloc(length);
+        await handle.read(buffer, 0, length, stats.size - length);
+        return buffer
+            .toString("utf8")
+            .split("\n")
+            .filter(Boolean)
+            .slice(-lines)
+            .map((line) => `  ${line}`)
+            .join("\n");
+    }
+    finally {
+        await handle.close();
+    }
+}
+function formatListenKind(listen) {
+    if (!listen)
+        return "not configured";
+    if (listen.startsWith("unix://") || listen.startsWith("/"))
+        return "local socket";
+    if (listen.startsWith("pipe://") || listen.startsWith("\\\\.\\pipe\\"))
+        return "local pipe";
+    return "direct TCP";
+}
+function countBy(items, getKey) {
+    const counts = new Map();
+    for (const item of items) {
+        const key = getKey(item) || "unknown";
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    return counts;
+}
+function formatCountMap(counts) {
+    if (counts.size === 0)
+        return "none";
+    return [...counts.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, count]) => `${key}=${count}`)
+        .join(", ");
+}
+function formatDurationMs(ms) {
+    const seconds = Math.max(0, Math.round(ms / 1000));
+    const hours = Math.floor(seconds / 3600);
+    const minutes = Math.floor((seconds % 3600) / 60);
+    const remainingSeconds = seconds % 60;
+    if (hours > 0)
+        return `${hours}h ${minutes}m ${remainingSeconds}s`;
+    if (minutes > 0)
+        return `${minutes}m ${remainingSeconds}s`;
+    return `${remainingSeconds}s`;
+}
+function formatBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 0)
+        return "unknown";
+    const units = ["B", "KiB", "MiB", "GiB", "TiB"];
+    let value = bytes;
+    let unitIndex = 0;
+    while (value >= 1024 && unitIndex < units.length - 1) {
+        value /= 1024;
+        unitIndex += 1;
+    }
+    return `${value.toFixed(unitIndex === 0 ? 0 : 1)} ${units[unitIndex]}`;
+}
+function truncateForDiagnostic(value, maxLength) {
+    const trimmed = value.trim();
+    if (trimmed.length <= maxLength)
+        return trimmed;
+    return `${trimmed.slice(0, maxLength)}...(truncated)`;
+}
+function formatDaemonShell() {
+    const shell = getEnvValue("SHELL");
+    if (shell)
+        return `SHELL=${shell}`;
+    const comspec = getEnvValue("ComSpec", "COMSPEC");
+    if (comspec)
+        return `ComSpec=${comspec}`;
+    return "unset";
+}
+function getEnvValue(...names) {
+    for (const name of names) {
+        const value = process.env[name];
+        if (value)
+            return value;
+    }
+    const lowerNames = new Set(names.map((name) => name.toLowerCase()));
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value && lowerNames.has(key.toLowerCase()))
+            return value;
+    }
+    return null;
+}
+function toErrorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "string")
+        return error;
+    return String(error);
+}
+export function redactDiagnostic(value, options) {
+    let redacted = value;
+    const sensitiveValues = [
+        options?.daemonRuntimeConfig?.listen,
+        options?.daemonRuntimeConfig?.relay?.endpoint,
+        options?.daemonRuntimeConfig?.relay?.publicEndpoint,
+    ].filter((item) => Boolean(item));
+    for (const sensitive of sensitiveValues) {
+        redacted = redacted.split(sensitive).join("[redacted]");
+    }
+    return redacted
+        .replace(/paseo:\/\/\S+/gi, "paseo://[redacted]")
+        .replace(/([?&](?:password|token|secret|key|publicKey|daemonPublicKeyB64)=)[^&\s"']+/gi, "$1[redacted]")
+        .replace(/((?:password|token|secret|authorization|api[_-]?key|daemonPublicKeyB64|relayKey)\s*[:=]\s*)("[^"]+"|'[^']+'|[^\s,}]+)/gi, "$1[redacted]");
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/server/server/session/daemon/install-origin.d.ts

@@ -0,0 +1,7 @@
+import { type NpmGlobalPaseoInstall } from "./npm-global-cli.js";
+export interface DaemonInstallOriginRuntime {
+    resolveCurrentServerPackageRoot(): string | null;
+}
+export declare const daemonInstallOriginRuntime: DaemonInstallOriginRuntime;
+export declare function validateDaemonInstallOrigin(install: NpmGlobalPaseoInstall, daemonVersion: string | null, runtime?: DaemonInstallOriginRuntime): string | null;
+//# sourceMappingURL=install-origin.d.ts.map

package/dist/server/server/session/daemon/install-origin.js

@@ -0,0 +1,64 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { isRealpathInsideRoot } from "../../../utils/path.js";
+import { PASEO_CLI_PACKAGE } from "./npm-global-cli.js";
+const PackageJsonSchema = z.object({ name: z.string().optional() }).passthrough();
+export const daemonInstallOriginRuntime = {
+    resolveCurrentServerPackageRoot,
+};
+export function validateDaemonInstallOrigin(install, daemonVersion, runtime = daemonInstallOriginRuntime) {
+    if (install.isLinked) {
+        return `The global ${PASEO_CLI_PACKAGE} install is linked; self-update only supports normal npm global installs.`;
+    }
+    if (daemonVersion && install.version !== daemonVersion) {
+        return `This daemon is not running from the npm global ${PASEO_CLI_PACKAGE} install (global npm has ${install.version}, daemon is ${daemonVersion}).`;
+    }
+    const currentServerPackageRoot = runtime.resolveCurrentServerPackageRoot();
+    if (!currentServerPackageRoot) {
+        return "Unable to verify that this daemon is running from an npm global install.";
+    }
+    if (!isCurrentServerUnderNpmInstall(currentServerPackageRoot, install)) {
+        return `This daemon is not running from the npm global ${PASEO_CLI_PACKAGE} install.`;
+    }
+    return null;
+}
+function isCurrentServerUnderNpmInstall(currentServerPackageRoot, install) {
+    const roots = install.globalRootPath
+        ? [install.packagePath, globalNodeModulesPath(install.globalRootPath)]
+        : [install.packagePath];
+    return roots.some((root) => isRealpathInsideRoot(root, currentServerPackageRoot));
+}
+function globalNodeModulesPath(globalRootPath) {
+    const normalized = path.normalize(globalRootPath);
+    return path.basename(normalized) === "node_modules"
+        ? normalized
+        : path.join(normalized, "node_modules");
+}
+function resolveCurrentServerPackageRoot() {
+    return resolvePackageRootFrom(fileURLToPath(import.meta.url), "@getpaseo/server");
+}
+function resolvePackageRootFrom(startPath, packageName) {
+    let currentDir = path.dirname(startPath);
+    while (true) {
+        const packageJsonPath = path.join(currentDir, "package.json");
+        if (existsSync(packageJsonPath)) {
+            try {
+                const packageJson = PackageJsonSchema.parse(JSON.parse(readFileSync(packageJsonPath, "utf8")));
+                if (packageJson.name === packageName) {
+                    return currentDir;
+                }
+            }
+            catch {
+                return null;
+            }
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) {
+            return null;
+        }
+        currentDir = parentDir;
+    }
+}
+//# sourceMappingURL=install-origin.js.map

package/dist/server/server/session/daemon/npm-global-cli.d.ts

@@ -0,0 +1,29 @@
+export declare const PASEO_CLI_PACKAGE = "@getpaseo/cli";
+export interface CommandOptions {
+    timeout?: number;
+    maxBuffer?: number;
+}
+export interface CommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface NpmGlobalPaseoInstall {
+    version: string;
+    packagePath: string;
+    globalRootPath: string | null;
+    isLinked: boolean;
+}
+export interface NpmGlobalPaseoCli {
+    inspect(): Promise<NpmGlobalPaseoInstall>;
+    installLatest(): Promise<CommandResult>;
+}
+export type CommandRunner = (command: string, args: string[], options?: CommandOptions) => Promise<CommandResult>;
+export declare class DefaultNpmGlobalPaseoCli implements NpmGlobalPaseoCli {
+    private readonly runCommand;
+    constructor(runCommand?: CommandRunner);
+    inspect(): Promise<NpmGlobalPaseoInstall>;
+    installLatest(): Promise<CommandResult>;
+}
+export declare const npmGlobalPaseoCli: DefaultNpmGlobalPaseoCli;
+//# sourceMappingURL=npm-global-cli.d.ts.map

package/dist/server/server/session/daemon/npm-global-cli.js

@@ -0,0 +1,98 @@
+import { getErrorMessage } from "@getpaseo/protocol/error-utils";
+import { z } from "zod";
+import { execCommand } from "../../../utils/spawn.js";
+export const PASEO_CLI_PACKAGE = "@getpaseo/cli";
+const NPM_PROBE_TIMEOUT_MS = 10000;
+const NPM_INSTALL_TIMEOUT_MS = 300000;
+const NPM_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
+const NpmGlobalListSchema = z
+    .object({
+    path: z.string().optional(),
+    dependencies: z.record(z.string(), z.unknown()).optional(),
+})
+    .passthrough();
+const NpmGlobalCliPackageSchema = z
+    .object({
+    version: z.string(),
+    path: z.string(),
+    link: z.boolean().optional(),
+})
+    .passthrough();
+const CommandErrorSchema = z
+    .object({
+    code: z.union([z.number(), z.string()]).optional(),
+    stdout: z.string().optional(),
+    stderr: z.string().optional(),
+})
+    .passthrough();
+async function runExternalCommand(command, args, options) {
+    try {
+        const { stdout, stderr } = await execCommand(command, args, {
+            timeout: options?.timeout,
+            maxBuffer: options?.maxBuffer,
+        });
+        return { exitCode: 0, stdout, stderr };
+    }
+    catch (error) {
+        const parsed = CommandErrorSchema.safeParse(error);
+        if (!parsed.success) {
+            return { exitCode: 1, stdout: "", stderr: getErrorMessage(error) };
+        }
+        return {
+            exitCode: typeof parsed.data.code === "number" ? parsed.data.code : 1,
+            stdout: parsed.data.stdout ?? "",
+            stderr: parsed.data.stderr || getErrorMessage(error),
+        };
+    }
+}
+function parseNpmGlobalPaseoInstall(stdout) {
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    const list = NpmGlobalListSchema.safeParse(parsedJson);
+    if (!list.success) {
+        return null;
+    }
+    const rawCliPackage = list.data.dependencies?.[PASEO_CLI_PACKAGE];
+    const cliPackage = NpmGlobalCliPackageSchema.safeParse(rawCliPackage);
+    if (!cliPackage.success) {
+        return null;
+    }
+    return {
+        version: cliPackage.data.version,
+        packagePath: cliPackage.data.path,
+        globalRootPath: list.data.path ?? null,
+        isLinked: cliPackage.data.link === true,
+    };
+}
+export class DefaultNpmGlobalPaseoCli {
+    constructor(runCommand = runExternalCommand) {
+        this.runCommand = runCommand;
+    }
+    async inspect() {
+        const result = await this.runCommand("npm", ["-g", "ls", PASEO_CLI_PACKAGE, "--json", "--depth=0", "--long"], {
+            timeout: NPM_PROBE_TIMEOUT_MS,
+            maxBuffer: NPM_MAX_BUFFER_BYTES,
+        });
+        if (result.exitCode !== 0 && result.stdout.trim().length === 0) {
+            throw new Error(result.stderr.trim() || "npm is not available on this host");
+        }
+        const install = parseNpmGlobalPaseoInstall(result.stdout);
+        if (!install) {
+            throw new Error(`${PASEO_CLI_PACKAGE} is not installed with npm -g on this host`);
+        }
+        return install;
+    }
+    installLatest() {
+        return this.runCommand("npm", ["install", "-g", `${PASEO_CLI_PACKAGE}@latest`], {
+            timeout: NPM_INSTALL_TIMEOUT_MS,
+            maxBuffer: NPM_MAX_BUFFER_BYTES,
+        });
+    }
+}
+export const npmGlobalPaseoCli = new DefaultNpmGlobalPaseoCli();
+//# sourceMappingURL=npm-global-cli.js.map

package/dist/server/server/session/git-mutation/git-mutation-service.d.ts

@@ -0,0 +1,34 @@
+import type pino from "pino";
+import type { GitHubService } from "../../../services/github-service.js";
+import { type CheckoutExistingBranchResult, type GitMutationRefreshReason } from "../../../utils/checkout-git.js";
+import type { WorkspaceGitService } from "../../workspace-git-service.js";
+/**
+ * The git branch / working-tree mutation primitives a client session performs on a
+ * workspace: switch to an existing branch, create a branch from a base, and force a
+ * snapshot refresh (plus optional GitHub cache invalidation) after any mutation.
+ *
+ * CheckoutSession (the branch/commit/merge commands), the worktree session-config
+ * builder, and the auto-naming + worktree-creation paths all funnel their git
+ * mutations through this one module, so the validate-ref → clean-tree → execute →
+ * refresh sequence lives in a single place instead of being smeared across the
+ * session as loose callbacks.
+ */
+export interface GitMutationService {
+    checkoutExistingBranch(cwd: string, branch: string): Promise<CheckoutExistingBranchResult>;
+    createBranchFromBase(params: {
+        cwd: string;
+        baseBranch: string;
+        newBranchName: string;
+    }): Promise<void>;
+    notifyGitMutation(cwd: string, reason: GitMutationRefreshReason, options?: {
+        invalidateGithub?: boolean;
+    }): Promise<void>;
+}
+type GitMutationGitSource = Pick<WorkspaceGitService, "validateBranchRef" | "getSnapshot" | "hasLocalBranch">;
+export declare function createGitMutationService(deps: {
+    workspaceGitService: GitMutationGitSource;
+    github: Pick<GitHubService, "invalidate">;
+    logger: pino.Logger;
+}): GitMutationService;
+export {};
+//# sourceMappingURL=git-mutation-service.d.ts.map