@codemieai/code 0.15.1 → 0.15.2

package/dist/utils/hook-command.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Detect whether a `codemie` command path actually resolves to the bundled agent
+ * binary instead of this CLI. Checks both the raw path and its symlink target;
+ * never throws (unresolvable paths are treated as not shadowed).
+ */
+export declare function isShadowedCodemieShim(commandPath: string): boolean;
 export declare function resolveCodemieBinary(): Promise<string>;
 export declare function resolveHookCommand(command: string, binary: string): string;
 export declare function rewriteHooksCommandTree(node: unknown, binary: string): boolean;

package/dist/utils/hook-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hook-command.d.ts","sourceRoot":"","sources":["../../src/utils/hook-command.ts"],"names":[],"mappings":"AA2BA,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CAoB5D;AAGD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAI1E;AAID,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CA2B9E"}
+{"version":3,"file":"hook-command.d.ts","sourceRoot":"","sources":["../../src/utils/hook-command.ts"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAWlE;AAsBD,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CAoB5D;AAKD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAc1E;AAID,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CA2B9E"}

package/dist/utils/hook-command.js

@@ -3,9 +3,34 @@
  * bare `codemie hook` no longer fails with `command not found` when the hook
  * shell's PATH lacks the codemie bin dir. See EPMCDME-14035.
  */
+import { realpathSync } from 'fs';
 import { getCommandPath } from './processes.js';
 // Shell-special chars that force the command path to be quoted; mirrors BaseAgentAdapter.
 const NEEDS_QUOTING = /[ \t,;=()&|<>^%[\]{}]/;
+// The bundled agent package (@codemieai/codemie-opencode) registers `codemie` as
+// its own bin name, so in dev checkouts node_modules/.bin/codemie symlinks to the
+// agent binary, not to this CLI. Hooks pointed at that shim silently run the
+// wrong program: `codemie hook` is parsed as a project path, and
+// `codemie sound X` prints the agent's CLI help to stdout and exits 1 with empty
+// stderr (surfacing in agents as "Failed with non-blocking status code: No
+// stderr output").
+const SHADOWING_PACKAGE_SEGMENT = '/@codemieai/codemie-opencode/';
+/**
+ * Detect whether a `codemie` command path actually resolves to the bundled agent
+ * binary instead of this CLI. Checks both the raw path and its symlink target;
+ * never throws (unresolvable paths are treated as not shadowed).
+ */
+export function isShadowedCodemieShim(commandPath) {
+    const unquoted = commandPath.replace(/^"|"$/g, '');
+    const candidates = [unquoted];
+    try {
+        candidates.push(realpathSync(unquoted));
+    }
+    catch {
+        // Unresolvable path — judge by the raw path alone.
+    }
+    return candidates.some((candidate) => candidate.replace(/\\/g, '/').includes(SHADOWING_PACKAGE_SEGMENT));
+}
 function quoteIfNeeded(p) {
     return NEEDS_QUOTING.test(p) && !p.startsWith('"') ? `"${p}"` : p;
 }
@@ -20,10 +45,13 @@ function toForwardSlash(p) {
 }
 // Prefer the PATH-resolved shim, then the running entry (argv[1]), then bare `codemie`.
 // Never throws — it runs in launch-critical hook paths, so errors degrade to the next fallback.
+// A PATH shim that resolves to the bundled agent binary (dev checkouts where
+// node_modules/.bin precedes the global bin dir) is rejected: hooks would run the
+// agent, not this CLI.
 export async function resolveCodemieBinary() {
     try {
         const resolved = await getCommandPath('codemie');
-        if (resolved)
+        if (resolved && !isShadowedCodemieShim(resolved))
             return quoteIfNeeded(toForwardSlash(resolved));
     }
     catch {
@@ -42,11 +70,22 @@ export async function resolveCodemieBinary() {
     return 'codemie';
 }
 // Rewrite a leading `codemie` token to `binary`; other commands pass through.
+// Also rewrites absolute paths baked in by older resolvers that point at the
+// bundled agent shim, so already-installed hooks get repaired on rewrite.
 export function resolveHookCommand(command, binary) {
     if (command === 'codemie')
         return binary;
     if (command.startsWith('codemie '))
         return binary + command.slice('codemie'.length);
+    const firstTokenEnd = command.startsWith('"')
+        ? command.indexOf('"', 1) + 1
+        : command.indexOf(' ');
+    if (firstTokenEnd > 0) {
+        const firstToken = command.slice(0, firstTokenEnd);
+        if (isShadowedCodemieShim(firstToken)) {
+            return binary + command.slice(firstTokenEnd);
+        }
+    }
     return command;
 }
 // Recursively rewrite every string `command` field anywhere in a hooks structure.

package/dist/utils/hook-command.js.map

@@ -1 +1 @@
-{"version":3,"file":"hook-command.js","sourceRoot":"","sources":["../../src/utils/hook-command.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hook-command.js","sourceRoot":"","sources":["../../src/utils/hook-command.ts"],"names":[],"mappings":"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"}

package/dist/utils/pricing.json

@@ -15,16 +15,24 @@
     "notes": {
       "keys": "All keys use dashes instead of dots (e.g. gpt-5-4 not gpt-5.4) so normalizeModelName dots→dashes works",
       "cacheRead": "cache hit price (Anthropic: 0.1x input, OpenAI: varies, Google: ~0.1x input)",
-      "cacheWrite": "cache write price (Anthropic: 1.25x input, OpenAI: ~same as input)"
+      "cacheWrite": "cache write price (Anthropic: 1.25x input, OpenAI: ~same as input)",
+      "claude5": "Sonnet 5 and Opus 5 standard API-equivalent token rates verified 2026-09-15 at https://platform.claude.com/docs/en/about-claude/pricing; excludes additional tool charges. Sonnet 5's planned September 1 price increase was cancelled."
     },
     "note": "codemie: added claude 4-7/4-8 tier estimates 2026-06-08; added kimi-for-coding alias and normalized kimi-k2-5 key 2026-06-15; added claude-sonnet-5 pinned entry 2026-07-01 (pricing table lookup also has a generic same-tier fallback now, see pricing.ts)"
   },
   "claude-sonnet-5": {
-    "input": 3,
-    "output": 15,
-    "cacheRead": 0.3,
-    "cacheWrite": 3.75,
-    "cacheWrite1h": 6.0
+    "input": 2,
+    "output": 10,
+    "cacheRead": 0.2,
+    "cacheWrite": 2.5,
+    "cacheWrite1h": 4.0
+  },
+  "claude-opus-5": {
+    "input": 5,
+    "output": 25,
+    "cacheRead": 0.5,
+    "cacheWrite": 6.25,
+    "cacheWrite1h": 10.0
   },
   "claude-opus-4-6": {
     "input": 5,

package/dist/utils/tips.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Feature Tips ("Did you know?") — selection, rotation and rendering logic.
+ *
+ * The curated catalog lives in src/utils/tips.json (pure data — edit tips
+ * there); this module loads it once at startup and exposes it as TIPS.
+ * Tips are shown at session start and end, browseable on demand via
+ * `codemie tips`, and sprinkled onto selected CLI surfaces (doctor, first-run
+ * screens) via renderTip().
+ *
+ * Catalog maintenance workflow (edit src/utils/tips.json):
+ * - Add a tip: append one `{ "id", "category", "message", "command"? }` object
+ *   to the array. Use a fresh kebab-case id — ids are never reused, because
+ *   the rotation state (~/.codemie/.tips-state.json) remembers them.
+ * - Retire a command: delete its tip in the same PR. If the tip is missed,
+ *   `codemie tips` validates `command` references against the live CLI command
+ *   tree and silently drops (plus debug-logs) tips pointing at retired
+ *   commands — session rendering never validates and never breaks.
+ * - Reword a tip: edit `message` in place and keep `id` stable so the rotation
+ *   history stays meaningful.
+ *
+ * This module must stay safe to import from the agent runtime, so it depends
+ * only on fs/path, chalk, the logger and the paths utility — never on
+ * commander or the CLI layer.
+ *
+ * Environment Variables:
+ * - CODEMIE_TIPS=true (default): show tips at session start/end
+ * - CODEMIE_TIPS=false|0|no: disable session tips (`codemie tips` still works)
+ */
+/**
+ * A single feature tip.
+ */
+export interface Tip {
+    /** Stable unique id, kebab-case, e.g. 'cmd-skill'. Never reused. */
+    id: string;
+    /** Short category for grouping in `codemie tips`, e.g. 'Commands'. */
+    category: string;
+    /** Full sentence shown to the user. May embed the command inline. */
+    message: string;
+    /**
+     * Optional top-level command name used for validation and display,
+     * e.g. 'skill' or 'proxy'. When the referenced command is retired,
+     * `codemie tips` drops/flags this tip automatically.
+     */
+    command?: string;
+    /** Concrete invocation variations taught by this tip. */
+    commands?: string[];
+}
+/**
+ * Curated tip catalog, loaded eagerly from src/utils/tips.json. Every
+ * `command` value references a top-level command registered in
+ * src/cli/index.ts; `codemie tips` re-validates these at runtime.
+ */
+export declare const TIPS: readonly Tip[];
+/**
+ * Check if session tips are enabled (default: true).
+ * Reads the CODEMIE_TIPS environment variable.
+ *
+ * @returns true unless CODEMIE_TIPS is set to a falsy value ('false', '0', 'no')
+ */
+export declare function isTipsEnabled(): boolean;
+/**
+ * Return the full tip catalog (used by `codemie tips`).
+ */
+export declare function listTips(): readonly Tip[];
+/**
+ * Pick the tip to show at a session lifecycle point.
+ *
+ * Randomly selects a tip that has not been shown yet (per the rotation state
+ * file), records the pick, and resets the shown list once every tip has been
+ * shown. Both contexts share one catalog and one rotation for now; the context
+ * is recorded in the debug log so future per-context catalogs can reuse it.
+ *
+ * Best-effort: unreadable/corrupt state is treated as empty, write failures
+ * are swallowed — a tip must never block or break a session.
+ *
+ * @param context - Where the tip is rendered ('start' or 'end' of session)
+ * @returns A tip, or null when tips are disabled or the catalog is empty
+ */
+export declare function getSessionTip(context: 'start' | 'end'): Tip | null;
+/**
+ * Format a tip for terminal display: a gold ✨ prefix followed by the message
+ * in the same warm gold, bold. Yellow is the CLI's established accent color
+ * (matches the Kimi-style prompt echo) — deliberately no background bars or
+ * badge, just plain foreground styling.
+ * Shared by session lifecycle rendering (BaseAgentAdapter), renderTip(), and
+ * `codemie tips --random` so tips look identical everywhere.
+ */
+export declare function formatTipLine(tip: Tip): string;
+/**
+ * Print a single random tip to the console for CLI surfaces (doctor,
+ * first-run and post-setup screens, ...). Unlike getSessionTip(), this does
+ * not read or update the rotation state — rotation stays exclusive to session
+ * start/end.
+ *
+ * Best-effort: never throws, and is a no-op when tips are disabled.
+ *
+ * @param options.category - Restrict the pick to one category; falls back to
+ *   the full catalog when the category has no tips
+ */
+export declare function renderTip(options?: {
+    category?: string;
+}): void;
+//# sourceMappingURL=tips.d.ts.map

package/dist/utils/tips.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tips.d.ts","sourceRoot":"","sources":["../../src/utils/tips.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAUH;;GAEG;AACH,MAAM,WAAW,GAAG;IAClB,oEAAoE;IACpE,EAAE,EAAE,MAAM,CAAC;IACX,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAqDD;;;;GAIG;AACH,eAAO,MAAM,IAAI,EAAE,SAAS,GAAG,EAAsB,CAAC;AAYtD;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;GAEG;AACH,wBAAgB,QAAQ,IAAI,SAAS,GAAG,EAAE,CAEzC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,KAAK,GAAG,GAAG,GAAG,IAAI,CAwBlE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAE9C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAoB/D"}

package/dist/utils/tips.js

@@ -0,0 +1,221 @@
+/**
+ * Feature Tips ("Did you know?") — selection, rotation and rendering logic.
+ *
+ * The curated catalog lives in src/utils/tips.json (pure data — edit tips
+ * there); this module loads it once at startup and exposes it as TIPS.
+ * Tips are shown at session start and end, browseable on demand via
+ * `codemie tips`, and sprinkled onto selected CLI surfaces (doctor, first-run
+ * screens) via renderTip().
+ *
+ * Catalog maintenance workflow (edit src/utils/tips.json):
+ * - Add a tip: append one `{ "id", "category", "message", "command"? }` object
+ *   to the array. Use a fresh kebab-case id — ids are never reused, because
+ *   the rotation state (~/.codemie/.tips-state.json) remembers them.
+ * - Retire a command: delete its tip in the same PR. If the tip is missed,
+ *   `codemie tips` validates `command` references against the live CLI command
+ *   tree and silently drops (plus debug-logs) tips pointing at retired
+ *   commands — session rendering never validates and never breaks.
+ * - Reword a tip: edit `message` in place and keep `id` stable so the rotation
+ *   history stays meaningful.
+ *
+ * This module must stay safe to import from the agent runtime, so it depends
+ * only on fs/path, chalk, the logger and the paths utility — never on
+ * commander or the CLI layer.
+ *
+ * Environment Variables:
+ * - CODEMIE_TIPS=true (default): show tips at session start/end
+ * - CODEMIE_TIPS=false|0|no: disable session tips (`codemie tips` still works)
+ */
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+import { logger } from './logger.js';
+import { getCodemiePath } from './paths.js';
+import { parseBooleanEnv } from './env.js';
+const isStringArray = (value) => Array.isArray(value) && value.every(item => typeof item === 'string');
+/**
+ * Load the tip catalog from src/utils/tips.json at the package root (resolved
+ * relative to this module, so it works from src/utils in dev and dist/utils in
+ * the installed package, where the JSON ships via the package.json files list).
+ *
+ * Best-effort: any failure — missing file, malformed JSON, wrong shape — is
+ * debug-logged and yields an empty catalog. Tips must never break a session.
+ */
+function loadTipsCatalog() {
+    try {
+        // Resolve via import.meta.url, not paths.js: tests legitimately mock
+        // ./paths.js without declaring every export, and this module is loaded
+        // eagerly through BaseAgentAdapter — a mocked-out helper must never break
+        // module evaluation. Resolves identically from src/utils (dev) and
+        // dist/utils (built/installed package, where tips.json ships in src/utils).
+        const catalogPath = fileURLToPath(new URL('../../src/utils/tips.json', import.meta.url));
+        const parsed = JSON.parse(readFileSync(catalogPath, 'utf-8'));
+        if (!Array.isArray(parsed)) {
+            logger.debug('[tips] tips.json is not an array — using empty catalog', { catalogPath });
+            return [];
+        }
+        const tips = parsed
+            .filter((entry) => typeof entry === 'object' &&
+            entry !== null &&
+            typeof entry.id === 'string' &&
+            typeof entry.category === 'string' &&
+            typeof entry.message === 'string')
+            .map(entry => {
+            // Tolerate a malformed optional `commands` field by dropping just it
+            if (entry.commands !== undefined && !isStringArray(entry.commands)) {
+                logger.debug(`[tips] tips.json: ignoring malformed 'commands' on tip '${entry.id}'`);
+                return { ...entry, commands: undefined };
+            }
+            return entry;
+        });
+        if (tips.length !== parsed.length) {
+            logger.debug(`[tips] tips.json: dropped ${parsed.length - tips.length} malformed entrie(s)`, { catalogPath });
+        }
+        return tips;
+    }
+    catch (error) {
+        logger.debug('[tips] Failed to load tips.json — using empty catalog:', error);
+        return [];
+    }
+}
+/**
+ * Curated tip catalog, loaded eagerly from src/utils/tips.json. Every
+ * `command` value references a top-level command registered in
+ * src/cli/index.ts; `codemie tips` re-validates these at runtime.
+ */
+export const TIPS = loadTipsCatalog();
+const stateFilePath = () => getCodemiePath('.tips-state.json');
+/**
+ * Check if session tips are enabled (default: true).
+ * Reads the CODEMIE_TIPS environment variable.
+ *
+ * @returns true unless CODEMIE_TIPS is set to a falsy value ('false', '0', 'no')
+ */
+export function isTipsEnabled() {
+    return parseBooleanEnv(process.env.CODEMIE_TIPS, true);
+}
+/**
+ * Return the full tip catalog (used by `codemie tips`).
+ */
+export function listTips() {
+    return TIPS;
+}
+/**
+ * Pick the tip to show at a session lifecycle point.
+ *
+ * Randomly selects a tip that has not been shown yet (per the rotation state
+ * file), records the pick, and resets the shown list once every tip has been
+ * shown. Both contexts share one catalog and one rotation for now; the context
+ * is recorded in the debug log so future per-context catalogs can reuse it.
+ *
+ * Best-effort: unreadable/corrupt state is treated as empty, write failures
+ * are swallowed — a tip must never block or break a session.
+ *
+ * @param context - Where the tip is rendered ('start' or 'end' of session)
+ * @returns A tip, or null when tips are disabled or the catalog is empty
+ */
+export function getSessionTip(context) {
+    if (!isTipsEnabled() || TIPS.length === 0) {
+        return null;
+    }
+    const state = loadRotationState();
+    // Prune ids of retired tips so the rotation can still complete and reset.
+    const catalogIds = new Set(TIPS.map(tip => tip.id));
+    state.shownTipIds = state.shownTipIds.filter(id => catalogIds.has(id));
+    let candidates = TIPS.filter(tip => !state.shownTipIds.includes(tip.id));
+    if (candidates.length === 0) {
+        // Full rotation complete — start a fresh cycle.
+        state.shownTipIds = [];
+        candidates = [...TIPS];
+    }
+    const tip = candidates[Math.floor(Math.random() * candidates.length)];
+    state.shownTipIds.push(tip.id);
+    saveRotationState(state);
+    logger.debug('[tips] Selected session tip', { context, id: tip.id });
+    return tip;
+}
+/**
+ * Format a tip for terminal display: a gold ✨ prefix followed by the message
+ * in the same warm gold, bold. Yellow is the CLI's established accent color
+ * (matches the Kimi-style prompt echo) — deliberately no background bars or
+ * badge, just plain foreground styling.
+ * Shared by session lifecycle rendering (BaseAgentAdapter), renderTip(), and
+ * `codemie tips --random` so tips look identical everywhere.
+ */
+export function formatTipLine(tip) {
+    return chalk.bold.yellow(`✨ ${tip.message}`);
+}
+/**
+ * Print a single random tip to the console for CLI surfaces (doctor,
+ * first-run and post-setup screens, ...). Unlike getSessionTip(), this does
+ * not read or update the rotation state — rotation stays exclusive to session
+ * start/end.
+ *
+ * Best-effort: never throws, and is a no-op when tips are disabled.
+ *
+ * @param options.category - Restrict the pick to one category; falls back to
+ *   the full catalog when the category has no tips
+ */
+export function renderTip(options) {
+    try {
+        if (!isTipsEnabled() || TIPS.length === 0) {
+            return;
+        }
+        let pool = TIPS;
+        if (options?.category) {
+            const filtered = TIPS.filter(tip => tip.category === options.category);
+            if (filtered.length > 0) {
+                pool = filtered;
+            }
+        }
+        const tip = pool[Math.floor(Math.random() * pool.length)];
+        console.log();
+        console.log(formatTipLine(tip));
+    }
+    catch (error) {
+        logger.debug('[tips] renderTip failed (non-fatal):', error);
+    }
+}
+function loadRotationState() {
+    const file = stateFilePath();
+    try {
+        const content = readFileSync(file, 'utf-8');
+        const parsed = JSON.parse(content);
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            Array.isArray(parsed.shownTipIds)) {
+            const shownTipIds = parsed.shownTipIds
+                .filter((id) => typeof id === 'string');
+            return { shownTipIds };
+        }
+        return { shownTipIds: [] };
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'ENOENT') {
+            logger.debug('[tips] Rotation state unreadable — treating as empty', { file });
+        }
+        return { shownTipIds: [] };
+    }
+}
+/**
+ * Persist rotation state. The write goes through a same-directory temp file
+ * plus rename, so a concurrent reader never sees a truncated file (rename is
+ * atomic on POSIX and Windows for same-dir renames). Read-modify-write races
+ * between concurrent sessions remain theoretically possible — accepted as
+ * low-harm (worst case: a tip repeats); deliberately no locking.
+ */
+function saveRotationState(state) {
+    const file = stateFilePath();
+    try {
+        mkdirSync(path.dirname(file), { recursive: true });
+        const tmpFile = `${file}.tmp`;
+        writeFileSync(tmpFile, JSON.stringify(state, null, 2), 'utf-8');
+        renameSync(tmpFile, file);
+    }
+    catch (error) {
+        logger.debug('[tips] Failed to persist rotation state (non-fatal):', error);
+    }
+}
+//# sourceMappingURL=tips.js.map

package/dist/utils/tips.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tips.js","sourceRoot":"","sources":["../../src/utils/tips.ts"],"names":[],"mappings":"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"}

package/dist/utils/version-warnings.d.ts

@@ -0,0 +1,41 @@
+/**
+ * VersionWarningStore
+ *
+ * Records one-time "untested version" markers at user scope.
+ * Backing file: `~/.codemie/version-warnings.json`.
+ *
+ * A marker is keyed by (agent, installed agent version) and additionally stores
+ * the `supportedVersion` baseline it was acknowledged against. The marker is
+ * honoured only while that baseline still matches: a CodeMie release that moves
+ * the recommended version forward invalidates old markers and buys exactly one
+ * re-notice, while CodeMie releases that leave the baseline alone never re-nag.
+ *
+ * See EPMCDME-13734.
+ */
+export interface VersionWarningRecord {
+    agentName: string;
+    agentVersion: string;
+    /** Recommended version at the time the notice was acknowledged. */
+    supportedVersion: string;
+    /** CodeMie version that emitted the notice (context for `codemie doctor`). */
+    codemieVersion: string;
+    warnedAt: string;
+}
+export interface VersionWarningHistory {
+    version: 1;
+    warnings: VersionWarningRecord[];
+}
+export declare class VersionWarningStore {
+    static loadHistory(): Promise<VersionWarningHistory>;
+    static saveHistory(history: VersionWarningHistory): Promise<void>;
+    /**
+     * True when this agent version was already acknowledged against the same
+     * recommended baseline. A moved baseline makes the stored marker stale.
+     */
+    static hasWarned(agentName: string, agentVersion: string, supportedVersion: string): Promise<boolean>;
+    static recordWarning(agentName: string, agentVersion: string, supportedVersion: string, codemieVersion: string): Promise<void>;
+    static clear(): Promise<{
+        removed: number;
+    }>;
+}
+//# sourceMappingURL=version-warnings.d.ts.map

package/dist/utils/version-warnings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-warnings.d.ts","sourceRoot":"","sources":["../../src/utils/version-warnings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,CAAC,CAAC;IACX,QAAQ,EAAE,oBAAoB,EAAE,CAAC;CAClC;AAMD,qBAAa,mBAAmB;WACjB,WAAW,IAAI,OAAO,CAAC,qBAAqB,CAAC;WA0B7C,WAAW,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMvE;;;OAGG;WACU,SAAS,CACpB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,OAAO,CAAC;WAUN,aAAa,CACxB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,MAAM,EACxB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC;WAeH,KAAK,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAkBnD"}

package/dist/utils/version-warnings.js

@@ -0,0 +1,93 @@
+/**
+ * VersionWarningStore
+ *
+ * Records one-time "untested version" markers at user scope.
+ * Backing file: `~/.codemie/version-warnings.json`.
+ *
+ * A marker is keyed by (agent, installed agent version) and additionally stores
+ * the `supportedVersion` baseline it was acknowledged against. The marker is
+ * honoured only while that baseline still matches: a CodeMie release that moves
+ * the recommended version forward invalidates old markers and buys exactly one
+ * re-notice, while CodeMie releases that leave the baseline alone never re-nag.
+ *
+ * See EPMCDME-13734.
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { logger } from './logger.js';
+import { getCodemiePath } from './paths.js';
+const filePath = () => getCodemiePath('version-warnings.json');
+const emptyHistory = () => ({ version: 1, warnings: [] });
+export class VersionWarningStore {
+    static async loadHistory() {
+        const file = filePath();
+        try {
+            const content = await fs.readFile(file, 'utf-8');
+            const parsed = JSON.parse(content);
+            if (typeof parsed === 'object' &&
+                parsed !== null &&
+                Array.isArray(parsed.warnings)) {
+                return {
+                    version: 1,
+                    warnings: parsed.warnings,
+                };
+            }
+            return emptyHistory();
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'ENOENT') {
+                return emptyHistory();
+            }
+            logger.warn('[VersionWarningStore] Corrupt or unreadable file — treating as empty', { file });
+            return emptyHistory();
+        }
+    }
+    static async saveHistory(history) {
+        const file = filePath();
+        await fs.mkdir(path.dirname(file), { recursive: true });
+        await fs.writeFile(file, JSON.stringify(history, null, 2), 'utf-8');
+    }
+    /**
+     * True when this agent version was already acknowledged against the same
+     * recommended baseline. A moved baseline makes the stored marker stale.
+     */
+    static async hasWarned(agentName, agentVersion, supportedVersion) {
+        const history = await this.loadHistory();
+        return history.warnings.some((warning) => warning.agentName === agentName &&
+            warning.agentVersion === agentVersion &&
+            warning.supportedVersion === supportedVersion);
+    }
+    static async recordWarning(agentName, agentVersion, supportedVersion, codemieVersion) {
+        const history = await this.loadHistory();
+        const others = history.warnings.filter((warning) => !(warning.agentName === agentName && warning.agentVersion === agentVersion));
+        others.push({
+            agentName,
+            agentVersion,
+            supportedVersion,
+            codemieVersion,
+            warnedAt: new Date().toISOString(),
+        });
+        await this.saveHistory({ version: 1, warnings: others });
+    }
+    static async clear() {
+        const file = filePath();
+        const history = await this.loadHistory();
+        const removed = history.warnings.length;
+        try {
+            await fs.unlink(file);
+            return { removed };
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'ENOENT') {
+                return { removed: 0 };
+            }
+            // The user ran the reset intentionally — failing `codemie doctor` here
+            // would be worse than reporting "0 removed" and continuing the checks.
+            logger.warn('[VersionWarningStore] clear() failed; markers left in place', { file, code });
+            return { removed: 0 };
+        }
+    }
+}
+//# sourceMappingURL=version-warnings.js.map

package/dist/utils/version-warnings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-warnings.js","sourceRoot":"","sources":["../../src/utils/version-warnings.ts"],"names":[],"mappings":"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"}