@xfey/tutti 0.1.61 → 0.1.62

package/README.md

@@ -7,7 +7,7 @@
 它负责：
 
 - `tutti launch` 后的项目绑定、恢复和接管入口
-- 裸 `tutti` 经 lifecycle lock 启动 / 复用的版本感知 loopback Local Console、独立 invocation context，以及既有项目 Host 编排
+- 裸 `tutti` 经 lifecycle lock 启动 / 复用的版本感知 loopback Local Console、独立 invocation context、既有项目 Host 编排，以及可信全局npm安装的idle-only worker / completion自更新交接
 - 首次 eligible 裸 `tutti`、显式 `tutti desktop` 与严格 `tutti://projects` bridge 共用的用户级 desktop integration manager
 - Fastify API、SSE、packaged static Web 产物服务和 server 生命周期
 - SQLite store、migrations、repository 与协作真相读写
@@ -28,7 +28,7 @@
 
 ## 当前状态
 
-- 已具备 Fastify host shell、后台 host manager CLI 套件、用户级 desktop integration / strict `tutti://projects` bridge、带 `service status / stop / restart`、卸载前 `shutdown`、并发启动锁、版本替换、strict terminal / desktop browser context、idle / package update cleanup 与私有日志的机器级 Local Console、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 接入。
+- 已具备 Fastify host shell、后台 host manager CLI 套件、用户级 desktop integration / strict `tutti://projects` bridge、带 `service status / stop / restart`、卸载前 `shutdown`、并发启动锁、版本替换、strict terminal / desktop browser context、idle / package update cleanup、全机readiness、exact npm global install、跨版本worker / recovery与私有日志的机器级 Local Console、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 project 的空群聊会由 collaboration-state 幂等写入一条 Tutti 欢迎消息；它不经过 browser message command，不触发 `@tutti`、Chat read-state、Scratchpad 或 Timeline / execution 流程。
 - Host server 与 Local Console 支持在显式 `webStatic.root` 或 packaged `web/` 存在时服务 Web 静态产物；`/api/*`、SSE、health、host-local control 和 `/local-console/*` API 不被 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` 与测试产物。

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

@@ -28,6 +28,10 @@ export type CliCommand = {
 } | {
     kind: "internal-desktop-open";
     url?: string;
+} | {
+    kind: "internal-package-update-worker";
+} | {
+    kind: "internal-package-update-complete";
 } | {
     kind: "ps";
     manage: boolean;

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

@@ -138,6 +138,17 @@ export function parseCliArgs(argv, cwd = process.cwd()) {
     }
     if (command === "internal") {
         const internalCommand = args.shift();
+        if (internalCommand === "package-update-worker" ||
+            internalCommand === "package-update-complete") {
+            if (args.length > 0) {
+                throw new LaunchError("git_bootstrap_failed", `Internal ${internalCommand} does not accept options`, "Internal commands are managed by Tutti.");
+            }
+            return {
+                kind: internalCommand === "package-update-worker"
+                    ? "internal-package-update-worker"
+                    : "internal-package-update-complete",
+            };
+        }
         if (internalCommand === "console-run") {
             if (args.length > 0) {
                 throw new LaunchError("git_bootstrap_failed", "Internal console-run does not accept options", "Internal commands are managed by Tutti.");

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { dirname, resolve } from "node:path";
+import { resolveTuttiHome } from "../../providers/openai/index.js";
 import { formatCliError, formatCliErrorReason, LaunchError } from "./errors.js";
 import { parseCliArgs, shouldEnsureDesktopIntegrationAutomatically } from "./args.js";
 import { confirmTextFromTty, runBackgroundLaunchCommand, runForegroundLaunchCommand, runInternalHostRunCommand, } from "./launch-command.js";
@@ -9,6 +10,8 @@ import { runArchiveCommand, runDoctorCommand, runForgetCommand, runInviteCommand
 import { readCliVersion } from "./version.js";
 import { ensureDesktopIntegrationAutomatically, parseTuttiDesktopUrl, runDesktopIntegrationCommand, TUTTI_DESKTOP_PROJECTS_URL, TuttiDesktopProtocolError, } from "../desktop-integration/index.js";
 import { ensureLocalConsole, openLocalConsoleBrowser, readLocalConsoleServiceStatus, restartLocalConsoleService, runLocalConsoleProcess, stopLocalConsoleService, } from "../local-console/index.js";
+import { runPackageUpdateCompletionProtocol, runPackageUpdateWorkerProtocol, } from "../local-console/package-update-process.js";
+import { recoverPackageUpdateForConsoleStartup } from "../local-console/package-update-recovery.js";
 const HELP_TEXT = `Usage:
   tutti
   tutti launch [target] [--yes] [--foreground]
@@ -209,13 +212,30 @@ function ensureDesktopIntegrationForConsole() {
         process.stderr.write("Tutti could not update its desktop entry. Run `tutti desktop` for details.\n");
     }
 }
+async function ensureUserLocalConsole(options) {
+    const env = process.env;
+    const entrypointArgument = process.argv[1];
+    if (entrypointArgument !== undefined && entrypointArgument.trim() !== "") {
+        const recovery = await recoverPackageUpdateForConsoleStartup({
+            tuttiHome: resolveTuttiHome(env.TUTTI_HOME, options.cwd),
+            cliEntrypoint: resolve(entrypointArgument),
+            cwd: options.cwd,
+            env,
+            source: options.source,
+        });
+        if (recovery.status === "completed") {
+            return recovery.url;
+        }
+    }
+    return (await ensureLocalConsole({ cwd: options.cwd, env, source: options.source })).url;
+}
 async function runLocalConsoleCommand() {
-    const console = await ensureLocalConsole();
-    if (openLocalConsoleBrowser(console.url)) {
-        process.stdout.write(`Tutti is ready at ${console.endpoint.base_url}/console\n`);
+    const url = await ensureUserLocalConsole({ cwd: process.cwd(), source: "terminal" });
+    if (openLocalConsoleBrowser(url)) {
+        process.stdout.write(`Tutti is ready at ${new URL(url).origin}/console\n`);
         return;
     }
-    process.stdout.write(["Open Tutti in a browser:", console.url, ""].join("\n"));
+    process.stdout.write(["Open Tutti in a browser:", url, ""].join("\n"));
 }
 function desktopResultMessage(result) {
     if (result.status === "installed") {
@@ -239,9 +259,9 @@ function runDesktopCommand(action) {
     return desktopResultMessage(runDesktopIntegrationCommand(action));
 }
 async function runDesktopOpenCommand(value) {
-    const url = value ?? TUTTI_DESKTOP_PROJECTS_URL;
+    const desktopUrl = value ?? TUTTI_DESKTOP_PROJECTS_URL;
     try {
-        parseTuttiDesktopUrl(url);
+        parseTuttiDesktopUrl(desktopUrl);
     }
     catch (error) {
         if (error instanceof TuttiDesktopProtocolError) {
@@ -250,11 +270,9 @@ async function runDesktopOpenCommand(value) {
         throw error;
     }
     const cliEntrypoint = process.argv[1];
-    const console = await ensureLocalConsole({
-        source: "desktop",
-        ...(cliEntrypoint === undefined ? {} : { cwd: dirname(resolve(cliEntrypoint)) }),
-    });
-    if (!openLocalConsoleBrowser(console.url)) {
+    const cwd = cliEntrypoint === undefined ? process.cwd() : dirname(resolve(cliEntrypoint));
+    const url = await ensureUserLocalConsole({ source: "desktop", cwd });
+    if (!openLocalConsoleBrowser(url)) {
         throw new LaunchError("desktop_open_failed", "The Local Console started, but no desktop browser opener is available.", "Run `tutti` from a terminal to print a one-time browser URL.");
     }
 }
@@ -378,6 +396,12 @@ try {
         case "internal-desktop-open":
             await runDesktopOpenCommand(command.url);
             break;
+        case "internal-package-update-worker":
+            await runPackageUpdateWorkerProtocol();
+            break;
+        case "internal-package-update-complete":
+            await runPackageUpdateCompletionProtocol();
+            break;
         case "ps":
             if (command.manage) {
                 await runPsManageCommand({ all: command.all });

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

@@ -1,4 +1,5 @@
 import type { FastifyInstance } from "fastify";
+import type { ExecutionStatusProjection } from "@tutti/shared/schemas/api";
 import { type HostProjectStore } from "../../store/index.js";
 import type { createHostServer } from "../http/create-server.js";
 import type { HostLocalLaunchStatus } from "../http/routes/local-control.js";
@@ -8,6 +9,7 @@ import type { HostRelayConnectionManager } from "./host-relay-connection-manager
 import type { LaunchPreparationResult } from "./launch.js";
 import { type MachineRuntimeEndpointRecord } from "./machine-local.js";
 export declare const HOST_SERVER_VERSION: string;
+export declare function packageUpdateReadinessFromExecutionStatus(execution: Pick<ExecutionStatusProjection, "status" | "active_activity" | "active_activities" | "blocked_by">): "ready" | "busy";
 export type HostServerFactory = typeof createHostServer;
 export type HostServerHandle = {
     app: FastifyInstance;

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

@@ -23,6 +23,15 @@ import { relayStateFromLaunchStatus } from "./host-relay-status.js";
 import { appendHostLogLine, readHostRegistrationSecret, createMachineRuntimeEndpointToken, deleteMachineRuntimeEndpoint, ensureHostLogFile, getHostLogFilePath, updateMachineProjectDisplayNameSnapshot, writeMachineRuntimeEndpoint, } from "./machine-local.js";
 import { readProjectDescription, readProjectDisplayName, writeProjectDescription, writeProjectDisplayName, } from "./project-identity.js";
 export const HOST_SERVER_VERSION = readCliVersion();
+export function packageUpdateReadinessFromExecutionStatus(execution) {
+    const active = execution.active_activity !== undefined || (execution.active_activities?.length ?? 0) > 0;
+    return active ||
+        execution.blocked_by !== undefined ||
+        execution.status === "running" ||
+        execution.status === "pending"
+        ? "busy"
+        : "ready";
+}
 function createHostRuntimeLogger(options) {
     return {
         info(fields, message) {
@@ -279,13 +288,11 @@ export async function startForegroundHostServer(options) {
     });
     let close = async () => { };
     let relayConnectionManager;
+    const packageUpdateReadiness = () => packageUpdateReadinessFromExecutionStatus(controlPlane.getExecutionStatus());
     const localControl = {
         token,
-        requestIdleShutdown: () => {
-            const execution = controlPlane.getExecutionStatus();
-            const hasActiveActivities = execution.active_activity !== undefined || (execution.active_activities?.length ?? 0) > 0;
-            return hasActiveActivities ? "busy" : "accepted";
-        },
+        getPackageUpdateReadiness: packageUpdateReadiness,
+        requestIdleShutdown: () => packageUpdateReadiness() === "ready" ? "accepted" : "busy",
         requestShutdown: () => {
             void close();
         },

package/dist/server-shell/cli/local-control-client.d.ts

@@ -1,4 +1,4 @@
-import type { HostLocalIdleShutdownDisposition, HostLocalLaunchStatus, HostLocalProjectProjection, HostLocalProviderConfigBody } from "../http/routes/local-control.js";
+import type { HostLocalIdleShutdownDisposition, HostLocalLaunchStatus, HostLocalPackageUpdateReadiness, HostLocalProjectProjection, HostLocalProviderConfigBody } from "../http/routes/local-control.js";
 import type { HostProviderConfigProjection } from "../http/routes/project-api/types.js";
 import type { MachineRuntimeEndpointRecord } from "./machine-local.js";
 export type LocalControlFetch = (input: string | URL, init?: RequestInit) => Promise<Response>;
@@ -6,6 +6,10 @@ export declare function readHostLocalLaunchStatus(options: {
     endpoint: MachineRuntimeEndpointRecord;
     fetchImpl?: LocalControlFetch;
 }): Promise<HostLocalLaunchStatus>;
+export declare function readHostLocalPackageUpdateReadiness(options: {
+    endpoint: MachineRuntimeEndpointRecord;
+    fetchImpl?: LocalControlFetch;
+}): Promise<HostLocalPackageUpdateReadiness>;
 export declare function rotateHostLocalInvite(options: {
     endpoint: MachineRuntimeEndpointRecord;
     fetchImpl?: LocalControlFetch;

package/dist/server-shell/cli/local-control-client.js

@@ -35,6 +35,25 @@ export async function readHostLocalLaunchStatus(options) {
         path: "/host-local/v1/launch-status",
     });
 }
+export async function readHostLocalPackageUpdateReadiness(options) {
+    const response = await fetchWithTimeout(options.fetchImpl ?? fetch, new URL("/host-local/v1/package-update-readiness", options.endpoint.base_url), {
+        headers: {
+            accept: "application/json",
+            authorization: `Bearer ${options.endpoint.token}`,
+        },
+    });
+    if (response.status === 404) {
+        return "unsupported";
+    }
+    if (!response.ok) {
+        throw new Error(`host-local package-update-readiness returned HTTP ${response.status}`);
+    }
+    const body = (await response.json());
+    if (body.status !== "ready" && body.status !== "busy" && body.status !== "unsupported") {
+        throw new Error("host-local package-update-readiness returned an invalid response");
+    }
+    return body.status;
+}
 export async function rotateHostLocalInvite(options) {
     return await requestLocalJson({
         ...options,

package/dist/server-shell/desktop-integration/manager.d.ts

@@ -1,3 +1,4 @@
+import { type SyncPackageCommandRunner } from "../package-installation/index.js";
 import { type DesktopCommandRunner, type DesktopInstallationIdentity, type DesktopPlatformAdapter } from "./platform.js";
 export type DesktopIntegrationResult = {
     status: "installed";
@@ -32,6 +33,7 @@ declare function createRealContext(options: {
     platform?: NodeJS.Platform;
     now?: () => Date;
     runner?: DesktopCommandRunner;
+    packageRunner?: SyncPackageCommandRunner;
     requireStableGlobal?: boolean;
 }): ManagerContext | DesktopIntegrationResult;
 export declare function ensureDesktopIntegrationAutomatically(options?: Parameters<typeof createRealContext>[0]): DesktopIntegrationResult;

package/dist/server-shell/desktop-integration/manager.js

@@ -1,14 +1,13 @@
-import { existsSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { dirname, isAbsolute, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveTuttiHome } from "../../providers/openai/index.js";
 import { readCliPackageIdentity } from "../cli/version.js";
-import { createLinuxDesktopAdapter, findDesktopExecutable, linuxDesktopRequirementsAvailable, } from "./linux.js";
+import { resolveGlobalPackageInstallation, } from "../package-installation/index.js";
+import { createLinuxDesktopAdapter, linuxDesktopRequirementsAvailable } from "./linux.js";
 import { createMacosDesktopAdapter, macosDesktopRequirementsAvailable } from "./macos.js";
 import { runDesktopCommand, } from "./platform.js";
 import { readDesktopIntegrationRecord, writeDesktopIntegrationRecord, } from "./record.js";
-const PUBLISHED_CLI_PACKAGE_NAME = "@xfey/tutti";
 function desktopAssetRoot() {
     return resolve(dirname(fileURLToPath(import.meta.url)), "../../../desktop-assets");
 }
@@ -136,39 +135,28 @@ export function removeDesktopIntegration(context) {
         return unavailable("operation_failed", "Tutti could not remove the user-level desktop entry.", context.adapter.entryPath);
     }
 }
-function stableGlobalPackage(options) {
-    const npmExecutable = findDesktopExecutable("npm", options.env);
-    if (npmExecutable === null) {
-        return false;
-    }
-    const result = options.runner(npmExecutable, ["root", "--global"]);
-    const globalRoot = result.stdout.trim();
-    if (result.status !== 0 || !isAbsolute(globalRoot)) {
-        return false;
-    }
-    const expectedRoot = join(globalRoot, ...PUBLISHED_CLI_PACKAGE_NAME.split("/"));
-    if (!existsSync(expectedRoot)) {
-        return false;
-    }
-    try {
-        return realpathSync(expectedRoot) === realpathSync(options.packageRoot);
-    }
-    catch {
-        return false;
-    }
-}
 function createRealContext(options) {
     const cwd = resolve(options.cwd ?? process.cwd());
     const env = options.env ?? process.env;
     const platform = options.platform ?? process.platform;
     const runner = options.runner ?? runDesktopCommand;
     const packageIdentity = readCliPackageIdentity();
-    if (packageIdentity.name !== PUBLISHED_CLI_PACKAGE_NAME ||
-        (options.requireStableGlobal !== false &&
-            !stableGlobalPackage({ packageRoot: packageIdentity.root, env, runner }))) {
-        return unavailable("package_not_global", "Desktop integration requires a stable global @xfey/tutti installation.");
+    const tuttiHome = resolveTuttiHome(env.TUTTI_HOME, cwd);
+    if (options.requireStableGlobal !== false) {
+        const packageInstallation = resolveGlobalPackageInstallation({
+            packageIdentity,
+            tuttiHome,
+            defaultTuttiHome: resolveTuttiHome(undefined, cwd),
+            env,
+            ...(options.packageRunner === undefined ? {} : { runner: options.packageRunner }),
+        });
+        if (packageInstallation.status === "unavailable") {
+            return packageInstallation.reasonCode === "custom_home"
+                ? unavailable("custom_tutti_home", "Desktop integration is available only for the default Tutti home.")
+                : unavailable("package_not_global", "Desktop integration requires a stable global @xfey/tutti installation.");
+        }
     }
-    if (env.TUTTI_HOME !== undefined && env.TUTTI_HOME.trim() !== "") {
+    else if (tuttiHome !== resolveTuttiHome(undefined, cwd)) {
         return unavailable("custom_tutti_home", "Desktop integration is available only for the default Tutti home.");
     }
     if (platform !== "darwin" && platform !== "linux") {
@@ -188,7 +176,7 @@ function createRealContext(options) {
         ? createMacosDesktopAdapter({ homeDir, assetRoot, runner })
         : createLinuxDesktopAdapter({ homeDir, assetRoot, env, runner });
     return {
-        tuttiHome: resolveTuttiHome(undefined, cwd),
+        tuttiHome,
         adapter,
         identity: {
             packageVersion: packageIdentity.version,

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

@@ -14,10 +14,12 @@ export type HostLocalControlOptions = {
         get: () => ProviderConfigProjection;
         configure: (input: HostLocalProviderConfigBody) => Promise<ProviderConfigProjection>;
     };
+    getPackageUpdateReadiness?: () => HostLocalPackageUpdateReadiness;
     requestIdleShutdown?: () => HostLocalIdleShutdownDisposition;
     requestShutdown: () => void;
 };
 export type HostLocalIdleShutdownDisposition = "accepted" | "busy" | "unsupported";
+export type HostLocalPackageUpdateReadiness = "ready" | "busy" | "unsupported";
 export type HostLocalLaunchStatus = {
     project_id?: ProjectId;
     relay_connection?: {

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

@@ -55,6 +55,14 @@ const HostLocalIdleShutdownResponseSchema = {
         disposition: { type: "string", enum: ["accepted", "busy", "unsupported"] },
     },
 };
+const HostLocalPackageUpdateReadinessResponseSchema = {
+    type: "object",
+    required: ["status"],
+    additionalProperties: false,
+    properties: {
+        status: { type: "string", enum: ["ready", "busy", "unsupported"] },
+    },
+};
 const HostLocalProviderConfigBodySchema = {
     type: "object",
     required: ["api_key"],
@@ -252,6 +260,12 @@ export function registerHostLocalControlRoutes(app, options) {
             throw new HostLocalControlUnauthorizedError();
         }
     }
+    function packageUpdateReadiness() {
+        if (draining || activeMutations > 0) {
+            return "busy";
+        }
+        return options.getPackageUpdateReadiness?.() ?? "unsupported";
+    }
     app.get("/host-local/v1/launch-status", {
         schema: {
             response: {
@@ -262,6 +276,16 @@ export function registerHostLocalControlRoutes(app, options) {
         requireLocalToken(request.headers.authorization);
         return options.getLaunchStatus?.() ?? {};
     });
+    app.get("/host-local/v1/package-update-readiness", {
+        schema: {
+            response: {
+                200: HostLocalPackageUpdateReadinessResponseSchema,
+            },
+        },
+    }, (request) => {
+        requireLocalToken(request.headers.authorization);
+        return { status: packageUpdateReadiness() };
+    });
     app.post("/host-local/v1/relay/reconnect", {
         schema: {
             response: {

package/dist/server-shell/local-console/invocation-context.js

@@ -37,7 +37,16 @@ export function createDesktopLocalConsoleInvocationContext(options) {
 }
 export function createLocalConsoleServiceEnvironment(options) {
     const environment = { TUTTI_HOME: options.tuttiHome };
-    for (const key of ["HOME", "LANG", "LC_ALL", "LC_CTYPE", "LOGNAME", "TMPDIR", "USER"]) {
+    for (const key of [
+        "HOME",
+        "LANG",
+        "LC_ALL",
+        "LC_CTYPE",
+        "LOGNAME",
+        "PATH",
+        "TMPDIR",
+        "USER",
+    ]) {
         const value = options.env[key];
         if (value !== undefined && value !== "") {
             environment[key] = value;

package/dist/server-shell/local-console/operation-coordinator.d.ts

@@ -0,0 +1,16 @@
+export declare class LocalConsoleOperationConflictError extends Error {
+    readonly statusCode = 409;
+    readonly code = "package_update_in_progress";
+    constructor();
+}
+export type LocalConsolePackageUpdateOperationLease = {
+    release: () => void;
+};
+export type LocalConsoleOperationState = "idle" | "project_busy" | "package_update";
+export declare class LocalConsoleOperationCoordinator {
+    #private;
+    state(): LocalConsoleOperationState;
+    runProjectOperation<T>(operation: () => Promise<T>): Promise<T>;
+    tryBeginPackageUpdate(): LocalConsolePackageUpdateOperationLease | null;
+}
+//# sourceMappingURL=operation-coordinator.d.ts.map

package/dist/server-shell/local-console/operation-coordinator.js

@@ -0,0 +1,50 @@
+export class LocalConsoleOperationConflictError extends Error {
+    statusCode = 409;
+    code = "package_update_in_progress";
+    constructor() {
+        super("Tutti is restarting to install an update.");
+        this.name = "LocalConsoleOperationConflictError";
+    }
+}
+export class LocalConsoleOperationCoordinator {
+    #operationTail = Promise.resolve();
+    #pendingOperations = 0;
+    #packageUpdateOwner;
+    state() {
+        if (this.#packageUpdateOwner !== undefined) {
+            return "package_update";
+        }
+        return this.#pendingOperations > 0 ? "project_busy" : "idle";
+    }
+    runProjectOperation(operation) {
+        if (this.#packageUpdateOwner !== undefined) {
+            return Promise.reject(new LocalConsoleOperationConflictError());
+        }
+        this.#pendingOperations += 1;
+        const result = this.#operationTail.then(operation, operation);
+        this.#operationTail = result.then(() => undefined, () => undefined);
+        return result.finally(() => {
+            this.#pendingOperations = Math.max(0, this.#pendingOperations - 1);
+        });
+    }
+    tryBeginPackageUpdate() {
+        if (this.#packageUpdateOwner !== undefined || this.#pendingOperations > 0) {
+            return null;
+        }
+        const owner = Symbol("localConsolePackageUpdate");
+        this.#packageUpdateOwner = owner;
+        let released = false;
+        return {
+            release: () => {
+                if (released) {
+                    return;
+                }
+                released = true;
+                if (this.#packageUpdateOwner === owner) {
+                    this.#packageUpdateOwner = undefined;
+                }
+            },
+        };
+    }
+}
+//# sourceMappingURL=operation-coordinator.js.map

package/dist/server-shell/local-console/package-update-completion.d.ts

@@ -0,0 +1,25 @@
+import { PackageUpdateLogger } from "./package-update-log.js";
+import { type PackageUpdateRuntimeRecord } from "./package-update-record.js";
+export type PackageUpdateCompletionResult = {
+    status: "completed";
+    restart_failure_count: number;
+    browser_opened: boolean;
+};
+export declare function runPackageUpdateCompletion(options: {
+    tuttiHome: string;
+    cliEntrypoint: string;
+    env: NodeJS.ProcessEnv;
+    currentVersion?: string;
+    logger?: Pick<PackageUpdateLogger, "append">;
+    restoreHosts?: (record: PackageUpdateRuntimeRecord) => Promise<{
+        restored_project_ids: string[];
+        failed_project_ids: string[];
+    }>;
+    ensureConsole?: () => Promise<{
+        url: string;
+    }>;
+    openBrowser?: (url: string) => boolean;
+    releaseLock?: () => boolean;
+    now?: () => Date;
+}): Promise<PackageUpdateCompletionResult>;
+//# sourceMappingURL=package-update-completion.d.ts.map

package/dist/server-shell/local-console/package-update-completion.js

@@ -0,0 +1,91 @@
+import { dirname } from "node:path";
+import { readCliVersion } from "../cli/version.js";
+import { ensureLocalConsole } from "./managed-console.js";
+import { openLocalConsoleBrowser } from "./browser-open.js";
+import { releasePackageUpdateLockForCurrentProcess } from "./package-update-lock.js";
+import { PackageUpdateLogger } from "./package-update-log.js";
+import { readPackageUpdateRuntimeRecord, updatePackageUpdateRuntimeRecord, } from "./package-update-record.js";
+import { restorePackageUpdateHosts } from "./package-update-hosts.js";
+export async function runPackageUpdateCompletion(options) {
+    const currentVersion = options.currentVersion ?? readCliVersion();
+    const read = readPackageUpdateRuntimeRecord({ tuttiHome: options.tuttiHome });
+    if (read.status !== "valid" ||
+        read.record.phase !== "restarting" ||
+        read.record.target_version !== currentVersion ||
+        read.record.updater_pid !== process.pid) {
+        throw new Error("Package update completion record is unavailable or does not match this CLI.");
+    }
+    const logger = options.logger ??
+        new PackageUpdateLogger({
+            tuttiHome: options.tuttiHome,
+            privatePaths: [options.tuttiHome],
+            ...(options.now === undefined ? {} : { now: options.now }),
+        });
+    const releaseLock = options.releaseLock ?? (() => releasePackageUpdateLockForCurrentProcess(options.tuttiHome));
+    const log = (entry) => {
+        try {
+            logger.append(entry);
+        }
+        catch {
+            // Completion correctness must not depend on the diagnostic log remaining writable.
+        }
+    };
+    try {
+        const restored = await (options.restoreHosts ??
+            ((record) => restorePackageUpdateHosts({
+                tuttiHome: options.tuttiHome,
+                projectIds: record.restore_project_ids,
+                env: options.env,
+            })))(read.record);
+        updatePackageUpdateRuntimeRecord({
+            tuttiHome: options.tuttiHome,
+            current: read.record,
+            phase: "restarting",
+            updaterPid: process.pid,
+            restartFailureCount: restored.failed_project_ids.length,
+            ...(options.now === undefined ? {} : { now: options.now }),
+        });
+        const consoleResult = await (options.ensureConsole ??
+            (() => ensureLocalConsole({
+                cwd: dirname(options.cliEntrypoint),
+                env: options.env,
+                source: "desktop",
+            })))();
+        if (!releaseLock()) {
+            throw new Error("Package update completion could not release its machine lock.");
+        }
+        const browserOpened = (options.openBrowser ?? openLocalConsoleBrowser)(consoleResult.url);
+        log({
+            level: restored.failed_project_ids.length === 0 ? "info" : "warn",
+            message: restored.failed_project_ids.length === 0
+                ? "Package update completed."
+                : "Package update completed with Host restore failures.",
+            phase: "restarting",
+            ...(restored.failed_project_ids.length === 0 ? {} : { reasonCode: "host_restore_failed" }),
+        });
+        return {
+            status: "completed",
+            restart_failure_count: restored.failed_project_ids.length,
+            browser_opened: browserOpened,
+        };
+    }
+    catch (error) {
+        updatePackageUpdateRuntimeRecord({
+            tuttiHome: options.tuttiHome,
+            current: read.record,
+            phase: "failed",
+            updaterPid: process.pid,
+            failureReasonCode: "completion_failed",
+            ...(options.now === undefined ? {} : { now: options.now }),
+        });
+        releaseLock();
+        log({
+            level: "error",
+            message: "Package update completion failed.",
+            phase: "failed",
+            reasonCode: "completion_failed",
+        });
+        throw error;
+    }
+}
+//# sourceMappingURL=package-update-completion.js.map

package/dist/server-shell/local-console/package-update-hosts.d.ts

@@ -0,0 +1,17 @@
+import type { ProjectId } from "@tutti/shared/ids";
+export type PackageUpdateHostStopResult = "stopped" | "host_busy" | "host_identity_unverified" | "host_update_unsupported";
+export declare function stopPackageUpdateHost(options: {
+    tuttiHome: string;
+    projectId: ProjectId;
+    fetchImpl?: typeof fetch;
+}): Promise<PackageUpdateHostStopResult>;
+export declare function restorePackageUpdateHosts(options: {
+    tuttiHome: string;
+    projectIds: readonly ProjectId[];
+    env: NodeJS.ProcessEnv;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    restored_project_ids: ProjectId[];
+    failed_project_ids: ProjectId[];
+}>;
+//# sourceMappingURL=package-update-hosts.d.ts.map