@tapi-dev/sdk 0.1.15 → 0.1.20

package/dist/cli.js

@@ -8,6 +8,7 @@ import { mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "n
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { performance } from "node:perf_hooks";
+import { emitKeypressEvents } from "node:readline";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -23,6 +24,9 @@ const DEFAULT_INSTALL_AUTH_TIMEOUT_MS = 120_000;
 const PORTABLE_STUDIO_SERVER_READY_TIMEOUT_MS = 30_000;
 const PORTABLE_STUDIO_SERVER_READY_INTERVAL_MS = 250;
 const MAX_WIDE_EVENT_PROCESS_ROOTS = 5;
+const MAX_NONCURRENT_MANAGED_DOWNLOADS = 0;
+const MAX_NONCURRENT_MANAGED_RELEASES = 0;
+const MANAGED_RELEASE_MARKER = ".tapi-managed-release";
 class StudioInstallApprovalError extends Error {
     code;
     status;
@@ -171,6 +175,23 @@ export async function runCli(argv = process.argv.slice(2)) {
         printTriggersHelp();
         return 1;
     }
+    if (command === "sessions") {
+        const sessionsCommand = subcommand && !subcommand.startsWith("-") ? subcommand : "list";
+        const sessionsArgs = subcommand && !subcommand.startsWith("-") ? rest : [subcommand, ...rest].filter(Boolean);
+        if (sessionsCommand === "help" || sessionsCommand === "--help" || sessionsCommand === "-h" || hasHelpFlag(sessionsArgs)) {
+            printSessionsHelp();
+            return 0;
+        }
+        if (sessionsCommand === "list") {
+            return listDevSessions(sessionsArgs);
+        }
+        if (sessionsCommand === "open") {
+            return openDevSession(sessionsArgs);
+        }
+        console.error(`Unknown sessions command: ${sessionsCommand}`);
+        printSessionsHelp();
+        return 1;
+    }
     if (command !== "studio") {
         console.error(`Unknown command: ${command}`);
         printHelp();
@@ -282,6 +303,14 @@ export function parseStudioOptions(args) {
             raw.cacheDir = resolve(arg.slice("--cache-dir=".length));
             continue;
         }
+        if (arg === "--install-dir") {
+            raw.installDir = resolve(requireOptionValue(args, ++index, "--install-dir"));
+            continue;
+        }
+        if (arg.startsWith("--install-dir=")) {
+            raw.installDir = resolve(arg.slice("--install-dir=".length));
+            continue;
+        }
         if (arg === "--exe") {
             raw.exePath = resolve(requireOptionValue(args, ++index, "--exe"));
             continue;
@@ -324,6 +353,7 @@ export function parseStudioOptions(args) {
         manifestUrl,
         manifestUrlOverride: explicitManifestUrl ? normalizeHttpUrl(explicitManifestUrl, "Studio manifest URL") : undefined,
         cacheDir: raw.cacheDir ?? getDefaultStudioCacheDir(),
+        installDir: raw.installDir ?? resolve(envString("TAPI_STUDIO_INSTALL_DIR") ?? getDefaultPortableStudioServerReleasesDir()),
         downloadOnly: raw.downloadOnly ?? false,
         silent: raw.silent ?? false,
         exePath: raw.exePath ?? envString("TAPI_STUDIO_EXE"),
@@ -603,6 +633,350 @@ async function syncApiTriggers(args) {
         return 1;
     }
 }
+function parseSessionsOptions(args) {
+    const workspace = loadWorkspace();
+    let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
+    let apiKey = envString("TAPI_API_KEY") || "";
+    let projectId = envString("TAPI_PROJECT_ID") || workspace?.projectId || "";
+    let site = "";
+    let sessionId = "";
+    let json = false;
+    let noInteractive = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg)
+            continue;
+        if (arg === "--api-base-url" || arg === "--server") {
+            apiBaseUrl = requireOptionValue(args, ++index, arg);
+            continue;
+        }
+        if (arg.startsWith("--api-base-url=")) {
+            apiBaseUrl = arg.slice("--api-base-url=".length);
+            continue;
+        }
+        if (arg.startsWith("--server=")) {
+            apiBaseUrl = arg.slice("--server=".length);
+            continue;
+        }
+        if (arg === "--api-key") {
+            apiKey = requireOptionValue(args, ++index, "--api-key");
+            continue;
+        }
+        if (arg.startsWith("--api-key=")) {
+            apiKey = arg.slice("--api-key=".length);
+            continue;
+        }
+        if (arg === "--project") {
+            projectId = normalizeProjectValue(requireOptionValue(args, ++index, "--project"), "project");
+            continue;
+        }
+        if (arg.startsWith("--project=")) {
+            projectId = normalizeProjectValue(arg.slice("--project=".length), "project");
+            continue;
+        }
+        if (arg === "--site") {
+            site = requireOptionValue(args, ++index, "--site").trim();
+            continue;
+        }
+        if (arg.startsWith("--site=")) {
+            site = arg.slice("--site=".length).trim();
+            continue;
+        }
+        if (arg === "--json") {
+            json = true;
+            noInteractive = true;
+            continue;
+        }
+        if (arg === "--no-interactive") {
+            noInteractive = true;
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            throw new Error(`Unknown sessions option: ${arg}`);
+        }
+        if (!sessionId) {
+            sessionId = arg;
+            continue;
+        }
+        throw new Error(`Unexpected sessions argument: ${arg}`);
+    }
+    if (!apiKey) {
+        throw new Error("sessions command requires --api-key or TAPI_API_KEY.");
+    }
+    if (!projectId) {
+        throw new Error("sessions command requires --project, TAPI_PROJECT_ID, or .tapi/project.json.");
+    }
+    return {
+        sessionId,
+        options: {
+            apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
+            apiKey,
+            projectId,
+            site: site || undefined,
+            json,
+            noInteractive,
+        },
+    };
+}
+async function listDevSessions(args) {
+    try {
+        const { options } = parseSessionsOptions(args);
+        const sessions = await fetchDevSessions(options);
+        if (options.json) {
+            console.log(JSON.stringify(sessions, null, 2));
+            return 0;
+        }
+        const rows = flattenDevSessions(sessions);
+        if (rows.length === 0) {
+            console.log(`No Tapi dev sessions found for project ${sessions.projectId || options.projectId}.`);
+            return 0;
+        }
+        if (!options.noInteractive && process.stdin.isTTY && process.stdout.isTTY && rows.some((session) => session.openable)) {
+            return await runSessionsPicker(sessions, options);
+        }
+        console.log(renderDevSessions(sessions));
+        const openable = rows.find((session) => session.openable);
+        if (openable) {
+            console.log("\nOpen a takeover session with `tapi sessions open <session-id>`.");
+        }
+        return 0;
+    }
+    catch (error) {
+        console.error(formatError(error));
+        return 1;
+    }
+}
+async function openDevSession(args) {
+    try {
+        const { sessionId, options } = parseSessionsOptions(args);
+        if (!sessionId) {
+            throw new Error("sessions open requires a session id.");
+        }
+        const sessions = await fetchDevSessions(options);
+        const session = findDevSession(sessions, sessionId);
+        if (!session) {
+            throw new Error(`Tapi session not found: ${sessionId}`);
+        }
+        return await openDevSessionInStudio(session, options);
+    }
+    catch (error) {
+        console.error(formatError(error));
+        return 1;
+    }
+}
+async function fetchDevSessions(options) {
+    const client = new TapiClient({
+        baseUrl: options.apiBaseUrl,
+        apiKey: options.apiKey,
+        projectId: options.projectId,
+    });
+    return await withCliSpinner("Fetching Tapi dev sessions", () => client.sessions.list({ site: options.site }));
+}
+function flattenDevSessions(sessions) {
+    return (sessions.groups || []).flatMap((group) => group.sessions || []);
+}
+function findDevSession(sessions, sessionId) {
+    const normalized = sessionId.trim();
+    return flattenDevSessions(sessions).find((session) => session.id === normalized || session.id.startsWith(normalized));
+}
+async function runSessionsPicker(sessions, options) {
+    let currentSessions = sessions;
+    let rows = flattenDevSessions(currentSessions);
+    let openableIndexes = openableSessionIndexes(rows);
+    if (openableIndexes.length === 0) {
+        console.log(renderDevSessions(currentSessions));
+        return 0;
+    }
+    let selectedIndex = openableIndexes[0];
+    const input = process.stdin;
+    return await new Promise((resolvePromise) => {
+        let onKeypress;
+        const cleanup = () => {
+            input.off("keypress", onKeypress);
+            input.setRawMode?.(false);
+            input.pause();
+        };
+        const move = (direction) => {
+            if (openableIndexes.length === 0)
+                return;
+            const currentOpenableIndex = openableIndexes.indexOf(selectedIndex);
+            const nextOpenableIndex = (currentOpenableIndex + direction + openableIndexes.length) % openableIndexes.length;
+            selectedIndex = openableIndexes[nextOpenableIndex];
+            render();
+        };
+        const render = () => {
+            process.stdout.write("\x1Bc");
+            process.stdout.write(renderDevSessions(currentSessions, rows[selectedIndex]?.id));
+            process.stdout.write("\n\nUse Up/Down and Enter to open Studio. Press r to refresh, q to exit.\n");
+        };
+        const finish = (code) => {
+            cleanup();
+            resolvePromise(code);
+        };
+        onKeypress = (_input, key = {}) => {
+            if (key.ctrl && key.name === "c") {
+                finish(130);
+                return;
+            }
+            if (key.name === "q" || key.name === "escape") {
+                finish(0);
+                return;
+            }
+            if (key.name === "up") {
+                move(-1);
+                return;
+            }
+            if (key.name === "down") {
+                move(1);
+                return;
+            }
+            if (key.name === "r") {
+                fetchDevSessions(options)
+                    .then((nextSessions) => {
+                    currentSessions = nextSessions;
+                    rows = flattenDevSessions(currentSessions);
+                    openableIndexes = openableSessionIndexes(rows);
+                    if (!rows[selectedIndex]?.openable) {
+                        selectedIndex = openableIndexes[0] ?? 0;
+                    }
+                    render();
+                })
+                    .catch((error) => {
+                    process.stderr.write(`\n${formatError(error)}\n`);
+                    render();
+                });
+                return;
+            }
+            if (key.name === "return" || key.name === "enter") {
+                const session = rows[selectedIndex];
+                if (!session?.openable) {
+                    return;
+                }
+                cleanup();
+                openDevSessionInStudio(session, options)
+                    .then(resolvePromise)
+                    .catch((error) => {
+                    console.error(formatError(error));
+                    resolvePromise(1);
+                });
+            }
+        };
+        emitKeypressEvents(input);
+        input.setRawMode?.(true);
+        input.resume();
+        input.on("keypress", onKeypress);
+        render();
+    });
+}
+function openableSessionIndexes(rows) {
+    return rows
+        .map((session, index) => (session.openable ? index : -1))
+        .filter((index) => index >= 0);
+}
+async function openDevSessionInStudio(session, options) {
+    if (!session.openable) {
+        throw new Error(`Tapi session ${session.id} is not awaiting developer takeover.`);
+    }
+    const params = studioSessionLaunchParams(session);
+    const studioOptions = parseStudioOptions([
+        "--api-base-url",
+        options.apiBaseUrl,
+        "--project",
+        options.projectId,
+    ]);
+    studioOptions.launchUrlQuery = params.toString();
+    const selected = await trySelectDevSessionInOpenStudio(session, studioOptions);
+    if (selected.selected) {
+        console.log(`Selected Tapi Studio session in existing Studio: ${selected.baseUrl}`);
+        return 0;
+    }
+    return await openStudio(studioOptions);
+}
+function studioSessionLaunchParams(session) {
+    const params = new URLSearchParams();
+    params.set("runId", session.id);
+    params.set("apiRunId", session.id);
+    if (session.sitemap)
+        params.set("sitemap", session.sitemap);
+    if (session.runtimeSessionId)
+        params.set("runtimeSessionId", session.runtimeSessionId);
+    return params;
+}
+function studioSessionSelectIntent(session) {
+    return {
+        sessionId: session.id,
+        runId: session.id,
+        apiRunId: session.id,
+        ...(session.sitemap ? { sitemap: session.sitemap } : {}),
+        ...(session.runtimeSessionId ? { runtimeSessionId: session.runtimeSessionId } : {}),
+        source: "cli",
+        selectedAt: new Date().toISOString(),
+    };
+}
+export async function trySelectDevSessionInOpenStudio(session, options, fetchImpl = fetch) {
+    const record = await readStudioInstanceRecord(options);
+    if (!record) {
+        return { selected: false, reason: "instance_record_missing" };
+    }
+    try {
+        const identityResponse = await fetchWithTimeout(`${record.baseUrl.replace(/\/+$/, "")}/api/studio/control/identity`, { headers: { Accept: "application/json" } }, 1_000, fetchImpl);
+        if (!identityResponse.ok) {
+            await unlinkIfExists(studioInstanceRecordPathForOptions(options));
+            return { selected: false, reason: `identity_http_${identityResponse.status}` };
+        }
+        const identity = await readJsonBody(identityResponse);
+        if (!studioInstanceIdentityMatches(identity, options)) {
+            return { selected: false, reason: "identity_mismatch" };
+        }
+        const selectResponse = await fetchWithTimeout(`${record.baseUrl.replace(/\/+$/, "")}/api/studio/control/select-session`, {
+            method: "POST",
+            headers: {
+                Accept: "application/json",
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(studioSessionSelectIntent(session)),
+        }, 1_500, fetchImpl);
+        if (!selectResponse.ok) {
+            return { selected: false, reason: `select_http_${selectResponse.status}` };
+        }
+        return { selected: true, baseUrl: record.baseUrl };
+    }
+    catch (error) {
+        return { selected: false, reason: formatError(error) };
+    }
+}
+function renderDevSessions(sessions, selectedId = "") {
+    const lines = [`Tapi sessions for project ${sessions.projectId || "unknown"}`];
+    for (const group of sessions.groups || []) {
+        lines.push("");
+        lines.push(`[${group.sitemap || "unknown"}]`);
+        if (!group.sessions || group.sessions.length === 0) {
+            lines.push("  No sessions.");
+            continue;
+        }
+        for (const session of group.sessions) {
+            const selected = selectedId && session.id === selectedId ? ">" : " ";
+            const openable = session.openable ? "*" : " ";
+            const id = truncateText(session.id || "", 18).padEnd(18, " ");
+            const status = truncateText(String(session.status || ""), 24).padEnd(24, " ");
+            const apiName = session.apiName && session.requestKey
+                ? `${session.apiName}.${session.requestKey}`
+                : session.apiName || session.requestKey || "unknown";
+            const state = session.stateLabel ? ` state=${session.stateLabel}` : "";
+            const url = session.currentUrl ? ` ${truncateText(session.currentUrl, 60)}` : "";
+            lines.push(`${selected}${openable} ${id} ${status} ${apiName}${state}${url}`);
+        }
+    }
+    lines.push("");
+    lines.push("* openable awaiting-takeover session");
+    return lines.join("\n");
+}
+function truncateText(value, maxLength) {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return `${value.slice(0, Math.max(0, maxLength - 3))}...`;
+}
 function defaultTriggerConfigPath(root) {
     for (const name of ["tapi.config.ts", "tapi.config.mjs", "tapi.config.js", "tapi.config.cjs", "tapi.config.json"]) {
         const path = join(root, name);
@@ -844,23 +1218,23 @@ function renderGeneratedApiClient(catalog) {
         const lines = operations.map(({ key, operationName }) => `    ${operationName}: (inputs: Record<string, unknown> = {}, options: GeneratedRunOptions = {}) => client.websiteApis.run(${JSON.stringify(key)}, { ...options, inputs }),`);
         return `  ${namespace}: {\n${lines.join("\n")}\n  },`;
     });
-    return `/* Generated by Tapi. Do not edit by hand. */
-import { TapiClient, type TapiClientOptions, type RuntimeRunOptions } from "@tapi-dev/sdk";
-
-export interface GeneratedRunOptions {
-  runtime?: RuntimeRunOptions;
-  priority?: number;
-  runnerId?: string;
-  idempotencyKey?: string;
-  site?: string;
-}
-
-export function createTapiGeneratedClient(options: TapiClientOptions) {
-  const client = new TapiClient(options);
-  return {
-${namespaceBlocks.join("\n")}
-  };
-}
+    return `/* Generated by Tapi. Do not edit by hand. */
+import { TapiClient, type TapiClientOptions, type RuntimeRunOptions } from "@tapi-dev/sdk";
+
+export interface GeneratedRunOptions {
+  runtime?: RuntimeRunOptions;
+  priority?: number;
+  runnerId?: string;
+  idempotencyKey?: string;
+  site?: string;
+}
+
+export function createTapiGeneratedClient(options: TapiClientOptions) {
+  const client = new TapiClient(options);
+  return {
+${namespaceBlocks.join("\n")}
+  };
+}
 `;
 }
 function safeIdentifier(value) {
@@ -1074,18 +1448,7 @@ async function fetchServiceManifestForEnsure(options) {
         options: installEventOptions(options),
     });
     try {
-        let installToken = options.installToken?.trim();
-        if (!installToken) {
-            await event.phase("auth.install_token.request.start", {
-                apiBaseUrl: options.apiBaseUrl,
-                channel: options.channel,
-            });
-            installToken = await withCliSpinner("Checking Tapi Service install approval", () => obtainStudioInstallToken(options, event));
-            await event.phase("auth.install_token.request.success", {
-                apiBaseUrl: options.apiBaseUrl,
-                channel: options.channel,
-            });
-        }
+        const installToken = await ensureStudioInstallTokenForRun(options, event, "Checking Tapi Service install authorization");
         await event.phase("service_manifest.fetch.start", {
             apiBaseUrl: options.apiBaseUrl,
             channel: options.channel,
@@ -1148,18 +1511,7 @@ async function installService(options) {
             arch: process.arch,
         });
         ensureWindowsHost();
-        let installToken = options.installToken?.trim();
-        if (!installToken) {
-            await event.phase("auth.install_token.request.start", {
-                apiBaseUrl: options.apiBaseUrl,
-                channel: options.channel,
-            });
-            installToken = await withCliSpinner("Checking Tapi Service install approval", () => obtainStudioInstallToken(options, event));
-            await event.phase("auth.install_token.request.success", {
-                apiBaseUrl: options.apiBaseUrl,
-                channel: options.channel,
-            });
-        }
+        const installToken = await ensureStudioInstallTokenForRun(options, event, "Checking Tapi Service install authorization");
         await event.phase("service_manifest.fetch.start", {
             apiBaseUrl: options.apiBaseUrl,
             channel: options.channel,
@@ -1202,6 +1554,7 @@ async function installService(options) {
         }
         const releaseDir = join(releasesDir, safePathSegment(manifest.version));
         await withCliSpinner(`Extracting Tapi Service ${manifest.version}`, () => extractZip(zipPath, releaseDir));
+        await markManagedReleaseDir(releaseDir, manifest.version);
         const installer = join(releaseDir, manifest.installer || "install_tapi_service.ps1");
         const hostExe = join(releaseDir, manifest.serviceHostExecutable || "tapi-service-host.exe");
         if (!existsSync(installer)) {
@@ -1243,6 +1596,8 @@ async function installService(options) {
             releaseDir,
             version: manifest.version,
         });
+        await pruneManagedFiles(downloadsDir, [zipPath], isTapiServiceDownloadArtifact, MAX_NONCURRENT_MANAGED_DOWNLOADS, "old Tapi Service download");
+        await pruneManagedDirs(releasesDir, [releaseDir], isSafeManagedReleaseDirName, MAX_NONCURRENT_MANAGED_RELEASES, "old Tapi Service release");
         console.log("Tapi Service is installed and running.");
         return 0;
     }
@@ -1395,6 +1750,10 @@ async function requestJson(method, url, body, apiKey, projectId) {
     }
 }
 export function getDefaultStudioCacheDir() {
+    const homeOverride = envString("TAPI_STUDIO_HOME");
+    if (homeOverride) {
+        return join(resolve(homeOverride), "downloads");
+    }
     if (process.platform === "win32") {
         const localAppData = process.env.LOCALAPPDATA ??
             (process.env.USERPROFILE ? join(process.env.USERPROFILE, "AppData", "Local") : join(homedir(), "AppData", "Local"));
@@ -1716,24 +2075,7 @@ async function installStudio(options) {
             throw new Error("Direct Studio manifest overrides are no longer supported for install. "
                 + "Use --channel with the protected install flow instead.");
         }
-        let installToken = options.installToken?.trim();
-        if (installToken) {
-            await event.phase("auth.install_token.provided", {
-                apiBaseUrl: options.apiBaseUrl,
-                channel: options.channel,
-            });
-        }
-        else {
-            await event.phase("auth.install_token.request.start", {
-                apiBaseUrl: options.apiBaseUrl,
-                channel: options.channel,
-            });
-            installToken = await withCliSpinner("Checking Studio install approval", () => obtainStudioInstallToken(options, event));
-            await event.phase("auth.install_token.request.success", {
-                apiBaseUrl: options.apiBaseUrl,
-                channel: options.channel,
-            });
-        }
+        const installToken = await ensureStudioInstallTokenForRun(options, event, "Checking Studio install authorization");
         await event.phase("manifest.fetch.start", {
             apiBaseUrl: options.apiBaseUrl,
             channel: options.channel,
@@ -1852,6 +2194,39 @@ async function obtainStudioInstallToken(options, event) {
     const issued = await requestStudioInstallToken(options.apiBaseUrl, options.channel, firebaseCreds.idToken);
     return issued.installToken;
 }
+export function memoizeStudioInstallToken(options, installToken) {
+    const existing = options.installToken?.trim();
+    if (existing) {
+        options.installToken = existing;
+        return existing;
+    }
+    const normalized = installToken?.trim() ?? "";
+    if (normalized) {
+        options.installToken = normalized;
+    }
+    return normalized;
+}
+async function ensureStudioInstallTokenForRun(options, event, message) {
+    const existing = memoizeStudioInstallToken(options);
+    if (existing) {
+        await event.phase("auth.install_token.reused", {
+            apiBaseUrl: options.apiBaseUrl,
+            channel: options.channel,
+        });
+        return existing;
+    }
+    await event.phase("auth.install_token.request.start", {
+        apiBaseUrl: options.apiBaseUrl,
+        channel: options.channel,
+    });
+    const installToken = memoizeStudioInstallToken(options, await withCliSpinner(message, () => obtainStudioInstallToken(options, event)));
+    await event.phase("auth.install_token.request.success", {
+        apiBaseUrl: options.apiBaseUrl,
+        channel: options.channel,
+        cachedForRun: true,
+    });
+    return installToken;
+}
 async function openStudio(options) {
     ensureWindowsHost();
     if (options.downloadOnly) {
@@ -1876,7 +2251,7 @@ async function openStudio(options) {
     }
     if (!exePath || !existsSync(exePath)) {
         console.error("Tapi Studio executable was not found.");
-        console.error("Run `npx tapi studio install --channel pilot`, or set TAPI_STUDIO_EXE to the installed executable path.");
+        console.error("Run `tapi studio install --channel pilot`, or set TAPI_STUDIO_EXE to the installed executable path.");
         return 1;
     }
     const child = spawn(exePath, [], {
@@ -1901,18 +2276,7 @@ async function ensurePortableStudioServer(options) {
         options: installEventOptions(options),
     });
     try {
-        let installToken = options.installToken?.trim();
-        if (!installToken) {
-            await event.phase("auth.install_token.request.start", {
-                apiBaseUrl: options.apiBaseUrl,
-                channel: options.channel,
-            });
-            installToken = await withCliSpinner("Checking Studio install approval", () => obtainStudioInstallToken(options, event));
-            await event.phase("auth.install_token.request.success", {
-                apiBaseUrl: options.apiBaseUrl,
-                channel: options.channel,
-            });
-        }
+        const installToken = await ensureStudioInstallTokenForRun(options, event, "Checking Studio install authorization");
         await event.phase("manifest.fetch.start", {
             apiBaseUrl: options.apiBaseUrl,
             channel: options.channel,
@@ -1928,7 +2292,7 @@ async function ensurePortableStudioServer(options) {
             });
             return null;
         }
-        const existing = findPortableStudioServerExe(portableStudioServerReleaseDir(manifest), manifest);
+        const existing = findPortableStudioServerExe(portableStudioServerReleaseDir(manifest, options.installDir), manifest);
         if (existing) {
             await event.finish(true, {
                 serverExe: existing,
@@ -1972,14 +2336,13 @@ async function installPortableStudioServer(options, manifest, event) {
     }
     if (options.downloadOnly) {
         console.log(`Downloaded Tapi Studio server artifact: ${artifactPath}`);
+        await pruneManagedFiles(options.cacheDir, [artifactPath], isTapiStudioDownloadArtifact, MAX_NONCURRENT_MANAGED_DOWNLOADS, "old Tapi Studio download");
         return artifactPath;
     }
-    const releaseDir = portableStudioServerReleaseDir(manifest);
-    await withCliSpinner(`Extracting Tapi Studio server ${manifest.version}`, () => extractZip(artifactPath, releaseDir));
-    const exePath = findPortableStudioServerExe(releaseDir, manifest);
-    if (!exePath) {
-        throw new Error(`Tapi Studio server executable was not found after extraction: ${releaseDir}`);
-    }
+    const releaseDir = portableStudioServerReleaseDir(manifest, options.installDir);
+    const exePath = await withCliSpinner(`Extracting Tapi Studio server ${manifest.version}`, () => extractPortableStudioServerZip(artifactPath, releaseDir, manifest));
+    await pruneManagedFiles(options.cacheDir, [artifactPath], isTapiStudioDownloadArtifact, MAX_NONCURRENT_MANAGED_DOWNLOADS, "old Tapi Studio download");
+    await pruneManagedDirs(dirname(releaseDir), [releaseDir], isSafeManagedReleaseDirName, MAX_NONCURRENT_MANAGED_RELEASES, "old Tapi Studio server release");
     console.log(`Installed Tapi Studio server ${manifest.version}: ${releaseDir}`);
     return exePath;
 }
@@ -2003,6 +2366,9 @@ async function launchPortableStudioServer(exePath, options, manifest) {
         env.PLAYWRIGHT_BROWSERS_PATH = playwrightBrowsersPath;
     }
     const url = `http://${host}:${port}`;
+    const launchQuery = options.launchUrlQuery ? options.launchUrlQuery.replace(/^\?+/, "") : "";
+    const launchUrl = launchQuery ? `${url}/?${launchQuery}` : url;
+    let childPid = 0;
     await withCliSpinner("Starting Tapi Studio", async () => {
         const child = spawn(exePath, [], {
             detached: true,
@@ -2010,11 +2376,25 @@ async function launchPortableStudioServer(exePath, options, manifest) {
             stdio: "ignore",
             windowsHide: true,
         });
+        childPid = child.pid ?? 0;
         child.unref();
         await waitForHttpOk(`${url}/healthz`, PORTABLE_STUDIO_SERVER_READY_TIMEOUT_MS, PORTABLE_STUDIO_SERVER_READY_INTERVAL_MS);
     });
-    openBrowser(url);
-    console.log(`Opened Tapi Studio ${manifest.version}: ${url}`);
+    await writeStudioInstanceRecord(options, {
+        version: 1,
+        baseUrl: url,
+        host,
+        port,
+        pid: childPid || undefined,
+        apiBaseUrl: options.apiBaseUrl,
+        projectId: options.projectId,
+        workspaceRoot: options.workspaceRoot,
+        workspaceConfig: options.workspace?.configPath,
+        manifestVersion: manifest.version,
+        updatedAt: new Date().toISOString(),
+    });
+    openBrowser(launchUrl);
+    console.log(`Opened Tapi Studio ${manifest.version}: ${launchUrl}`);
 }
 export function findPortablePlaywrightBrowsersDir(exePath) {
     const exeDir = dirname(exePath);
@@ -2060,6 +2440,19 @@ export async function waitForHttpOk(url, timeoutMs = PORTABLE_STUDIO_SERVER_READ
     const suffix = lastError ? ` Last error: ${lastError}.` : "";
     throw new Error(`Tapi Studio server did not become ready at ${url} within ${Math.ceil(timeoutMs / 1000)}s.${suffix}`);
 }
+async function fetchWithTimeout(url, init, timeoutMs, fetchImpl = fetch) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), Math.max(1, timeoutMs));
+    try {
+        return await fetchImpl(url, {
+            ...init,
+            signal: controller.signal,
+        });
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
 function delay(ms) {
     return new Promise((resolvePromise) => {
         setTimeout(resolvePromise, Math.max(0, ms));
@@ -2183,7 +2576,7 @@ async function requestStudioInstallToken(apiBaseUrl, channel, firebaseIdToken, f
     if (!response.ok) {
         const detail = typeof responseBody?.detail === "string" ? responseBody.detail : "";
         if (detail === "pending_approval" || detail === "access_pending") {
-            throw new StudioInstallApprovalError("Access request submitted. Check your email for approval, then rerun `npx tapi studio install`.", detail, response.status);
+            throw new StudioInstallApprovalError("Access request submitted. Check your email for approval, then rerun `tapi studio install`.", detail, response.status);
         }
         if (detail === "access_rejected") {
             throw new StudioInstallApprovalError("Studio install access was rejected. Contact the Tapi admin if this is unexpected.", detail, response.status);
@@ -2370,6 +2763,81 @@ async function writeStudioAuthCache(credentials) {
 function getStudioAuthCachePath() {
     return join(getDefaultTapiDataDir(), "auth.json");
 }
+export function studioInstanceRecordPathForOptions(options) {
+    const key = createHash("sha256")
+        .update(JSON.stringify({
+        apiBaseUrl: comparableHttpUrl(options.apiBaseUrl),
+        projectId: options.projectId ?? "",
+        workspaceRoot: comparableFsPath(options.workspaceRoot ?? ""),
+    }))
+        .digest("hex")
+        .slice(0, 24);
+    return join(getDefaultTapiDataDir(), "Studio", "instances", `${key}.json`);
+}
+async function writeStudioInstanceRecord(options, record) {
+    await writeJsonFile(studioInstanceRecordPathForOptions(options), record);
+}
+async function readStudioInstanceRecord(options) {
+    try {
+        const parsed = JSON.parse(await readFile(studioInstanceRecordPathForOptions(options), "utf8"));
+        if (!isRecord(parsed)) {
+            return null;
+        }
+        const baseUrl = typeof parsed.baseUrl === "string" ? parsed.baseUrl.trim() : "";
+        const host = typeof parsed.host === "string" ? parsed.host.trim() : "";
+        const port = typeof parsed.port === "number" && Number.isFinite(parsed.port) ? parsed.port : 0;
+        if (!baseUrl || !host || port <= 0) {
+            return null;
+        }
+        return {
+            version: 1,
+            baseUrl,
+            host,
+            port,
+            pid: typeof parsed.pid === "number" && Number.isFinite(parsed.pid) ? parsed.pid : undefined,
+            apiBaseUrl: typeof parsed.apiBaseUrl === "string" ? parsed.apiBaseUrl : "",
+            projectId: typeof parsed.projectId === "string" ? parsed.projectId : undefined,
+            workspaceRoot: typeof parsed.workspaceRoot === "string" ? parsed.workspaceRoot : undefined,
+            workspaceConfig: typeof parsed.workspaceConfig === "string" ? parsed.workspaceConfig : undefined,
+            manifestVersion: typeof parsed.manifestVersion === "string" ? parsed.manifestVersion : undefined,
+            updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : "",
+        };
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return null;
+        }
+        return null;
+    }
+}
+function studioInstanceIdentityMatches(identity, options) {
+    if (!identity || identity.ok !== true) {
+        return false;
+    }
+    const expectedProject = (options.projectId ?? "").trim();
+    const actualProject = typeof identity.projectId === "string" ? identity.projectId.trim() : "";
+    if (expectedProject && actualProject && actualProject !== expectedProject) {
+        return false;
+    }
+    const expectedWorkspace = comparableFsPath(options.workspaceRoot ?? "");
+    const actualWorkspace = comparableFsPath(typeof identity.workspaceRoot === "string" ? identity.workspaceRoot : "");
+    if (expectedWorkspace && actualWorkspace && actualWorkspace !== expectedWorkspace) {
+        return false;
+    }
+    const expectedApiBaseUrl = comparableHttpUrl(options.apiBaseUrl);
+    const actualApiBaseUrl = comparableHttpUrl(typeof identity.apiBaseUrl === "string" ? identity.apiBaseUrl : "");
+    if (expectedApiBaseUrl && actualApiBaseUrl && actualApiBaseUrl !== expectedApiBaseUrl) {
+        return false;
+    }
+    return true;
+}
+function comparableHttpUrl(value) {
+    return String(value || "").trim().replace(/\/+$/, "").toLowerCase();
+}
+function comparableFsPath(value) {
+    const trimmed = String(value || "").trim();
+    return trimmed ? resolve(trimmed).toLowerCase() : "";
+}
 function getDefaultTapiDataDir() {
     if (process.platform === "win32") {
         const localAppData = process.env.LOCALAPPDATA
@@ -2493,10 +2961,14 @@ function isPortableStudioServerManifest(manifest) {
     const kind = String(manifest.installerKind || "").toLowerCase();
     return kind === "portable-server" || manifest.artifactName.toLowerCase().endsWith(".zip");
 }
-function portableStudioServerReleaseDir(manifest) {
-    return join(getDefaultPortableStudioServerReleasesDir(), safePathSegment(manifest.version));
+function portableStudioServerReleaseDir(manifest, releasesDir = getDefaultPortableStudioServerReleasesDir()) {
+    return join(releasesDir, safePathSegment(manifest.version));
 }
 function getDefaultPortableStudioServerReleasesDir() {
+    const homeOverride = envString("TAPI_STUDIO_HOME");
+    if (homeOverride) {
+        return join(resolve(homeOverride), "server", "releases");
+    }
     if (process.platform === "win32") {
         const localAppData = process.env.LOCALAPPDATA ??
             (process.env.USERPROFILE ? join(process.env.USERPROFILE, "AppData", "Local") : join(homedir(), "AppData", "Local"));
@@ -2519,6 +2991,34 @@ export function findPortableStudioServerExe(releaseDir, manifest) {
     ];
     return candidates.find((candidate) => existsSync(candidate));
 }
+async function extractPortableStudioServerZip(zipPath, releaseDir, manifest) {
+    const stagingDir = `${releaseDir}.extracting-${process.pid}-${Date.now()}`;
+    const existingExe = findPortableStudioServerExe(releaseDir, manifest);
+    if (!existingExe) {
+        await rm(releaseDir, { recursive: true, force: true });
+    }
+    await rm(stagingDir, { recursive: true, force: true });
+    try {
+        await extractZip(zipPath, stagingDir);
+        const stagedExe = findPortableStudioServerExe(stagingDir, manifest);
+        if (!stagedExe) {
+            throw new Error(`Tapi Studio server executable was not found after extraction. Expected ${manifest.serverExecutable || "tapi-studio-server.exe"} under ${stagingDir}.`);
+        }
+        await rm(releaseDir, { recursive: true, force: true });
+        await mkdir(dirname(releaseDir), { recursive: true });
+        await rename(stagingDir, releaseDir);
+        await markManagedReleaseDir(releaseDir, manifest.version);
+        const finalExe = findPortableStudioServerExe(releaseDir, manifest);
+        if (!finalExe) {
+            throw new Error(`Tapi Studio server executable disappeared while finalizing extraction: ${releaseDir}`);
+        }
+        return finalExe;
+    }
+    catch (error) {
+        await rm(stagingDir, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+    }
+}
 function cachedServiceArtifactName(manifest) {
     const rawName = manifest.artifactName || basename(new URL(manifest.url).pathname) || `TapiService-${manifest.version}.zip`;
     return rawName.replace(/[^A-Za-z0-9._-]/g, "_");
@@ -2526,13 +3026,141 @@ function cachedServiceArtifactName(manifest) {
 async function extractZip(zipPath, destination) {
     await rm(destination, { recursive: true, force: true });
     await mkdir(destination, { recursive: true });
-    await runProcessCapture("powershell.exe", [
-        "-NoProfile",
-        "-ExecutionPolicy",
-        "Bypass",
-        "-Command",
-        `Expand-Archive -LiteralPath ${powerShellSingleQuoted(zipPath)} -DestinationPath ${powerShellSingleQuoted(destination)} -Force`,
-    ]);
+    try {
+        await runProcessCapture("powershell.exe", [
+            "-NoProfile",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-Command",
+            buildExpandArchiveCommand(zipPath, destination),
+        ]);
+    }
+    catch (error) {
+        throw new Error(formatZipExtractionFailure(zipPath, destination, error), { cause: error });
+    }
+}
+export function buildExpandArchiveCommand(zipPath, destination) {
+    return `$ErrorActionPreference = 'Stop'; try { Expand-Archive -LiteralPath ${powerShellSingleQuoted(zipPath)} -DestinationPath ${powerShellSingleQuoted(destination)} -Force -ErrorAction Stop } catch { Write-Error $_; exit 1 }`;
+}
+export function formatZipExtractionFailure(zipPath, destination, error) {
+    const detail = formatError(error);
+    const diskHint = /not enough space|no space left|disk full/i.test(detail)
+        ? " Free disk space on that drive, or set TAPI_STUDIO_HOME / --cache-dir / --install-dir to paths on a drive with more room."
+        : "";
+    return `Failed to extract archive ${zipPath} to ${destination}: ${detail}${diskHint}`;
+}
+export async function pruneManagedFiles(directory, keepPaths, isManagedFileName, maxNoncurrentEntries = 0, label = "old Tapi download") {
+    const keep = normalizedKeepPathSet(keepPaths);
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    const candidates = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !isManagedFileName(entry.name)) {
+            continue;
+        }
+        const candidate = join(directory, entry.name);
+        if (keep.has(normalizeFilesystemPath(candidate))) {
+            continue;
+        }
+        const info = await stat(candidate).catch(() => undefined);
+        if (!info?.isFile()) {
+            continue;
+        }
+        candidates.push({ path: candidate, mtimeMs: info.mtimeMs });
+    }
+    candidates.sort((left, right) => right.mtimeMs - left.mtimeMs);
+    const removable = candidates.slice(Math.max(0, maxNoncurrentEntries));
+    let removed = 0;
+    for (const candidate of removable) {
+        try {
+            await rm(candidate.path, { force: true });
+            removed += 1;
+        }
+        catch {
+            // Cache pruning is best effort; install success should not depend on cleanup.
+        }
+    }
+    if (removed > 0) {
+        console.log(`Pruned ${removed} ${label}${removed === 1 ? "" : "s"}.`);
+    }
+    return removed;
+}
+async function pruneManagedDirs(directory, keepPaths, isManagedDirName, maxNoncurrentEntries = 0, label = "old Tapi release") {
+    const keep = normalizedKeepPathSet(keepPaths);
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    const candidates = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !isManagedDirName(entry.name)) {
+            continue;
+        }
+        const candidate = join(directory, entry.name);
+        if (keep.has(normalizeFilesystemPath(candidate))) {
+            continue;
+        }
+        if (!existsSync(join(candidate, MANAGED_RELEASE_MARKER))) {
+            continue;
+        }
+        const info = await stat(candidate).catch(() => undefined);
+        if (!info?.isDirectory()) {
+            continue;
+        }
+        candidates.push({ path: candidate, mtimeMs: info.mtimeMs });
+    }
+    candidates.sort((left, right) => right.mtimeMs - left.mtimeMs);
+    const removable = candidates.slice(Math.max(0, maxNoncurrentEntries));
+    let removed = 0;
+    for (const candidate of removable) {
+        try {
+            await rm(candidate.path, { recursive: true, force: true });
+            removed += 1;
+        }
+        catch {
+            // Cache pruning is best effort; install success should not depend on cleanup.
+        }
+    }
+    if (removed > 0) {
+        console.log(`Pruned ${removed} ${label}${removed === 1 ? "" : "s"}.`);
+    }
+    return removed;
+}
+export function isTapiStudioDownloadArtifact(fileName) {
+    const normalized = fileName.toLowerCase();
+    return (normalized.endsWith(".zip")
+        && (normalized.startsWith("tapi-studio")
+            || normalized.startsWith("tapistudio")
+            || normalized.includes("tapi_studio")));
+}
+export function isTapiServiceDownloadArtifact(fileName) {
+    const normalized = fileName.toLowerCase();
+    return normalized.endsWith(".zip") && (normalized.startsWith("tapiservice-") || normalized.startsWith("tapi-service"));
+}
+function isSafeManagedReleaseDirName(name) {
+    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name);
+}
+async function markManagedReleaseDir(directory, version) {
+    const payload = JSON.stringify({
+        product: "tapi",
+        version,
+        managedBy: "@tapi-dev/sdk",
+    });
+    await writeFile(join(directory, MANAGED_RELEASE_MARKER), `${payload}\n`).catch(() => undefined);
+}
+function normalizedKeepPathSet(paths) {
+    return new Set(paths.map((path) => normalizeFilesystemPath(path)));
+}
+function normalizeFilesystemPath(path) {
+    return resolve(path).replace(/\\/g, "/").toLowerCase();
 }
 function installEventOptions(options) {
     return {
@@ -2541,6 +3169,7 @@ function installEventOptions(options) {
         manifestUrl: options.manifestUrl,
         manifestUrlOverride: options.manifestUrlOverride,
         cacheDir: options.cacheDir,
+        installDir: options.installDir,
         downloadOnly: options.downloadOnly,
         silent: options.silent,
         exePath: options.exePath,
@@ -2669,145 +3298,166 @@ function readSdkVersion() {
 function printHelp() {
     console.log(`Tapi CLI
 
-Usage:
-  tapi init --project PROJECT
-  tapi link --project PROJECT
-  tapi studio install [--channel pilot] [--api-base-url URL]
-  tapi studio
-  tapi studio open
-  tapi studio doctor
-  tapi apis describe <namespace.operation>
-  tapi apis sync
-  tapi apis generate
-  tapi triggers sync
-  tapi publish
-  tapi service status
-  tapi doctor
-
-Commands:
-  init            Create .tapi/project.json for this repo
-  link            Rebind this repo to an existing Tapi project
-  studio install  Download, verify, and run the Tapi Studio installer
-  studio          Open Tapi Studio for this repo
-  studio open     Open Tapi Studio for this repo
-  studio doctor   Check local SDK and Studio release configuration
-  apis describe   Print a generated website API input/output contract
-  apis sync       Save the published API catalog to .tapi/generated
-  apis generate   Generate a TypeScript runtime wrapper from the catalog
-  triggers sync   Upsert API-call triggers from tapi.config
-  publish         Upload local .tapi API drafts and publish ready requests
-  service         Inspect or control the local Tapi Windows service
-  doctor          Alias for studio doctor
+Usage:
+  tapi init --project PROJECT
+  tapi link --project PROJECT
+  tapi studio install [--channel pilot] [--api-base-url URL]
+  tapi studio
+  tapi studio open
+  tapi studio doctor
+  tapi apis describe <namespace.operation>
+  tapi apis sync
+  tapi apis generate
+  tapi triggers sync
+  tapi sessions
+  tapi publish
+  tapi service status
+  tapi doctor
+
+Commands:
+  init            Create .tapi/project.json for this repo
+  link            Rebind this repo to an existing Tapi project
+  studio install  Download, verify, and run the Tapi Studio installer
+  studio          Open Tapi Studio for this repo
+  studio open     Open Tapi Studio for this repo
+  studio doctor   Check local SDK and Studio release configuration
+  apis describe   Print a generated website API input/output contract
+  apis sync       Save the published API catalog to .tapi/generated
+  apis generate   Generate a TypeScript runtime wrapper from the catalog
+  triggers sync   Upsert API-call triggers from tapi.config
+  sessions        List dev-mode API sessions and open takeover sessions
+  publish         Upload local .tapi API drafts and publish ready requests
+  service         Inspect or control the local Tapi Windows service
+  doctor          Alias for studio doctor
+`);
+}
+function printSessionsHelp() {
+    console.log(`Tapi dev session commands
+
+Usage:
+  tapi sessions [--api-base-url URL] [--api-key KEY] [--project PROJECT]
+  tapi sessions list [--json] [--site SITE]
+  tapi sessions open <session-id> [--api-base-url URL] [--api-key KEY] [--project PROJECT]
+
+Options:
+  --api-base-url <url>   Tapi API base URL
+  --server <url>         Alias for --api-base-url
+  --api-key <key>        Tapi API key; defaults to TAPI_API_KEY
+  --project <id>         Tapi project id; defaults to TAPI_PROJECT_ID or .tapi/project.json
+  --site <name>          Limit sessions to one sitemap/site
+  --json                 Print raw grouped session JSON
+  --no-interactive       Print the grouped list without the arrow-key picker
 `);
 }
 function printApisHelp() {
-    console.log(`Tapi generated website API commands
-
-Usage:
-  tapi apis describe <namespace.operation> [--api-base-url URL] [--api-key KEY] [--project PROJECT]
-  tapi apis sync [--api-base-url URL] [--api-key KEY] [--project PROJECT]
-  tapi apis generate [--api-base-url URL] [--api-key KEY] [--project PROJECT] [--out FILE]
-
-Options:
-  --api-base-url <url>   Tapi API base URL
-  --server <url>         Alias for --api-base-url
-  --api-key <key>        Tapi API key; defaults to TAPI_API_KEY
-  --project <id>         Tapi project id; defaults to TAPI_PROJECT_ID or .tapi/project.json
-  --catalog <path>       Catalog JSON output path
-  --out <path>           Generated TypeScript output path
+    console.log(`Tapi generated website API commands
+
+Usage:
+  tapi apis describe <namespace.operation> [--api-base-url URL] [--api-key KEY] [--project PROJECT]
+  tapi apis sync [--api-base-url URL] [--api-key KEY] [--project PROJECT]
+  tapi apis generate [--api-base-url URL] [--api-key KEY] [--project PROJECT] [--out FILE]
+
+Options:
+  --api-base-url <url>   Tapi API base URL
+  --server <url>         Alias for --api-base-url
+  --api-key <key>        Tapi API key; defaults to TAPI_API_KEY
+  --project <id>         Tapi project id; defaults to TAPI_PROJECT_ID or .tapi/project.json
+  --catalog <path>       Catalog JSON output path
+  --out <path>           Generated TypeScript output path
 `);
 }
 function printTriggersHelp() {
-    console.log(`Tapi API trigger commands
-
-Usage:
-  tapi triggers sync [--config FILE] [--api-base-url URL] [--api-key KEY] [--project PROJECT]
-
-Options:
-  --config <path>        Trigger config path; defaults to tapi.config.ts/js/json in the workspace root
-  --api-base-url <url>   Tapi API base URL
-  --server <url>         Alias for --api-base-url
-  --api-key <key>        Tapi API key; defaults to TAPI_API_KEY
-  --project <id>         Tapi project id; defaults to TAPI_PROJECT_ID or .tapi/project.json
-
-Config:
-  export default {
-    triggers: {
-      nightlyBalance: {
-        apiRequest: "schwab.get_balance",
-        interval: "1h",
-        inputs: { accountId: "main" },
-        runtime: { profileRef: "perm_default" },
-      },
-    },
-  };
+    console.log(`Tapi API trigger commands
+
+Usage:
+  tapi triggers sync [--config FILE] [--api-base-url URL] [--api-key KEY] [--project PROJECT]
+
+Options:
+  --config <path>        Trigger config path; defaults to tapi.config.ts/js/json in the workspace root
+  --api-base-url <url>   Tapi API base URL
+  --server <url>         Alias for --api-base-url
+  --api-key <key>        Tapi API key; defaults to TAPI_API_KEY
+  --project <id>         Tapi project id; defaults to TAPI_PROJECT_ID or .tapi/project.json
+
+Config:
+  export default {
+    triggers: {
+      nightlyBalance: {
+        apiRequest: "schwab.get_balance",
+        interval: "1h",
+        inputs: { accountId: "main" },
+        runtime: { profileRef: "perm_default" },
+      },
+    },
+  };
 `);
 }
 function printStudioHelp() {
-    console.log(`Tapi Studio commands
-
-Usage:
-  tapi studio [options]
-  tapi studio install [options]
-  tapi studio open [options]
-  tapi studio doctor [options]
-
-Options:
+    console.log(`Tapi Studio commands
+
+Usage:
+  tapi studio [options]
+  tapi studio install [options]
+  tapi studio open [options]
+  tapi studio doctor [options]
+
+Options:
   --channel <name>       Release channel: pilot, stable, or nightly
-  --api-base-url <url>   Tapi API base URL for approval and protected downloads
-  --server <url>         Alias for --api-base-url
-  --workspace <path>     Search this directory for .tapi/project.json
-  --no-workspace         Do not load .tapi/project.json
-  --project <id>         Tapi project id for workspace-bound Studio
-  --project-slug <slug>  Optional display slug for the bound project
-  --install-token <tok>  Preissued Studio install token (skips browser sign-in)
-  --manifest <url>       Exact release manifest URL for doctor only
-  --cache-dir <path>     Installer download cache directory
-  --download-only        Download and verify without running the installer
-  --silent               Run the NSIS installer with /S
-  --exe <path>           Tapi Studio executable path for open/doctor
+  --api-base-url <url>   Tapi API base URL for install authorization and protected downloads
+  --server <url>         Alias for --api-base-url
+  --workspace <path>     Search this directory for .tapi/project.json
+  --no-workspace         Do not load .tapi/project.json
+  --project <id>         Tapi project id for workspace-bound Studio
+  --project-slug <slug>  Optional display slug for the bound project
+  --install-token <tok>  Preissued Studio install token (skips browser sign-in)
+  --manifest <url>       Exact release manifest URL for doctor only
+  --cache-dir <path>     Installer download cache directory
+  --install-dir <path>   Portable Studio server release directory
+  --download-only        Download and verify without running the installer
+  --silent               Run the NSIS installer with /S
+  --exe <path>           Tapi Studio executable path for open/doctor
 `);
 }
 function printWorkspaceHelp(command) {
-    console.log(`Tapi workspace ${command}
-
-Usage:
-  tapi ${command} --project PROJECT [--api-base-url URL] [--root PATH] [--force]
-
-Options:
-  --project <id>         Tapi project id/name to bind this repo to
-  --project-slug <slug>  Optional display slug
-  --api-base-url <url>   Tapi API base URL stored in .tapi/project.json
-  --server <url>         Alias for --api-base-url
-  --root <path>          Directory where .tapi/project.json should be written
-  --force                Overwrite an existing workspace config
+    console.log(`Tapi workspace ${command}
+
+Usage:
+  tapi ${command} --project PROJECT [--api-base-url URL] [--root PATH] [--force]
+
+Options:
+  --project <id>         Tapi project id/name to bind this repo to
+  --project-slug <slug>  Optional display slug
+  --api-base-url <url>   Tapi API base URL stored in .tapi/project.json
+  --server <url>         Alias for --api-base-url
+  --root <path>          Directory where .tapi/project.json should be written
+  --force                Overwrite an existing workspace config
 `);
 }
 function printServiceHelp() {
-    console.log(`Tapi service commands
-
-Usage:
-  tapi service status
-  tapi service start
-  tapi service stop
-  tapi service restart
-  tapi service repair
-
-Commands:
-  status    Print installed/running status for tapi-service
-  start     Start tapi-service
-  stop      Stop tapi-service
-  restart   Restart tapi-service
-  repair    Restart tapi-service using the current installed service
+    console.log(`Tapi service commands
+
+Usage:
+  tapi service status
+  tapi service start
+  tapi service stop
+  tapi service restart
+  tapi service repair
+
+Commands:
+  status    Print installed/running status for tapi-service
+  start     Start tapi-service
+  stop      Stop tapi-service
+  restart   Restart tapi-service
+  repair    Restart tapi-service using the current installed service
 `);
 }
 function printPublishHelp() {
-    console.log(`Tapi publish
-
-Usage:
-  tapi publish [--api-base-url URL] [--api-key KEY] [--project PROJECT]
-
-Publishes ready generated API requests from local .tapi/apis files.
+    console.log(`Tapi publish
+
+Usage:
+  tapi publish [--api-base-url URL] [--api-key KEY] [--project PROJECT]
+
+Publishes ready generated API requests from local .tapi/apis files.
 `);
 }
 function formatError(error) {