refactor(update): move notifier policy to services

Author: kushagrchitkar

docs/intentional-architecture-rewrite-2026-06-27/status.md

@@ -5,7 +5,7 @@ Branch: `codex/intentional-architecture-rewrite`
 
 ## Current State
 
-The branch has more than 250 committed rewrite commits past `dev`. The worklog records 211 production slices so far.
+The branch has more than 250 committed rewrite commits past `dev`. The worklog records 212 production slices so far.
 
 The diff is broad: more than 490 files changed, with tens of thousands of lines reshaped.
 
@@ -53,6 +53,7 @@ This is no longer a small cleanup branch. It is a real ownership rewrite.
 - Moved update state and install-lock persistence into `src/stores/update/`; platform update modules now own registry/npm/version behavior, not JSON state-file mechanics.
 - Moved update registry/version/install mechanics behind a service-owned `UpdateRuntime` contract, with the real runtime composed in the CLI edge.
 - Moved update check/cache workflow into `src/services/update/check.ts`, registry fetch mechanics into `src/platform/update/check.ts`, and concrete runtime composition into `src/app/update-runtime.ts`.
+- Moved update notifier/banner eligibility into `src/services/update/notifier.ts`, CLI banner rendering into `src/edges/cli/update-announcement.ts`, and detached update-check process spawning into `src/platform/update/notifier-worker.ts`.
 - Moved GitHub source resolution mechanics into `src/platform/github/`.
 - Moved Absorb source resolver composition into `src/platform/sources/absorb.ts` and the CLI edge, so lifecycle Absorb services no longer import platform GitHub mechanics.
 - Moved Absorb source-ref and resolved-source contracts into `src/shared/absorb-sources.ts`, so platform source resolvers no longer import lifecycle service-internal Absorb files.
@@ -86,23 +87,23 @@ This is no longer a small cleanup branch. It is a real ownership rewrite.
 
 ## Latest Checkpoint
 
-The latest slice moved update cache/check workflow out of platform and into `src/services/update/check.ts`, added `src/shared/update-runtime.ts` for update runtime contracts, replaced `src/platform/update/check.ts` with a registry-only latest-version fetcher, and added `src/app/update-runtime.ts` as the concrete composition point. Platform update modules no longer own update-state cache policy.
+The latest slice moved update notifier/banner eligibility and background-check scheduling policy out of platform and into `src/services/update/notifier.ts`, added a config-store sync read for startup-time notifier checks, moved banner rendering into `src/edges/cli/update-announcement.ts`, and reduced `src/platform/update/notifier-worker.ts` to detached process spawning.
 
 Verification passed:
 
 - `git diff --check`
 - `npm run lint`
-- `npx vitest run test/architecture-boundaries.test.ts test/update-check.test.ts test/update.test.ts test/update-install.test.ts test/update-store.test.ts test/update-announce.test.ts test/cli.test.ts`
+- `npx vitest run test/architecture-boundaries.test.ts test/update-announce.test.ts test/update.test.ts test/update-check.test.ts test/cli.test.ts test/config-command.test.ts test/doctor.test.ts`
 - `npm test`
 - `npm run build`
-- `node dist/launcher.js update --help | head -50`
-- `node dist/launcher.js doctor --json --install-only`
-- `node dist/launcher.js --help | head -25`
+- `node dist/launcher.js --help`
+- `node dist/launcher.js update --help`
 - `node dist/launcher.js update --check`
+- `node dist/launcher.js doctor --json --install-only`
 
 ## Immediate Next Work
 
-Continue top-down subsystem passes before small leak cleanup. The major loose source buckets for jobs, init, config, wiki, viewer read models, worker entrypoints, serve process lifetime, setup/uninstall terminal UI, wiki file mechanics, automation scheduler mechanics, automation scheduler app composition, setup instruction runtime composition, provider setup-view ownership, job provider-runner composition, job-worker process spawning, Absorb source resolver composition, Absorb source contract ownership, prompt loader mechanics, update runtime composition, setup runtime composition, sync transcript runtime composition, sync-to-job session lookup, CLI app composition, diagnostic fact contracts, provider-neutral agent runtime contracts, lock process-liveness contracts, operation-spec type ownership, init prompt-context ownership, config command validation ownership, store atomic-write ownership, review command markdown ownership, and lifecycle workflow type ownership have now been removed or assigned. Remaining candidates include command files that still own workflow decisions, remaining platform modules that read config/store state directly, lifecycle/job boundary duplication that remains after the big moves, and large files whose size may still reflect mixed ownership.
+Continue top-down subsystem passes before small leak cleanup. The major loose source buckets for jobs, init, config, wiki, viewer read models, worker entrypoints, serve process lifetime, setup/uninstall terminal UI, wiki file mechanics, automation scheduler mechanics, automation scheduler app composition, setup instruction runtime composition, provider setup-view ownership, job provider-runner composition, job-worker process spawning, Absorb source resolver composition, Absorb source contract ownership, prompt loader mechanics, update runtime composition, update notifier ownership, setup runtime composition, sync transcript runtime composition, sync-to-job session lookup, CLI app composition, diagnostic fact contracts, provider-neutral agent runtime contracts, lock process-liveness contracts, operation-spec type ownership, init prompt-context ownership, config command validation ownership, store atomic-write ownership, review command markdown ownership, and lifecycle workflow type ownership have now been removed or assigned. Remaining candidates include command files that still own workflow decisions, remaining platform modules that read config/store state directly, lifecycle/job boundary duplication that remains after the big moves, and large files whose size may still reflect mixed ownership.
 
 ## Decision Log
 

docs/intentional-architecture-rewrite-2026-06-27/worklog.md

@@ -1472,3 +1472,12 @@ Two-hundred-eleventh production slice:
 - Added `src/app/update-runtime.ts` as the concrete composition point for service check/cache workflow plus platform registry fetch, installed-version reads, and npm install mechanics.
 - Deleted `src/platform/update/runtime.ts` and rewired CLI setup/update paths to use app update runtime composition.
 - Strengthened architecture-boundary tests so platform update check no longer imports update stores and service update check no longer imports platform registry mechanics.
+
+Two-hundred-twelfth production slice:
+
+- Added `src/services/update/notifier.ts` as the service owner for update banner eligibility, notifier-enabled config reads, and background update-check scheduling policy.
+- Added `readConfigSync` to `src/stores/config/store.ts` so startup-time config reads stay in store ownership instead of platform code parsing config files directly.
+- Moved update banner rendering from `src/platform/update/announce.ts` into the CLI edge at `src/edges/cli/update-announcement.ts`.
+- Added `src/edges/cli/update-check-scheduler.ts` to compose service scheduling policy with platform detached-process spawning.
+- Reduced `src/platform/update/notifier-worker.ts` to process mechanics only and deleted `src/platform/update/announce.ts`.
+- Strengthened architecture-boundary tests so platform update modules no longer import config or update stores for notifier behavior.

src/edges/cli/run.ts

@@ -16,8 +16,8 @@ import { runCodealmanacBootstrap } from "../../platform/install/global.js";
 import { isLocalPidAlive } from "../../platform/process.js";
 import type { runDoctor } from "../../cli/commands/doctor/index.js";
 import { runInternalUpdateCheck } from "../../app/update-runtime.js";
-import { announceUpdateIfAvailable } from "../../platform/update/announce.js";
-import { scheduleBackgroundUpdateCheck } from "../../platform/update/notifier-worker.js";
+import { announceUpdateIfAvailable } from "./update-announcement.js";
+import { scheduleBackgroundUpdateCheck } from "./update-check-scheduler.js";
 
 /**
  * Optional dependency overrides for `run`. Tests use these to avoid

src/edges/cli/update-announcement.ts

@@ -0,0 +1,39 @@
+import { makeAnsiTheme } from "../../ansi-theme.js";
+import { readUpdateAnnouncement } from "../../services/update/index.js";
+import { readInstalledVersion } from "../../platform/update/version.js";
+
+export interface AnnounceUpdateOptions {
+  statePath?: string;
+  configPath?: string;
+  installedVersion?: string;
+  color?: boolean;
+}
+
+export function announceUpdateIfAvailable(
+  stderr: NodeJS.WritableStream,
+  opts: AnnounceUpdateOptions = {},
+): void {
+  const announcement = readUpdateAnnouncement({
+    statePath: opts.statePath,
+    configPath: opts.configPath,
+    installedVersion: opts.installedVersion ?? readInstalledVersion(),
+  });
+  if (announcement === null) return;
+
+  const useColor = opts.color ?? shouldUseStreamColor(stderr);
+  const theme = makeAnsiTheme(useColor);
+  const warn = useColor ? `${theme.YELLOW}${theme.BOLD}\u26a0${theme.RST}` : "!";
+  const cmd = `${theme.BOLD}almanac update${theme.RST}`;
+  stderr.write(
+    `${warn} Almanac ${announcement.latestVersion} available ` +
+      `(you're on ${announcement.installedVersion}) — run: ${cmd}\n`,
+  );
+}
+
+function shouldUseStreamColor(stream: NodeJS.WritableStream): boolean {
+  return streamIsTTY(stream) && !("NO_COLOR" in process.env);
+}
+
+function streamIsTTY(stream: NodeJS.WritableStream): boolean {
+  return (stream as NodeJS.WritableStream & { isTTY?: boolean }).isTTY === true;
+}

src/edges/cli/update-check-scheduler.ts

@@ -0,0 +1,7 @@
+import { shouldScheduleUpdateCheck } from "../../services/update/index.js";
+import { spawnBackgroundUpdateCheck } from "../../platform/update/notifier-worker.js";
+
+export function scheduleBackgroundUpdateCheck(argv: string[]): void {
+  if (!shouldScheduleUpdateCheck({ argv, environment: process.env })) return;
+  spawnBackgroundUpdateCheck(argv);
+}

src/platform/update/announce.ts

@@ -1,11 +1,4 @@
 import { spawn } from "node:child_process";
-import { readFileSync } from "node:fs";
-
-import {
-  getConfigPath,
-  getLegacyConfigPath,
-  parseConfigText,
-} from "../../stores/config/index.js";
 
 /**
  * Post-command worker for the update-notifier cache.
@@ -16,9 +9,7 @@ import {
  * live under `src/platform/automation/`.
  */
 
-export function scheduleBackgroundUpdateCheck(argv: string[]): void {
-  if (!shouldSchedule(argv)) return;
-
+export function spawnBackgroundUpdateCheck(argv: string[]): void {
   const scriptPath = argv[1];
   const nodeBin = process.execPath;
   if (scriptPath === undefined || scriptPath.length === 0) return;
@@ -38,28 +29,3 @@ export function scheduleBackgroundUpdateCheck(argv: string[]): void {
     // Background checks are best-effort.
   }
 }
-
-function shouldSchedule(argv: string[]): boolean {
-  if (process.env.CODEALMANAC_SKIP_UPDATE_CHECK === "1") return false;
-  if (process.env.NODE_ENV === "test") return false;
-  if (process.env.VITEST !== undefined) return false;
-  if (argv.slice(2).includes("--internal-check-updates")) return false;
-  if (!notifierEnabled()) return false;
-  return true;
-}
-
-function notifierEnabled(): boolean {
-  const parsed = readConfigSync(getConfigPath());
-  if (parsed !== null) return parsed.update_notifier !== false;
-  const legacy = readConfigSync(getLegacyConfigPath());
-  return legacy?.update_notifier !== false;
-}
-
-function readConfigSync(path: string): { update_notifier?: unknown } | null {
-  try {
-    const raw = readFileSync(path, "utf8");
-    return parseConfigText(raw, path) as { update_notifier?: unknown };
-  } catch {
-    return null;
-  }
-}

src/platform/update/notifier-worker.ts

@@ -1,5 +1,13 @@
 export { runUpdateWorkflow } from "./update.js";
 export { checkForUpdate, type CheckForUpdateOptions } from "./check.js";
+export {
+  readUpdateAnnouncement,
+  readUpdateNotifierEnabled,
+  shouldScheduleUpdateCheck,
+  type UpdateAnnouncement,
+  type UpdateAnnouncementOptions,
+  type UpdateCheckScheduleOptions,
+} from "./notifier.js";
 export type {
   UpdateCheckFn,
   UpdateInstallFn,

src/services/update/index.ts

@@ -0,0 +1,51 @@
+import { isNewerVersion } from "../../shared/version.js";
+import { readConfigSync } from "../../stores/config/index.js";
+import { readStateSync } from "../../stores/update/index.js";
+
+export interface UpdateAnnouncementOptions {
+  installedVersion: string;
+  statePath?: string;
+  configPath?: string;
+}
+
+export interface UpdateAnnouncement {
+  installedVersion: string;
+  latestVersion: string;
+}
+
+export interface UpdateCheckScheduleOptions {
+  argv: readonly string[];
+  environment: NodeJS.ProcessEnv;
+  configPath?: string;
+}
+
+export function readUpdateAnnouncement(
+  options: UpdateAnnouncementOptions,
+): UpdateAnnouncement | null {
+  if (!readUpdateNotifierEnabled(options.configPath)) return null;
+
+  const state = readStateSync(options.statePath);
+  if (state === null) return null;
+  if (state.latest_version.length === 0) return null;
+  if (!isNewerVersion(state.latest_version, options.installedVersion)) return null;
+  if (state.dismissed_versions.includes(state.latest_version)) return null;
+
+  return {
+    installedVersion: options.installedVersion,
+    latestVersion: state.latest_version,
+  };
+}
+
+export function readUpdateNotifierEnabled(configPath?: string): boolean {
+  return readConfigSync(configPath).update_notifier !== false;
+}
+
+export function shouldScheduleUpdateCheck(
+  options: UpdateCheckScheduleOptions,
+): boolean {
+  if (options.environment.CODEALMANAC_SKIP_UPDATE_CHECK === "1") return false;
+  if (options.environment.NODE_ENV === "test") return false;
+  if (options.environment.VITEST !== undefined) return false;
+  if (options.argv.slice(2).includes("--internal-check-updates")) return false;
+  return readUpdateNotifierEnabled(options.configPath);
+}

src/services/update/notifier.ts

@@ -25,6 +25,7 @@ export {
 export {
   ensureAutomationSyncSince,
   readConfig,
+  readConfigSync,
   readConfigWithOrigins,
   writeConfig,
   type ConfigReadOptions,