Skip to content

Write HTML. Render video. Built for agents.

40.0 KB
Raw Blame
import * as fs from "node:fs";
import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import { homedir } from "node:os";
import { randomUUID } from "node:crypto";
import { normalizeErrorMessage } from "../utils/errorMessage.js";
import { telemetryRuntimeOverride } from "./policy.js";
import { isAttendedTerminal } from "../utils/attendedTerminal.js";
import { withFileLock } from "../media-use/lib/config-lock.mjs";

// ---------------------------------------------------------------------------
// Config directory: ~/.hyperframes/
// ---------------------------------------------------------------------------

const CONFIG_DIR = join(homedir(), ".hyperframes");
const CONFIG_FILE = join(CONFIG_DIR, "config.json");

// ---------------------------------------------------------------------------
// Install-state file: ~/.hyperframes/install-state.json
//
// A separate FILE, but deliberately the same DIRECTORY as config.json, so
// `rm -rf ~/.hyperframes` really is a full reset. It previously lived in
// ~/.local/state/hyperframes/ specifically to survive that delete; review
// rejected that ("if someone is deleting their hyperframes config it should
// wipe all hyperframes state — I'm not sure we should try and persist state
// elsewhere to get around this"), and the measurement agreed: the churn this
// actually defends against is not users running `rm -rf`.
//
// The threat it does defend against is config.json itself. That file is hot
// and wide — ~20 fields rewritten on every command and every render — and
// readConfig recovers from ANY parse/permission/IO failure by minting a fresh
// identity. Splitting these two facts into their own file decouples them from
// that churn: no shared schema to migrate on upgrade, and one write at first
// mint instead of one per command.
//
// It carries exactly three facts, and no telemetry identity — no anonymousId,
// no counters, nothing emitted that links the old install to the new one:
//
//   1. `markerAt` — "a hyperframes install existed on this machine". Now that
//      it shares CONFIG_DIR, `predecessorFound` measures the churn we care
//      about (config.json lost, install-state survived => corruption/re-mint)
//      rather than deliberate directory deletion, which takes both.
//   2. `deParallelRouterTrialFired` — the DE parallel-router circuit
//      breaker's tripped state, so a config re-mint does not re-enrol an
//      install into an experimental path that already FAILED on this machine.
//   3. `bucketSeed` — the canary bucketing unit, so a re-mint does not
//      reshuffle cohorts mid-rollout. Never transmitted; only the resulting
//      true/false assignments are. Sharing CONFIG_DIR is what keeps it from
//      being a persistent identifier that outlives the user's reset.
//
// Removal path: delete ~/.hyperframes (or just this file). `hyperframes
// telemetry status` prints its exact location.
// ---------------------------------------------------------------------------

const STATE_FILE = join(CONFIG_DIR, "install-state.json");

// Pre-move location. Read once, migrated, then deleted — an install that
// wrote state under the old scheme keeps its tripped breaker instead of
// silently re-enrolling, and no file is left behind outside CONFIG_DIR.
const LEGACY_STATE_FILE = join(homedir(), ".local", "state", "hyperframes", "install-state.json");

interface InstallState {
  /** ISO timestamp of when the marker was first written. */
  markerAt: string;
  /** Rolled-over circuit-breaker state — see HyperframesConfig's field. */
  deParallelRouterTrialFired?: boolean;
  /**
   * The canary bucketing seed — see HyperframesConfig's field. Write-once
   * within this config dir: the first install's seed wins forever, so a
   * config.json re-mint re-rolls the telemetry id but NOT the canary cohorts.
   * Deleting ~/.hyperframes takes the seed with it, by design.
   */
  bucketSeed?: string;
}

/**
 * Why there is no usable state: the file isn't there, or it is but couldn't be
 * read/parsed. Distinguished because they mean opposite things for churn
 * measurement — "absent" is a genuinely new machine, "corrupt" is a machine we
 * already knew whose record we lost. Collapsing them into one `null` reported
 * every corruption as a fresh install and biased `predecessorFound` low.
 */
type InstallStateMiss = "absent" | "corrupt";

/**
 * Parse one state file.
 *
 * A malformed `markerAt` no longer discards the record. `markerAt` is
 * regenerable — it is only a timestamp — while `bucketSeed` is not: losing it
 * silently re-rolls the install's canary cohort. So a partial corruption that
 * leaves a usable seed keeps the seed and restamps the marker.
 */
function salvageInstallState(parsed: Partial<InstallState>): InstallState | InstallStateMiss {
  const markerAt = typeof parsed.markerAt === "string" ? parsed.markerAt : undefined;
  const bucketSeed = parseNonEmptyString(parsed.bucketSeed);
  const fired = parsed.deParallelRouterTrialFired === true ? true : undefined;
  // Each of the three is independently salvageable, and the tripped breaker
  // most of all: dropping it re-enrols a machine into an experimental path
  // that already FAILED there, which is the one outcome this file exists to
  // prevent. `markerAt` is only a timestamp and can be restamped.
  if (markerAt === undefined && bucketSeed === undefined && fired === undefined) return "corrupt";
  return {
    markerAt: markerAt ?? new Date().toISOString(),
    deParallelRouterTrialFired: fired,
    bucketSeed,
  };
}

function parseInstallState(file: string): InstallState | InstallStateMiss {
  if (!existsSync(file)) return "absent";
  try {
    return salvageInstallState(JSON.parse(readFileSync(file, "utf-8")) as Partial<InstallState>);
  } catch {
    return "corrupt";
  }
}

// Once per process: the backfill runs on every readConfig until it lands, and
// a read-only home directory would otherwise print on every single command.
let seedBackfillWarned = false;

/**
 * The seed backfill could not be persisted, so this install will mint a
 * different seed next invocation and silently churn its canary cohort. Rare
 * (unwritable ~/.hyperframes) but invisible without this, and it makes the
 * "backfilled once" contract in the field's docstring false.
 */
function warnSeedBackfillFailed(error: string | undefined): void {
  if (seedBackfillWarned) return;
  seedBackfillWarned = true;
  // Suppressed when the user has opted out of telemetry: the only consequence
  // of the failed write is unstable CANARY cohorts, and an opted-out install
  // is not enrolled in any. Printing anyway put an unsilenceable line into
  // CI render logs on every invocation for a user who wants no telemetry at
  // all. `hyperframes doctor` still surfaces it on demand.
  if (telemetryRuntimeOverride() !== null) return;
  console.warn(
    `[hyperframes] Could not persist telemetry config${error ? `: ${error}` : ""}. ` +
      "Canary cohort assignment will not be stable across runs.",
  );
}

/**
 * One-time backfill for configs predating the bucket seed: prefer the seed a
 * previous install recorded, else mint. Mutates `config` in place.
 *
 * Persisting is the whole point — an unpersisted seed re-rolls next process,
 * silently churning this install's cohort on every invocation. `~/.hyperframes`
 * being unwritable (root-owned after a sudo mishap, read-only mount, disk full)
 * is exactly when that happens, so it says so once rather than failing
 * invisibly.
 */
function backfillBucketSeed(config: HyperframesConfig): ConfigWriteResult {
  const recorded = readInstallState();
  config.bucketSeed = (isInstallState(recorded) ? recorded.bucketSeed : undefined) ?? randomUUID();
  const write = writeConfigWithResult(config);
  if (!write.ok) warnSeedBackfillFailed(write.error);
  return write;
}

// ONLY the positive is cached. The latch is monotonic across processes in one
// direction: once some process trips it, it stays tripped. A cached `false`
// is not monotonic — another process can trip the breaker while this one is
// alive, and a long-lived process (the preview/studio server) would then hold
// a stale negative for hours. So `true` short-circuits and `false` re-reads.
let latchedFiredSeen = false;

/**
 * Is the breaker latched according to install-state?
 *
 * Merged into EVERY effective read, which is what makes install-state
 * authoritative for the latch rather than merely a mirror of config.json.
 * Without this a failed mirror, or a stale concurrent writer that rewrites
 * config.json from a pre-trip snapshot, leaves state latched and config
 * false — and the next process happily re-enrols a machine whose router
 * already failed. Verifying the write is not enough on its own; the read has
 * to prefer the safety fact.
 */
function installStateLatchedFired(): boolean {
  if (latchedFiredSeen) return true;
  const state = readInstallState();
  latchedFiredSeen = isInstallState(state) && state.deParallelRouterTrialFired === true;
  return latchedFiredSeen;
}

/**
 * The seed install-state has recorded for this machine, if any.
 *
 * Deliberately NOT memoized, unlike the latch above. This is only reached on a
 * `readConfig` cache miss, so a memo saved one `readFileSync` per re-parse —
 * and cost the documented full reset: a long-lived preview that had read seed
 * A, observed `rm -rf ~/.hyperframes`, and minted B would still be handed the
 * cached A, resurrecting the cohort the user just cleared. The latch memo is
 * different on purpose: it caches only `true`, and a breaker that survives a
 * reset fails safe.
 */
function installStateSeed(): string | undefined {
  const state = readInstallState();
  return isInstallState(state) ? state.bucketSeed : undefined;
}

/** Narrow the parse result to a usable record. */
function isInstallState(value: InstallState | InstallStateMiss): value is InstallState {
  return typeof value !== "string";
}

/**
 * Read the install-state file, adopting the pre-move copy if this machine
 * still has one.
 *
 * Migration is one-way and best-effort: the current location always wins (a
 * stale legacy file must never resurrect a breaker the user has since
 * cleared), and failing to delete the legacy copy is not an error — it is
 * re-read harmlessly next time.
 */
function readInstallState(): InstallState | InstallStateMiss {
  const current = parseInstallState(STATE_FILE);
  if (isInstallState(current)) {
    removeLegacyStateFile();
    return current;
  }
  const legacy = parseInstallState(LEGACY_STATE_FILE);
  if (!isInstallState(legacy)) {
    // Unreadable legacy copy: nothing to migrate, so drop it here too. It
    // used to survive, and since it lives OUTSIDE ~/.hyperframes it then
    // reported predecessorFound/stateFileCorrupt forever on a machine the
    // user had already reset with `rm -rf ~/.hyperframes` — poisoning the one
    // metric this file exists to produce.
    if (legacy === "corrupt") removeLegacyStateFile();
    // Corruption at EITHER location still means this machine had an install.
    return current === "corrupt" || legacy === "corrupt" ? "corrupt" : "absent";
  }
  try {
    writeInstallState(legacy);
    removeLegacyStateFile();
  } catch {
    // Keep the legacy copy; the value is still returned below either way.
  }
  return legacy;
}

function removeLegacyStateFile(): void {
  try {
    if (existsSync(LEGACY_STATE_FILE)) rmSync(LEGACY_STATE_FILE, { force: true });
  } catch {
    // Best-effort cleanup — never break the CLI over a leftover file.
  }
}

// Sync bookkeeping, so the existsSync+read doesn't run on every writeConfig:
// `stateMarkerSynced` = the marker is known present; `stateFiredSynced` = the
// state file is known to already carry fired=true.
let stateMarkerSynced = false;
let stateFiredSynced = false;

/** Test-only: reset the sync memo (module state leaks across vitest cases). */
export function __resetInstallStateSyncForTests(): void {
  stateMarkerSynced = false;
  stateFiredSynced = false;
}

/**
 * Atomic for the same reason writeConfig is: a torn read must never exist,
 * since a corrupted state file silently reads as absent.
 */
function writeInstallState(next: InstallState): void {
  mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
  const tmpFile = `${STATE_FILE}.${process.pid}.tmp`;
  writeFileSync(tmpFile, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
  renameSync(tmpFile, STATE_FILE);
}

/**
 * Bring the install-state file up to date with this config write: ensure the
 * marker exists, and mirror a tripped breaker. Called from `writeConfig` so
 * no breaker write site can forget it. Never throws — same contract as the
 * rest of this file, telemetry must not break the CLI.
 */
function sameInstallState(a: InstallState, b: InstallState): boolean {
  return (
    a.deParallelRouterTrialFired === b.deParallelRouterTrialFired && a.bucketSeed === b.bucketSeed
  );
}

/** Latching: once tripped (by any install in this config dir), stays tripped. */
function latchedFired(state: InstallState | null, config: HyperframesConfig): true | undefined {
  return (
    state?.deParallelRouterTrialFired === true ||
    config.deParallelRouterTrialFired === true ||
    undefined
  );
}

/** What the state file should say after this config write; null = already correct. */
function nextInstallState(
  state: InstallState | null,
  config: HyperframesConfig,
): InstallState | null {
  const next: InstallState = {
    markerAt: state?.markerAt ?? new Date().toISOString(),
    deParallelRouterTrialFired: latchedFired(state, config),
    // Write-once: an existing seed always wins, so cohorts stay
    // anchored to the FIRST install in this config dir, not the latest one.
    bucketSeed: state?.bucketSeed ?? config.bucketSeed,
  };
  if (state !== null && sameInstallState(state, next)) return null;
  return next;
}

/** @returns false if the mirror could not be written this call. */
/** The write half, split out to keep the memo bookkeeping legible. */
function applyInstallState(config: HyperframesConfig, wantFired: boolean): void {
  const read = readInstallState();
  const state = isInstallState(read) ? read : null;
  const next = nextInstallState(state, config);
  if (next !== null) writeInstallState(next);
  stateMarkerSynced = true;
  stateFiredSynced = wantFired || state?.deParallelRouterTrialFired === true;
  if (wantFired) latchedFiredSeen = true;
}

function syncInstallState(config: HyperframesConfig): boolean {
  const wantFired = config.deParallelRouterTrialFired === true;
  // The memo says "this process already wrote the state file". That is only
  // true while the file is still there. `rm -rf ~/.hyperframes` under a
  // long-lived preview left the memo set, so the mirror was never recreated:
  // the freshly minted seed lived in config.json alone, and the NEXT
  // config-only re-mint rolled a third seed instead of inheriting the second.
  // One existsSync on a path we are about to write anyway.
  if (stateMarkerSynced && !existsSync(STATE_FILE)) {
    stateMarkerSynced = false;
    stateFiredSynced = false;
  }
  if (stateMarkerSynced && (stateFiredSynced || !wantFired)) return true;
  try {
    applyInstallState(config, wantFired);
    return true;
  } catch {
    // Leave the memo unset so a later write retries.
    return false;
  }
}

/**
 * Mint a fresh config, persist it, and cache it EVEN IF the write failed.
 *
 * Without the unconditional cache the next readConfig in the same process
 * re-minted, re-rolling bucketSeed along with the id — and across processes an
 * unwritable ~/.hyperframes (read-only mount, root-owned after a sudo run,
 * full disk) meant a fresh cohort on every single command, which is exactly
 * the unbounded cumulative exposure the seed exists to prevent.
 */
function mintAndCacheConfig(): HyperframesConfig {
  const config = mintConfig();
  const write = writeConfigWithResult(config);
  if (!write.ok) warnSeedBackfillFailed(write.error);
  classifyIdentity(
    config.anonymousId,
    write.ok ? "unknown" : "process_only",
    writeOutcomeOf(write),
  );
  cachedConfig = { ...config };
  return { ...config };
}

/**
 * Build a brand-new config for an install with no (readable) config file,
 * consulting the install-state file for what a previous install on this
 * machine left behind.
 */
function mintConfig(): HyperframesConfig {
  const read = readInstallState();
  const state = isInstallState(read) ? read : null;
  return {
    ...DEFAULT_CONFIG,
    anonymousId: randomUUID(),
    // A corrupt record still means this machine had an install — reporting it
    // as `false` would count a partial disk write as a brand-new machine and
    // understate recoverable churn, which is the one thing this field exists
    // to measure. `undefined` on configs minted before the field existed.
    predecessorFound: state !== null || read === "corrupt",
    stateFileCorrupt: read === "corrupt" ? true : undefined,
    // The rollover itself: a breaker tripped by a previous install on this
    // machine stays tripped for the new one, and the canary bucketing seed is
    // inherited so cohorts hold across a config.json re-mint.
    deParallelRouterTrialFired: state?.deParallelRouterTrialFired === true ? true : undefined,
    bucketSeed: state?.bucketSeed ?? randomUUID(),
  };
}

export interface HyperframesConfig {
  /** Has the user agreed to download the on-device search model? Undefined means never asked. */
  localEmbeddingEnabled?: boolean;
  /** Whether anonymous telemetry is enabled (default: true in production) */
  telemetryEnabled: boolean;
  /** Stable anonymous identifier — no PII, just a random UUID */
  anonymousId: string;
  /** Whether the first-run telemetry notice has been shown */
  telemetryNoticeShown: boolean;
  /** Total CLI command invocations (for engagement prompts) */
  commandCount: number;
  /** Total successful renders (for feedback prompt gating) */
  renderSuccessCount: number;
  /** The renderSuccessCount at which feedback was last shown */
  lastFeedbackPromptAt: number;
  /** ISO timestamp of the last npm registry version check */
  lastUpdateCheck?: string;
  /** Latest version found on npm */
  latestVersion?: string;
  /** Throttle for the non-TTY stale-project-pin notice (ms epoch). */
  lastStalePinNoticeAt?: number;
  lastUpdateAttemptAt?: string;
  lastSkillsAttemptAt?: string;
  /**
   * Auto-update marker. Set when a background install is spawned so a
   * subsequent run can skip re-triggering it. Cleared once
   * `completedUpdate` captures the outcome.
   */
  pendingUpdate?: {
    /** Version being installed. */
    version: string;
    /** Install command being run, for debug logging. */
    command: string;
    /** ISO timestamp of when the background install was launched. */
    startedAt: string;
  };
  /**
   * Outcome of the last completed auto-update, written by the detached
   * installer. Surfaced once in the next invocation and then cleared.
   */
  completedUpdate?: {
    version: string;
    /** Whether the install succeeded. */
    ok: boolean;
    /** ISO timestamp of when the installer finished. */
    finishedAt: string;
    /** Non-empty when `ok === false` — the installer's stderr tail. */
    error?: string;
    /** True after the result has been surfaced once to the user. */
    reported?: boolean;
  };
  /** ISO timestamp of the last `skills check` freshness check (24h cache). */
  lastSkillsCheck?: string;
  /** Whether installed skills were stale at the last check. */
  skillsUpdateAvailable?: boolean;
  /** How many installed skills were outdated at the last check. */
  skillsOutdatedCount?: number;
  /** How many skills were missing (not installed) at the last check. */
  skillsMissingCount?: number;
  /** How many installed skills were flagged removed-upstream at the last check. */
  skillsRemovedCount?: number;
  /**
   * True once the DE parallel-router experiment ("HF_DE_PARALLEL_ROUTER")
   * has actually FAILED (its self-verify/generic-failure safety net fired —
   * "reverted", not merely "routed") on a render from this install. The CLI
   * enables the experiment for free on EVERY eligible render from a fresh
   * install — not just once — to maximize real-traffic router telemetry
   * (mostly successful "routed" outcomes) without requiring anyone to
   * manually opt in via env var; only a real failure turns it off, and only
   * for this install going forward. See `renderLocal`'s
   * `maybeEnableDeParallelRouterTrial`/`maybeConsumeDeParallelRouterTrial`.
   */
  deParallelRouterTrialFired?: boolean;
  /**
   * Count of engaged (routed or reverted) trial renders so far — the
   * backstop that caps exposure even absent an actual failure. See
   * `DE_PARALLEL_ROUTER_TRIAL_MAX_RENDERS` in `render.ts`.
   */
  deParallelRouterTrialRenderCount?: number;
  /**
   * Whether a previous install's state marker existed on this machine when
   * this config was minted. Attached to telemetry so the fraction of fresh
   * installs that are RECOVERABLE churn (config.json re-minted, install-state
   * survived) is
   * measurable directly. `undefined` on configs minted before this field
   * existed — a different fact from `false` (minted fresh, no predecessor).
   */
  predecessorFound?: boolean;
  /**
   * The install-state file existed but could not be read. Separates "we lost
   * this machine's record" from "genuinely new machine" in the churn split —
   * without it a partial disk write is indistinguishable from a fresh install.
   * Absent (not false) in the normal case, so it costs nothing on the wire.
   */
  stateFileCorrupt?: boolean;
  /**
   * The unit canary percentages bucket on — deliberately NOT the anonymousId.
   * A fresh random UUID, mirrored write-once into the install-state file and
   * inherited at mint, so a config.json RE-MINT re-rolls the telemetry id but
   * keeps this install's canary cohorts: no cumulative-exposure drift from
   * corruption, and before/after comparisons survive one.
   *
   * A re-mint is the churn that actually happens — config.json is rewritten on
   * every command and every render, and readConfig recovers from any
   * parse/permission/IO failure by minting fresh. Deleting ~/.hyperframes
   * deliberately does NOT survive: install-state lives in that same directory
   * precisely so the user's reset is a real reset. A seed that outlived it
   * would be a persistent identifier defeating the only lever they have.
   *
   * Never emitted in telemetry (only the resulting true/false assignments
   * are), so it does not link the old id to the new one server-side.
   * Backfilled once for configs predating the field.
   */
  bucketSeed?: string;
  /**
   * Ring of the last few local renders (newest last). `hyperframes feedback`
   * attaches these ids — which are the `render_job_id` /
   * `observability_render_job_id` on this install's PostHog events — to the
   * feedback it submits, so a wild bug report can be joined to the exact
   * telemetry rows of the renders it describes.
   */
  recentRenders?: RecentRenderRecord[];
}

/** One entry in {@link HyperframesConfig.recentRenders}. */
export interface RecentRenderRecord {
  /** The render job id (`RenderJob.id` — the telemetry `render_job_id`). */
  id: string;
  /** ISO timestamp of when the render finished. */
  at: string;
  /** Whether the render completed successfully. */
  ok: boolean;
}

/** Ring size for {@link HyperframesConfig.recentRenders}. */
const MAX_RECENT_RENDERS = 5;

/**
 * Append a finished render to the recent-renders ring (newest last, capped).
 * Fresh read-modify-write like the trial counters — narrows, but does not
 * eliminate, lost updates against a concurrent CLI process.
 */
export function recordRecentRender(id: string, ok: boolean): void {
  const config = readConfigFresh();
  const ring = [...(config.recentRenders ?? []), { id, at: new Date().toISOString(), ok }];
  config.recentRenders = ring.slice(-MAX_RECENT_RENDERS);
  writeConfig(config);
}

const DEFAULT_CONFIG: HyperframesConfig = {
  telemetryEnabled: true,
  anonymousId: "",
  telemetryNoticeShown: false,
  commandCount: 0,
  renderSuccessCount: 0,
  lastFeedbackPromptAt: 0,
};

let cachedConfig: HyperframesConfig | null = null;

// ---------------------------------------------------------------------------
// Identity-persistence classification — one sticky verdict per anonymous id
// within this process.
//
// Install-grain metrics need to know whether this process's anonymousId can
// be trusted to survive to the next run. Three-way, because from inside a
// single process durability is not always provable:
//
//   durable       — the id was LOADED from a preexisting config file: it has
//                   already survived at least one process boundary.
//   unknown       — the id was minted this run and the write landed. An
//                   ephemeral/isolated HOME (the identity-churn workloads:
//                   fresh id per run, install_predecessor_found=false every
//                   time) looks IDENTICAL to a genuine first run from in
//                   here, so this cannot be promoted to durable.
//   process_only  — minted this run but not persisted by the identity-
//                   establishing path (the write failed or no write occurred).
//
// The verdict is sticky for the same id: a fresh-install process that later
// re-reads its own just-written file must not upgrade itself to durable. If a
// config refresh replaces the id, the replacement gets its own classification.
// ---------------------------------------------------------------------------

export type IdentityPersistence = "durable" | "process_only" | "unknown";
/** `ok_unmirrored`: config.json landed but the install-state mirror did not. */
export type IdentityWriteOutcome = "ok" | "ok_unmirrored" | "failed";

interface IdentityClassification {
  anonymousId: string;
  persistence: IdentityPersistence;
  writeOutcome: IdentityWriteOutcome | undefined;
}

let identityClassification: IdentityClassification | undefined;

function classifyIdentity(
  anonymousId: string,
  persistence: IdentityPersistence,
  writeOutcome?: IdentityWriteOutcome,
): void {
  if (identityClassification?.anonymousId === anonymousId) return;
  identityClassification = { anonymousId, persistence, writeOutcome };
}

function writeOutcomeOf(write: ConfigWriteResult): IdentityWriteOutcome {
  if (!write.ok) return "failed";
  return write.mirrored === false ? "ok_unmirrored" : "ok";
}

/** The current anonymous id's sticky persistence verdict (classifies on demand). */
export function getIdentityPersistence(): IdentityPersistence {
  const config = readConfig();
  return identityClassification?.anonymousId === config.anonymousId
    ? identityClassification.persistence
    : "unknown";
}

/**
 * Outcome of the identity-establishing config write. Absent when that path did
 * not write: either the id came from disk or a replacement was minted on a
 * no-write path.
 */
export function getIdentityWriteOutcome(): IdentityWriteOutcome | undefined {
  const config = readConfig();
  return identityClassification?.anonymousId === config.anonymousId
    ? identityClassification.writeOutcome
    : undefined;
}

/** A non-empty string, or undefined — hand-edited configs can carry anything. */
function parseNonEmptyString(value: unknown): string | undefined {
  return typeof value === "string" && value.length > 0 ? value : undefined;
}

/** Shape-validate the recent-renders ring from a parsed config. */
function parseRecentRenders(value: unknown): RecentRenderRecord[] | undefined {
  if (!Array.isArray(value)) return undefined;
  return value
    .filter(
      (r): r is RecentRenderRecord =>
        typeof r === "object" &&
        r !== null &&
        typeof (r as RecentRenderRecord).id === "string" &&
        typeof (r as RecentRenderRecord).at === "string" &&
        typeof (r as RecentRenderRecord).ok === "boolean",
    )
    .slice(-MAX_RECENT_RENDERS);
}

/**
 * Read the config file, creating it with defaults if it doesn't exist.
 * Returns a mutable copy — call `writeConfig()` to persist changes.
 */
/**
 * Materialize a parsed config object, applying defaults and the explicit
 * type guards. Split out of readConfig purely for size — that function is
 * otherwise one long object literal plus four control-flow branches.
 */
/** Fields that are pure passthrough — no default, no validation. */
function passthroughFields(parsed: Partial<HyperframesConfig>): Partial<HyperframesConfig> {
  return {
    lastUpdateCheck: parsed.lastUpdateCheck,
    latestVersion: parsed.latestVersion,
    lastStalePinNoticeAt: parsed.lastStalePinNoticeAt,
    lastUpdateAttemptAt: parsed.lastUpdateAttemptAt,
    lastSkillsAttemptAt: parsed.lastSkillsAttemptAt,
    pendingUpdate: parsed.pendingUpdate,
    completedUpdate: parsed.completedUpdate,
    lastSkillsCheck: parsed.lastSkillsCheck,
    skillsUpdateAvailable: parsed.skillsUpdateAvailable,
    skillsOutdatedCount: parsed.skillsOutdatedCount,
    skillsMissingCount: parsed.skillsMissingCount,
    skillsRemovedCount: parsed.skillsRemovedCount,
    localEmbeddingEnabled: consentFrom(parsed.localEmbeddingEnabled),
  };
}

/**
 * Fields that need an explicit type guard or a cross-store merge, split from
 * the plain defaults so neither block is complex on its own.
 */
function guardedFields(parsed: Partial<HyperframesConfig>): Partial<HyperframesConfig> {
  return {
    // Explicit `=== true`/typeof-number checks rather than a truthy/nullish
    // read — a hand-edited or corrupted config could plausibly carry a
    // non-boolean/non-number JSON value (e.g. the STRING "false", which is
    // truthy in JS) for these two fields specifically, since they're read
    // with a bare truthy check at the call site (review finding).
    // `|| installStateLatchedFired()` — a latch recorded in install-state
    // wins over an untripped config.json, never the reverse.
    deParallelRouterTrialFired:
      parsed.deParallelRouterTrialFired === true || installStateLatchedFired() ? true : undefined,
    deParallelRouterTrialRenderCount:
      typeof parsed.deParallelRouterTrialRenderCount === "number"
        ? parsed.deParallelRouterTrialRenderCount
        : undefined,
    predecessorFound:
      typeof parsed.predecessorFound === "boolean" ? parsed.predecessorFound : undefined,
    stateFileCorrupt: parsed.stateFileCorrupt === true ? true : undefined,
    // Install-state wins, exactly as it does for the latch. Without this the
    // two stores could hold different seeds indefinitely: nextInstallState
    // is write-once (state's seed always survives), but the read took
    // config.json's blindly — so restoring or syncing only config.json left
    // the install bucketing on A while install-state kept B, and the next
    // re-mint silently flipped every cohort at once.
    bucketSeed: installStateSeed() ?? parseNonEmptyString(parsed.bucketSeed),
  };
}

function materializeConfig(parsed: Partial<HyperframesConfig>): HyperframesConfig {
  return {
    ...passthroughFields(parsed),
    telemetryEnabled: parsed.telemetryEnabled ?? DEFAULT_CONFIG.telemetryEnabled,
    anonymousId: parsed.anonymousId || randomUUID(),
    telemetryNoticeShown: parsed.telemetryNoticeShown ?? DEFAULT_CONFIG.telemetryNoticeShown,
    commandCount: parsed.commandCount ?? DEFAULT_CONFIG.commandCount,
    renderSuccessCount: parsed.renderSuccessCount ?? DEFAULT_CONFIG.renderSuccessCount,
    lastFeedbackPromptAt: parsed.lastFeedbackPromptAt ?? DEFAULT_CONFIG.lastFeedbackPromptAt,
    ...guardedFields(parsed),
    recentRenders: parseRecentRenders(parsed.recentRenders),
  };
}

export function readConfig(): HyperframesConfig {
  if (cachedConfig) return { ...cachedConfig };

  if (!existsSync(CONFIG_FILE)) return mintAndCacheConfig();

  try {
    const raw = readFileSync(CONFIG_FILE, "utf-8");
    const parsed = JSON.parse(raw) as Partial<HyperframesConfig>;

    const config = materializeConfig(parsed);

    // `durable` requires the id to have actually COME OFF DISK — a file that
    // predates this process proves cross-run persistence. materializeConfig
    // mints a REPLACEMENT id when the parsed file lacks one (hand-edited /
    // image-baked configs), and that replacement only reaches disk if the
    // bucket-seed backfill below happens to write; labelling it durable would
    // dress the exact churn signature this field exists to catch in the one
    // trustworthy label (review finding). Sticky either way, so a
    // fresh-install process re-reading its own write cannot self-promote.
    const idFromDisk = parseNonEmptyString(parsed.anonymousId) !== undefined;

    // One-time backfill for configs predating the bucket seed: prefer the
    // recorded seed if a previous install already wrote one, else mint.
    // Persisted immediately — an unpersisted seed would re-roll every process.
    if (config.bucketSeed === undefined) {
      const write = backfillBucketSeed(config);
      // The backfill write carries any replacement id to disk, so a minted id
      // classifies exactly like a fresh mint: by whether the write landed.
      if (idFromDisk) classifyIdentity(config.anonymousId, "durable");
      else
        classifyIdentity(
          config.anonymousId,
          write.ok ? "unknown" : "process_only",
          writeOutcomeOf(write),
        );
      // Cache even if the write failed, so the seed is at least stable for
      // the life of this process (a re-roll per readConfigFresh would flip
      // cohorts mid-session).
      cachedConfig = config;
      return { ...config };
    }

    // No write happens on this path: a replacement id lives only in this
    // process, guaranteed — the definition of process_only.
    classifyIdentity(config.anonymousId, idFromDisk ? "durable" : "process_only");

    cachedConfig = config;
    return { ...config };
  } catch {
    // A missing file is handled above. Any failure here means an existing
    // preference could not be read safely (corrupt JSON, permissions, I/O).
    // Recover through the same mint path as a missing file — so a tripped
    // breaker survives config corruption too — but fail closed for the
    // privacy control: recovery must never silently turn telemetry back on.
    const config = { ...mintConfig(), telemetryEnabled: false, localEmbeddingEnabled: false };
    const write = writeConfigWithResult(config);
    classifyIdentity(
      config.anonymousId,
      write.ok ? "unknown" : "process_only",
      writeOutcomeOf(write),
    );
    return config;
  }
}

/**
 * Re-read the config from disk, bypassing the in-process cache. Use
 * immediately before a targeted single-field read-modify-write (e.g. the DE
 * parallel-router trial's render count/fired flag) to narrow — though not
 * eliminate, there is no cross-process file locking here — the window for a
 * lost update against a concurrently-running CLI process that wrote other
 * fields in the meantime.
 */
export function readConfigFresh(): HyperframesConfig {
  cachedConfig = null;
  return readConfig();
}

/**
 * Persist config to disk. Updates the in-memory cache on success.
 *
 * Atomic: writes to a pid-suffixed temp file and renames it over the config —
 * `rename(2)` within one directory is atomic on POSIX, so a concurrent
 * reader can never observe a partially-written file. That matters beyond
 * hygiene: `readConfig`'s corrupted-file catch RESETS the config to defaults
 * (new anonymousId, telemetry re-enabled, all optional fields wiped), so a
 * torn read of a non-atomic write would silently destroy the user's config
 * (review finding).
 *
 * Returns whether the write actually landed — errors are still swallowed
 * (telemetry must never break the CLI), but callers that need persistence
 * certainty (e.g. the DE parallel-router trial's off-switch) can react
 * instead of re-implementing read-back verification.
 */
export function writeConfig(config: HyperframesConfig): boolean {
  return writeConfigWithResult(config).ok;
}

export type ConfigWriteResult =
  // `mirrored: false` means config.json landed but the install-state mirror
  // did not. Not a write failure — the latch is merged back in on read — but
  // callers persisting a tripped breaker may want to retry or warn.
  { ok: true; mirrored?: false } | { ok: false; error: string };

/**
 * Persist config and retain the failure reason for user-facing commands that
 * must distinguish a durable preference write from a best-effort update.
 */
export function writeConfigWithResult(config: HyperframesConfig): ConfigWriteResult {
  try {
    // The consent answer changes only through updateLocalModelConsent; a copy read earlier must not undo one.
    return withConfigLock(() =>
      persistConfig({ ...config, localEmbeddingEnabled: localModelConsentOnDisk() }),
    );
  } catch (error) {
    warnSettingsLockedOnce(error);
    return { ok: false, error: normalizeErrorMessage(error) };
  }
}

let warnedSettingsLocked = false;

/** One line per process while a leftover lock blocks settings; never where a program reads the output. */
function warnSettingsLockedOnce(error: unknown): void {
  if (warnedSettingsLocked || (error as NodeJS.ErrnoException)?.code !== "HF_SETTINGS_LOCKED")
    return;
  warnedSettingsLocked = true;
  if (
    !isAttendedTerminal() ||
    process.argv.some((arg) => arg === "--json" || arg.startsWith("--json="))
  )
    return;
  console.error(`${(error as Error).message} (see \`hyperframes doctor\`).`);
}

export function updateLocalModelConsent(
  decide: (onDisk: boolean | undefined) => boolean | undefined,
): boolean | undefined {
  try {
    return withConfigLock(() => {
      const onDisk = localModelConsentOnDisk();
      const next = decide(onDisk);
      if (next === onDisk) {
        if (cachedConfig) cachedConfig.localEmbeddingEnabled = onDisk;
        return next;
      }
      const written = persistConfig({ ...readConfigFresh(), localEmbeddingEnabled: next });
      return written.ok ? next : localModelConsentOnDisk();
    });
  } catch (error) {
    warnSettingsLockedOnce(error);
    return localModelConsentOnDisk();
  }
}

/** Absent means never asked; anything present but not `true` counts as a no. */
function consentFrom(value: unknown): boolean | undefined {
  return value === undefined ? undefined : value === true;
}

function localModelConsentOnDisk(): boolean | undefined {
  try {
    return consentFrom(JSON.parse(readFileSync(CONFIG_FILE, "utf-8")).localEmbeddingEnabled);
  } catch (error) {
    // A settings file that exists but cannot be read may hold a no; only a missing one was never asked.
    return (error as NodeJS.ErrnoException).code === "ENOENT" ? undefined : false;
  }
}

let holdingConfigLock = false;

/** One process at a time between reading config.json and replacing it; re-entrant within this one. */
function withConfigLock<T>(task: () => T): T {
  if (holdingConfigLock) return task();
  mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
  return withFileLock(`${CONFIG_FILE}.lock`, fs, () => {
    holdingConfigLock = true;
    try {
      return task();
    } finally {
      holdingConfigLock = false;
    }
  });
}

function persistConfig(config: HyperframesConfig): ConfigWriteResult {
  try {
    mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
    const tmpFile = `${CONFIG_FILE}.${process.pid}.tmp`;
    writeFileSync(tmpFile, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
    renameSync(tmpFile, CONFIG_FILE);
    cachedConfig = { ...config };
    // Mirror into the install-state file (marker + tripped breaker) so no
    // breaker write site has to remember to do it. A failed mirror does NOT
    // fail the config write — config.json landed, and the latch is merged
    // back in on read — but it is reported rather than swallowed so a caller
    // persisting a tripped breaker can tell the safety fact only reached one
    // of the two stores.
    const mirrored = syncInstallState(config);
    return mirrored ? { ok: true } : { ok: true, mirrored: false };
  } catch (error) {
    // Non-fatal — telemetry should never break the CLI
    return { ok: false, error: normalizeErrorMessage(error) };
  }
}

/**
 * Increment the command counter and persist.
 */
export function incrementCommandCount(): number {
  const config = readConfig();
  config.commandCount++;
  writeConfig(config);
  return config.commandCount;
}

/** Expose the config directory path for the telemetry command output */
export const CONFIG_PATH = CONFIG_FILE;

/** Expose the install-state path for the telemetry command output. */
export const STATE_PATH = STATE_FILE;