cozyclay 3.1.4 → 3.1.5

package/CHANGELOG.md

@@ -2,6 +2,92 @@
 
 ## Unreleased
 
+## 3.1.5 - 2026-10-25
+
+The Studio tells you when a new release is out and installs it in one click, Claude models work in the agent panel again, IK edits stay on their own character, turns and walks look more natural, and anonymous analytics show where the Studio gets in the way.
+
+Agent
+
+- Agent turns on Claude models no longer fail with a 400 error about a
+  deferred placeholder tool.
+- When a turn is already running, the failure chip reads `busy` instead of
+  `upstream`. The message text is unchanged.
+
+Motion
+
+- The head turns first and leads the body into a turn, by about 5 frames at
+  24 fps, the way a person's does. `flow.headLead` sets the frames (0 to
+  12), and `false` turns it off. A keyed head look still wins.
+- Takes that walk report `observations.gait`: cadence, step length, speed,
+  stance and pelvis motion, with warnings outside a person's range. It is a
+  reading only and never changes the QA result.
+- Grasp QA reads each finger: `FINGER_ROM` (a joint past its range),
+  `FINGER_SELF` (two fingers inside each other) and `THUMB_OFF` (a held
+  object without the thumb on it).
+- A carried ball keeps the thumb on it. A finger that misses a held object
+  turns toward it at the knuckle, and the ring and little fingers curl
+  together. Stacked hand presets no longer over-curl.
+
+Studio
+
+- An npm studio shows a small **Update** chip in the top bar when a newer
+  release is out, once per version. A global install whose folder npm can
+  write gets **Update now**, which installs the release and then asks you
+  to restart `cclay`. Other installs get the command to copy, and npx gets
+  "run `npx cozyclay` again". **Update now** waits while an agent turn,
+  an export or a recording runs. A failed install names the cause
+  (permissions, network, Node version, npm missing) and keeps the command.
+- An IK edit stays with its own character. Selecting another character
+  mid-drag no longer poses it, and undo no longer reverts or deletes the
+  other character. Switching characters applies a pending IK edit and shows
+  a notice.
+- Ctrl+Z after an IK drag puts the pose back, with or without a take
+  loaded.
+- On a browser without WebGL, the unavailable notice appears one frame
+  after the Studio first draws instead of during it.
+
+CLI
+
+- `cclay update --check` prints the current and latest version without
+  installing, and exits 0 (up to date), 10 (update available) or 11
+  (unknown). `cclay update` now refuses a release your Node.js cannot run.
+- A source checkout reports itself as `clone`, and a Windows global install
+  is no longer mistaken for npx.
+
+Site
+
+- A redesigned cozyclay.org: a black first screen with a greybox-to-video
+  reel, how-it-works clips from the tutorial, and Try it opens the Studio.
+
+Analytics
+
+- The anonymous usage analytics now cover where the Studio gets in the way:
+  - the agent loop: refused commands, a summary per agent turn, each motion
+    draft and its QA result, and each prompt sent, so retry loops and
+    hesitation show
+  - model connect: the sign-in steps and where they stop, and model changes
+  - exports: retries, the stage a failed or stopped export reached, and
+    saved files. Storyboard PNG, render pass and OTIO exports are now
+    counted.
+  - clicks, shortcuts and search: repeated or dead clicks on the main
+    controls, shortcuts that did nothing, searches with no result, and
+    switching panels or orbiting the camera back and forth
+  - playback, boot and crashes: time to the first frame, playback runs and
+    late frames, the first-success guide, render crashes and lost WebGL
+  - the update notice: when it shows, which button was pressed, and whether
+    the install worked
+  - one friction summary per session
+- Every value is a closed bucket or a fixed id. No text, names, paths,
+  object ids, click coordinates or npm output are sent. Prompt text never
+  leaves the browser; only a length bucket and a similarity grade to the
+  last prompt do.
+- First-edit events count only your own edits, not the agent's, and report
+  `definition_version` 2.
+- Events that nothing sent any more are removed: the old motion-generation
+  events and `sample:played`.
+- The privacy page lists every event and property. `cclay telemetry off`
+  still turns it all off.
+
 ## 3.1.4 - 2026-10-24
 
 Starring CozyClay from the terminal takes one key when the GitHub CLI is signed in.

package/INSTALL_FOR_AGENTS.md

@@ -32,6 +32,9 @@ npx -y cozyclay --no-star
 
 For a permanent install, run `npm install -g cozyclay`. Then `cclay` and `cozyclay` are the same
 command. `cclay update` installs the latest release.
+`cclay update --check` installs nothing. It prints the current version, the latest version and
+the install kind, then exits `0` when up to date, `10` when an update is available, and `11` when
+it cannot tell (offline, or checks turned off).
 
 Tell the user:
 

package/README.md

@@ -58,6 +58,11 @@ npx cozyclay
 That is the whole install. You need Node.js 22.19 or newer and a Chromium browser. You do not need
 a GPU, Python or a model download. The studio opens at `http://127.0.0.1:5180/app/`.
 
+**Updating.** `npx cozyclay` fetches the newest release each time you run it. After
+`npm install -g cozyclay`, the studio shows a small **Update** chip in the top bar when a newer
+release is out. **Update now** installs it, and then you restart `cclay`. `cclay update` does the
+same from the terminal. `--no-update-check` or `COZYCLAY_NO_UPDATE_CHECK=1` turns the check off.
+
 > **Asking an AI agent to set it up?** Give it this repository link. Its instructions are in
 > [`INSTALL_FOR_AGENTS.md`](INSTALL_FOR_AGENTS.md).
 

package/bin/agent/agent-failure-codes.mjs

@@ -0,0 +1,31 @@
+// The closed `agent:turn_failed.failure_code` vocabulary, sidecar side. Kept
+// self-contained (minimal sidecar installs omit src/); it gives the same answers
+// as src/workflow/agent-failure-codes.js, whose header defines each code, and
+// test/verify-agent-execution.mjs holds the two tables to that. Only the
+// structured code and HTTP status are read, never a message.
+const BY_CODE = {
+	unauthorized: "key_refused", auth: "auth", AUTH_REQUIRED: "auth", rate_limit: "rate_limited", RATE_LIMITED: "rate_limited",
+	STALE_SCENE: "stale_scene", STALE_TARGET: "stale_scene", STALE_ENVIRONMENT: "stale_scene",
+	CAPABILITY_MISSING: "capability_missing", LIVE_HUB_UNAVAILABLE: "capability_missing",
+	busy: "busy", TARGET_BUSY: "busy", SCOPE_BUSY: "busy", TARGET_NOT_READY: "busy",
+};
+
+/** `{ code, status }` (a thrown error or a runner `error` frame) -> failure code.
+ * The runner's `overloaded`/`upstream`/`truncated` and every 5xx read as upstream. */
+export function failureCodeOf(error, fallback = "upstream") {
+	try {
+		const code = typeof error?.code === "string" ? error.code : "";
+		const status = error?.status;
+		if (Object.hasOwn(BY_CODE, code)) return BY_CODE[code];
+		if (code.startsWith("INVALID_")) return "invalid_request";
+		if (status === 401 || status === 403) return "auth";
+		if (status === 429) return "rate_limited";
+		return Number.isInteger(status) && status >= 400 && status < 500 ? "invalid_request" : fallback;
+	} catch { return fallback; }
+}
+
+/** A turn that threw: an abort wins, then the error's own code, then a tool failure. */
+export const agentFailureCode = (error, signal, tool = false) => {
+	try { if (signal.aborted || error?.name === "AbortError") return "aborted"; } catch { /* foreign getter */ }
+	return failureCodeOf(error, tool ? "tool_failed" : "upstream");
+};

package/bin/agent/agent-routes.mjs

@@ -13,6 +13,7 @@ import { createAgentRunner } from "./agent-runner.mjs";
 import { createProviderRoutes } from "./provider-routes.mjs";
 import { STUDIO_SYSTEM_PROMPT_STORYBOARD } from "./studio-prompt.mjs";
 import { studioTransaction } from "./studio-turn-transaction.mjs";
+import { agentFailureCode, failureCodeOf } from "./agent-failure-codes.mjs";
 
 // Values the codex backend accepts for reasoning.effort (its own 400 lists them).
 export const REASONING_EFFORTS = ["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"];
@@ -77,12 +78,6 @@ const agentToolCategory = (name) => {
 	if (name === "place_image_in_scene" || name === "add_reference_node") return "scene_write";
 	return "other";
 };
-const agentFailureCode = (error, signal, tool = false) => advisory(() => {
-	if (signal.aborted || error?.name === "AbortError") return "aborted";
-	if (error?.status === 401 || error?.code === "unauthorized") return "auth";
-	if (error?.status === 429) return "rate_limited";
-	return tool ? "tool_failed" : "upstream";
-}, tool ? "tool_failed" : "upstream");
 // These existing canvas commands only return a node/edge after publishing a
 // new insertion. Read/focus, generic accepted responses, update no-ops and run
 // outputs (which can echo old values) are deliberately not application proof.
@@ -579,7 +574,7 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 			}
 			if (frame.type === "error") {
 			turnOutcome = controller.signal.aborted || frame.code === "aborted" ? "cancelled" : "failed";
-			turnFailureCode = controller.signal.aborted ? "aborted" : frame.code;
+			turnFailureCode = controller.signal.aborted || frame.code === "aborted" ? "aborted" : failureCodeOf(frame);
 			return send(frame);
 			}
 			if (frame.type === "done") {
@@ -822,7 +817,7 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 		const send = (event) => { if (!res.writableEnded && !res.destroyed) res.write(`data: ${JSON.stringify(event)}\n\n`); };
 		let session = sessions.get(value.sessionId);
 		if (session?.running) {
-			send({ type: "error", code: "upstream", message: "busy" }); send({ type: "done" }); res.end(); return true;
+			send({ type: "error", code: "busy", message: "busy" }); send({ type: "done" }); res.end(); return true;
 		}
 		session ||= { images: new Map(), history: [] };
 		sessions.set(value.sessionId, session);
@@ -870,7 +865,7 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 					return;
 				}
 				turnOutcome = signal.aborted || frame.code === "aborted" ? "cancelled" : "failed";
-				turnFailureCode = signal.aborted ? "aborted" : frame.code;
+				turnFailureCode = signal.aborted || frame.code === "aborted" ? "aborted" : failureCodeOf(frame);
 				return send(frame);
 			}
 			if (frame.type === "done") {
@@ -903,7 +898,7 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 		catch (error) {
 			turnOutcome = signal.aborted ? "cancelled" : "failed";
 			turnFailureCode = signal.aborted ? "aborted" : agentFailureCode(error, signal, toolFailed);
-			if (!signal.aborted) emitFrame({ type: "error", ...errorInfo(error, quota) });
+			if (!signal.aborted) send({ type: "error", ...errorInfo(error, quota) });
 			if (!res.writableEnded) emitFrame({ type: "done" });
 		}
 		finally {

package/bin/agent/agent-runner.mjs

@@ -220,8 +220,10 @@ export function withAnthropicCacheBreakpoints(payload, model) {
 		next = { ...next, system: [...system.slice(0, -1), { ...system.at(-1), cache_control: cacheControl }] };
 		count += 1;
 	}
-	if (tools.length && !marked(tools.at(-1)) && model?.compat?.supportsCacheControlOnTools !== false && count < 4) {
-		next = { ...next, tools: [...tools.slice(0, -1), { ...tools.at(-1), cache_control: cacheControl }] };
+	// pi-ai 1.4 appends a defer_loading placeholder tool; the API rejects cache_control on deferred tools.
+	const lastTool = tools.findLastIndex((tool) => !tool?.defer_loading);
+	if (lastTool !== -1 && !marked(tools[lastTool]) && model?.compat?.supportsCacheControlOnTools !== false && count < 4) {
+		next = { ...next, tools: tools.map((tool, index) => index === lastTool ? { ...tool, cache_control: cacheControl } : tool) };
 	}
 	return next === payload ? undefined : next;
 }
@@ -511,7 +513,7 @@ export function createAgentRunner({ models: suppliedModels, sessionStore, tools
 
 		const start = async function* (input = {}) {
 			if (state.active) {
-				yield { type: "error", code: "upstream", message: "busy" };
+				yield { type: "error", code: "busy", message: "busy" };
 				yield { type: "done" };
 				return;
 			}

package/bin/cozyclay.mjs

@@ -14,7 +14,6 @@
  * that needs an install step before it can serve a prebuilt app is a
  * launcher that will break.
  */
-import { spawn } from "node:child_process";
 import { createReadStream, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { createServer } from "node:http";
 import { homedir } from "node:os";
@@ -24,7 +23,8 @@ 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 } from "./update-check.mjs";
+import { checkForUpdate, readUpdateStatus, runUpdate, runUpdateCheck, 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";
@@ -56,8 +56,8 @@ const OFFICIAL_PACKAGE = (
 	&& !SOURCE_CHECKOUT
 	&& verifyPackageMarker(join(DIST, "cozyclay-package.json"), PKG_ROOT, packageMetadata)
 );
-const INSTALL_KIND = process.env.npm_config_global === "true"
-	|| (PKG_ROOT.includes("/node_modules/") && !PKG_ROOT.includes("/_npx/"))
+const INSTALL_KIND = SOURCE_CHECKOUT ? "clone" : process.env.npm_config_global === "true"
+	|| (/[\\/]node_modules[\\/]/.test(PKG_ROOT) && !/[\\/]_npx[\\/]/.test(PKG_ROOT))
 	? "global"
 	: "npx";
 
@@ -143,6 +143,7 @@ const HELP = `cozyclay - browser-based 3D staging studio
   cclay live status         drive a running studio from the terminal
                             (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
   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
@@ -211,11 +212,12 @@ if (argv[0] === "mcp") {
 } 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) {
-		console.error(`cozyclay: update takes no arguments (got ${argv.slice(1).join(" ")})`);
+	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);
 	}
-	runUpdate();
+	if (argv[1] === "--check") process.exit(await runUpdateCheck({ currentVersion: readVersion(), kind: INSTALL_KIND, stateDir: STATE_DIR }));
+	else runUpdate();
 } else if (argv[0] === "telemetry") {
 	const action = argv[1] ?? "status";
 	const internalAction = action === "internal" ? argv[2] : null;
@@ -251,21 +253,14 @@ if (opts.version) {
 	console.log(version);
 	process.exit(0);
 }
-let runtimeTelemetry = takeRuntimeTelemetryConfig(STATE_FILE, {
-	appVersion: version,
-	officialPackage: OFFICIAL_PACKAGE,
-	installKind: INSTALL_KIND,
-});
+const takeRuntime = () => takeRuntimeTelemetryConfig(STATE_FILE, { appVersion: version, officialPackage: OFFICIAL_PACKAGE, installKind: INSTALL_KIND });
+let runtimeTelemetry = takeRuntime();
 if (runtimeTelemetry.firstLaunch && !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);
-	runtimeTelemetry = takeRuntimeTelemetryConfig(STATE_FILE, {
-		appVersion: version,
-		officialPackage: OFFICIAL_PACKAGE,
-		installKind: INSTALL_KIND,
-	});
+	runtimeTelemetry = takeRuntime();
 	}
 }
 const telemetryState = readTelemetryState(STATE_FILE);
@@ -281,7 +276,7 @@ if (
 }
 // 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 = Boolean(opts.updateCheck && !process.env.CI && !process.env.COZYCLAY_NO_UPDATE_CHECK);
+const updateChecksEnabled = updateChecksOn(opts.updateCheck);
 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).");
@@ -309,6 +304,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 } });
 server = createServer((req, res) => {
 	const url = new URL(req.url ?? "/", "http://127.0.0.1");
 	if (/^\/oauth\/(start|status|logout)$/.test(url.pathname)) {
@@ -328,47 +324,7 @@ server = createServer((req, res) => {
 		});
 		return;
 	}
-	if (url.pathname === "/__cozyclay/telemetry") {
-		if (req.method === "POST") {
-			const origin = req.headers.origin;
-			const expectedOrigin = `http://127.0.0.1:${opts.port}`;
-			if (origin !== expectedOrigin) {
-				res.writeHead(403, { "content-type": "application/json; charset=utf-8" });
-				res.end(JSON.stringify({ error: "forbidden origin" }));
-				return;
-			}
-			let body = "";
-			req.setEncoding("utf8");
-			req.on("data", (chunk) => {
-				body += chunk;
-				if (body.length > 1024) req.destroy();
-			});
-			req.on("end", () => {
-				try {
-					const value = JSON.parse(body);
-					if (typeof value.enabled !== "boolean") throw new TypeError("enabled must be boolean");
-					setTelemetryEnabled(STATE_FILE, value.enabled);
-					runtimeTelemetry = takeRuntimeTelemetryConfig(STATE_FILE, {
-						appVersion: version,
-						officialPackage: OFFICIAL_PACKAGE,
-						installKind: INSTALL_KIND,
-					});
-					res.writeHead(200, {
-						"content-type": "application/json; charset=utf-8",
-						"cache-control": "no-store",
-					});
-					res.end(JSON.stringify(runtimeTelemetry));
-				} catch {
-					res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
-					res.end(JSON.stringify({ error: "invalid telemetry setting" }));
-				}
-			});
-			return;
-		}
-		res.writeHead(405, { allow: "POST", "content-type": "application/json; charset=utf-8" });
-		res.end(JSON.stringify({ error: "method not allowed" }));
-		return;
-	}
+	if (studioRoutes(req, res, url)) return;
 	let rel;
 	try {
 		rel = decodeURIComponent(url.pathname);
@@ -396,11 +352,7 @@ server = createServer((req, res) => {
 		return;
 	}
 	if (target === join(DIST, "app", "index.html")) {
-		runtimeTelemetry = takeRuntimeTelemetryConfig(STATE_FILE, {
-			appVersion: version,
-			officialPackage: OFFICIAL_PACKAGE,
-			installKind: INSTALL_KIND,
-		});
+		runtimeTelemetry = takeRuntime();
 		// Whether this launch is the newest release, from the registry answer the
 		// update check already cached (#466). Never a request of its own.
 		const runtime = { ...runtimeTelemetry, updateStatus: updateChecksEnabled ? readUpdateStatus(version, STATE_DIR) : "unknown" };

package/bin/studio-routes.mjs

@@ -0,0 +1,69 @@
+/**
+ * The launcher's own /__cozyclay/* routes, kept out of bin/cozyclay.mjs:
+ * the telemetry toggle the Studio's privacy setting posts to, and the update
+ * routes behind the Studio's update chip.
+ */
+import { setTelemetryEnabled } from "./telemetry-state.mjs";
+import { lookupLatest } from "./update-check.mjs";
+import { canSelfUpdate, createInstaller } from "./update-install.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.
+ */
+export function createStudioRoutes({ port, stateFile, takeRuntime, update: { currentVersion, stateDir, kind, enabled, pkgRoot } }) {
+	const updateRoute = createUpdateRoutes({
+		currentVersion,
+		kind,
+		enabled,
+		port,
+		checkLatest: () => lookupLatest(currentVersion, stateDir),
+		canSelfUpdate: () => canSelfUpdate({ pkgRoot }),
+		installer: createInstaller(),
+	});
+	return function handleStudioRoute(req, res, url) {
+		if (url.pathname === "/__cozyclay/update") {
+			void updateRoute(req, res);
+			return true;
+		}
+		if (url.pathname !== "/__cozyclay/telemetry") return false;
+		if (req.method === "POST") {
+			const origin = req.headers.origin;
+			const expectedOrigin = `http://127.0.0.1:${port}`;
+			if (origin !== expectedOrigin) {
+				res.writeHead(403, { "content-type": "application/json; charset=utf-8" });
+				res.end(JSON.stringify({ error: "forbidden origin" }));
+				return true;
+			}
+			let body = "";
+			req.setEncoding("utf8");
+			req.on("data", (chunk) => {
+				body += chunk;
+				if (body.length > 1024) req.destroy();
+			});
+			req.on("end", () => {
+				try {
+					const value = JSON.parse(body);
+					if (typeof value.enabled !== "boolean") throw new TypeError("enabled must be boolean");
+					setTelemetryEnabled(stateFile, value.enabled);
+					const runtimeTelemetry = takeRuntime();
+					res.writeHead(200, {
+						"content-type": "application/json; charset=utf-8",
+						"cache-control": "no-store",
+					});
+					res.end(JSON.stringify(runtimeTelemetry));
+				} catch {
+					res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
+					res.end(JSON.stringify({ error: "invalid telemetry setting" }));
+				}
+			});
+			return true;
+		}
+		res.writeHead(405, { allow: "POST", "content-type": "application/json; charset=utf-8" });
+		res.end(JSON.stringify({ error: "method not allowed" }));
+		return true;
+	};
+}

package/bin/update-check.mjs

@@ -52,20 +52,32 @@ export function compareVersions(a, b) {
 	return 0;
 }
 
+// A registry answer whose cache write failed (a read-only home), by cache file.
+// The write is best effort, so a good fetch must not depend on it.
+const fetchedInProcess = new Map();
+
+// The newer of the cache file and this process's own last fetch.
 function readCache(cacheFile) {
+	let disk = null;
 	try {
-		return JSON.parse(readFileSync(cacheFile, "utf8"));
+		disk = JSON.parse(readFileSync(cacheFile, "utf8"));
 	} catch {
-		return null;
+		/* missing or unreadable: the in-process answer, if any, stands */
 	}
+	const memory = fetchedInProcess.get(cacheFile) ?? null;
+	if (!disk) return memory;
+	return memory && !(memory.checkedAt <= disk.checkedAt) ? memory : disk;
 }
 
 function writeCache(cacheFile, cacheDir, latest) {
+	const entry = { latest, checkedAt: Date.now() };
 	try {
 		mkdirSync(cacheDir, { recursive: true });
-		writeFileSync(cacheFile, JSON.stringify({ latest, checkedAt: Date.now() }, null, "\t"));
+		writeFileSync(cacheFile, JSON.stringify(entry, null, "\t"));
+		fetchedInProcess.delete(cacheFile);
 	} catch {
-		/* a read-only home is not a reason to fail a local dev server */
+		// A read-only home is not a reason to fail a local dev server, nor to forget the answer.
+		fetchedInProcess.set(cacheFile, entry);
 	}
 }
 
@@ -134,11 +146,47 @@ 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 registry's latest x.y.z with this launch's status: the shape behind
+ * GET /__cozyclay/update and `cclay update --check`. The cache rules are
+ * checkForUpdate's; `fresh` asks the registry even inside the TTL, and a dead
+ * registry still falls back to the cached answer.
+ */
+export async function lookupLatest(currentVersion, stateDir, { fresh = false } = {}) {
+	const cacheFile = join(stateDir, "update-check.json");
+	if (fresh) {
+		const fetched = await fetchLatest();
+		if (fetched) writeCache(cacheFile, stateDir, fetched);
+	} else {
+		await checkForUpdate(currentVersion, stateDir);
+	}
+	const latest = readCache(cacheFile)?.latest;
+	const known = typeof latest === "string" && /^\d+\.\d+\.\d+/.test(latest);
+	return { latest: known ? latest : null, status: readUpdateStatus(currentVersion, stateDir) };
+}
+
+/**
+ * `cclay update --check`: print, install nothing, and exit 0 when this is the
+ * 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 }) {
+	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;
+}
+
 // 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() {
 	const npm = process.platform === "win32" ? "npm.cmd" : "npm";
-	const child = spawn(npm, ["install", "-g", "cozyclay@latest"], { stdio: "inherit", shell: process.platform === "win32" });
+	const child = spawn(npm, ["install", "-g", "cozyclay@latest", "--engine-strict"], { stdio: "inherit", shell: process.platform === "win32" });
 	child.on("error", (err) => {
 		console.error(`cozyclay: could not run npm: ${err.message}`);
 		process.exit(1);