mirror-mind 0.33.0 → 0.33.1

package/ts/src/util/tarEntries.ts

@@ -0,0 +1,128 @@
+// Named entries out of a gzipped tar archive, in memory. (CR134)
+//
+// A package's pending release notes are read from the channel version's
+// tarball, which `npm pack` fetched across a trust boundary: the registry is
+// whatever the npm config names, and a project's `.npmrc` can name it (CR135).
+// So nothing here writes a file, and no entry name becomes a path or an
+// argument -- the caller asks for names and gets bytes. That is also why `tar`
+// is not spawned: it would take archive-chosen member names as arguments.
+// Inflation stops at a bound, because a small gzip can inflate to gigabytes.
+//
+// What is read is what tar writers produce: ustar headers with the POSIX
+// `prefix` field, pax extended headers (`x`, whose `path` names the next
+// entry), and GNU long names (`L`). Every header's checksum is checked, and an
+// archive that stops before its end-of-archive block is refused rather than
+// half-read: a tarball cut between two entries would otherwise lose the later
+// ones -- the newest note among them -- without a word.
+
+import { gunzipSync } from "node:zlib";
+
+const BLOCK = 512;
+const USTAR_MAGIC = Buffer.from("ustar\0", "latin1");
+
+/** The bound on inflated bytes. A release tarball inflates to a few MB. */
+export const MAX_INFLATED_BYTES = 64 * 1024 * 1024;
+
+export type TarEntries = { ok: true; entries: Map<string, Buffer> } | { ok: false; detail: string };
+
+/** A NUL-terminated header field. */
+function field(bytes: Buffer): string {
+  const end = bytes.indexOf(0);
+  return bytes.subarray(0, end === -1 ? bytes.length : end).toString("utf8");
+}
+
+/** An octal header number, or null when the field holds anything else. */
+function octal(bytes: Buffer): number | null {
+  const value = field(bytes).trim();
+  return /^[0-7]+$/.test(value) ? Number.parseInt(value, 8) : null;
+}
+
+/** The checksum counts the header with its own field read as spaces. */
+function checksumHolds(header: Buffer): boolean {
+  const recorded = octal(header.subarray(148, 156));
+  if (recorded === null) return false;
+  let sum = 0;
+  for (let index = 0; index < BLOCK; index += 1) {
+    sum += index >= 148 && index < 156 ? 0x20 : (header[index] as number);
+  }
+  return sum === recorded;
+}
+
+/** The `path` record of a pax extended header: records are `<len> <key>=<value>\n`. */
+function paxPath(data: Buffer): string | null {
+  let path: string | null = null;
+  let offset = 0;
+  while (offset < data.length) {
+    const space = data.indexOf(0x20, offset);
+    if (space === -1) break;
+    const length = Number.parseInt(data.subarray(offset, space).toString("latin1"), 10);
+    if (!Number.isInteger(length) || length <= 0 || offset + length > data.length) break;
+    const record = data.subarray(space + 1, offset + length - 1).toString("utf8");
+    const equals = record.indexOf("=");
+    if (equals !== -1 && record.slice(0, equals) === "path") path = record.slice(equals + 1);
+    offset += length;
+  }
+  return path;
+}
+
+/**
+ * The regular-file entries of a gzipped tar whose names `wanted` accepts.
+ * Refuses, with a reason, an archive that inflates past the bound, is not
+ * gzip, fails a header checksum, or ends inside an entry.
+ */
+export function readTarGzEntries(
+  gz: Buffer,
+  wanted: (name: string) => boolean,
+  maxInflatedBytes: number = MAX_INFLATED_BYTES,
+): TarEntries {
+  let tar: Buffer;
+  try {
+    tar = gunzipSync(gz, { maxOutputLength: maxInflatedBytes });
+  } catch (error) {
+    if ((error as { code?: string }).code === "ERR_BUFFER_TOO_LARGE") {
+      return { ok: false, detail: `the archive inflates to more than ${maxInflatedBytes} bytes` };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: false, detail: `unreadable gzip: ${message}` };
+  }
+
+  const entries = new Map<string, Buffer>();
+  let nextName: string | null = null;
+  let offset = 0;
+  while (offset + BLOCK <= tar.length) {
+    const header = tar.subarray(offset, offset + BLOCK);
+    if (header.every((byte) => byte === 0)) return { ok: true, entries };
+    if (!checksumHolds(header)) {
+      return { ok: false, detail: `the tar header at byte ${offset} fails its checksum` };
+    }
+    const size = octal(header.subarray(124, 136));
+    if (size === null) {
+      return { ok: false, detail: `the tar header at byte ${offset} has an unreadable size` };
+    }
+    const start = offset + BLOCK;
+    const end = start + size;
+    if (end > tar.length) return { ok: false, detail: "the archive is truncated" };
+    const data = tar.subarray(start, end);
+    const type = String.fromCharCode(header[156] as number);
+
+    if (type === "x") {
+      nextName = paxPath(data) ?? nextName;
+    } else if (type === "L") {
+      nextName = field(data);
+    } else if (type !== "g") {
+      const prefix = header.subarray(257, 263).equals(USTAR_MAGIC)
+        ? field(header.subarray(345, 500))
+        : "";
+      const base = field(header.subarray(0, 100));
+      const name = nextName ?? (prefix ? `${prefix}/${base}` : base);
+      nextName = null;
+      if ((type === "0" || type === "\0") && wanted(name)) entries.set(name, Buffer.from(data));
+    }
+    offset = start + Math.ceil(size / BLOCK) * BLOCK;
+  }
+  // The archive stopped before its end-of-archive block: inside an entry's
+  // padding, or cleanly between two entries. Entries after the last whole one
+  // may be missing, so nothing read here is presented as the whole (CI at
+  // 565b7b97 met the first; the second is the general case).
+  return { ok: false, detail: "the archive is truncated" };
+}

package/ts/src/welcome/card.ts

@@ -2,36 +2,53 @@
 // `compose_welcome` from `src/memory/cli/welcome.py`.
 //
 // Unlike the status line, the card MAY reach the network: on the stable
-// channel it performs a bounded remote update check so a newly published
-// release becomes visible without manual cache repair. That check is
-// TTL-guarded, refresh-guarded, and switched off entirely by
+// channel it performs a bounded remote update check at every render, so a
+// newly published release becomes visible at the next session start. The
+// check is switched off entirely by
 // `MIRROR_WELCOME_REMOTE_UPDATE_CHECK=off|0|false|no`.
 //
+// The check asks the RUNNING INSTALL, never the cwd (CR135). Pi renders the
+// card in the person's project, and the oracle asked whatever repository that
+// was: a project with a tagged `origin/stable` made the card announce its tag.
+// A package now reads its channel's dist-tag, as `runtime update --check`
+// does, with npm run in the install's own root; a clone asks its own checkout
+// and its own remote. One budget bounds the remote reads of a render.
+//
 // Date rendering is done by hand from `_MONTH_ABBR`, never through
 // `toLocaleDateString`: the oracle formats the month itself, so a locale-aware
 // TypeScript formatter would render "since ago. 2025" on a machine whose
 // locale is not English and call it parity.
 
 import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { basename, join } from "node:path";
 import { type Database, openDatabaseReadOnly } from "#db/database.ts";
 import { dbNameForEnv } from "#frontDoor/dbPath.ts";
 import { listJourneysForListCommand } from "#identity/journeyListing.ts";
+import { channelFor } from "#runtime/channel.ts";
 import {
   checkUpdateAvailability,
+  GIT_NETWORK_TIMEOUT_MS,
   type GitStatus,
   inspectGit,
   inspectGitUpdatePlan,
   type MarkerValue,
+  NO_REPOSITORY,
   runGit,
 } from "#runtime/git.ts";
+import type { InstallKind } from "#runtime/installKind.ts";
+import {
+  checkPackageUpdateAvailability,
+  defaultNpmRunner,
+  type NpmRunner,
+} from "#runtime/strategies/package.ts";
 import { compareSemver } from "#util/semver.ts";
 import { SEPARATOR } from "./statusLine.ts";
 import {
-  cacheIsStale,
-  cacheShouldRefresh,
+  isoNow,
   readUpdateCache,
   type UpdateAwareness,
+  verdictApplies,
   writeUpdateCache,
 } from "./updateCache.ts";
 
@@ -159,16 +176,21 @@ function commitsMatch(candidate: string, target: string): boolean {
  * Port of `_remote_tag_for_commit`: which published tag names the commit the
  * remote is at. `^{}` refs are the dereferenced peel of an annotated tag and
  * are skipped, so a tag is not counted twice.
+ *
+ * A network read: it ran on git's 2 s LOCAL budget until CR135, so a lookup
+ * slower than that cached an update without its version. The card passes
+ * what is left of its own budget.
  */
 export function remoteTagForCommit(
   upstream: string,
   remoteCommit: string,
   repository: string | null,
+  timeoutMs: number = GIT_NETWORK_TIMEOUT_MS,
 ): string | null {
   if (!upstream.includes("/")) return null;
   const remote = upstream.split("/", 1)[0] as string;
   if (repository === null) return null;
-  const result = runGit(["ls-remote", "--tags", remote, "refs/tags/v*"], repository);
+  const result = runGit(["ls-remote", "--tags", remote, "refs/tags/v*"], repository, timeoutMs);
   if (result.code !== 0 || !result.stdout) return null;
 
   const matches: string[] = [];
@@ -206,76 +228,174 @@ export function localReleaseTitle(version: string | null, treeRoot: string): str
   return null;
 }
 
+/** How long the card's remote reads may take, together (CR135, decision 1). */
+export const WELCOME_REMOTE_BUDGET_MS = 5_000;
+
 export interface WelcomeOptions {
   /** The resolved mirror home. Null renders "", as in the oracle. */
   mirrorHome: string | null;
-  /** Where git is inspected for the update check (a clone's working tree). */
-  cwd?: string;
-  /** The tree holding the running program, where `docs/releases` is read. Defaults to `cwd`. */
-  treeRoot?: string;
+  /**
+   * The running install, detected from where the front door lives. The card's
+   * channel, its update check, and its "commits behind" line are this
+   * install's, whatever the cwd (CR135).
+   */
+  install: InstallKind;
   env?: NodeJS.ProcessEnv;
   version: string;
-  updateChannel: MarkerValue;
+  /** The OS home whose config directory holds a package's channel file. */
+  osHome?: string;
+  /** The npm seam, injected as the update route's is. */
+  npm?: NpmRunner;
+  /** The budget of the remote reads; production takes `WELCOME_REMOTE_BUDGET_MS`. */
+  remoteBudgetMs?: number;
   /** Injected only so the written cache is byte-comparable; production omits it. */
   now?: () => string;
 }
 
-/** Port of `_iso_now`. */
-function isoNow(): string {
-  return new Date().toISOString().replace(/\.(\d{3})Z$/, ".$1000+00:00");
+/** What one render's remote check asked, how it answered, and how long it took. */
+export interface RemoteCheck {
+  source: "registry" | "git";
+  verdict: string;
+  ms: number;
 }
 
-/** Port of `_refresh_update_cache`. Any failure leaves the cache untouched. */
-function refreshUpdateCache(
-  homePath: string,
+export interface WelcomeRender {
+  card: string;
+  /** Null when no remote check ran. */
+  check: RemoteCheck | null;
+}
+
+interface CheckSeams {
+  npm: NpmRunner;
+  budgetMs: number;
+  now: () => string;
+}
+
+type CheckedInstall = Exclude<InstallKind, { kind: "unknown" }>;
+
+/**
+ * A package's verdict: its channel's dist-tag, read as `runtime update
+ * --check` reads it, in the install's own root. One read, so it gets the
+ * whole budget, and no retries: unanswered, npm retries for over a minute.
+ */
+function checkPackage(
+  install: Extract<InstallKind, { kind: "package" }>,
+  channel: MarkerValue,
+  seams: CheckSeams,
+): UpdateAwareness {
+  const report = checkPackageUpdateAvailability(install, channel, seams.npm, {
+    timeoutMs: seams.budgetMs,
+    fetchRetries: 0,
+  });
+  const version =
+    report.status === "update_available" && report.resolved !== null ? `v${report.resolved}` : null;
+  return {
+    // `unresolved` is the cache's `unknown`: the check could not answer.
+    availability: report.status === "unresolved" ? "unknown" : report.status,
+    checked_at: seams.now(),
+    channel: channel.value,
+    current_commit: null,
+    remote_commit: null,
+    version,
+    title: localReleaseTitle(version, install.root),
+    note: report.note,
+  };
+}
+
+/**
+ * Port of `_refresh_update_cache`'s question, asked of the clone's own
+ * checkout. The `ls-remote` and then the tag lookup share one deadline.
+ */
+function checkClone(
+  repository: string,
   channel: MarkerValue,
-  cwd: string,
-  treeRoot: string,
   version: string,
-  now: () => string,
-): UpdateAwareness | null {
-  let report: ReturnType<typeof checkUpdateAvailability>;
-  try {
-    report = checkUpdateAvailability(cwd, channel.value, version);
-  } catch {
-    return null;
-  }
+  seams: CheckSeams,
+): UpdateAwareness {
+  const deadline = Date.now() + seams.budgetMs;
+  // At least 1 ms: a spawn timeout of 0 is no timeout at all.
+  const report = checkUpdateAvailability(
+    repository,
+    channel.value,
+    version,
+    Math.max(1, deadline - Date.now()),
+  );
   let tag: string | null = null;
-  let title: string | null = null;
   if (report.status === "update_available" && report.remote_commit && report.upstream) {
-    tag = remoteTagForCommit(report.upstream, report.remote_commit, inspectGit(cwd).repository);
-    title = localReleaseTitle(tag, treeRoot);
+    const left = deadline - Date.now();
+    if (left >= 1)
+      tag = remoteTagForCommit(report.upstream, report.remote_commit, repository, left);
   }
-  const awareness: UpdateAwareness = {
+  return {
     availability: report.status,
-    checked_at: now(),
+    checked_at: seams.now(),
     channel: channel.value,
     current_commit: report.local_commit,
     remote_commit: report.remote_commit,
     version: tag,
-    title,
+    title: localReleaseTitle(tag, repository),
     note: report.note,
   };
-  if (report.status === "up_to_date" || report.status === "update_available") {
-    writeUpdateCache(homePath, awareness);
+}
+
+function checkInstall(
+  install: CheckedInstall,
+  channel: MarkerValue,
+  version: string,
+  seams: CheckSeams,
+): UpdateAwareness {
+  try {
+    return install.kind === "package"
+      ? checkPackage(install, channel, seams)
+      : checkClone(install.repository, channel, version, seams);
+  } catch (error) {
+    return {
+      availability: "unknown",
+      checked_at: seams.now(),
+      channel: channel.value,
+      current_commit: null,
+      remote_commit: null,
+      version: null,
+      title: null,
+      note: error instanceof Error ? error.message : String(error),
+    };
   }
-  return awareness;
 }
 
-/** Port of `_update_awareness`: cache first, remote only when it must. */
+/**
+ * Port of `_update_awareness`, asking the install instead of the cwd.
+ *
+ * On `stable` the install is asked at every render; on `main`, never. Only
+ * `up_to_date` and `update_available` are written. A check that could not
+ * answer (`unknown`) leaves the cache as it is, and the card shows what the
+ * cache knows, as the status line does. Any other answer (`local_ahead`,
+ * `diverged`, `channel_behind`) is an answer: no update to take, and nothing
+ * written.
+ */
 export function updateAwareness(
   homePath: string,
+  install: InstallKind,
   channel: MarkerValue,
-  cwd: string,
   version: string,
   env: NodeJS.ProcessEnv,
-  now: () => string,
-  treeRoot: string = cwd,
-): UpdateAwareness | null {
+  seams: CheckSeams,
+): { awareness: UpdateAwareness | null; check: RemoteCheck | null } {
   const cached = readUpdateCache(homePath);
-  if (cached && !cacheIsStale(cached) && !cacheShouldRefresh(cached, channel)) return cached;
-  if (remoteUpdateCheckDisabled(env) || channel.value !== "stable") return cached;
-  return refreshUpdateCache(homePath, channel, cwd, treeRoot, version, now) ?? cached;
+  if (remoteUpdateCheckDisabled(env) || channel.value !== "stable" || install.kind === "unknown") {
+    return { awareness: cached, check: null };
+  }
+  const started = Date.now();
+  const fresh = checkInstall(install, channel, version, seams);
+  const check: RemoteCheck = {
+    source: install.kind === "package" ? "registry" : "git",
+    verdict: fresh.availability,
+    ms: Date.now() - started,
+  };
+  if (fresh.availability === "up_to_date" || fresh.availability === "update_available") {
+    writeUpdateCache(homePath, fresh);
+    return { awareness: fresh, check };
+  }
+  return { awareness: fresh.availability === "unknown" ? cached : fresh, check };
 }
 
 /** Port of `_update_line`. */
@@ -315,25 +435,27 @@ export function updateLine(
  * mirror home: a fresh database with nothing in it still renders the full card
  * with zeroes.
  */
-export function composeWelcome(options: WelcomeOptions): string {
+export function composeWelcome(options: WelcomeOptions): WelcomeRender {
   const homePath = options.mirrorHome;
-  if (homePath === null) return "";
-  const cwd = options.cwd ?? process.cwd();
+  if (homePath === null) return { card: "", check: null };
   const env = options.env ?? process.env;
-  const now = options.now ?? isoNow;
+  const install = options.install;
+  // Nothing here reads the cwd (CR135): the channel is the one `runtime
+  // channel` reports for this install, and so is everything below.
+  const channel = channelFor(install, env, options.osHome ?? homedir());
 
   const dbPath = join(homePath, dbNameForEnv(env.MEMORY_ENV || "production"));
   const stats = formatStats(readWelcomeStats(existsSync(dbPath) ? dbPath : null));
-  const versionLine = `${options.version} · channel ${options.updateChannel.value}`;
-  const awareness = updateAwareness(
-    homePath,
-    options.updateChannel,
-    cwd,
-    options.version,
-    env,
-    now,
-    options.treeRoot ?? cwd,
-  );
-  const update = updateLine(options.updateChannel, awareness, inspectGit(cwd));
-  return renderWelcome(basename(homePath), stats, versionLine, update);
+  const versionLine = `${options.version} · channel ${channel.value}`;
+  const { awareness, check } = updateAwareness(homePath, install, channel, options.version, env, {
+    npm: options.npm ?? defaultNpmRunner,
+    budgetMs: options.remoteBudgetMs ?? WELCOME_REMOTE_BUDGET_MS,
+    now: options.now ?? isoNow,
+  });
+  // A cached update the install already has is not shown (CR135).
+  const shown = awareness !== null && verdictApplies(awareness, options.version) ? awareness : null;
+  // A package has no checkout to be behind: its "commits behind" line is none.
+  const git = install.kind === "clone" ? inspectGit(install.repository) : NO_REPOSITORY;
+  const update = updateLine(channel, shown, git);
+  return { card: renderWelcome(basename(homePath), stats, versionLine, update), check };
 }

package/ts/src/welcome/statusLine.ts

@@ -10,6 +10,10 @@
 // It reads the update CACHE, never the remote -- refreshing the cache is the
 // full card's job, and the one time that budget was allowed to leak into the
 // per-turn path it cost a 120s network timeout on a status bar.
+//
+// Since CR135 it also drops a cached update the install already has. The
+// installed version is the caller's: the route reads it from the running
+// tree's manifest, a file read, so this module still spawns nothing.
 
 import { existsSync } from "node:fs";
 import { basename, join } from "node:path";
@@ -18,13 +22,15 @@ import { dbNameForEnv } from "#frontDoor/dbPath.ts";
 import { getIdentityContent } from "#identity/identityRead.ts";
 import { GLOBAL_STICKY_DEFAULTS_SESSION_ID, getRuntimeSession } from "#mirror/runtimeSession.ts";
 import { getActiveOperatingMode, modeLabel } from "#mode/operatingMode.ts";
-import { readUpdateCache } from "./updateCache.ts";
+import { readUpdateCache, verdictApplies } from "./updateCache.ts";
 
 export const SEPARATOR = " · ";
 
 export interface StatusLineOptions {
   /** The resolved mirror home. Null renders nothing, as in the oracle. */
   mirrorHome: string | null;
+  /** The running install's version: a cached update to it, or to an older one, is not shown. */
+  installedVersion: string;
   sessionId?: string | null;
   env?: NodeJS.ProcessEnv;
 }
@@ -92,7 +98,11 @@ export function composeStatusLine(options: StatusLineOptions): string {
   if (mode) parts.push(mode);
 
   const awareness = readUpdateCache(homePath);
-  if (awareness && awareness.availability === "update_available") {
+  if (
+    awareness &&
+    awareness.availability === "update_available" &&
+    verdictApplies(awareness, options.installedVersion)
+  ) {
     parts.push(`⬆${awareness.version ? ` ${awareness.version}` : ""}`);
   } else {
     parts.push("✓");

package/ts/src/welcome/updateCache.ts

@@ -7,14 +7,19 @@
 // nicety: two cores that serialize the same state differently would rewrite the
 // file on every alternating invocation and thrash the 6h TTL, turning a bounded
 // remote check into one on every turn.
+//
+// CR135 removed that TTL, which gated nothing: on `stable` every verdict the
+// card writes is refreshed at the next render, and on `main` the card never
+// checks. What a reader needs instead is to know whether a verdict still
+// APPLIES to the install reading it (`verdictApplies`), and a successful
+// `runtime update` now says what it installed (`recordUpToDate`).
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import type { MarkerValue } from "#runtime/git.ts";
 import { pythonJsonDumpsIndented } from "#util/pyGenerators.ts";
+import { compareSemver } from "#util/semver.ts";
 
 export const UPDATE_CHECK_CACHE = "runtime/update-check.json";
-export const UPDATE_CHECK_TTL_MS = 6 * 60 * 60 * 1000;
 
 export interface UpdateAwareness {
   availability: string;
@@ -92,38 +97,51 @@ export function writeUpdateCache(homePath: string, awareness: UpdateAwareness):
   }
 }
 
-/** Port of `_parse_iso`, narrowed to the timestamps this cache carries. */
-export function parseIso(value: string | null): Date | null {
-  if (!value) return null;
-  const parsed = Date.parse(value.replace("Z", "+00:00"));
-  return Number.isNaN(parsed) ? null : new Date(parsed);
+/** Port of `_iso_now`: the cache's timestamp shape, microseconds and all. */
+export function isoNow(): string {
+  return new Date().toISOString().replace(/\.(\d{3})Z$/, ".$1000+00:00");
 }
 
 /**
- * Port of `_cache_is_stale`. A timestamp that cannot be parsed is stale, not
- * fresh -- the safe direction for a cache that gates a network call.
+ * Does a cached verdict still apply to the install reading it? (CR135)
  *
- * A NAIVE timestamp (no offset) is read as UTC, matching the oracle's explicit
- * `replace(tzinfo=timezone.utc)`. JavaScript would otherwise read it as local
- * time and shift the TTL by the machine's offset.
+ * One verdict goes stale in a way the reader can see: an update to a version
+ * the install already has, or has passed -- after an update, after a manual
+ * install, or when another install over the same home wrote it. Such a
+ * verdict is not shown, by the card or by the status line. A verdict without
+ * a version, from a clone's tag lookup that found none, cannot be judged and
+ * stands. A version that does not parse as `vX.Y.Z` sorts below every real one
+ * (`#util/semver.ts`), so it is never newer and is not shown.
  */
-export function cacheIsStale(awareness: UpdateAwareness, now: Date = new Date()): boolean {
-  const hasOffset = /(?:Z|[+-]\d{2}:\d{2})$/.test(awareness.checked_at);
-  const checkedAt = parseIso(hasOffset ? awareness.checked_at : `${awareness.checked_at}Z`);
-  if (checkedAt === null) return true;
-  return now.getTime() - checkedAt.getTime() > UPDATE_CHECK_TTL_MS;
+export function verdictApplies(awareness: UpdateAwareness, installedVersion: string): boolean {
+  if (awareness.availability !== "update_available" || awareness.version === null) return true;
+  return compareSemver(awareness.version, installedVersion) > 0;
+}
+
+export interface UpToDateRecord {
+  /** The channel the update followed. */
+  channel: string;
+  /** A clone's commit after the update; null for a package, which has none. */
+  commit: string | null;
+  checkedAt: string;
 }
 
 /**
- * Port of `_cache_should_refresh`: stable-channel awareness is refreshed even
- * inside the TTL. A cached notice may point at an intermediate release, and a
- * cached up-to-date answer goes wrong the moment stable advances -- opening
- * Mirror should show the newly published version without manually fetching
- * refs or deleting this file.
+ * What a successful `runtime update` knows, written where the card and the
+ * status line read it (CR135): the install now holds its channel's version.
+ * Until CR135 nothing rewrote the cache after an update, so the status line
+ * kept announcing the version just installed until some later check, from
+ * some repository, said otherwise.
  */
-export function cacheShouldRefresh(awareness: UpdateAwareness, channel: MarkerValue): boolean {
-  return (
-    (awareness.availability === "up_to_date" || awareness.availability === "update_available") &&
-    channel.value === "stable"
-  );
+export function recordUpToDate(homePath: string, record: UpToDateRecord): void {
+  writeUpdateCache(homePath, {
+    availability: "up_to_date",
+    checked_at: record.checkedAt,
+    channel: record.channel,
+    current_commit: record.commit,
+    remote_commit: record.commit,
+    version: null,
+    title: null,
+    note: null,
+  });
 }