@retaw106/mmc-oc 1.2.3 → 2.0.0

package/src/shared/model-resolution.test.ts

@@ -18,8 +18,9 @@ describe("model-resolution", () => {
             const resolved = resolveHistorianAgentOverrides({
                 ...(fixture.temperature !== undefined ? { temperature: fixture.temperature } : {}),
                 maxTokens: 16_000,
-                opencode: { model: "google/flash", variant: "low" },
-                pi: { model: "pi/must-not-leak", thinking_level: "high" },
+                model: "google/flash",
+                variant: "low",
+                thinking_level: "high",
             });
             expect(resolved).toEqual({
                 maxTokens: 16_000,
@@ -61,8 +62,7 @@ describe("model-resolution", () => {
     test("keeps the flash calibration available only as an explicit override", () => {
         expect(
             resolveHistorianAgentOverrides({
-                opencode: { model: { model: "google/flash", variant: "fast" } },
-                pi: { model: "pi/ignored" },
+                model: { model: "google/flash", variant: "fast" },
                 two_pass: true,
             }),
         ).toEqual({
@@ -76,56 +76,46 @@ describe("model-resolution", () => {
         ).toMatchObject({ temperature: 0.1, maxTokens: 12_000 });
     });
 
-    test("does not inherit a block qualifier into unqualified fallbacks", () => {
+    test("does not inherit the primary qualifier into unqualified fallbacks", () => {
         const config = {
             historian: {
-                opencode: {
-                    model: "open/primary",
-                    fallback_models: ["open/fallback"],
-                    variant: "primary-only",
-                },
-                pi: {
-                    model: "pi/primary",
-                    fallback_models: ["pi/fallback"],
-                    thinking_level: "high",
-                },
+                model: "open/primary",
+                fallback_models: ["open/fallback"],
+                variant: "primary-only",
+                thinking_level: "high",
             },
         };
 
         // Inheritance is deliberately absent because a fallback model may not support the
-        // qualifier selected for the primary model.
+        // qualifier selected for the primary model. Each harness reads only its own
+        // qualifier (OpenCode variant, Pi thinking_level) from the flat entry.
         expect(resolveHistorianModel(config, "opencode")).toEqual({
             primary: { model: "open/primary", qualifier: "primary-only" },
             fallbacks: [{ model: "open/fallback" }],
         });
         expect(resolveHistorianModel(config, "pi")).toEqual({
-            primary: { model: "pi/primary", qualifier: "high" },
-            fallbacks: [{ model: "pi/fallback" }],
+            primary: { model: "open/primary", qualifier: "high" },
+            fallbacks: [{ model: "open/fallback" }],
         });
     });
 
-    test("reads historian attempts only from the requested harness", () => {
+    test("selects the requested harness's qualifier from a shared flat entry", () => {
         const config = {
             historian: {
-                model: "flat/ignored",
-                opencode: {
-                    model: { model: "open/code", variant: "oc-primary" },
-                    fallback_models: [{ model: "open/fallback", variant: "oc-fallback" }],
-                },
-                pi: {
-                    model: { model: "pi/model", thinking_level: "high" },
-                    fallback_models: [{ model: "pi/fallback", thinking_level: "max" }],
-                },
+                model: { model: "shared/model", variant: "oc-primary", thinking_level: "high" },
+                fallback_models: [
+                    { model: "shared/fallback", variant: "oc-fallback", thinking_level: "max" },
+                ],
             },
         };
 
         expect(resolveHistorianModel(config, "opencode")).toEqual({
-            primary: { model: "open/code", qualifier: "oc-primary" },
-            fallbacks: [{ model: "open/fallback", qualifier: "oc-fallback" }],
+            primary: { model: "shared/model", qualifier: "oc-primary" },
+            fallbacks: [{ model: "shared/fallback", qualifier: "oc-fallback" }],
         });
         expect(resolveHistorianModel(config, "pi")).toEqual({
-            primary: { model: "pi/model", qualifier: "high" },
-            fallbacks: [{ model: "pi/fallback", qualifier: "max" }],
+            primary: { model: "shared/model", qualifier: "high" },
+            fallbacks: [{ model: "shared/fallback", qualifier: "max" }],
         });
         expect(resolveHistorianModel({}, "pi")).toEqual({ fallbacks: [] });
     });

package/src/shared/model-resolution.ts

@@ -23,13 +23,6 @@ function readString(value: unknown): string | undefined {
     return trimmed.length > 0 ? trimmed : undefined;
 }
 
-function resolveHarnessBlock(
-    container: ConfigRecord | undefined,
-    harness: ModelHarness,
-): ConfigRecord | undefined {
-    return asRecord(container?.[harness]);
-}
-
 /**
  * Collapses the string and object spellings of a harness model entry into the
  * same model identity. Qualifiers stay separate because they alter an attempt,
@@ -101,29 +94,31 @@ export interface ResolvedHistorianModel {
 }
 
 /**
- * Resolve historian model attempts from the selected harness block.
+ * Resolve historian model attempts from the flat historian config. The harness
+ * parameter selects which qualifier is read: OpenCode uses `variant`, Pi uses
+ * `thinking_level`. The other harness's qualifier is ignored (no cross-harness
+ * mapping).
  */
 export function resolveHistorianModel(
     config: unknown,
     harness: ModelHarness,
 ): ResolvedHistorianModel {
     const historian = asRecord(asRecord(config)?.historian);
-    const block = resolveHarnessBlock(historian, harness);
-    if (!block) return { fallbacks: [] };
+    if (!historian) return { fallbacks: [] };
 
     return {
         primary: resolvePrimaryEntry({
-            entry: block.model,
-            defaultQualifier: block[harness === "opencode" ? "variant" : "thinking_level"],
+            entry: historian.model,
+            defaultQualifier: historian[harness === "opencode" ? "variant" : "thinking_level"],
             harness,
         }),
-        fallbacks: resolveFallbackEntries(block.fallback_models, harness),
+        fallbacks: resolveFallbackEntries(historian.fallback_models, harness),
     };
 }
 
 /**
  * Keep non-model agent settings at their original level while replacing only
- * OpenCode's model-resolution fields with the executing harness's primary.
+ * OpenCode's model-resolution fields with the flat primary entry.
  */
 export function resolveOpenCodeAgentOverrides(agent: unknown): Record<string, unknown> {
     const source = asRecord(agent);
@@ -133,14 +128,14 @@ export function resolveOpenCodeAgentOverrides(agent: unknown): Record<string, un
         fallback_models: _fallbackModels,
         variant: _variant,
         thinking_level: _thinking,
-        opencode,
-        pi,
+        opencode: _opencode,
+        pi: _pi,
         tasks,
         ...rest
     } = source;
     const primary = resolvePrimaryEntry({
-        entry: asRecord(opencode)?.model,
-        defaultQualifier: asRecord(opencode)?.variant,
+        entry: source.model,
+        defaultQualifier: source.variant,
         harness: "opencode",
     });
     return {

package/src/shared/model-suggestion-retry.ts

@@ -1,5 +1,4 @@
 import type { createOpencodeClient } from "@opencode-ai/sdk";
-
 import { detectOverflow } from "../features/magic-context/overflow-detection";
 import { HiddenCompletionRefusal } from "../hooks/magic-context/compartment-runner-types";
 import { HiddenAgentStepLimit } from "../v2/hooks/hidden-child";
@@ -11,6 +10,12 @@ import {
 } from "./assistant-message-extractor";
 import { log } from "./logger";
 import type { ModelInput } from "./model-resolution";
+import {
+    ProviderOutputFailureError,
+    primaryQuotaFailure,
+    providerOutputFailureFromInvalidManifest,
+    rememberPrimaryQuota,
+} from "./provider-output-failure";
 import { sanitizeDiagnosticText } from "./redaction";
 import { parseProviderModel, toModelEntry } from "./resolve-fallbacks";
 
@@ -59,6 +64,8 @@ export interface PromptAttemptInfo {
     totalAttempts: number;
     /** Explicit model override for this attempt, when one was supplied. */
     model?: { providerID: string; modelID: string };
+    /** A run-local quota deadline prevented dispatch; not an actual model call. */
+    skipped?: boolean;
 }
 
 export interface PromptRetryOptions {
@@ -433,14 +440,25 @@ function throwWithPromptFailure(
         legacyError instanceof Error ? legacyError : new Error(extractMessage(legacyError));
     const last = failedAttempts.at(-1);
     const failureClass = last?.failureClass ?? "unknown";
+    const quota = failedAttempts.find(
+        (failure) =>
+            failure.error instanceof ProviderOutputFailureError &&
+            failure.error.quotaResetAt !== undefined,
+    )?.error as ProviderOutputFailureError | undefined;
+    if (quota && error !== quota && !error.message.includes(quota.message))
+        error.message = `${quota.message}; ${error.message}`;
     const providerError =
-        failureClass === "provider_error"
-            ? sanitizeDiagnosticText(shortErr(last?.error ?? legacyError)).slice(0, 500)
+        failureClass === "provider_error" || quota
+            ? sanitizeDiagnosticText(
+                  `${quota ? `${quota.message}; ` : ""}${shortErr(last?.error ?? legacyError)}`,
+              ).slice(0, 500)
             : null;
     promptFailureDetails.set(error, {
         failureClass,
         modelAttempted: last?.attempt.label ?? null,
-        modelsTried: failedAttempts.map((failure) => failure.attempt.label),
+        modelsTried: failedAttempts
+            .filter((failure) => !failure.attempt.skipped)
+            .map((failure) => failure.attempt.label),
         providerError,
         timeoutMs: failureClass === "provider_timeout" ? timeoutMs : null,
         childSessionId: transport ? (transport.childSessionId ?? null) : args.path.id || null,
@@ -664,6 +682,16 @@ async function attemptAndValidate<TOutput, TValidated>(
     }
 
     try {
+        // Only the structured account-pool notice bypasses caller validation.
+        // The near-zero-token heuristic remains owned by manifest callers.
+        const messages = Array.isArray(output)
+            ? output
+            : (output as { messages?: unknown } | null)?.messages;
+        const text = extractLatestAssistantText(messages);
+        if (text) {
+            const failure = providerOutputFailureFromInvalidManifest(messages, text);
+            if (failure?.quotaResetAt !== undefined) throw failure;
+        }
         if (!extractLatestAssistantText(output)) {
             const assistantFailure = extractLatestAssistantFailure(output);
             if (assistantFailure) {
@@ -718,8 +746,22 @@ export async function promptSyncWithValidatedOutputRetry<TOutput, TValidated = T
     const failedAttempts: FailedAttempt[] = [];
     let firstError: unknown = null;
     let lastError: unknown = null;
+    const cooledPrimary = primaryQuotaFailure(explicitPrimaryLabel);
 
     try {
+        if (cooledPrimary)
+            throw {
+                error: cooledPrimary,
+                failureClass: "provider_error",
+                attempt: {
+                    label: explicitPrimaryLabel,
+                    attemptIndex: 0,
+                    isFallback: false,
+                    totalAttempts,
+                    model: baseBody.model,
+                    skipped: true,
+                },
+            } satisfies FailedAttempt;
         return await attemptAndValidate(
             client,
             baseArgs,
@@ -739,6 +781,19 @@ export async function promptSyncWithValidatedOutputRetry<TOutput, TValidated = T
         const failure = caught as FailedAttempt;
         failedAttempts.push(failure);
         firstError = failure.error;
+        if (
+            failure.error instanceof ProviderOutputFailureError &&
+            failure.error.quotaResetAt !== undefined
+        )
+            failure.error.message = failure.error.message.replace(
+                /^provider quota exhausted/,
+                "primary quota exhausted",
+            );
+        const quota = !cooledPrimary && rememberPrimaryQuota(explicitPrimaryLabel, failure.error);
+        if (quota)
+            log(
+                `[${callContext}] ${quota.message}; skipping ${explicitPrimaryLabel} for this run until reset`,
+            );
         lastError = failure.error;
         if (isNonRetryable(failure.error, options.signal)) {
             throwWithPromptFailure(
@@ -760,9 +815,10 @@ export async function promptSyncWithValidatedOutputRetry<TOutput, TValidated = T
             );
         }
 
-        log(
-            `[${callContext}] primary (${explicitPrimaryLabel}) failed validation/prompt: ${shortErr(failure.error)}; trying ${fallbacks.length} fallback(s)`,
-        );
+        if (!cooledPrimary && !quota)
+            log(
+                `[${callContext}] primary (${explicitPrimaryLabel}) failed validation/prompt: ${shortErr(failure.error)}; trying ${fallbacks.length} fallback(s)`,
+            );
     }
 
     for (let i = 0; i < fallbacks.length; i += 1) {

package/src/shared/protected-tools-policy.ts

@@ -0,0 +1,25 @@
+/** Default result keep counts shared by runtime and configuration. */
+export const DEFAULT_PROTECTED_TOOLS: Readonly<Record<string, number>> = {
+    todowrite: 1,
+    // The fork's tool name; upstream's ctx_reduce alias merges onto the same key.
+    mmc_reduce: 3,
+};
+
+export function normalizeProtectedToolName(name: string | null): string {
+    const lowered = (name ?? "").toLowerCase().replace(/^mcp_/, "");
+    return lowered === "ctx_reduce" ? "mmc_reduce" : lowered;
+}
+
+/** Normalize before merging tiers so aliases cannot defeat a project override. */
+export function mergeProtectedTools(
+    ...maps: (Readonly<Record<string, number>> | undefined)[]
+): Record<string, number> {
+    return Object.fromEntries(
+        [DEFAULT_PROTECTED_TOOLS, ...maps].flatMap((map) =>
+            Object.entries(map ?? {}).map(([name, count]) => [
+                normalizeProtectedToolName(name),
+                count,
+            ]),
+        ),
+    );
+}

package/src/shared/provider-output-failure.ts

@@ -0,0 +1,176 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash } from "node:crypto";
+
+import { isRecord } from "./record-type-guard";
+
+const MAX_NEAR_ZERO_OUTPUT_TOKENS = 32;
+
+interface AssistantCompletionShape {
+    createdAt: number;
+    finish: string | null;
+    error: unknown;
+    outputTokens: number | null;
+    reasoningTokens: number | null;
+}
+
+/** A provider transport failure that arrived as an ordinary assistant completion. */
+export class ProviderOutputFailureError extends Error {
+    readonly transient = true;
+
+    constructor(
+        readonly fingerprint: string,
+        readonly outputTokens: number,
+        readonly reasoningTokens: number,
+        responseText: string,
+        readonly quotaResetAt?: number,
+    ) {
+        const preview = responseText.trim().replace(/\s+/g, " ").slice(0, 160);
+        super(
+            quotaResetAt !== undefined
+                ? `provider quota exhausted until ${new Date(quotaResetAt).toISOString()} (account-pool rate limit)`
+                : `provider outage completion (output_tokens=${outputTokens}, reasoning_tokens=${reasoningTokens}): ${JSON.stringify(preview)}`,
+        );
+        this.name = "ProviderOutputFailureError";
+    }
+}
+
+// Concurrent maintenance runs must not share provider health, and a new run
+// must re-probe its configured primary. Nested verify batches inherit the scope.
+const primaryQuotas = new AsyncLocalStorage<Map<string, ProviderOutputFailureError>>();
+
+export function withDreamerModelCooldown<T>(run: () => T): T {
+    return primaryQuotas.getStore() ? run() : primaryQuotas.run(new Map(), run);
+}
+
+export function rememberPrimaryQuota(
+    model: string,
+    error: unknown,
+): ProviderOutputFailureError | null {
+    const quotas = primaryQuotas.getStore();
+    if (
+        !quotas ||
+        model === "primary" ||
+        !(error instanceof ProviderOutputFailureError) ||
+        error.quotaResetAt === undefined ||
+        error.quotaResetAt <= Date.now()
+    )
+        return null;
+    const cached = new ProviderOutputFailureError(
+        error.fingerprint,
+        error.outputTokens,
+        error.reasoningTokens,
+        "",
+        error.quotaResetAt,
+    );
+    cached.message = error.message;
+    quotas.set(model, cached);
+    return error;
+}
+
+export function primaryQuotaFailure(model: string): ProviderOutputFailureError | null {
+    const quotas = primaryQuotas.getStore();
+    const error = quotas?.get(model);
+    if (!error) return null;
+    if (error.quotaResetAt === undefined || error.quotaResetAt <= Date.now()) {
+        quotas?.delete(model);
+        return null;
+    }
+    const failure = new ProviderOutputFailureError(
+        error.fingerprint,
+        error.outputTokens,
+        error.reasoningTokens,
+        "",
+        error.quotaResetAt,
+    );
+    failure.message = error.message;
+    return failure;
+}
+
+/** The auth adapter emits this entire notice as assistant text, not a host error.
+ * Match the envelope, never a quoted notice inside a real manifest or narration. */
+function quotaResetAt(responseText: string, now: number): number | undefined {
+    const notice =
+        /^All [1-9]\d* account\(s\) rate-limited for [\w.-]+\. Quota resets in ((?:\d+[hms] ?)+)\. Add more accounts with `opencode auth login` or wait and retry\.$/.exec(
+            responseText.trim(),
+        );
+    if (!notice) return undefined;
+    const units: Record<string, number> = { h: 3_600_000, m: 60_000, s: 1_000 };
+    const duration = [...notice[1].matchAll(/(\d+)([hms])/g)].reduce(
+        (sum, match) => sum + Number(match[1]) * units[match[2]],
+        0,
+    );
+    const resetAt = now + duration;
+    return duration > 0 && Number.isSafeInteger(resetAt) && resetAt < 8.64e15 ? resetAt : undefined;
+}
+
+function finiteTokenCount(value: unknown): number | null {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+function completionShape(value: unknown): AssistantCompletionShape | null {
+    if (!isRecord(value)) return null;
+    const info = isRecord(value.info) ? value.info : value;
+    if (info.role !== "assistant") return null;
+
+    const time = isRecord(info.time) ? info.time : null;
+    const tokens = isRecord(info.tokens) ? info.tokens : null;
+    return {
+        createdAt: typeof time?.created === "number" ? time.created : 0,
+        finish:
+            typeof info.finish === "string"
+                ? info.finish
+                : typeof info.finish_reason === "string"
+                  ? info.finish_reason
+                  : typeof info.finishReason === "string"
+                    ? info.finishReason
+                    : null,
+        error: info.error,
+        outputTokens: finiteTokenCount(tokens?.output),
+        reasoningTokens: finiteTokenCount(tokens?.reasoning),
+    };
+}
+
+function latestAssistantCompletion(messages: unknown): AssistantCompletionShape | null {
+    if (!Array.isArray(messages)) return null;
+    let latest: AssistantCompletionShape | null = null;
+    for (const message of messages) {
+        const completion = completionShape(message);
+        if (completion && (!latest || completion.createdAt >= latest.createdAt))
+            latest = completion;
+    }
+    return latest;
+}
+
+/**
+ * OpenCode can serialize a provider outage as a successful `finish=stop` assistant
+ * message. Only classify that shape after manifest validation has already failed:
+ * a real manifest remains authoritative regardless of its token counts.
+ */
+export function providerOutputFailureFromInvalidManifest(
+    messages: unknown,
+    responseText: string,
+    now = Date.now(),
+): ProviderOutputFailureError | null {
+    const completion = latestAssistantCompletion(messages);
+    if (completion?.finish?.toLowerCase() !== "stop") return null;
+    if (
+        completion.error != null ||
+        completion.outputTokens === null ||
+        completion.reasoningTokens !== 0
+    ) {
+        return null;
+    }
+
+    const normalized = responseText.trim().replace(/\s+/g, " ").toLowerCase();
+    if (!normalized) return null;
+    const resetAt = quotaResetAt(responseText, now);
+    if (resetAt === undefined && completion.outputTokens > MAX_NEAR_ZERO_OUTPUT_TOKENS) return null;
+    const fingerprint = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+    return new ProviderOutputFailureError(
+        fingerprint,
+        completion.outputTokens,
+        completion.reasoningTokens,
+        responseText,
+        resetAt,
+    );
+}

package/src/shared/status-detail-text.test.ts

@@ -92,7 +92,7 @@ describe("status detail text", () => {
         expect(formatStatusDetailMarkdown(STATUS_FIXTURE)).toBe(`## Magic Context Status
 
 - **Context:** 75.0% of usable context (96,000 / 128,000 tokens)
-- **Cache lifetime:** 1h (config for anthropic/claude-opus-5)
+- **Cache lifetime:** 1h (your config)
 - **Automatic compression:** at 65.0% of usable context
 - **History compression:** Compressing history · 12 history blocks
 - **Reclaimable:** 3 spent tool outputs (~14k tokens)

package/src/shared/status-view.test.ts

@@ -256,7 +256,7 @@ describe("status view model", () => {
      * gap fit; otherwise the caller draws one column.
      */
     test("draws two columns only when both columns' values fit", () => {
-        const sections = view().sections;
+        const sections = view({ cacheTtlSource: "default" }).sections;
         for (const section of sections) {
             const longest = Math.max(...section.rows.map((row) => row.value.length));
             expect(statusSectionWidth(section)).toBe(section.labelWidth + 1 + longest);

package/src/shared/temporal-upgrade-fixture.ts

@@ -0,0 +1,50 @@
+import fixture from "../../../../testdata/temporal-upgrade-projections.json";
+import type { Database } from "./sqlite";
+
+export type TemporalFixtureRuntime = "Pi" | "OpenCode 1" | "OpenCode 2";
+type Value = null | string | number | { base64: string };
+interface CapturedSession {
+    sessionId: string;
+    cwd?: string;
+    input: unknown[];
+    entryIds?: string[];
+    projection: unknown[];
+    projectionJson: string;
+    state: Record<string, Array<Record<string, Value>>>;
+}
+
+export const temporalUpgradeCases: Record<TemporalFixtureRuntime, CapturedSession> = fixture.cases;
+
+/** Restore old served state, never by first rendering it with the current code. */
+export function seedTemporalUpgradeFixture(
+    db: Database,
+    runtime: TemporalFixtureRuntime,
+): CapturedSession {
+    const captured = temporalUpgradeCases[runtime];
+    db.transaction(() => {
+        for (const [table, rows] of Object.entries(captured.state)) {
+            for (const row of rows) {
+                const columns = Object.keys(row);
+                const values = Object.values(row).map((value) =>
+                    value !== null && typeof value === "object"
+                        ? Buffer.from(value.base64, "base64")
+                        : value,
+                );
+                db.prepare(
+                    `INSERT INTO ${table} (${columns.join(",")}) VALUES (${columns.map(() => "?").join(",")})`,
+                ).run(...values);
+            }
+        }
+        // Advance only the cache clock: timestamp-derived marker bytes and
+        // the old input/projection are the immutable captured fixture.
+        db.prepare("UPDATE session_meta SET last_response_time=? WHERE session_id=?").run(
+            Date.now(),
+            captured.sessionId,
+        );
+        db.prepare("UPDATE lkg_slots SET captured_at=? WHERE session_id=?").run(
+            Date.now(),
+            captured.sessionId,
+        );
+    }).immediate();
+    return captured;
+}

package/src/shared/window-geometry.ts

@@ -89,6 +89,8 @@ export interface WindowDerivation {
     geometry: WindowGeometry;
     windowSource: WindowLimitSource;
     absoluteWall: number;
+    /** Accepted provider input used to raise the usable denominator above metadata. */
+    provenInputTokens?: number;
 }
 
 export interface WindowGeometryResult {
@@ -691,6 +693,7 @@ export function applyProvenInputFloor(
                 absoluteWall: trustedAbsoluteWall
                     ? geometry.derivation.absoluteWall
                     : Math.max(geometry.derivation.absoluteWall, provenInputTokens),
+                provenInputTokens,
             },
         },
     };
@@ -715,6 +718,13 @@ export function formatWindowDerivationLine(
     return `${formatCompactTokens(inputTokens)} / ${formatCompactTokens(result.usableSoft)} usable · window ${formatCompactTokens(result.derivation.window)} · ${formatCompactTokens(result.derivation.reserve)} ${reserveLabel}`;
 }
 
+/** Distinguish metadata from a denominator raised by an accepted input measurement. */
+export function formatWindowSource(result: WindowGeometryResult | undefined): string {
+    return result?.derivation.provenInputTokens
+        ? `provider-measured floor (${result.derivation.windowSource})`
+        : (result?.derivation.windowSource ?? "unknown");
+}
+
 export function formatCompactTokens(value: number): string {
     if (Math.abs(value) >= 1_000_000) {
         return `${(value / 1_000_000).toFixed(1).replace(/\.0$/, "")}m`;

package/src/shared/write-transaction-timing.ts

@@ -15,12 +15,36 @@ export function logSlowWriteTransaction(
     startedAt: number,
     thresholdMs = SLOW_WRITE_TRANSACTION_THRESHOLD_MS,
     completedAtMs = performance.now(),
+    steps?: Readonly<Record<string, number>>,
 ): void {
     try {
         const durationMs = completedAtMs - startedAt;
         if (durationMs < thresholdMs) return;
-        log(`[magic-context] slow write transaction: site=${site} held=${durationMs.toFixed(1)}ms`);
+        const detail = steps
+            ? Object.entries(steps)
+                  .map(([name, ms]) => `${name}=${ms.toFixed(1)}ms`)
+                  .join(" ")
+            : "";
+        log(
+            `[magic-context] slow write transaction: site=${site} held=${durationMs.toFixed(1)}ms${detail ? ` ${detail}` : ""}`,
+        );
     } catch {
         // Timing diagnostics must never make a committed write appear to fail.
     }
 }
+
+/** Step durations include precomputation when named `pre_*`; held time never does. */
+export class WriteTransactionSteps {
+    readonly durations: Record<string, number> = {};
+    private last = performance.now();
+
+    mark(name: string): void {
+        const now = performance.now();
+        this.durations[name] = now - this.last;
+        this.last = now;
+    }
+
+    reset(): void {
+        this.last = performance.now();
+    }
+}