@mnemom/mnemom 0.17.4-next.3 → 0.17.4-next.5

package/dist/lib/first-run/screen.js

@@ -0,0 +1,210 @@
+/**
+ * The first-run screen: one plain terminal screen (at most 16 lines of at most 78
+ * columns, ASCII) built from the backtest numbers. Pure — no I/O — so every layout is
+ * unit-tested. Every number on it is recorded in the audit with its raw value and
+ * method.
+ *
+ * Exactly three variations (operator v1, 2026-10-01); every number has one source and no
+ * two lines make the same claim:
+ *   A  saving   the shown saving is >= $5 and >= 5%: the usage at API prices, with Mnemom,
+ *               the saving, the biggest session; plus ONE subscription sentence for a Team /
+ *               Enterprise subscriber whose usage cut rounds to >= 5%.
+ *   B  small    >= $5 of usage at API prices but a smaller saving: the usage, the honest
+ *               "wouldn't have changed that much" line, and the forward line.
+ *   C  none     too little history: the forward line only.
+ * All three end with the price line and the live lines.
+ *
+ * Operator rulings (2026-09-30 / 2026-10-01), binding:
+ *   - Cost only. Nothing about conduct ("habits", "caught", "checked").
+ *   - Round DOWN, never overstate; frame the number around the biggest session.
+ *   - Every kept session is priced at API list prices whatever it was billed on, and the
+ *     screen says "at API prices". A subscriber gets a usage %, never a seat bill, an
+ *     overage dollar figure or a limit-hit count.
+ *   - No live counter is promised: `mnemom agent` has no status bar today.
+ */
+import { ESTIMATOR_METHOD } from "./backtest.js";
+export const WIDTH = 78;
+export const MAX_LINES = 16;
+/** Less history than this (API prices, in the window) is too little to backtest. */
+export const MIN_HISTORY_USD = 5;
+/** Variation A iff the shown saving is at least this many dollars and this many percent. */
+export const STRONG_MIN_USD = 5;
+export const STRONG_MIN_PCT = 5;
+export const DAYS = 30;
+/**
+ * The forward line: the best finished chain45 run with its error margin (operator
+ * 2026-10-01, until something better): S43 C2 total bill -19.5% [-23.9, -14.9], Opus 5.5,
+ * n=23, 95% CI rounded to 15-25. The d240p1 ~45% figure is NOT used (its re-bill
+ * undercounts output).
+ */
+export const FORWARD_LINE = "Long sessions are where Mnemom saves the most: about 15 to 25% in our tests.";
+const FORWARD_SOURCE = "operator 2026-10-01: S43 C2 total bill -19.5% [-23.9, -14.9] (Opus 5.5, n=23), 95% CI " +
+    "rounded to 15 to 25; measured vs stock at the 1M default";
+/** Prices, promotions and plan allocations move; the saving is in usage (operator 2026-10-01). */
+export const PRICE_LINE = "Prices and plan limits change. Mnemom cuts what you use, so you stay ahead.";
+/** What `mnemom agent` does today: routes through the gateway, records, keeps context lean. */
+export const LIVE_LINES = [
+    "From now on it's live: your sessions run through Mnemom, which keeps long",
+    "conversations lean and puts each tool call your agent makes on the record.",
+];
+// ── rounding (never inflate) ─────────────────────────────────────────────────
+/** 2 significant figures, rounded DOWN; 0 below $1. */
+export function sig2(x) {
+    if (!(x >= 1))
+        return 0;
+    const step = 10 ** Math.max(Math.floor(Math.log10(x)) - 1, 0);
+    return Math.floor(x / step + 1e-9) * step;
+}
+/** 3 significant figures, rounded DOWN; 0 below $1. */
+export function sig3(x) {
+    if (!(x >= 1))
+        return 0;
+    const step = 10 ** Math.max(Math.floor(Math.log10(x)) - 2, 0);
+    return Math.floor(x / step + 1e-9) * step;
+}
+/**
+ * (total shown, saved shown, with-Mnemom shown) with total - saved === with EXACTLY on
+ * screen. The implied saving is the shown saving, which never exceeds the raw saving.
+ */
+export function pair(total, saved) {
+    const sv = sig2(Math.max(saved, 0));
+    const tot = sig3(total);
+    return [tot, Math.min(sv, tot), Math.max(tot - sv, 0)];
+}
+/** part / whole as a percentage rounded DOWN to a multiple of 5. */
+export function pct5(part, whole) {
+    if (whole <= 0 || part <= 0)
+        return 0;
+    return Math.floor((100 * part) / whole / 5 + 1e-9) * 5;
+}
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+export function day(t) {
+    const d = new Date(t * 1000);
+    return `${d.getUTCDate()} ${MONTHS[d.getUTCMonth()]}`;
+}
+export function usd(n) {
+    return `$${Math.floor(n).toLocaleString("en-US")}`;
+}
+// ── output hygiene ───────────────────────────────────────────────────────────
+const SECRETS = /(sk-[A-Za-z0-9_-]{6,}|ghp_[A-Za-z0-9]{6,}|mnm_[A-Za-z0-9_-]{6,}|op:\/\/\S+|Bearer\s+\S+|\b[0-9a-f]{40,}\b|\b[A-Za-z0-9+/]{48,}={0,2})/g;
+const PATHISH = /(\/Users\/\S+|\/home\/\S+|\/private\/\S+|~\/\S+)/g;
+export function clean(s) {
+    return s.replace(SECRETS, "[REDACTED]").replace(PATHISH, "[path]");
+}
+/** A short, safe project label from Claude Code's encoded project dir, or null. */
+export function labelFor(pretty) {
+    let base = pretty.replace(/-{1,2}\.?worktrees-/g, "/").replace(/^-+|-+$/g, "");
+    base = base.replace(/-?\d{8}T\d{6}Z/g, "").replace(/-?[0-9a-f]{12,}/g, "");
+    if (base.includes("/"))
+        base = base.slice(base.lastIndexOf("/") + 1);
+    if (!base || clean(base) !== base || !/^[A-Za-z0-9._ -]+$/.test(base))
+        return null;
+    return base.length <= 36 ? base : `${base.slice(0, 35)}~`;
+}
+export function wrap(text, width = WIDTH) {
+    const out = [];
+    let cur = "";
+    for (const w of text.split(/\s+/).filter(Boolean)) {
+        if (cur && cur.length + 1 + w.length > width) {
+            out.push(cur);
+            cur = w;
+        }
+        else {
+            cur = cur ? `${cur} ${w}` : w;
+        }
+    }
+    if (cur)
+        out.push(cur);
+    return out;
+}
+const SPENT_METHOD = "transcript usage x Claude Code 2.1.285's price table, deduped by message id, every kept " +
+    "session's requests in the last 30 days, priced at API list prices whatever they were billed " +
+    "on; 3 sig figs DOWN; a lower bound (side calls not in transcripts are missing)";
+const SAVED_METHOD = `backtest.estimate(): ${ESTIMATOR_METHOD}; 2 sig figs DOWN`;
+function subLines(sub, A) {
+    if (!sub)
+        return [];
+    const p = pct5(sub.saved, sub.actual);
+    const raw = sub.actual > 0 ? (100 * sub.saved) / sub.actual : 0;
+    if (p < 5) {
+        A("sub_line_omitted", { shown: true, raw, method: "usage cut rounds DOWN below 5%" });
+        return [];
+    }
+    A("sub_usage_pct", {
+        shown: p,
+        raw,
+        method: "saving / API-price cost over the subscription sessions in the window (all sessions if " +
+            "none is tagged); cost-weighted, rounded DOWN to 5s",
+    });
+    return wrap(`On your subscription that is about ${p}% less usage: fewer limit hits, and less ` +
+        "overage if you use extra usage.");
+}
+/** -> the screen lines, the variation and the audit of every number on them. */
+export function buildScreen(inp) {
+    const audit = {};
+    const A = (k, e) => {
+        audit[k] = e;
+    };
+    const ses = inp.sessions;
+    const actual = ses.reduce((t, r) => t + r.actual, 0);
+    const saved = ses.reduce((t, r) => t + r.saved, 0);
+    const [a, s, e] = pair(actual, saved);
+    const p = pct5(saved, actual);
+    const enough = actual >= MIN_HISTORY_USD;
+    const variation = enough && s >= STRONG_MIN_USD && p >= STRONG_MIN_PCT ? "A" : enough ? "B" : "C";
+    A("variation", { shown: variation, raw: { actual, saved }, method: "see screen.ts header" });
+    const L = ["Welcome to Mnemom.", ""];
+    L.push(...(variation === "C"
+        ? wrap("We didn't find enough Claude Code history on this machine to look at.")
+        : wrap(`We looked at your last ${DAYS} days of Claude Code. It all stayed on this machine.`)));
+    L.push("");
+    if (variation === "A") {
+        A("spent_usd", { shown: a, raw: actual, method: SPENT_METHOD });
+        A("saved_usd", { shown: s, raw: saved, method: SAVED_METHOD });
+        A("with_mnemom_usd", { shown: e, raw: actual - saved, method: "spent shown - saved shown" });
+        A("saved_pct", { shown: p, raw: (100 * saved) / actual, method: "rounded DOWN to 5s" });
+        L.push(...wrap(`At API prices that usage cost about ${usd(a)}. With Mnemom: about ${usd(e)}.`));
+        L.push(...wrap(`That's about ${usd(s)} less (${p}%), and you don't change how you work.`));
+        // A has a saving, so the session with the largest saving exists and saved something.
+        const big = ses.reduce((m, r) => (r.saved > m.saved ? r : m));
+        const [ba, , be] = pair(big.actual, big.saved);
+        A("biggest_session_usd", {
+            shown: ba,
+            raw: big.actual,
+            method: "the session with the largest saving; its API-price cost, 3 sig figs DOWN",
+        });
+        A("biggest_session_with_mnemom_usd", {
+            shown: be,
+            raw: big.actual - big.saved,
+            method: "its cost shown - its saving (2 sig figs DOWN)",
+        });
+        const where = big.label ? `${big.label} on ${day(big.end)}` : `on ${day(big.end)}`;
+        L.push(...wrap(`Your biggest session, ${where}: ${usd(ba)}, with Mnemom about ${usd(be)}.`));
+        L.push(...subLines(inp.sub, A));
+    }
+    else {
+        if (variation === "B") {
+            A("spent_usd", { shown: a, raw: actual, method: SPENT_METHOD });
+            A("saved_usd_not_shown", {
+                shown: null,
+                raw: saved,
+                method: `below $${STRONG_MIN_USD} or ${STRONG_MIN_PCT}% after rounding DOWN`,
+            });
+            L.push(...wrap(`Your sessions used about ${usd(a)} at API prices. They stayed small, so Mnemom ` +
+                "wouldn't have changed that much."));
+        }
+        L.push(FORWARD_LINE);
+        A("forward_range_pct", {
+            shown: "15 to 25",
+            raw: [-23.9, -19.5, -14.9],
+            method: FORWARD_SOURCE,
+        });
+    }
+    L.push("", PRICE_LINE, "", ...LIVE_LINES);
+    A("sessions", {
+        shown: null,
+        raw: ses.length,
+        method: "kept sessions with requests in the window",
+    });
+    return { lines: L.map(clean), audit, variation };
+}

package/dist/lib/first-run/seat.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Seat economics for Team / Enterprise subscription sessions. A seat is flat-rate up to
+ * its usage limits; past them the user either STOPS until the window resets, or (extra
+ * usage on) keeps going and pays overage at API list rates. So for a seat user Mnemom's
+ * lower usage means more work per window, fewer or shorter stops and less overage —
+ * never a lower seat bill.
+ *
+ * Sources (Claude Code 2.1.285 binary):
+ *   windows  rateLimitType five_hour | seven_day (+ per-model weekly caps, folded into the
+ *            weekly window); display names "session limit" / "weekly limit".
+ *   stop     a plan-limit 429 is written as an API-error assistant record whose text is
+ *            "You've hit your <limit name> · resets <time>" (also "Usage limit reached …").
+ *   overage  "… now using usage credits instead of your plan limits" / "You're now using
+ *            extra usage" mark the switch to paid overage. Measured 2026-09-30: UI-only
+ *            today — no transcript records one — so an allowance is pinned only when a
+ *            record does carry it.
+ *
+ * Only records Claude Code itself writes (system, API-error, or `<synthetic>` assistant
+ * records) count — a user or model message that merely discusses limits never does.
+ * Read-only; no network.
+ */
+import { type Row } from "./backtest.js";
+export declare const WINDOW_S: {
+    readonly five_hour: number;
+    readonly seven_day: number;
+};
+export type WindowType = keyof typeof WINDOW_S;
+export declare const DAYS = 30;
+export interface LimitEvent {
+    t: number;
+    kind: "hit" | "extra_on" | "extra_cap";
+    wtype: WindowType | null;
+    blockedS: number;
+}
+/** Limit / extra-usage events from Claude Code's own records, sorted by time. */
+export declare function limitEvents(paths: readonly string[]): LimitEvent[];
+export interface SeatSessionInput {
+    rows: readonly Row[];
+    /** Screen rate per row (backtest.ruleRate(...).screen). */
+    rates: readonly number[];
+    paths: readonly string[];
+}
+export interface SeatAnalysis {
+    extraUsage: boolean | null;
+    requests30d: number;
+    usageListUsd30d: number;
+    withMnemomListUsd30d: number;
+    events30d: {
+        hit: number;
+        extra_on: number;
+        extra_cap: number;
+    };
+    allowance: Partial<Record<WindowType, {
+        usd: number;
+        source: string;
+    }>>;
+    overage?: {
+        paidUsd: number;
+        withMnemomUsd: number;
+        overPeriods: number;
+        stayedInside: number;
+        method: string;
+    };
+    hits?: {
+        n: number;
+        waitedS: number;
+        avoided: number;
+        notInferable: number;
+        notInferableWithSaving: number;
+        withMnemom: number;
+        method: string;
+    };
+}
+/** One account's seat sessions → the seat block's numbers and their method. */
+export declare function analyzeSeat(sessions: readonly SeatSessionInput[], extraUsage: boolean | null, now?: number, days?: number): SeatAnalysis;

package/dist/lib/first-run/seat.js

@@ -0,0 +1,250 @@
+/**
+ * Seat economics for Team / Enterprise subscription sessions. A seat is flat-rate up to
+ * its usage limits; past them the user either STOPS until the window resets, or (extra
+ * usage on) keeps going and pays overage at API list rates. So for a seat user Mnemom's
+ * lower usage means more work per window, fewer or shorter stops and less overage —
+ * never a lower seat bill.
+ *
+ * Sources (Claude Code 2.1.285 binary):
+ *   windows  rateLimitType five_hour | seven_day (+ per-model weekly caps, folded into the
+ *            weekly window); display names "session limit" / "weekly limit".
+ *   stop     a plan-limit 429 is written as an API-error assistant record whose text is
+ *            "You've hit your <limit name> · resets <time>" (also "Usage limit reached …").
+ *   overage  "… now using usage credits instead of your plan limits" / "You're now using
+ *            extra usage" mark the switch to paid overage. Measured 2026-09-30: UI-only
+ *            today — no transcript records one — so an allowance is pinned only when a
+ *            record does carry it.
+ *
+ * Only records Claude Code itself writes (system, API-error, or `<synthetic>` assistant
+ * records) count — a user or model message that merely discusses limits never does.
+ * Read-only; no network.
+ */
+import { rowCost } from "./backtest.js";
+import { forEachLine, isoSeconds, parseJson } from "./lines.js";
+export const WINDOW_S = { five_hour: 5 * 3600, seven_day: 7 * 86400 };
+const TYPE_BY_NAME = [
+    ["session limit", "five_hour"],
+    ["weekly limit", "seven_day"],
+    ["opus limit", "seven_day"],
+    ["sonnet limit", "seven_day"],
+];
+const HIT_MARKERS = ["hit your limit", "usage limit reached", "limit reached again"];
+const ON_MARKERS = [
+    "now using extra usage",
+    "extra usage is now covering",
+    "now using usage credits instead of your plan",
+    "is drawing from usage credits",
+    "now uses usage credits",
+];
+const CAP_MARKERS = ["out of extra usage"];
+export const DAYS = 30;
+function textOf(m) {
+    if (typeof m === "string")
+        return m;
+    const c = m?.content;
+    if (typeof c === "string")
+        return c;
+    if (Array.isArray(c)) {
+        return c
+            .map((x) => (x && typeof x === "object" && typeof x.text === "string" ? x.text : ""))
+            .join(" ");
+    }
+    return "";
+}
+/** Limit / extra-usage events from Claude Code's own records, sorted by time. */
+export function limitEvents(paths) {
+    const ev = [];
+    for (const fp of paths) {
+        const recs = [];
+        forEachLine(fp, (line) => {
+            const d = parseJson(line);
+            if (!d)
+                return;
+            const t = isoSeconds(d.timestamp);
+            if (t === null)
+                return;
+            const m = d.message;
+            const own = d.type === "system" ||
+                d.isApiErrorMessage === true ||
+                (d.type === "assistant" && !!m && typeof m === "object" && m.model === "<synthetic>");
+            let txt = "";
+            if (own)
+                txt = textOf(m) || (typeof d.content === "string" ? d.content : "");
+            recs.push({ t, own, txt });
+        });
+        recs.sort((a, b) => a.t - b.t);
+        recs.forEach((r, i) => {
+            if (!r.own || !r.txt)
+                return;
+            const low = r.txt.toLowerCase();
+            const isHit = HIT_MARKERS.some((k) => low.includes(k)) ||
+                (low.includes("limit") && low.includes("resets"));
+            const kind = isHit
+                ? "hit"
+                : ON_MARKERS.some((k) => low.includes(k))
+                    ? "extra_on"
+                    : CAP_MARKERS.some((k) => low.includes(k))
+                        ? "extra_cap"
+                        : null;
+            if (!kind)
+                return;
+            const wtype = TYPE_BY_NAME.find(([n]) => low.includes(n))?.[1] ?? null;
+            let blockedS = 0;
+            if (kind === "hit") {
+                // The stop lasts until the session's next record not written by Claude Code itself,
+                // capped at the window; a session that ended at the stop waited 0 (never guessed).
+                const next = recs.slice(i + 1).find((x) => !x.own);
+                blockedS = next ? Math.min(next.t - r.t, WINDOW_S[wtype ?? "five_hour"]) : 0;
+            }
+            ev.push({ t: r.t, kind, wtype, blockedS });
+        });
+    }
+    return ev.sort((a, b) => a.t - b.t);
+}
+/** Usage windows start at the first request after the previous window ended. */
+function windowIndex(ts, length) {
+    const out = [];
+    let start = null;
+    let k = -1;
+    for (const t of ts) {
+        if (start === null || t >= start + length) {
+            start = t;
+            k++;
+        }
+        out.push(k);
+    }
+    return out;
+}
+/** One account's seat sessions → the seat block's numbers and their method. */
+export function analyzeSeat(sessions, extraUsage, now = Date.now() / 1000, days = DAYS) {
+    const cut = now - days * 86400;
+    const reqs = [];
+    for (const s of sessions) {
+        s.rows.forEach((r, i) => {
+            const c = rowCost(r);
+            reqs.push([r.t, c, c * (1 - (s.rates[i] ?? 0))]);
+        });
+    }
+    reqs.sort((a, b) => a[0] - b[0]);
+    const ev = limitEvents(sessions.flatMap((s) => s.paths));
+    const ev30 = ev.filter((e) => e.t >= cut);
+    const in30 = reqs.filter((x) => x[0] >= cut);
+    const out = {
+        extraUsage,
+        requests30d: in30.length,
+        usageListUsd30d: in30.reduce((a, x) => a + x[1], 0),
+        withMnemomListUsd30d: in30.reduce((a, x) => a + x[2], 0),
+        events30d: {
+            hit: ev30.filter((e) => e.kind === "hit").length,
+            extra_on: ev30.filter((e) => e.kind === "extra_on").length,
+            extra_cap: ev30.filter((e) => e.kind === "extra_cap").length,
+        },
+        allowance: {},
+    };
+    const ts = reqs.map((x) => x[0]);
+    const win = {
+        five_hour: windowIndex(ts, WINDOW_S.five_hour),
+        seven_day: windowIndex(ts, WINDOW_S.seven_day),
+    };
+    const firstAtOrAfter = (t) => {
+        const j = ts.findIndex((x) => x >= t);
+        return j === -1 ? ts.length : j;
+    };
+    // Allowance: usage in the window before an extra-usage transition record. An untyped
+    // marker is pinned to the shorter window; the LARGEST pin wins (less overage avoided).
+    for (const e of ev) {
+        if (e.kind !== "extra_on" || !reqs.length)
+            continue;
+        const w = e.wtype ?? "five_hour";
+        const i = firstAtOrAfter(e.t);
+        if (i === 0)
+            continue;
+        const k = win[w][i - 1];
+        let before = 0;
+        for (let j = 0; j < i; j++)
+            if (win[w][j] === k)
+                before += reqs[j][1];
+        const prev = out.allowance[w]?.usd ?? 0;
+        out.allowance[w] = { usd: Math.max(prev, before), source: "extra-usage transition record" };
+    }
+    // Overage (extra usage on): a request is overage once ANY window with a known allowance
+    // is used up. Same windows in both worlds (request times do not move).
+    const allow = Object.entries(out.allowance);
+    if (extraUsage && allow.length) {
+        const walk = (col) => {
+            const used = new Map();
+            let over = 0;
+            const periods = new Set();
+            reqs.forEach((x, j) => {
+                let isOver = false;
+                for (const [w, cap] of allow) {
+                    const id = `${w}:${win[w][j]}`;
+                    if ((used.get(id) ?? 0) >= cap.usd) {
+                        isOver = true;
+                        if (x[0] >= cut)
+                            periods.add(id);
+                    }
+                    used.set(id, (used.get(id) ?? 0) + x[col]);
+                }
+                if (isOver && x[0] >= cut)
+                    over += x[col];
+            });
+            return { over, periods };
+        };
+        const a = walk(1);
+        const b = walk(2);
+        out.overage = {
+            paidUsd: a.over,
+            withMnemomUsd: b.over,
+            overPeriods: a.periods.size,
+            stayedInside: [...a.periods].filter((p) => !b.periods.has(p)).length,
+            method: "overage = list-price usage past the allowance in its window; with Mnemom the same walk on " +
+                "usage x (1 - rate); a period stays inside when it has no overage left",
+        };
+    }
+    // Stops: a hit is AVOIDED only if the saving in its window before the stop covers the
+    // FULL list cost of the work done in the 5 h after the stop ended.
+    const hits = ev30.filter((e) => e.kind === "hit");
+    if (hits.length) {
+        let avoided = 0;
+        let unknown = 0;
+        let unknownSaving = 0;
+        for (const e of hits) {
+            const w = e.wtype ?? "five_hour";
+            const i = firstAtOrAfter(e.t);
+            if (i === 0) {
+                unknown++;
+                continue;
+            }
+            const k = win[w][i - 1];
+            let saved = 0;
+            for (let j = 0; j < i; j++)
+                if (win[w][j] === k)
+                    saved += reqs[j][1] - reqs[j][2];
+            const resume = e.t + e.blockedS;
+            const cont = e.blockedS
+                ? reqs.filter((x) => resume <= x[0] && x[0] < resume + WINDOW_S.five_hour)
+                : [];
+            if (!cont.length) {
+                unknown++;
+                if (saved > 0)
+                    unknownSaving++;
+                continue;
+            }
+            if (saved >= cont.reduce((a, x) => a + x[1], 0))
+                avoided++;
+        }
+        out.hits = {
+            n: hits.length,
+            waitedS: hits.reduce((a, e) => a + e.blockedS, 0),
+            avoided,
+            notInferable: unknown,
+            notInferableWithSaving: unknownSaving,
+            withMnemom: hits.length - avoided,
+            method: "a hit is avoided only if the list-price saving in its window before the stop >= the full " +
+                "list-price cost of the work done in the 5 h after the stop ended; a hit whose overshoot " +
+                "cannot be inferred counts as NOT avoided",
+        };
+    }
+    return out;
+}

package/dist/rc-proxy.mjs

@@ -77,6 +77,8 @@
 //   MNEMOM_AGENT_RC_PROXY_LOG         append log lines to this file instead of stderr (optional)
 //   MNEMOM_AGENT_RC_PARENT_PID        exit when this pid is gone, so no orphan holds the keys
 //   MNEMOM_AGENT_RC_PORT              listen port (default 0 = ephemeral)
+//   MNEMOM_AGENT_TURN_HEADER          0/off: no x-mnemom-turn header (default on in implicit mode;
+//                                  see turn-origin.mjs)
 //
 // stdout: exactly one line, `READY <port> <ca.pem path>`, once listening. Node ≥ 18, no deps.
 import http from "node:http";
@@ -87,6 +89,7 @@ import os from "node:os";
 import path from "node:path";
 import crypto from "node:crypto";
 import { execFileSync } from "node:child_process";
+import { TURN_HEADER, TurnOrigins, turnHeaderEnabled, turnHeaderFor } from "./turn-origin.mjs";
 
 const MITM_HOST = "api.anthropic.com";
 const env = process.env;
@@ -118,6 +121,9 @@ if (THREAD_MODE !== "reject" && THREAD_MODE !== "strip")
 const LOGFILE = env.MNEMOM_AGENT_RC_PROXY_LOG || "";
 const PARENT = Number(env.MNEMOM_AGENT_RC_PARENT_PID || 0);
 const PORT = Number(env.MNEMOM_AGENT_RC_PORT || 0);
+// x-mnemom-turn (turn-origin.mjs): each main request's turn origins, read from Claude Code's own
+// transcript. Implicit goal mode only — a sealed contract does not infer a goal from the user.
+const TURNS = GOAL_MODE && turnHeaderEnabled(env) ? new TurnOrigins() : null;
 
 const log = (line) => {
   // One record per line: gateway header values and error bodies are spliced into log lines, so a
@@ -411,6 +417,7 @@ function handle(req, res, viaPlain) {
       agent: gatewayAgent,
     };
     noteCcSession(headers["x-claude-code-session-id"]);
+    delete headers["x-mnemom-turn"]; // only this proxy states turn origins
     if (!SUBSCRIPTION) {
       delete headers.authorization; // the OAuth bearer stays local
       headers["x-api-key"] = secrets.anthropic;
@@ -523,7 +530,15 @@ function handle(req, res, viaPlain) {
         rejectThread(res, tag, thread);
         return;
       }
-      forward(body);
+      if (!TURNS) {
+        forward(body);
+        return;
+      }
+      turnHeaderFor(TURNS, headers).then((t) => {
+        if (t.value) headers[TURN_HEADER] = t.value;
+        log(`${tag} turn=${t.note}`);
+        forward(body);
+      });
     });
   } else {
     forward();