@xfey/tutti 0.1.29 → 0.1.31

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

@@ -1,17 +1,17 @@
-import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
 import { emitKeypressEvents } from "node:readline";
-import { ID_PREFIXES, isPrefixedId } from "@tutti/shared/ids";
 import { redactText } from "@tutti/shared/utils";
-import { createRuntimeEndpointProbe } from "./host-runtime-endpoint.js";
-import { deleteMachineProjectLocalState, getHostLogFilePath, getMachineRuntimeEndpointPath, getProjectLocalStoreRoot, readMachineProjectBinding, readMachineRuntimeEndpoint, } from "./machine-local.js";
-import { readHostLocalLaunchStatus, readHostLocalProject, readHostLocalProviderConfig, requestHostLocalShutdown, rotateHostLocalInvite, } from "./local-control-client.js";
+import { archiveRelayProject as archiveRelayProjectAtRelay, RelayHostControlClientError, } from "@tutti/relay-client";
+import { createRuntimeEndpointProbe, requestExistingHostShutdown, } from "./host-runtime-endpoint.js";
+import { deleteMachineProjectLocalState, getHostLogFilePath, getMachineRuntimeEndpointPath, getProjectLocalStoreRoot, readMachineRuntimeEndpoint, readHostRegistrationSecret, } from "./machine-local.js";
+import { inspectMachineProject, inspectMachineProjectInventory, inspectMachineProjects, } from "./machine-project-inspector.js";
+import { readHostLocalLaunchStatus, readHostLocalProviderConfig, requestHostLocalShutdown, rotateHostLocalInvite, } from "./local-control-client.js";
 import { formatCliErrorReason, LaunchError } from "./errors.js";
 import { resolveManagedProjectContext } from "./project-resolver.js";
 import { formatJoinLinkValidity, renderTerminalQr } from "./terminal-qr.js";
 import { resolveTuttiHome } from "../../providers/openai/index.js";
 import { readCliVersion } from "./version.js";
-import { readProjectIdentity } from "./project-identity.js";
+import { resolveRelayUrl } from "./launch.js";
 const PROJECT_ID_DISPLAY_MIN_LENGTH = 12;
 function resolveProject(target, options = {}) {
     return resolveManagedProjectContext({
@@ -20,16 +20,6 @@ function resolveProject(target, options = {}) {
         ...(options.env === undefined ? {} : { env: options.env }),
     });
 }
-function projectIdsFromTuttiHome(tuttiHome) {
-    const projectsRoot = join(tuttiHome, "projects");
-    if (!existsSync(projectsRoot)) {
-        return [];
-    }
-    return readdirSync(projectsRoot, { withFileTypes: true })
-        .filter((entry) => entry.isDirectory() && isPrefixedId(entry.name, ID_PREFIXES.project))
-        .map((entry) => entry.name)
-        .sort();
-}
 function readEndpointFile(tuttiHome, projectId) {
     try {
         return readMachineRuntimeEndpoint(tuttiHome, projectId);
@@ -38,37 +28,32 @@ function readEndpointFile(tuttiHome, projectId) {
         return null;
     }
 }
-function readBindingFile(tuttiHome, projectId) {
-    try {
-        return readMachineProjectBinding(tuttiHome, projectId);
+function runtimeStatus(inspection) {
+    if (inspection.binding.kind === "invalid" || inspection.endpoint.kind === "invalid") {
+        return "invalid";
     }
-    catch {
-        return null;
+    if (inspection.workspace.kind === "missing") {
+        return "workspace-missing";
     }
-}
-function workspaceBelongsToProject(workspaceRoot, projectId) {
-    if (!existsSync(workspaceRoot)) {
-        return false;
+    if (inspection.workspace.kind === "replaced" ||
+        inspection.workspace.kind === "not_a_tutti_project" ||
+        inspection.workspace.kind === "unreadable" ||
+        inspection.host.kind === "identity_mismatch") {
+        return "workspace-replaced";
     }
-    try {
-        const identity = readProjectIdentity(workspaceRoot);
-        return identity.kind === "present" && identity.project_id === projectId;
+    if (inspection.host.kind === "stale") {
+        return "stale";
     }
-    catch {
-        return false;
+    if (inspection.host.kind === "stopped") {
+        return "stopped";
     }
-}
-async function cleanupOrphanedRuntimeProject(options) {
-    if (options.hostAlive) {
-        await requestHostLocalShutdown({
-            endpoint: options.endpoint,
-            ...(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
-        }).catch(() => undefined);
+    if (inspection.relay === "connected") {
+        return "online";
     }
-    deleteMachineProjectLocalState({
-        tuttiHome: options.tuttiHome,
-        projectId: options.projectId,
-    });
+    if (inspection.relay === "connecting" || inspection.relay === "reconnecting") {
+        return "reconnecting";
+    }
+    return "relay-unavailable";
 }
 export function formatProjectIdForDisplay(projectId, projectIds) {
     for (let length = Math.min(PROJECT_ID_DISPLAY_MIN_LENGTH, projectId.length); length <= projectId.length; length += 1) {
@@ -82,60 +67,50 @@ export function formatProjectIdForDisplay(projectId, projectIds) {
 export async function listRuntimeProjects(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const tuttiHome = resolveTuttiHome(options.env?.TUTTI_HOME, cwd);
-    const probe = createRuntimeEndpointProbe(options.fetchImpl ?? fetch);
     const rows = [];
-    for (const projectId of projectIdsFromTuttiHome(tuttiHome)) {
-        const endpoint = readEndpointFile(tuttiHome, projectId);
-        if (endpoint === null) {
-            continue;
-        }
-        const binding = readBindingFile(tuttiHome, projectId);
-        const workspaceRoot = binding?.workspace_root ?? endpoint.workspace_root;
-        const displayName = binding?.workspace_root === undefined
-            ? projectId
-            : binding.workspace_root.split(/[\\/]/u).pop() ?? projectId;
-        const health = await probe(endpoint);
-        if (!workspaceBelongsToProject(workspaceRoot, projectId)) {
-            await cleanupOrphanedRuntimeProject({
-                tuttiHome,
-                projectId,
-                endpoint,
-                hostAlive: health.kind === "alive",
-                ...(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
-            });
-            continue;
-        }
-        if (health.kind === "stale") {
-            rows.push({
-                project_id: projectId,
-                status: "stale",
-                display_name: displayName,
-                workspace_root: workspaceRoot,
-                endpoint: endpoint.base_url,
-            });
+    const inspections = await inspectMachineProjects({
+        tuttiHome,
+        ...(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+    });
+    for (const inspection of inspections) {
+        if (options.all !== true && inspection.endpoint.kind === "missing") {
             continue;
         }
+        const endpoint = inspection.endpoint.kind === "valid" ? inspection.endpoint.record : undefined;
         const fetchOption = options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl };
-        const [project, provider, launchStatus] = await Promise.allSettled([
-            readHostLocalProject({ endpoint, ...fetchOption }),
-            readHostLocalProviderConfig({ endpoint, ...fetchOption }),
-            readHostLocalLaunchStatus({ endpoint, ...fetchOption }),
-        ]);
+        const [provider, launchStatus] = endpoint === undefined || inspection.host.kind !== "running"
+            ? [undefined, undefined]
+            : await Promise.all([
+                readHostLocalProviderConfig({ endpoint, ...fetchOption }).catch(() => undefined),
+                readHostLocalLaunchStatus({ endpoint, ...fetchOption }).catch(() => undefined),
+            ]);
         const row = {
-            project_id: projectId,
-            status: health.readiness?.relay === "connected" ? "online" : "offline",
-            display_name: project.status === "fulfilled" ? project.value.display_name : displayName,
-            workspace_root: workspaceRoot,
-            endpoint: endpoint.base_url,
+            project_id: inspection.project_id,
+            status: runtimeStatus(inspection),
+            display_name: inspection.display_name,
+            workspace_root: inspection.workspace_root ?? "-",
+            ...(endpoint === undefined ? {} : { endpoint: endpoint.base_url }),
         };
-        if (provider.status === "fulfilled") {
-            row.provider_status = provider.value.status;
+        if (provider !== undefined) {
+            row.provider_status = provider.status;
         }
-        if (launchStatus.status === "fulfilled" && launchStatus.value.relay?.relay_project_ref !== undefined) {
-            row.relay_project_ref = launchStatus.value.relay.relay_project_ref;
+        if (launchStatus?.relay?.relay_project_ref !== undefined) {
+            row.relay_project_ref = launchStatus.relay.relay_project_ref;
         }
-        if (launchStatus.status === "fulfilled" && launchStatus.value.relay?.join_url !== undefined) {
-            row.join_url = launchStatus.value.relay.join_url;
+        if (launchStatus?.relay?.join_url !== undefined) {
+            row.join_url = launchStatus.relay.join_url;
+        }
+        if (launchStatus?.relay_connection !== undefined) {
+            row.relay_connection_status = launchStatus.relay_connection.status;
+            if (launchStatus.relay_connection.last_connected_at !== undefined) {
+                row.last_connected_at = launchStatus.relay_connection.last_connected_at;
+            }
+            if (launchStatus.relay_connection.next_retry_at !== undefined) {
+                row.next_retry_at = launchStatus.relay_connection.next_retry_at;
+            }
+            if (launchStatus.relay_connection.reason_code !== undefined) {
+                row.relay_reason_code = launchStatus.relay_connection.reason_code;
+            }
         }
         rows.push(row);
     }
@@ -145,19 +120,29 @@ function formatTable(rows) {
     if (rows.length === 0) {
         return "No Tutti host processes found.";
     }
-    const header = ["STATUS", "ID", "PROJECT", "PROVIDER", "WORKSPACE"];
+    const header = ["STATUS", "ID", "PROJECT", "PROVIDER", "RELAY", "WORKSPACE"];
     const projectIds = rows.map((row) => row.project_id);
     const data = rows.map((row) => [
         row.status,
         formatProjectIdForDisplay(row.project_id, projectIds),
         row.display_name,
         row.provider_status ?? "-",
+        formatRelayRuntimeDetail(row),
         redactText(row.workspace_root),
     ]);
     const widths = header.map((label, index) => Math.max(label.length, ...data.map((row) => row[index]?.length ?? 0)));
     const line = (columns) => columns.map((column, index) => column.padEnd(widths[index] ?? column.length)).join("  ");
     return [line(header), line(widths.map((width) => "-".repeat(width))), ...data.map(line)].join("\n");
 }
+function formatRelayRuntimeDetail(row) {
+    const details = [
+        row.relay_connection_status,
+        ...(row.last_connected_at === undefined ? [] : [`last=${row.last_connected_at}`]),
+        ...(row.next_retry_at === undefined ? [] : [`retry=${row.next_retry_at}`]),
+        ...(row.relay_reason_code === undefined ? [] : [`reason=${row.relay_reason_code}`]),
+    ].filter((value) => value !== undefined && value !== "");
+    return details.length === 0 ? "-" : redactText(details.join(" "));
+}
 const CLEAR = "\u001B[2J\u001B[H";
 const HIDE_CURSOR = "\u001B[?25l";
 const SHOW_CURSOR = "\u001B[?25h";
@@ -186,7 +171,7 @@ function renderManager(options) {
         "",
     ];
     if (options.rows.length > 0) {
-        const header = ["", "STATUS", "ID", "PROJECT", "PROVIDER", "WORKSPACE"];
+        const header = ["", "STATUS", "ID", "PROJECT", "PROVIDER", "RELAY", "WORKSPACE"];
         const projectIds = options.rows.map((row) => row.project_id);
         const data = options.rows.map((row, index) => [
             index === options.selectedIndex ? ">" : " ",
@@ -194,6 +179,7 @@ function renderManager(options) {
             formatProjectIdForDisplay(row.project_id, projectIds),
             row.display_name,
             row.provider_status ?? "-",
+            formatRelayRuntimeDetail(row),
             redactText(row.workspace_root),
         ]);
         const widths = header.map((label, index) => Math.max(label.length, ...data.map((row) => row[index]?.length ?? 0)));
@@ -208,19 +194,20 @@ function renderManager(options) {
     }
     return lines.join("\n");
 }
-export async function runPsCommand() {
-    return formatTable(await listRuntimeProjects());
+export async function runPsCommand(options = {}) {
+    return formatTable(await listRuntimeProjects(options));
 }
 export async function runPsManageCommand(options = {}) {
     const stdin = options.stdin ?? process.stdin;
     const stdout = options.stdout ?? process.stdout;
+    const listOptions = options.all === undefined ? {} : { all: options.all };
     if (!stdin.isTTY || !stdout.isTTY) {
-        stdout.write(`${await runPsCommand()}\n`);
+        stdout.write(`${await runPsCommand(listOptions)}\n`);
         return;
     }
     emitKeypressEvents(stdin);
     stdin.setRawMode(true);
-    let rows = await listRuntimeProjects();
+    let rows = await listRuntimeProjects(listOptions);
     let selectedIndex = 0;
     let message;
     let detail;
@@ -257,7 +244,7 @@ export async function runPsManageCommand(options = {}) {
                 continue;
             }
             if (input.character === "r") {
-                rows = await listRuntimeProjects();
+                rows = await listRuntimeProjects(listOptions);
                 selectedIndex = Math.min(selectedIndex, Math.max(rows.length - 1, 0));
                 message = "Refreshed.";
                 detail = undefined;
@@ -273,7 +260,7 @@ export async function runPsManageCommand(options = {}) {
             }
             if (input.key.name === "return" || input.character === "i") {
                 try {
-                    detail = await runInviteCommand(project.workspace_root);
+                    detail = await runInviteCommand(project.project_id);
                     message = `Invite refreshed for ${project.display_name}.`;
                 }
                 catch (error) {
@@ -284,15 +271,15 @@ export async function runPsManageCommand(options = {}) {
                 continue;
             }
             if (input.character === "l") {
-                detail = runLogsCommand(project.workspace_root, 40);
+                detail = runLogsCommand(project.project_id, 40);
                 message = `Showing last 40 host log lines for ${project.display_name}.`;
                 render();
                 continue;
             }
             if (input.character === "s") {
                 try {
-                    message = await runStopCommand(project.workspace_root);
-                    rows = await listRuntimeProjects();
+                    message = await runStopCommand(project.project_id);
+                    rows = await listRuntimeProjects(listOptions);
                     selectedIndex = Math.min(selectedIndex, Math.max(rows.length - 1, 0));
                     detail = undefined;
                 }
@@ -317,14 +304,9 @@ export async function runStopCommand(target, options = {}) {
     const project = resolveProject(target, options);
     const endpoint = project.runtime_endpoint;
     if (endpoint === null) {
-        if (!project.workspace_exists) {
-            deleteMachineProjectLocalState({
-                tuttiHome: project.tutti_home,
-                projectId: project.project_id,
-            });
-            return `Deleted ${project.display_name}; the workspace no longer exists.`;
-        }
-        return "Tutti host is not running for this project.";
+        return project.workspace_exists
+            ? "Tutti host is not running for this project."
+            : `Tutti host is not running for ${project.display_name}; machine-local state was retained. Use \`tutti forget ${project.project_id}\` to delete it.`;
     }
     try {
         await requestHostLocalShutdown({
@@ -336,13 +318,121 @@ export async function runStopCommand(target, options = {}) {
         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.");
     }
     if (!project.workspace_exists) {
-        deleteMachineProjectLocalState({
-            tuttiHome: project.tutti_home,
+        return `Stopped ${project.display_name}; machine-local state was retained. Use \`tutti forget ${project.project_id}\` to delete it.`;
+    }
+    return `Stopped ${project.display_name}.`;
+}
+async function stopVerifiedHostBeforeDestructiveLifecycle(options) {
+    const inspection = await inspectMachineProject(options.projectId, {
+        tuttiHome: options.tuttiHome,
+        ...(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+    });
+    if (inspection.host.kind === "stale" &&
+        inspection.host.reason_code === "local_control_unavailable") {
+        throw new LaunchError("existing_server_unhealthy", "The host is reachable but its identity and shutdown control could not be verified", `Stop the host manually, then retry ${options.action} with the full project ID.`);
+    }
+    if (inspection.host.kind === "identity_mismatch") {
+        throw new LaunchError("existing_server_unhealthy", "The runtime endpoint belongs to a different Tutti project host", `Stop the host manually or remove the stale endpoint through launch recovery, then retry ${options.action} with the full project ID.`);
+    }
+    if (inspection.endpoint.kind !== "valid" || inspection.host.kind !== "running") {
+        return;
+    }
+    if (!inspection.host.identity_verified) {
+        throw new LaunchError("existing_server_unhealthy", `The running host identity could not be verified before ${options.action}`, `Stop the host manually, then retry ${options.action} with the full project ID.`);
+    }
+    const fetchImpl = options.fetchImpl ?? fetch;
+    try {
+        await requestExistingHostShutdown({
+            endpoint: inspection.endpoint.record,
+            fetchImpl,
+            probeRuntimeEndpoint: createRuntimeEndpointProbe(fetchImpl),
+            shutdownWaitMs: options.shutdownWaitMs ?? 2_000,
+        });
+    }
+    catch (error) {
+        throw new LaunchError("existing_server_unhealthy", `Could not safely stop the host before ${options.action}: ${formatCliErrorReason(error)}`, `The project state was retained. Stop the host manually, then retry ${options.action} with the full project ID.`);
+    }
+}
+export async function runArchiveCommand(target, options = {}) {
+    const project = resolveProject(target, options);
+    const relayProjectRef = project.binding?.relay_project_ref;
+    if (relayProjectRef === undefined) {
+        throw new LaunchError("relay_registration_failed", "This machine-local project has no Relay project binding to archive", "Run `tutti launch` to establish a Relay binding, or use `tutti forget` for local-only cleanup.");
+    }
+    const interactive = options.interactive ?? (process.stdin.isTTY === true && process.stdout.isTTY === true);
+    if (options.yes !== true) {
+        if (!interactive) {
+            throw new LaunchError("archive_confirmation_required", "Archive requires explicit confirmation in a non-interactive terminal", `Re-run \`tutti archive ${project.project_id} --yes\` after verifying the project ID and global impact.`);
+        }
+        const accepted = (await options.confirm?.([
+            `Archive ${project.display_name} (${project.project_id}) on Relay?`,
+            "",
+            "This hides the project for all members and revokes its join link and client sessions.",
+            "Memberships and machine-local project state are retained.",
+        ].join("\n"))) ?? false;
+        if (!accepted) {
+            throw new LaunchError("archive_rejected", "Relay project archive was not confirmed", "No Relay or machine-local project state was changed.");
+        }
+    }
+    const hostSecret = readHostRegistrationSecret(project.tutti_home, project.project_id);
+    await stopVerifiedHostBeforeDestructiveLifecycle({
+        projectId: project.project_id,
+        tuttiHome: project.tutti_home,
+        action: "archive",
+        ...(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+        ...(options.shutdownWaitMs === undefined ? {} : { shutdownWaitMs: options.shutdownWaitMs }),
+    });
+    let response;
+    try {
+        response = await archiveRelayProjectAtRelay({
+            relayUrl: resolveRelayUrl(options.env),
             projectId: project.project_id,
+            relayProjectRef,
+            hostRegistrationSecret: hostSecret.secret,
+            ...(options.fetchImpl === undefined ? {} : { fetch: options.fetchImpl }),
+            ...(options.now === undefined ? {} : { issuedAt: options.now() }),
         });
-        return `Stopped and deleted ${project.display_name}; the workspace no longer exists.`;
     }
-    return `Stopped ${project.display_name}.`;
+    catch (error) {
+        if (error instanceof RelayHostControlClientError && error.code === "relay_unavailable") {
+            throw new LaunchError("relay_unavailable", "Relay is unavailable, so the project was not archived", `Machine-local state was retained. Retry \`tutti archive ${project.project_id} --yes\` after Relay recovers.`);
+        }
+        throw new LaunchError("relay_registration_failed", `Relay rejected project archive${error instanceof RelayHostControlClientError && error.relayErrorCode !== undefined ? ` (${error.relayErrorCode})` : ""}`, "Machine-local state was retained. Verify the Relay binding and host credential, then retry archive.");
+    }
+    if (response.disposition.kind === "interrupted") {
+        throw new LaunchError("relay_registration_failed", "Relay project archive was interrupted before completion", `Machine-local state was retained. Retry \`tutti archive ${project.project_id} --yes\` with a new command.`);
+    }
+    return `${response.disposition.kind === "already_archived" ? "Already archived" : "Archived"} ${project.display_name} (${project.project_id}) on Relay. Memberships and machine-local state were retained. Use \`tutti forget ${project.project_id} --yes\` only if local cleanup is also intended.`;
+}
+export async function runForgetCommand(target, options = {}) {
+    const project = resolveProject(target, options);
+    const interactive = options.interactive ?? (process.stdin.isTTY === true && process.stdout.isTTY === true);
+    if (options.yes !== true) {
+        if (!interactive) {
+            throw new LaunchError("forget_confirmation_required", "Forget requires explicit confirmation in a non-interactive terminal", `Re-run \`tutti forget ${project.project_id} --yes\` after verifying the project ID.`);
+        }
+        const accepted = (await options.confirm?.([
+            `Forget ${project.display_name} (${project.project_id}) on this machine?`,
+            "",
+            "This deletes its local SQLite store, provider config/auth, skills, cache, binding, endpoint, and host credential.",
+            "The Relay project and other members are not archived or removed.",
+        ].join("\n"))) ?? false;
+        if (!accepted) {
+            throw new LaunchError("forget_rejected", "Machine-local project deletion was not confirmed", "No project state was deleted.");
+        }
+    }
+    await stopVerifiedHostBeforeDestructiveLifecycle({
+        projectId: project.project_id,
+        tuttiHome: project.tutti_home,
+        action: "forget",
+        ...(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+        ...(options.shutdownWaitMs === undefined ? {} : { shutdownWaitMs: options.shutdownWaitMs }),
+    });
+    deleteMachineProjectLocalState({
+        tuttiHome: project.tutti_home,
+        projectId: project.project_id,
+    });
+    return `Forgot ${project.display_name} (${project.project_id}) on this machine. The Relay project and memberships were not archived.`;
 }
 export async function runInviteCommand(target) {
     const project = resolveProject(target);
@@ -398,17 +488,44 @@ export function runLogsCommand(target, tailLines = 120) {
     const lines = readFileSync(logPath, "utf8").split(/\r?\n/u).filter(Boolean).slice(-tailLines);
     return lines.length === 0 ? "Host log is empty." : lines.join("\n");
 }
-export function runDoctorCommand(target, options = {}) {
+export async function runDoctorCommand(target, options = {}) {
     const checks = [];
     checks.push(`Node: ${process.version}`);
     checks.push(`Tutti: ${readCliVersion()}`);
     try {
         const project = resolveProject(target, options);
+        const inventory = inspectMachineProjectInventory(project.project_id, project.tutti_home);
         checks.push(`Project: ${project.display_name}`);
         checks.push(`Project ID: ${project.project_id}`);
-        checks.push(`Workspace: ${project.workspace_exists ? redactText(project.workspace_root) : "missing"}`);
+        checks.push(`Workspace: ${inventory.workspace.kind}${project.workspace_exists ? ` (${redactText(project.workspace_root)})` : ""}`);
         checks.push(`Provider: ${project.provider_config.status}`);
         checks.push(`Host: ${project.runtime_endpoint === null ? "not running" : project.runtime_endpoint.base_url}`);
+        if (project.runtime_endpoint !== null) {
+            try {
+                const launchStatus = await readHostLocalLaunchStatus({
+                    endpoint: project.runtime_endpoint,
+                    ...(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+                });
+                if (launchStatus.project_id !== project.project_id) {
+                    checks.push("Relay: unknown (host identity unverified)");
+                }
+                else {
+                    checks.push(`Relay: ${launchStatus.relay_connection?.status ?? "unknown"}`);
+                    if (launchStatus.relay_connection?.last_connected_at !== undefined) {
+                        checks.push(`Relay last connected: ${launchStatus.relay_connection.last_connected_at}`);
+                    }
+                    if (launchStatus.relay_connection?.next_retry_at !== undefined) {
+                        checks.push(`Relay next retry: ${launchStatus.relay_connection.next_retry_at}`);
+                    }
+                    if (launchStatus.relay_connection?.reason_code !== undefined) {
+                        checks.push(`Relay reason: ${redactText(launchStatus.relay_connection.reason_code)}`);
+                    }
+                }
+            }
+            catch {
+                checks.push("Relay: unknown (host-local status unavailable)");
+            }
+        }
     }
     catch (error) {
         checks.push("Project: unavailable");

package/dist/server-shell/http/routes/local-control.d.ts

@@ -1,9 +1,11 @@
 import type { FastifyInstance } from "fastify";
 import type { ProviderConfigProjection } from "@tutti/shared/schemas/api";
+import type { ProjectId } from "@tutti/shared/ids";
 export type HostLocalControlOptions = {
     token: string;
     getLaunchStatus?: () => HostLocalLaunchStatus;
     refreshInvite?: () => Promise<HostLocalLaunchStatus>;
+    reconnectRelay?: () => Promise<HostLocalLaunchStatus>;
     project?: {
         get: () => HostLocalProjectProjection;
         update: (input: HostLocalProjectBody) => HostLocalProjectProjection;
@@ -15,6 +17,14 @@ export type HostLocalControlOptions = {
     requestShutdown: () => void;
 };
 export type HostLocalLaunchStatus = {
+    project_id?: ProjectId;
+    relay_connection?: {
+        status: "connecting" | "connected" | "reconnecting" | "unavailable" | "stopped";
+        attempt?: number;
+        next_retry_at?: string;
+        last_connected_at?: string;
+        reason_code?: string;
+    };
     relay?: {
         relay_project_ref: string;
         host_connection_ref: string;

package/dist/server-shell/http/routes/local-control.js

@@ -115,6 +115,22 @@ const HostLocalLaunchStatusResponseSchema = {
     type: "object",
     additionalProperties: false,
     properties: {
+        project_id: { type: "string" },
+        relay_connection: {
+            type: "object",
+            required: ["status"],
+            additionalProperties: false,
+            properties: {
+                status: {
+                    type: "string",
+                    enum: ["connecting", "connected", "reconnecting", "unavailable", "stopped"],
+                },
+                attempt: { type: "integer", minimum: 0 },
+                next_retry_at: { type: "string" },
+                last_connected_at: { type: "string" },
+                reason_code: { type: "string" },
+            },
+        },
         relay: {
             type: "object",
             required: [
@@ -190,6 +206,19 @@ export function registerHostLocalControlRoutes(app, options) {
         requireLocalToken(request.headers.authorization);
         return options.getLaunchStatus?.() ?? {};
     });
+    app.post("/host-local/v1/relay/reconnect", {
+        schema: {
+            response: {
+                200: HostLocalLaunchStatusResponseSchema,
+            },
+        },
+    }, async (request) => {
+        requireLocalToken(request.headers.authorization);
+        if (options.reconnectRelay === undefined) {
+            return options.getLaunchStatus?.() ?? {};
+        }
+        return await options.reconnectRelay();
+    });
     app.post("/host-local/v1/invite/rotate", {
         schema: {
             response: {

package/node_modules/@tutti/relay-client/dist/host-control.d.ts

@@ -81,6 +81,17 @@ export type RefreshRelayJoinTokenPayload = {
 export type RefreshRelayJoinTokenResponse = {
     join_token: JoinTokenProjection;
 };
+export type ArchiveRelayProjectResponse = {
+    command_id: IdempotencyKey;
+    disposition: {
+        kind: "archived";
+    } | {
+        kind: "already_archived";
+    } | {
+        kind: "interrupted";
+        retry_with_new_command_id: true;
+    };
+};
 export type RelayUploadProjection = {
     upload_id: RelayUploadRef;
     relay_project_ref: RelayProjectRef;
@@ -122,6 +133,7 @@ export type RegisterRelayHostConnectionOptions = {
     capabilities?: Partial<RegisterRelayHostConnectionPayload["host"]["capabilities"]>;
     fetch?: RelayHostControlFetch;
     timeoutMs?: number;
+    signal?: AbortSignal;
 };
 export type RefreshRelayJoinTokenOptions = {
     relayUrl: string;
@@ -136,6 +148,16 @@ export type RefreshRelayJoinTokenOptions = {
     fetch?: RelayHostControlFetch;
     timeoutMs?: number;
 };
+export type ArchiveRelayProjectOptions = {
+    relayUrl: string;
+    projectId: ProjectId;
+    relayProjectRef: RelayProjectRef;
+    hostRegistrationSecret: string;
+    commandId?: IdempotencyKey;
+    issuedAt?: Date;
+    fetch?: RelayHostControlFetch;
+    timeoutMs?: number;
+};
 export type ResolveRelayUploadOptions = {
     relayUrl: string;
     projectId: ProjectId;
@@ -159,6 +181,7 @@ export declare class RelayHostControlClientError extends Error {
 }
 export declare function registerRelayHostConnection(options: RegisterRelayHostConnectionOptions): Promise<RegisterRelayHostConnectionResponse>;
 export declare function refreshRelayJoinToken(options: RefreshRelayJoinTokenOptions): Promise<RefreshRelayJoinTokenResponse>;
+export declare function archiveRelayProject(options: ArchiveRelayProjectOptions): Promise<ArchiveRelayProjectResponse>;
 export declare function resolveRelayUpload(options: ResolveRelayUploadOptions): Promise<ResolveRelayUploadResponse>;
 export declare function completeRelayUpload(options: CompleteRelayUploadOptions): Promise<CompleteRelayUploadResponse>;
 //# sourceMappingURL=host-control.d.ts.map