@golba98/codexa 1.0.2 → 1.0.4

package/src/core/terminal/frameLock.ts

@@ -0,0 +1,109 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isTerminalResizing } from "./terminalControl.js";
+
+export interface FrameLockOptions {
+  stdout: any;
+  env: Record<string, string | undefined>;
+}
+
+const resizeFrameCacheResetters = new WeakMap<object, () => void>();
+
+export function resetFrameLockForResize(stdout: object): void {
+  resizeFrameCacheResetters.get(stdout)?.();
+}
+
+/**
+ * Wraps the stdout stream to enforce frame-level deduplication, a flush lock,
+ * and width-safe row padding via ANSI clear-to-EOL (\x1b[K) injection.
+ */
+export function wrapStdoutWithFrameLock({
+  stdout,
+  env,
+}: FrameLockOptions) {
+  let lastFrame = "";
+  let isFlushing = false;
+  let debugLogStream: fs.WriteStream | null = null;
+
+  if (env.CODEXA_RENDER_DEBUG === "1") {
+    try {
+      const logPath = env.CODEXA_RENDER_DEBUG_FILE?.trim()
+        || path.join(process.cwd(), ".codexa", "debug", "render-status.log");
+      const logDir = path.dirname(logPath);
+      if (!fs.existsSync(logDir)) {
+        fs.mkdirSync(logDir, { recursive: true });
+      }
+      debugLogStream = fs.createWriteStream(logPath, { flags: "a" });
+    } catch (e) {
+      // Gracefully fall back if logging fails (e.g. read-only filesystem)
+      void e;
+    }
+  }
+
+  const logDebug = (msg: string) => {
+    if (debugLogStream) {
+      debugLogStream.write(`${new Date().toISOString()} ${msg}\n`);
+    }
+  };
+
+  const originalWrite = stdout.write.bind(stdout);
+
+  // A terminal resize can make an otherwise identical Ink frame meaningful:
+  // rows reflow at a new width and height-driven spacer/layout changes must be
+  // written even when their source text did not change. src/index.tsx owns the
+  // single resize listener and invokes this reset through the exported helper.
+  resizeFrameCacheResetters.set(stdout, () => {
+    lastFrame = "";
+    logDebug("Frame cache reset: terminal resize");
+  });
+
+  stdout.write = (chunk: string | Uint8Array) => {
+    if (typeof chunk !== "string") {
+      return originalWrite(chunk);
+    }
+
+    // Task 7: Frame Lock
+    // Ensure only one render flush can write to stdout at a time.
+    if (isFlushing) {
+      logDebug("Frame dropped: lock active (concurrent flush)");
+      return true;
+    }
+
+    // Task 8: Full-frame Deduplication
+    // Skip if identical to last frame.
+    if (chunk === lastFrame) {
+      logDebug("Frame dropped: identical to last frame");
+      return true;
+    }
+
+    // Task 4: Width-Safe Injection
+    // Ensure every row clears to the end of the line. This fixes artifacts
+    // left behind when a shorter row replaces a longer row or when terminal
+    // wrapping occurs during resize.
+    //
+    // We inject \x1b[K before every newline and at the end of the frame.
+    // padding via \x1b[K injection.
+    // Only apply if the chunk is non-empty and doesn't look like a control-only 
+    // sequence (e.g. terminal title OSC).
+    let processed = chunk;
+    const isControlSequence = chunk.includes("\x1b]");
+    if (chunk.length > 0 && !isControlSequence) {
+      processed = chunk.replace(/\n/g, "\x1b[K\n");
+      if (!processed.endsWith("\x1b[K") && !processed.endsWith("\x1b[K\n")) {
+        processed += "\x1b[K";
+      }
+    }
+
+    isFlushing = true;
+    try {
+      lastFrame = chunk;
+      const resizing = isTerminalResizing();
+      logDebug(`Frame written: length=${processed.length} original=${chunk.length} resizing=${resizing}`);
+      return originalWrite(processed);
+    } finally {
+      isFlushing = false;
+    }
+  };
+
+  return stdout;
+}

package/src/core/terminal/inkRenderReset.ts

@@ -0,0 +1,123 @@
+import * as renderDebug from "../perf/renderDebug.js";
+
+/**
+ * Typed subset of the internal Ink class instance we reach into.
+ *
+ * `unsubscribeResize` is used at startup to disable Ink's competing resize
+ * handler (see src/index.tsx). The remaining fields are Ink's per-frame render
+ * caches; we reset them on the explicit /clear boundary so the next frame is
+ * written authoritatively from a clean baseline — exactly like the first frame
+ * after a cold startup — rather than diffed against pre-clear output.
+ *
+ * All fields are optional so the type also describes the minimal capability
+ * needed by callers that only disable resize, and so resolution degrades
+ * gracefully across Ink versions / test mocks.
+ */
+export interface InkRenderInstance {
+  unsubscribeResize?: () => void;
+  renderInteractiveFrame?: (output: string, outputHeight: number, staticOutput: string) => void;
+  lastOutput?: string;
+  lastOutputToRender?: string;
+  lastOutputHeight?: number;
+  lastTerminalWidth?: number;
+  fullStaticOutput?: string;
+  log?: { reset?: () => void };
+  throttledOnRender?: { cancel?: () => void };
+  throttledLog?: { cancel?: () => void };
+}
+
+export interface AppStdoutLike {
+  columns?: number;
+  rows?: number;
+}
+
+/**
+ * Resolve the real Ink class instance via Ink's internal WeakMap<stdout, Ink>.
+ * Returns null if resolution fails (e.g. different Ink version, test mocks).
+ *
+ * Bun doesn't resolve bare subpath imports like "ink/build/instances.js" so we
+ * resolve ink's main entry first, then derive the sibling path.
+ */
+export function resolveInkRenderInstance(stdout: object): InkRenderInstance | null {
+  try {
+    const { createRequire } = require("node:module");
+    const req = createRequire(import.meta.url);
+    const inkMain = req.resolve("ink");
+    const instancesPath = inkMain.replace(/index\.js$/, "instances.js");
+    const instances = req(instancesPath);
+    const weakMap: WeakMap<object, InkRenderInstance> =
+      instances.default ?? instances;
+    return weakMap.get(stdout) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export interface ResetInkOutputOptions {
+  instance: InkRenderInstance | null;
+  /** Current terminal column count, used to reseat lastTerminalWidth. */
+  columns?: number;
+}
+
+/**
+ * Reset Ink's render-state caches to the fresh-startup baseline.
+ *
+ * Call this immediately AFTER the terminal has been physically cleared (e.g. by
+ * terminalControl.clearTranscript on /clear) and BEFORE the post-clear React
+ * render commits. It mirrors what a brand-new Ink instance looks like at cold
+ * startup: empty frame caches and zero previous height, so the next frame is
+ * authoritative and the subsequent resize math (Ink's renderInteractiveFrame /
+ * shouldClearTerminalForFrame) is evaluated against truthful state.
+ *
+ * This does NOT emit any clear/erase escape sequences itself — the terminal is
+ * already physically cleared, and Ink's log.reset() zeroes log-update's
+ * accounting without writing. Returns false (graceful no-op) if no live Ink
+ * instance is available.
+ */
+export function resetInkOutputForFreshFrame({ instance, columns }: ResetInkOutputOptions): boolean {
+  if (!instance) {
+    renderDebug.traceEvent("terminal", "clearRenderReset", { instanceResolved: false });
+    return false;
+  }
+
+  const before = {
+    lastOutputLength: instance.lastOutput?.length ?? 0,
+    lastOutputToRenderLength: instance.lastOutputToRender?.length ?? 0,
+    lastOutputHeight: instance.lastOutputHeight ?? 0,
+    fullStaticOutputLength: instance.fullStaticOutput?.length ?? 0,
+    lastTerminalWidth: instance.lastTerminalWidth,
+  };
+
+  // Drop any pending throttled render/log so a stale pre-clear frame can't be
+  // flushed after we reset the caches.
+  instance.throttledOnRender?.cancel?.();
+  instance.throttledLog?.cancel?.();
+
+  // Zero log-update's previousOutput/previousLineCount WITHOUT emitting escape
+  // sequences (the terminal was already physically cleared).
+  instance.log?.reset?.();
+
+  // Reset Ink's frame caches to the constructor/startup state.
+  instance.lastOutput = "";
+  instance.lastOutputToRender = "";
+  instance.lastOutputHeight = 0;
+  instance.fullStaticOutput = "";
+  if (typeof columns === "number" && Number.isFinite(columns)) {
+    instance.lastTerminalWidth = columns;
+  }
+
+  renderDebug.traceEvent("terminal", "clearRenderReset", {
+    instanceResolved: true,
+    columns,
+    before,
+    after: {
+      lastOutputLength: instance.lastOutput.length,
+      lastOutputToRenderLength: instance.lastOutputToRender.length,
+      lastOutputHeight: instance.lastOutputHeight,
+      fullStaticOutputLength: instance.fullStaticOutput.length,
+      lastTerminalWidth: instance.lastTerminalWidth,
+    },
+  });
+
+  return true;
+}

package/src/core/terminal/terminalControl.ts

@@ -14,11 +14,24 @@ export const TERMINAL_SEQUENCES = {
   mouseEnable: "\x1b[?1000h\x1b[?1006h",
   mouseDisable: "\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l\x1b[?1015l",
   title: `\x1b]0;${TERMINAL_TITLE}\x07\x1b]2;${TERMINAL_TITLE}\x07`,
+  alternateScreenEnable: "\x1b[?1049h",
+  alternateScreenDisable: "\x1b[?1049l",
 } as const;
 
 export type TerminalWrite = (chunk: string) => boolean | void;
 export type TerminalChannel = "stdout" | "stderr";
 
+// Tracks whether the terminal is currently in a live resize debounce.
+let terminalResizing = false;
+
+export function setTerminalResizing(resizing: boolean): void {
+  terminalResizing = resizing;
+}
+
+export function isTerminalResizing(): boolean {
+  return terminalResizing;
+}
+
 // Tracks current UI state kind for diagnostic assertions.
 let currentUIStateKind: string = "IDLE";
 
@@ -107,12 +120,14 @@ export interface TerminalModeController {
   clearViewport(source: string): void;
   setMouseReporting(enabled: boolean, source: string): void;
   setBracketedPaste(enabled: boolean, source: string): void;
+  setAlternateScreen(enabled: boolean, source: string): void;
   resetModes(): void;
 }
 
 export function createTerminalModeController(write: TerminalWrite): TerminalModeController {
   let mouseReporting: boolean | null = null;
   let bracketedPaste: boolean | null = null;
+  let alternateScreen: boolean | null = null;
 
   const writeStdout = (sequence: string, source: string) =>
     writeTerminalControl(write, "stdout", source, sequence);
@@ -135,13 +150,20 @@ export function createTerminalModeController(write: TerminalWrite): TerminalMode
       bracketedPaste = enabled;
       writeStdout(enabled ? TERMINAL_SEQUENCES.bracketedPasteEnable : TERMINAL_SEQUENCES.bracketedPasteDisable, source);
     },
+    setAlternateScreen(enabled, source) {
+      if (alternateScreen === enabled) return;
+      alternateScreen = enabled;
+      writeStdout(enabled ? TERMINAL_SEQUENCES.alternateScreenEnable : TERMINAL_SEQUENCES.alternateScreenDisable, source);
+    },
     resetModes() {
       renderDebug.traceEvent("terminal", "resetModes", {
         mouseReporting,
         bracketedPaste,
+        alternateScreen,
       });
       mouseReporting = null;
       bracketedPaste = null;
+      alternateScreen = null;
     },
   };
 }

package/src/core/terminal/terminalTitle.ts

@@ -1,6 +1,7 @@
-import { APP_NAME, type TerminalTitleMode, formatTerminalTitlePath } from "../../config/settings.js";
-import { appendFileSync, mkdirSync } from "fs";
-import { dirname, join } from "path";
+import { APP_NAME, type TerminalTitleMode, formatTerminalTitlePath } from "../../config/settings.js";
+import { appendFileSync, mkdirSync } from "fs";
+import { dirname, join } from "path";
+import * as renderDebug from "../perf/renderDebug.js";
 
 export const DEFAULT_TERMINAL_TITLE = APP_NAME;
 
@@ -49,16 +50,17 @@ function findIncompleteOscTitleStart(text: string): number {
   return -1;
 }
 
-const TERMINAL_TITLE_DEBUG_LOG_PATH = process.env["CODEXA_TERMINAL_TITLE_DEBUG_FILE"]?.trim()
-  || join(process.cwd(), ".codexa-debug", "terminal-title-debug.log");
+const TERMINAL_TITLE_DEBUG_LOG_PATH = process.env["CODEXA_TERMINAL_TITLE_DEBUG_FILE"]?.trim()
+  || process.env["CODEXA_RENDER_DEBUG_FILE"]?.trim()
+  || join(process.cwd(), ".codexa", "debug", "render-status.log");
 
 let terminalTitleLifecycleState = "unknown";
 
-function debugLog(msg: string): void {
-  if (DEBUG_TERMINAL_TITLE) {
-    process.stderr.write(`[codexa:terminal-title] ${msg}\n`);
-  }
-}
+function debugLog(msg: string): void {
+  if (DEBUG_TERMINAL_TITLE) {
+    writeTerminalTitleDebugRecord({ event: "debug", message: msg });
+  }
+}
 
 function writeTerminalTitleDebugRecord(fields: Record<string, unknown>): void {
   if (!DEBUG_TERMINAL_TITLE) return;
@@ -144,8 +146,9 @@ export function writeCodexaTerminalTitle(title: string, options?: TerminalTitleO
 
   lastWrittenTerminalTitle = cleanTitle;
 
-  const sequence = buildTerminalTitleSequence(cleanTitle);
-  writeTerminalTitleDebugRecord({
+  const sequence = buildTerminalTitleSequence(cleanTitle);
+  renderDebug.traceTerminalWrite("stdout", `terminalTitle:${options?.reason ?? "unknown"}`, sequence);
+  writeTerminalTitleDebugRecord({
     event: "codexaTitleWrite",
     title: cleanTitle,
     reason: options?.reason ?? "unknown",
@@ -353,76 +356,7 @@ export function writeGuardedTerminalOutput(
   return write(safeText) !== false;
 }
 
-// ─── Startup guard ────────────────────────────────────────────────────────────
-
-/**
- * Schedules a sequence of title assertions to outlast Windows Terminal's
- * shell integration, which overwrites the process title at unpredictable
- * points during startup (shell prompt init, profile scripts, etc.).
- * The retries at 50/250/500/1000ms are intentional: no single delay is
- * reliable across all terminal configurations, so we assert multiple times.
- */
-export function beginColdStartSequence(title: string, options?: { write?: (chunk: string) => void }) {
-  setIntendedTerminalTitle(title, { force: true, write: options?.write, reason: "cold-start-immediate" });
-
-  const timers: ReturnType<typeof setTimeout>[] = [];
-  let cancelled = false;
-
-  const scheduleRetry = (delayMs: number) => {
-    const id = setTimeout(() => {
-      if (!cancelled) {
-        debugLog(`cold-start retry t=${delayMs}ms fired`);
-        reassertIntendedTerminalTitle({ write: options?.write, reason: `cold-start-retry-${delayMs}ms` });
-      }
-    }, delayMs);
-    timers.push(id);
-  };
-
-  scheduleRetry(50);
-  scheduleRetry(250);
-  scheduleRetry(500);
-  scheduleRetry(1000);
-
-  return () => {
-    cancelled = true;
-    timers.forEach(clearTimeout);
-    debugLog("cold-start sequence cancelled");
-  };
-}
-
-export function startTerminalTitleStartupGuard(options?: {
-  write?: (chunk: string) => void;
-  intervalMs?: number;
-  durationMs?: number;
-  reason?: string;
-}): () => void {
-  const intervalMs = options?.intervalMs ?? 150;
-  const durationMs = options?.durationMs ?? 3500;
-  const reason = options?.reason ?? "startup-guard";
-  let stopped = false;
-  const startedAt = Date.now();
-
-  reassertIntendedTerminalTitle({ write: options?.write, reason: `${reason}-start` });
-  const interval = setInterval(() => {
-    if (stopped) return;
-    if (Date.now() - startedAt >= durationMs) {
-      stopped = true;
-      clearInterval(interval);
-      reassertIntendedTerminalTitle({ write: options?.write, reason: `${reason}-end` });
-      return;
-    }
-    reassertIntendedTerminalTitle({ write: options?.write, reason });
-  }, intervalMs);
-  interval.unref?.();
-
-  return () => {
-    if (stopped) return;
-    stopped = true;
-    clearInterval(interval);
-  };
-}
-
-export function sanitizeTerminalTitle(title: string): string {
+export function sanitizeTerminalTitle(title: string): string {
   return title
     .replace(/[\u0000-\u001f\u007f]/g, " ")
     .replace(/\u001b/g, "")
@@ -461,23 +395,3 @@ export function reassertTerminalTitle(
   write(buildTerminalTitleSequence(title));
 }
 
-/**
- * Acquire a run-scoped title guard that immediately asserts the title,
- * reasserts it periodically while work is active, and emits one final
- * assertion when released.
- */
-export function acquireTerminalTitleGuard(
-  intervalMs = 250,
-  reassert: () => void = () => reassertTerminalTitle(),
-): () => void {
-  let released = false;
-  reassert();
-  const timer = setInterval(reassert, intervalMs);
-  timer.unref?.();
-  return () => {
-    if (released) return;
-    released = true;
-    clearInterval(timer);
-    reassert();
-  };
-}

package/src/core/version/channel.ts

@@ -0,0 +1,23 @@
+import { APP_VERSION } from "../../config/settings.js";
+
+export const CODEXA_CHANNEL_ENV = "CODEXA_CHANNEL";
+export const LOCAL_DEV_CHANNEL = "local-dev";
+
+export function getCodexaChannel(env: NodeJS.ProcessEnv = process.env): string {
+  return env[CODEXA_CHANNEL_ENV]?.trim() || "published";
+}
+
+export function isLocalDevChannel(env: NodeJS.ProcessEnv = process.env): boolean {
+  return getCodexaChannel(env) === LOCAL_DEV_CHANNEL;
+}
+
+export function formatCodexaVersionLabel(
+  version: string = APP_VERSION,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return isLocalDevChannel(env) ? `${version}-dev local` : version;
+}
+
+export function formatCodexaBrandLabel(env: NodeJS.ProcessEnv = process.env): string {
+  return `Codexa v${formatCodexaVersionLabel(APP_VERSION, env)}`;
+}

package/src/core/version/updateCheck.ts

@@ -0,0 +1,193 @@
+import { APP_VERSION } from "../../config/settings.js";
+import { isLocalDevChannel } from "./channel.js";
+
+export const CODEXA_NPM_PACKAGE = "@golba98/codexa";
+export const CODEXA_NPM_REGISTRY_URL = "https://registry.npmjs.org/@golba98%2Fcodexa";
+export const CODEXA_UPDATE_COMMAND = `npm install -g ${CODEXA_NPM_PACKAGE}@latest`;
+
+export type UpdateStatus = "up-to-date" | "update-available" | "unknown" | "error";
+
+export interface NpmRegistryMetadata {
+  "dist-tags"?: { latest?: unknown };
+}
+
+export interface UpdateCheckResult {
+  status: UpdateStatus;
+  currentVersion: string;
+  latestVersion: string | null;
+  errorMessage?: string;
+  checkedAt: number;
+  source?: "npm" | "cache";
+}
+
+const FETCH_TIMEOUT_MS = 5000;
+
+/** Strip a leading "v" so "v1.0.2" and "1.0.2" are treated as equal. */
+export function normalizeVersion(v: string): string {
+  return v.startsWith("v") ? v.slice(1) : v;
+}
+
+export function formatVersionLabel(version: string): string {
+  const normalized = normalizeVersion(version.trim());
+  return normalized ? `v${normalized}` : version;
+}
+
+const SEMVER_RE = /^\d+\.\d+\.\d+(-[\w.]+)?$/;
+
+/** Returns true for valid semver strings with or without a leading "v". */
+export function isValidSemver(v: string): boolean {
+  return SEMVER_RE.test(normalizeVersion(v));
+}
+
+export function shouldRunStartupUpdateCheck(
+  env: NodeJS.ProcessEnv = process.env,
+  enabled = true,
+): boolean {
+  return enabled && !isLocalDevChannel(env);
+}
+
+// Compares two semver strings numerically. Returns negative if a < b, 0 if equal, positive if a > b.
+// Pre-release versions (e.g. 1.0.2-beta.1) sort below their release counterpart (1.0.2 > 1.0.2-beta.1).
+// Leading "v" is stripped before comparison.
+export function compareSemver(a: string, b: string): number {
+  const parseParts = (v: string): { numeric: number[]; prerelease: string | null } => {
+    const norm = normalizeVersion(v);
+    const dashIdx = norm.indexOf("-");
+    const base = dashIdx === -1 ? norm : norm.slice(0, dashIdx);
+    const prerelease = dashIdx === -1 ? null : norm.slice(dashIdx + 1);
+    const numeric = base.split(".").map((p) => parseInt(p, 10) || 0);
+    return { numeric, prerelease };
+  };
+
+  const pa = parseParts(a);
+  const pb = parseParts(b);
+  const len = Math.max(pa.numeric.length, pb.numeric.length);
+
+  for (let i = 0; i < len; i++) {
+    const diff = (pa.numeric[i] ?? 0) - (pb.numeric[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+
+  // Same numeric version: no pre-release > has pre-release
+  if (pa.prerelease === null && pb.prerelease !== null) return 1;
+  if (pa.prerelease !== null && pb.prerelease === null) return -1;
+  if (pa.prerelease !== null && pb.prerelease !== null) {
+    return pa.prerelease < pb.prerelease ? -1 : pa.prerelease > pb.prerelease ? 1 : 0;
+  }
+  return 0;
+}
+
+export function isNewerVersion(candidate: string, current: string): boolean {
+  return compareSemver(candidate, current) > 0;
+}
+
+export interface UpdateCheckOverrides {
+  currentVersion?: string;
+  fetchNpmMetadataFn?: (url: string) => Promise<NpmRegistryMetadata>;
+}
+
+async function defaultFetchNpmMetadata(url: string): Promise<NpmRegistryMetadata> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      signal: controller.signal,
+      headers: { "User-Agent": `${CODEXA_NPM_PACKAGE}-update-checker/1.0` },
+    });
+    if (!res.ok) throw new Error(`npm registry returned HTTP ${res.status}`);
+    return await res.json() as NpmRegistryMetadata;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function checkForUpdates(
+  opts?: { enabled?: boolean },
+  overrides?: UpdateCheckOverrides,
+): Promise<UpdateCheckResult> {
+  const currentVersion = normalizeVersion(overrides?.currentVersion ?? APP_VERSION);
+
+  if (opts?.enabled === false) {
+    return { status: "unknown", currentVersion, latestVersion: null, checkedAt: Date.now(), source: "npm" };
+  }
+
+  try {
+    const fetchFn = overrides?.fetchNpmMetadataFn ?? defaultFetchNpmMetadata;
+    const metadata = await fetchFn(CODEXA_NPM_REGISTRY_URL);
+    const rawLatest = metadata["dist-tags"]?.latest;
+
+    if (typeof rawLatest !== "string" || !rawLatest.trim()) {
+      return {
+        status: "error",
+        currentVersion,
+        latestVersion: null,
+        errorMessage: "npm registry response did not include dist-tags.latest",
+        checkedAt: Date.now(),
+        source: "npm",
+      };
+    }
+
+    const latestVersion = normalizeVersion(rawLatest.trim());
+
+    if (!isValidSemver(latestVersion) || !isValidSemver(currentVersion)) {
+      return {
+        status: "unknown",
+        currentVersion,
+        latestVersion: rawLatest,
+        errorMessage: `Invalid semver — current: "${currentVersion}", latest: "${rawLatest}"`,
+        checkedAt: Date.now(),
+        source: "npm",
+      };
+    }
+
+    const status = isNewerVersion(latestVersion, currentVersion) ? "update-available" : "up-to-date";
+    return { status, currentVersion, latestVersion, checkedAt: Date.now(), source: "npm" };
+  } catch (err) {
+    return {
+      status: "error",
+      currentVersion,
+      latestVersion: null,
+      errorMessage: err instanceof Error ? err.message : String(err),
+      checkedAt: Date.now(),
+      source: "npm",
+    };
+  }
+}
+
+export function formatUpdateInstructions(result: UpdateCheckResult | null): string {
+  const current = result?.currentVersion ?? APP_VERSION;
+  const latest = result?.latestVersion ?? "unknown";
+
+  if (result?.status === "error") {
+    return [
+      `Current installed version: ${current}`,
+      `npm latest version:        ${latest}`,
+      `Error checking npm update status: ${result.errorMessage ?? "unknown error"}`,
+    ].join("\n");
+  }
+
+  let statusLine: string;
+  if (result?.status === "update-available" && result.latestVersion) {
+    statusLine = `Update available: Codexa ${formatVersionLabel(result.latestVersion)}`;
+  } else if (result?.status === "up-to-date") {
+    statusLine = "Already up to date.";
+  } else {
+    statusLine = "Status unknown — could not reach npm registry.";
+  }
+
+  return [
+    `Current installed version: ${current}`,
+    `npm latest version:        ${latest}`,
+    `Status:          ${statusLine}`,
+    "",
+    `Run: ${CODEXA_UPDATE_COMMAND}`,
+  ].join("\n");
+}
+
+export function formatLocalDevUpdateStatus(): string {
+  return [
+    "Running local-dev Codexa.",
+    "Automatic published npm update prompts are disabled for this channel.",
+    "Run /update check to explicitly check the published npm package.",
+  ].join("\n");
+}