Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
fix(cli): only check for updates when a person is watching (#681)
Ian Hock5dea6674f69e
diff --git a/ix-cli/src/cli/__tests__/update-check-gate.test.ts b/ix-cli/src/cli/__tests__/update-check-gate.test.tsnew file mode 100644index 00000000..59fe267a--- /dev/null+++ b/ix-cli/src/cli/__tests__/update-check-gate.test.ts@@ -0,0 +1,65 @@+// Copyright 2026 Ix Infrastructure Inc.++import { describe, expect, it } from "vitest";++import { updateCheckEnabled } from "../commands/upgrade.js";++/** A terminal session with nothing special set. */+const tty = (argv: string[], env: NodeJS.ProcessEnv = {}) => updateCheckEnabled(argv, env, true);+/** Anything capturing stderr: an agent, a pipe, a CI log. */+const captured = (argv: string[], env: NodeJS.ProcessEnv = {}) => updateCheckEnabled(argv, env, false);++describe("updateCheckEnabled", () => {+ it("runs for an ordinary command at a terminal", () => {+ expect(tty(["status"])).toBe(true);+ expect(tty(["context", "resolveWorkspaceRoot"])).toBe(true);+ });++ it("does not run when stderr is captured", () => {+ // The case that matters: an agent runs `ix <cmd> 2>&1` and the notice+ // lands at the top of every tool result it reads.+ expect(captured(["status"])).toBe(false);+ });++ it("does not run when a machine-readable format was asked for", () => {+ for (const format of ["llm", "json"]) {+ expect(tty(["search", "Widget", "--format", format])).toBe(false);+ expect(tty(["search", "Widget", `--format=${format}`])).toBe(false);+ }+ });++ it("still runs for an explicit --format text", () => {+ expect(tty(["search", "Widget", "--format", "text"])).toBe(true);+ expect(tty(["search", "Widget", "--format=text"])).toBe(true);+ });++ it("leaves the check on when --format has no value to read", () => {+ // commander reports the error; the gate should not guess.+ expect(tty(["search", "Widget", "--format"])).toBe(true);+ });++ it("honours IX_NO_UPDATE_CHECK", () => {+ for (const value of ["1", "true", "TRUE", "yes"]) {+ expect(tty(["status"], { IX_NO_UPDATE_CHECK: value })).toBe(false);+ }+ });++ it("treats an empty or falsy IX_NO_UPDATE_CHECK as unset", () => {+ for (const value of ["", "0", "false", " "]) {+ expect(tty(["status"], { IX_NO_UPDATE_CHECK: value })).toBe(true);+ }+ });++ it("keeps the existing exemptions", () => {+ // `upgrade` reports versions itself; `mcp` speaks JSON-RPC on stdio, where+ // a stray notice is a protocol error.+ expect(tty(["upgrade"])).toBe(false);+ expect(tty(["mcp"])).toBe(false);+ expect(tty(["status"], { IX_MCP_CHILD: "1" })).toBe(false);+ });++ it("does not mistake another flag's value for a format", () => {+ expect(tty(["text", "--format-ish", "json"])).toBe(true);+ expect(tty(["search", "--path", "--format"])).toBe(true);+ });+});diff --git a/ix-cli/src/cli/commands/upgrade.ts b/ix-cli/src/cli/commands/upgrade.tsindex 2c055c7c..d9d2d675 100644--- a/ix-cli/src/cli/commands/upgrade.ts+++ b/ix-cli/src/cli/commands/upgrade.ts@@ -1235,6 +1235,53 @@ function detectPlatform(): string {* Check for updates (non-blocking, cached for 1 hour).* Call this from other commands to notify users.*/+/**+ * Whether the background update check should run for this invocation.+ *+ * The notice it can print is four or five lines on stderr, and it fires on+ * ordinary commands. That is fine for a person at a terminal and wrong for+ * everything else: an agent runs `ix <cmd> 2>&1`, so the notice lands at the+ * top of every tool result it reads, and it led 100% of the `ix` calls in a+ * recorded benchmark. A script or a CI log gets the same treatment.+ *+ * Skipping the check rather than only the print also drops the unawaited+ * network fetch, which is what delays process exit on an otherwise local+ * command.+ *+ * `--format` is read straight from argv because this runs before commander has+ * parsed anything; an unparseable or absent value just leaves the check on.+ */+export function updateCheckEnabled(+ argv: readonly string[],+ env: NodeJS.ProcessEnv,+ stderrIsTerminal: boolean,+): boolean {+ // `upgrade` reports versions itself, and `mcp` speaks JSON-RPC on stdio+ // where a stray notice is a protocol error.+ if (argv[0] === "upgrade" || argv[0] === "mcp") return false;+ if (env.IX_MCP_CHILD === "1") return false;+ if (isTruthyEnv(env.IX_NO_UPDATE_CHECK)) return false;+ if (!stderrIsTerminal) return false;+ const format = requestedFormat(argv);+ if (format !== undefined && format !== "text") return false;+ return true;+}++function isTruthyEnv(value: string | undefined): boolean {+ if (value === undefined) return false;+ const normalized = value.trim().toLowerCase();+ return normalized !== "" && normalized !== "0" && normalized !== "false";+}++function requestedFormat(argv: readonly string[]): string | undefined {+ for (let i = 0; i < argv.length; i += 1) {+ const arg = argv[i];+ if (arg === "--format") return argv[i + 1];+ if (arg !== undefined && arg.startsWith("--format=")) return arg.slice("--format=".length);+ }+ return undefined;+}+export async function checkForUpdate(): Promise<void> {const current = getCurrentVersion();const cache = readCache();diff --git a/ix-cli/src/cli/main.ts b/ix-cli/src/cli/main.tsindex 2a35e39b..e8363896 100644--- a/ix-cli/src/cli/main.ts+++ b/ix-cli/src/cli/main.ts@@ -5,7 +5,8 @@ import { Command } from "commander";import { registerOssCommands, registerProStubs } from "./register/oss.js";import { tryLoadProCommands } from "./register/pro-loader.js";import { buildHelpText } from "./help-text.js";-import { checkForUpdate } from "./commands/upgrade.js";+import { checkForUpdate, updateCheckEnabled } from "./commands/upgrade.js";+import { stderrIsTerminal } from "./stderr.js";import { renderCliError } from "./errors.js";import { getEndpoint } from "./config.js";@@ -85,9 +86,11 @@ registerOssCommands(program);registerProStubs(program);}- // Check for updates (non-blocking, cached 1hr) — skip for upgrade command itself+ // Check for updates (non-blocking, cached 1hr). Only when a person is+ // watching stderr — see updateCheckEnabled for why, and for the+ // IX_NO_UPDATE_CHECK opt-out.const args = process.argv.slice(2);- if (args[0] !== "upgrade" && args[0] !== "mcp" && process.env.IX_MCP_CHILD !== "1") {+ if (updateCheckEnabled(args, process.env, stderrIsTerminal())) {// Deliberately not awaited — but it must still be caught here. The catch// inside checkForUpdate only guards its inner fetch chain; the function's// own promise covers the synchronous cached-read path, and a corruptdiff --git a/ix-cli/src/cli/stderr.ts b/ix-cli/src/cli/stderr.tsindex 13e790b1..eeddbe81 100644--- a/ix-cli/src/cli/stderr.ts+++ b/ix-cli/src/cli/stderr.ts@@ -27,5 +27,15 @@ export function stderrDim(message: string): void {* whatever the first import happened to see.*/export function canRenderProgress(): boolean {+ return stderrIsTerminal();+}++/**+ * Whether stderr is a terminal, i.e. whether anything written there is going to+ * a person watching rather than into a capture.+ *+ * Read at each call, for the reason given on `canRenderProgress`.+ */+export function stderrIsTerminal(): boolean {return Boolean(process.stderr.isTTY);}