@retaw106/mmc-oc 0.0.0-stage → 1.2.2

package/src/shared/__fixtures__/window-overlay.v1.json

@@ -0,0 +1,337 @@
+{
+  "schema": "fusiform-window-overlay/v1",
+  "generated_at": "2026-08-13T15:12:00Z",
+  "batch": "1 of N \u2014 the geometry spec's measured rows, transcribed",
+  "minted_provider_ids": [
+    "openai-chatgpt-oauth"
+  ],
+  "relay_note": "Cells whose source_ref names mc-geometry-spec are RELAYED: the grade records the evidence class that document assigns, not evidence this seat verified independently. Where a primary source was on disk it was read directly and the source_ref names it instead.",
+  "cells": [
+    {
+      "provider_id": "openai-chatgpt-oauth",
+      "model_id": "gpt-5.6",
+      "facts": {
+        "window.enforced": {
+          "value": {
+            "kind": "bracket",
+            "at_least": 340000
+          },
+          "grade": "measured",
+          "units": "estimate",
+          "boundary": "Observed",
+          "source_ref": "mc-geometry-spec@06a0e5ac#measured-per-model-findings:gpt-5.6-oauth (operator-confirmed live)",
+          "observed_at": "2026-08-13T12:54:15Z"
+        },
+        "window.advertised": {
+          "value": {
+            "kind": "unknown",
+            "why": "never_measured"
+          },
+          "grade": "unknown",
+          "units": "provider",
+          "boundary": "Observed",
+          "source_ref": "codex-rs@32f4687b8c:models-manager/src/model_info.rs:125",
+          "observed_at": "2026-08-13T15:12:00Z"
+        },
+        "output.advertised": {
+          "value": {
+            "kind": "unknown",
+            "why": "never_measured"
+          },
+          "grade": "unknown",
+          "units": "provider",
+          "boundary": "Observed",
+          "source_ref": "codex-rs@32f4687b8c:protocol/src/openai_models.rs:409",
+          "observed_at": "2026-08-13T15:12:00Z"
+        }
+      },
+      "note": "window.advertised is UNKNOWN rather than 272000. The seed spec reads the 272k in codex-rs as a server-delivered advertisement; the source has it only in model_info_from_slug, the fallback for unrecognised slugs, beside used_fallback_model_metadata: true. Every other occurrence is a test fixture inheriting it. The server may also send 272k; the source does not establish that. output.advertised is unknown because ModelInfo carries no output field at all, so the client cannot request a cap and nothing states one."
+    },
+    {
+      "provider_id": "openai",
+      "model_id": "gpt-5.6",
+      "facts": {
+        "window.advertised": {
+          "value": {
+            "kind": "stated",
+            "value": 1050000
+          },
+          "grade": "provider_asserted_doc",
+          "units": "provider",
+          "boundary": "Observed",
+          "source_ref": "mc-geometry-spec@06a0e5ac#measured-per-model-findings:gpt-5.6-platform",
+          "observed_at": "2026-08-13T12:54:15Z"
+        },
+        "output.advertised": {
+          "value": {
+            "kind": "stated",
+            "value": 128000
+          },
+          "grade": "provider_asserted_doc",
+          "units": "provider",
+          "boundary": "Observed",
+          "source_ref": "mc-geometry-spec@06a0e5ac#measured-per-model-findings:gpt-5.6-platform",
+          "observed_at": "2026-08-13T12:54:15Z"
+        },
+        "geometry": {
+          "value": {
+            "kind": "stated",
+            "value": "shared_upfront"
+          },
+          "grade": "provider_asserted_doc",
+          "units": "provider",
+          "boundary": "Observed",
+          "source_ref": "https://platform.openai.com/docs/guides/conversation-state (read 2026-08-13) \u2014 'The context window is the maximum number of tokens that can be used in a single request. This max tokens number includes input, output, and reasoning tokens.'",
+          "observed_at": "2026-08-13T12:54:15Z"
+        }
+      },
+      "note": "GEOMETRY VERIFIED AGAINST OPENAI'S OWN DOCS 2026-08-13: 'The context window is the maximum number of tokens that can be used in a single request. This max tokens number includes input, output, and reasoning tokens.' That establishes the wall COUNTS the combined total, which is the half of shared_upfront this cell asserts. WHAT THE DOC DOES NOT ESTABLISH is the other half \u2014 whether an over-window request is rejected up front or truncated. The seed spec attributes rejection to `truncation: disabled`, implying the same endpoint truncates when truncation is enabled, and this page does not mention truncation at all (the API reference that would is behind a 403 from here). So shared_upfront is correct for the truncation-disabled path and is NOT established as a property of the provider. See the design note's section 12: the combined-and-truncating combination has no enum value, and this is the request mode that reaches it. The window and output numbers are relayed from the seed spec; the catalog agrees with both for this path, which is exactly why the access-path split matters \u2014 the same catalog row is right here and wrong for openai-chatgpt-oauth."
+    },
+    {
+      "provider_id": "anthropic",
+      "model_id": "claude-opus-5",
+      "facts": {
+        "window.advertised": {
+          "value": {
+            "kind": "stated",
+            "value": 1000000
+          },
+          "grade": "provider_asserted_doc",
+          "units": "provider",
+          "boundary": "Observed",
+          "source_ref": "https://docs.claude.com/en/docs/build-with-claude/context-windows (read 2026-08-13) \u2014 'Claude Opus 5 ... has a 1M-token context window on the Claude API, Amazon Bedrock, Google Cloud, and Microsoft Foundry'",
+          "observed_at": "2026-08-13T12:54:15Z"
+        },
+        "output.advertised": {
+          "value": {
+            "kind": "stated",
+            "value": 128000
+          },
+          "grade": "provider_asserted_doc",
+          "units": "provider",
+          "boundary": "Observed",
+          "source_ref": "https://docs.claude.com/en/docs/build-with-claude/context-windows (read 2026-08-13) \u2014 'a request to any model with a 1M-token context window can generate up to 128k output tokens (max_tokens)'",
+          "observed_at": "2026-08-13T12:54:15Z"
+        },
+        "geometry": {
+          "value": {
+            "kind": "stated",
+            "value": "shared_truncating"
+          },
+          "grade": "provider_asserted_doc",
+          "units": "provider",
+          "boundary": "Asserted",
+          "source_ref": "https://docs.claude.com/en/docs/build-with-claude/context-windows (read 2026-08-13) \u2014 'Context window overflow behavior'",
+          "observed_at": "2026-08-13T12:54:15Z"
+        }
+      },
+      "note": "VERIFIED AGAINST THE PRIMARY SOURCE 2026-08-13, replacing the seed spec as source_ref. The doc names Opus 5 explicitly in a list of 1M-window models, and states the 128k output cap as a property of any 1M-window model rather than of this model. NO access-path id minted: the window holds on the Claude API, Bedrock, Google Cloud and Microsoft Foundry alike, so by mint-on-divergence there is nothing to fork. GEOMETRY IS THE INTERESTING PART AND IT SPLITS. The prompt-only wall is universal: 'if the input alone already exceeds the model's context window, the API returns a 400 invalid_request_error (prompt is too long) ON EVERY MODEL'. What happens to over-window OUTPUT is version-gated AND header-controlled: 4.5+ accepts the request and stops with stop_reason model_context_window_exceeded, earlier models return a validation error, and earlier models can OPT IN to the newer behaviour with the model-context-window-exceeded-2025-08-26 beta header. So a pre-4.5 model's geometry depends on a request header \u2014 the second instance of the request-dependence recorded in the design note's section 12, and the first with a named mechanism. shared_truncating is correct for Opus 5 and must not be inherited by an older Claude."
+    },
+    {
+      "provider_id": "xai",
+      "model_id": "grok-4.6",
+      "facts": {
+        "window.enforced": {
+          "value": {
+            "kind": "stated",
+            "value": 500000
+          },
+          "grade": "measured",
+          "units": "provider",
+          "boundary": "Observed",
+          "source_ref": "mc-geometry-spec@06a0e5ac#measured-per-model-findings:grok-4.6",
+          "observed_at": "2026-08-13T12:54:15Z"
+        },
+        "output.default": {
+          "value": {
+            "kind": "stated",
+            "value": 128000
+          },
+          "grade": "provider_asserted_doc",
+          "units": "provider",
+          "boundary": "Observed",
+          "source_ref": "mc-geometry-spec@06a0e5ac#measured-per-model-findings:grok-4.6",
+          "observed_at": "2026-08-13T12:54:15Z"
+        },
+        "geometry": {
+          "value": {
+            "kind": "stated",
+            "value": "shared_truncating"
+          },
+          "grade": "measured",
+          "units": "provider",
+          "boundary": "Observed",
+          "source_ref": "mc-geometry-spec@06a0e5ac#provider-geometry-classes:xai (error text 'maximum prompt length is N' is a prompt-only wall)",
+          "observed_at": "2026-08-13T12:54:15Z"
+        },
+        "window.advertised": {
+          "value": {
+            "kind": "stated",
+            "value": 500000
+          },
+          "grade": "provider_asserted_doc",
+          "units": "provider",
+          "boundary": "Observed",
+          "source_ref": "https://docs.x.ai/developers/models/grok-4.6.md (read 2026-08-13) \u2014 'Context window: 500,000 tokens'",
+          "observed_at": "2026-08-13T16:30:00Z"
+        }
+      },
+      "note": "No output.enforced cell: the documented behaviour is no fixed cap, with the ceiling being window minus prompt. That is a FUNCTION of the request, not a constant, and this schema has no shape for it \u2014 geometry plus window is what a consumer needs to derive it. Writing a number here would state a constant that does not exist. The catalog's output=500000 equals its context and is a placeholder by the spec's own rule. This model arrived AFTER the embedded seed snapshot (seed fetched 2026-08-12T10:07:29Z, model first observed 16:12:49Z), so it cannot be join-checked against the seed; post_seed records how its existence was verified instead. ADVERTISED ADDED FROM XAI'S OWN MODEL PAGE 2026-08-13, and it AGREES with the measured enforced wall. That is the dataset's first corroboration rather than a correction, and it is worth recording as such: the advertised/enforced split exists because they CAN differ, not because they always do, and a split that only ever shows divergence would be evidence the measurement is biased toward cases someone went looking at. Two independent sources, one number. Note the two facts remain separate cells rather than being collapsed: they agree today, and collapsing them would destroy the ability to notice when they stop. The page states no output cap at all, which is consistent with the spec's 'no fixed cap' but does not establish it \u2014 an absent statement is not a statement of absence.",
+      "post_seed": {
+        "verified_at": "2026-08-13T15:12:00Z",
+        "evidence": "fusiform era history: existence observed present at 2026-08-12T16:12:49Z, changed between 15:42:49Z and 16:12:49Z",
+        "catalog_limit_at_verification": {
+          "context": 500000,
+          "output": 500000
+        }
+      }
+    },
+    {
+      "provider_id": "ollama-cloud",
+      "model_id": "deepseek-v4-flash",
+      "facts": {
+        "window.enforced": {
+          "value": {
+            "kind": "stated",
+            "value": 1048576
+          },
+          "grade": "provider_asserted_doc",
+          "units": "provider",
+          "boundary": "Observed",
+          "source_ref": "mc-geometry-spec@06a0e5ac#measured-per-model-findings:deepseek-v4-flash-ollama-cloud",
+          "observed_at": "2026-08-13T12:54:15Z"
+        },
+        "output.enforced": {
+          "value": {
+            "kind": "stated",
+            "value": 65536
+          },
+          "grade": "provider_asserted_doc",
+          "units": "provider",
+          "boundary": "Observed",
+          "source_ref": "https://github.com/ollama/ollama/issues/16890",
+          "observed_at": "2026-08-13T12:54:15Z"
+        }
+      },
+      "note": "The catalog row is wrong twice over here, which is why this cell leads the batch: output equals context so it is a placeholder by the spec's rule, AND the real cap is 16x smaller. A consumer trusting the row reserves 1M against a 64k wall and gets an HTTP 400. NOT written as a provider-wide wildcard: the evidence names this model, and asserting it for all 20 ollama-cloud models would manufacture a claim from absence. If the cap is genuinely path-wide, one report naming a second model promotes it."
+    },
+    {
+      "provider_id": "moonshotai",
+      "model_id": "kimi-k3",
+      "facts": {
+        "window.advertised": {
+          "value": {
+            "kind": "stated",
+            "value": 1048576
+          },
+          "grade": "provider_asserted_doc",
+          "units": "provider",
+          "boundary": "Observed",
+          "source_ref": "mc-geometry-spec@06a0e5ac#measured-per-model-findings:kimi-k3",
+          "observed_at": "2026-08-13T12:54:15Z"
+        },
+        "output.default": {
+          "value": {
+            "kind": "stated",
+            "value": 131072
+          },
+          "grade": "provider_asserted_doc",
+          "units": "provider",
+          "boundary": "Observed",
+          "source_ref": "mc-geometry-spec@06a0e5ac#measured-per-model-findings:kimi-k3",
+          "observed_at": "2026-08-13T12:54:15Z"
+        },
+        "output.advertised": {
+          "value": {
+            "kind": "stated",
+            "value": 1048576
+          },
+          "grade": "provider_asserted_doc",
+          "units": "provider",
+          "boundary": "Observed",
+          "source_ref": "mc-geometry-spec@06a0e5ac#measured-per-model-findings:kimi-k3",
+          "observed_at": "2026-08-13T12:54:15Z"
+        }
+      },
+      "note": "The clearest case for output.default existing as its own fact. models.dev publishes output=131072 for this model, and 131072 is the DEFAULT you get without asking \u2014 the cap is 1M, configurable. Some aggregators read the same 131k as the context window. One number, three wrong readings, and the split is what stops a consumer from inheriting any of them."
+    },
+    {
+      "provider_id": "google",
+      "model_id": "gemini-3.5-flash",
+      "facts": {
+        "window.advertised": {
+          "value": {
+            "kind": "stated",
+            "value": 1048576
+          },
+          "grade": "provider_asserted_doc",
+          "units": "provider",
+          "boundary": "Observed",
+          "source_ref": "mc-geometry-spec@06a0e5ac#measured-per-model-findings:gemini-3.5-flash",
+          "observed_at": "2026-08-13T12:54:15Z"
+        },
+        "output.advertised": {
+          "value": {
+            "kind": "stated",
+            "value": 65536
+          },
+          "grade": "provider_asserted_doc",
+          "units": "provider",
+          "boundary": "Observed",
+          "source_ref": "mc-geometry-spec@06a0e5ac#measured-per-model-findings:gemini-3.5-flash",
+          "observed_at": "2026-08-13T12:54:15Z"
+        },
+        "geometry": {
+          "value": {
+            "kind": "unknown",
+            "why": "never_measured"
+          },
+          "grade": "unknown",
+          "units": "provider",
+          "boundary": "Observed",
+          "source_ref": "https://ai.google.dev/gemini-api/docs/tokens (contradicts itself; see note)",
+          "observed_at": "2026-08-13T16:05:00Z"
+        }
+      },
+      "note": "NO antigravity id minted: 1M input and 65k output on both the Antigravity and generateContent paths, so nothing has diverged. Antigravity's self-compaction around 135k is harness behaviour, not a window, and does not belong in this dataset. Separate geometry means a smaller output request buys no input headroom \u2014 the input_token_limit is the usable input, full stop. GEOMETRY DOWNGRADED TO UNKNOWN 2026-08-13 after reading the primary source. The seed spec classifies Gemini as `separate` citing input_token_limit and output_token_limit as independent model constants. Those fields are real (https://ai.google.dev/api/models: 'Maximum number of input tokens allowed', 'Maximum number of output tokens available'), but the same docs page that demonstrates them states the opposite about the wall: 'The context window defines the combined limit of input and output tokens.' Two field constants and a combined wall are not contradictory \u2014 the fields can be per-side caps INSIDE a shared budget \u2014 so the field names do not establish `separate`. Neither reading is established by documentation alone; only a request that trades output for input can settle it."
+    },
+    {
+      "provider_id": "deepseek",
+      "model_id": "*",
+      "facts": {
+        "geometry": {
+          "value": {
+            "kind": "unknown",
+            "why": "never_measured"
+          },
+          "grade": "unknown",
+          "units": "provider",
+          "boundary": "Observed",
+          "source_ref": "magic-context@5ac4408d:packages/plugin/src/features/magic-context/overflow-detection.ts:68 \u2014 pattern tagged `combined`, attribution confirmed by MC 2026-08-13 as observed-emitting-the-string only",
+          "observed_at": "2026-08-13T17:05:00Z"
+        }
+      },
+      "note": "AN EXPLICIT REFUSAL, minted because a specific wrong inference is available. DeepSeek appears in MC's overflow table under the pattern `maximum context length is (N) tokens`, tagged `combined`. MC confirmed 2026-08-13 that the tag was assigned ONCE for the pattern, reasoned from OpenAI's documented semantics, and inherited by every provider observed emitting that string \u2014 so the per-provider evidence establishes that DeepSeek EMITS the text, not that its wall counts combined. Without this cell a future transcriber mining that table would mint `combined` for DeepSeek with an honest-looking source_ref, which is the inference this dataset exists to refuse. Wildcard because the claim is about the provider's wall and nothing model-specific is known."
+    },
+    {
+      "provider_id": "openrouter",
+      "model_id": "*",
+      "facts": {
+        "geometry": {
+          "value": {
+            "kind": "unknown",
+            "why": "not_single_valued_at_key"
+          },
+          "grade": "measured",
+          "units": "provider",
+          "boundary": "Observed",
+          "source_ref": "models.dev@2026-08-13: openrouter carries 348 models spanning other providers' catalogs; MC confirmed 2026-08-13 that the wall which fires belongs to whichever upstream served the request",
+          "observed_at": "2026-08-13T17:05:00Z"
+        }
+      },
+      "note": "NOT AN ABSENCE OF EVIDENCE \u2014 a positive, evidenced claim that this KEY cannot hold a single geometry. OpenRouter routes to heterogeneous backends, so the wall that fires belongs to whichever upstream served the request; measuring once yields a value correct for that routing decision and wrong for the next. GRADE IS `measured`, NOT `unknown`: the claim rests on evidence (the catalog shows 348 models spanning other providers' offerings; MC confirmed the routing behaviour), and a grade of unknown would say nobody has established it, which is false. This is the first cell where kind=unknown and grade!=unknown, and the two fields are doing different jobs exactly as designed: the VALUE is unknown, the CLAIM ABOUT WHY is measured. The reason value forbids promoting any measured report into a stated or bracket cell at this key without a routing discriminant \u2014 that clause is what makes it load-bearing rather than decorative."
+    }
+  ],
+  "source_revision_note": "Cells transcribed from mc-geometry-spec were read at c6a85d85 and their source_ref names 06a0e5ac, the current revision. The bump is verified rather than assumed: every row transcribed here is byte-identical between the two revisions (checked per row with git show). The Codex row DID change between them, and no cell here cites the spec for Codex \u2014 those cells cite codex-rs directly. Pointing at the newer revision matters because c6a85d85 carried a misattributed Codex number, and a reader resolving a source_ref should land on a document without a known bad row in it.",
+  "additive_note": "The reason value `not_single_valued_at_key` was added 2026-08-13 WITHOUT a schema version bump, deliberately. Bumping would trigger the file-level refusal rule and cost a consumer all 9 cells over one additive value affecting 1. Unbumped, a consumer that does not know the value skips that single cell and merges the other 8 \u2014 which is the correct degradation for an addition."
+}

package/src/shared/announcement.test.ts

@@ -0,0 +1,198 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { createTestTempDirFromPath } from "./test-temp-dir";
+
+/**
+ * `announcement.ts` reads/writes a single `last_announced_version` file under
+ * `getMagicContextStorageDir()`. The behavior we test:
+ *   1. `markAnnouncementSeen` then `readLastAnnouncedVersion` round-trips
+ *   2. `shouldShowAnnouncement` returns false after a matching mark
+ *   3. `shouldShowAnnouncement` returns true after a non-matching (older) mark
+ *   4. `shouldShowAnnouncement` seeds state + returns false on first run / wiped
+ *      sandbox (no prior file), so fresh installs and ephemeral envs aren't
+ *      spammed with a changelog (issue #99)
+ *   5. Empty-version inputs are no-ops (don't crash, don't write garbage)
+ *
+ * We isolate writes by pointing `XDG_DATA_HOME` at a temp dir before requiring
+ * the module fresh per test, since the module captures the storage path at
+ * import time via `getMagicContextStorageDir()`.
+ */
+
+let tmpRoot = "";
+let originalXdg: string | undefined;
+
+beforeEach(() => {
+    tmpRoot = createTestTempDirFromPath(path.join(os.tmpdir(), "mc-announcement-test-"));
+    originalXdg = process.env.XDG_DATA_HOME;
+    process.env.XDG_DATA_HOME = tmpRoot;
+});
+
+afterEach(() => {
+    if (originalXdg === undefined) {
+        delete process.env.XDG_DATA_HOME;
+    } else {
+        process.env.XDG_DATA_HOME = originalXdg;
+    }
+    try {
+        // maxRetries/retryDelay ride out transient EBUSY/EPERM on Windows.
+        fs.rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+    } catch {
+        // best-effort
+    }
+});
+
+describe("announcement state persistence", () => {
+    test("round-trips a dismissed version through the file", async () => {
+        // Fresh import after XDG override so the module captures the temp path
+        const mod = await import(`./announcement?t=${Date.now()}-rt`);
+        const { readLastAnnouncedVersion, markAnnouncementSeen } = mod;
+
+        expect(readLastAnnouncedVersion()).toBe("");
+
+        markAnnouncementSeen("9.9.9");
+        expect(readLastAnnouncedVersion()).toBe("9.9.9");
+
+        markAnnouncementSeen("9.9.10");
+        expect(readLastAnnouncedVersion()).toBe("9.9.10");
+    });
+
+    test("ignores empty / zero-length version marks", async () => {
+        const mod = await import(`./announcement?t=${Date.now()}-empty`);
+        const { readLastAnnouncedVersion, markAnnouncementSeen } = mod;
+
+        markAnnouncementSeen("");
+        expect(readLastAnnouncedVersion()).toBe("");
+    });
+
+    test("creates the storage directory if it does not exist", async () => {
+        const mod = await import(`./announcement?t=${Date.now()}-mkdir`);
+        const { markAnnouncementSeen } = mod;
+
+        // Storage dir lives under tmpRoot + mmc — does not
+        // exist yet at the start of the test
+        const expectedDir = path.join(tmpRoot, "mmc");
+        expect(fs.existsSync(expectedDir)).toBe(false);
+
+        markAnnouncementSeen("0.21.7");
+
+        expect(fs.existsSync(expectedDir)).toBe(true);
+        expect(fs.readFileSync(path.join(expectedDir, "last_announced_version"), "utf-8")).toBe(
+            "0.21.7",
+        );
+    });
+
+    test("trims whitespace from stored version on read", async () => {
+        const mod = await import(`./announcement?t=${Date.now()}-trim`);
+        const { readLastAnnouncedVersion } = mod;
+
+        const dir = path.join(tmpRoot, "mmc");
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, "last_announced_version"), "  1.2.3  \n");
+
+        expect(readLastAnnouncedVersion()).toBe("1.2.3");
+    });
+});
+
+describe("shouldShowAnnouncement gating", () => {
+    test("returns false when the live version is already marked", async () => {
+        const mod = await import(`./announcement?t=${Date.now()}-match`);
+        const {
+            ANNOUNCEMENT_VERSION,
+            ANNOUNCEMENT_FEATURES,
+            markAnnouncementSeen,
+            shouldShowAnnouncement,
+        } = mod;
+
+        // Skip the test if announcements are currently disabled (empty constants)
+        // — the gate's empty-input behavior is covered separately below.
+        if (!ANNOUNCEMENT_VERSION || ANNOUNCEMENT_FEATURES.length === 0) {
+            return;
+        }
+
+        markAnnouncementSeen(ANNOUNCEMENT_VERSION);
+        expect(shouldShowAnnouncement()).toBe(false);
+    });
+
+    test("seeds state and returns false on first run / wiped sandbox (issue #99)", async () => {
+        const mod = await import(`./announcement?t=${Date.now()}-none`);
+        const {
+            ANNOUNCEMENT_VERSION,
+            ANNOUNCEMENT_FEATURES,
+            shouldShowAnnouncement,
+            readLastAnnouncedVersion,
+        } = mod;
+
+        if (!ANNOUNCEMENT_VERSION || ANNOUNCEMENT_FEATURES.length === 0) {
+            // When empty, the gate is always false regardless of state
+            expect(shouldShowAnnouncement()).toBe(false);
+            return;
+        }
+
+        // No mark exists yet (fresh install or ephemeral/wiped sandbox). The
+        // gate must NOT announce — it seeds the state to the current version and
+        // returns false, so first-run users and disposable containers are never
+        // spammed with a changelog they have no context for.
+        expect(readLastAnnouncedVersion()).toBe("");
+        expect(shouldShowAnnouncement()).toBe(false);
+        // The seed was written, so a subsequent check stays quiet too.
+        expect(readLastAnnouncedVersion()).toBe(ANNOUNCEMENT_VERSION);
+        expect(shouldShowAnnouncement()).toBe(false);
+    });
+
+    test("does not seed or advance state when an existing state file is unreadable/corrupt", async () => {
+        const mod = await import(`./announcement?t=${Date.now()}-corrupt`);
+        const { ANNOUNCEMENT_VERSION, ANNOUNCEMENT_FEATURES, shouldShowAnnouncement } = mod;
+
+        if (!ANNOUNCEMENT_VERSION || ANNOUNCEMENT_FEATURES.length === 0) {
+            expect(shouldShowAnnouncement()).toBe(false);
+            return;
+        }
+
+        const dir = path.join(tmpRoot, "mmc");
+        const file = path.join(dir, "last_announced_version");
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(file, "");
+
+        expect(shouldShowAnnouncement()).toBe(false);
+        expect(fs.readFileSync(file, "utf-8")).toBe("");
+    });
+
+    test("returns true when a different (older) version is marked", async () => {
+        const mod = await import(`./announcement?t=${Date.now()}-older`);
+        const {
+            ANNOUNCEMENT_VERSION,
+            ANNOUNCEMENT_FEATURES,
+            markAnnouncementSeen,
+            shouldShowAnnouncement,
+        } = mod;
+
+        if (!ANNOUNCEMENT_VERSION || ANNOUNCEMENT_FEATURES.length === 0) {
+            return;
+        }
+
+        markAnnouncementSeen("0.0.0-pre-historic");
+        expect(shouldShowAnnouncement()).toBe(true);
+    });
+
+    test("does NOT re-announce on a downgrade (stored version is newer)", async () => {
+        const mod = await import(`./announcement?t=${Date.now()}-downgrade`);
+        const {
+            ANNOUNCEMENT_VERSION,
+            ANNOUNCEMENT_FEATURES,
+            markAnnouncementSeen,
+            shouldShowAnnouncement,
+        } = mod;
+
+        if (!ANNOUNCEMENT_VERSION || ANNOUNCEMENT_FEATURES.length === 0) {
+            return;
+        }
+
+        // Stored version is far newer than the running binary (user downgraded).
+        // A bare string-inequality gate would re-show the OLD announcement; the
+        // semver gate must stay quiet (current is NOT > stored).
+        markAnnouncementSeen("999.0.0");
+        expect(shouldShowAnnouncement()).toBe(false);
+    });
+});