@xfey/tutti 0.1.9 → 0.1.11

package/dist/server-shell/cli/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { formatCliError } from "./errors.js";
+import { formatCliError, formatCliErrorReason } from "./errors.js";
 import { parseCliArgs } from "./args.js";
 import { runBackgroundLaunchCommand, runForegroundLaunchCommand, runInternalHostRunCommand, } from "./launch-command.js";
 import { resolveExistingProjectContext } from "./project-resolver.js";
@@ -96,15 +96,12 @@ async function runProviderSetupCommand(workspacePath) {
         ...(workspacePath === undefined ? {} : { workspacePath }),
     });
     const result = await runProviderSetupTui({
-        projectName: project.display_name,
         tuttiHome: project.tutti_home,
         projectId: project.project_id,
-        initialBaseUrl: project.provider_base_url ?? "https://api.openai.com/v1",
     });
     process.stdout.write([
         "",
         "Provider configured.",
-        `Base URL: ${result.base_url}`,
         `Model: ${result.default_model}`,
         `Key: ${result.redacted_key}`,
         `Validated: ${result.validated_at}`,
@@ -125,7 +122,8 @@ function runDoctorCommand(workspacePath) {
         checks.push(`Host: ${project.runtime_endpoint === null ? "not running" : project.runtime_endpoint.base_url}`);
     }
     catch (error) {
-        checks.push(`Project: unavailable (${error instanceof Error ? error.message : "unknown"})`);
+        checks.push("Project: unavailable");
+        checks.push(`Project detail: ${formatCliErrorReason(error)}`);
     }
     process.stdout.write(`${checks.join("\n")}\n`);
 }

package/dist/server-shell/cli/errors.d.ts

@@ -1,4 +1,4 @@
-export type LaunchErrorCode = "unsafe_project_root" | "unsupported_tutti_schema" | "project_identity_conflict" | "git_bootstrap_failed" | "sensitive_file_detected" | "relay_unavailable" | "relay_registration_failed" | "provider_configuration_required" | "provider_validation_failed" | "store_migration_failed" | "existing_server_unhealthy" | "takeover_rejected" | "takeover_failed" | "port_unavailable";
+export type LaunchErrorCode = "unsafe_project_root" | "unsupported_tutti_schema" | "project_identity_conflict" | "git_bootstrap_failed" | "sensitive_file_detected" | "relay_unavailable" | "relay_registration_failed" | "host_not_running" | "provider_configuration_required" | "provider_setup_cancelled" | "provider_validation_failed" | "store_migration_failed" | "existing_server_unhealthy" | "takeover_rejected" | "takeover_failed" | "port_unavailable";
 export declare class LaunchError extends Error {
     readonly code: LaunchErrorCode;
     readonly next: string;
@@ -7,4 +7,5 @@ export declare class LaunchError extends Error {
 }
 export declare function formatLaunchError(error: unknown): string;
 export declare function formatCliError(error: unknown): string;
+export declare function formatCliErrorReason(error: unknown): string;
 //# sourceMappingURL=errors.d.ts.map

package/dist/server-shell/cli/errors.js

@@ -1,4 +1,4 @@
-import { redactError, redactText } from "@tutti/shared/utils";
+import { redactAndTruncateText, redactError, redactText } from "@tutti/shared/utils";
 export class LaunchError extends Error {
     code;
     next;
@@ -13,53 +13,102 @@ export class LaunchError extends Error {
 }
 export function formatLaunchError(error) {
     if (error instanceof LaunchError) {
+        if (error.code === "provider_setup_cancelled") {
+            return ["Tutti launch cancelled", "", `Reason: ${redactText(error.message)}`].join("\n");
+        }
         const lines = [
             "Tutti launch failed",
             "",
             `Code: ${error.code}`,
-            `Reason: ${redactText(error.message)}`,
+            `Reason: ${formatBoundedText(error.message)}`,
         ];
         const detailLines = Object.entries(error.details)
             .filter(([, value]) => value !== undefined)
-            .map(([key, value]) => `Detail ${key}: ${redactText(formatDetailValue(value))}`);
+            .map(([key, value]) => `Detail ${key}: ${formatBoundedDetail(value)}`);
         if (detailLines.length > 0) {
             lines.push(...detailLines);
         }
         lines.push(`Next: ${redactText(error.next)}`);
         return lines.join("\n");
     }
-    const redactedError = redactError(error);
-    const reason = typeof redactedError === "string" ? redactedError : JSON.stringify(redactedError);
     return [
         "Tutti launch failed",
         "",
         "Code: internal_error",
-        `Reason: ${reason ?? "Unknown error"}`,
+        `Reason: ${formatUnknownErrorReason(error)}`,
         "Next: Retry after checking the local debug logs.",
     ].join("\n");
 }
 export function formatCliError(error) {
     if (error instanceof LaunchError) {
-        const lines = ["Tutti command failed", "", `Code: ${error.code}`, `Reason: ${redactText(error.message)}`];
+        if (error.code === "provider_setup_cancelled") {
+            return ["Tutti command cancelled", "", `Reason: ${redactText(error.message)}`].join("\n");
+        }
+        const lines = ["Tutti command failed", "", `Code: ${error.code}`, `Reason: ${formatBoundedText(error.message)}`];
         const detailLines = Object.entries(error.details)
             .filter(([, value]) => value !== undefined)
-            .map(([key, value]) => `Detail ${key}: ${redactText(formatDetailValue(value))}`);
+            .map(([key, value]) => `Detail ${key}: ${formatBoundedDetail(value)}`);
         if (detailLines.length > 0) {
             lines.push(...detailLines);
         }
         lines.push(`Next: ${redactText(error.next)}`);
         return lines.join("\n");
     }
-    const redactedError = redactError(error);
-    const reason = typeof redactedError === "string" ? redactedError : JSON.stringify(redactedError);
     return [
         "Tutti command failed",
         "",
         "Code: internal_error",
-        `Reason: ${reason ?? "Unknown error"}`,
+        `Reason: ${formatUnknownErrorReason(error)}`,
         "Next: Retry after checking the local debug logs.",
     ].join("\n");
 }
+const MAX_REASON_LENGTH = 320;
+const MAX_DETAIL_LENGTH = 720;
+function formatBoundedText(value) {
+    return redactAndTruncateText(value, MAX_REASON_LENGTH);
+}
+function formatBoundedDetail(value) {
+    return redactAndTruncateText(formatDetailValue(value), MAX_DETAIL_LENGTH);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function formatCliErrorReason(error) {
+    const redactedError = redactError(error);
+    if (typeof redactedError === "string" && redactedError.trim() !== "") {
+        return formatBoundedText(redactedError);
+    }
+    if (isRecord(redactedError)) {
+        const message = redactedError.message;
+        if (typeof message === "string" && message.trim() !== "") {
+            return formatBoundedText(message);
+        }
+        const name = redactedError.name;
+        if (typeof name === "string" && name.trim() !== "") {
+            return formatBoundedText(name);
+        }
+    }
+    return "Unexpected error.";
+}
+function formatUnknownErrorReason(error) {
+    return formatCliErrorReason(error);
+}
+function stripStackFields(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => stripStackFields(entry));
+    }
+    if (isRecord(value)) {
+        const stripped = {};
+        for (const [key, nested] of Object.entries(value)) {
+            if (key.toLowerCase() === "stack") {
+                continue;
+            }
+            stripped[key] = stripStackFields(nested);
+        }
+        return stripped;
+    }
+    return value;
+}
 function formatDetailValue(value) {
     if (Array.isArray(value)) {
         return value.map((entry) => formatDetailValue(entry)).join(", ");
@@ -70,6 +119,6 @@ function formatDetailValue(value) {
     if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
         return String(value);
     }
-    return JSON.stringify(value) ?? "undefined";
+    return JSON.stringify(stripStackFields(value)) ?? "undefined";
 }
 //# sourceMappingURL=errors.js.map

package/dist/server-shell/cli/launch-command.js

@@ -1,5 +1,4 @@
 import { createInterface } from "node:readline/promises";
-import { basename } from "node:path";
 import { formatLaunchLifecycleResult, startLaunchProject, waitForForegroundHostShutdown } from "./host-lifecycle.js";
 import { prepareLaunchProject } from "./launch.js";
 import { spawnDetachedHost, waitForManagedHostReady } from "./managed-host.js";
@@ -24,9 +23,6 @@ export async function confirmFromTty(request) {
         readline.close();
     }
 }
-function projectName(preparation) {
-    return basename(preparation.workspace_root) || preparation.project_id;
-}
 async function waitForEnter() {
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
         return;
@@ -48,13 +44,11 @@ function renderCompletionPage(options) {
         ...(isTty ? [CLEAR, renderTuttiTerminalLogo({ tty: true }), ""] : []),
         "Tutti is running in the background.",
         "",
-        `Project: ${options.projectName}`,
-        "",
         `Join URL: ${options.joinUrl}`,
         "",
         renderTerminalQr(options.joinUrl),
         "",
-        "Press Enter to close this page. The host will keep running in the background.",
+        "[Enter] to continue",
     ].join("\n");
 }
 async function ensureProviderConfigured(preparation) {
@@ -65,10 +59,8 @@ async function ensureProviderConfigured(preparation) {
         throw new LaunchError("provider_configuration_required", "Provider credentials are not configured for this project", "Run `tutti provider setup` from an interactive terminal, then run `tutti launch` again.");
     }
     await runProviderSetupTui({
-        projectName: projectName(preparation),
         tuttiHome: preparation.tutti_home,
         projectId: preparation.project_id,
-        initialBaseUrl: "https://api.openai.com/v1",
     });
 }
 export async function runForegroundLaunchCommand(options) {
@@ -110,7 +102,6 @@ export async function runBackgroundLaunchCommand(options) {
         throw new LaunchError("relay_registration_failed", "Host started but Relay did not return a visible join URL", "Run `tutti invite` to rotate a fresh invite link.");
     }
     process.stdout.write(`${renderCompletionPage({
-        projectName: projectName(preparation),
         joinUrl: ready.join_url,
     })}\n`);
     await waitForEnter();

package/dist/server-shell/cli/launch.js

@@ -1,6 +1,5 @@
 import { resolve } from "node:path";
 import { createProjectId } from "@tutti/shared/ids";
-import { redactText } from "@tutti/shared/utils";
 import { readOpenAiProviderConfigProjection, resolveTuttiHome, } from "../../providers/openai/index.js";
 import { LaunchError } from "./errors.js";
 import { assertSafeProjectRoot, ensureGitBootstrap, } from "./git-bootstrap.js";
@@ -101,8 +100,6 @@ export function formatLaunchPreparation(result) {
         "Tutti launch prerequisites are ready",
         "",
         "Status: prepared",
-        `Workspace: ${redactText(result.workspace_root)}`,
-        `Project: ${result.project_id}`,
         `Branch: ${result.branch}`,
         `Relay: ${result.relay_url}`,
         `Provider: ${result.provider_status}`,

package/dist/server-shell/cli/managed-host.js

@@ -1,8 +1,8 @@
 import { spawn } from "node:child_process";
-import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { createRuntimeEndpointProbe } from "./host-runtime-endpoint.js";
-import { getHostLogFilePath, readMachineRuntimeEndpoint, } from "./machine-local.js";
+import { LaunchError } from "./errors.js";
+import { readMachineRuntimeEndpoint } from "./machine-local.js";
 import { readHostLocalLaunchStatus, rotateHostLocalInvite } from "./local-control-client.js";
 const DEFAULT_READY_TIMEOUT_MS = 60_000;
 const READY_POLL_INTERVAL_MS = 250;
@@ -38,15 +38,6 @@ export function spawnDetachedHost(options) {
     });
     child.unref();
 }
-function readHostLogTail(tuttiHome, maxLines = 80) {
-    try {
-        const text = readFileSync(getHostLogFilePath(tuttiHome), "utf8");
-        return text.split(/\r?\n/u).filter(Boolean).slice(-maxLines).join("\n");
-    }
-    catch {
-        return "";
-    }
-}
 export async function waitForManagedHostReady(options) {
     const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_READY_TIMEOUT_MS);
     const probe = createRuntimeEndpointProbe(options.fetchImpl ?? fetch);
@@ -92,12 +83,6 @@ export async function waitForManagedHostReady(options) {
         }
         await delay(READY_POLL_INTERVAL_MS);
     }
-    const tail = readHostLogTail(options.tuttiHome);
-    throw new Error([
-        `Tutti host did not become ready before timeout: ${lastReason}`,
-        tail.length === 0 ? "" : `Recent host log:\n${tail}`,
-    ]
-        .filter(Boolean)
-        .join("\n"));
+    throw new LaunchError("existing_server_unhealthy", `Tutti host did not become ready before timeout: ${lastReason}`, "Run `tutti logs` for details, then retry `tutti launch`.");
 }
 //# sourceMappingURL=managed-host.js.map

package/dist/server-shell/cli/provider-tui.d.ts

@@ -1,16 +1,33 @@
+import { type ConfigureProjectOpenAiProviderResult } from "../../providers/openai/index.js";
 import type { ProjectId } from "@tutti/shared/ids";
+type ProviderSetupLogEvent = {
+    ts: string;
+    level: "error";
+    scope: "provider_setup";
+    event: "provider_validation_failed" | "provider_validation_exception";
+    project_id: ProjectId;
+    reason?: string;
+    retryable?: boolean;
+    diagnostic?: unknown;
+    error?: unknown;
+};
 export type ProviderSetupResult = {
     base_url: string;
     redacted_key: string;
     default_model: string;
     validated_at: string;
 };
+export declare function providerValidationFailureMessage(result: ConfigureProjectOpenAiProviderResult): string;
+export declare function writeProviderSetupValidationLog(options: {
+    tuttiHome: string;
+    event: Omit<ProviderSetupLogEvent, "ts" | "level" | "scope">;
+    now?: () => Date;
+}): boolean;
 export declare function runProviderSetupTui(options: {
-    projectName: string;
     tuttiHome: string;
     projectId: ProjectId;
-    initialBaseUrl?: string;
     stdin?: NodeJS.ReadStream;
     stdout?: NodeJS.WriteStream;
 }): Promise<ProviderSetupResult>;
+export {};
 //# sourceMappingURL=provider-tui.d.ts.map

package/dist/server-shell/cli/provider-tui.js

@@ -1,15 +1,21 @@
 import { emitKeypressEvents } from "node:readline";
 import { redactError } from "@tutti/shared/utils";
 import { configureProjectOpenAiProvider, DEFAULT_OPENAI_MODEL, } from "../../providers/openai/index.js";
+import { LaunchError } from "./errors.js";
+import { appendHostLogLine, getHostLogFilePath } from "./machine-local.js";
 import { renderTuttiTerminalLogo } from "./terminal-logo.js";
-const DEFAULT_BASE_URL = "https://api.openai.com/v1";
 const HIDE_CURSOR = "\u001B[?25l";
 const SHOW_CURSOR = "\u001B[?25h";
+const BLINK_ON = "\u001B[5m";
+const BLINK_OFF = "\u001B[25m";
 const CLEAR = "\u001B[2J\u001B[H";
 const DIVIDER = "----------------------------------------------------------------";
+function providerSetupCancelled() {
+    return new LaunchError("provider_setup_cancelled", "Provider setup cancelled.", "Run the command again when you are ready.");
+}
 function fieldLine(options) {
     const value = options.secret && options.value.length > 0 ? "*".repeat(options.value.length) : options.value;
-    return `> ${options.label}: ${value} _`;
+    return `> ${options.label}: ${value}${BLINK_ON}_${BLINK_OFF}`;
 }
 function renderProviderField(state) {
     if (state.step === "base-url") {
@@ -22,13 +28,11 @@ function renderProviderField(state) {
                 value: state.baseUrl,
             }),
             "",
-            "Press Enter to continue. Press Ctrl-C to cancel.",
+            "[Enter] to continue",
         ];
     }
     return [
         "Step 2 of 2 - API Key",
-        `Base URL: ${state.baseUrl}`,
-        "",
         "Enter the API key for this provider. It will be stored only in the machine-local Tutti credential store.",
         "",
         fieldLine({
@@ -37,7 +41,9 @@ function renderProviderField(state) {
             secret: true,
         }),
         "",
-        "Press Enter to validate. Press Esc to edit the base URL. Press Ctrl-C to cancel.",
+        state.error === undefined
+            ? "[Enter] to validate    [Esc] to edit Base URL"
+            : "[Enter] to retry    [Esc] to edit Base URL",
     ];
 }
 function renderProviderForm(options) {
@@ -50,11 +56,8 @@ function renderProviderForm(options) {
         DIVIDER,
         "Tutti uses an OpenAI-compatible Responses API provider.",
         "The base URL should expose POST /responses under the entered URL.",
-        `Default example: ${DEFAULT_BASE_URL}`,
         DIVIDER,
         "",
-        `Project: ${options.projectName}`,
-        "",
         ...renderProviderField(options.state),
         "",
     ];
@@ -66,46 +69,58 @@ function renderProviderForm(options) {
     }
     return lines.join("\n");
 }
-function validationFailureMessage(result) {
+export function providerValidationFailureMessage(result) {
     if (result.kind === "configured") {
         return "";
     }
-    const retry = result.retryable ? " Retry after the provider recovers." : "";
-    return `${result.reason}.${retry}`;
+    switch (result.reason) {
+        case "provider_auth_invalid":
+            return "API key was rejected.";
+        case "provider_model_unavailable":
+            return "Default model is unavailable for this provider.";
+        case "provider_quota_or_billing_required":
+            return "Provider quota or billing is not available.";
+        case "provider_rate_limited":
+            return "Provider is rate limited. Try again later.";
+        case "provider_network_error":
+            return "Could not reach a Responses API-compatible endpoint.";
+    }
 }
-function waitForKeypress(stdin) {
-    return new Promise((resolve, reject) => {
-        const onKeypress = (_character, key) => {
-            cleanup();
-            if (key.ctrl === true && key.name === "c") {
-                reject(new Error("Provider setup cancelled"));
-                return;
-            }
-            resolve();
-        };
-        const cleanup = () => {
-            stdin.off("keypress", onKeypress);
-            if (stdin.isTTY) {
-                stdin.setRawMode(false);
-            }
-        };
-        if (stdin.isTTY) {
-            stdin.setRawMode(true);
-        }
-        stdin.once("keypress", onKeypress);
-    });
+function providerValidationExceptionMessage(logged) {
+    if (logged) {
+        return "Could not validate the provider connection. Details were written to the host log.";
+    }
+    return "Could not validate the provider connection. Host log could not be written.";
+}
+export function writeProviderSetupValidationLog(options) {
+    const logEvent = {
+        ts: (options.now ?? (() => new Date()))().toISOString(),
+        level: "error",
+        scope: "provider_setup",
+        ...options.event,
+    };
+    const redactedLogEvent = {
+        ...logEvent,
+        ...(logEvent.error === undefined ? {} : { error: redactError(logEvent.error) }),
+    };
+    try {
+        appendHostLogLine(getHostLogFilePath(options.tuttiHome), JSON.stringify(redactError(redactedLogEvent)));
+        return true;
+    }
+    catch {
+        return false;
+    }
 }
 async function readProviderForm(options) {
     const state = {
         step: options.initialStep ?? "base-url",
-        baseUrl: options.initialBaseUrl ?? DEFAULT_BASE_URL,
+        baseUrl: options.initialBaseUrl ?? "",
         apiKey: options.initialApiKey ?? "",
-        error: undefined,
+        error: options.initialError,
     };
     return await new Promise((resolve, reject) => {
         const render = () => {
             options.stdout.write(renderProviderForm({
-                projectName: options.projectName,
                 state,
                 tty: options.stdout.isTTY === true,
             }));
@@ -120,7 +135,7 @@ async function readProviderForm(options) {
         const onKeypress = (character, key) => {
             if (key.ctrl === true && key.name === "c") {
                 cleanup();
-                reject(new Error("Provider setup cancelled"));
+                reject(providerSetupCancelled());
                 return;
             }
             if (key.name === "escape") {
@@ -131,7 +146,7 @@ async function readProviderForm(options) {
                     return;
                 }
                 cleanup();
-                reject(new Error("Provider setup cancelled"));
+                reject(providerSetupCancelled());
                 return;
             }
             if (key.name === "return") {
@@ -185,7 +200,7 @@ async function readProviderForm(options) {
         render();
     });
 }
-function renderChecking(projectName, frame, tty) {
+function renderChecking(frame, tty) {
     const frames = ["|", "/", "-", "\\"];
     const indicator = frames[frame % frames.length] ?? "|";
     return [
@@ -194,8 +209,9 @@ function renderChecking(projectName, frame, tty) {
         renderTuttiTerminalLogo({ tty }),
         "",
         "Provider setup",
-        "",
-        `Project: ${projectName}`,
+        DIVIDER,
+        "Validating the provider with the configured Responses API endpoint.",
+        DIVIDER,
         "",
         `${indicator} Checking provider connection with ${DEFAULT_OPENAI_MODEL}...`,
     ].join("\n");
@@ -204,17 +220,18 @@ export async function runProviderSetupTui(options) {
     const stdin = options.stdin ?? process.stdin;
     const stdout = options.stdout ?? process.stdout;
     if (!stdin.isTTY || !stdout.isTTY) {
-        throw new Error("Provider setup requires an interactive terminal.");
+        throw new LaunchError("provider_configuration_required", "Provider setup requires an interactive terminal.", "Run `tutti provider setup` from an interactive terminal.");
     }
-    let initialBaseUrl = options.initialBaseUrl;
+    let initialBaseUrl;
     let initialApiKey = "";
     let initialStep = "base-url";
+    let initialError;
     while (true) {
         const input = await readProviderForm({
-            projectName: options.projectName,
             ...(initialBaseUrl === undefined ? {} : { initialBaseUrl }),
             ...(initialApiKey === "" ? {} : { initialApiKey }),
             initialStep,
+            ...(initialError === undefined ? {} : { initialError }),
             stdin,
             stdout,
         });
@@ -223,11 +240,11 @@ export async function runProviderSetupTui(options) {
         initialStep = "api-key";
         let frame = 0;
         const interval = setInterval(() => {
-            stdout.write(renderChecking(options.projectName, frame, stdout.isTTY === true));
+            stdout.write(renderChecking(frame, stdout.isTTY === true));
             frame += 1;
         }, 120);
         try {
-            stdout.write(renderChecking(options.projectName, frame, stdout.isTTY === true));
+            stdout.write(renderChecking(frame, stdout.isTTY === true));
             const result = await configureProjectOpenAiProvider({
                 tuttiHome: options.tuttiHome,
                 projectId: options.projectId,
@@ -244,23 +261,33 @@ export async function runProviderSetupTui(options) {
                     validated_at: result.projection.validated_at,
                 };
             }
-            stdout.write(renderProviderForm({
-                projectName: options.projectName,
-                state: {
-                    step: "api-key",
-                    baseUrl: input.baseUrl,
-                    apiKey: input.apiKey,
-                    error: validationFailureMessage(result),
+            writeProviderSetupValidationLog({
+                tuttiHome: options.tuttiHome,
+                event: {
+                    event: "provider_validation_failed",
+                    project_id: options.projectId,
+                    reason: result.reason,
+                    retryable: result.retryable,
+                    ...(result.diagnostic === undefined ? {} : { diagnostic: result.diagnostic }),
                 },
-                footer: "Press any key to edit and try again.",
-                tty: stdout.isTTY === true,
-            }));
-            await waitForKeypress(stdin);
+            });
+            initialError = providerValidationFailureMessage(result);
         }
         catch (error) {
             clearInterval(interval);
             stdout.write(SHOW_CURSOR);
-            throw new Error(`Provider setup failed: ${String(redactError(error))}`, { cause: error });
+            if (error instanceof LaunchError) {
+                throw error;
+            }
+            const logged = writeProviderSetupValidationLog({
+                tuttiHome: options.tuttiHome,
+                event: {
+                    event: "provider_validation_exception",
+                    project_id: options.projectId,
+                    error,
+                },
+            });
+            initialError = providerValidationExceptionMessage(logged);
         }
     }
 }

package/dist/server-shell/cli/runtime-commands.js

@@ -6,6 +6,7 @@ import { redactText } from "@tutti/shared/utils";
 import { createRuntimeEndpointProbe } from "./host-runtime-endpoint.js";
 import { getHostLogFilePath, getMachineRuntimeEndpointPath, getProjectLocalStoreRoot, readMachineProjectBinding, readMachineRuntimeEndpoint, } from "./machine-local.js";
 import { readHostLocalLaunchStatus, readHostLocalProject, readHostLocalProviderConfig, requestHostLocalShutdown, rotateHostLocalInvite, } from "./local-control-client.js";
+import { formatCliErrorReason, LaunchError } from "./errors.js";
 import { resolveExistingProjectContext } from "./project-resolver.js";
 import { renderTerminalQr } from "./terminal-qr.js";
 import { resolveTuttiHome } from "../../providers/openai/index.js";
@@ -212,7 +213,7 @@ export async function runPsManageCommand(options = {}) {
                     message = `Invite refreshed for ${project.display_name}.`;
                 }
                 catch (error) {
-                    message = error instanceof Error ? error.message : "Invite refresh failed.";
+                    message = formatCliErrorReason(error);
                     detail = undefined;
                 }
                 render();
@@ -232,7 +233,7 @@ export async function runPsManageCommand(options = {}) {
                     detail = undefined;
                 }
                 catch (error) {
-                    message = error instanceof Error ? error.message : "Stop failed.";
+                    message = formatCliErrorReason(error);
                     detail = undefined;
                 }
                 render();
@@ -254,19 +255,30 @@ export async function runStopCommand(workspacePath) {
     if (endpoint === null) {
         return "Tutti host is not running for this project.";
     }
-    await requestHostLocalShutdown({ endpoint });
+    try {
+        await requestHostLocalShutdown({ endpoint });
+    }
+    catch (error) {
+        throw new LaunchError("existing_server_unhealthy", `Could not stop the host: ${formatCliErrorReason(error)}`, "Run `tutti ps` to inspect the runtime state, or stop the host process manually.");
+    }
     return `Stopped ${project.display_name}.`;
 }
 export async function runInviteCommand(workspacePath) {
     const project = resolveProject(workspacePath);
     const endpoint = project.runtime_endpoint;
     if (endpoint === null) {
-        throw new Error("Tutti host is not running for this project.");
+        throw new LaunchError("host_not_running", "Tutti host is not running for this project.", "Run `tutti launch` first, then retry `tutti invite`.");
+    }
+    let status;
+    try {
+        status = await rotateHostLocalInvite({ endpoint });
+    }
+    catch (error) {
+        throw new LaunchError("existing_server_unhealthy", `Could not refresh the invite: ${formatCliErrorReason(error)}`, "Run `tutti launch` to restart or reconnect the host, then retry `tutti invite`.");
     }
-    const status = await rotateHostLocalInvite({ endpoint });
     const joinUrl = status.relay?.join_url;
     if (joinUrl === undefined) {
-        throw new Error("Relay did not return a visible join URL.");
+        throw new LaunchError("relay_registration_failed", "Relay did not return a visible join URL.", "Retry `tutti invite`; if it keeps failing, run `tutti launch` to reconnect the host.");
     }
     return [`Join URL: ${joinUrl}`, "", renderTerminalQr(joinUrl)].join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfey/tutti",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",