insta 0.0.47 → 0.0.49

package/dist/commands/manifest.js

@@ -1,5 +1,28 @@
 import { ApiClient, requireProject } from '../api.js';
 import { info, printJson } from '../util.js';
+/**
+ * The label that names WHERE a resource runs.
+ *
+ * `kind` is the platform's internal resource kind, and for compute it is always 'fly' — 'fly' is
+ * the compute SEAT, occupied by the microvm plane on any environment that has cut over. Printing
+ * it is how `insta manifest` came to tell users and agents that a microvm-backed service ran on
+ * Fly (staging, 2026-08-25: `fly(api)` for a row serving from warm pod insta-warm-00178a-16).
+ *
+ * So for compute rows the label is the platform's explicit `provider`, and when that is absent --
+ * an older platform, or a row whose provider the platform itself could not determine -- we fall
+ * back to the neutral 'compute'. That names the resource without asserting a plane: no provider
+ * beats a wrong one. Non-compute kinds keep printing their kind.
+ */
+export function resourceLabel(r) {
+    const kind = r.kind ?? 'resource';
+    const label = kind === 'fly' ? (r.provider === 'fly' || r.provider === 'microvm' ? r.provider : 'compute') : kind;
+    return `${label}${r.name ? `(${r.name})` : ''}`;
+}
+// One `manifest` resource line. Pure, so the label is unit-tested without a network mock.
+export function resourceLine(r) {
+    const where = r.ref?.url ?? r.ref?.bucket ?? r.ref?.neonProjectId ?? '';
+    return `    - ${resourceLabel(r)}  ${where}  [${r.status}]`;
+}
 // Agent-legible view of each environment's databases / storage / compute.
 export async function manifest(opts) {
     const api = await ApiClient.load();
@@ -11,10 +34,8 @@ export async function manifest(opts) {
     for (const b of detail.branches) {
         info(`  branch ${b.name}${b.is_default ? ' *' : ''} [${b.status}]`);
         const rs = detail.resources.filter((r) => r.branchId === b.id || (b.is_default && r.branchId === null));
-        for (const r of rs) {
-            const where = r.ref?.url ?? r.ref?.bucket ?? r.ref?.neonProjectId ?? '';
-            info(`    - ${r.kind}${r.name ? `(${r.name})` : ''}  ${where}  [${r.status}]`);
-        }
+        for (const r of rs)
+            info(resourceLine(r));
     }
 }
 //# sourceMappingURL=manifest.js.map

package/dist/commands/setup.js

@@ -6,18 +6,21 @@
 // Stack skills (tigris/better-auth) intentionally stay per-project: their presence in a
 // project doubles as its stack manifest — that install happens on `project create|link`.
 import { spawn } from 'node:child_process';
-import { closeSync, createReadStream, existsSync, openSync, readFileSync, statSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { closeSync, createReadStream, openSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import os from 'node:os';
 import { createInterface } from 'node:readline';
 import { ApiClient } from '../api.js';
 import { readPersistedGlobal, resolveEnv } from '../config.js';
 import { DEFAULT_ENV, ENVS, ENV_NAMES, envForApiUrl, envFromEnvVar, isEnvName, mcpServerName } from '../env.js';
 import { info } from '../util.js';
+import { isRunnableFile, resolveSpawnable } from '../spawn.js';
 import { loginOauth } from './auth.js';
+import { projectLink } from './project.js';
 import { envUse } from './env.js';
 import { installAgentConfigs } from './mcp.js';
 import { detectChannel } from './upgrade.js';
+export { resolveSpawnable, whichOnPath } from '../spawn.js';
 // The `skills` tool we shell out to prints a clack UI: a frame-by-frame clone spinner, an
 // "Installing to all N agents" banner, a full N-line install-path box, and a third-party
 // "Security Risk Assessment" that flags our OWN first-party skill as "Critical Risk". Streamed
@@ -98,35 +101,6 @@ export function summarizeInstall(output) {
 // access() answers "can THIS process exec it", which for root is always yes, so a root-run
 // setup would wrongly treat a non-executable file as a durable install. On Windows execute
 // permission is extension-driven, so existence of a regular file is the right check.
-const isRunnableFile = (p, win) => {
-    try {
-        const st = statSync(p);
-        if (!st.isFile())
-            return false;
-        return win || (st.mode & 0o111) !== 0;
-    }
-    catch {
-        return false;
-    }
-};
-/** Resolve a bare command name to its absolute PATH location (PATHEXT-aware on Windows).
- *  cmd.exe searches the CURRENT DIRECTORY before PATH for bare names, so handing it a bare
- *  `claude` would let a claude.cmd planted in the project directory shadow the real CLI —
- *  the cmd.exe wrapper below only ever passes absolute paths. */
-export function whichOnPath(bin, env = process.env, platform = process.platform) {
-    const win = platform === 'win32';
-    const exts = win ? [...(env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';'), ''] : [''];
-    for (const dir of (env.PATH ?? '').split(win ? ';' : ':')) {
-        if (!dir)
-            continue;
-        for (const ext of exts) {
-            const p = join(dir, bin + ext);
-            if (isRunnableFile(p, win))
-                return p;
-        }
-    }
-    return null;
-}
 export function findDurableOnPath(bin, env = process.env, platform = process.platform) {
     const win = platform === 'win32';
     const dirs = (env.PATH ?? '').split(win ? ';' : ':');
@@ -181,54 +155,6 @@ export async function ensureCliInstalled(run, channel = detectChannel(), onPath
         info('    (permission error: the npm prefix is system-owned — use a Node version manager, or elevate that one command)');
     }
 }
-// ---- Windows-safe spawning for npm/npx ----
-// On Windows `npm`/`npx` are .cmd shims, which spawn() without a shell refuses (Node docs:
-// spawning .bat/.cmd needs a shell or cmd.exe). Rather than a shell (argument-quoting hazards),
-// re-enter them as node scripts: the CLI script named by npm_execpath (swapped between
-// npm-cli.js and npx-cli.js as needed), else the one shipped beside the running node, else the
-// bare name (POSIX, where PATH shims resolve fine). Applied ONCE, inside the default runner,
-// so every `run('npm'|'npx', …)` call site benefits and nothing is ever resolved twice.
-export function resolveSpawnable(cmd, args, npmExecpath = process.env.npm_execpath, execPath = process.execPath, platform = process.platform, env = process.env) {
-    // Node re-entry is only valid when THIS process runs on node. On the native-binary channel
-    // execPath is the compiled `insta` executable — and npm scripts export npm_execpath to their
-    // children — so re-entering blindly would spawn `insta npx-cli.js …`. A non-node execPath
-    // sends npm/npx down the generic shim path below instead.
-    const execIsNode = /(^|[\\/])node(\.exe)?$/i.test(execPath);
-    if ((cmd === 'npm' || cmd === 'npx') && execIsNode) {
-        if (npmExecpath && /(^|[\\/])np[mx](-cli)?\.[cm]?js$/.test(npmExecpath)) {
-            const cli = npmExecpath.replace(/np[mx](-cli)?(\.[cm]?js)$/, `${cmd}$1$2`);
-            if (existsSync(cli))
-                return { cmd: execPath, args: [cli, ...args] };
-        }
-        const nodeDir = dirname(execPath);
-        const besideNode = platform === 'win32'
-            ? join(nodeDir, 'node_modules', 'npm', 'bin', `${cmd}-cli.js`)
-            : join(nodeDir, '..', 'lib', 'node_modules', 'npm', 'bin', `${cmd}-cli.js`);
-        if (existsSync(besideNode))
-            return { cmd: execPath, args: [besideNode, ...args] };
-    }
-    // Generic shim path — every non-npm CLI we shell out to (claude), plus npm/npx themselves
-    // when node isn't resolvable (native binary channel). On Windows these are .cmd shims, which
-    // spawn() refuses without a shell, so route them through cmd.exe. Guards, in order:
-    // - BARE names only: an absolute path or anything .exe (node.exe from a resolved npm/npx
-    //   invocation passing back through here) is directly spawnable and must NOT see cmd.exe.
-    // - The name is resolved to its ABSOLUTE PATH location first: cmd.exe searches the current
-    //   directory before PATH, so a bare name would let a shim planted in the project dir
-    //   shadow the real CLI. No PATH hit → pass through (spawn fails; callers degrade).
-    // - No manual quoting: libuv already wraps spaced args when building the child command
-    //   line — pre-quoting would be quoted AGAIN and arrive as literal quote characters.
-    // - That leaves cmd.exe metacharacters unprotectable, so an arg carrying one (e.g. a
-    //   custom INSTA_MCP_URL with `&`) skips the wrapper: the bare-shim spawn fails and every
-    //   caller degrades gracefully (probe → not-installed; registration → manual-add
-    //   fallback). Never hand metacharacters to a shell.
-    const bareShim = !/[\\/]/.test(cmd) && !/\.exe$/i.test(cmd);
-    if (platform === 'win32' && bareShim && !args.some((a) => /[&|<>^%"]/.test(a))) {
-        const abs = whichOnPath(cmd, env, platform);
-        if (abs)
-            return { cmd: 'cmd.exe', args: ['/d', '/s', '/c', abs, ...args] };
-    }
-    return { cmd, args };
-}
 // Capture stdout+stderr silently (don't stream) so we can print our own clean summary.
 // stdin is 'ignore', NOT 'inherit': under the canonical `curl … | sh` install, stdin is the
 // piped install script itself — a child that inherits it (npx/skills reads for keypresses even
@@ -424,7 +350,7 @@ export async function setupAgent(opts, run = defaultRunner, mint, installConfigs
     login: () => loginOauth('github', {}),
     stdinTty: canPromptViaTty(),
     stdoutTty: !!process.stdout.isTTY,
-}) {
+}, link = projectLink) {
     if (!opts.yes && !process.stdout.isTTY) {
         info('non-interactive shell — assuming -y');
     }
@@ -485,6 +411,31 @@ export async function setupAgent(opts, run = defaultRunner, mint, installConfigs
             }
         }
     }
+    // --project: link this directory inside the SAME process. The console's connect panel used to
+    // print `setup agent && insta project link <id>` as one paste — but no shell joiner survives
+    // every Windows shell, and in shells without bracketed paste the queued link line is eaten as
+    // the answer to the login prompt above (console PR #290). Carrying the id as a flag is the one
+    // form where "one line" is safe. Linking needs the session: without one the manual command is
+    // the hint, never a hang; a failed link (bad id, no access) is a REAL error — the link is the
+    // entire point of the flag — so it sets the exit code instead of pretending setup succeeded.
+    if (opts.project) {
+        if (!loggedIn) {
+            info(`  not logged in — project not linked; run \`insta login\`, then \`insta project link ${opts.project}\``);
+        }
+        else {
+            try {
+                await link(opts.project);
+            }
+            catch (e) {
+                // Stop here — like the skill-install failure above, finishing with the success summary
+                // and a cheerful `next:` after an error is mixed messaging. Setup itself did succeed,
+                // so say exactly that alongside the retry command.
+                info(`  project link failed (${e instanceof Error ? e.message : String(e)}) — agent setup itself is done; run \`insta project link ${opts.project}\` to retry the link`);
+                process.exitCode = 1;
+                return;
+            }
+        }
+    }
     // THE summary line. The restart note exists because config-file agents only read their MCP
     // config at startup; the skill files need no restart.
     const mcpOk = claude === 'new' || claude === 'existing' || others.length > 0;

package/dist/commands/upgrade.js

@@ -1,19 +1,43 @@
 // Self-update: `insta upgrade` updates the CLI in place, channel-aware (native binary via the
-// release installer; npm via `npm i -g`). A background version check (detached, cached 24h in
+// release installer; npm via `npm i -g`). A background version check (detached, cached in
 // ~/.insta/update-check.json) powers an update nudge — and, since the CLI is young and moves
-// fast, AUTO-UPDATE IS ON BY DEFAULT: when a newer version is known, the next invocation spawns
-// a quiet detached upgrade. `insta autoupdate off` (or INSTA_NO_AUTOUPDATE=1) disables that,
-// leaving just the stderr nudge.
+// fast, AUTO-UPDATE IS ON BY DEFAULT: when a newer version is known, a quiet upgrade runs in the
+// background. `insta autoupdate off` (or INSTA_NO_AUTOUPDATE=1) disables that, leaving just the
+// stderr nudge.
+//
+// ONE SOURCE OF TRUTH. "What is the latest insta?" is answered in exactly one place —
+// `resolveLatest()`, reading npm's `latest` dist-tag, the same thing `npx insta@latest` and
+// `npm i -g insta` resolve. Both the background check and `insta upgrade` go through it, and the
+// binary channel then installs THAT version by tag (INSTA_VERSION=v<latest>) rather than asking
+// GitHub independently for /releases/latest. Two independent resolvers is how the two paths came
+// to disagree; they have drifted before (v0.0.46 was merged but never tagged, so it exists on
+// neither npm nor GitHub).
+//
+// A CACHE MUST NOT LIE. ~/.insta/update-check.json is a cache of that one answer, never a second
+// source. Every path that learns the real latest rewrites it (including a successful upgrade),
+// and any entry that is old, malformed, or behind the running build is refused rather than used
+// — a sticky wrong `latest` is what silently pinned existing installs to an old version.
 import { spawn } from 'node:child_process';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { readGlobal, writeGlobal } from '../config.js';
+import { resolveSpawnable } from '../spawn.js';
 import { info } from '../util.js';
 const INSTALL_SH = 'https://raw.githubusercontent.com/InsForge/insta-cli/main/install.sh';
+// The dist-tag document is the authoritative, tiny (~50 byte) answer for `latest`. The full
+// `latest` manifest is the fallback if that route is ever unavailable.
+const REGISTRY_DIST_TAGS = 'https://registry.npmjs.org/-/package/insta/dist-tags';
 const REGISTRY_LATEST = 'https://registry.npmjs.org/insta/latest';
-const CHECK_TTL_MS = 24 * 60 * 60 * 1000; // re-check the registry at most once a day
-const AUTO_THROTTLE_MS = 60 * 60 * 1000; //  don't respawn a failed auto-upgrade more than hourly
+// Re-check at most this often. Deliberately short: releases ship every day or two, so a TTL
+// measured in days strands every existing install whenever a release lands just after a check.
+export const CHECK_TTL_MS = 3 * 60 * 60 * 1000;
+const AUTO_THROTTLE_MS = 60 * 60 * 1000; //  don't retry a failed auto-upgrade more than hourly
+const FETCH_TIMEOUT_MS = 5000;
+export function resolveRunSpec(spec, npmExecpath = spec.env.npm_execpath, execPath = process.execPath, platform = process.platform) {
+    const resolved = resolveSpawnable(spec.cmd, spec.args, npmExecpath, execPath, platform, spec.env);
+    return { ...spec, ...resolved };
+}
 const cachePath = () => process.env.INSTA_UPDATE_CACHE ?? join(homedir(), '.insta', 'update-check.json');
 // How is this CLI running? Bun standalone → execPath IS the insta binary (not node);
 // npm global → the module lives under node_modules; anything else is a source checkout.
@@ -24,17 +48,110 @@ export function detectChannel(execPath = process.execPath, moduleUrl = import.me
         return 'npm';
     return 'source';
 }
-// -1 / 0 / 1 for a<b / a==b / a>b on dotted numeric versions ("0.0.4" style).
+// A publishable, non-prerelease version. Anything carrying a `-suffix` (0.0.23-rc.1 — the `next`
+// dist-tag today) is not a stable release and must never be offered as "latest".
+const STABLE_VERSION_RE = /^\d+\.\d+\.\d+(?:\+[0-9A-Za-z.-]+)?$/;
+export function isStableVersion(v) {
+    return typeof v === 'string' && STABLE_VERSION_RE.test(v.trim().replace(/^v/, ''));
+}
+function parseVersion(v) {
+    const noBuild = String(v ?? '')
+        .trim()
+        .replace(/^v/, '')
+        .split('+')[0] ?? '';
+    const dash = noBuild.indexOf('-');
+    const coreStr = dash === -1 ? noBuild : noBuild.slice(0, dash);
+    const preStr = dash === -1 ? '' : noBuild.slice(dash + 1);
+    return {
+        core: coreStr.split('.').map((n) => {
+            const p = parseInt(n, 10);
+            return Number.isFinite(p) ? p : 0;
+        }),
+        pre: preStr ? preStr.split('.') : [],
+    };
+}
+// -1 / 0 / 1 for a<b / a==b / a>b, by semver precedence: numeric core compare (so 0.0.9 < 0.0.10,
+// which a string compare gets backwards), then a release outranks any prerelease of the same core
+// (1.0.0 > 1.0.0-rc.1), then identifier by identifier.
 export function cmpSemver(a, b) {
-    const pa = a.split('.').map((n) => parseInt(n, 10) || 0);
-    const pb = b.split('.').map((n) => parseInt(n, 10) || 0);
-    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
-        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    const A = parseVersion(a);
+    const B = parseVersion(b);
+    for (let i = 0; i < Math.max(A.core.length, B.core.length); i++) {
+        const d = (A.core[i] ?? 0) - (B.core[i] ?? 0);
         if (d !== 0)
             return d < 0 ? -1 : 1;
     }
+    if (!A.pre.length && !B.pre.length)
+        return 0;
+    if (!A.pre.length)
+        return 1;
+    if (!B.pre.length)
+        return -1;
+    for (let i = 0; i < Math.max(A.pre.length, B.pre.length); i++) {
+        const x = A.pre[i];
+        const y = B.pre[i];
+        if (x === undefined)
+            return -1; // a shorter prerelease series ranks lower
+        if (y === undefined)
+            return 1;
+        const nx = /^\d+$/.test(x);
+        const ny = /^\d+$/.test(y);
+        if (nx && ny) {
+            const d = parseInt(x, 10) - parseInt(y, 10);
+            if (d !== 0)
+                return d < 0 ? -1 : 1;
+            continue;
+        }
+        if (nx !== ny)
+            return nx ? -1 : 1; // numeric identifiers rank lower than alphanumeric
+        if (x !== y)
+            return x < y ? -1 : 1;
+    }
     return 0;
 }
+// Pick `latest` — and only `latest` — out of npm's dist-tag document. `next` (a prerelease
+// channel: 0.0.23-rc.1 today) must never win, and a `latest` that is itself a prerelease or
+// malformed is refused rather than guessed at.
+export function pickLatestDistTag(tags) {
+    const v = tags?.latest;
+    if (!isStableVersion(v))
+        return null;
+    return v.trim().replace(/^v/, '');
+}
+async function getJson(url, fetchImpl, timeoutMs) {
+    try {
+        const ctl = new AbortController();
+        const t = setTimeout(() => ctl.abort(), timeoutMs);
+        try {
+            // no-cache: an intermediary serving a stale dist-tag would re-create the very bug this
+            // resolver exists to kill.
+            const res = await fetchImpl(url, {
+                signal: ctl.signal,
+                headers: { accept: 'application/json', 'cache-control': 'no-cache' },
+            });
+            if (!res.ok)
+                return null;
+            return (await res.json());
+        }
+        finally {
+            clearTimeout(t);
+        }
+    }
+    catch {
+        return null;
+    }
+}
+// THE resolver: the live latest published version, or null when the registry can't be reached.
+// Never consults the cache — callers decide whether a cached answer may stand in for this.
+export async function resolveLatest(fetchImpl = fetch, timeoutMs = FETCH_TIMEOUT_MS) {
+    const tags = await getJson(REGISTRY_DIST_TAGS, fetchImpl, timeoutMs);
+    const fromTags = pickLatestDistTag(tags);
+    if (fromTags)
+        return fromTags;
+    const manifest = await getJson(REGISTRY_LATEST, fetchImpl, timeoutMs);
+    const v = manifest?.version;
+    return isStableVersion(v) ? v.trim().replace(/^v/, '') : null;
+}
 export function readCache() {
     try {
         return JSON.parse(readFileSync(cachePath(), 'utf8'));
@@ -47,9 +164,25 @@ export function writeCache(c) {
     mkdirSync(dirname(cachePath()), { recursive: true });
     writeFileSync(cachePath(), JSON.stringify(c));
 }
+// May this cached answer stand in for a live registry call? An entry that is old, malformed, or
+// provably behind the build we are running must not suppress the check — that is exactly how a
+// wrong `latest` pins an install to an old version indefinitely. Note the deliberate `>= 0`:
+// `latest === current` is the ordinary up-to-date state and stays cacheable for the TTL, while a
+// `latest` BELOW the running build (an out-of-band upgrade happened) is refused outright.
+export function cacheIsFresh(cache, current, now = Date.now()) {
+    if (!cache || !isStableVersion(cache.latest))
+        return false;
+    if (!Number.isFinite(cache.checkedAt))
+        return false;
+    if (now < cache.checkedAt)
+        return false; // clock went backwards — don't trust the stamp
+    if (now - cache.checkedAt > CHECK_TTL_MS)
+        return false;
+    return cmpSemver(cache.latest, current) >= 0;
+}
 // Pure decision for what start-up should do given the cache. Exported for tests.
 export function decideAction(cache, current, autoUpdate, channel, now = Date.now()) {
-    if (!cache || cmpSemver(cache.latest, current) <= 0)
+    if (!cache || !isStableVersion(cache.latest) || cmpSemver(cache.latest, current) <= 0)
         return 'none';
     if (!autoUpdate || channel === 'source')
         return 'nudge';
@@ -57,46 +190,145 @@ export function decideAction(cache, current, autoUpdate, channel, now = Date.now
         return 'nudge';
     return 'auto';
 }
+// Is auto-update on? (env kill-switch wins, then the persisted preference, default on.)
+export function autoEnabled(home = homedir()) {
+    if (process.env.INSTA_NO_AUTOUPDATE)
+        return false;
+    try {
+        // config read is async elsewhere; a tiny sync read keeps start-up non-blocking
+        const raw = JSON.parse(readFileSync(join(home, '.insta', 'config.json'), 'utf8'));
+        return raw.autoUpdate !== false;
+    }
+    catch {
+        return true; // no config yet
+    }
+}
+const spawnRun = ({ cmd, args, env }) => new Promise((resolve, reject) => {
+    const resolved = resolveRunSpec({ cmd, args, env });
+    const p = spawn(resolved.cmd, resolved.args, { stdio: 'inherit', env });
+    p.on('error', reject);
+    p.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`upgrade failed (exit ${code})`))));
+});
+const observeInstalled = (channel, installDir) => new Promise((resolve) => {
+    const cmd = channel === 'binary' ? join(installDir, 'insta') : 'insta';
+    let out = '';
+    try {
+        // INSTA_NO_AUTOUPDATE: the child must not kick off yet another upgrade while we are reading it.
+        const env = { ...process.env, INSTA_NO_AUTOUPDATE: '1' };
+        const resolved = resolveRunSpec({ cmd, args: ['--version'], env });
+        const p = spawn(resolved.cmd, resolved.args, { stdio: ['ignore', 'pipe', 'ignore'], env });
+        p.stdout.on('data', (d) => (out += String(d)));
+        p.on('error', () => resolve(null));
+        p.on('close', () => {
+            const last = out.trim().split('\n').pop()?.trim().replace(/^v/, '');
+            resolve(isStableVersion(last) ? last : null);
+        });
+    }
+    catch {
+        resolve(null);
+    }
+});
 // `insta upgrade` — synchronous, visible self-update on the detected channel.
-export async function upgrade() {
-    const channel = detectChannel();
+//
+// ALWAYS resolves the target live: an explicitly requested upgrade must never be answered out of
+// ~/.insta/update-check.json, or the documented remedy for a stale cache would itself be stale.
+//
+// NEVER REPORTS A VERSION IT DID NOT OBSERVE. After any install path it reads the installed
+// binary's actual `--version` and prints the transition from THAT. In the drift case (npm's tag
+// ahead of GitHub Releases) the pinned install 404s and the unpinned retry legitimately exits 0
+// having installed nothing — the honest line is "still 0.0.45", not "upgraded → 0.0.47". The
+// cache is rewritten from the observed version too: it then says the newest version THIS channel
+// can actually install, and the start-up nudge stops advertising a build the user cannot get.
+export async function upgrade(current, deps = {}) {
+    const say = deps.report ?? info;
+    const channel = deps.channel ?? detectChannel();
     if (channel === 'source') {
-        info('running from a source checkout — `git pull` to update');
+        say('running from a source checkout — `git pull` to update');
+        return;
+    }
+    const latest = deps.latest !== undefined ? deps.latest : await resolveLatest(deps.fetchImpl ?? fetch);
+    const now = deps.now ?? Date.now();
+    if (latest) {
+        // Record what we just learned so the start-up nudge can't keep quoting a stale answer.
+        writeCache({ ...(readCache() ?? { checkedAt: 0, latest }), checkedAt: now, latest });
+        if (cmpSemver(latest, current) <= 0) {
+            say(`✓ insta ${current} is already the latest release — nothing to upgrade`);
+            return;
+        }
+    }
+    else {
+        say('could not reach the npm registry — installing the newest release available');
+    }
+    say(`upgrading insta ${current} → ${latest ?? 'latest'} via ${channel} …`);
+    const run = deps.run ?? spawnRun;
+    const installDir = deps.installDir ?? dirname(process.execPath);
+    if (channel === 'npm') {
+        await run({ cmd: 'npm', args: ['install', '-g', `insta@${latest ?? 'latest'}`], env: process.env });
+    }
+    else {
+        const shellEnv = { ...process.env, INSTA_INSTALL_DIR: installDir };
+        const sh = { cmd: 'sh', args: ['-c', `curl -fsSL ${INSTALL_SH} | sh`] };
+        if (!latest) {
+            await run({ ...sh, env: shellEnv });
+        }
+        else {
+            try {
+                // Pin the binary install to the EXACT version npm's `latest` dist-tag names, so the two
+                // channels cannot land on different builds.
+                await run({ ...sh, env: { ...shellEnv, INSTA_VERSION: `v${latest}` } });
+            }
+            catch (e) {
+                // Release assets can lag the npm tag. Retry unpinned so the user at least gets the newest
+                // binary that IS published — and let the observation below say what that turned out to be.
+                say(`pinned install of v${latest} failed (${e.message}) — retrying with the newest published release`);
+                await run({ ...sh, env: shellEnv });
+            }
+        }
+    }
+    // Report only what is actually on disk now. The installer prints its own generic onboarding
+    // banner and can exit 0 without changing anything, so its exit code proves nothing.
+    const observed = await (deps.observe ?? observeInstalled)(channel, installDir);
+    if (!observed) {
+        say(`insta install finished, but the installed version could not be read — run \`insta --version\` to confirm`);
         return;
     }
-    info(`upgrading insta via ${channel} …`);
-    let cmd;
-    let args;
-    let env = process.env;
+    writeCache({ ...(readCache() ?? { checkedAt: 0, latest: observed }), checkedAt: now, latest: observed });
+    if (cmpSemver(observed, current) > 0) {
+        say(`✓ insta upgraded ${current} → ${observed}`);
+        return;
+    }
+    const target = latest ?? 'the newest release';
     if (channel === 'binary') {
-        cmd = 'sh';
-        args = ['-c', `curl -fsSL ${INSTALL_SH} | sh`];
-        env = { ...process.env, INSTA_INSTALL_DIR: dirname(process.execPath) };
+        say(`insta is still ${observed} — the newest release (${target}) is published on npm but its binary assets are not on GitHub Releases yet; ` +
+            `try again later or install via npm (npm i -g insta@latest)`);
     }
     else {
-        cmd = 'npm';
-        args = ['install', '-g', 'insta@latest'];
+        say(`insta is still ${observed} — npm reports ${target} as latest but the install did not change the version; try again later`);
     }
-    await new Promise((resolve, reject) => {
-        const p = spawn(cmd, args, { stdio: 'inherit', env });
-        p.on('error', reject);
-        p.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`upgrade failed (exit ${code})`))));
-    });
 }
-// Hidden `insta __update-check` — runs detached in the background: fetch latest, refresh cache.
-export async function backgroundCheck() {
+// Hidden `insta __update-check` — runs detached in the background: resolve latest, refresh the
+// cache, and ACT on what it just learned. Acting here (rather than only priming the cache for
+// some later invocation) is what stops a release that lands just after a check from stranding the
+// install for a whole TTL plus one more run.
+export async function backgroundCheck(current, deps = {}) {
+    const latest = await resolveLatest(deps.fetchImpl ?? fetch);
+    if (!latest)
+        return 'none'; // offline / registry down — try again next TTL
+    const now = deps.now ?? Date.now();
+    const cache = { ...(readCache() ?? { checkedAt: 0, latest }), checkedAt: now, latest };
+    writeCache(cache);
+    const channel = deps.channel ?? detectChannel();
+    const action = decideAction(cache, current, deps.auto ?? autoEnabled(), channel, now);
+    if (action !== 'auto')
+        return action;
+    writeCache({ ...cache, lastAutoAt: now });
     try {
-        const ctl = new AbortController();
-        const t = setTimeout(() => ctl.abort(), 5000);
-        const res = await fetch(REGISTRY_LATEST, { signal: ctl.signal });
-        clearTimeout(t);
-        if (!res.ok)
-            return;
-        const { version } = (await res.json());
-        if (version)
-            writeCache({ ...(readCache() ?? { checkedAt: 0, latest: '0.0.0' }), checkedAt: Date.now(), latest: version });
+        await (deps.runUpgrade ?? ((c, l) => upgrade(c, { latest: l, channel })))(current, latest);
+    }
+    catch {
+        /* best-effort; the hourly throttle retries */
     }
-    catch { /* offline / registry down — try again next TTL */ }
+    return 'auto';
 }
 // `insta autoupdate [on|off]` — toggle / show the auto-update preference (default: on).
 export async function autoupdate(mode) {
@@ -117,23 +349,17 @@ export function maybeUpdate(current, argv) {
         return;
     const channel = detectChannel();
     const cache = readCache();
-    // keep the cache fresh (detached; survives this process exiting)
-    if (!cache || Date.now() - cache.checkedAt > CHECK_TTL_MS) {
+    const now = Date.now();
+    // Re-resolve unless the cached answer is genuinely usable (fresh, well-formed, not behind us).
+    // The child refreshes the cache AND performs the upgrade if one is due.
+    if (!cacheIsFresh(cache, current, now))
         respawnDetached(['__update-check']);
-    }
-    let auto = !process.env.INSTA_NO_AUTOUPDATE;
-    try { // config read is async elsewhere; a tiny sync read keeps start-up non-blocking
-        const raw = JSON.parse(readFileSync(join(homedir(), '.insta', 'config.json'), 'utf8'));
-        if (raw.autoUpdate === false)
-            auto = false;
-    }
-    catch { /* no config yet */ }
-    const action = decideAction(cache, current, auto, channel);
+    const action = decideAction(cache, current, autoEnabled(), channel, now);
     if (action === 'nudge') {
         console.error(`↑ insta ${cache.latest} is available (you have ${current}) — run \`insta upgrade\``);
     }
     else if (action === 'auto') {
-        writeCache({ ...cache, lastAutoAt: Date.now() });
+        writeCache({ ...cache, lastAutoAt: now });
         respawnDetached(['upgrade']);
         console.error(`↑ auto-updating insta ${current} → ${cache.latest} in the background (\`insta autoupdate off\` to disable)`);
     }
@@ -146,6 +372,8 @@ function respawnDetached(args) {
         const p = spawn(process.execPath, argv, { detached: true, stdio: 'ignore' });
         p.unref();
     }
-    catch { /* best-effort */ }
+    catch {
+        /* best-effort */
+    }
 }
 //# sourceMappingURL=upgrade.js.map