great-cto 2.78.0 → 2.80.0

package/board/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "great_cto",
   "id": "great_cto",
   "description": "Engineering process for solo founders and teams up to 50 engineers. Agents do architecture, code review, QA, and security. You make two decisions per feature.",
-  "version": "2.78.0",
+  "version": "2.80.0",
   "author": {
     "name": "Great CTO",
     "url": "https://github.com/avelikiy/great_cto"

package/board/packages/board/lib/alerts.mjs

@@ -6,7 +6,7 @@ import {
   loadSubscriptions,
   removeSubscription,
 } from '../push-adapter.mjs';
-import { GREAT_CTO_DIR, PUSH_SUBS_FILE, VAPID_KEYS_FILE, VAPID_SUBJECT } from './config.mjs';
+import { GREAT_CTO_DIR, PUSH_SUBS_FILE, VAPID_KEYS_FILE, VAPID_SUBJECT, BUILD_VERSION } from './config.mjs';
 import { _reportRepublishDedupeSet } from './state.mjs';
 import { listProjects, readProjectMd } from './projects.mjs';
 import { addNotification } from './notifications.mjs';
@@ -16,6 +16,7 @@ import { getTasks } from './beads.mjs';
 import { readVerdicts } from './verdicts.mjs';
 import { isFailure } from './fleet.mjs';
 import { getShareState, toggleShare } from './share.mjs';
+import { checkForRelease, buildUpdatePayload } from './update-alert.mjs';
 import { log } from './log.mjs';
 
 // ── Email alerts (Resend) ─────────────────────────────────────────────────
@@ -134,6 +135,7 @@ async function firePushAlert(eventName, dedupeKey, payload) {
 function startAlertCron() {
   const FIVE_MIN = 5 * 60 * 1000;
   const ONE_HOUR = 60 * 60 * 1000;
+  const ONE_DAY = 24 * 60 * 60 * 1000;
 
   // incident.p0: open P0 task with recent activity (last 24h).
   // Older P0s are existing backlog — surfacing them via email is spam.
@@ -408,7 +410,26 @@ function startAlertCron() {
     } catch (e) { log.warn('cron report.daily failed:', e.message); }
   }, FIVE_MIN);
 
-  log.info('Alert cron started: gate.stale (5min), sla.escalate (5min), connector.health (5min), cost.threshold (1h), digest.daily (Mon–Fri 08:00), digest.weekly (Fri 09:00), report.daily (09:00)');
+  // update.available: daily check for a newer great-cto npm release.
+  // Dedupe key embeds the latest version string (see update-alert.mjs), so a
+  // given release notifies exactly once no matter how many daily ticks pass
+  // while it remains latest — a fresh key is only minted when npm publishes
+  // a newer version. Fails silent offline; skipped entirely when
+  // GREAT_CTO_NO_UPDATE_CHECK=1 (checkForRelease honors the env var itself).
+  setInterval(() => {
+    checkForRelease({
+      currentVersion: BUILD_VERSION,
+      isFired: (dedupeKey) => Boolean(readAlertsFired()[dedupeKey]),
+      notify: (current, latest, dedupeKey) => {
+        const payload = buildUpdatePayload(current, latest);
+        fireEmailAlert('update.available', dedupeKey, payload);
+        addNotification('update.available', payload);
+        firePushAlert('update.available', dedupeKey, payload);
+      },
+    }).catch(e => log.warn('cron update.available failed:', e.message));
+  }, ONE_DAY);
+
+  log.info('Alert cron started: gate.stale (5min), sla.escalate (5min), connector.health (5min), cost.threshold (1h), digest.daily (Mon–Fri 08:00), digest.weekly (Fri 09:00), report.daily (09:00), update.available (24h)');
 }
 
 export { readAlertsFired, writeAlertsFired, fireEmailAlert, firePushAlert, startAlertCron };

package/board/packages/board/lib/update-alert.mjs

@@ -0,0 +1,107 @@
+// Release notification — daily check for a newer great-cto npm release,
+// surfaced through the board's existing notification + push-alert pipeline.
+//
+// Design mirrors the CLI's update-check.ts (same registry endpoint, same
+// zero-dependency approach) but fires through addNotification()/firePushAlert()
+// instead of a stderr hint, since the board is a long-running server, not a
+// one-shot CLI invocation.
+//
+// Registry endpoint: https://registry.npmjs.org/-/package/great-cto/dist-tags
+//   Verified with curl to return only `{"latest":"x.y.z"}`.
+//
+// Dedupe: alerts-fired.json (existing mechanism in alerts.mjs) is keyed by
+// dedupeKey; the key here embeds the latest version string so each new
+// release notifies exactly once, no matter how many daily ticks pass while
+// that version remains the latest.
+//
+// Opt-out: GREAT_CTO_NO_UPDATE_CHECK=1 (same env var as the CLI hint).
+
+const REGISTRY_DIST_TAGS_URL = 'https://registry.npmjs.org/-/package/great-cto/dist-tags';
+const FETCH_TIMEOUT_MS = 3000;
+
+/** Pure function: parse "x.y.z" into a 3-tuple of ints (missing/garbage segments -> 0). */
+function parseSemver(v) {
+  return String(v || '').split('.').map(n => parseInt(n, 10) || 0);
+}
+
+/** Pure function: true when `latest` is strictly newer than `current` (semver order). */
+function isNewerVersion(current, latest) {
+  if (!current || !latest || current === 'unknown') return false;
+  const a = parseSemver(latest);
+  const b = parseSemver(current);
+  for (let i = 0; i < 3; i++) {
+    const d = (a[i] ?? 0) - (b[i] ?? 0);
+    if (d !== 0) return d > 0;
+  }
+  return false;
+}
+
+/** Pure function: the dedupe key for a given latest version — one notification per new release, ever. */
+function updateDedupeKey(latest) {
+  return `update.available:${latest}`;
+}
+
+/** Pure function: build the notification payload for a given current/latest pair. */
+function buildUpdatePayload(current, latest) {
+  return {
+    title: `great_cto v${latest} released (you run v${current})`,
+    body: `A new great-cto release is available. Upgrade with: npx great-cto upgrade`,
+    level: 'info',
+    project: 'great_cto',
+    link: 'https://github.com/avelikiy/great_cto/releases',
+    action: 'View release',
+    kv: { current, latest },
+  };
+}
+
+/** Fetch {latest} from the npm registry. Returns null on any error/timeout/offline — fail-silent by design. */
+async function fetchLatestVersion(fetchFn = fetch) {
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+    try {
+      const res = await fetchFn(REGISTRY_DIST_TAGS_URL, { signal: ctrl.signal });
+      if (!res.ok) return null;
+      const body = await res.json();
+      return typeof body?.latest === 'string' ? body.latest : null;
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run one update check. Injectable deps for testing — no real network calls
+ * or fs/notification side effects when `fetchFn`/`isFired`/`notify` are stubs.
+ *
+ * @param {object} opts
+ * @param {string} opts.currentVersion   BUILD_VERSION from lib/config.mjs
+ * @param {(url: string, init?: object) => Promise<Response>} [opts.fetchFn]
+ * @param {(dedupeKey: string) => boolean} [opts.isFired]   dedupe lookup (alerts-fired.json)
+ * @param {(current: string, latest: string, dedupeKey: string) => void} [opts.notify]
+ *   called once when a newer, undelivered version is found
+ * @returns {Promise<{checked: boolean, latest: string|null, notified: boolean}>}
+ */
+async function checkForRelease({ currentVersion, fetchFn = fetch, isFired = () => false, notify = () => {} }) {
+  if (process.env.GREAT_CTO_NO_UPDATE_CHECK === '1') {
+    return { checked: false, latest: null, notified: false };
+  }
+  const latest = await fetchLatestVersion(fetchFn);
+  if (!latest) return { checked: true, latest: null, notified: false };
+  if (!isNewerVersion(currentVersion, latest)) return { checked: true, latest, notified: false };
+  const dedupeKey = updateDedupeKey(latest);
+  if (isFired(dedupeKey)) return { checked: true, latest, notified: false };
+  notify(currentVersion, latest, dedupeKey);
+  return { checked: true, latest, notified: true };
+}
+
+export {
+  REGISTRY_DIST_TAGS_URL,
+  isNewerVersion,
+  updateDedupeKey,
+  buildUpdatePayload,
+  fetchLatestVersion,
+  checkForRelease,
+};

package/dist/main.js

@@ -21,6 +21,7 @@ import { bootstrap } from "./bootstrap.js";
 import { compileFlow } from "./flow.js";
 import { shouldUseLlmFallback, suggestArchetypeFromLlm } from "./llm-fallback.js";
 import { sendUsagePing, sendInstallPing, telemetrySubcommand, isTelemetryEnabled, computeAnonId } from "./telemetry.js";
+import { checkForUpdate } from "./update-check.js";
 import { findBoardServerPath } from "./board-path.js";
 import { readFileSync, writeFileSync, copyFileSync, chmodSync, mkdirSync, unlinkSync, existsSync as fsExistsSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -54,6 +55,7 @@ function parseArgs(argv) {
         useLlm: false,
         noLlm: false,
         host: null,
+        upgradeSelf: false,
         positional: [],
     };
     const rest = [];
@@ -119,6 +121,8 @@ function parseArgs(argv) {
             args.command = "report";
         else if (a === "upgrade")
             args.command = "upgrade";
+        else if (a === "--self")
+            args.upgradeSelf = true;
         else if (a === "task") {
             args.command = "task";
             args.taskArgs = argv.slice(i + 1);
@@ -355,6 +359,7 @@ ${bold("Usage:")}
   npx great-cto adapt [--dry-run]
   npx great-cto serve [--port 3142]
   npx great-cto upgrade [superpowers|beads]  Re-clone companions to latest tag + re-apply overlays
+  npx great-cto upgrade --self                Upgrade the great-cto CLI itself, in place
   npx great-cto help
   npx great-cto version
 
@@ -385,6 +390,7 @@ ${bold("Upgrade:")}
   great-cto upgrade              Upgrade superpowers + beads to latest, re-apply critic overlays
   great-cto upgrade superpowers  Upgrade superpowers only
   great-cto upgrade beads        Upgrade beads only
+  great-cto upgrade --self       Upgrade the great-cto CLI itself (also: upgrade self)
   ${dim("(Safe to run any time — idempotent if already on latest)")}
 
 ${bold("CI gate:")}
@@ -998,12 +1004,36 @@ function installPrePushHook(projectDir) {
         // Best-effort: hook failure must never block init
     }
 }
-async function runUpgrade(rawArgv) {
+async function runSelfUpgrade() {
+    const { performSelfUpgrade, resolveRunningBinaryPath } = await import("./self-upgrade.js");
+    const currentVersion = getCliVersion();
+    const binaryPath = resolveRunningBinaryPath();
+    log(`${bold("great-cto upgrade --self")} — current version ${cyan(currentVersion)}`);
+    log(dim(`  running binary: ${binaryPath}`));
+    log("");
+    const result = performSelfUpgrade({ currentVersion, binaryPath });
+    if (result.manager === "npx") {
+        log(result.message);
+        return 0;
+    }
+    if (result.exitCode !== 0) {
+        error(result.message);
+        return result.exitCode;
+    }
+    success(result.message);
+    return 0;
+}
+async function runUpgrade(rawArgv, args) {
+    // `upgrade --self` / `upgrade self` — upgrade the CLI itself, not companion plugins.
+    const upgradeIdx = rawArgv.indexOf("upgrade");
+    const firstArgAfterUpgrade = upgradeIdx >= 0 ? rawArgv[upgradeIdx + 1] : undefined;
+    if (args.upgradeSelf || firstArgAfterUpgrade === "self") {
+        return runSelfUpgrade();
+    }
     const { upgradePlugin, upgradeAll } = await import("./upgrade.js");
     const { COMPANION_PLUGINS } = await import("./companion.js");
     // Optional positional: great-cto upgrade [plugin-name]
-    const upgradeIdx = rawArgv.indexOf("upgrade");
-    const pluginArg = upgradeIdx >= 0 ? rawArgv[upgradeIdx + 1] : undefined;
+    const pluginArg = firstArgAfterUpgrade;
     const targetPlugin = pluginArg && !pluginArg.startsWith("--") ? pluginArg : undefined;
     let results;
     if (targetPlugin) {
@@ -1047,6 +1077,18 @@ async function main() {
             });
         }
         catch { /* telemetry never affects the exit */ }
+        // Update hint / prompt — printed after the command's own output, never
+        // blocks on network (reads a local cache; spawns a detached refresh if
+        // stale). May await a single Y/n keystroke for up to 15s, but ONLY when
+        // a newer version is already cached, stderr+stdin are TTYs, and this
+        // version hasn't been prompted before (see shouldPrompt() in
+        // update-check.ts). Excluded automatically for mcp/worker/task via
+        // PROTOCOL_SENSITIVE_COMMANDS inside checkForUpdate — worker/task don't
+        // even route through finish().
+        try {
+            await checkForUpdate({ currentVersion: getCliVersion(), command: args.command });
+        }
+        catch { /* update hint never affects the exit */ }
         process.exit(code);
     };
     // `great-cto telemetry <on|off|status|whoami>` — inspect / toggle, never sends.
@@ -1180,7 +1222,7 @@ async function main() {
     }
     if (args.command === "upgrade") {
         try {
-            const code = await runUpgrade(rawArgv);
+            const code = await runUpgrade(rawArgv, args);
             await finish(code);
         }
         catch (e) {

package/dist/self-upgrade.js

@@ -0,0 +1,156 @@
+/**
+ * self-upgrade.ts — `great-cto upgrade --self` (and `great-cto upgrade self`).
+ *
+ * Upgrades the great-cto CLI itself, in place, by detecting HOW the running
+ * binary was installed and running the matching package-manager command.
+ *
+ * Detection is driven entirely by the resolved (symlinks-followed) path to
+ * the currently-running binary — never by "which npm is on PATH" or similar,
+ * because a machine can have multiple package managers and multiple install
+ * prefixes at once (e.g. a Volta-style toolchain manager alongside a plain
+ * nvm-style Node version manager). The whole point of resolving from
+ * process.argv[1] is to upgrade the exact binary that is actually running,
+ * not just "some" great-cto install found elsewhere on the machine.
+ *
+ * Detection is a pure function (binaryPath: string -> Plan) so it's fully
+ * unit-testable without spawning any process or touching the filesystem.
+ */
+import { realpathSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { sep } from "node:path";
+/**
+ * Pure function: given the resolved path to the running binary, decide which
+ * package manager "owns" it and what command would upgrade it in place.
+ *
+ * Resolution order (first match wins):
+ *   1. npx / npm exec cache            -> no-op (npx always runs latest already)
+ *   2. Volta shim/install directory    -> `volta install great-cto@latest`
+ *   3. pnpm global install directory   -> `pnpm add -g great-cto@latest`
+ *   4. anything else (plain npm/nvm)   -> `npm install -g great-cto@latest --prefix <prefix>`
+ *
+ * `pathSep` is injectable purely so tests can exercise POSIX-style paths
+ * deterministically regardless of the host OS running the test.
+ */
+export function detectInstall(binaryPath, pathSep = sep) {
+    const normalized = binaryPath.split("\\").join("/");
+    // 1. npx / npm exec cache — npx always fetches+runs the latest version on
+    //    every invocation, so there is nothing to "upgrade": the next `npx
+    //    great-cto` already gets the newest release. Installing here would be
+    //    a no-op at best and would litter the npx cache at worst.
+    if (normalized.includes("/_npx/") || normalized.includes("/.npm/_npx/") || /\/\.npm\/[^/]*_cacache/.test(normalized)) {
+        return { manager: "npx", prefix: null, command: null };
+    }
+    // 2. Volta — toolchain manager that shims global installs under ~/.volta
+    //    (real-world installs use the dotfile form ".volta"; match both so the
+    //    detector works against the actual directory Volta creates).
+    if (normalized.includes("/volta/") || normalized.includes("/.volta/")) {
+        return { manager: "volta", prefix: null, command: ["volta", "install", "great-cto@latest"] };
+    }
+    // 3. pnpm — global installs live under a pnpm-managed store/bin directory
+    //    (real-world installs use the dotfile form ".pnpm"/".local/share/pnpm";
+    //    match both bare and dotfile forms for the same reason as Volta above).
+    if (normalized.includes("/pnpm/") || normalized.includes("/.pnpm/")) {
+        return { manager: "pnpm", prefix: null, command: ["pnpm", "add", "-g", "great-cto@latest"] };
+    }
+    // 4. Plain npm (including nvm-style per-version prefixes, and custom
+    //    prefixes like a dotfile-managed toolchain directory). Derive the
+    //    global prefix from the binary path: a global npm bin shim always
+    //    lives at "<prefix>/bin/<name>", so the prefix is the parent of the
+    //    "bin" directory. For nvm-style layouts (~/.nvm/versions/node/vX.Y.Z/bin/great-cto)
+    //    that parent *is* the version's own prefix, which is exactly right —
+    //    npm install -g scoped with --prefix installs into that same version's
+    //    global node_modules, so the binary that's running gets upgraded, not
+    //    some other prefix on the machine.
+    const prefix = derivePrefixFromBinPath(normalized, pathSep);
+    if (prefix) {
+        return { manager: "npm", prefix, command: ["npm", "install", "-g", "great-cto@latest", "--prefix", prefix] };
+    }
+    // Derivation failed (e.g. binary isn't inside a "bin" dir at all) — fall
+    // back to a plain global install and let npm pick whatever prefix is
+    // currently configured (npm config get prefix / NPM_CONFIG_PREFIX).
+    return { manager: "npm", prefix: null, command: ["npm", "install", "-g", "great-cto@latest"] };
+}
+/** …/bin/great-cto -> prefix is the directory above "bin". Returns null if no "bin" segment is found. */
+function derivePrefixFromBinPath(normalizedPath, _pathSep) {
+    const parts = normalizedPath.split("/").filter((p) => p !== "");
+    const binIdx = parts.lastIndexOf("bin");
+    if (binIdx <= 0)
+        return null; // no "bin" dir, or "bin" is the root itself
+    const prefixParts = parts.slice(0, binIdx);
+    const isAbsolute = normalizedPath.startsWith("/");
+    return (isAbsolute ? "/" : "") + prefixParts.join("/");
+}
+/**
+ * Resolve the real (symlinks-followed) path to the currently-running binary.
+ * Exported so callers/tests can compute it once and pass it through.
+ */
+export function resolveRunningBinaryPath(argv1 = process.argv[1] ?? "") {
+    try {
+        return realpathSync(argv1);
+    }
+    catch {
+        return argv1;
+    }
+}
+/**
+ * Perform the actual self-upgrade: run the install command synchronously
+ * with inherited stdio, then verify by spawning the SAME binary path with
+ * --version.
+ *
+ * Never throws — all failure modes are captured in the returned result so
+ * callers can decide the process exit code themselves.
+ */
+export function performSelfUpgrade(opts) {
+    const binaryPath = opts.binaryPath ?? resolveRunningBinaryPath();
+    const spawnFn = opts.spawnFn ?? spawnSync;
+    const plan = detectInstall(binaryPath);
+    if (plan.manager === "npx" || plan.command === null) {
+        return {
+            exitCode: 0,
+            manager: "npx",
+            prefix: null,
+            oldVersion: opts.currentVersion,
+            newVersion: opts.currentVersion,
+            message: "running via npx — npx always fetches the latest release on every run, nothing to upgrade.",
+        };
+    }
+    const [cmd, ...cmdArgs] = plan.command;
+    const installRun = spawnFn(cmd, cmdArgs, { stdio: "inherit" });
+    if (installRun.error) {
+        return {
+            exitCode: 1,
+            manager: plan.manager,
+            prefix: plan.prefix,
+            oldVersion: opts.currentVersion,
+            newVersion: null,
+            message: `self-upgrade failed: could not run '${plan.command.join(" ")}' — ${installRun.error.message}`,
+        };
+    }
+    const installExitCode = installRun.status ?? 1;
+    if (installExitCode !== 0) {
+        return {
+            exitCode: installExitCode,
+            manager: plan.manager,
+            prefix: plan.prefix,
+            oldVersion: opts.currentVersion,
+            newVersion: null,
+            message: `self-upgrade failed: '${plan.command.join(" ")}' exited with code ${installExitCode}`,
+        };
+    }
+    // Verify: spawn the SAME binary path with --version and report old -> new.
+    const verifyRun = spawnFn(process.execPath, [binaryPath, "--version"], { encoding: "utf8" });
+    const newVersion = verifyRun.status === 0 ? (verifyRun.stdout ?? "").trim() || null : null;
+    const prefixNote = plan.prefix ? ` (prefix: ${plan.prefix})` : "";
+    return {
+        exitCode: 0,
+        manager: plan.manager,
+        prefix: plan.prefix,
+        oldVersion: opts.currentVersion,
+        newVersion,
+        message: newVersion
+            ? `upgraded via ${plan.manager}${prefixNote}: ${opts.currentVersion} → ${newVersion}`
+            : `install via ${plan.manager}${prefixNote} succeeded, but could not verify the new version (--version check failed)`,
+    };
+}
+// Re-export for callers that only need the prefix-derivation logic directly.
+export { derivePrefixFromBinPath as _derivePrefixFromBinPath };

package/dist/update-check-worker.js

@@ -0,0 +1,6 @@
+// Standalone entry point for the detached background update-check process.
+// Spawned by update-check.ts (spawnBackgroundCheck) via `node dist/update-check-worker.js`.
+// Deliberately tiny: just calls refreshCache() and exits. stdio is "ignore"
+// from the parent, so nothing here should assume a console is attached.
+import { refreshCache } from "./update-check.js";
+await refreshCache();

package/dist/update-check.js

@@ -0,0 +1,323 @@
+// Update notifier — classic update-notifier pattern, zero dependency.
+//
+// Design:
+//   - Foreground NEVER waits on the network. It only reads a local cache
+//     file (~/.great_cto/update-check.json) written by a previous run.
+//   - When the cache is missing or stale (>24h), a DETACHED background
+//     process is spawned (node, stdio ignored, unref'd) that hits the npm
+//     registry and refreshes the cache for the *next* invocation to read.
+//   - This means the very first run (and the first run after 24h) never
+//     shows a hint — the hint appears one run later, once the cache is
+//     warm. That's the standard update-notifier trade-off: never block,
+//     never slow down the command the user actually asked for.
+//
+// Registry endpoint: https://registry.npmjs.org/-/package/great-cto/dist-tags
+//   Verified with curl to return only `{"latest":"x.y.z"}` — much smaller
+//   than the full package document (https://registry.npmjs.org/great-cto),
+//   which would pull the entire versions/times history.
+//
+// Privacy: read-only GET against the public npm registry, equivalent to the
+// request `npm install` already performs. No project data, no PII, nothing
+// user-specific is sent. See docs/PRIVACY.md.
+//
+// Opt-out: GREAT_CTO_NO_UPDATE_CHECK=1 (checked by both the foreground read
+// and the background refresh entry point).
+//
+// Interactive prompt: when a newer version is found AND both stderr and
+// stdin are TTYs AND the check isn't suppressed AND this specific version
+// hasn't been prompted for before, checkForUpdate() asks `Update to X? [Y/n]`
+// on stderr with a 15s timeout (node:readline). "Yes" runs the same
+// self-upgrade code path as `great-cto upgrade --self`, in-process. Either
+// way the chosen (or timed-out) version is recorded in the cache file's
+// `promptedFor` field so a given release is prompted for AT MOST ONCE —
+// every later run falls back to the one-line hint.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { semverDescending } from "./semver.js";
+export const REGISTRY_DIST_TAGS_URL = "https://registry.npmjs.org/-/package/great-cto/dist-tags";
+export const CACHE_FRESH_MS = 24 * 60 * 60 * 1000; // 24h
+export const PACKAGE_NAME = "great-cto";
+export const PROMPT_TIMEOUT_MS = 15_000;
+/** Commands where stdout/stderr are machine-parsed — never print a hint, never spawn a check. */
+export const PROTOCOL_SENSITIVE_COMMANDS = new Set([
+    "mcp", // stdio JSON-RPC protocol — any stray byte on stdout/stderr breaks the client
+    "worker", // long-running daemon; status is polled programmatically
+    "task", // machine-invoked task runner (spawned by worker)
+]);
+function defaultCachePath() {
+    return join(homedir(), ".great_cto", "update-check.json");
+}
+/** Resolve the cache file path — GREAT_CTO_HOME lets tests/worker isolate state, same convention as worker.ts/task-queue.ts. */
+export function cachePath() {
+    const base = process.env.GREAT_CTO_HOME || join(homedir(), ".great_cto");
+    return join(base, "update-check.json");
+}
+/** Pure function: is a suppression condition active? Fail-open to "suppressed" on any ambiguity. */
+export function isSuppressed(opts = {}) {
+    const env = opts.env ?? process.env;
+    if (env.CI != null && env.CI !== "" && env.CI !== "0" && env.CI !== "false")
+        return true;
+    if (env.GREAT_CTO_NO_UPDATE_CHECK === "1")
+        return true;
+    if (opts.command && PROTOCOL_SENSITIVE_COMMANDS.has(opts.command))
+        return true;
+    if (opts.stderrIsTTY === false)
+        return true;
+    return false;
+}
+/**
+ * Pure function: should the interactive `Update to X? [Y/n]` prompt fire?
+ *
+ * All of the following must hold:
+ *   - not suppressed (isSuppressed() — reuses the same CI/opt-out/protocol/TTY rules)
+ *   - stdin is ALSO a TTY (isSuppressed only checks stderr; a prompt needs to
+ *     read a keystroke, so a piped/redirected stdin must never block on it)
+ *   - a newer version is actually available
+ *   - this exact `latest` version hasn't already been prompted for
+ *     (cache.promptedFor === latest means "already asked, at most once per release")
+ */
+export function shouldPrompt(opts) {
+    if (isSuppressed({ env: opts.env, command: opts.command, stderrIsTTY: opts.stderrIsTTY }))
+        return false;
+    if (opts.stdinIsTTY !== true)
+        return false;
+    if (!opts.cache)
+        return false;
+    if (!isNewerVersion(opts.currentVersion, opts.cache.latest))
+        return false;
+    if (opts.cache.promptedFor === opts.cache.latest)
+        return false;
+    return true;
+}
+/** Pure function: read + parse cache JSON. Returns null on any error (missing/corrupt). */
+export function readCache(readFileFn = (p) => readFileSync(p, "utf8"), path = cachePath()) {
+    try {
+        const raw = readFileFn(path);
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.checkedAt !== "string" || typeof parsed.latest !== "string")
+            return null;
+        const cache = { checkedAt: parsed.checkedAt, latest: parsed.latest };
+        if (typeof parsed.promptedFor === "string")
+            cache.promptedFor = parsed.promptedFor;
+        return cache;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Pure function: write `promptedFor` into the cache file, preserving the
+ * other fields. Best-effort — swallows write errors (a failed write just
+ * means the prompt might fire again next run, which is safe, not silent
+ * data loss).
+ */
+export function recordPromptedFor(version, readFileFn = (p) => readFileSync(p, "utf8"), writeFileFn = writeFileSync, path = cachePath()) {
+    try {
+        const existing = readCache(readFileFn, path);
+        const cache = existing
+            ? { ...existing, promptedFor: version }
+            : { checkedAt: new Date().toISOString(), latest: version, promptedFor: version };
+        writeFileFn(path, JSON.stringify(cache, null, 2) + "\n");
+    }
+    catch {
+        /* best-effort — never break the CLI over a cache write failure */
+    }
+}
+/** Pure function: is a cache entry still fresh (<24h old)? */
+export function isCacheFresh(cache, now = Date.now(), freshMs = CACHE_FRESH_MS) {
+    if (!cache)
+        return false;
+    const checkedAtMs = Date.parse(cache.checkedAt);
+    if (Number.isNaN(checkedAtMs))
+        return false;
+    return now - checkedAtMs < freshMs;
+}
+/** Pure function: does `latest` represent a newer version than `current`? */
+export function isNewerVersion(current, latest) {
+    if (!current || !latest || current === "unknown")
+        return false;
+    // semverDescending(a, b) < 0 means a > b (descending sort). latest > current => descending(latest, current) < 0.
+    return semverDescending(latest, current) < 0;
+}
+/** Pure function: build the one-line stderr hint text. `styler` lets callers inject color helpers (matches ui.ts). */
+export function formatHint(current, latest, styler = {
+    cyan: (s) => s,
+    dim: (s) => s,
+    bold: (s) => s,
+}) {
+    return `${styler.dim("update available:")} ${styler.dim(current)} ${styler.dim("→")} ${styler.bold(styler.cyan(latest))}  ${styler.dim(`run ${styler.cyan("great-cto upgrade --self")} to upgrade`)}`;
+}
+/**
+ * Ask `question` on stderr and read one line of input from stdin via
+ * node:readline, with a hard timeout. Resolves `true` for an empty/"y"/"Y"
+ * answer, `false` for anything else INCLUDING a timeout or "n". Never
+ * rejects. Only called when both stderr and stdin are already confirmed
+ * TTYs (see shouldPrompt), so this never blocks a piped/CI invocation.
+ *
+ * `input`/`output` are injectable (defaulting to the real process streams)
+ * so tests can exercise real readline behavior — including the timeout —
+ * against isolated streams instead of monkey-patching process.stdin.
+ */
+export function promptYesNo(question, timeoutMs = PROMPT_TIMEOUT_MS, input = process.stdin, output = process.stderr) {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input, output, terminal: false });
+        let settled = false;
+        const finish = (answer) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            rl.close();
+            resolve(answer);
+        };
+        // Intentionally NOT unref'd: this timer is the only thing standing
+        // between "user is deciding" and "give up and fall back to the hint" —
+        // it must keep the event loop alive for up to timeoutMs so the prompt
+        // reliably resolves (and, on success, so recordPromptedFor()/finish()
+        // in main.ts still run). It is always cleared on any resolution path
+        // (answer or timeout), so it never actually blocks exit beyond that.
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        try {
+            rl.question(question, (answer) => {
+                const normalized = answer.trim().toLowerCase();
+                finish(normalized === "" || normalized === "y" || normalized === "yes");
+            });
+        }
+        catch {
+            finish(false);
+        }
+    });
+}
+/**
+ * Foreground entry point. Call once per CLI invocation, after the command's
+ * normal output has been printed. Never throws.
+ *
+ * - If suppressed: no-op.
+ * - If cache is fresh:
+ *     - if a newer version exists and shouldPrompt() says yes, show the
+ *       interactive `Update to X? [Y/n]` prompt (15s timeout) and, on yes,
+ *       run the self-upgrade in-process before returning.
+ *     - otherwise, print the one-line hint (if newer) exactly as before.
+ * - If cache is missing/stale: spawn a detached background refresh and
+ *   return immediately (no hint/prompt this run — the cache isn't warm yet).
+ *
+ * Only the prompt path awaits anything (stdin, up to 15s); every other path
+ * returns synchronously-fast, matching the original never-block guarantee.
+ */
+export async function checkForUpdate(opts) {
+    try {
+        const env = opts.env ?? process.env;
+        const stderrIsTTY = opts.stderrIsTTY ?? Boolean(process.stderr.isTTY);
+        const stdinIsTTY = opts.stdinIsTTY ?? Boolean(process.stdin.isTTY);
+        if (isSuppressed({ env, command: opts.command, stderrIsTTY }))
+            return;
+        const cache = readCache();
+        if (isCacheFresh(cache, opts.now)) {
+            if (!cache || !isNewerVersion(opts.currentVersion, cache.latest))
+                return;
+            if (shouldPrompt({ currentVersion: opts.currentVersion, cache, env, command: opts.command, stderrIsTTY, stdinIsTTY })) {
+                const accepted = await promptYesNo(`Update to ${cache.latest}? [Y/n] `);
+                recordPromptedFor(cache.latest);
+                if (accepted) {
+                    await runSelfUpgradeInProcess(opts.currentVersion);
+                }
+                return;
+            }
+            printHint(opts.currentVersion, cache.latest);
+            return;
+        }
+        spawnBackgroundCheck();
+    }
+    catch {
+        // Fail-silent — an update hint must never break or slow down a real command.
+    }
+}
+/**
+ * Run the same self-upgrade code path as `great-cto upgrade --self`,
+ * in-process, after the user accepted the interactive prompt. Isolated into
+ * its own function (rather than importing self-upgrade.ts at module scope)
+ * so update-check.ts's own unit tests never need to touch child_process.
+ */
+async function runSelfUpgradeInProcess(currentVersion) {
+    try {
+        const { performSelfUpgrade, resolveRunningBinaryPath } = await import("./self-upgrade.js");
+        const binaryPath = resolveRunningBinaryPath();
+        const result = performSelfUpgrade({ currentVersion, binaryPath });
+        process.stderr.write((result.exitCode === 0 ? result.message : `error: ${result.message}`) + "\n");
+    }
+    catch {
+        /* fail-silent — an accepted prompt must never crash the command that triggered it */
+    }
+}
+function printHint(current, latest) {
+    try {
+        // Local, minimal color helpers mirroring ui.ts's NO_COLOR-aware wrap(),
+        // but gated on stderr TTY (ui.ts gates on stdout, which is the wrong
+        // stream for a hint that must print to stderr).
+        const useColor = Boolean(process.stderr.isTTY) && process.env.NO_COLOR !== "1";
+        const wrap = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
+        const styler = { cyan: wrap("36"), dim: wrap("2"), bold: wrap("1") };
+        process.stderr.write(formatHint(current, latest, styler) + "\n");
+    }
+    catch {
+        /* fail-silent */
+    }
+}
+/** Spawn a detached, unref'd background process that refreshes the cache. Never awaited by the caller. */
+function spawnBackgroundCheck() {
+    try {
+        // Test-only escape hatch: unit tests exercise checkForUpdate()'s control
+        // flow (including "cache missing/stale -> spawn") without ever launching
+        // a real child process or touching the network. Never set in production.
+        if (process.env.GREAT_CTO_UPDATE_CHECK_NO_SPAWN === "1")
+            return;
+        const here = dirname(fileURLToPath(import.meta.url));
+        const entry = join(here, "update-check-worker.js");
+        if (!existsSync(entry))
+            return; // dist not built (e.g. running from src in dev) — skip rather than crash
+        const child = spawn(process.execPath, [entry], {
+            detached: true,
+            stdio: "ignore",
+            env: process.env,
+        });
+        child.unref();
+    }
+    catch {
+        /* fail-silent — network/update check is best-effort only */
+    }
+}
+/**
+ * Background worker body — invoked as a standalone script by
+ * update-check-worker.ts. Fetches the registry dist-tags and writes the
+ * cache. Exported so it's independently unit-testable with an injected
+ * fetcher, without needing to actually spawn a child process.
+ */
+export async function refreshCache(fetchFn = fetch, writeFileFn = writeFileSync, mkdirFn = (p) => mkdirSync(p, { recursive: true }), path = cachePath()) {
+    try {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), 3000);
+        let latest;
+        try {
+            const res = await fetchFn(REGISTRY_DIST_TAGS_URL, { signal: ctrl.signal });
+            if (res.ok) {
+                const body = (await res.json());
+                latest = body.latest;
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!latest)
+            return;
+        mkdirFn(dirname(path));
+        const cache = { checkedAt: new Date().toISOString(), latest };
+        writeFileFn(path, JSON.stringify(cache, null, 2) + "\n");
+    }
+    catch {
+        /* offline / registry unreachable — fail-silent, next invocation retries */
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "great-cto",
-  "version": "2.78.0",
+  "version": "2.80.0",
   "description": "One command install for the great_cto Claude Code plugin. Auto-detects your stack, picks the right archetype, bootstraps PROJECT.md.",
   "keywords": [
     "claude-code",