Skip to content

Write HTML. Render video. Built for agents.

fix(cli): an update never replaces the CLI's files while a hyperframes command is running (#4637)

Miguel Ángelf39b179030f8
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 0635ec1366..9d2541cd70 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -116,6 +116,9 @@ import {
registerRootExitRequester,
type CommandResult,
} from "./utils/commandResult.js";
+import { registerRunningCli } from "./utils/runningCli.js";
+
+registerRunningCli();
const isHelp = process.argv.includes("--help") || process.argv.includes("-h");
diff --git a/packages/cli/src/utils/autoUpdate.installer.test.ts b/packages/cli/src/utils/autoUpdate.installer.test.ts
new file mode 100644
index 0000000000..fe1802e880
--- /dev/null
+++ b/packages/cli/src/utils/autoUpdate.installer.test.ts
@@ -0,0 +1,152 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ rmSync,
+ utimesSync,
+ writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, expect, it } from "vitest";
+import { installerScript } from "./autoUpdate.js";
+
+// Runs the real detached-installer script; the "install" only writes a marker file.
+const dirs: string[] = [];
+const children: ChildProcess[] = [];
+
+afterEach(() => {
+ for (const child of children.splice(0)) child.kill();
+ for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+function setup(staleMs = 60_000) {
+ const dir = mkdtempSync(join(tmpdir(), "hf-installer-"));
+ dirs.push(dir);
+ const runningDir = join(dir, "running");
+ mkdirSync(runningDir);
+ const marker = join(dir, "installed");
+ const script = installerScript({
+ configFile: join(dir, "config.json"),
+ version: "9.9.9",
+ bin: process.execPath,
+ args: ["-e", `require("node:fs").writeFileSync(${JSON.stringify(marker)}, "")`],
+ runningDir,
+ pollMs: 50,
+ maxWaitMs: 60_000,
+ staleMs,
+ });
+ return { dir, runningDir, marker, script };
+}
+
+function start(args: string[]): ChildProcess {
+ const child = spawn(process.execPath, args, { stdio: "ignore" });
+ children.push(child);
+ return child;
+}
+
+const exited = (child: ChildProcess) =>
+ child.exitCode !== null || child.signalCode !== null
+ ? Promise.resolve()
+ : new Promise<void>((resolve) => child.once("exit", () => resolve()));
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function until(check: () => boolean): Promise<void> {
+ while (!check()) await sleep(25);
+}
+
+function backdate(file: string): void {
+ const tenMinutesAgo = new Date(Date.now() - 10 * 60_000);
+ utimesSync(file, tenMinutesAgo, tenMinutesAgo);
+}
+
+async function expectInstalledAndRemoved(script: string, marker: string, file: string) {
+ await exited(start(["-e", script]));
+ expect(existsSync(marker)).toBe(true);
+ expect(existsSync(file)).toBe(false);
+}
+
+function registerCli(runningDir: string): ChildProcess {
+ const cli = start(["-e", "setInterval(() => {}, 1000)"]);
+ writeFileSync(join(runningDir, String(cli.pid)), "");
+ return cli;
+}
+
+it("never replaces package files while a CLI process is running, then installs once it exits", async () => {
+ const { dir, runningDir, marker, script } = setup();
+ const cli = registerCli(runningDir);
+ const installer = start(["-e", script]);
+
+ await sleep(1000);
+ expect(existsSync(marker)).toBe(false);
+
+ cli.kill();
+ await exited(installer);
+ expect(existsSync(marker)).toBe(true);
+ expect(JSON.parse(readFileSync(join(dir, "config.json"), "utf-8")).completedUpdate).toMatchObject(
+ { version: "9.9.9", ok: true },
+ );
+});
+
+it("does not wait on a CLI process that died without cleaning up", async () => {
+ const { runningDir, marker, script } = setup();
+ const dead = start(["-e", ""]);
+ await exited(dead);
+ const staleFile = join(runningDir, String(dead.pid));
+ writeFileSync(staleFile, "");
+
+ await expectInstalledAndRemoved(script, marker, staleFile);
+});
+
+it("keeps waiting on a live command whose file looks old after the machine slept", async () => {
+ const { runningDir, marker, script } = setup();
+ const cli = registerCli(runningDir);
+ const file = join(runningDir, String(cli.pid));
+ backdate(file);
+ const installer = start(["-e", script]);
+
+ await sleep(1000);
+ expect(existsSync(marker)).toBe(false);
+ expect(existsSync(file)).toBe(true);
+
+ cli.kill();
+ await exited(installer);
+ expect(existsSync(marker)).toBe(true);
+});
+
+it("drops a pid file whose pid belongs to another process once it stops changing", async () => {
+ const { runningDir, marker, script } = setup(300);
+ const other = start(["-e", "setInterval(() => {}, 1000)"]);
+ const staleFile = join(runningDir, String(other.pid));
+ writeFileSync(staleFile, "");
+ backdate(staleFile);
+
+ await expectInstalledAndRemoved(script, marker, staleFile);
+});
+
+it("lets only one installer wait: a later launch exits and installs nothing", async () => {
+ const { dir, runningDir, marker, script } = setup();
+ const cli = registerCli(runningDir);
+ const first = start(["-e", script]);
+ await until(() => existsSync(join(dir, "config.json.install-lock")));
+
+ await exited(start(["-e", script]));
+ expect(existsSync(marker)).toBe(false);
+
+ cli.kill();
+ await exited(first);
+ expect(existsSync(marker)).toBe(true);
+});
+
+it("takes over an install lock whose pid belongs to another process once it stops changing", async () => {
+ const { dir, marker, script } = setup(300);
+ const other = start(["-e", "setInterval(() => {}, 1000)"]);
+ const lock = join(dir, "config.json.install-lock");
+ writeFileSync(lock, String(other.pid));
+ backdate(lock);
+
+ await exited(start(["-e", script]));
+ expect(existsSync(marker)).toBe(true);
+});
diff --git a/packages/cli/src/utils/autoUpdate.ts b/packages/cli/src/utils/autoUpdate.ts
index 3b034f11b4..bb5350851c 100644
--- a/packages/cli/src/utils/autoUpdate.ts
+++ b/packages/cli/src/utils/autoUpdate.ts
@@ -31,6 +31,7 @@ import { compareVersions } from "compare-versions";
import { withFileLock } from "../media-use/lib/config-lock.mjs";
import { readConfig, writeConfig } from "../telemetry/config.js";
import { updateCheckDisabled } from "./updateCheck.js";
+import { RUNNING_DIR, RUNNING_STALE_MS } from "./runningCli.js";
import {
detectInstaller,
installInvocation,
@@ -41,6 +42,9 @@ const CONFIG_DIR = join(homedir(), ".hyperframes");
const LOG_FILE = join(CONFIG_DIR, "auto-update.log");
/** An install that hasn't finished after this many ms is considered stuck. */
const PENDING_TIMEOUT_MS = 10 * 60 * 1000;
+/** A waiting installer gives up after this long; the next run schedules it again. */
+const INSTALL_MAX_WAIT_MS = 60 * 60 * 1000;
+const INSTALL_POLL_MS = 2_000;
function isAutoInstallDisabled(): boolean {
return updateCheckDisabled() || process.env["HYPERFRAMES_NO_AUTO_INSTALL"] === "1";
@@ -65,6 +69,125 @@ function log(line: string): void {
}
}
+export interface InstallerScriptOptions {
+ configFile: string;
+ version: string;
+ bin: string;
+ args: readonly string[];
+ runningDir: string;
+ pollMs: number;
+ maxWaitMs: number;
+ /** A pid or install-lock file not touched for this long belongs to a dead process. */
+ staleMs: number;
+}
+
+/** The detached installer, run via `node -e`: waits until no CLI in `runningDir` is alive, then
+ * installs with execFile (no shell) and records completedUpdate under the settings lock. */
+export function installerScript(o: InstallerScriptOptions): string {
+ return `
+ const { execFile } = require("node:child_process");
+ const fs = require("node:fs");
+ const { join } = require("node:path");
+ const { readFileSync, renameSync, writeFileSync } = fs;
+ const CFG = ${JSON.stringify(o.configFile)};
+ const TMP = \`\${CFG}.tmp\`;
+ const INSTALL_LOCK = \`\${CFG}.install-lock\`;
+ const RUNNING = ${JSON.stringify(o.runningDir)};
+ const VERSION = ${JSON.stringify(o.version)};
+ const BIN = ${JSON.stringify(o.bin)};
+ const ARGS = ${JSON.stringify(o.args)};
+ const withFileLock = ${withFileLock.toString()};
+ const withLock = (task) => { try { withFileLock(\`\${CFG}.lock\`, fs, task); } catch (e) {} };
+ const alive = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; } };
+ // Stale = no heartbeat for staleMs on this process's own clock, which stops while the machine sleeps.
+ const seen = new Map();
+ const mono = () => Number(process.hrtime.bigint() / 1000000n);
+ const observe = (file) => {
+ let mtime;
+ try { mtime = fs.statSync(file).mtimeMs; } catch (e) { return "stale"; }
+ const prev = seen.get(file);
+ if (prev && prev.mtime === mtime) return mono() - prev.at >= ${o.staleMs} ? "stale" : "quiet";
+ seen.set(file, { mtime, at: mono() });
+ return prev ? "beating" : "quiet";
+ };
+ const touch = (file) => { try { const now = new Date(); fs.utimesSync(file, now, now); } catch (e) {} };
+ const running = () => {
+ let names = [];
+ try { names = fs.readdirSync(RUNNING); } catch (e) {}
+ return names.filter((name) => {
+ const pid = Number(name);
+ const file = join(RUNNING, name);
+ if (Number.isInteger(pid) && pid > 0 && alive(pid) && observe(file) !== "stale") return true;
+ try { fs.unlinkSync(file); } catch (e) {}
+ return false;
+ });
+ };
+ let lockBeat;
+ const ownsLock = () => { try { return Number(readFileSync(INSTALL_LOCK, "utf-8")) === process.pid; } catch (e) { return false; } };
+ // Under the settings lock, so two installers launched together cannot both take it over.
+ const tryLock = () => {
+ let result = "stuck";
+ withLock(() => {
+ let owner = NaN;
+ try { owner = Number(readFileSync(INSTALL_LOCK, "utf-8")); } catch (e) {}
+ const state = Number.isInteger(owner) && owner > 0 && alive(owner) ? observe(INSTALL_LOCK) : "stale";
+ if (state !== "stale") { result = state; return; }
+ writeFileSync(INSTALL_LOCK, String(process.pid));
+ result = "taken";
+ });
+ return result;
+ };
+ const releaseInstallLock = () => {
+ clearInterval(lockBeat);
+ if (ownsLock()) { try { fs.unlinkSync(INSTALL_LOCK); } catch (e) {} }
+ };
+ const install = () => execFile(BIN, ARGS, { windowsHide: true, maxBuffer: 4 * 1024 * 1024 }, (err, _stdout, stderr) => {
+ withLock(() => {
+ let cfg = {};
+ try { cfg = JSON.parse(readFileSync(CFG, "utf-8")); } catch (e) { if (e.code !== "ENOENT") return; }
+ cfg.completedUpdate = {
+ version: VERSION,
+ ok: !err,
+ finishedAt: new Date().toISOString(),
+ ...(err ? { error: String(stderr || err.message || "install failed").slice(-400) } : {}),
+ };
+ delete cfg.pendingUpdate;
+ try {
+ writeFileSync(TMP, JSON.stringify(cfg, null, 2) + "\\n", { mode: 0o600 });
+ renameSync(TMP, CFG);
+ } catch (e) {}
+ });
+ releaseInstallLock();
+ });
+ const started = Date.now();
+ let lastPoll = Date.now();
+ const waitThenInstall = () => {
+ if (!ownsLock()) return releaseInstallLock();
+ // A long gap between polls means the machine slept: watch every file afresh.
+ if (Date.now() - lastPoll > ${o.pollMs} * 5) seen.clear();
+ lastPoll = Date.now();
+ if (running().length === 0) return install();
+ if (Date.now() - started > ${o.maxWaitMs}) {
+ console.log(\`[wait] gave up on \${VERSION}: a hyperframes process is still running\`);
+ return releaseInstallLock();
+ }
+ setTimeout(waitThenInstall, ${o.pollMs});
+ };
+ const acquire = () => {
+ const result = tryLock();
+ if (result === "taken") {
+ lockBeat = setInterval(() => ownsLock() && touch(INSTALL_LOCK), ${o.pollMs});
+ return waitThenInstall();
+ }
+ if (result === "quiet") return setTimeout(acquire, ${o.pollMs});
+ console.log(result === "beating"
+ ? \`[wait] another installer is already waiting; leaving \${VERSION} to it\`
+ : \`[wait] settings lock busy; \${VERSION} left for the next run\`);
+ };
+ acquire();
+ `;
+}
+
/**
* Spawn a detached child to run the install command. Stdout/stderr land in
* the log file; the child is `unref()`d so the parent exits immediately
@@ -83,41 +206,16 @@ function launchDetachedInstall(
mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
const configFile = join(CONFIG_DIR, "config.json");
- // The child script:
- // 1. Runs the install via execFile (bin + argv, NO shell) so a version
- // string can never be re-interpreted as shell syntax — structural
- // symmetry with the interactive `runDetectedInstall` path.
- // 2. Under the shared settings lock (withFileLock, embedded as source), rewrites the config with
- // completedUpdate and clears pendingUpdate; skips on lock timeout or an unreadable file.
- // We run it through `node -e` so we don't need to ship a separate file. Bin
- // and args are embedded as JSON literals (data, not code).
- const nodeScript = `
- const { execFile } = require("node:child_process");
- const fs = require("node:fs");
- const { readFileSync, renameSync, writeFileSync } = fs;
- const CFG = ${JSON.stringify(configFile)};
- const TMP = \`\${CFG}.tmp\`;
- const VERSION = ${JSON.stringify(version)};
- const BIN = ${JSON.stringify(invocation.bin)};
- const ARGS = ${JSON.stringify(invocation.args)};
- const withFileLock = ${withFileLock.toString()};
- const withLock = (task) => { try { withFileLock(\`\${CFG}.lock\`, fs, task); } catch (e) {} };
- execFile(BIN, ARGS, { windowsHide: true, maxBuffer: 4 * 1024 * 1024 }, (err, _stdout, stderr) => withLock(() => {
- let cfg = {};
- try { cfg = JSON.parse(readFileSync(CFG, "utf-8")); } catch (e) { if (e.code !== "ENOENT") return; }
- cfg.completedUpdate = {
- version: VERSION,
- ok: !err,
- finishedAt: new Date().toISOString(),
- ...(err ? { error: String(stderr || err.message || "install failed").slice(-400) } : {}),
- };
- delete cfg.pendingUpdate;
- try {
- writeFileSync(TMP, JSON.stringify(cfg, null, 2) + "\\n", { mode: 0o600 });
- renameSync(TMP, CFG);
- } catch (e) {}
- }));
- `;
+ const nodeScript = installerScript({
+ configFile,
+ version,
+ bin: invocation.bin,
+ args: invocation.args,
+ runningDir: RUNNING_DIR,
+ pollMs: INSTALL_POLL_MS,
+ maxWaitMs: INSTALL_MAX_WAIT_MS,
+ staleMs: RUNNING_STALE_MS,
+ });
const out = openSync(LOG_FILE, "a", 0o600);
const child = spawn(process.execPath, ["-e", nodeScript], {
@@ -130,12 +228,7 @@ function launchDetachedInstall(
log(`[launch] pid=${child.pid ?? "?"} cmd=${displayCommand} version=${version}`);
}
-/**
- * If a new version is available and policy allows, kick off a detached
- * installer. Returns whether an install was spawned (for tests).
- */
-export function scheduleBackgroundInstall(latestVersion: string, currentVersion: string): boolean {
- if (isAutoInstallDisabled()) return false;
+function isSilentUpgrade(latestVersion: string, currentVersion: string): boolean {
if (!latestVersion || !currentVersion) return false;
let cmp: number;
@@ -155,6 +248,16 @@ export function scheduleBackgroundInstall(latestVersion: string, currentVersion:
log(`[skip] major-bump ${currentVersion} -> ${latestVersion}`);
return false;
}
+ return true;
+}
+
+/**
+ * If a new version is available and policy allows, kick off a detached
+ * installer. Returns whether an install was spawned (for tests).
+ */
+export function scheduleBackgroundInstall(latestVersion: string, currentVersion: string): boolean {
+ if (isAutoInstallDisabled()) return false;
+ if (!isSilentUpgrade(latestVersion, currentVersion)) return false;
const installer = detectInstaller();
if (installer.kind === "skip") {
diff --git a/packages/cli/src/utils/runningCli.test.ts b/packages/cli/src/utils/runningCli.test.ts
new file mode 100644
index 0000000000..f977069e1b
--- /dev/null
+++ b/packages/cli/src/utils/runningCli.test.ts
@@ -0,0 +1,38 @@
+import { existsSync, mkdtempSync, rmSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, expect, it } from "vitest";
+import { registerRunningCli } from "./runningCli.js";
+
+let dir = "";
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+it("marks this process as running until it exits", () => {
+ dir = mkdtempSync(join(tmpdir(), "hf-running-"));
+ const before = process.listeners("exit");
+ registerRunningCli(join(dir, "running"));
+ const file = join(dir, "running", String(process.pid));
+ expect(existsSync(file)).toBe(true);
+
+ const added = process.listeners("exit").filter((listener) => !before.includes(listener));
+ for (const listener of added) {
+ listener(0);
+ process.off("exit", listener);
+ }
+ expect(existsSync(file)).toBe(false);
+});
+
+it("rewrites the file on each heartbeat, so a removed file comes back", async () => {
+ dir = mkdtempSync(join(tmpdir(), "hf-running-"));
+ const before = process.listeners("exit");
+ registerRunningCli(join(dir, "running"), 20);
+ const file = join(dir, "running", String(process.pid));
+ unlinkSync(file);
+ await new Promise((resolve) => setTimeout(resolve, 200));
+ expect(existsSync(file)).toBe(true);
+
+ for (const listener of process.listeners("exit").filter((l) => !before.includes(l))) {
+ listener(0);
+ process.off("exit", listener);
+ }
+});
diff --git a/packages/cli/src/utils/runningCli.ts b/packages/cli/src/utils/runningCli.ts
new file mode 100644
index 0000000000..538c955381
--- /dev/null
+++ b/packages/cli/src/utils/runningCli.ts
@@ -0,0 +1,39 @@
+import { mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** One empty file per live CLI process, named by pid; the background installer waits until none is alive. */
+export const RUNNING_DIR = join(homedir(), ".hyperframes", "running");
+const RUNNING_HEARTBEAT_MS = 30_000;
+export const RUNNING_STALE_MS = 10 * 60_000;
+
+/** Mark this process as running until it exits. Never throws: a failed write only lets an update land sooner. */
+export function registerRunningCli(
+ dir: string = RUNNING_DIR,
+ heartbeatMs: number = RUNNING_HEARTBEAT_MS,
+): void {
+ try {
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
+ const file = join(dir, String(process.pid));
+ writeFileSync(file, "", { mode: 0o600 });
+ const heartbeat = setInterval(() => {
+ try {
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
+ writeFileSync(file, String(Date.now()), { mode: 0o600 });
+ } catch {
+ /* best-effort */
+ }
+ }, heartbeatMs);
+ heartbeat.unref();
+ process.on("exit", () => {
+ clearInterval(heartbeat);
+ try {
+ unlinkSync(file);
+ } catch {
+ /* already gone */
+ }
+ });
+ } catch {
+ /* best-effort */
+ }
+}