@retaw106/mmc-oc 0.0.0-stage → 1.2.2

package/src/shared/data-path.ts

@@ -0,0 +1,310 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { getHarness, type HarnessId } from "./harness";
+import { createTestTempDir } from "./test-temp-dir";
+
+export function getDataDir(): string {
+    return process.env.XDG_DATA_HOME ?? path.join(os.homedir(), ".local", "share");
+}
+
+/**
+ * Per-harness scratch directory under the OS temp dir.
+ *
+ * Layout:
+ *   - OpenCode: `${os.tmpdir()}/opencode/magic-context/`
+ *   - Pi:       `${os.tmpdir()}/pi/magic-context/`
+ *
+ * Why a per-harness subtree of `os.tmpdir()`:
+ *   1. OpenCode Desktop runs as an Electron app with a permission sandbox.
+ *      Writing to arbitrary tmp paths can trigger user-visible permission
+ *      prompts; the `${tmpdir}/opencode/` subtree is allow-listed by
+ *      OpenCode, so anything we put under it never asks for permission.
+ *   2. Splitting harnesses keeps their logs and historian dump directories
+ *      cleanly separated. `doctor --issue` for each harness reports diagnostics
+ *      from the matching subtree, so issue reports do not include another
+ *      harness's log noise.
+ *   3. Pi has no permission sandbox, so the path choice is purely
+ *      cosmetic for Pi — it just keeps the layout symmetric.
+ *
+ * Pass an explicit `harness` only when the caller already knows the
+ * harness without relying on the global `setHarness()` state (e.g. the
+ * CLI's doctor commands, which target a specific harness regardless of
+ * which plugin is loaded). Production runtime callers should omit it so
+ * the helper picks up the boot-time harness automatically.
+ */
+export function getMagicContextTempDir(harness: HarnessId = getHarness()): string {
+    return path.join(os.tmpdir(), harness, "magic-context");
+}
+
+/**
+ * Standard log file path the plugin writes to. Each harness writes to a
+ * separate log under its own subtree so a machine running multiple harnesses
+ * does not interleave session traces.
+ *
+ * The plugin's buffered logger calls this on every flush rather than
+ * caching, so the boot-time `setHarness()` call is reflected in the next
+ * flush.
+ */
+export function getMagicContextLogPath(harness: HarnessId = getHarness()): string {
+    // An explicit override wins over the harness temp-dir default, so users on
+    // sandboxed/ephemeral setups (Docker, CI) can point the diagnostic log at a
+    // persistent or shared path. Blank/whitespace is treated as unset.
+    const envPath = process.env.MMC_LOG_PATH?.trim();
+    if (envPath) return envPath;
+    return path.join(getMagicContextTempDir(harness), "magic-context.log");
+}
+
+/**
+ * Directory used for both historian validation-failure dumps and the
+ * existing-state offload XMLs that large historian/recomp passes write
+ * before invoking the model. Per-harness so dumps from different
+ * harnesses don't collide on filename and so `doctor --issue` for each
+ * harness reports only its own historian artifacts.
+ */
+export function getMagicContextHistorianDir(harness: HarnessId = getHarness()): string {
+    return path.join(getMagicContextTempDir(harness), "historian");
+}
+
+/**
+ * Project-local magic-context artifact directory.
+ *
+ * Layout: `<project-directory>/.mmc/magic-context/`
+ *
+ * Used for artifacts that the historian/recomp pipeline writes during a run
+ * and that the model is asked to read via its native Read tool. OpenCode's
+ * `external_directory` permission system asks the user before reading any
+ * file outside the project directory or its worktree, which interrupts every
+ * historian run when artifacts live under `os.tmpdir()`. Writing under the
+ * project's own `.mmc/` subtree falls inside the project boundary and
+ * never triggers a permission prompt.
+ *
+ * `.mmc/` is the shared MMC per-project dir (also holds the
+ * project config `mmc.jsonc`). Because these artifacts are transient
+ * debug dumps that shouldn't dirty the user's repo, the first write also drops
+ * a fenced-block `.gitignore` entry ignoring this subdir (see
+ * ensureMmcArtifactGitignore) while leaving `*.jsonc` config tracked.
+ *
+ * Migration note: artifacts used to live under `.opencode/magic-context/`. We
+ * cut the write path forward only — old transient dumps are git-ignored and
+ * regenerated, so they are intentionally NOT migrated (left to be cleaned).
+ *
+ * Logger does NOT use this — log files stay in the per-harness tmp subtree
+ * because they are written by the plugin process itself (no model-side Read
+ * tool call, no permission prompt) and span sessions/projects.
+ */
+export function getProjectMagicContextDir(directory: string): string {
+    return path.join(directory, ".mmc", "magic-context");
+}
+
+const GITIGNORE_GUARD_OPEN = "# >>> mmc:magic-context";
+const GITIGNORE_GUARD_CLOSE = "# <<< mmc:magic-context";
+
+/**
+ * Ensure `<project>/.mmc/.gitignore` ignores Magic Context's transient
+ * artifact subdir (`magic-context/`) without touching anything else in the
+ * shared `.mmc/` dir — the project config `mmc.jsonc` stays
+ * tracked, and any sibling module's (e.g. AFT's) entries are preserved.
+ *
+ * Uses the shared MMC fenced-block convention: each module owns exactly
+ * its `# >>> mmc:<module>` … `# <<< mmc:<module>` block and appends
+ * it idempotently (no-op when its own guard line is already present). This lets
+ * multiple mmc modules coexist in one `.gitignore` without clobbering.
+ *
+ * Best-effort: a write failure never blocks an artifact write (the caller
+ * already degrades gracefully on its own write failures).
+ */
+export function ensureMmcArtifactGitignore(directory: string): void {
+    try {
+        const mmcDir = path.join(directory, ".mmc");
+        const gitignorePath = path.join(mmcDir, ".gitignore");
+        let existing = "";
+        if (existsSync(gitignorePath)) {
+            existing = readFileSync(gitignorePath, "utf8");
+            // Already fenced by us — nothing to do.
+            if (existing.includes(GITIGNORE_GUARD_OPEN)) return;
+        }
+        const block = `${GITIGNORE_GUARD_OPEN}\nmagic-context/\n${GITIGNORE_GUARD_CLOSE}\n`;
+        const needsLeadingNewline = existing.length > 0 && !existing.endsWith("\n");
+        const next = existing + (needsLeadingNewline ? "\n" : "") + block;
+        mkdirSync(mmcDir, { recursive: true });
+        writeFileSync(gitignorePath, next, "utf8");
+    } catch {
+        // best-effort — never block an artifact write on the gitignore.
+    }
+}
+
+/**
+ * Project-local historian artifact directory.
+ *
+ * Layout: `<project-directory>/.opencode/magic-context/historian/`
+ *
+ * Used for:
+ *   - existing-state offload XMLs that long historian/recomp passes write
+ *     before invoking the model (the model reads the file via Read tool)
+ *   - validation-failure dump XMLs preserved for debugging
+ *
+ * Callers must `mkdirSync(dir, { recursive: true })` before writing — the
+ * `.opencode/` parent may not exist on a fresh project, and write failures
+ * here must degrade gracefully (e.g. historian falls back to inline state).
+ */
+export function getProjectMagicContextHistorianDir(directory: string): string {
+    return path.join(getProjectMagicContextDir(directory), "historian");
+}
+
+export function getOpenCodeStorageDir(): string {
+    return path.join(getDataDir(), "opencode", "storage");
+}
+
+/**
+ * Resolve the shared magic-context storage directory.
+ *
+ * Magic-context's own data (compartments, facts, memories, embeddings, dream
+ * runs, notes, etc.) lives at this path regardless of which harness loaded the
+ * plugin (OpenCode or Pi). This enables:
+ *   - Shared project memories across harnesses
+ *   - Shared embedding cache
+ *   - Shared Dreamer runs (one per project per machine)
+ *   - Future cross-harness session migration
+ *
+ * Resolution precedence: test isolation, MMC_STORAGE_DIR, XDG data
+ * home, then the platform default. The explicit override is a complete storage
+ * directory and must be absolute so every process on a host selects one store.
+ *
+ * TEST-ISOLATION GUARD. `openDatabase()` has been guarded in
+ * `resolveDatabasePath()` since the 2026-06-01 (v26) and 2026-06-19 (v41)
+ * incidents, in which unisolated tests migrated the user's REAL shared DB.
+ * Every OTHER caller bypassed that guard — notably the CLI doctors, which
+ * build `join(getMagicContextStorageDir(), "context.db")` themselves and run
+ * `PRAGMA integrity_check` against it. A test that deletes XDG_DATA_HOME to
+ * exercise path fallbacks cannot restore isolation by setting
+ * `process.env.HOME`: bun caches `os.homedir()` at startup, so `getDataDir()`
+ * still resolves to the real home. MMC_TEST_DATA_DIR — set by
+ * `packages/plugin/test-preload.ts`, and restored by any test that touches it
+ * — is honored here, so the preload's "cannot be defeated" guarantee holds for
+ * every caller, not just `openDatabase()`. It is never set in production.
+ *
+ * CWD-INDEPENDENT BACKSTOP. The preload only runs when `bun test`'s CWD has a
+ * bunfig wiring `[test] preload`. A run from a dir WITHOUT that wiring (a
+ * package missing its bunfig, or a brand-new one) executes every *.test.ts with
+ * NO preload, and this resolver would hand back the REAL shared path — which is
+ * how the live DB reached v41. Bun sets NODE_ENV=test for EVERY `bun test`
+ * regardless of CWD, and production never sets it, so that window redirects to
+ * a memoized throwaway dir instead. It lives here rather than in
+ * `resolveDatabasePath()` so direct callers (the CLI doctors' own
+ * `PRAGMA integrity_check`, announcements, the models.dev cache) are covered
+ * too — they never go through the DB resolver.
+ *
+ * In production, MMC_STORAGE_DIR takes precedence over XDG_DATA_HOME.
+ * Test isolation remains authoritative so an ambient override cannot redirect
+ * a test into a user's real shared database.
+ */
+export type MagicContextStorageSource =
+    | "test isolation"
+    | "environment override"
+    | "XDG_DATA_HOME"
+    | "platform default";
+
+export interface MagicContextStorageResolution {
+    path: string;
+    source: MagicContextStorageSource;
+}
+
+export function getMagicContextStorageResolution(): MagicContextStorageResolution {
+    const testDataDir = process.env.MMC_TEST_DATA_DIR?.trim();
+    if (testDataDir) {
+        const perTestDataHome = process.env.XDG_DATA_HOME?.trim();
+        if (perTestDataHome && path.resolve(perTestDataHome) !== path.resolve(testDataDir)) {
+            return {
+                path: path.join(perTestDataHome, "mmc"),
+                source: "test isolation",
+            };
+        }
+        return {
+            path: path.join(testDataDir, "mmc"),
+            source: "test isolation",
+        };
+    }
+    if (process.env.NODE_ENV === "test") {
+        return { path: getTestBackstopStorageDir(), source: "test isolation" };
+    }
+    const explicitStorageDir = process.env.MMC_STORAGE_DIR?.trim();
+    if (explicitStorageDir) {
+        if (!path.isAbsolute(explicitStorageDir)) {
+            throw new Error("MMC_STORAGE_DIR must be an absolute path");
+        }
+        return { path: explicitStorageDir, source: "environment override" };
+    }
+    const xdgDataHome = process.env.XDG_DATA_HOME?.trim();
+    if (xdgDataHome) {
+        return {
+            path: path.join(xdgDataHome, "mmc"),
+            source: "XDG_DATA_HOME",
+        };
+    }
+    return {
+        path: path.join(os.homedir(), ".local", "share", "mmc"),
+        source: "platform default",
+    };
+}
+
+export function getMagicContextStorageDir(): string {
+    return getMagicContextStorageResolution().path;
+}
+
+let testBackstopStorageDir: string | null = null;
+let testBackstopWarned = false;
+
+/**
+ * Memoized per process so repeated calls in the same unisolated test resolve to
+ * the SAME path — `openDatabase()` caches by path, and a fresh temp dir per call
+ * would defeat that cache and hand back different DB handles.
+ */
+function getTestBackstopStorageDir(): string {
+    if (!testBackstopStorageDir) {
+        // Registered so the test preload's exit cleanup removes it; the preload's
+        // stale sweep also recognizes the prefix.
+        const { dir } = createTestTempDir("mc-test-db-backstop-");
+        testBackstopStorageDir = path.join(dir, "mmc");
+    }
+    if (!testBackstopWarned) {
+        testBackstopWarned = true;
+        // Deliberately console, not the logger: logger.ts imports this module.
+        console.warn(
+            "[magic-context] TEST BACKSTOP: NODE_ENV=test with no MMC_TEST_DATA_DIR " +
+                `— redirecting storage to a throwaway temp dir (${testBackstopStorageDir}) so no ` +
+                "test can touch the user's real shared database. Wire `[test] preload` in this " +
+                "package's bunfig.toml.",
+        );
+    }
+    return testBackstopStorageDir;
+}
+
+/**
+ * Legacy magic-context storage directory used by the OpenCode plugin before the
+ * shared mmc path. Used only for one-time migration of existing data into
+ * the new shared location. The legacy directory is left in place after copy so
+ * users can roll back if needed; manual cleanup is safe after one stable
+ * release.
+ */
+export function getLegacyOpenCodeMagicContextStorageDir(): string {
+    return path.join(getOpenCodeStorageDir(), "plugin", "magic-context");
+}
+
+/**
+ * Resolve OpenCode's cache base directory.
+ *
+ * OpenCode uses the `xdg-basedir` package, which — on every platform, including
+ * Windows — falls back to `<homedir>/.cache` when `XDG_CACHE_HOME` is unset.
+ * A previous Windows-specific branch that resolved to `%LOCALAPPDATA%` did not
+ * match OpenCode's own resolution and caused `doctor --force` to target a
+ * non-existent directory, leaving the real cache at `C:\Users\<user>\.cache`
+ * untouched.
+ */
+export function getCacheDir(): string {
+    return process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), ".cache");
+}
+
+export function getOpenCodeCacheDir(): string {
+    return path.join(getCacheDir(), "opencode");
+}

package/src/shared/error-message.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "bun:test";
+import { describeError, getErrorMessage } from "./error-message";
+
+describe("describeError", () => {
+    it("extracts name and message from standard Error", () => {
+        const err = new TypeError("boom");
+        const desc = describeError(err);
+        expect(desc.name).toBe("TypeError");
+        expect(desc.message).toBe("boom");
+        expect(desc.brief).toContain("TypeError");
+        expect(desc.brief).toContain('message="boom"');
+    });
+
+    it("surfaces class name when message is empty (NotFoundError case)", () => {
+        class NotFoundError extends Error {
+            constructor() {
+                super("");
+                this.name = "NotFoundError";
+            }
+        }
+        const err = new NotFoundError();
+        const desc = describeError(err);
+        expect(desc.name).toBe("NotFoundError");
+        expect(desc.message).toBe("");
+        // brief must still carry a useful signal even with empty message
+        expect(desc.brief).toContain("NotFoundError");
+    });
+
+    it("falls back to constructor.name when .name is missing", () => {
+        // Simulate an SDK-shaped object where .name is an empty string
+        const err = Object.assign(new Error("x"), { name: "" });
+        const desc = describeError(err);
+        // Falls back to constructor.name ("Error")
+        expect(desc.name).toBe("Error");
+    });
+
+    it("extracts status/code fields from HTTP-style errors", () => {
+        const err = Object.assign(new Error("not found"), {
+            status: 404,
+            code: "ENOTFOUND",
+        });
+        const desc = describeError(err);
+        expect(desc.status).toBe("404");
+        expect(desc.code).toBe("ENOTFOUND");
+        expect(desc.brief).toContain("status=404");
+        expect(desc.brief).toContain("code=ENOTFOUND");
+    });
+
+    it("captures first stack frames in stackHead", () => {
+        const err = new Error("with stack");
+        const desc = describeError(err);
+        expect(desc.stackHead).toBeDefined();
+        expect(desc.stackHead?.length).toBeGreaterThan(0);
+    });
+
+    it("handles non-Error thrown values", () => {
+        const desc = describeError("plain string");
+        expect(desc.brief).toContain("plain string");
+        expect(desc.stringForm).toContain("plain string");
+    });
+
+    it("handles objects without .message", () => {
+        const desc = describeError({ name: "WeirdError" });
+        expect(desc.name).toBe("WeirdError");
+        expect(desc.message).toBe("");
+        expect(desc.brief).toContain("WeirdError");
+    });
+
+    it("handles undefined/null", () => {
+        expect(describeError(undefined).brief).toBeTruthy();
+        expect(describeError(null).brief).toBeTruthy();
+    });
+
+    it("surfaces cause name when present", () => {
+        const cause = new TypeError("inner");
+        const outer = new Error("outer");
+        (outer as unknown as { cause: unknown }).cause = cause;
+        const desc = describeError(outer);
+        expect(desc.causeName).toBe("TypeError");
+        expect(desc.brief).toContain("cause=TypeError");
+    });
+
+    it("clips very long messages in brief", () => {
+        const long = "x".repeat(1000);
+        const err = new Error(long);
+        const desc = describeError(err);
+        expect(desc.brief.length).toBeLessThan(500);
+    });
+
+    it("getErrorMessage still works as before", () => {
+        expect(getErrorMessage(new Error("foo"))).toBe("foo");
+        expect(getErrorMessage("bar")).toBe("bar");
+    });
+});

package/src/shared/error-message.ts

@@ -0,0 +1,115 @@
+export function getErrorMessage(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Produce a rich, safe-to-log description of any thrown value.
+ *
+ * Motivated by SDK errors whose `.message` is empty while `.name`/`toString()`
+ * carry the actual signal (e.g. `NotFoundError` with no message on OpenCode
+ * session-delete races). Using {@link getErrorMessage} alone erases that signal.
+ *
+ * Captures:
+ * - `name` from the Error (defaults to `constructor.name`)
+ * - `message` (may be empty)
+ * - first few stack frames
+ * - `String(error)` so objects and custom toString surfaces are visible
+ * - Common HTTP-shape fields (`status`, `statusCode`, `code`)
+ * - `cause` chain summary (first level only)
+ *
+ * Returns a compact, single-line-friendly string suitable for log lines,
+ * plus a structured object for callers that want individual fields.
+ */
+export interface ErrorDescription {
+    name: string;
+    message: string;
+    status?: string;
+    code?: string;
+    causeName?: string;
+    stackHead?: string;
+    stringForm: string;
+    /** Best short summary for human-readable logs. Never empty. */
+    brief: string;
+}
+
+function readString(value: unknown): string | undefined {
+    if (typeof value === "string" && value.length > 0) return value;
+    if (typeof value === "number") return String(value);
+    return undefined;
+}
+
+function clip(value: string, max: number): string {
+    if (value.length <= max) return value;
+    return `${value.slice(0, max)}…`;
+}
+
+export function describeError(error: unknown): ErrorDescription {
+    const stringForm = clip(safeString(error), 400);
+
+    if (!(error instanceof Error) && !(error && typeof error === "object")) {
+        return {
+            name: typeof error,
+            message: "",
+            stringForm,
+            brief: stringForm || "<empty>",
+        };
+    }
+
+    const obj = error as Record<string, unknown>;
+    const nameFromField = readString(obj.name);
+    const nameFromCtor = error?.constructor?.name;
+    const name = nameFromField ?? nameFromCtor ?? "Error";
+
+    const message = readString(obj.message) ?? "";
+    const status = readString(obj.status) ?? readString(obj.statusCode);
+    const code = readString(obj.code);
+
+    let causeName: string | undefined;
+    const cause = obj.cause;
+    if (cause && typeof cause === "object") {
+        const causeRecord = cause as Record<string, unknown>;
+        causeName =
+            readString(causeRecord.name) ??
+            (cause as { constructor?: { name?: string } }).constructor?.name;
+    }
+
+    const stack = readString(obj.stack);
+    const stackHead = stack
+        ? stack
+              .split("\n")
+              .slice(0, 4)
+              .map((l) => l.trim())
+              .filter((l) => l.length > 0)
+              .join(" | ")
+        : undefined;
+
+    const briefParts: string[] = [];
+    if (name) briefParts.push(name);
+    if (message) briefParts.push(`message="${clip(message, 200)}"`);
+    if (status) briefParts.push(`status=${status}`);
+    if (code) briefParts.push(`code=${code}`);
+    if (causeName) briefParts.push(`cause=${causeName}`);
+    if (!message && stringForm && stringForm !== name) {
+        briefParts.push(`str="${clip(stringForm, 200)}"`);
+    }
+    const brief = briefParts.join(" ") || stringForm || name;
+
+    return {
+        name,
+        message,
+        ...(status ? { status } : {}),
+        ...(code ? { code } : {}),
+        ...(causeName ? { causeName } : {}),
+        ...(stackHead ? { stackHead } : {}),
+        stringForm,
+        brief,
+    };
+}
+
+function safeString(value: unknown): string {
+    try {
+        return String(value);
+    } catch {
+        return "<unstringifiable>";
+    }
+}

package/src/shared/escalation-bands.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from "bun:test";
+import { escalationBands } from "./escalation-bands";
+
+describe("escalationBands", () => {
+    test.each([
+        [65, 85],
+        [80, 85],
+        [88, 90],
+        [90, 92],
+    ])("keeps the force band ordered for threshold %i", (threshold, expectedForce) => {
+        const bands = escalationBands(threshold);
+        expect(bands.forceMaterializationPercentage).toBe(expectedForce);
+        expect(threshold).toBeLessThan(bands.forceMaterializationPercentage);
+        expect(bands.forceMaterializationPercentage).toBeGreaterThanOrEqual(85);
+        expect(bands.forceMaterializationPercentage).toBeLessThan(95);
+        expect(bands.emergencyPercentage).toBe(95);
+    });
+
+    test("preserves the exact pre-raise behavior through threshold 80", () => {
+        expect(escalationBands(65).forceMaterializationPercentage).toBe(85);
+        expect(escalationBands(80).forceMaterializationPercentage).toBe(85);
+    });
+});

package/src/shared/escalation-bands.ts

@@ -0,0 +1,18 @@
+export const MAX_EXECUTE_THRESHOLD = 90;
+export const ABSOLUTE_EMERGENCY_PERCENTAGE = 95;
+
+export interface EscalationBands {
+    forceMaterializationPercentage: number;
+    emergencyPercentage: number;
+}
+
+/** Keep force cleanup above normal execution while preserving the absolute 95% wall. */
+export function escalationBands(effectiveThresholdPercentage: number): EscalationBands {
+    const threshold = Number.isFinite(effectiveThresholdPercentage)
+        ? Math.min(effectiveThresholdPercentage, MAX_EXECUTE_THRESHOLD)
+        : 65;
+    return {
+        forceMaterializationPercentage: Math.max(85, threshold + 2),
+        emergencyPercentage: ABSOLUTE_EMERGENCY_PERCENTAGE,
+    };
+}

package/src/shared/format-bytes.ts

@@ -0,0 +1,5 @@
+export function formatBytes(bytes: number): string {
+    if (bytes < 1024) return `${bytes}B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}

package/src/shared/format-threshold.ts

@@ -0,0 +1,54 @@
+/**
+ * Format an execute-threshold percentage for human-facing display.
+ *
+ * `executeThreshold` in the snapshot is always a percentage number, but it
+ * comes from two very different config paths:
+ *   1. `execute_threshold_percentage` (or its model-keyed variant) — user
+ *      configures an integer like 65 directly. We must render exactly that.
+ *   2. `execute_threshold_tokens` — user configures absolute token cap (e.g.
+ *      128000). The resolver in `event-resolvers.ts` divides that by the
+ *      model's context limit (`(128000 / 907788) * 100`) and the result is
+ *      a long float like `14.099783080260304` that overflows the TUI cell
+ *      (issue #90).
+ *
+ * Behaviour:
+ *   - Integer input (≤0.05 fractional drift) renders without decimals.
+ *   - Anything else is rendered with one decimal digit, which is precise
+ *     enough to convey the configured token budget without smearing across
+ *     two lines in a narrow sidebar.
+ *
+ * Returns the formatted percentage WITHOUT the trailing `%` so callers can
+ * compose richer strings like `47.5% / 65%` consistently.
+ */
+export function formatThresholdPercent(value: number | undefined | null): string {
+    if (typeof value !== "number" || !Number.isFinite(value)) return "—";
+    const rounded = Math.round(value);
+    if (Math.abs(value - rounded) < 0.05) return String(rounded);
+    return value.toFixed(1);
+}
+
+/**
+ * Build a terse "clamped" annotation for execute-threshold display, or "" when the
+ * configured value was not clamped. Status surfaces (/mmc-status text, pi status
+ * dialog) append this so a user who configured e.g. 190000 tokens on a 128K model
+ * sees that it was reduced to the 90% safety cap, instead of the value being
+ * silently ignored (issue #241). The note includes the configured value and the cap
+ * so the user can see the math.
+ *
+ * `maxPercentage` is passed in (rather than imported) to keep this shared module
+ * free of a dependency on the resolver that owns the cap constant.
+ */
+export function formatThresholdClampNote(opts: {
+    clamped?: boolean;
+    mode: "tokens" | "percentage";
+    /** Raw configured value before clamping (tokens in tokens mode, % in percentage mode). */
+    configuredValue?: number;
+    contextLimit: number;
+    maxPercentage: number;
+}): string {
+    if (!opts.clamped || opts.configuredValue === undefined) return "";
+    if (opts.mode === "tokens" && opts.contextLimit > 0) {
+        return ` [clamped: ${opts.configuredValue.toLocaleString()} > ${opts.maxPercentage}% of ${opts.contextLimit.toLocaleString()}]`;
+    }
+    return ` [clamped: ${opts.configuredValue}% > ${opts.maxPercentage}%]`;
+}