@xfey/tutti 0.1.29 → 0.1.30

package/README.md

@@ -27,7 +27,7 @@
 - 已具备 Fastify host shell、后台 host manager CLI 套件、Dev Runner、Host Project API、SSE、SQLite store、collaboration-state、workspace read-state、project timeline observability helper、Control Plane、Procedure / Run、workspace-ops、checks、Relay staged upload finalize、user skills 文件服务、artifacts 可视化产物查看层和 OpenAI / Codex provider 接入。
 - Host server 支持在显式 `webStatic.root` 或 packaged `web/` 存在时服务 Web 静态产物；`/api/*`、SSE、health 和 host-local control 不被 SPA fallback 吞掉。
 - Root `pack:dry-run` 会先清理 build output、重新构建，再复制 `apps/web/dist` 到 package-local `web/`，生成临时 staging `@xfey/tutti` artifact，并校验 npm pack 文件列表包含 CLI、migrations、prompts、Web index、bundled `@tutti/shared` / `@tutti/relay-client` 以及它们的外部 runtime dependencies，同时排除源码、source map、日志、SQLite、`.env`、`.tutti-dev` 与测试产物。
-- Root `smoke:packed-cli` 同样从干净 build output 生成 staging `@xfey/tutti` tarball、在临时目录安装，并验证 SQLite native binding、`tutti --help` / `tutti launch --help` / `tutti --version`、migrations、prompts、Web static index、bundled internal dependencies、bundled external runtime dependencies、CLI QR dependency、仓库锁定的 `@openai/codex` binary 可执行性和临时全局安装路径；该 smoke 不需要 Tutti source repo 存在。
+- Root `smoke:packed-cli` 同样从干净 build output 生成 staging `@xfey/tutti` tarball、在临时目录安装，并验证 SQLite native binding、`tutti --help` / `tutti launch --help` / `tutti archive --help` / `tutti --version`、migrations、prompts、Web static index、bundled internal dependencies、bundled external runtime dependencies、CLI QR dependency、仓库锁定的 `@openai/codex` binary 可执行性和临时全局安装路径；该 smoke 不需要 Tutti source repo 存在。
 - `prompts/` 是所有模型-facing prompt、指令模板和 Codex 执行模板的统一落点；长 prompt 不内联在 TypeScript 中。
 - Host Project API 只信任 Relay tunnel metadata 注入的 `relay_session_context`；direct loopback 缺少可信 context 时不作为浏览器工作区入口。
 - 详细模块落点见 `src/README.md`；logger redaction、command idempotency、schema、provider 与 Codex 边界以 `docs/system/` 对应 canonical 文档为准。

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

@@ -15,12 +15,21 @@ export type CliCommand = {
 } | {
     kind: "ps";
     manage: boolean;
+    all: boolean;
 } | {
     kind: "stop";
     target?: string;
 } | {
     kind: "invite";
     target?: string;
+} | {
+    kind: "archive";
+    target: string;
+    yes: boolean;
+} | {
+    kind: "forget";
+    target: string;
+    yes: boolean;
 } | {
     kind: "logs";
     target?: string;

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

@@ -49,10 +49,7 @@ function readOptionalTarget(args) {
 export function parseCliArgs(argv, cwd = process.cwd()) {
     const args = [...argv];
     const command = args.shift();
-    if (command === undefined ||
-        command === "--help" ||
-        command === "-h" ||
-        command === "help") {
+    if (command === undefined || command === "--help" || command === "-h" || command === "help") {
         return { kind: "help", ...(args[0] === undefined ? {} : { topic: args[0] }) };
     }
     if (command === "--version" || command === "-v" || command === "version") {
@@ -115,17 +112,22 @@ export function parseCliArgs(argv, cwd = process.cwd()) {
     }
     if (command === "ps") {
         let manage = false;
+        let all = false;
         for (const arg of args) {
             if (arg === "--manage") {
                 manage = true;
                 continue;
             }
+            if (arg === "--all") {
+                all = true;
+                continue;
+            }
             if (isHelpArg(arg)) {
                 return { kind: "help", topic: "ps" };
             }
             throw new LaunchError("git_bootstrap_failed", `Unsupported option: ${arg}`, "Use `tutti ps --help` to see supported ps options.");
         }
-        return { kind: "ps", manage };
+        return { kind: "ps", manage, all };
     }
     if (command === "stop") {
         if (hasHelpArg(args)) {
@@ -141,6 +143,54 @@ export function parseCliArgs(argv, cwd = process.cwd()) {
         const target = readOptionalTarget(args);
         return { kind: "invite", ...(target === undefined ? {} : { target }) };
     }
+    if (command === "archive") {
+        if (hasHelpArg(args)) {
+            return { kind: "help", topic: "archive" };
+        }
+        let target;
+        let yes = false;
+        for (const arg of args) {
+            if (arg === "--yes") {
+                yes = true;
+                continue;
+            }
+            if (arg.startsWith("--")) {
+                throw new LaunchError("git_bootstrap_failed", `Unsupported option: ${arg}`, "Run `tutti archive --help` to see supported archive options.");
+            }
+            if (target !== undefined) {
+                throw new LaunchError("git_bootstrap_failed", "Only one archive target is supported", "Run `tutti archive <target> [--yes]`.");
+            }
+            target = arg;
+        }
+        if (target === undefined) {
+            throw new LaunchError("project_target_not_found", "Archive requires a project target", "Run `tutti archive <project-id> [--yes]`.");
+        }
+        return { kind: "archive", target, yes };
+    }
+    if (command === "forget") {
+        if (hasHelpArg(args)) {
+            return { kind: "help", topic: "forget" };
+        }
+        let target;
+        let yes = false;
+        for (const arg of args) {
+            if (arg === "--yes") {
+                yes = true;
+                continue;
+            }
+            if (arg.startsWith("--")) {
+                throw new LaunchError("git_bootstrap_failed", `Unsupported option: ${arg}`, "Run `tutti forget --help` to see supported forget options.");
+            }
+            if (target !== undefined) {
+                throw new LaunchError("git_bootstrap_failed", "Only one forget target is supported", "Run `tutti forget <target> [--yes]`.");
+            }
+            target = arg;
+        }
+        if (target === undefined) {
+            throw new LaunchError("project_target_not_found", "Forget requires a project target", "Run `tutti forget <project-id> [--yes]`.");
+        }
+        return { kind: "forget", target, yes };
+    }
     if (command === "logs") {
         if (hasHelpArg(args)) {
             return { kind: "help", topic: "logs" };

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

@@ -1,16 +1,18 @@
 #!/usr/bin/env node
 import { formatCliError } from "./errors.js";
 import { parseCliArgs } from "./args.js";
-import { runBackgroundLaunchCommand, runForegroundLaunchCommand, runInternalHostRunCommand, } from "./launch-command.js";
+import { confirmTextFromTty, runBackgroundLaunchCommand, runForegroundLaunchCommand, runInternalHostRunCommand, } from "./launch-command.js";
 import { resolveExistingProjectContext } from "./project-resolver.js";
 import { runProviderSetupTui } from "./provider-tui.js";
-import { runDoctorCommand, runInviteCommand, runLogsCommand, runProviderStatusCommand, runPsManageCommand, runPsCommand, runStopCommand, } from "./runtime-commands.js";
+import { runArchiveCommand, runDoctorCommand, runForgetCommand, runInviteCommand, runLogsCommand, runProviderStatusCommand, runPsManageCommand, runPsCommand, runStopCommand, } from "./runtime-commands.js";
 import { readCliVersion } from "./version.js";
 const HELP_TEXT = `Usage:
   tutti launch [target] [--yes] [--foreground]
-  tutti ps [--manage]
+  tutti ps [--manage] [--all]
   tutti invite [target]
   tutti stop [target]
+  tutti archive <target> [--yes]
+  tutti forget <target> [--yes]
   tutti logs [target] [--tail 120]
   tutti provider setup [target]
   tutti provider status [target]
@@ -42,10 +44,11 @@ Commands:
   status   Show the redacted provider status for a project.
 `;
 const PS_HELP_TEXT = `Usage:
-  tutti ps [--manage]
+  tutti ps [--manage] [--all]
 
 Options:
   --manage   Open the keyboard project manager.
+  --all      Include stopped and binding-only machine projects.
 `;
 const INVITE_HELP_TEXT = `Usage:
   tutti invite [target]
@@ -57,6 +60,24 @@ const STOP_HELP_TEXT = `Usage:
 
 Stops the background Tutti host for a project.
 `;
+const ARCHIVE_HELP_TEXT = `Usage:
+  tutti archive <target> [--yes]
+
+Archives the Relay project for all members after safely stopping its host.
+Memberships and machine-local project state are retained.
+
+Options:
+  --yes   Confirm global Relay archive in a non-interactive terminal.
+`;
+const FORGET_HELP_TEXT = `Usage:
+  tutti forget <target> [--yes]
+
+Deletes this project's machine-local state after safely stopping its host.
+It does not archive the Relay project or change other members.
+
+Options:
+  --yes   Confirm destructive local deletion in a non-interactive terminal.
+`;
 const LOGS_HELP_TEXT = `Usage:
   tutti logs [target] [--tail 120]
 
@@ -83,6 +104,12 @@ function helpForTopic(topic) {
     if (topic === "stop") {
         return STOP_HELP_TEXT;
     }
+    if (topic === "archive") {
+        return ARCHIVE_HELP_TEXT;
+    }
+    if (topic === "forget") {
+        return FORGET_HELP_TEXT;
+    }
     if (topic === "logs") {
         return LOGS_HELP_TEXT;
     }
@@ -147,15 +174,27 @@ try {
             break;
         case "ps":
             if (command.manage) {
-                await runPsManageCommand();
+                await runPsManageCommand({ all: command.all });
             }
             else {
-                process.stdout.write(`${await runPsCommand()}\n`);
+                process.stdout.write(`${await runPsCommand({ all: command.all })}\n`);
             }
             break;
         case "stop":
             process.stdout.write(`${await runStopCommand(command.target)}\n`);
             break;
+        case "archive":
+            process.stdout.write(`${await runArchiveCommand(command.target, {
+                yes: command.yes,
+                confirm: confirmTextFromTty,
+            })}\n`);
+            break;
+        case "forget":
+            process.stdout.write(`${await runForgetCommand(command.target, {
+                yes: command.yes,
+                confirm: confirmTextFromTty,
+            })}\n`);
+            break;
         case "invite":
             process.stdout.write(`${await runInviteCommand(command.target)}\n`);
             break;
@@ -169,7 +208,7 @@ try {
             process.stdout.write(`${runProviderStatusCommand(command.target)}\n`);
             break;
         case "doctor":
-            process.stdout.write(`${runDoctorCommand(command.target)}\n`);
+            process.stdout.write(`${await runDoctorCommand(command.target)}\n`);
             break;
     }
 }

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" | "host_not_running" | "project_target_ambiguous" | "project_target_not_found" | "provider_configuration_required" | "provider_setup_cancelled" | "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" | "archive_confirmation_required" | "archive_rejected" | "forget_confirmation_required" | "forget_rejected" | "project_target_ambiguous" | "project_target_not_found" | "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;

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

@@ -44,7 +44,12 @@ export function formatCliError(error) {
         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 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}: ${formatBoundedDetail(value)}`);

package/dist/server-shell/cli/host-lifecycle.d.ts

@@ -37,6 +37,7 @@ export type StartLaunchProjectOptions = LaunchPreparationOptions & {
     connectRelayHostTunnel?: RelayHostTunnelConnector;
     probeRuntimeEndpoint?: HostRuntimeEndpointProbe;
     registerRelayHostConnection?: RelayHostConnectionRegistrar;
+    reconnectWaitMs?: number;
     shutdownWaitMs?: number;
 };
 export type FormatLaunchLifecycleResultOptions = {

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

@@ -4,15 +4,19 @@ import { createHostServer } from "../http/create-server.js";
 import { createHostProjectApiTunnelRequestHandler, createHostProjectApiTunnelStreamRequestHandler, } from "../http/host-tunnel.js";
 import { LaunchError } from "./errors.js";
 import { TUTTI_MAINLINE_BRANCH } from "./git-bootstrap.js";
-import { relayStateFromLaunchStatus, relayStatusFromLocalStatus } from "./host-relay-status.js";
+import { hostLocalLaunchStatusFromConnectionManagerState, relayStateFromConnectionManagerState, relayStatusFromLocalStatus, } from "./host-relay-status.js";
+import { createHostRelayConnectionManager, } from "./host-relay-connection-manager.js";
 import { createRuntimeEndpointProbe, readExistingHostLaunchStatus, requestExistingHostShutdown, } from "./host-runtime-endpoint.js";
+import { reconnectHostLocalRelay } from "./local-control-client.js";
 import { HOST_SERVER_VERSION, startForegroundHostServer, } from "./host-server-runtime.js";
 import { deleteMachineRuntimeEndpoint, readHostRegistrationSecret, readMachineProjectBinding, readMachineRuntimeEndpoint, } from "./machine-local.js";
+import { inspectMachineProject, inspectMachineProjectInventories, normalizeMachineWorkspacePath, } from "./machine-project-inspector.js";
 import { prepareLaunchProject, resolveLaunchLocalContext, } from "./launch.js";
 import { registerHostWithRelay, relayErrorToLaunchError, } from "./relay-registration.js";
 import { formatJoinLinkValidity, formatTerminalLink } from "./terminal-qr.js";
 export { createRuntimeEndpointProbe } from "./host-runtime-endpoint.js";
 const DEFAULT_SHUTDOWN_WAIT_MS = 2_000;
+const DEFAULT_RECONNECT_WAIT_MS = 8_000;
 function urlLine(label, value, options) {
     return `${label}: ${formatTerminalLink(value, options)}`;
 }
@@ -72,21 +76,106 @@ function createSummary(options) {
     }
     return summary;
 }
+async function reconcileReplacedWorkspaceHosts(options) {
+    const normalizedWorkspaceRoot = normalizeMachineWorkspacePath(options.workspaceRoot);
+    const replacedProjects = inspectMachineProjectInventories(options.tuttiHome).filter((inspection) => inspection.project_id !== options.projectId &&
+        inspection.normalized_workspace_root === normalizedWorkspaceRoot &&
+        inspection.workspace.kind === "replaced" &&
+        inspection.workspace.actual_project_id === options.projectId &&
+        inspection.endpoint.kind === "valid" &&
+        normalizeMachineWorkspacePath(inspection.endpoint.record.workspace_root) ===
+            normalizedWorkspaceRoot);
+    for (const replacedProject of replacedProjects) {
+        const inspection = await inspectMachineProject(replacedProject.project_id, {
+            tuttiHome: options.tuttiHome,
+            fetchImpl: options.fetchImpl,
+            probeRuntimeEndpoint: options.probeRuntimeEndpoint,
+        });
+        if (inspection.endpoint.kind !== "valid") {
+            continue;
+        }
+        if ((inspection.host.kind === "running" && !inspection.host.identity_verified) ||
+            (inspection.host.kind === "stale" &&
+                inspection.host.reason_code === "local_control_unavailable")) {
+            throw new LaunchError("takeover_failed", "The replaced project host identity could not be verified before shutdown", "Stop the old host manually, then run `tutti launch` again.");
+        }
+        const shouldRequestShutdown = inspection.host.kind === "running";
+        if (shouldRequestShutdown) {
+            await requestExistingHostShutdown({
+                endpoint: inspection.endpoint.record,
+                fetchImpl: options.fetchImpl,
+                probeRuntimeEndpoint: options.probeRuntimeEndpoint,
+                shutdownWaitMs: options.shutdownWaitMs,
+            });
+        }
+        if (shouldRequestShutdown ||
+            inspection.host.kind === "stale" ||
+            inspection.host.kind === "identity_mismatch") {
+            deleteMachineRuntimeEndpoint({
+                tuttiHome: options.tuttiHome,
+                projectId: inspection.project_id,
+                expectedToken: inspection.endpoint.record.token,
+            });
+        }
+    }
+}
 export async function startLaunchProject(options) {
     const context = resolveLaunchLocalContext(options);
     const fetchImpl = options.fetch ?? fetch;
     const probeRuntimeEndpoint = options.probeRuntimeEndpoint ?? createRuntimeEndpointProbe(fetchImpl);
     const shutdownWaitMs = options.shutdownWaitMs ?? DEFAULT_SHUTDOWN_WAIT_MS;
+    const reconnectWaitMs = options.reconnectWaitMs ?? DEFAULT_RECONNECT_WAIT_MS;
     let startupStatus = context.existing_identity.kind === "missing" ? "created" : "recovered";
     let allowWorkspaceRootTakeover = false;
     if (context.existing_identity.kind === "present") {
         const projectId = context.existing_identity.project_id;
+        await reconcileReplacedWorkspaceHosts({
+            tuttiHome: context.tutti_home,
+            workspaceRoot: context.workspace_root,
+            projectId,
+            fetchImpl,
+            probeRuntimeEndpoint,
+            shutdownWaitMs,
+        });
         const endpoint = readMachineRuntimeEndpoint(context.tutti_home, projectId);
         if (endpoint !== null) {
             const sameWorkspace = resolve(endpoint.workspace_root) === context.workspace_root;
             const probe = await probeRuntimeEndpoint(endpoint);
             if (probe.kind === "alive" && sameWorkspace) {
-                const launchStatus = await readExistingHostLaunchStatus({ endpoint, fetchImpl });
+                let launchStatus = await readExistingHostLaunchStatus({ endpoint, fetchImpl });
+                if (launchStatus.project_id !== projectId) {
+                    throw new LaunchError("existing_server_unhealthy", "The existing Tutti host identity could not be verified for this project", "Stop the existing host manually, then run `tutti launch` again.");
+                }
+                const relayConnected = launchStatus.relay_connection?.status === "connected" ||
+                    (launchStatus.relay_connection === undefined && probe.readiness?.relay === "connected");
+                if (!relayConnected) {
+                    try {
+                        launchStatus = await reconnectHostLocalRelay({
+                            endpoint,
+                            fetchImpl,
+                            timeoutMs: reconnectWaitMs,
+                        });
+                    }
+                    catch {
+                        throw new LaunchError("relay_unavailable", "The existing Tutti host could not complete a bounded Relay reconnect", "The host is still running. Check Relay connectivity, then run `tutti launch` again.");
+                    }
+                    if (launchStatus.project_id !== projectId) {
+                        throw new LaunchError("existing_server_unhealthy", "The reconnected Tutti host identity does not match this project", "The existing host was preserved. Stop it manually, then run `tutti launch` again.");
+                    }
+                    const reconnectedProbe = await probeRuntimeEndpoint(endpoint);
+                    const reconnected = launchStatus.relay_connection?.status === "connected" ||
+                        (launchStatus.relay_connection === undefined &&
+                            reconnectedProbe.kind === "alive" &&
+                            reconnectedProbe.readiness?.relay === "connected");
+                    if (!reconnected) {
+                        throw new LaunchError("relay_unavailable", "The existing Tutti host is running but Relay reconnection is not complete", "The host was preserved. Check `tutti ps` or `tutti doctor`, then retry launch.", {
+                            relay_status: launchStatus.relay_connection?.status ?? "not_connected",
+                            ...(launchStatus.relay_connection?.reason_code === undefined
+                                ? {}
+                                : { reason_code: launchStatus.relay_connection.reason_code }),
+                        });
+                    }
+                }
                 const relay = relayStatusFromLocalStatus(launchStatus);
                 return {
                     kind: "connected",
@@ -154,58 +243,55 @@ export async function startLaunchProject(options) {
         ...options,
         allowWorkspaceRootTakeover,
     });
-    const launchStatus = {};
-    const refreshRelayJoinUrl = async () => {
-        if (launchStatus.relay === undefined) {
-            return relayStateFromLaunchStatus(preparation.relay_url, launchStatus);
-        }
-        const hostSecret = readHostRegistrationSecret(preparation.tutti_home, preparation.project_id);
-        const response = await refreshRelayJoinTokenWithRelay({
-            relayUrl: preparation.relay_url,
+    if (context.existing_identity.kind === "missing") {
+        await reconcileReplacedWorkspaceHosts({
+            tuttiHome: preparation.tutti_home,
+            workspaceRoot: preparation.workspace_root,
             projectId: preparation.project_id,
-            relayProjectRef: launchStatus.relay.relay_project_ref,
-            hostConnectionRef: launchStatus.relay.host_connection_ref,
-            hostRegistrationSecret: hostSecret.secret,
-            joinToken: { mode: "rotate" },
-            fetch: fetchImpl,
+            fetchImpl,
+            probeRuntimeEndpoint,
+            shutdownWaitMs,
         });
-        const relayWithoutJoinUrl = { ...launchStatus.relay };
-        delete relayWithoutJoinUrl.join_url;
-        launchStatus.relay = {
-            ...relayWithoutJoinUrl,
-            ...(response.join_token.join_url === undefined
-                ? {}
-                : { join_url: response.join_token.join_url }),
-            join_url_visibility: response.join_token.visibility,
-            join_token_expires_at: response.join_token.expires_at,
-            join_token_reusable: response.join_token.reusable,
-        };
-        return relayStateFromLaunchStatus(preparation.relay_url, launchStatus);
+    }
+    const relayRuntime = {};
+    const readConnectionState = () => relayRuntime.connectionManager?.getState() ?? {
+        status: "unavailable",
+        reason_code: "not_started",
+    };
+    const getLaunchStatus = () => hostLocalLaunchStatusFromConnectionManagerState(preparation.project_id, readConnectionState());
+    const refreshRelayJoinUrl = async () => {
+        if (relayRuntime.connectionManager === undefined) {
+            return relayStateFromConnectionManagerState(preparation.relay_url, readConnectionState());
+        }
+        await relayRuntime.connectionManager.refreshJoinUrl();
+        return relayStateFromConnectionManagerState(preparation.relay_url, relayRuntime.connectionManager.getState());
     };
     const host = await startForegroundHostServer({
         preparation,
         endpointHost: context.local_diagnostic_endpoint.host,
         endpointPort: context.local_diagnostic_endpoint.port,
         createServer: options.createServer ?? createHostServer,
-        getLaunchStatus: () => launchStatus,
+        getLaunchStatus,
         refreshRelayJoinUrl,
         ...(options.now === undefined ? {} : { now: options.now }),
     });
-    let relay;
-    try {
-        const registered = await registerHostWithRelay({
+    const connectionManager = createHostRelayConnectionManager({
+        tuttiHome: preparation.tutti_home,
+        projectId: preparation.project_id,
+        workspaceRoot: preparation.workspace_root,
+        registerConnection: async ({ joinTokenMode, signal }) => await registerHostWithRelay({
             preparation,
             fetchImpl,
             registerRelayHostConnection: options.registerRelayHostConnection ?? registerRelayHostConnectionWithRelay,
             serverVersion: HOST_SERVER_VERSION,
+            joinTokenMode,
+            signal,
             ...(options.now === undefined ? {} : { now: options.now }),
-        });
-        relay = registered.summary;
-        launchStatus.relay = relay;
-        const tunnel = (options.connectRelayHostTunnel ?? connectRelayHostTunnel)({
-            tunnelUrl: relay.tunnel_url,
-            relayProjectRef: relay.relay_project_ref,
-            hostConnectionRef: relay.host_connection_ref,
+        }),
+        connectTunnel: (registered) => (options.connectRelayHostTunnel ?? connectRelayHostTunnel)({
+            tunnelUrl: registered.summary.tunnel_url,
+            relayProjectRef: registered.summary.relay_project_ref,
+            hostConnectionRef: registered.summary.host_connection_ref,
             hostConnectionToken: registered.hostConnectionToken,
             handleRequest: createHostProjectApiTunnelRequestHandler({
                 app: host.app,
@@ -215,9 +301,37 @@ export async function startLaunchProject(options) {
                 baseUrl: host.runtime_endpoint.base_url,
                 trustedMetadataStore: host.trusted_relay_metadata_store,
             }),
-        });
-        await tunnel.connected;
-        host.attachRelayTunnel(tunnel);
+        }),
+        refreshJoinUrl: async (current) => {
+            const hostSecret = readHostRegistrationSecret(preparation.tutti_home, preparation.project_id);
+            const response = await refreshRelayJoinTokenWithRelay({
+                relayUrl: preparation.relay_url,
+                projectId: preparation.project_id,
+                relayProjectRef: current.relay_project_ref,
+                hostConnectionRef: current.host_connection_ref,
+                hostRegistrationSecret: hostSecret.secret,
+                joinToken: { mode: "rotate" },
+                fetch: fetchImpl,
+            });
+            const withoutJoinUrl = { ...current };
+            delete withoutJoinUrl.join_url;
+            return {
+                ...withoutJoinUrl,
+                ...(response.join_token.join_url === undefined
+                    ? {}
+                    : { join_url: response.join_token.join_url }),
+                join_url_visibility: response.join_token.visibility,
+                join_token_expires_at: response.join_token.expires_at,
+                join_token_reusable: response.join_token.reusable,
+            };
+        },
+        ...(options.now === undefined ? {} : { now: options.now }),
+    });
+    relayRuntime.connectionManager = connectionManager;
+    host.attachRelayConnectionManager(connectionManager);
+    let relay;
+    try {
+        relay = await connectionManager.start();
     }
     catch (error) {
         const launchError = error instanceof LaunchError || error instanceof RelayHostControlClientError

package/dist/server-shell/cli/host-relay-connection-manager.d.ts

@@ -0,0 +1,50 @@
+import { type RelayHostTunnelHandle } from "@tutti/relay-client";
+import type { ProjectId } from "@tutti/shared/ids";
+import type { HostLaunchRelaySummary, RegisteredRelayHostConnection } from "./relay-registration.js";
+export type HostRelayConnectionManagerState = {
+    status: "unavailable";
+    reason_code: "not_started" | "relay_unavailable" | "workspace_missing" | "workspace_replaced" | "workspace_unreadable" | "fatal_error";
+    error_code?: string;
+    next_retry_at?: string;
+    last_connection?: HostLaunchRelaySummary;
+} | {
+    status: "connecting";
+    attempt: 0;
+} | {
+    status: "connected";
+    connection: HostLaunchRelaySummary;
+} | {
+    status: "reconnecting";
+    attempt: number;
+    next_retry_at?: string;
+    last_connected_at?: string;
+    last_connection?: HostLaunchRelaySummary;
+} | {
+    status: "stopped";
+};
+export type HostRelayConnectionManager = {
+    start: () => Promise<HostLaunchRelaySummary>;
+    reconnectNow: () => Promise<HostRelayConnectionManagerState>;
+    refreshJoinUrl: () => Promise<HostLaunchRelaySummary>;
+    getState: () => HostRelayConnectionManagerState;
+    stop: () => Promise<void>;
+};
+export type CreateHostRelayConnectionManagerOptions = {
+    tuttiHome: string;
+    projectId: ProjectId;
+    workspaceRoot: string;
+    registerConnection: (options: {
+        joinTokenMode: "reuse_active" | "rotate";
+        signal: AbortSignal;
+    }) => Promise<RegisteredRelayHostConnection>;
+    connectTunnel: (registered: RegisteredRelayHostConnection) => RelayHostTunnelHandle;
+    refreshJoinUrl?: (connection: HostLaunchRelaySummary) => Promise<HostLaunchRelaySummary>;
+    onStateChange?: (state: HostRelayConnectionManagerState) => void;
+    retryDelaysMs?: readonly number[];
+    jitterRatio?: number;
+    workspaceCheckIntervalMs?: number;
+    now?: () => Date;
+    random?: () => number;
+};
+export declare function createHostRelayConnectionManager(options: CreateHostRelayConnectionManagerOptions): HostRelayConnectionManager;
+//# sourceMappingURL=host-relay-connection-manager.d.ts.map