@mnemom/mnemom 0.17.36 → 0.17.38-next.0

package/dist/lib/conduct-receipt.js

@@ -1,6 +1,9 @@
 /**
- * The conduct receipt (experimental `record`, Doors W1.2 / W1.3): the engineer's private view of
- * one session, printed when `mnemom agent` exits and when a durable session parks.
+ * The conduct receipt (Doors W1.2 / W1.3): the engineer's private view of one session, printed
+ * when `mnemom agent` exits and when a durable session parks. On by default since 0.17.38
+ * (MNE-9013; MNEMOM_AGENT_RECEIPT=0 opts out). It prints ONLY when the server returns tally data:
+ * an org outside the record cohort (404), a caller without the role (403), no captured lineage,
+ * or a read that never answers inside the deadline all print nothing.
  *
  *   Conduct receipt
  *     model cost  $0.42
@@ -13,14 +16,14 @@
  *
  * NEVER BLOCKS EXIT. The whole read, auth refresh included, races a hard deadline
  * (RECEIPT_DEADLINE_MS): with the API or the record builder down, exit takes at most that much
- * longer, and the receipt falls back to the link. The caller keeps its exit code; nothing here
+ * longer, and the receipt prints nothing. The caller keeps its exit code; nothing here
  * throws.
  *
  * The lineage key is the gateway's (x-mnemom-lineage-key, set on every response), captured by the
  * local base-URL proxy into a state file: the CLI never derives one itself.
  */
 import { readFileSync } from "node:fs";
-import { getRecordTotals } from "./api.js";
+import { getRecordTotals, MnemomApiError } from "./api.js";
 import { getWebsiteUrl } from "./config.js";
 /** The hard ceiling on what the receipt adds to exit (W1.3: at most 2 s). */
 export const RECEIPT_DEADLINE_MS = 1800;
@@ -101,7 +104,7 @@ export function formatMu(mmu) {
 /** The receipt lines for what was read (pure). */
 export function receiptLines(read, link, trigger = "exit") {
     const head = trigger === "park" ? "Conduct receipt (parked)" : "Conduct receipt";
-    if (!read || read.kind === "unavailable") {
+    if (!read || read.kind !== "ok") {
         return [head, `  record not available yet: ${link}`];
     }
     const lines = [head, `  model cost  ${formatUsd(read.modelCostMmu)}`];
@@ -117,8 +120,9 @@ export function receiptLines(read, link, trigger = "exit") {
  */
 export async function buildConductReceipt(state, deps, trigger = "exit") {
     const link = state.recordUrl ?? deps.fallbackUrl;
+    // No lineage captured: nothing to read, so nothing to print.
     if (!state.lineageKey)
-        return receiptLines(null, link, trigger);
+        return [];
     const now = deps.now ?? Date.now;
     const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
     const deadline = now() + (deps.deadlineMs ?? RECEIPT_DEADLINE_MS);
@@ -130,6 +134,10 @@ export async function buildConductReceipt(state, deps, trigger = "exit") {
         if (left <= 0)
             break;
         const read = await readWithin(deps.readTotals, lineageKey, left);
+        // Not in the cohort, or no role to read it: stop at once, no exit delay. An earlier good read
+        // (the cohort or role changed mid-poll) still prints; otherwise nothing does.
+        if (read.kind === "absent")
+            break;
         // A later failure never hides an earlier good read.
         if (read.kind === "ok" || !last)
             last = read;
@@ -139,6 +147,9 @@ export async function buildConductReceipt(state, deps, trigger = "exit") {
             break;
         await sleep(pollMs);
     }
+    // Only tally data prints: every read failing or timing out stays silent.
+    if (!last || last.kind !== "ok")
+        return [];
     return receiptLines(last, link, trigger);
 }
 async function readWithin(readTotals, lineageKey, ms) {
@@ -171,7 +182,18 @@ export async function conductReceiptFor(launch, trigger = "exit", deps = {}) {
     return buildConductReceipt(readRecordState(launch.statePath), {
         ...deps,
         readTotals: deps.readTotals ??
-            (async (lineageKey, signal) => parseTotals(await getRecordTotals(launch.orgId, lineageKey, signal))),
+            (async (lineageKey, signal) => {
+                try {
+                    return parseTotals(await getRecordTotals(launch.orgId, lineageKey, signal));
+                }
+                catch (err) {
+                    // effectiveStatus, not status: the enforce hook may rewrite a 404 to a synthetic 500.
+                    if (err instanceof MnemomApiError && [403, 404].includes(err.effectiveStatus)) {
+                        return { kind: "absent" };
+                    }
+                    throw err;
+                }
+            }),
         fallbackUrl: deps.fallbackUrl ?? `${getWebsiteUrl()}/agents/${encodeURIComponent(launch.agentId)}`,
     }, trigger);
 }

package/dist/lib/experimental.d.ts

@@ -12,7 +12,7 @@
  * Everything here is pure or dependency-injected; index.ts and the command
  * modules are the thin drivers.
  */
-export type ExperimentalId = "context-handoff" | "slack" | "implicit" | "measured-savings" | "record" | "fuel" | "durable" | "dispatch";
+export type ExperimentalId = "context-handoff" | "slack" | "implicit" | "measured-savings" | "fuel" | "durable" | "dispatch";
 /**
  * Features that used to be experimental and are now on by default for everyone. Their ids are
  * no longer in the registry, but `mnemom experimental enable|disable <id>` still accepts them

package/dist/lib/experimental.js

@@ -24,6 +24,7 @@ export const GRADUATED_FEATURES = {
         since: "0.17.23",
         optOut: "--no-compaction-intercept, `compaction_intercept = false` in launcher.toml, or MNEMOM_AGENT_COMPACTION_INTERCEPT=0",
     },
+    record: { since: "0.17.38", optOut: "MNEMOM_AGENT_RECEIPT=0" },
 };
 /** The one-line note for `mnemom experimental enable|disable <graduated id>`; null otherwise. */
 export function graduatedNote(id) {
@@ -85,18 +86,6 @@ export const EXPERIMENTAL_FEATURES = [
             env: [],
         },
     },
-    {
-        // No flag, launcher.toml key or env of its own: `mnemom experimental enable` is the switch.
-        id: "record",
-        summary: "Print the conduct receipt at exit: the session's measured model cost and μ, or the record link",
-        since: "0.17.32",
-        gates: {
-            flags: [],
-            configKeys: [],
-            commands: [],
-            env: [],
-        },
-    },
     {
         id: "fuel",
         summary: "The fuel step: `mnemom agent fuel <file>` seals a batch of job contracts with one confirmation and commits them to the repo",

package/dist/lib/runner/executor-client.d.ts

@@ -8,6 +8,7 @@
  * Nothing here decides an outcome: each call returns its status, body and error code, and the job
  * (job.ts) maps them to 34.12's reasons. Never throws: a network failure is status 0.
  */
+import type { RecordCommitBody } from "./record-commit.js";
 import type { ExecAppendBody } from "./exec-append.js";
 export interface HttpResult {
     readonly status: number;
@@ -34,6 +35,8 @@ export declare const JOB_READ_PATH: (sessionId: string) => string;
 /** The served bundle fetch, per claim (W-L12). */
 export declare const BUNDLE_FETCH_PATH: (sessionId: string) => string;
 export declare const JWKS_PATH = "/v1/.well-known/jwks.json";
+/** Record's commit index (ruling 34.05 (a)): the lease key may write the session's own commits. */
+export declare const RECORD_COMMITS_PATH: (orgId: string) => string;
 export interface RunnerApi {
     readyList(limit: number): Promise<HttpResult>;
     attest(sessionId: string, nonce: string): Promise<HttpResult>;
@@ -63,6 +66,8 @@ export interface RunnerApi {
     job(sessionId: string): Promise<HttpResult>;
     bundle(sessionId: string, leaseKey: string): Promise<HttpResult>;
     jwks(): Promise<HttpResult>;
+    /** One RecordCommit/v1 body, with the lease key; the api pins it to the session's lineage. */
+    recordCommit(orgId: string, body: RecordCommitBody, leaseKey: string): Promise<HttpResult>;
 }
 export declare function runnerApi(opts: {
     apiUrl: string;

package/dist/lib/runner/executor-client.js

@@ -34,6 +34,9 @@ export const JOB_READ_PATH = (sessionId) => `/v1/executor/sessions/${sessionId}/
 /** The served bundle fetch, per claim (W-L12). */
 export const BUNDLE_FETCH_PATH = (sessionId) => `/v1/executor/sessions/${sessionId}/bundle`;
 export const JWKS_PATH = "/v1/.well-known/jwks.json";
+/** Record's commit index (ruling 34.05 (a)): the lease key may write the session's own commits. */
+export const RECORD_COMMITS_PATH = (orgId) => `/v1/orgs/${encodeURIComponent(orgId)}/record/commits`;
+const ORG_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
 const SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 export function runnerApi(opts) {
     const base = opts.apiUrl.replace(/\/+$/, "");
@@ -93,5 +96,10 @@ export function runnerApi(opts) {
         job: (id) => call(JOB_READ_PATH(scoped(id)), "GET", ex),
         bundle: (id, leaseKey) => call(BUNDLE_FETCH_PATH(scoped(id)), "GET", leaseKey),
         jwks: () => call(JWKS_PATH, "GET", null),
+        recordCommit: (orgId, body, leaseKey) => {
+            if (!ORG_ID_RE.test(orgId))
+                throw new RangeError("org id is not a Mnemom org id");
+            return call(RECORD_COMMITS_PATH(orgId), "POST", leaseKey, body);
+        },
     };
 }

package/dist/lib/runner/job.d.ts

@@ -15,6 +15,7 @@ import { type HttpResult, type RunnerApi } from "./executor-client.js";
 import { type OutcomeFields, type RefusedReason } from "./outcome.js";
 import { type PhaseInvocation } from "./phases.js";
 import { type ModelProxy, type ProxyState } from "./proxy.js";
+import type { RecordCommitBody } from "./record-commit.js";
 import { type RunnerFailMode } from "./settings.js";
 /** A claimed job's working copy. */
 export interface Workspace {
@@ -45,6 +46,13 @@ export interface JobDeps {
     openPr(repo: string, ws: Workspace, title: string, body: string): Promise<string>;
     /** Commits on the job branch that the base does not have; 0 means there is nothing to open. */
     commitsAhead(ws: Workspace): Promise<number>;
+    /** The working copy's HEAD sha before a phase runs; null only for a clone with no commit. Throws otherwise. */
+    headSha(ws: Workspace): Promise<string | null>;
+    /**
+     * RecordCommit/v1 bodies for the commits made since `since` (null: since the base), oldest
+     * first, under `lineageKey` and the job's repo. A commit that cannot be read is left out.
+     */
+    commitBodies(ws: Workspace, since: string | null, lineageKey: string, repo: string): Promise<RecordCommitBody[]>;
     enableAutoMerge(prUrl: string): Promise<void>;
     cleanup(ws: Workspace): Promise<void>;
 }
@@ -69,6 +77,35 @@ export declare function authRefusal(r: HttpResult): RefusedReason | null;
  * outcome. Throws only on a runner bug.
  */
 export declare function runJob(sessionId: string, opts: JobOptions, deps: JobDeps): Promise<JobResult>;
+/** What the job reported to Record's commit index; logged once, never part of the outcome. */
+export interface CommitReport {
+    reported: number;
+    /** Refused by the api (4xx other than 404) or unreachable: left out of the index. */
+    dropped: number;
+    /** Made in a phase whose model calls left no lineage key, so there was nothing to file under. */
+    unlinked: number;
+    /** Phases whose starting HEAD could not be read: their commits are never guessed at. */
+    skipped: number;
+    /** The index answered 404 (Record dark for the org): nothing more is sent for this job. */
+    dark: boolean;
+}
+/** Waits before each retry of a 429, 5xx or unreachable report; then the commit is dropped. */
+export declare const COMMIT_RETRY_MS: readonly [1000, 3000];
+/**
+ * Report the commits one phase made (ruling 34.05 (a)): each under the lineage key the gateway
+ * answered for that phase's conversation, with the lease key, from this process. Never throws and
+ * never changes the outcome; the lease key is sent only as the request credential, never logged.
+ */
+export declare function reportPhaseCommits(deps: JobDeps, report: CommitReport, p: {
+    ws: Workspace;
+    /** The HEAD before the phase; null: a clone with no commit; undefined: it could not be read. */
+    before: string | null | undefined;
+    conversationId: string;
+    proxy: Pick<ModelProxy, "lineageFor">;
+    orgId: string;
+    repo: string;
+    leaseKey: string;
+}): Promise<void>;
 /**
  * Report a failed job after claim (34.12 (6), (10)); a refusal releases the lease instead. The
  * fail reason vocabulary is the Durable lead's to rule (A3 accepts only transcript_lost today); a

package/dist/lib/runner/job.js

@@ -20,7 +20,7 @@ import { errorCode, errorDetails } from "./executor-client.js";
 import { doneOutcome, failedOutcome, phaseReason, refusedOutcome, } from "./outcome.js";
 import { planPhase } from "./phases.js";
 import { canonNodeKey, prBody } from "./pr-body.js";
-import { requestSummary } from "./proxy.js";
+import { phaseConversationId, requestSummary } from "./proxy.js";
 import { resolveMergeStrategy } from "./settings.js";
 const TOLERATED = RUNNER_OPEN_MODE_TOLERATED;
 const OPEN_MODE_RETRIES = 3;
@@ -189,6 +189,13 @@ export async function runJob(sessionId, opts, deps) {
     let leaseLost = false;
     let ws = null;
     let proxy = null;
+    const commits = {
+        reported: 0,
+        dropped: 0,
+        unlinked: 0,
+        skipped: 0,
+        dark: false,
+    };
     let heartbeat = null;
     const phaseAbort = new AbortController();
     const onStop = () => phaseAbort.abort();
@@ -303,10 +310,17 @@ export async function runJob(sessionId, opts, deps) {
             contractValue: header.value,
             leaseKey: claim.leaseKey,
             agentId: job.agent_id,
+            conversationId: phaseConversationId(sessionId, claim.epoch, phases[0].order),
         };
         proxy = await deps.startProxy(state);
         let opensPr = false;
         for (const phase of phases) {
+            state.conversationId = phaseConversationId(sessionId, claim.epoch, phase.order);
+            // undefined: the HEAD could not be read, so this phase's commits cannot be told apart.
+            const before = await deps.headSha(ws).catch((e) => {
+                deps.log(`reading HEAD before phase ${phase.order} failed: ${e.message}`);
+                return undefined;
+            });
             const planned = planPhase(phase);
             if (!planned.ok) {
                 deps.log(`phase ${phase.order} ${phase.name}: ${planned.detail}`);
@@ -354,6 +368,15 @@ export async function runJob(sessionId, opts, deps) {
                 }
                 break;
             }
+            await reportPhaseCommits(deps, commits, {
+                ws,
+                before,
+                conversationId: state.conversationId,
+                proxy,
+                orgId: bundle.org_id,
+                repo: job.repo,
+                leaseKey: claim.leaseKey,
+            });
         }
         if (opensPr) {
             try {
@@ -390,12 +413,62 @@ export async function runJob(sessionId, opts, deps) {
             await proxy.close();
             // One line per job that reached its phases: what every model request carried (W3.11).
             deps.log(`model requests: ${JSON.stringify(requestSummary(proxy.forwarded))}`);
+            deps.log(`commits reported: ${JSON.stringify(commits)}`);
         }
         // A workspace left behind never changes the outcome; it is logged for the operator.
         if (ws)
             await deps.cleanup(ws).catch((e) => deps.log(`cleanup failed: ${e.message}`));
     }
 }
+/** Waits before each retry of a 429, 5xx or unreachable report; then the commit is dropped. */
+export const COMMIT_RETRY_MS = [1_000, 3_000];
+/**
+ * Report the commits one phase made (ruling 34.05 (a)): each under the lineage key the gateway
+ * answered for that phase's conversation, with the lease key, from this process. Never throws and
+ * never changes the outcome; the lease key is sent only as the request credential, never logged.
+ */
+export async function reportPhaseCommits(deps, report, p) {
+    if (report.dark)
+        return;
+    if (p.before === undefined) {
+        report.skipped += 1;
+        deps.log(`${p.conversationId}: commits not reported, the phase's starting HEAD is unknown`);
+        return;
+    }
+    try {
+        const lineageKey = p.proxy.lineageFor(p.conversationId);
+        if (lineageKey === null) {
+            const n = (await deps.commitBodies(p.ws, p.before, "-", p.repo)).length;
+            report.unlinked += n;
+            if (n > 0)
+                deps.log(`${n} commit(s) in ${p.conversationId} have no lineage key: not reported`);
+            return;
+        }
+        for (const body of await deps.commitBodies(p.ws, p.before, lineageKey, p.repo)) {
+            let res = await deps.api.recordCommit(p.orgId, body, p.leaseKey);
+            for (const wait of COMMIT_RETRY_MS) {
+                if (!(res.status === 0 || res.status === 429 || res.status >= 500))
+                    break;
+                await deps.sleep(wait);
+                res = await deps.api.recordCommit(p.orgId, body, p.leaseKey);
+            }
+            if (res.status >= 200 && res.status < 300)
+                report.reported += 1;
+            else if (res.status === 404) {
+                report.dark = true;
+                deps.log("the commit index answered 404 (Record is off for this org): commits not reported");
+                return;
+            }
+            else {
+                report.dropped += 1;
+                deps.log(`commit ${body.sha.slice(0, 12)} not reported: ${res.code ?? res.networkError ?? res.status}`);
+            }
+        }
+    }
+    catch (e) {
+        deps.log(`commit report failed: ${e.message}`);
+    }
+}
 async function fetchBundle(deps, sessionId, claim) {
     const [jwksRes, res] = await Promise.all([
         deps.api.jwks(),

package/dist/lib/runner/phases.d.ts

@@ -15,8 +15,13 @@ export declare const CAPABILITY_TOOLS: Readonly<Record<string, {
     tools: string[];
     allowed: string[];
 }>>;
-/** Env names a phase may inherit: a working PATH and locale. Nothing else. */
-export declare const PHASE_ENV_PASSTHROUGH: readonly ["PATH", "LANG", "TZ"];
+/**
+ * Env names a phase may inherit: a working PATH, the shell and locale. Nothing else. Claude Code's
+ * Bash tool needs SHELL to name a POSIX shell; without it, on an image with no bash on PATH (Alpine),
+ * every Bash call fails and a phase can write files but never commit them (door2-path image run
+ * 41940973594 ended pr_no_changes).
+ */
+export declare const PHASE_ENV_PASSTHROUGH: readonly ["PATH", "SHELL", "LANG", "TZ"];
 /** Not a secret: lets claude start; the proxy drops it before the gateway (ruling: option (i)). */
 export declare const PHASE_MODEL_KEY_PLACEHOLDER = "mnemom-runner-placeholder";
 export type ToolGrant = {

package/dist/lib/runner/phases.js

@@ -21,8 +21,13 @@ export const CAPABILITY_TOOLS = Object.freeze({
     // The runner opens the PR itself once every phase has passed; the model gets no tool for it.
     "pr.open": { tools: [], allowed: [] },
 });
-/** Env names a phase may inherit: a working PATH and locale. Nothing else. */
-export const PHASE_ENV_PASSTHROUGH = ["PATH", "LANG", "TZ"];
+/**
+ * Env names a phase may inherit: a working PATH, the shell and locale. Nothing else. Claude Code's
+ * Bash tool needs SHELL to name a POSIX shell; without it, on an image with no bash on PATH (Alpine),
+ * every Bash call fails and a phase can write files but never commit them (door2-path image run
+ * 41940973594 ended pr_no_changes).
+ */
+export const PHASE_ENV_PASSTHROUGH = ["PATH", "SHELL", "LANG", "TZ"];
 /** Not a secret: lets claude start; the proxy drops it before the gateway (ruling: option (i)). */
 export const PHASE_MODEL_KEY_PLACEHOLDER = "mnemom-runner-placeholder";
 export function toolsFor(capabilityIds) {

package/dist/lib/runner/proxy.d.ts

@@ -7,24 +7,39 @@
  * Anthropic key in x-api-key (ruling 34.30.1; the phase only ever holds a placeholder), the job read's agent id in
  * x-mnemom-agent-id (the gateway checks it against the lease's session), and the job's
  * sealed contract goes in `x-mnemom-contract` (exactly one, the sealed version). The phase never
- * sees the lease key. A 409 `contract_mismatch` from the gateway (34.11) is reported to the job,
+ * sees the lease key. Each phase gets its own `x-mnemom-conversation-id` (from the session, lease
+ * epoch and phase order), so the gateway keys one lineage per phase instead of a body-hash one per
+ * request, and the `x-mnemom-lineage-key` it answers is kept for the phase's commit report. A 409 `contract_mismatch` from the gateway (34.11) is reported to the job,
  * which refetches and continues only on a higher sealed version, else fails closed.
  */
 import { request as httpRequest, type IncomingMessage, type ServerResponse } from "node:http";
 export declare const LEASE_KEY_HEADER = "x-mnemom-api-key";
 export declare const AGENT_ID_HEADER = "x-mnemom-agent-id";
+export declare const CONVERSATION_ID_HEADER = "x-mnemom-conversation-id";
+export declare const LINEAGE_KEY_HEADER = "x-mnemom-lineage-key";
+/**
+ * One phase's conversation id: the session, the lease epoch and the phase order, so a retried
+ * claim or another phase never shares a lineage. Within the gateway's 1-256 printable, no-`#` id.
+ */
+export declare function phaseConversationId(sessionId: string, epoch: number, order: number): string;
 export interface ProxyState {
     /** The sealed header value to send; swapped in place after an accepted amend. */
     contractValue: string;
     leaseKey: string;
     /** The session's agent, from the job read; always sent, a phase's own value never is. */
     agentId: string;
+    /** The running phase's conversation id; the job sets it before each phase. */
+    conversationId: string;
 }
 export interface ForwardedRequest {
     method: string;
     path: string;
     contract: string;
     status: number;
+    /** The conversation id the request carried. */
+    conversation: string;
+    /** The gateway's `x-mnemom-lineage-key` answer, when it sent a well-formed one. */
+    lineage: string | null;
 }
 export interface ModelProxy {
     url: string;
@@ -34,17 +49,26 @@ export interface ModelProxy {
     contractMismatch: {
         expected_version: number | null;
     } | null;
+    /** The lineage key the gateway last answered for a conversation id, or null when none came. */
+    lineageFor(conversationId: string): string | null;
     close(): Promise<void>;
 }
 /** Outbound headers for one request: the phase's own, minus anything the proxy decides. */
 export declare function outboundHeaders(incoming: IncomingMessage["headers"], state: ProxyState, modelKey: string): Record<string, string | string[] | undefined>;
-/** What the job's model requests carried: each contract by its sha256, in first-seen order. */
+/**
+ * What the job's model requests carried: each contract by its sha256, in first-seen order, and the
+ * lineage key the gateway answered for each conversation (one per phase), in first-seen order.
+ */
 export interface RequestSummary {
     count: number;
     contracts: {
         contract_sha256: string;
         requests: number;
     }[];
+    lineages: {
+        conversation_id: string;
+        lineage_key: string | null;
+    }[];
 }
 /**
  * One job's forwarded requests, summarised for the operator's log and for the door2-path header

package/dist/lib/runner/proxy.js

@@ -7,7 +7,9 @@
  * Anthropic key in x-api-key (ruling 34.30.1; the phase only ever holds a placeholder), the job read's agent id in
  * x-mnemom-agent-id (the gateway checks it against the lease's session), and the job's
  * sealed contract goes in `x-mnemom-contract` (exactly one, the sealed version). The phase never
- * sees the lease key. A 409 `contract_mismatch` from the gateway (34.11) is reported to the job,
+ * sees the lease key. Each phase gets its own `x-mnemom-conversation-id` (from the session, lease
+ * epoch and phase order), so the gateway keys one lineage per phase instead of a body-hash one per
+ * request, and the `x-mnemom-lineage-key` it answers is kept for the phase's commit report. A 409 `contract_mismatch` from the gateway (34.11) is reported to the job,
  * which refetches and continues only on a higher sealed version, else fails closed.
  */
 import { createServer, request as httpRequest, } from "node:http";
@@ -16,6 +18,17 @@ import { createHash } from "node:crypto";
 import { applySealedContract, CONTRACT_HEADER } from "./contract-header.js";
 export const LEASE_KEY_HEADER = "x-mnemom-api-key";
 export const AGENT_ID_HEADER = "x-mnemom-agent-id";
+export const CONVERSATION_ID_HEADER = "x-mnemom-conversation-id";
+export const LINEAGE_KEY_HEADER = "x-mnemom-lineage-key";
+/** The gateway's lineage key as echoed: short, printable, no spaces. Anything else is not kept. */
+const LINEAGE_KEY_RE = /^[\x21-\x7e]{1,256}$/;
+/**
+ * One phase's conversation id: the session, the lease epoch and the phase order, so a retried
+ * claim or another phase never shares a lineage. Within the gateway's 1-256 printable, no-`#` id.
+ */
+export function phaseConversationId(sessionId, epoch, order) {
+    return `durable-${sessionId}-e${epoch}-p${order}`;
+}
 /** Hop-by-hop headers (RFC 9110 7.6.1) and the ones the proxy owns. */
 const DROP = new Set([
     "connection",
@@ -43,8 +56,16 @@ export function outboundHeaders(incoming, state, modelKey) {
     kept[LEASE_KEY_HEADER] = state.leaseKey;
     kept["x-api-key"] = modelKey;
     kept[AGENT_ID_HEADER] = state.agentId;
+    kept[CONVERSATION_ID_HEADER] = state.conversationId;
     return applySealedContract(kept, state.contractValue);
 }
+/** The last well-formed lineage key answered for each conversation, in first-seen order. */
+function lineagesOf(forwarded) {
+    const m = new Map();
+    for (const f of forwarded)
+        m.set(f.conversation, f.lineage ?? m.get(f.conversation) ?? null);
+    return m;
+}
 /**
  * One job's forwarded requests, summarised for the operator's log and for the door2-path header
  * check (W3.11): the sha256 of each header value's decoded bytes is the contract it sealed to.
@@ -58,6 +79,10 @@ export function requestSummary(forwarded) {
     return {
         count: forwarded.length,
         contracts: [...by].map(([contract_sha256, requests]) => ({ contract_sha256, requests })),
+        lineages: [...lineagesOf(forwarded)].map(([conversation_id, lineage_key]) => ({
+            conversation_id,
+            lineage_key,
+        })),
     };
 }
 /** The largest 409 body the proxy reads for a contract mismatch. */
@@ -102,11 +127,13 @@ export async function startModelProxy(gatewayUrl, state, modelKey) {
         url: "",
         forwarded,
         contractMismatch: null,
+        lineageFor: (id) => lineagesOf(forwarded).get(id) ?? null,
         close: async () => { },
     };
     const server = createServer((req, res) => {
         const headers = outboundHeaders(req.headers, state, modelKey);
         const sent = headers[CONTRACT_HEADER];
+        const conversation = state.conversationId;
         const out = send({
             protocol: upstream.protocol,
             hostname: upstream.hostname,
@@ -116,11 +143,14 @@ export async function startModelProxy(gatewayUrl, state, modelKey) {
             headers,
         }, (up) => {
             const status = up.statusCode ?? 502;
+            const echoed = up.headers[LINEAGE_KEY_HEADER];
             forwarded.push({
                 method: req.method ?? "GET",
                 path: req.url ?? "/",
                 contract: sent,
                 status,
+                conversation,
+                lineage: typeof echoed === "string" && LINEAGE_KEY_RE.test(echoed) ? echoed : null,
             });
             if (status === 409) {
                 // Buffered to read the mismatch, up to a cap; a larger body is relayed unread.
@@ -162,6 +192,8 @@ export async function startModelProxy(gatewayUrl, state, modelKey) {
                 path: req.url ?? "/",
                 contract: sent,
                 status: 502,
+                conversation,
+                lineage: null,
             });
             upstreamFailed(res, e);
         });

package/dist/lib/runner/record-commit.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The RecordCommit/v1 body Record's commit index takes (`POST /v1/orgs/{org}/record/commits`).
+ * It lives here so the runner can type its commit report without loading the CLI's commit reporter
+ * (which spawns git and reads auth); lib/commit-report.ts re-exports both names.
+ */
+/** The commit index body's schema tag (shared with the fleet worker's reporter). */
+export declare const COMMIT_SCHEMA = "RecordCommit/v1";
+/** RecordCommit/v1: strings only, every field required; the route rejects an unknown field. */
+export interface RecordCommitBody {
+    schema: typeof COMMIT_SCHEMA;
+    lineage_key: string;
+    repo: string;
+    branch: string;
+    sha: string;
+    patch_id: string;
+}

package/dist/lib/runner/record-commit.js

@@ -0,0 +1,7 @@
+/**
+ * The RecordCommit/v1 body Record's commit index takes (`POST /v1/orgs/{org}/record/commits`).
+ * It lives here so the runner can type its commit report without loading the CLI's commit reporter
+ * (which spawns git and reads auth); lib/commit-report.ts re-exports both names.
+ */
+/** The commit index body's schema tag (shared with the fleet worker's reporter). */
+export const COMMIT_SCHEMA = "RecordCommit/v1";

package/dist/lib/scan/spend/anthropic-usage.d.ts

@@ -1,12 +1,24 @@
 export declare const ANTHROPIC_ADMIN_ORIGIN = "https://api.anthropic.com";
 export declare const ADMIN_KEY_ENV = "ANTHROPIC_ADMIN_KEY";
+/** The only paths a usage credential is ever sent to (design T18: fenced to report endpoints). */
+export declare const REPORT_PATHS: readonly string[];
+/** The fence, as one exported check so it is directly testable. Throws AnthropicUsageError for any other path. */
+export declare function assertReportPath(path: string): void;
+/** The exact auth header to send; same shape as mnemom-api src/org-scan/usage/credential-source.ts. */
+export type AnthropicAuthHeader = {
+    header: "x-api-key";
+    value: string;
+} | {
+    header: "authorization";
+    value: string;
+};
 export declare const DEFAULT_MAX_PAGES = 20;
 /** One shared deadline for a request including its retries (not N x timeout). */
 export declare const DEFAULT_TIMEOUT_MS = 15000;
 export declare const DEFAULT_MAX_RETRIES = 2;
 /** Shape check only; the key is never echoed, even on a mismatch. */
 export declare const isAdminKeyShape: (k: unknown) => k is string;
-export type UsageFailure = "key_invalid" | "key_refused" | "rate_limited" | "timeout" | "network" | "upstream" | "malformed" | "too_large";
+export type UsageFailure = "key_invalid" | "key_refused" | "token_refused" | "rate_limited" | "timeout" | "network" | "upstream" | "malformed" | "too_large";
 /** Fixed sentence for a failure reason. */
 export declare const usageFailureText: (r: UsageFailure) => string;
 /** Carries only a reason tag. Its message is the fixed sentence: nothing upstream can reach it. */
@@ -55,3 +67,10 @@ export declare function fetchMeasuredUsage(key: string | undefined, period: {
     start: string;
     end: string;
 }, deps?: AnthropicUsageDeps): Promise<MeasuredUsage>;
+/** A WIF access token as the bearer for the two report reads. Printable ASCII only, else key_invalid. */
+export declare function bearerAuth(token: string): AnthropicAuthHeader;
+/** The two reads with an already-resolved credential (pasted key or WIF bearer). Throws AnthropicUsageError only. */
+export declare function fetchMeasuredUsageWithAuth(auth: AnthropicAuthHeader, period: {
+    start: string;
+    end: string;
+}, deps?: AnthropicUsageDeps): Promise<MeasuredUsage>;