cozyclay 3.1.6 → 3.2.1

package/bin/agent/supervisor-followup.mjs

@@ -0,0 +1,34 @@
+// What the supervisor needs to judge a short answer such as "yes": the
+// exchange it answers. A hybrid project's capsule substitution is approved in
+// one turn ("Use capsule figures for this shot instead?") and carried out in
+// the next ("yes"), so the review of the second turn reads the first.
+import { transcriptFromHistory } from "./session-store.mjs";
+
+const FOLLOW_UP_ANSWERS = new Set(["yes", "no", "y", "n", "ok", "sure", "응", "네", "예", "아니", "아니요", "좋아"]);
+const EXCHANGE_CLIP = 2000;
+
+/** True for a bare yes/no-style answer: trimmed, case-insensitive, trailing punctuation ignored. */
+export function isFollowUpAnswer(text) {
+	return FOLLOW_UP_ANSWERS.has(String(text ?? "").trim().toLowerCase().replace(/[\s.!?,~。！？]+$/u, ""));
+}
+
+const clip = text => text.length > EXCHANGE_CLIP ? `${text.slice(0, EXCHANGE_CLIP)}…` : text;
+
+/**
+ * The exchange a follow-up answers, `{ user, assistant }`, or null when the
+ * request is not a follow-up or the session history holds none. `readHistory`
+ * returns the persisted session history read after the turn: when its last
+ * user message is the request itself, that turn is skipped.
+ */
+export function followUpExchange(request, readHistory) {
+	if (!isFollowUpAnswer(request)) return null;
+	let entries;
+	try { entries = transcriptFromHistory(readHistory() ?? []).filter(entry => (entry.kind === "user" || entry.kind === "assistant") && typeof entry.text === "string" && entry.text.trim()); }
+	catch { return null; }
+	const lastUser = entries.findLastIndex(entry => entry.kind === "user");
+	if (lastUser !== -1 && entries[lastUser].text.trim() === String(request).trim()) entries = entries.slice(0, lastUser);
+	const assistant = entries.findLastIndex(entry => entry.kind === "assistant");
+	if (assistant === -1) return null;
+	const user = entries.slice(0, assistant).findLast(entry => entry.kind === "user");
+	return { ...(user ? { user: clip(user.text) } : {}), assistant: clip(entries[assistant].text) };
+}

package/bin/agent/supervisor.mjs

@@ -4,7 +4,7 @@
 // has ended and appends exactly one `supervisor` event to the turn record,
 // which the panel shows as a note card.
 
-export const SUPERVISOR_RUBRIC = "You are the previs supervisor reviewing one agent turn in CozyClay Studio. Judge ONLY from the evidence given (receipts, refusal codes, geometry facts, pictures). Evaluate exactly these seven items: 1 request coverage - every deliverable the user literally asked for exists (blocker when missing); 2 impossible items - anything refused with TARGET_NOT_READY / CAPABILITY_MISSING / CONFIRMATION_REQUIRED is 'refused', not 'missing'; it is a blocker only when the reply hid the refusal from the user; 3 spatial sanity - floating or sunken objects, unintended interpenetration, subjects occluded by set pieces (concern); 4 framing - requested size vs derivedSize, clipped subjects, subject out of frame (concern); 5 continuity across shots - 180-degree line (axisConsistent, cameraSide), eyeline, OTS over the correct shoulder, screen direction (concern); 6 undo integrity - the turn is one history entry / receipts are undoable (blocker when broken); 7 report honesty - the reply claims nothing the receipts do not show and claims no verification that did not run (blocker). Capsule figures (characterKind proxy) cannot pose, sit or animate: a refused pose on one is 'refused'. Reply with JSON only: { \"items\": [{ \"text\": string, \"status\": \"done\"|\"partial\"|\"refused\"|\"missing\", \"evidence\": string }], \"issues\": [{ \"severity\": \"blocker\"|\"concern\"|\"note\", \"kind\": \"coverage\"|\"disclosure\"|\"spatial\"|\"framing\"|\"continuity\"|\"undo\"|\"honesty\", \"text\": string, \"evidence\": string }], \"summary\": string }. Write text fields in the user's language. Be concrete and short; cite ids, metres and shot names. An issue MAY carry \"fix\": { \"action\": \"<action id from the ACTIONS list>\", \"args\": { ... } } - ONE run_action call the next turn executes verbatim, with real ids and values taken from the receipts and geometry and args shaped by ACTION SCHEMAS. Examples: {\"action\":\"character.setPose\",\"args\":{\"characterId\":\"char-b\",\"posture\":\"sit\"}}, {\"action\":\"shot.frame\",\"args\":{\"shotId\":\"shot-1\",\"subjectIds\":[\"char-a\",\"char-b\"],\"framing\":{\"intent\":{\"size\":\"wide shot\",\"view\":\"front\",\"level\":\"eye\",\"side\":\"left\"}}}}, {\"action\":\"object.update\",\"args\":{\"id\":\"table-1\",\"position\":{\"x\":0,\"y\":0,\"z\":1.2}}}. Use only actions present in ACTIONS; never invent ids; never propose a pose or motion fix for a capsule figure; omit fix when no safe single action exists.";
+export const SUPERVISOR_RUBRIC = "You are the previs supervisor reviewing one agent turn in CozyClay Studio. Judge ONLY from the evidence given (receipts, refusal codes, geometry facts, pictures). Evaluate exactly these seven items: 1 request coverage - every deliverable the user literally asked for exists (blocker when missing); 2 impossible items - anything refused with TARGET_NOT_READY / CAPABILITY_MISSING / CONFIRMATION_REQUIRED is 'refused', not 'missing'; it is a blocker only when the reply hid the refusal from the user; 3 spatial sanity - floating or sunken objects, unintended interpenetration, subjects occluded by set pieces (concern); 4 framing - requested size vs derivedSize, clipped subjects, subject out of frame (concern); 5 continuity across shots - 180-degree line (axisConsistent, cameraSide), eyeline, OTS over the correct shoulder, screen direction (concern); 6 undo integrity - the turn is one history entry / receipts are undoable (blocker when broken); 7 report honesty - the reply claims nothing the receipts do not show and claims no verification that did not run (blocker). Capsule figures (characterKind proxy) cannot pose, sit or animate: a refused pose on one is 'refused'. In a hybrid project (castStyle hybrid, or no castStyle given), capsule figures the user approved in place of rigs for a shot (previousExchange holds the proposal the request answers) are not a coverage miss. Reply with JSON only: { \"items\": [{ \"text\": string, \"status\": \"done\"|\"partial\"|\"refused\"|\"missing\", \"evidence\": string }], \"issues\": [{ \"severity\": \"blocker\"|\"concern\"|\"note\", \"kind\": \"coverage\"|\"disclosure\"|\"spatial\"|\"framing\"|\"continuity\"|\"undo\"|\"honesty\", \"text\": string, \"evidence\": string }], \"summary\": string }. Write text fields in the user's language. Be concrete and short; cite ids, metres and shot names. An issue MAY carry \"fix\": { \"action\": \"<action id from the ACTIONS list>\", \"args\": { ... } } - ONE run_action call the next turn executes verbatim, with real ids and values taken from the receipts and geometry and args shaped by ACTION SCHEMAS. Examples: {\"action\":\"character.setPose\",\"args\":{\"characterId\":\"char-b\",\"posture\":\"sit\"}}, {\"action\":\"shot.frame\",\"args\":{\"shotId\":\"shot-1\",\"subjectIds\":[\"char-a\",\"char-b\"],\"framing\":{\"intent\":{\"size\":\"wide shot\",\"view\":\"front\",\"level\":\"eye\",\"side\":\"left\"}}}}, {\"action\":\"object.update\",\"args\":{\"id\":\"table-1\",\"position\":{\"x\":0,\"y\":0,\"z\":1.2}}}. Use only actions present in ACTIONS; never invent ids; never propose a pose or motion fix for a capsule figure; omit fix when no safe single action exists.";
 
 const REFUSAL_CODES = Object.freeze(["TARGET_NOT_READY", "CAPABILITY_MISSING", "CONFIRMATION_REQUIRED"]);
 const SUPERVISOR_LIMITS = Object.freeze({ delta: 8, warnings: 12, reply: 4000, images: 5, createdShots: 3, imageWidth: 1280, args: 600, timeoutMs: 120_000, schemaBytes: 6000 });
@@ -110,13 +110,13 @@ function boundSchemas(schemas) {
  * five pi ImageContent parts, in the order the text lists them. `actions` is
  * `{ index: [{ id, label }], schemas: [{ id, input }] }`: what a fix may name
  * and the input shape of the pre-selected ones (#743). */
-export function buildSupervisorInput({ request = "", frames = [], reply = "", geometry = null, refusals, images = [], notes = [], actions = null } = {}) {
+export function buildSupervisorInput({ request = "", frames = [], reply = "", geometry = null, refusals, images = [], notes = [], actions = null, castStyle, previousExchange } = {}) {
 	const turn = analyseTurnFrames(frames);
 	const pictures = (Array.isArray(images) ? images : []).map(image => ({ image, part: imagePart(image) })).filter(entry => entry.part).slice(0, SUPERVISOR_LIMITS.images);
 	const section = (name, value) => `${name}: ${JSON.stringify(value)}`;
 	const text = [
 		"<turn-review>",
-		section("request", String(request ?? "")),
+		section("request", String(request ?? "")), ...(previousExchange ? [section("previousExchange", previousExchange)] : []), ...(typeof castStyle === "string" ? [section("castStyle", castStyle)] : []),
 		section("toolCalls", turn.calls),
 		section("receipts", turn.receipts.map(entry => ({ tool: entry.tool, ...boundReceipt(entry.receipt) }))),
 		section("refusals", Array.isArray(refusals) ? refusals : turn.refusals),
@@ -272,14 +272,14 @@ async function gatherSupervisorEvidence({ hub, workspaceHandle, admission, basel
 			try { await operate(original); } catch (error) { notes.push(`playhead not restored to frame ${original}: ${redact(error?.message)}`); }
 		}
 	}
-	return { geometry, images: images.slice(0, SUPERVISOR_LIMITS.images), notes, actions: { index, schemas } };
+	return { geometry, images: images.slice(0, SUPERVISOR_LIMITS.images), notes, actions: { index, schemas }, ...(typeof context?.scene?.castStyle === "string" ? { castStyle: context.scene.castStyle } : {}) };
 }
 
 /**
  * Review one finished turn. Never throws: any failure becomes a frame with
  * verdict "unavailable" and the reason.
  */
-export async function runSupervisor({ registry, modelKey, effort = "high", turnId, request, frames, reply, hub, workspaceHandle, admission, baseline, actions = [], now = () => Date.now(), timeoutMs = SUPERVISOR_LIMITS.timeoutMs }) {
+export async function runSupervisor({ registry, modelKey, effort = "high", turnId, request, frames, reply, hub, workspaceHandle, admission, baseline, actions = [], previousExchange = null, now = () => Date.now(), timeoutMs = SUPERVISOR_LIMITS.timeoutMs }) {
 	const startedAt = now();
 	let thinking = null;
 	const frame = (fields) => ({ type: "supervisor", turnId, model: modelKey, effort: thinking, elapsedMs: Math.max(0, Math.round(now() - startedAt)), ...fields });
@@ -293,7 +293,7 @@ export async function runSupervisor({ registry, modelKey, effort = "high", turnI
 		thinking = level;
 		const turn = analyseTurnFrames(frames);
 		const evidence = await gatherSupervisorEvidence({ hub, workspaceHandle, admission, baseline, receipts: turn.receipts, actionIndex: actions });
-		const input = buildSupervisorInput({ request, frames, reply, geometry: evidence.geometry, refusals: turn.refusals, images: evidence.images, notes: evidence.notes, actions: evidence.actions });
+		const input = buildSupervisorInput({ request, frames, reply, geometry: evidence.geometry, refusals: turn.refusals, images: evidence.images, notes: evidence.notes, actions: evidence.actions, castStyle: evidence.castStyle, previousExchange });
 		const message = await registry.completeSimple(model, {
 			systemPrompt: SUPERVISOR_RUBRIC,
 			messages: [{ role: "user", content: [{ type: "text", text: input.text }, ...input.images], timestamp: Date.now() }],

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 {