impel-cli 0.20.45 → 0.20.46-beta.0

package/src/commands/status.js

@@ -10,10 +10,12 @@ import { findReviewedVendorCliBinary } from "../vendorCliBinaries.js";
 import { windowsTenantShortcutName } from "../shellEntries.js";
 import {
   ensureTenantSelection,
+  normalizeCliUser,
   PAT_SCOPE_CLAUDE,
   PAT_SCOPE_CODEX,
   productAccessLabel,
 } from "../tenants.js";
+import { telemetryNoticeLine } from "../posthog.js";
 import { installedVersion, maybePrintUpdateNotice } from "../updates.js";
 import { findManagedWindowsChatGPTApp, windowsClaudeUserData } from "../windowsApps.js";
 import { RUNTIME_BRAND } from "../runtimeBrand.js";
@@ -85,6 +87,24 @@ function cliState({ supported, available = true, profileReady, binaryReady }) {
   return profileReady && binaryReady ? "ready" : "missing";
 }
 
+/**
+ * Everything `impel status` prints on its way out, from every exit.
+ *
+ * There are three: no PAT, an authentication check that did not come back, and
+ * the full report. The first two are precisely the states a broken install is
+ * in — a notice wired only to the tail would be invisible exactly when someone
+ * runs `status` to find out what is wrong.
+ *
+ * `doctor` deliberately does not carry this. It runs synthetic, billable
+ * end-to-end gateway checks; a local drop notice should not cost a request.
+ */
+function printLocalNotices(io) {
+  if (RUNTIME_BRAND.cli.packageName !== "impel-cli") return;
+  const telemetry = io.telemetryNoticeLine();
+  if (telemetry) console.log(telemetry);
+  io.maybePrintUpdateNotice();
+}
+
 export async function cmdStatus(overrides = {}) {
   const io = {
     loadConfig,
@@ -94,6 +114,7 @@ export async function cmdStatus(overrides = {}) {
     installedVersion,
     findNativeBinary: findReviewedVendorCliBinary,
     maybePrintUpdateNotice,
+    telemetryNoticeLine,
     platform: process.platform,
     environment: process.env,
     ...overrides,
@@ -102,8 +123,12 @@ export async function cmdStatus(overrides = {}) {
   const version = process.env.IMPEL_CLI_EXTENSION_VERSION || io.installedVersion() || "?";
   console.log(`${RUNTIME_BRAND.cli.command}-cli: v${version}`);
   console.log(`Authentication: ${config?.pat ? `configured (${maskSecret(config.pat)})` : "not configured - run `impel setup`"}`);
+  // Read back through the same normalizer that wrote it: config.json is a file
+  // on disk, so what it holds is untrusted input by the time it is printed.
+  const user = normalizeCliUser(config?.user, { allowMissing: true });
+  if (user) console.log(`Signed in as: ${user.displayName || user.id}`);
   if (!config?.pat) {
-    if (RUNTIME_BRAND.cli.packageName === "impel-cli") io.maybePrintUpdateNotice();
+    printLocalNotices(io);
     return;
   }
 
@@ -117,7 +142,7 @@ export async function cmdStatus(overrides = {}) {
     console.log(RUNTIME_BRAND.tenant.defaultId
       ? `Run \`${RUNTIME_BRAND.cli.command} setup\` to refresh authentication and repair the local tenant.`
       : "Run `impel setup` to refresh authentication, then `impel update` to repair local tenants.");
-    if (RUNTIME_BRAND.cli.packageName === "impel-cli") io.maybePrintUpdateNotice();
+    printLocalNotices(io);
     return;
   }
 
@@ -162,5 +187,5 @@ export async function cmdStatus(overrides = {}) {
       ? `Repair or finish missing tenant surfaces with: ${RUNTIME_BRAND.cli.command} setup`
       : "Repair or finish missing tenant surfaces with: impel update");
   }
-  if (RUNTIME_BRAND.cli.packageName === "impel-cli") io.maybePrintUpdateNotice();
+  printLocalNotices(io);
 }

package/src/commands/update.js

@@ -10,6 +10,7 @@ import { loadConfig, redactSecretText } from "../config.js";
 import { nativeCommandInvocation } from "../nativeProcess.js";
 import { withProgress } from "../progress.js";
 import { runInstallRecovery } from "../installRecovery/engine.js";
+import { reportInstallFailure } from "../autoReport.js";
 import { brandedEnvironmentName, brandedText, RUNTIME_BRAND } from "../runtimeBrand.js";
 import { IMPEL_CLI_ENTRYPOINT } from "../selfInvocation.js";
 import {
@@ -252,6 +253,7 @@ export async function cmdUpdate(argv, overrides = {}) {
     environment: process.env,
     progress: withProgress,
     recoverInstall: runInstallRecovery,
+    reportInstallFailure,
     postInstallVersion: postInstallCliVersion,
     postInstallRunnable: postInstallCliRunnable,
     resolveFreshInstall: resolveFreshGlobalEntrypoint,
@@ -315,6 +317,36 @@ export async function cmdUpdate(argv, overrides = {}) {
     return;
   }
 
+  // Read at most once, and only when something actually needs it. All three
+  // terminal failures do, which is why this is not still buried in the npm
+  // branch — but an `impel update` that succeeds must not pay a config read it
+  // has no use for, and this whole feature is supposed to cost the success
+  // path nothing.
+  let configLoaded = false;
+  let configValue;
+  const currentConfig = () => {
+    if (!configLoaded) {
+      configValue = io.loadConfig();
+      configLoaded = true;
+    }
+    return configValue;
+  };
+
+  /**
+   * File one automatic report for a terminal `impel update` failure.
+   *
+   * Each caller has already printed the message the user needs to act on, so
+   * this must not add a second one: `reportInstallFailure` swallows its own
+   * errors and the `catch` covers whatever an injected reporter does (R10).
+   */
+  const reportUpdateFailure = async (failure) => {
+    try {
+      await io.reportInstallFailure({ failure, config: currentConfig(), io });
+    } catch {
+      // R10: one error message, and it is the one the caller already printed.
+    }
+  };
+
   // ── CLI ────────────────────────────────────────────────────────────────
   let cascadeEntrypoint = null;
   if (!remote) {
@@ -340,8 +372,8 @@ export async function cmdUpdate(argv, overrides = {}) {
         console.error("  Verify `npm --version` in PowerShell, then retry `impel update`.");
         console.error(`  Manual recovery: \`npm install --global ${installSpec}\`.`);
       }
-      const config = io.loadConfig();
       let recovered = false;
+      const config = currentConfig();
       if (config?.pat && config?.tenantId) {
         // The goal passes on the most recent reviewed retry of the npm
         // install OR on a live disk probe of the package that owns the
@@ -399,6 +431,19 @@ export async function cmdUpdate(argv, overrides = {}) {
         }
       }
       if (!recovered) {
+        // Past recovery, so this is a failure that ran out of fixes (KTD2).
+        await reportUpdateFailure({
+          scope: "shared",
+          platform: io.platform,
+          architecture: process.arch,
+          step: "install.impel_cli",
+          command: `npm install --global ${installSpec}`,
+          message: `The npm-verified global ${RUNTIME_BRAND.cli.packageName} update failed.`,
+          diagnostics: {
+            installedVersion: String(current ?? "unknown"),
+            remoteVersion: String(remote ?? "unknown"),
+          },
+        });
         process.exitCode = 1;
         return;
       }
@@ -426,6 +471,22 @@ export async function cmdUpdate(argv, overrides = {}) {
         console.error(`  Running CLI: ${CLI_BIN}`);
         console.error("  This usually means the `impel` on PATH belongs to a different npm prefix than `npm prefix -g`.");
         console.error(`  Fix: run \`npm prefix -g\`, confirm it owns the \`impel\` shim on PATH, then \`npm install --global ${installSpec}\` there.`);
+        // Its own step, not `install.impel_cli`: npm succeeded and the update
+        // landed somewhere real. The reportable fact is the prefix skew, and
+        // the two versions below are what makes a report of it actionable.
+        await reportUpdateFailure({
+          scope: "shared",
+          platform: io.platform,
+          architecture: process.arch,
+          step: "install.impel_cli_prefix_skew",
+          command: `npm install --global ${installSpec}`,
+          message: `npm reported success but the running CLI still resolves v${postInstall ?? "?"} (expected v${remote}), and the freshly installed build could not be located.`,
+          diagnostics: {
+            runningVersion: String(postInstall ?? "unknown"),
+            expectedVersion: String(remote),
+            cliBin: CLI_BIN,
+          },
+        });
         process.exitCode = 1;
         return;
       }
@@ -449,6 +510,26 @@ export async function cmdUpdate(argv, overrides = {}) {
   };
   if (!await io.runConvergence(convergenceArgs)) {
     console.error("impel update: tenant convergence failed; rerun `impel update` after addressing the reported issue.");
+    // The child is `impel _converge`, which files no report of its own — and
+    // this parent only sees its exit status, because the child inherits stdio
+    // so its progress reaches the terminal live. So this report carries what
+    // the parent does know: that it was an update cascade, and which flags
+    // shaped the run it failed under. Which tenants failed is visible on the
+    // user's screen but not in the report; closing that gap needs a channel
+    // between the two processes, which R2 (one report per invocation) says must
+    // not simply be a second report from the child.
+    await reportUpdateFailure({
+      scope: "shared",
+      platform: io.platform,
+      architecture: process.arch,
+      step: "update.tenant_convergence",
+      message: "Tenant convergence failed during `impel update`.",
+      diagnostics: {
+        skipApps: String(Boolean(flags["skip-apps"])),
+        skipClis: String(Boolean(flags["skip-clis"])),
+        cascadedEntrypoint: String(Boolean(cascadeEntrypoint)),
+      },
+    });
     process.exitCode = 1;
     return;
   }

package/src/cursorLocal.js

@@ -1473,6 +1473,14 @@ export function cursorLaunchSpec({
   }
   const env = { ...environment };
   for (const key of [...DIRECT_PROVIDER_ENV_KEYS, ...RUNTIME_OVERRIDE_ENV_KEYS]) delete env[key];
+  // The positive managed marker `telemetryConsent.js` denies on. It has to be
+  // stamped here rather than inferred: the delete loop above removes
+  // CLAUDE_CONFIG_DIR and CODEX_HOME, and `HOME` below points at the managed
+  // profile, so every path the guard could otherwise key on either disappears
+  // or stops looking managed. Without it a terminal inside managed Cursor —
+  // holding CURSOR_LOCAL_AGENT_API_KEY — would capture and flush telemetry to a
+  // host other than the gateway, which is the P1-8 egress boundary.
+  env[brandedEnvironmentName("MANAGED_CURSOR")] = "1";
   env.HOME = paths.home;
   env.XDG_CACHE_HOME = path.join(paths.home, ".cache");
   env.XDG_CONFIG_HOME = path.join(paths.home, ".config");

package/src/exitCodes.js

@@ -0,0 +1,61 @@
+// Process exit codes that mean something specific.
+//
+// Three values are already spoken for and must never be reused:
+//
+//   1  — `bin/impel.js`'s catch-all for any escaped throw. A dedicated code
+//        that collides with this is indistinguishable from a crash.
+//   78 — `MANAGED_RUNTIME_PREFLIGHT_EXIT_CODE` (EX_CONFIG) in `src/apps.js`.
+//   127 — the shell's "command not found"; a CLI that returns it is claiming
+//        it was never invoked.
+//
+// Everything else follows sysexits.h, so an operator reading a bare number
+// gets the right intuition without a lookup.
+
+/** Codes an Impel-specific exit code must not reuse. Asserted by tests. */
+export const RESERVED_EXIT_CODES = Object.freeze([0, 1, 78, 127]);
+
+/**
+ * `impel _telemetry flush` could not deliver its batch (EX_TEMPFAIL): the
+ * spool is intact and a later flush retries.
+ *
+ * Nothing reads this in production — the sender is detached with stdio
+ * ignored, and the durable drop notice is the real observability surface. It
+ * exists because the send is an external call, and Law 6 wants every failure
+ * branch to have a distinct non-zero outcome that a test and a human running
+ * the command by hand can both see.
+ */
+export const TELEMETRY_FLUSH_FAILED_EXIT_CODE = 75;
+
+/**
+ * A gated command refused because the feature-flag state could not be
+ * established (EX_UNAVAILABLE): no fresh evaluation, no cached one for this
+ * account, and no way to reach the control plane.
+ *
+ * Distinct from the catch-all 1 on purpose. "I could not find out whether you
+ * are allowed to run this" and "I crashed" are different states, and only the
+ * first one is worth retrying once the machine is back online.
+ */
+export const FLAG_STATE_UNKNOWN_EXIT_CODE = 69;
+
+/**
+ * A gated command refused because the flag is off for this account
+ * (EX_NOPERM): the state *was* established, and the answer was no.
+ *
+ * Separate from `FLAG_STATE_UNKNOWN_EXIT_CODE` because the two say opposite
+ * things about retrying. "Not enabled for you" is a settled answer — running it
+ * again changes nothing until someone grants access. "Could not find out" is
+ * worth retrying the moment the machine is back online. A script that treats
+ * both as one number has to guess which it got.
+ */
+export const FEATURE_NOT_ENABLED_EXIT_CODE = 77;
+
+/**
+ * `impel report` could not deliver the bug report and wrote the envelope to
+ * disk instead (EX_IOERR): the route was unreachable, absent, or rate-limited.
+ *
+ * The report is user-initiated, so unlike telemetry someone is watching this
+ * exit code. It says "your report was not lost, and it was not sent either" —
+ * a state that deserves its own number, because the printed spool path is the
+ * next action and 1 would read as a crash that produced nothing.
+ */
+export const REPORT_SPOOLED_EXIT_CODE = 74;

package/src/featureFlags.js

@@ -0,0 +1,393 @@
+// Remote feature flags for the CLI: a disk cache in front of
+// `POST /api/cli/flags`, evaluated fail-closed.
+//
+// The only consumer today is the Cursor experiment gate, and that shapes every
+// decision here. A gate exists so an experiment can be turned off remotely for
+// one account; if a machine that cannot reach the control plane guessed a
+// value, the guess would be wrong exactly when the switch is being thrown. So
+// there is no default: `evaluateFlag` either returns an answer it can trace to
+// a real server evaluation — fresh, cached, or stale — or it throws
+// `FlagStateUnknownError` for the command to turn into a distinct exit code.
+//
+// Two timers, mirroring `src/updates.js`: `fetchedAt` decides whether the
+// cached answer is still current (6h), and `lastFailedAt` suppresses re-probing
+// after a failure (1h). Without the second one an offline machine would attempt
+// a fetch on every single invocation of the gated command.
+//
+// The cache records the principal it was fetched for. A read under a different
+// `{orgId, userId}` is a miss rather than a hit: serving the previous org's
+// answers for up to six hours after a tenant or PAT switch would defeat a kill
+// switch precisely when one org is being killed and another is not.
+//
+// Everything written here lives under `CONFIG_DIR`, so `impel nuke` erases it.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  CONFIG_DIR,
+  loadConfig,
+  normalizeGatewayUrl,
+  resolveDefaultAppUrl,
+} from "./config.js";
+import { FLAG_STATE_UNKNOWN_EXIT_CODE } from "./exitCodes.js";
+import { fetchHttp1 } from "./http1.js";
+import { TELEMETRY_CONTRACT } from "./posthog.js";
+import { RUNTIME_BRAND } from "./runtimeBrand.js";
+import { managedMarkerPresent } from "./telemetryConsent.js";
+import { renameWithWindowsRetry } from "./windowsFs.js";
+
+/** The route this module posts to. */
+export const FLAGS_ENDPOINT_PATH = "/api/cli/flags";
+
+/** Beside `update-check.json`, and erased by the same `impel nuke` sweep. */
+export const FLAG_CACHE_PATH = path.join(CONFIG_DIR, "flags.json");
+
+/** How long an evaluation stays authoritative. The repo's cache default. */
+export const FLAG_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+
+/**
+ * How long a failed check suppresses the next attempt. Shorter than the TTL:
+ * a failure should heal within the session, but must not turn an offline
+ * machine into one request per gated command.
+ */
+export const FLAG_FETCH_BACKOFF_MS = 60 * 60 * 1000;
+
+/**
+ * The flag the managed-Cursor experiment is gated on.
+ *
+ * Declared as a literal rather than read out of `TELEMETRY_CONTRACT` by index;
+ * `test/feature-flags.test.js` pins it against `featureFlagKeys` so the two
+ * cannot drift while keeping the reference here readable.
+ */
+export const CURSOR_EXPERIMENT_FLAG = "cli-cursor-experiment";
+
+/** Long enough for a cold control-plane response, short enough to be a gate. */
+const REQUEST_TIMEOUT_MS = 10_000;
+
+/** Flag keys are bounded by the server schema; anything longer is not ours. */
+const MAX_FLAG_KEY_LENGTH = 128;
+
+/**
+ * The flag state could not be established, and no cached answer applies.
+ *
+ * Thrown rather than returned so a caller cannot accidentally treat it as a
+ * value. Commands catch it and set `exitCode` on `process.exitCode`: the
+ * `experimental` throw path always exits 1, so an escaping throw would be
+ * indistinguishable from a crash (see `src/exitCodes.js`).
+ */
+export class FlagStateUnknownError extends Error {
+  constructor(message, reason) {
+    super(message);
+    this.name = "FlagStateUnknownError";
+    /** Machine-readable cause; each maps to its own message. */
+    this.reason = reason;
+    this.exitCode = FLAG_STATE_UNKNOWN_EXIT_CODE;
+  }
+}
+
+/** Internal: a fetch that did not produce a usable evaluation. */
+class FlagFetchError extends Error {
+  constructor(message, reason) {
+    super(message);
+    this.name = "FlagFetchError";
+    this.reason = reason;
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/* Cache                                                                      */
+/* -------------------------------------------------------------------------- */
+
+export function readFlagCache() {
+  try {
+    const cache = JSON.parse(fs.readFileSync(FLAG_CACHE_PATH, "utf8"));
+    return cache && typeof cache === "object" && !Array.isArray(cache) ? cache : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Merge-and-replace, matching `writeUpdateCache`'s tmp+rename discipline. */
+export function writeFlagCache(patch) {
+  const next = { ...(readFlagCache() || {}), ...patch };
+  fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  const temporaryPath = `${FLAG_CACHE_PATH}.tmp-${process.pid}`;
+  try {
+    fs.writeFileSync(temporaryPath, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    renameWithWindowsRetry(temporaryPath, FLAG_CACHE_PATH);
+  } finally {
+    try {
+      fs.rmSync(temporaryPath, { force: true });
+    } catch {
+      // Cleanup must never mask the write/rename outcome.
+    }
+  }
+  return next;
+}
+
+/**
+ * Who the flags were evaluated for.
+ *
+ * `userId` comes from `config.user`, which U10 persists from the tenants
+ * response. Before that field exists it is `null` on both the write and the
+ * read, so the comparison stays consistent — an install that has never seen a
+ * `user` is one principal, not a permanent mismatch.
+ */
+function flagPrincipal(config) {
+  return {
+    orgId: typeof config?.tenantId === "string" ? config.tenantId : null,
+    userId: typeof config?.user?.id === "string" ? config.user.id : null,
+  };
+}
+
+function samePrincipal(cache, principal) {
+  return (cache?.orgId ?? null) === principal.orgId
+    && (cache?.userId ?? null) === principal.userId;
+}
+
+/** The cached evaluation, or null when there is none *for this principal*. */
+function cachedFlags(cache, principal) {
+  if (!cache || !samePrincipal(cache, principal)) return null;
+  const flags = cache.flags;
+  return flags && typeof flags === "object" && !Array.isArray(flags) ? flags : null;
+}
+
+function withinTtl(cache, now) {
+  return Number.isFinite(cache?.fetchedAt) && now - cache.fetchedAt < FLAG_CACHE_TTL_MS;
+}
+
+function backoffRemainingMs(cache, now) {
+  if (!Number.isFinite(cache?.lastFailedAt)) return 0;
+  return Math.max(0, cache.lastFailedAt + FLAG_FETCH_BACKOFF_MS - now);
+}
+
+/* -------------------------------------------------------------------------- */
+/* Evaluation                                                                 */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Read one flag out of an evaluation.
+ *
+ * A key the evaluation does not mention resolves to `enabled: false`. That is
+ * not a fabricated default: the server answered, and an answer that does not
+ * name the flag is an answer that the flag is not on for this principal. The
+ * fabricated case — no answer at all — throws instead. `known` lets a caller
+ * that cares tell the two apart.
+ */
+function resolveFlag(name, flags, source) {
+  const flag = flags?.[name];
+  return {
+    name,
+    enabled: flag?.enabled === true,
+    variant: typeof flag?.variant === "string" ? flag.variant : null,
+    payload: flag && Object.hasOwn(flag, "payload") ? flag.payload : null,
+    known: Boolean(flag),
+    source,
+  };
+}
+
+/**
+ * Validate a response into the shape the cache stores, or return null.
+ *
+ * One malformed flag rejects the whole response rather than being skipped: a
+ * partially-read evaluation is exactly the "some flags computed, some not"
+ * state the route already refuses to send (`flags_unavailable`), and a kill
+ * switch dropped by a lenient parser reads as "not killed".
+ */
+function normalizeFlagResponse(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  const { flags } = payload;
+  if (!flags || typeof flags !== "object" || Array.isArray(flags)) return null;
+  const keys = Object.keys(flags);
+  if (keys.length > TELEMETRY_CONTRACT.limits.maxFlagsPerResponse) return null;
+
+  const normalized = {};
+  for (const key of keys) {
+    if (key.length === 0 || key.length > MAX_FLAG_KEY_LENGTH) return null;
+    const value = flags[key];
+    if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+    if (typeof value.enabled !== "boolean") return null;
+    normalized[key] = { enabled: value.enabled };
+    if (typeof value.variant === "string" && value.variant.length > 0) {
+      normalized[key].variant = value.variant;
+    }
+    if (value.payload !== undefined) normalized[key].payload = value.payload;
+  }
+  return {
+    flags: normalized,
+    evaluatedAt: typeof payload.evaluatedAt === "string" ? payload.evaluatedAt : null,
+  };
+}
+
+async function jsonBody(response) {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * One evaluation request.
+ *
+ * Server-supplied text is never echoed — only status codes and our own
+ * sentences — so no message can carry back something that needs redacting.
+ */
+async function fetchFlags({ config, fetchImpl, timeoutMs }) {
+  const appUrl = normalizeGatewayUrl(config.appUrl || resolveDefaultAppUrl());
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  let response;
+  try {
+    response = await fetchImpl(new URL(FLAGS_ENDPOINT_PATH, appUrl), {
+      method: "POST",
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${config.pat}`,
+        "content-type": "application/json",
+      },
+      body: "{}",
+      signal: controller.signal,
+    });
+  } catch {
+    throw new FlagFetchError(
+      `could not reach ${appUrl} to check feature flags; reconnect and try again`,
+      "unreachable",
+    );
+  } finally {
+    clearTimeout(timeout);
+  }
+
+  if (!response.ok) {
+    // R16: a `next` deployment that predates the route. Named separately from
+    // every other failure because the remedy is a deployment, not a retry.
+    if (response.status === 404) {
+      throw new FlagFetchError(
+        `${appUrl} does not serve feature flags yet; update the ${RUNTIME_BRAND.product.displayName} control plane and try again`,
+        "absent_route",
+      );
+    }
+    const body = await jsonBody(response);
+    if (body?.code === "flags_unavailable") {
+      throw new FlagFetchError(
+        `${appUrl} cannot evaluate feature flags right now; try again in a few minutes`,
+        "unavailable",
+      );
+    }
+    throw new FlagFetchError(
+      `${appUrl} refused the feature-flag check (HTTP ${response.status}); try again later`,
+      "rejected",
+    );
+  }
+
+  const normalized = normalizeFlagResponse(await jsonBody(response));
+  if (!normalized) {
+    throw new FlagFetchError(
+      `${appUrl} returned a feature-flag response this CLI cannot read; update the CLI and try again`,
+      "malformed",
+    );
+  }
+  return normalized;
+}
+
+/**
+ * Why this process may not make the request, or null when it may.
+ *
+ * The managed-surface denial is the P1-8 egress boundary and is checked first:
+ * a managed vendor app profile may reach the gateway and nothing else, so a
+ * flag check from inside one presents as an unexpected call from a profile
+ * holding app credentials. Unlike analytics capture this is not a consent
+ * question — a kill switch that honors an opt-out is not a kill switch — but
+ * the context guard applies to every egress path without exception.
+ */
+function fetchBlocked({ config, env, homeDir, cache, now }) {
+  if (managedMarkerPresent(env, homeDir)) {
+    return {
+      reason: "managed_surface",
+      message: "feature flags cannot be checked from inside a managed Impel app profile; run this from a terminal",
+    };
+  }
+  if (!config?.pat) {
+    return {
+      reason: "unauthenticated",
+      message: `not authenticated; run \`${RUNTIME_BRAND.cli.command} setup\` before using a gated feature`,
+    };
+  }
+  const remaining = backoffRemainingMs(cache, now);
+  if (remaining > 0) {
+    const minutes = Math.max(1, Math.ceil(remaining / 60_000));
+    return {
+      reason: "backoff",
+      message: `a recent feature-flag check failed and no cached answer applies to this account; try again in ${minutes} minute${minutes === 1 ? "" : "s"}`,
+    };
+  }
+  return null;
+}
+
+/**
+ * Resolve one flag for the current principal.
+ *
+ * The state machine, in the order the branches are taken:
+ *
+ *   fresh cache                      -> use it, no request
+ *   blocked (managed/no PAT/backoff) -> stale cache if there is one, else refuse
+ *   fetch succeeds                   -> store and use
+ *   fetch fails, cache exists        -> stale value, failure stamped
+ *   fetch fails, no cache            -> refuse with that failure's own message
+ *
+ * "Cache" throughout means a cache written for *this* `{orgId, userId}`; one
+ * written for another principal is not a cache miss that degrades to stale, it
+ * is a miss that refuses.
+ */
+export async function evaluateFlag(name, options = {}) {
+  const {
+    config = loadConfig(),
+    fetchImpl = fetchHttp1,
+    env = process.env,
+    homeDir = os.homedir(),
+    now = Date.now(),
+    timeoutMs = REQUEST_TIMEOUT_MS,
+  } = options;
+
+  const principal = flagPrincipal(config);
+  const cache = readFlagCache();
+  const cached = cachedFlags(cache, principal);
+  if (cached && withinTtl(cache, now)) return resolveFlag(name, cached, "cache");
+
+  const blocked = fetchBlocked({ config, env, homeDir, cache, now });
+  if (blocked) {
+    if (cached) return resolveFlag(name, cached, "stale");
+    throw new FlagStateUnknownError(blocked.message, blocked.reason);
+  }
+
+  let evaluation;
+  try {
+    evaluation = await fetchFlags({ config, fetchImpl, timeoutMs });
+  } catch (error) {
+    // Stamp the failure even when a stale answer covers this call: the point of
+    // the second timer is that the *next* invocation does not re-probe either.
+    try {
+      writeFlagCache({ lastFailedAt: now });
+    } catch {
+      // The stamp is a request-rate limiter, not required state.
+    }
+    if (cached) return resolveFlag(name, cached, "stale");
+    throw new FlagStateUnknownError(error.message, error.reason || "unreachable");
+  }
+
+  try {
+    writeFlagCache({
+      ...principal,
+      flags: evaluation.flags,
+      evaluatedAt: evaluation.evaluatedAt,
+      fetchedAt: now,
+      lastFailedAt: 0,
+    });
+  } catch {
+    // An unwritable config dir costs a cache, not an answer: this evaluation is
+    // authoritative and is returned either way.
+  }
+  return resolveFlag(name, evaluation.flags, "network");
+}