@mnemom/mnemom 0.17.31-next.1 → 0.17.32-next.0

package/dist/lib/agent.js

@@ -22,6 +22,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { canonicalJson } from "./canonical-json.js";
 import { getGatewayUrl } from "./config.js";
 import { normSession } from "./slack-route.js";
 /** The us-2/prod gateway host. The default door — never any other cell silently. */
@@ -438,6 +439,7 @@ export const AGENT_SUB_VERBS = new Set([
     "move",
     "export",
     "sessions",
+    "fuel",
     "show",
     "goal",
 ]);
@@ -480,23 +482,7 @@ export function isPositiveNumber(value) {
     const n = Number(s);
     return Number.isFinite(n) && n > 0;
 }
-/**
- * Canonical JSON — object keys sorted recursively, arrays in order, no
- * whitespace, `undefined` keys dropped. Byte-identical to the gateway's
- * `canonicalJson` (gateway/src/goal-contract.ts), so the base64 we send and the
- * sha we print match what the gateway seals.
- */
-export function canonicalJson(value) {
-    if (value === null || typeof value !== "object")
-        return JSON.stringify(value);
-    if (Array.isArray(value))
-        return `[${value.map(canonicalJson).join(",")}]`;
-    const obj = value;
-    const keys = Object.keys(obj)
-        .filter((k) => obj[k] !== undefined)
-        .sort();
-    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`;
-}
+export { canonicalJson } from "./canonical-json.js";
 /** sha256 hex (first 16 chars) of a string — the operator-eyeball contract hash. */
 export function sha256Hex16(text) {
     return createHash("sha256").update(text, "utf8").digest("hex").slice(0, 16);
@@ -652,7 +638,8 @@ export const COMPACTION_INTERCEPT_KEY = "GATEWAY_COMPACTION_INTERCEPT";
 /**
  * The gateway env key that has it measure each request's saving for a single session and put
  * it in the client-facing usage (`mnemom_savings` in the read `usage.iterations` entry), where
- * the status bar reads it from Claude Code's transcript. Default OFF on the gateway; sent `"on"`
+ * it lands in Claude Code's transcript. The status bar never shows it (decision 14: never
+ * "saved"). Default OFF on the gateway; sent `"on"`
  * only while the `measured-savings` experimental feature is on and the launched CLI is Claude
  * Code (`resolveUsageSavings`). Independent of folding, so every profile sends it — `off` too,
  * where the measured saving is honestly $0.00.
@@ -1283,9 +1270,9 @@ export function resolveCompactionIntercept(opts) {
     return !(raw === "0" || raw === "false" || raw === "off" || raw === "no");
 }
 /**
- * Does the gateway measure this launch's saving (`GATEWAY_USAGE_SAVINGS` in the header, and the
- * status bar in measured mode)? Only with the `measured-savings` experimental feature on, and
- * only for Claude Code — the one CLI whose status bar reads the measurement. No flag or
+ * Does the gateway measure this launch's saving (`GATEWAY_USAGE_SAVINGS` in the header)? Only
+ * with the `measured-savings` experimental feature on, and only for Claude Code, whose
+ * transcript keeps the measurement. No flag or
  * launcher.toml key: `mnemom experimental enable measured-savings` is the switch.
  */
 export function resolveUsageSavings(opts) {
@@ -1333,27 +1320,42 @@ export function buildHandoffMcpConfig(p) {
 export function buildHandoffMcpConfigJson(p) {
     return JSON.stringify(buildHandoffMcpConfig(p));
 }
+/** Does a Claude Code passthrough run headless (`-p` / `--print`)? */
+export function passthroughIsPrint(passthrough) {
+    return passthrough.some((a) => a === "-p" || a === "--print" || a.startsWith("--print="));
+}
 /**
  * Is this launch implicit-mode? Precedence, highest wins:
  *   1. an explicit flag — `--implicit` (true) or `--no-implicit` (false);
  *   2. a `--goal` statement — a sealed contract is a per-launch choice that the
- *      standing config default must never silently override;
+ *      standing config default must never silently override, so a launch never
+ *      runs both modes;
  *   3. the config default `goal_mode` — `"off"` turns alignment off, `"implicit"`
  *      keeps it implicit;
- *   4. with the `implicit` experimental feature ON, IMPLICIT: the gateway infers
- *      the goal from the user's own messages (turn it off for a launch with
- *      `--no-implicit`, or standing with `goal_mode = "off"`); with it OFF (the
- *      default), OFF.
+ *   4. with the `implicit` experimental feature ON, IMPLICIT (as before T16);
+ *   5. on a prerelease (`next`) build, IMPLICIT for an interactive or Remote Control
+ *      launch and OFF for a headless `-p` one (OD-13: T16 never covers `-p`);
+ *   6. otherwise OFF — stable without the experimental feature behaves as today.
  * Pure so every arm is unit-tested; the caller passes the resolved value on to
  * `assembleContract` / `buildGoalModeHeader` (which still refuse `--implicit`
  * combined with a contract flag — that conflict is EXPLICIT and is reported).
  */
-export function resolveImplicit(opts) {
+export function resolveImplicitSource(opts) {
     if (opts.implicit !== undefined)
-        return opts.implicit;
+        return { implicit: opts.implicit, source: "flag" };
     if (hasText(opts.goal))
-        return false;
-    if (opts.experimentalOn === false)
-        return false;
-    return opts.configGoalMode !== "off";
+        return { implicit: false, source: "goal" };
+    const experimentalOn = opts.experimentalOn !== false;
+    if (!experimentalOn && !opts.prerelease)
+        return { implicit: false, source: "default" };
+    if (opts.configGoalMode !== undefined) {
+        return { implicit: opts.configGoalMode === "implicit", source: "config" };
+    }
+    if (experimentalOn)
+        return { implicit: true, source: "experimental" };
+    return { implicit: !opts.print, source: opts.print ? "default" : "prerelease" };
+}
+/** `resolveImplicitSource(opts).implicit`. */
+export function resolveImplicit(opts) {
+    return resolveImplicitSource(opts).implicit;
 }

package/dist/lib/api.d.ts

@@ -236,6 +236,12 @@ export declare function verifyBinding(agentId: string, keyHash: string): Promise
     bound: boolean;
     key_prefix: string | null;
 }>;
+/**
+ * GET /v1/agents/:id, sent with the caller's credentials. The API answers with the projection
+ * the caller may see: the org-member view (claimed_by, org_id, `caller: "org_member"`) for an
+ * agent in one of the caller's orgs, the public view otherwise. A pinned launch needs the member
+ * view, so an unauthenticated read here refuses every pin.
+ */
 export declare function getAgent(id: string): Promise<Agent>;
 export interface AgentListItem {
     id: string;
@@ -431,6 +437,19 @@ export interface MuBalance {
     effectiveMode?: string;
     enforcementPausedReason?: string | null;
 }
+/**
+ * GET /v1/orgs/{org_id}/record/totals?lineage_key= — one lineage's model cost and μ as
+ * decimal-string millimu (`mu_charged_mmu` null until billing commits a charge). Dark unless the
+ * org is in the record-accumulator cohort: a 404 then, like an unknown lineage.
+ */
+export interface RecordTotals {
+    lineage_key: string;
+    model_cost_mmu: string;
+    mu_charged_mmu: string | null;
+    as_of: string;
+    row_count: number;
+}
+export declare function getRecordTotals(orgId: string, lineageKey: string, signal?: AbortSignal): Promise<RecordTotals>;
 export declare function getMuBalance(orgId?: string): Promise<MuBalance>;
 /**
  * Mint the one-time `cards:write:protection` capability for an agent — the
@@ -1277,6 +1296,40 @@ export interface OrgUsageQuery {
  * the user "org not found" on what is most often just the flag being off.
  */
 export declare function getOrgUsage(orgId: string, opts?: OrgUsageQuery): Promise<OrgUsageResponse>;
+/** One sealed contract in the batch-seal response (mnemom-api migration 582). */
+export interface SealedContractRow {
+    seal_id: string;
+    ordinal: number;
+    contract_sha256: string;
+    /** The deterministic node identity: `contract:<org_id>:<sha256>`. */
+    node_id: string;
+    version: number;
+    job_key: string | null;
+    canon_status: "pending" | "written";
+}
+/** `POST /v1/orgs/{org_id}/contract-step/batch-seal` 200 body. */
+export interface BatchSealResponse {
+    batch_id: string;
+    replayed: boolean;
+    repo: string;
+    seals: SealedContractRow[];
+    /** Whether the sealed contracts were handed to dispatch: off, enqueued, or deferred (fail open). */
+    dispatch: "off" | "enqueued" | "deferred";
+}
+export interface BatchSealRequest {
+    repo: string;
+    source: "cli";
+    contracts: Array<{
+        contract: unknown;
+        job_key?: string;
+    }>;
+}
+/**
+ * Seal a batch of job contracts in one transaction (Doors fuel step, W3.2). The caller passes the
+ * Idempotency-Key and holds it across retries, so a retried confirmation replays the first batch
+ * instead of sealing twice.
+ */
+export declare function sealContractBatch(orgId: string, body: BatchSealRequest, idempotencyKey: string, githubToken: string): Promise<BatchSealResponse>;
 /** `GET /v1/code/entitlement` 200 body — why Mnemom Agent is enabled for the org. */
 export interface CodeEntitlement {
     org_id: string;

package/dist/lib/api.js

@@ -112,14 +112,6 @@ export async function readApiError(response, fallback) {
         specDeviation: parsed.spec_deviation,
     });
 }
-async function fetchApi(endpoint) {
-    const url = validateUrl(`${API_BASE}${endpoint}`);
-    const response = await mnemomFetch(url);
-    if (!response.ok) {
-        throw await readApiError(response, "API request failed");
-    }
-    return response.json();
-}
 export async function postApi(endpoint, body, opts = {}) {
     const url = validateUrl(`${API_BASE}${endpoint}`);
     const headers = {
@@ -197,8 +189,19 @@ async function fetchWithAuthRetry(url, buildInit) {
         return first;
     return mnemomFetch(url, await buildInit());
 }
+/**
+ * GET /v1/agents/:id, sent with the caller's credentials. The API answers with the projection
+ * the caller may see: the org-member view (claimed_by, org_id, `caller: "org_member"`) for an
+ * agent in one of the caller's orgs, the public view otherwise. A pinned launch needs the member
+ * view, so an unauthenticated read here refuses every pin.
+ */
 export async function getAgent(id) {
-    return fetchApi(`/v1/agents/${id}`);
+    const url = validateUrl(`${API_BASE}/v1/agents/${id}`);
+    const response = await fetchWithAuthRetry(url, async () => ({ headers: await authHeaders() }));
+    if (!response.ok) {
+        throw await readApiError(response, "API request failed");
+    }
+    return (await response.json());
 }
 /**
  * Key-compatible agent listing — `GET /v1/agents` is scoped by the caller's
@@ -405,6 +408,9 @@ export async function getMyPersonalOrg() {
 export async function getMe() {
     return gFetch("/v1/auth/me", {}, { fallback: "Could not read your identity" });
 }
+export async function getRecordTotals(orgId, lineageKey, signal) {
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/record/totals?lineage_key=${encodeURIComponent(lineageKey)}`, signal ? { signal } : {}, { notFoundLabel: "Record totals", fallback: "Could not read record totals" });
+}
 export async function getMuBalance(orgId) {
     const q = orgId ? `?org_id=${encodeURIComponent(orgId)}` : "";
     return gFetch(`/v1/billing/mu${q}`, {}, { fallback: "Could not read MU balance" });
@@ -747,7 +753,7 @@ function emptyIntegrityRow(agentId) {
 export async function getTraces(id, limit = 10) {
     const data = await gFetch(`/v1/traces?agent_id=${id}&limit=${limit}`, {}, { fallback: "API request failed" });
     // Accept both the envelope shape (current API) and a bare array (defensive
-    // — staging is mid-deploy when a CLI smoke runs against an older API).
+    // — the test cell is mid-deploy when a CLI smoke runs against an older API).
     if (Array.isArray(data))
         return data;
     return data.traces ?? [];
@@ -1308,6 +1314,7 @@ async function gFetch(path, init = {}, opts = {}) {
             ...(init.headers ?? {}),
         },
         body: init.body,
+        ...(init.signal ? { signal: init.signal } : {}),
     }));
     if (!response.ok) {
         if (response.status === 401)
@@ -1569,6 +1576,20 @@ async function codeFetch(path, init = {}, fallback) {
     }
     return (await response.json());
 }
+/**
+ * Seal a batch of job contracts in one transaction (Doors fuel step, W3.2). The caller passes the
+ * Idempotency-Key and holds it across retries, so a retried confirmation replays the first batch
+ * instead of sealing twice.
+ */
+export async function sealContractBatch(orgId, body, idempotencyKey, githubToken) {
+    return codeFetch(`/v1/orgs/${encodeURIComponent(orgId)}/contract-step/batch-seal`, {
+        method: "POST",
+        body: JSON.stringify(body),
+        // The api checks with this token that the caller can write to the repo (OD-10). It reads
+        // it for that check only and never stores it.
+        headers: { "Idempotency-Key": idempotencyKey, "X-GitHub-Token": githubToken },
+    }, "Could not seal the contracts");
+}
 /** The machine-readable code on the gate's 403 when the org is not enabled. */
 export const CODE_NOT_ENABLED = "code_not_enabled";
 /**

package/dist/lib/canonical-json.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Canonical JSON: the one place the CLI serialises a contract for hashing. Kept in its own module,
+ * with no imports, so the contract hash helper and the thin runner can use it without loading
+ * agent.ts. `agent.ts` re-exports it for its existing importers.
+ */
+/**
+ * Canonical JSON — object keys sorted recursively, arrays in order, no
+ * whitespace, `undefined` keys dropped. Byte-identical to the gateway's
+ * `canonicalJson` (gateway/src/goal-contract.ts), so the base64 we send and the
+ * sha we print match what the gateway seals.
+ */
+export declare function canonicalJson(value: unknown): string;

package/dist/lib/canonical-json.js

@@ -0,0 +1,22 @@
+/**
+ * Canonical JSON: the one place the CLI serialises a contract for hashing. Kept in its own module,
+ * with no imports, so the contract hash helper and the thin runner can use it without loading
+ * agent.ts. `agent.ts` re-exports it for its existing importers.
+ */
+/**
+ * Canonical JSON — object keys sorted recursively, arrays in order, no
+ * whitespace, `undefined` keys dropped. Byte-identical to the gateway's
+ * `canonicalJson` (gateway/src/goal-contract.ts), so the base64 we send and the
+ * sha we print match what the gateway seals.
+ */
+export function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    const obj = value;
+    const keys = Object.keys(obj)
+        .filter((k) => obj[k] !== undefined)
+        .sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`;
+}

package/dist/lib/conduct-receipt.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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.
+ *
+ *   Conduct receipt
+ *     model cost  $0.42
+ *     μ           12.5
+ *
+ * Every figure is measured, never estimated (decision 14): model cost and μ are the session
+ * lineage's `record_accumulator` totals, read from `GET /v1/orgs/{org}/record/totals`. μ reads
+ * "μ pending" until billing has committed a charge for the lineage (the route's null), and the
+ * receipt then gives a link instead of a number.
+ *
+ * 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
+ * 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.
+ */
+/** The hard ceiling on what the receipt adds to exit (W1.3: at most 2 s). */
+export declare const RECEIPT_DEADLINE_MS = 1800;
+/** Pause between totals reads while μ is still pending. */
+export declare const RECEIPT_POLL_MS = 400;
+/** What the local proxy saw on the session's responses (base-url-proxy.mjs, record state). */
+export interface RecordState {
+    lineageKey?: string;
+    recordUrl?: string;
+}
+/** A totals read: the route's two amounts, or why there are none. */
+export type TotalsRead = {
+    kind: "ok";
+    modelCostMmu: bigint;
+    muChargedMmu: bigint | null;
+} | {
+    kind: "unavailable";
+};
+export interface ReceiptDeps {
+    /** One totals read for the lineage; may throw or hang (both are "unavailable"). */
+    readTotals: (lineageKey: string, signal: AbortSignal) => Promise<TotalsRead>;
+    /** The page the receipt links to when no record URL was captured (the agent dashboard). */
+    fallbackUrl: string;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    deadlineMs?: number;
+    pollMs?: number;
+}
+/** Read the proxy's record-state file; a missing or malformed file is an empty state. */
+export declare function readRecordState(path: string | undefined): RecordState;
+/** Keep only a well-formed lineage key and an https record URL. */
+export declare function sanitizeRecordState(raw: Record<string, unknown>): RecordState;
+/** Parse the totals route body; anything off-contract is "unavailable", never a guessed figure. */
+export declare function parseTotals(body: unknown): TotalsRead;
+/** `$0.42`; a non-zero cost under a cent reads `< $0.01`, never `$0.00`. */
+export declare function formatUsd(mmu: bigint): string;
+/** μ to at most three decimals, trailing zeros dropped: 12500 mmu → `12.5`. */
+export declare function formatMu(mmu: bigint): string;
+/** The receipt lines for what was read (pure). */
+export declare function receiptLines(read: TotalsRead | null, link: string, trigger?: "exit" | "park"): string[];
+/**
+ * Read the lineage's totals until μ is final or the deadline passes, then return the receipt.
+ * Never throws and never waits past `deadlineMs`.
+ */
+export declare function buildConductReceipt(state: RecordState, deps: ReceiptDeps, trigger?: "exit" | "park"): Promise<string[]>;
+/** Where the receipt's launch facts come from (the launcher at exit; Durable at park). */
+export interface ReceiptLaunch {
+    orgId: string;
+    /** The served agent id: the fallback link is its dashboard page. */
+    agentId: string;
+    /** The proxy's record-state file (absent: no lineage was captured). */
+    statePath?: string;
+}
+/**
+ * The receipt for a launch, against the real API (the exit and park call sites).
+ *
+ * The deadline bounds what the caller waits for, not every network call: on a 401 the auth
+ * refresh (fetchWithAuthRetry) takes no signal and may outlive the receipt. The exit path
+ * process.exit()s right after; a long-lived caller (a durable park) may see it finish later.
+ */
+export declare function conductReceiptFor(launch: ReceiptLaunch, trigger?: "exit" | "park", deps?: Partial<ReceiptDeps>): Promise<string[]>;

package/dist/lib/conduct-receipt.js

@@ -0,0 +1,177 @@
+/**
+ * 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.
+ *
+ *   Conduct receipt
+ *     model cost  $0.42
+ *     μ           12.5
+ *
+ * Every figure is measured, never estimated (decision 14): model cost and μ are the session
+ * lineage's `record_accumulator` totals, read from `GET /v1/orgs/{org}/record/totals`. μ reads
+ * "μ pending" until billing has committed a charge for the lineage (the route's null), and the
+ * receipt then gives a link instead of a number.
+ *
+ * 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
+ * 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 { 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;
+/** Pause between totals reads while μ is still pending. */
+export const RECEIPT_POLL_MS = 400;
+/** 1 MU = 1000 mmu; 1 USD = 100 000 mmu (mnemom-api src/billing/pricing.ts MMU_PER_USD). */
+const MMU_PER_MU = 1000n;
+const MMU_PER_USD = 100000n;
+const LINEAGE_KEY_RE = /^[A-Za-z0-9:._-]{1,256}$/;
+const MMU_RE = /^(0|[1-9][0-9]{0,18})$/;
+/** Read the proxy's record-state file; a missing or malformed file is an empty state. */
+export function readRecordState(path) {
+    if (!path)
+        return {};
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        return sanitizeRecordState(raw);
+    }
+    catch {
+        return {};
+    }
+}
+/** Keep only a well-formed lineage key and an https record URL. */
+export function sanitizeRecordState(raw) {
+    const out = {};
+    if (typeof raw.lineage_key === "string" && LINEAGE_KEY_RE.test(raw.lineage_key)) {
+        out.lineageKey = raw.lineage_key;
+    }
+    if (typeof raw.record_url === "string" && isHttpsUrl(raw.record_url)) {
+        out.recordUrl = raw.record_url;
+    }
+    return out;
+}
+/** Printable ASCII only: the URL is printed to the user's terminal, so no escape bytes. */
+const PRINTABLE_URL_RE = /^https:\/\/[\x21-\x7e]+$/;
+function isHttpsUrl(s) {
+    if (s.length > 2048 || !PRINTABLE_URL_RE.test(s))
+        return false;
+    try {
+        return new URL(s).protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+/** Parse the totals route body; anything off-contract is "unavailable", never a guessed figure. */
+export function parseTotals(body) {
+    if (!body || typeof body !== "object")
+        return { kind: "unavailable" };
+    const b = body;
+    if (typeof b.model_cost_mmu !== "string" || !MMU_RE.test(b.model_cost_mmu)) {
+        return { kind: "unavailable" };
+    }
+    let mu = null;
+    if (b.mu_charged_mmu !== null) {
+        if (typeof b.mu_charged_mmu !== "string" || !MMU_RE.test(b.mu_charged_mmu)) {
+            return { kind: "unavailable" };
+        }
+        mu = BigInt(b.mu_charged_mmu);
+    }
+    return { kind: "ok", modelCostMmu: BigInt(b.model_cost_mmu), muChargedMmu: mu };
+}
+/** `$0.42`; a non-zero cost under a cent reads `< $0.01`, never `$0.00`. */
+export function formatUsd(mmu) {
+    if (mmu > 0n && mmu * 100n < MMU_PER_USD)
+        return "< $0.01";
+    const cents = (mmu * 100n + MMU_PER_USD / 2n) / MMU_PER_USD;
+    return `$${cents / 100n}.${String(cents % 100n).padStart(2, "0")}`;
+}
+/** μ to at most three decimals, trailing zeros dropped: 12500 mmu → `12.5`. */
+export function formatMu(mmu) {
+    const whole = mmu / MMU_PER_MU;
+    const frac = String(mmu % MMU_PER_MU)
+        .padStart(3, "0")
+        .replace(/0+$/, "");
+    return frac ? `${whole}.${frac}` : `${whole}`;
+}
+/** 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") {
+        return [head, `  record not available yet: ${link}`];
+    }
+    const lines = [head, `  model cost  ${formatUsd(read.modelCostMmu)}`];
+    if (read.muChargedMmu === null)
+        lines.push(`  μ pending   ${link}`);
+    else
+        lines.push(`  μ           ${formatMu(read.muChargedMmu)}`);
+    return lines;
+}
+/**
+ * Read the lineage's totals until μ is final or the deadline passes, then return the receipt.
+ * Never throws and never waits past `deadlineMs`.
+ */
+export async function buildConductReceipt(state, deps, trigger = "exit") {
+    const link = state.recordUrl ?? deps.fallbackUrl;
+    if (!state.lineageKey)
+        return receiptLines(null, link, trigger);
+    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);
+    const pollMs = deps.pollMs ?? RECEIPT_POLL_MS;
+    const lineageKey = state.lineageKey;
+    let last = null;
+    for (;;) {
+        const left = deadline - now();
+        if (left <= 0)
+            break;
+        const read = await readWithin(deps.readTotals, lineageKey, left);
+        // A later failure never hides an earlier good read.
+        if (read.kind === "ok" || !last)
+            last = read;
+        if (read.kind === "ok" && read.muChargedMmu !== null)
+            break;
+        if (deadline - now() <= pollMs)
+            break;
+        await sleep(pollMs);
+    }
+    return receiptLines(last, link, trigger);
+}
+async function readWithin(readTotals, lineageKey, ms) {
+    const ac = new AbortController();
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            ac.abort();
+            resolve({ kind: "unavailable" });
+        }, ms);
+    });
+    try {
+        return await Promise.race([
+            readTotals(lineageKey, ac.signal).catch(() => ({ kind: "unavailable" })),
+            timeout,
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * The receipt for a launch, against the real API (the exit and park call sites).
+ *
+ * The deadline bounds what the caller waits for, not every network call: on a 401 the auth
+ * refresh (fetchWithAuthRetry) takes no signal and may outlive the receipt. The exit path
+ * process.exit()s right after; a long-lived caller (a durable park) may see it finish later.
+ */
+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))),
+        fallbackUrl: deps.fallbackUrl ?? `${getWebsiteUrl()}/agents/${encodeURIComponent(launch.agentId)}`,
+    }, trigger);
+}

package/dist/lib/contract-hash.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The contract's full sha256 and seal-time check, as the gateway computes them (Doors W3.5).
+ *
+ * Callers that hash contracts outside the gateway (the fuel step's CLI verb and the thin runner,
+ * each in its own change) use this module. It computes a contract's hash, its committed file's
+ * bytes and its repo path; writing the file is the caller's job. It ports the gateway's
+ * `normaliseContractObject` / `checkContractObject` / `canonicalHash` (gateway/src/goal-contract.ts). The full sha256 is the digest whose first 16
+ * hex characters are the gateway's `x-mnemom-contract-hash`: sha256 of the canonical JSON of the
+ * normalised contract, with a default `"nudge"` mode dropped and `"enforce"` kept. The 8 KB
+ * limit is measured, like the gateway's, on the canonical JSON with the mode still present.
+ *
+ * `gateway/test/fixtures/contract-sha256-parity.json` pins the gateway's own outputs; the CLI's
+ * parity suite and mnemom-api's (`src/contract-step/hash.ts`) read the same cases.
+ */
+/** The gateway's `CONTRACT_JSON_MAX`: bytes of canonical JSON of the normalised contract. */
+export declare const CONTRACT_JSON_MAX = 8192;
+/** The gateway's `STATEMENT_MAX` (its `USER_CLIP`), in characters. */
+export declare const STATEMENT_MAX = 4000;
+export type ContractMode = "nudge" | "enforce";
+/** pv2 SealedContract, the shape the gateway seals from `x-mnemom-contract`. */
+export interface Contract {
+    goal_id?: string;
+    statement: string;
+    requirements: string[];
+    allowed_paths: string[];
+    forbidden_paths: string[];
+    max_turns?: number;
+    budget_usd?: number;
+    stall_turns?: number;
+    time_limit_s?: number;
+    mode?: ContractMode;
+}
+export type ContractRejectReason = "unparseable" | "statement_missing" | "statement_too_long" | "contract_too_large" | "mode_invalid";
+export type ContractCheck = {
+    ok: true;
+    contract: Contract;
+} | {
+    ok: false;
+    reason: ContractRejectReason;
+    message: string;
+};
+/** The gateway's `normaliseContractObject`: null without a non-empty statement. Mode defaults to "nudge". */
+export declare function normaliseContract(obj: Record<string, unknown>): Contract | null;
+/** The gateway's seal-time gate (`checkContractObject`), with the same reasons. */
+export declare function checkContract(value: unknown, label?: string): ContractCheck;
+/** Bytes the 8 KB limit measures: canonical JSON of the normalised contract, mode included. */
+export declare function contractSizeBytes(contract: Contract): number;
+/** The hash form: a default "nudge" mode dropped, "enforce" kept (the gateway's `canonicalHash`). */
+export declare function hashForm(contract: Contract): Contract;
+/**
+ * The committed contract file's exact bytes: canonical JSON of the hash form, no trailing newline,
+ * so sha256 of the file equals `contractSha256`.
+ */
+export declare function contractFileText(contract: Contract): string;
+/** Full lowercase-hex sha256. Its first 16 characters are the gateway's `x-mnemom-contract-hash`. */
+export declare function contractSha256(contract: Contract): string;
+/**
+ * Where a sealed contract is committed in the repo: content-addressed by its full sha256. Throws
+ * on anything but 64 lowercase hex characters, so the path can never leave `.mnemom/contracts/`.
+ */
+export declare function contractRepoPath(sha256: string): string;