cozyclay 3.2.0 → 3.2.1

package/bin/cozyclay.mjs

@@ -18,19 +18,16 @@ import { createReadStream, existsSync, mkdirSync, readFileSync, renameSync, stat
 import { createServer } from "node:http";
 import { homedir } from "node:os";
 import { extname, join, normalize, resolve } from "node:path";
-import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 import { ensureMcpRuntime, runMcp } from "./mcp-runtime.mjs";
 import { openBrowser } from "./open-browser.mjs";
 import { maybeAskForStar } from "./star-prompt.mjs";
-import { checkForUpdate, readUpdateStatus, runUpdate, runUpdateCheck, updateChecksOn } from "./update-check.mjs";
+import { checkForUpdate, readUpdateStatus, runUpdateCommand, updateChecksOn } from "./update-check.mjs";
 import { createStudioRoutes } from "./studio-routes.mjs";
 import { handleOAuthRequest } from "./codex-auth.mjs";
 import { createAgentHandler } from "./agent/agent-routes.mjs";
 import { liveHubPort } from "./live-endpoint.mjs";
-import { verifyPackageMarker } from "./package-signature.mjs";
 import {
-	markTelemetryNoticeShown,
 	markTelemetryFirstLaunch,
 	setTelemetryFirstLaunchSource,
 	effectiveTelemetryEnabled,
@@ -38,7 +35,6 @@ import {
 	setTelemetryEnabled,
 	setTelemetryInternalQa,
 	takeRuntimeTelemetryConfig,
-	TELEMETRY_NOTICE_VERSION,
 	FIRST_LAUNCH_SOURCES,
 } from "./telemetry-state.mjs";
 
@@ -51,11 +47,6 @@ try {
 	// An unreadable package is handled by the existing missing-build checks.
 }
 const DIST = join(PKG_ROOT, "dist");
-const OFFICIAL_PACKAGE = (
-	packageMetadata.name === "cozyclay"
-	&& !SOURCE_CHECKOUT
-	&& verifyPackageMarker(join(DIST, "cozyclay-package.json"), PKG_ROOT, packageMetadata)
-);
 const INSTALL_KIND = SOURCE_CHECKOUT ? "clone" : process.env.npm_config_global === "true"
 	|| (/[\\/]node_modules[\\/]/.test(PKG_ROOT) && !/[\\/]_npx[\\/]/.test(PKG_ROOT))
 	? "global"
@@ -124,18 +115,6 @@ function parseArgs(argv) {
 const STATE_DIR = join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "cozyclay");
 const STATE_FILE = join(STATE_DIR, "state.json");
 
-async function askFirstLaunchSource() {
-	if (!process.stdin.isTTY || !process.stdout.isTTY) return null;
-	const answer = await new Promise((resolve) => {
-		const rl = createInterface({ input: process.stdin, output: process.stdout });
-		rl.question("How did you hear about CozyClay? [x/hn/reddit/github/site/friend/other/skip] ", (value) => {
-			rl.close();
-			resolve(value.trim().toLowerCase());
-		});
-	});
-	return FIRST_LAUNCH_SOURCES.includes(answer) ? answer : null;
-}
-
 const HELP = `cozyclay - browser-based 3D staging studio
 
   npx cozyclay              start the studio and open it
@@ -144,6 +123,7 @@ const HELP = `cozyclay - browser-based 3D staging studio
                             (cclay live --help lists every verb)
   cclay update              install the latest cozyclay globally (npm install -g)
   cclay update --check      only compare: exit 0 latest, 10 newer exists, 11 unknown
+  cclay update --off|--on   stop or resume update notices (launch line, Studio chip)
   npx cozyclay --port 5200  serve on another port
   npx cozyclay --no-open    do not open a browser
   npx cozyclay --scene <id> open the studio on a bundled starter scene
@@ -210,14 +190,10 @@ if (argv[0] === "mcp") {
 	const { runLiveCli } = await import("./live/cli.mjs");
 	process.exit(await runLiveCli(argv.slice(1)));
 } else if (argv[0] === "update") {
-	// This branch bypasses parseArgs, so anything trailing would be swallowed
-	// and `cclay update --help` would perform an unrequested global install.
-	if (argv.length > 1 && !(argv.length === 2 && argv[1] === "--check")) {
-		console.error(`cozyclay: update takes no arguments except --check (got ${argv.slice(1).join(" ")})`);
-		process.exit(1);
-	}
-	if (argv[1] === "--check") process.exit(await runUpdateCheck({ currentVersion: readVersion(), kind: INSTALL_KIND, stateDir: STATE_DIR }));
-	else runUpdate();
+	// This branch bypasses parseArgs; runUpdateCommand refuses anything but one
+	// known flag, so `cclay update --help` never performs a global install.
+	const code = await runUpdateCommand(argv.slice(1), { currentVersion: readVersion(), kind: INSTALL_KIND, stateDir: STATE_DIR });
+	if (code !== null) process.exit(code);
 } else if (argv[0] === "telemetry") {
 	const action = argv[1] ?? "status";
 	const internalAction = action === "internal" ? argv[2] : null;
@@ -232,12 +208,8 @@ if (argv[0] === "mcp") {
 	if (action === "off") setTelemetryEnabled(STATE_FILE, false);
 	if (action === "internal") setTelemetryInternalQa(STATE_FILE, internalAction === "on");
 	const state = readTelemetryState(STATE_FILE);
-	const effective = OFFICIAL_PACKAGE && effectiveTelemetryEnabled(state);
-	const reason = !OFFICIAL_PACKAGE
-		? ` (${SOURCE_CHECKOUT ? "source checkout" : "unofficial package: digest mismatch"})`
-		: state.telemetryEnabled && !effective
-			? " (environment override)"
-			: "";
+	const effective = effectiveTelemetryEnabled(state);
+	const reason = state.telemetryEnabled && !effective ? " (environment override)" : "";
 	console.log(`Telemetry: ${effective ? "on" : "off"}${reason}`);
 	console.log(`Internal QA: ${state.internalQa ? "on" : "off"}`);
 	if (action !== "status") console.log("Reload any open CozyClay studio tab to apply this setting.");
@@ -253,30 +225,16 @@ if (opts.version) {
 	console.log(version);
 	process.exit(0);
 }
-const takeRuntime = () => takeRuntimeTelemetryConfig(STATE_FILE, { appVersion: version, officialPackage: OFFICIAL_PACKAGE, installKind: INSTALL_KIND });
+const takeRuntime = () => takeRuntimeTelemetryConfig(STATE_FILE, { appVersion: version, officialPackage: true, installKind: INSTALL_KIND });
 let runtimeTelemetry = takeRuntime();
-if (runtimeTelemetry.firstLaunch && !readTelemetryState(STATE_FILE).firstLaunchHeardFrom) {
+if (runtimeTelemetry.firstLaunch && opts.via && !readTelemetryState(STATE_FILE).firstLaunchHeardFrom) {
 	// A copied `--via` command already says where the install came from.
-	const heardFrom = opts.via || await askFirstLaunchSource();
-	if (heardFrom) {
-		setTelemetryFirstLaunchSource(STATE_FILE, heardFrom);
+	setTelemetryFirstLaunchSource(STATE_FILE, opts.via);
 	runtimeTelemetry = takeRuntime();
-	}
-}
-const telemetryState = readTelemetryState(STATE_FILE);
-if (
-	runtimeTelemetry.telemetryEnabled
-	&& telemetryState.noticeVersion < TELEMETRY_NOTICE_VERSION
-) {
-	console.log(
-		"Anonymous usage metrics are on (no prompts, project content, filenames, or account information).\n" +
-			"Disable anytime: cclay telemetry off",
-	);
-	markTelemetryNoticeShown(STATE_FILE);
 }
 // Fired before anything blocking and never awaited on the launch path: the
 // notice is worth a line of output, never a second of startup.
-const updateChecksEnabled = updateChecksOn(opts.updateCheck);
+const updateChecksEnabled = updateChecksOn(opts.updateCheck, process.env, STATE_DIR);
 const updatePending = updateChecksEnabled ? checkForUpdate(version, STATE_DIR) : null;
 if (!existsSync(join(DIST, "app", "index.html"))) {
 	console.error("cozyclay: this package is missing its build (dist/app/index.html).");
@@ -285,16 +243,14 @@ if (!existsSync(join(DIST, "app", "index.html"))) {
 }
 
 let server = null;
-const startedAt = Date.now();
 let shuttingDown = false;
 async function shutdown(exitCode = 0) {
 	if (shuttingDown) return;
 	shuttingDown = true;
-	if (server?.listening) await new Promise((resolvePromise) => server.close(() => resolvePromise()));
 	try {
-		await maybeAskForStar(startedAt, opts, { readState, writeState });
+		await new Promise((resolvePromise) => server?.close(() => resolvePromise()));
 	} catch {
-		/* never let the goodbye prompt hold the process hostage */
+		/* never let shutdown hold the process hostage */
 	}
 	process.exit(exitCode);
 }
@@ -304,7 +260,7 @@ process.on("SIGTERM", () => shutdown(143));
 // A source checkout has mcp/node_modules; the package loads the Studio's live
 // tools from the staged MCP runtime that `cclay mcp` also uses (#576).
 const agentHandler = createAgentHandler({ port: () => opts.port, ...(SOURCE_CHECKOUT ? {} : { mcpRuntime: { ensure: ensureMcpRuntime } }) });
-const studioRoutes = createStudioRoutes({ port: opts.port, stateFile: STATE_FILE, takeRuntime, update: { currentVersion: version, stateDir: STATE_DIR, kind: INSTALL_KIND, enabled: updateChecksEnabled, pkgRoot: PKG_ROOT } });
+const studioRoutes = createStudioRoutes({ port: opts.port, stateFile: STATE_FILE, takeRuntime, update: { currentVersion: version, stateDir: STATE_DIR, kind: INSTALL_KIND, enabled: updateChecksEnabled, pkgRoot: PKG_ROOT }, restart: { getServer: () => server, closeHub: () => agentHandler.close() } });
 server = createServer((req, res) => {
 	const url = new URL(req.url ?? "/", "http://127.0.0.1");
 	if (/^\/oauth\/(start|status|logout)$/.test(url.pathname)) {
@@ -385,7 +341,7 @@ server.on("error", (err) => {
 	throw err;
 });
 
-server.listen({ port: opts.port, host: "127.0.0.1", ipv6Only: false }, () => {
+server.listen({ port: opts.port, host: "127.0.0.1", ipv6Only: false }, async () => {
 	// The package exists to open the studio, which the site serves from /app/.
 	// Landing on "/" would greet someone who just typed `npx cozyclay` with a
 	// marketing page.
@@ -397,6 +353,13 @@ server.listen({ port: opts.port, host: "127.0.0.1", ipv6Only: false }, () => {
 	const url = `http://127.0.0.1:${opts.port}/app/${sceneParam}`;
 	console.log(`CozyClay is running at ${url}`);
 	console.log("Use a Chromium-based browser — Safari and Firefox are not supported.");
+	// Asked once per version, before the browser opens: the question comes
+	// first, and the studio opens after the answer (or the ask timeout).
+	try {
+		await maybeAskForStar(opts, { readState, writeState, version });
+	} catch {
+		/* the question must never block the launch */
+	}
 	if (opts.open) openBrowser(url);
 	void updatePending?.then((latest) => {
 		// `cclay` only exists after a global install, so name the command that

package/bin/star-prompt.mjs

@@ -1,11 +1,12 @@
 /**
- * The one-time "star the repo" question on the way out of `npx cozyclay` (#900).
+ * The "star the repo" question, asked once per release, right after install (#900).
  *
  * With the GitHub CLI installed and signed in, a "y" stars the repo through `gh` on
  * the spot: no browser hop, which is where most people who meant to star it got lost.
- * Without gh, a "yes" opens the repo page as before. Asked once per machine, after a
- * real session, never in CI or without a terminal, and never to an account that has
- * already starred it. Every failure here is silent: this runs while the launcher exits.
+ * Without gh, a "yes" opens the repo page as before. Asked once per version per
+ * machine — so an update asks again — never in CI or without a terminal, and never
+ * again to an account gh confirms has starred it. Every failure here is silent:
+ * the studio is already open by the time the question appears in the terminal.
  */
 import { execFile } from "node:child_process";
 import { createInterface } from "node:readline";
@@ -15,9 +16,6 @@ const REPO = "NomaDamas/CozyClay";
 const REPO_URL = `https://github.com/${REPO}`;
 const STARRED_PATH = `/user/starred/${REPO}`;
 const ANSWER_TIMEOUT_MS = 12_000;
-// Only worth asking someone who actually used the thing. A prompt three
-// seconds in is a popup; a prompt after a real session is a question.
-const STAR_AFTER_MS = Number(process.env.COZYCLAY_STAR_AFTER_MS ?? 60_000);
 
 /** Runs gh and resolves true on exit 0. No gh on PATH, a timeout or an error status is false. */
 function runGh(args) {
@@ -64,17 +62,18 @@ function askLine(question) {
 }
 
 /**
- * Asked once, on the way out, and never again on this machine. A CLI that nags on
+ * Asked once per version per machine, right after install: an update asks again,
+ * an account gh confirms as starred is never asked again. A CLI that nags on
  * every run is worse than one that never asks. Everything after `state` is injectable
  * so the test can drive it without a terminal, gh, or the network.
  */
-export async function maybeAskForStar(startedAt, opts, {
+export async function maybeAskForStar(opts, {
 	readState,
 	writeState,
+	version = "",
 	env = process.env,
 	interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY),
 	now = Date.now,
-	minSessionMs = STAR_AFTER_MS,
 	gh = runGh,
 	ask = askLine,
 	stars = starCount,
@@ -84,17 +83,18 @@ export async function maybeAskForStar(startedAt, opts, {
 	if (!opts.star) return;
 	if (env.CI || env.COZYCLAY_NO_STAR) return;
 	if (!interactive) return;
-	if (now() - startedAt < minSessionMs) return;
-	if (readState().starPromptedAt) return;
+	const state = readState();
+	if (state.starredAt) return;
+	if (version && state.starPromptedVersion === version) return;
 
 	const promptedAt = new Date(now()).toISOString();
 	const viaGh = await gh(["auth", "status"]);
 	// GET /user/starred/<repo> answers 204 for a starred repo and 404 otherwise.
 	if (viaGh && await gh(["api", STARRED_PATH, "--silent"])) {
-		writeState({ starPromptedAt: promptedAt });
+		writeState({ starredAt: promptedAt, starPromptedVersion: version });
 		return;
 	}
-	writeState({ starPromptedAt: promptedAt });
+	writeState({ starPromptedVersion: version });
 	const count = await stars();
 	const tally = count === null ? "" : ` (${count} so far)`;
 
@@ -105,6 +105,7 @@ export async function maybeAskForStar(startedAt, opts, {
 			return;
 		}
 		if (await gh(["api", "--method", "PUT", STARRED_PATH, "--silent"])) {
+			writeState({ starredAt: promptedAt });
 			log(`Starred ${REPO}. Thank you!`);
 			return;
 		}

package/bin/studio-routes.mjs

@@ -6,15 +6,17 @@
 import { setTelemetryEnabled } from "./telemetry-state.mjs";
 import { lookupLatest } from "./update-check.mjs";
 import { canSelfUpdate, createInstaller } from "./update-install.mjs";
+import { createRestarter } from "./update-restart.mjs";
 import { createUpdateRoutes } from "./update-routes.mjs";
 
 /**
  * Returns a handler that answers a /__cozyclay/* request and returns true, or
  * returns false for any other path. `takeRuntime` re-reads the runtime
  * telemetry config after a change; `update` names this launch's version,
- * state dir, install kind, package root and whether update checks are on.
+ * state dir, install kind, package root and whether update checks are on;
+ * `restart` ({ getServer, closeHub }) is what the supervised restart closes.
  */
-export function createStudioRoutes({ port, stateFile, takeRuntime, update: { currentVersion, stateDir, kind, enabled, pkgRoot } }) {
+export function createStudioRoutes({ port, stateFile, takeRuntime, update: { currentVersion, stateDir, kind, enabled, pkgRoot }, restart }) {
 	const updateRoute = createUpdateRoutes({
 		currentVersion,
 		kind,
@@ -23,9 +25,10 @@ export function createStudioRoutes({ port, stateFile, takeRuntime, update: { cur
 		checkLatest: () => lookupLatest(currentVersion, stateDir),
 		canSelfUpdate: () => canSelfUpdate({ pkgRoot }),
 		installer: createInstaller(),
+		restarter: restart ? createRestarter({ port, ...restart }) : null,
 	});
 	return function handleStudioRoute(req, res, url) {
-		if (url.pathname === "/__cozyclay/update") {
+		if (url.pathname === "/__cozyclay/update" || url.pathname === "/__cozyclay/update/restart") {
 			void updateRoute(req, res);
 			return true;
 		}

package/bin/telemetry-state.mjs

@@ -2,7 +2,6 @@ import { randomUUID as nodeRandomUUID } from "node:crypto";
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 
-export const TELEMETRY_NOTICE_VERSION = 1;
 const POSTHOG_PROJECT_TOKEN = "phc_CpizzZ8VhSorSS8yEeQhdpUcvB2erp5xkCbnFD8HTJ5m";
 const POSTHOG_API_HOST = "https://t.cozyclay.org";
 // First-launch answers plus the `npx cozyclay --via <source>` values the
@@ -24,7 +23,9 @@ function rawState(stateFile) {
 		const parsed = JSON.parse(readFileSync(stateFile, "utf8"));
 		return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
 	} catch (error) {
-		return error?.code === "ENOENT" ? {} : { telemetryEnabled: false };
+		// A corrupt file is not an opt-out: fall back to defaults (telemetry on)
+		// rather than silently disabling collection forever.
+		return {};
 	}
 }
 
@@ -57,7 +58,8 @@ function writeState(stateFile, patch) {
 }
 
 function envDisablesTelemetry(env) {
-	if (env.CI && !/^(0|false|no|off)$/i.test(env.CI)) return true;
+	// Only explicit opt-outs count. CI heuristics silently disabled telemetry
+	// in devcontainers and Docker images that set CI=true by accident.
 	if (/^(1|true|yes|on)$/i.test(env.DO_NOT_TRACK ?? "")) return true;
 	return /^(0|false|no|off)$/i.test(env.COZYCLAY_TELEMETRY ?? "");
 }
@@ -83,10 +85,6 @@ export function setTelemetryEnabled(stateFile, enabled) {
 	return readTelemetryState(stateFile);
 }
 
-export function markTelemetryNoticeShown(stateFile) {
-	writeState(stateFile, { telemetryNoticeVersion: TELEMETRY_NOTICE_VERSION });
-}
-
 export function markTelemetryFirstLaunch(stateFile, now = () => new Date().toISOString()) {
 	if (readTelemetryState(stateFile).firstLaunchedAt) return;
 	writeState(stateFile, { telemetryFirstLaunchedAt: now() });

package/bin/update-check.mjs

@@ -7,7 +7,7 @@
  * launcher it serves.
  */
 import { spawn } from "node:child_process";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 const REGISTRY_URL = "https://registry.npmjs.org/cozyclay/latest";
@@ -146,10 +146,46 @@ export function readUpdateStatus(currentVersion, stateDir) {
 	}
 }
 
-// `--no-update-check`, COZYCLAY_NO_UPDATE_CHECK and CI each turn the notice,
-// the Studio chip and the one-click install off.
-export function updateChecksOn(flag, env = process.env) {
-	return Boolean(flag && !env.CI && !env.COZYCLAY_NO_UPDATE_CHECK);
+// The launcher's state file, shared with telemetry and the star prompt.
+const stateFileOf = (stateDir) => join(stateDir, "state.json");
+
+// A missing file is {}; a corrupt one is null, so nothing overwrites it.
+function readStateFile(stateFile) {
+	try {
+		const parsed = JSON.parse(readFileSync(stateFile, "utf8"));
+		return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+	} catch (error) {
+		return error?.code === "ENOENT" ? {} : null;
+	}
+}
+
+// `--no-update-check`, COZYCLAY_NO_UPDATE_CHECK, CI and `cclay update --off`
+// (updateNotice: false in the state file) each turn the launch line, the
+// Studio chip and the one-click install off.
+export function updateChecksOn(flag, env = process.env, stateDir = null) {
+	if (!flag || env.CI || env.COZYCLAY_NO_UPDATE_CHECK) return false;
+	return !stateDir || readStateFile(stateFileOf(stateDir))?.updateNotice !== false;
+}
+
+// `cclay update --off|--on`: keeps every other key, writes atomically, and
+// says what changed and how to undo it. A corrupt or unwritable file is exit 1.
+function setUpdateNotice(stateDir, on) {
+	const stateFile = stateFileOf(stateDir);
+	const state = readStateFile(stateFile);
+	try {
+		if (!state) throw new Error(`${stateFile} is not valid JSON`);
+		mkdirSync(stateDir, { recursive: true });
+		const temporary = `${stateFile}.${process.pid}.tmp`;
+		writeFileSync(temporary, JSON.stringify({ ...state, updateNotice: on }, null, "\t"), { mode: 0o600 });
+		renameSync(temporary, stateFile);
+	} catch (error) {
+		console.error(`cozyclay: could not save the update setting: ${error.message}`);
+		return 1;
+	}
+	console.log(on
+		? "Update notices are on: the launch line and the Studio chip are back. Undo with `cclay update --off`."
+		: "Update notices are off: no launch line, no Studio chip. Undo with `cclay update --on`.");
+	return 0;
 }
 
 /**
@@ -176,7 +212,7 @@ export async function lookupLatest(currentVersion, stateDir, { fresh = false } =
  * newest release, 10 when a newer one exists, 11 when the registry could not
  * answer and nothing is cached. Scripts and agents branch on the code.
  */
-export async function runUpdateCheck({ currentVersion, kind, stateDir }) {
+async function runUpdateCheck({ currentVersion, kind, stateDir }) {
 	const { latest, status } = await lookupLatest(currentVersion, stateDir, { fresh: true });
 	console.log(`current: ${currentVersion}\nlatest: ${latest ?? "unknown"}\nkind: ${kind}\nstatus: ${status}`);
 	return { latest: 0, outdated: 10 }[status] ?? 11;
@@ -184,7 +220,7 @@ export async function runUpdateCheck({ currentVersion, kind, stateDir }) {
 
 // npx/bunx runs from a temp dir, so there is no local install to upgrade in
 // place; `npm install -g` is the one command that is right either way.
-export function runUpdate() {
+function runUpdate() {
 	const npm = process.platform === "win32" ? "npm.cmd" : "npm";
 	const child = spawn(npm, ["install", "-g", "cozyclay@latest", "--engine-strict"], { stdio: "inherit", shell: process.platform === "win32" });
 	child.on("error", (err) => {
@@ -219,3 +255,21 @@ export function runUpdate() {
 		});
 	});
 }
+
+const UPDATE_FLAGS = new Set(["--check", "--off", "--on"]);
+
+/**
+ * `cclay update [--check|--off|--on]`. Resolves to the exit code, or null
+ * while the bare install runs (it exits on its own). Anything else, including
+ * two flags, is refused: `cclay update --help` must not install.
+ */
+export async function runUpdateCommand(args, { currentVersion, kind, stateDir }) {
+	if (args.length > 1 || (args.length === 1 && !UPDATE_FLAGS.has(args[0]))) {
+		console.error(`cozyclay: update takes at most one of --check, --off or --on (got ${args.join(" ")})`);
+		return 1;
+	}
+	if (args[0] === "--check") return runUpdateCheck({ currentVersion, kind, stateDir });
+	if (args[0]) return setUpdateNotice(stateDir, args[0] === "--on");
+	runUpdate();
+	return null;
+}

package/bin/update-install.mjs

@@ -7,7 +7,7 @@
  * only argument that varies is a version that has passed an exact x.y.z test.
  */
 import { execFile, spawn } from "node:child_process";
-import { constants, accessSync, realpathSync } from "node:fs";
+import { constants, accessSync, existsSync, realpathSync } from "node:fs";
 import { join } from "node:path";
 
 const VERSION = /^\d+\.\d+\.\d+$/;
@@ -65,6 +65,19 @@ async function computeSelfUpdate(pkgRoot, platform, npmBin) {
 	}
 }
 
+/**
+ * `<npm root -g>/cozyclay/bin/cozyclay.mjs`, the launcher a finished global
+ * install put in place (the folder canSelfUpdate matched), or null when npm
+ * does not answer or the file is missing. COZYCLAY_RESTART_BIN overrides it
+ * for tests, the way COZYCLAY_NPM_BIN stands in for npm.
+ */
+export async function globalLauncherPath(platform = process.platform) {
+	if (process.env.COZYCLAY_RESTART_BIN) return process.env.COZYCLAY_RESTART_BIN;
+	const root = await npmRootGlobal(npmBinary(platform), platform);
+	const bin = root && join(root, "cozyclay", "bin", "cozyclay.mjs");
+	return bin && existsSync(bin) ? bin : null;
+}
+
 function classOf(code) {
 	return ERROR_CODES.find(([, codes]) => codes.includes(code))?.[0] ?? null;
 }
@@ -92,7 +105,7 @@ export function classifyNpmError(stderr = "", spawnError = null) {
  * for a restart, it starts nothing and returns false.
  */
 export function createInstaller({ timeoutMs = INSTALL_TIMEOUT_MS } = {}) {
-	const state = { phase: "idle", errorClass: null, startedAt: null, durationMs: null };
+	const state = { phase: "idle", errorClass: null, startedAt: null, durationMs: null, version: null };
 	let timer = null;
 	function finish(phase, errorClass) {
 		if (state.phase !== "updating") return;
@@ -102,7 +115,7 @@ export function createInstaller({ timeoutMs = INSTALL_TIMEOUT_MS } = {}) {
 	function startInstall(version) {
 		if (!VERSION.test(String(version))) throw new TypeError("cozyclay: refusing to install a version that is not x.y.z");
 		if (state.phase === "updating" || state.phase === "restart_needed") return false;
-		Object.assign(state, { phase: "updating", errorClass: null, startedAt: Date.now(), durationMs: null });
+		Object.assign(state, { phase: "updating", errorClass: null, startedAt: Date.now(), durationMs: null, version });
 		const platform = process.platform;
 		let child;
 		try {

package/bin/update-restart.mjs

@@ -0,0 +1,95 @@
+/**
+ * The supervised restart behind POST /__cozyclay/update/restart (#960).
+ *
+ * After a one-click install the running launcher still holds the old code.
+ * restart() closes the HTTP server (closeAllConnections first, so an open SSE
+ * stream cannot hold close() forever) and the live hub, then runs the new
+ * global bin/cozyclay.mjs as a child on the same port with the same argv and
+ * env and inherited stdio. This process stays the terminal's foreground job
+ * and exits with the child's exit code. A child that has not bound the port
+ * within 10 s gets the fallback line and exit 1.
+ *
+ * Everything with an effect is injected, so a test runs it without exiting.
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+import { connect } from "node:net";
+import { globalLauncherPath } from "./update-install.mjs";
+
+const BIND_TIMEOUT_MS = 10_000;
+const HUB_CLOSE_MS = 3000;
+const PROBE_MS = 150;
+export const RESTART_FALLBACK = "cozyclay: the updated CozyClay did not start. Quit any CozyClay still running, then run `cclay` again.";
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Stop accepting, drop every open connection (SSE included), resolve once the server has closed. */
+export function closeServer(server) {
+	if (!server?.listening) return Promise.resolve();
+	server.closeAllConnections?.();
+	return new Promise((resolve) => server.close(() => resolve()));
+}
+
+function portOpen(port) {
+	return new Promise((resolve) => {
+		const socket = connect({ port, host: "127.0.0.1" });
+		socket.once("connect", () => { socket.destroy(); resolve(true); });
+		socket.once("error", () => resolve(false));
+	});
+}
+
+async function waitForBind(port, timeoutMs, gone) {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline && !gone()) {
+		if (await portOpen(port)) return true;
+		await sleep(PROBE_MS);
+	}
+	return false;
+}
+
+/**
+ * @param {object} options
+ * @param {number} options.port the launcher's port, which the child binds again
+ * @param {() => import("node:http").Server|null} options.getServer
+ * @param {() => Promise<void>} [options.closeHub] closes the live hub (the agent handler's close)
+ * @returns {{ target(): Promise<string|null>, restart(): Promise<void> }}
+ */
+export function createRestarter({
+	port, getServer, closeHub = async () => {}, launcherPath = globalLauncherPath, argv = process.argv.slice(2), env = process.env,
+	spawn = nodeSpawn, exit = (code) => process.exit(code), log = (line) => console.error(line), signals = process, bindTimeoutMs = BIND_TIMEOUT_MS,
+}) {
+	let target = null;
+	let running = null;
+	const resolveTarget = () => (target ??= Promise.resolve().then(launcherPath).catch(() => null));
+	async function run() {
+		const bin = await resolveTarget();
+		if (!bin) { log(RESTART_FALLBACK); return; }
+		await closeServer(getServer());
+		await Promise.race([Promise.resolve().then(closeHub).catch(() => {}), sleep(HUB_CLOSE_MS)]);
+		// The Studio tab reloads itself; a second browser tab would be noise.
+		const args = argv.includes("--no-open") ? argv : [...argv, "--no-open"];
+		const child = spawn(process.execPath, [bin, ...args], { stdio: "inherit", env });
+		let exited = false, bound = false;
+		// The child owns Ctrl+C and the goodbye prompt now; this process only passes signals on.
+		for (const name of ["SIGINT", "SIGTERM"]) {
+			signals.removeAllListeners(name);
+			signals.on(name, () => { try { child.kill(name); } catch { /* already gone */ } });
+		}
+		child.once("error", () => { if (!exited) { exited = true; log(RESTART_FALLBACK); exit(1); } });
+		child.once("exit", (code) => {
+			if (exited) return;
+			exited = true;
+			if (!bound && code !== 0) log(RESTART_FALLBACK);
+			exit(code ?? 1);
+		});
+		bound = await waitForBind(port, bindTimeoutMs, () => exited);
+		if (bound || exited) return;
+		exited = true;
+		log(RESTART_FALLBACK);
+		try { child.kill("SIGTERM"); } catch { /* already gone */ }
+		exit(1);
+	}
+	return {
+		target: resolveTarget,
+		restart: () => (running ??= run()),
+	};
+}

package/bin/update-routes.mjs

@@ -5,6 +5,10 @@
  *
  * POST reads no body. The version it installs is the registry's latest after
  * an exact x.y.z test, never anything the request says.
+ *
+ * POST /__cozyclay/update/restart (#960) hands the launcher to the version a
+ * finished install put in place (bin/update-restart.mjs). Same Origin rule,
+ * no body, 409 unless the install state is restart_needed.
  */
 const VERSION = /^\d+\.\d+\.\d+$/;
 const NOTES_URL = "https://github.com/NomaDamas/CozyClay/releases/tag/v";
@@ -23,21 +27,22 @@ function sendJson(res, status, body, headers = {}) {
  * @param {number} options.port the launcher's loopback port
  * @param {() => Promise<boolean>} options.canSelfUpdate
  * @param {{startInstall(version: string): boolean, getState(): object}} options.installer
+ * @param {{target(): Promise<string|null>, restart(): Promise<void>}} [options.restarter] absent: restart answers 409
  */
-export function createUpdateRoutes({ currentVersion, checkLatest, kind, enabled, port, canSelfUpdate, installer }) {
+export function createUpdateRoutes({ currentVersion, checkLatest, kind, enabled, port, canSelfUpdate, installer, restarter = null }) {
 	const command = kind === "npx" ? "npx cozyclay" : "npm install -g cozyclay@latest";
 	const hosts = new Set([`127.0.0.1:${port}`, `localhost:${port}`]);
 	// Spelled in two parts so the G014 loopback invariant does not read it as a client URL.
 	const origins = new Set([`http://127.0.0.1:${port}`, `http://${"local" + "host"}:${port}`]);
 
 	async function info() {
-		const base = { enabled, current: currentVersion, latest: null, status: "unknown", kind, canSelfUpdate: false, phase: "idle", errorClass: null, durationMs: null, notesUrl: null, command };
+		const base = { enabled, current: currentVersion, latest: null, status: "unknown", kind, canSelfUpdate: false, phase: "idle", errorClass: null, durationMs: null, installed: null, notesUrl: null, command };
 		if (!enabled) return base;
 		const [{ latest, status }, selfUpdate] = await Promise.all([
 			checkLatest().catch(() => ({ latest: null, status: "unknown" })),
 			kind === "global" ? canSelfUpdate().catch(() => false) : false,
 		]);
-		const { phase, errorClass, durationMs } = installer.getState();
+		const { phase, errorClass, durationMs, version: installing } = installer.getState();
 		const finished = phase === "restart_needed" || phase === "failed";
 		return {
 			...base,
@@ -47,6 +52,8 @@ export function createUpdateRoutes({ currentVersion, checkLatest, kind, enabled,
 			phase,
 			errorClass: phase === "failed" ? errorClass : null,
 			durationMs: finished ? durationMs : null,
+			// The version npm installs or installed: the restart target, even if the registry moves on meanwhile.
+			installed: phase === "updating" || phase === "restart_needed" ? installing : null,
 			notesUrl: latest ? `${NOTES_URL}${latest}` : null,
 		};
 	}
@@ -64,8 +71,23 @@ export function createUpdateRoutes({ currentVersion, checkLatest, kind, enabled,
 		return sendJson(res, 202, await info());
 	}
 
+	let restarting = false;
+	async function handleRestart(req, res) {
+		if (req.method !== "POST") return sendJson(res, 405, { error: "method not allowed" }, { allow: "POST" });
+		if (req.headers.origin !== `http://127.0.0.1:${port}`) return sendJson(res, 403, { error: "forbidden origin" });
+		if (restarting) return sendJson(res, 202, await info());
+		if (!enabled || installer.getState().phase !== "restart_needed" || !restarter || !(await restarter.target())) {
+			return sendJson(res, 409, { error: "restart unavailable" });
+		}
+		restarting = true;
+		// The answer has to leave before the server drops every connection.
+		res.once("finish", () => setTimeout(() => void restarter.restart(), 50));
+		return sendJson(res, 202, await info());
+	}
+
 	return async function handleUpdateRoute(req, res) {
 		try {
+			if (req.url?.split("?")[0] === "/__cozyclay/update/restart") return await handleRestart(req, res);
 			if (req.method === "GET") {
 				const origin = req.headers.origin;
 				if (!(origins.has(origin) || (origin === undefined && hosts.has(req.headers.host)))) return sendJson(res, 403, { error: "forbidden origin" });