privateer-agent 0.12.13 → 0.12.15

package/src/outbox/cloudOutbox.ts

@@ -68,6 +68,62 @@ export interface OutboxMedia {
   blobId?: string;
 }
 
+/**
+ * What the run was ASKED to do, carried beside what it answered.
+ *
+ * A result on its own is a dead end: the app can show it, read it aloud and file
+ * it, but "now book the top one" needs the standing instruction the run was given,
+ * and the directory it ran in, or the follow-up starts from a summary with no idea
+ * what produced it. That context is the routine — it lives on this machine and the
+ * app has never seen it — so it rides inside the SEALED envelope (the server holds
+ * ciphertext either way, exactly like `origin`).
+ *
+ * Every field is optional and clipped: this travels on every result, and a routine
+ * prompt can be arbitrarily long. Absent → the app falls back to the result body
+ * alone, which is what results from older CLIs carry.
+ */
+export interface OutboxSource {
+  /** The saved routine's id, when one produced this. Absent for ad-hoc tasks. */
+  routineId?: string;
+  /** The instruction the run was given (a routine's `prompt`, a task's spec). */
+  prompt?: string;
+  /** Where the run executed — a follow-up belongs in the same directory. */
+  cwd?: string;
+  /** The "provider:model" the run resolved to. */
+  model?: string;
+  /** The trigger verbatim: a cron expression, or a one-off ISO datetime. */
+  schedule?: string;
+}
+
+/** Clip bounds for `source`. The prompt is the only field that can be long. */
+export const MAX_SOURCE_PROMPT = 2_000;
+const SOURCE_FIELD_CAPS: Record<keyof OutboxSource, number> = {
+  routineId: 200,
+  prompt: MAX_SOURCE_PROMPT,
+  cwd: 500,
+  model: 200,
+  schedule: 100,
+};
+
+/**
+ * Normalize a source for the envelope: trim, clip, drop empties — and return
+ * undefined when nothing survives, so a workflow (or an empty-prompt live spawn)
+ * doesn't ship an empty object and bump the envelope version for nothing.
+ * Exported for the round-trip test.
+ */
+export function packSource(source?: OutboxSource): OutboxSource | undefined {
+  if (!source) return undefined;
+  const out: OutboxSource = {};
+  for (const [key, cap] of Object.entries(SOURCE_FIELD_CAPS) as [keyof OutboxSource, number][]) {
+    const raw = source[key];
+    if (typeof raw !== "string") continue;
+    const value = raw.trim();
+    if (!value) continue;
+    out[key] = value.length > cap ? value.slice(0, cap) + "…" : value;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
 let outboxPub: Uint8Array | undefined;
 let originCache: { id: string; label: string } | undefined;
 
@@ -216,6 +272,9 @@ function undeliveredNote(names: string[]): string {
  * BEFORE the message, so a message that lands always references bytes that exist;
  * if the message then fails, the blobs are dropped again and the caller's queued
  * retry re-uploads from the same paths on disk.
+ *
+ * `source` is what the run was asked to do (see OutboxSource) — the context a
+ * follow-up needs, sealed alongside the answer.
  */
 export async function postOutbox(
   name: string,
@@ -224,20 +283,28 @@ export async function postOutbox(
   content: string,
   kind: OutboxKind = "routine",
   staged: StagedMedia[] = [],
+  source?: OutboxSource,
 ): Promise<boolean> {
   const pub = await ensureOutboxPub();
   if (!pub) return false;
   let body = content.length > MAX_CLOUD_PLAINTEXT ? content.slice(0, MAX_CLOUD_PLAINTEXT) + "\n…truncated" : content;
 
+  // Packed before the media budget is struck, because it spends the same envelope:
+  // attachments must not be sized against room the source has already taken.
+  const packedSource = packSource(source);
+  const sourceCost = packedSource ? JSON.stringify(packedSource).length : 0;
+
   const { media, blobIds, undelivered } = staged.length
-    ? await packMedia(pub, staged, MAX_ENVELOPE_PLAINTEXT - body.length - 2_000)
+    ? await packMedia(pub, staged, MAX_ENVELOPE_PLAINTEXT - body.length - sourceCost - 2_000)
     : { media: [] as OutboxMedia[], blobIds: [] as string[], undelivered: [] as string[] };
   body += undeliveredNote(undelivered);
 
-  // v2 adds `media`. Older apps ignore the field and still render the body, which is
-  // why the note above names undelivered files in prose rather than only in metadata.
+  // v2 adds `media`, v3 `source`. Both are additive: an older app ignores the field
+  // and still renders the body, which is why the note above names undelivered files
+  // in prose rather than only in metadata, and why a follow-up degrades to "the
+  // result text alone" rather than failing when `source` is missing.
   const envelope: Record<string, unknown> = {
-    v: media.length > 0 ? 2 : 1,
+    v: packedSource ? 3 : media.length > 0 ? 2 : 1,
     kind,
     name,
     status,
@@ -245,6 +312,7 @@ export async function postOutbox(
     content: body,
     origin: machineOrigin(),
     ...(media.length > 0 ? { media } : {}),
+    ...(packedSource ? { source: packedSource } : {}),
   };
 
   let sealed = sealJson(pub, envelope);

package/src/permissions/childSpend.ts

@@ -0,0 +1,105 @@
+// Handing an unattended run's SPEND AUTHORIZATION down to its subagent children.
+//
+// THE PROBLEM. A subagent is a fresh headless `pi` subprocess (pi-subagents, spawned
+// through bin/privateer-subagent.mjs), so it inherits nothing from its parent except the
+// environment and the `-e` moat the wrapper injects. Its gate therefore runs in bypass
+// with a fail-closed asker: ordinary writes go through, and every `alwaysAsk` tool — which
+// is every billing media tool — is denied, because there is no human on the other end of
+// a headless child's stdin. So "one subagent per shot" worked in a terminal, where the
+// child's ask relays up to the parent's TUI, and quietly could not work at all in the one
+// place it matters most: a routine that fires at 3am to build a film.
+//
+// WHAT IS HANDED DOWN, AND WHY THAT IS NOT A HOLE. Only the names of billing tools the
+// operator already authorized for this run, by naming them when they saved the routine —
+// media generation is deliberately absent from the harbor's default allow-list precisely
+// so that granting it is a decision someone made. The child gets no more than its parent
+// has, and the gate still refuses to let a pre-authorization cover a call that leaves the
+// working directory or touches a protected file (see ModeGate.isSpendPreauthorized).
+//
+// HONOURED ONLY IN A CHILD. `PRIVATEER_CHILD_SPEND` sitting in a developer's shell must
+// never turn a TERMINAL into a session that bills without asking, so the child side reads
+// it only when pi-subagents has marked this process as a child. A top-level session always
+// asks its human, however cheap the call.
+//
+// CONCURRENCY, AND WHY THE UNION WOULD BE WRONG. The harbor daemon can have two unattended
+// runs in flight at once (a scheduled routine and an app-submitted task), and children read
+// the environment when they spawn — one process-wide variable, two different grants. Taking
+// the union would let run B's child spend on a tool only run A was granted. So the exported
+// value is the INTERSECTION of every grant currently in flight: exact when one run holds a
+// grant (the overwhelmingly common case), and narrowing — fail-closed, with the gate's
+// ordinary denial message — when two overlap. A child denied that way reports it plainly;
+// a child over-granted would bill silently.
+
+import { isSubagentChild } from "../remote/subagentRelay.ts";
+
+/** The env var carrying a run's spend grant to its (possibly nested) children. */
+export const CHILD_SPEND_ENV = "PRIVATEER_CHILD_SPEND";
+
+// Grants currently in flight, keyed by the run that holds one. Module-level because the
+// value it projects is process-wide (the environment) — one registry per daemon.
+const active = new Map<string, ReadonlySet<string>>();
+
+function publish(): void {
+  if (active.size === 0) {
+    delete process.env[CHILD_SPEND_ENV];
+    return;
+  }
+  const sets = [...active.values()];
+  const shared = [...sets[0]].filter((tool) => sets.every((s) => s.has(tool)));
+  if (shared.length === 0) delete process.env[CHILD_SPEND_ENV];
+  else process.env[CHILD_SPEND_ENV] = [...new Set(shared)].sort().join(",");
+}
+
+/**
+ * Advertise `tools` to children spawned while this run is in flight, and return the
+ * release. ALWAYS call the release in a `finally`: a grant that outlives its run would
+ * authorize the next one's children, which is the whole thing this is careful about.
+ * An empty/absent `tools` registers nothing, so a run with no media grant neither widens
+ * nor narrows what a concurrent run advertises.
+ */
+export function grantChildSpend(runKey: string, tools: Iterable<string> | undefined): () => void {
+  const set = new Set([...(tools ?? [])].filter((t) => typeof t === "string" && t.trim() !== ""));
+  if (set.size === 0) return () => {};
+  active.set(runKey, set);
+  publish();
+  return () => {
+    active.delete(runKey);
+    publish();
+  };
+}
+
+/** Test seam: forget every in-flight grant (and the env var it projects). */
+export function resetChildSpend(): void {
+  active.clear();
+  delete process.env[CHILD_SPEND_ENV];
+}
+
+/**
+ * The grant this process inherited — empty unless we ARE a subagent child, so a stray
+ * env var can never lower a terminal's gate. Parsed defensively: unknown names simply
+ * never match a tool, and the gate's own guards bound what a match can authorize.
+ */
+export function inheritedChildSpend(env: NodeJS.ProcessEnv = process.env): ReadonlySet<string> {
+  if (!isSubagentChild()) return new Set();
+  const raw = env[CHILD_SPEND_ENV];
+  if (!raw) return new Set();
+  return new Set(
+    raw
+      .split(",")
+      .map((t) => t.trim())
+      .filter(Boolean),
+  );
+}
+
+/**
+ * Is `tool` pre-authorized for this process? False everywhere but a child that was
+ * granted it. Shape matches GateController.isSpendPreauthorized's needs.
+ */
+export function childSpendAllows(tool: string): boolean {
+  return inheritedChildSpend().has(tool);
+}
+
+/** Does this child hold any spend grant at all — i.e. should billing tools exist here? */
+export function childHoldsSpendGrant(): boolean {
+  return inheritedChildSpend().size > 0;
+}

package/src/permissions/classify.ts

@@ -118,6 +118,14 @@ function str(v: unknown): string {
   return typeof v === "string" ? v : v == null ? "" : String(v);
 }
 
+// A path from a list entry that may be a bare string or an object carrying one —
+// video_compose's `tracks` and `images` take both, and the tools open whichever arrives,
+// so the classifier has to resolve whichever arrives. Miss the object form and
+// `tracks: [{path: "~/.ssh/id_rsa"}]` reads a key with `outside` left false.
+function nestedPath(entry: unknown): string {
+  return entry && typeof entry === "object" ? str((entry as Record<string, unknown>).path) : str(entry);
+}
+
 function firstPath(input: Record<string, unknown>): string {
   return str(input.path ?? input.file_path ?? input.file ?? input.filename ?? input.dir ?? input.directory);
 }
@@ -166,8 +174,10 @@ const BASH_TOOLS = new Set(["bash", "shell", "run", "exec", "sh"]);
 const MEDIA_TOOLS = new Set([
   "generate_image",
   "generate_video",
+  "generate_model",
   "generate_speech",
   "generate_music",
+  "generate_sfx",
   "media_capabilities",
   "video_compose",
 ]);
@@ -181,17 +191,30 @@ const MEDIA_TOOLS = new Set([
 // remembered, so every generation is a fresh human decision. video_compose is
 // excluded on purpose — it is local ffmpeg, no egress and no spend — and
 // media_capabilities is a read.
-const MEDIA_GEN_TOOLS = new Set([
+// Exported because it is the definition of "this call bills, so a human decides": the
+// harbor reads it to work out which of a routine's granted tools its pre-authorization
+// has to cover (harbor/index.ts), and a second hand-written copy of this list there
+// would be one that drifts.
+export const BILLED_MEDIA_TOOLS: ReadonlySet<string> = new Set([
   "generate_image",
   "generate_video",
+  "generate_model",
   "generate_speech",
   "generate_music",
+  "generate_sfx",
 ]);
 const MEDIA_TITLES: Record<string, string> = {
   generate_image: "Generate an image (billed to your Privateer account)",
   generate_video: "Generate a video (billed to your Privateer account)",
+  // The dearest of these per call, and the one whose price moves with the
+  // options, so the title says so out loud rather than leaving the human to
+  // work it out from a JSON blob of flags.
+  generate_model: "Generate a 3D model (billed; $0.14-$2.41 a mesh depending on the model)",
   generate_speech: "Generate speech (billed to your Privateer account)",
   generate_music: "Generate music (billed; music prompts have no zero-retention option)",
+  // Cheap per call and therefore the one most likely to be called twenty times in a
+  // row for a single cut, which is the number the title should let a human weigh.
+  generate_sfx: "Generate a sound effect (billed ~$0.02; effect models are non-ZDR)",
   video_compose: "Compose video/audio locally",
   media_capabilities: "Read media capabilities",
 };
@@ -225,6 +248,28 @@ export function classifyToolCall(
     };
   }
 
+  // Reading a routine back (src/tools/routineResult.ts): its stored instruction and
+  // its latest result. A READ, and it must be classified as one — the unknown-tool
+  // branch at the bottom would call it bash-kind, which prompts with a JSON blob and
+  // denies outright in plan/readonly, the very posture where "what did last night's
+  // run find?" is the most reasonable question there is.
+  //
+  // It still asks in default mode rather than returning null: the files live in
+  // ~/.privateer (outside any cwd) and can hold whatever the run collected, so
+  // pulling one into a session is the user's call, exactly as reading the file by
+  // hand would be. It takes a NAME, not a path, so there is no target to resolve —
+  // `outside` is therefore left unset (setting it would force a prompt even under
+  // acceptEdits for a read the user just asked for).
+  if (name === "read_routine_result") {
+    const label = str(obj.name);
+    return {
+      tool: toolName,
+      kind: "read",
+      title: "Read a routine's saved result",
+      detail: label ? `routine "${label}" (instruction + latest result)` : "list saved routines",
+    };
+  }
+
   // Media generation (src/tools/media.ts) and local composition (videoCompose.ts).
   //
   // Left to the unknown-tool branch at the bottom these classify as bash-kind, which
@@ -243,9 +288,22 @@ export function classifyToolCall(
       ...(Array.isArray(obj.inputs) ? (obj.inputs as unknown[]).map(str) : []),
       str(obj.input),
       str(obj.audio),
-      ...(Array.isArray(obj.images) ? (obj.images as unknown[]).map(str) : []),
+      // `images` is a list of paths for generate_video's reference stills and a list of
+      // OBJECTS for video_compose overlay_image's layers — both shapes have to resolve, or
+      // the nested one is a path the gate never judges.
+      ...(Array.isArray(obj.images) ? (obj.images as unknown[]).map(nestedPath) : []),
       str(obj.firstFrame),
       str(obj.lastFrame),
+      // video_compose mix_audio carries its paths INSIDE objects — one per placed
+      // track — and a nested path is one the gate would never judge: `tracks:
+      // [{path: "~/.ssh/id_rsa"}]` would read a key outside scope with `outside`
+      // left false. Bare strings are accepted here too because the tool accepts
+      // them, and the classifier must see whatever the tool will open.
+      ...(Array.isArray(obj.tracks) ? (obj.tracks as unknown[]).map(nestedPath) : []),
+      // overlay_text renders a font file into the frame, and burn_subtitles reads a whole
+      // subtitle file into it, so an out-of-scope or protected one is a read like any other.
+      str(obj.fontFile),
+      str(obj.subtitles),
     ].filter(Boolean);
     // Resolve each input once, then flag the two ways an input is sensitive: it leaves
     // the working directory, or it is a guarded file (.env, keys, credentials, …). The
@@ -297,7 +355,7 @@ export function classifyToolCall(
       detail: `${outputOutside ? absOut : outPath}${inputNote}`,
       protected: isProtectedPath(absOut) || protectedInputs.length > 0,
       outside,
-      alwaysAsk: MEDIA_GEN_TOOLS.has(name),
+      alwaysAsk: BILLED_MEDIA_TOOLS.has(name),
       path: absOut,
     };
   }

package/src/permissions/modeGate.ts

@@ -54,6 +54,16 @@ export interface ModeGateDeps {
   // the remote branch, even the dangerous-command denylist): the operator has
   // explicitly opted the whole session out of the moat. Off unless the flag is set.
   getSkipAllPermissions?: () => boolean;
+  // Spend the operator authorized IN ADVANCE, by tool name, at a moment when there WAS
+  // a human to ask: the media tools a routine names when it is saved (naming them is
+  // itself the decision — they are deliberately absent from the default allow-list, and
+  // saving a routine that grants egress is an alwaysAsk prompt of its own), handed to
+  // the run that fires hours later with nobody watching.
+  //
+  // Consulted ONLY to lift `alwaysAsk`, and only under the guards in ModeGate.request.
+  // Absent ⇒ nothing is pre-authorized, which is the posture every interactive session
+  // keeps: a terminal always asks its human, however cheap the call.
+  isSpendPreauthorized?: (req: PermissionRequest) => boolean;
 }
 
 // The permission gate used by the live TUI. It first applies the mode/allowlist
@@ -96,6 +106,35 @@ export class ModeGate implements PermissionGate {
 
     if (auto !== "ask") return auto;
 
+    // Pre-authorized spend. An unattended run reaches here with no one to ask, so an
+    // `alwaysAsk` tool — every billing media tool — was denied outright: the harbor
+    // let a routine NAME generate_video and then blocked every call it made, which is
+    // not a safe default so much as a capability that silently didn't exist.
+    //
+    // This lifts that one veto, and only that one. Four guards, all load-bearing:
+    //
+    //   • the controller must vouch for THIS tool by name (the harbor passes the media
+    //     tools this run's own allow-list names — see harbor/index.ts);
+    //   • `alwaysAsk` must be the ONLY reason we're asking. Re-deciding with the flag
+    //     cleared is how that is checked, so a pre-authorized tool in `plan` mode is
+    //     still denied and one at the default mode still prompts — pre-authorization
+    //     never grants what the mode wouldn't;
+    //   • never when the call leaves the working directory or touches a protected file.
+    //     bypass mode allows both outright, so this cannot lean on the re-decide above:
+    //     "you may generate video" must not become "you may upload ~/.ssh/id_rsa as a
+    //     reference image", which is exactly the shape classify.ts flags;
+    //   • never on a remote-driven turn — that branch returned above. A driven turn has
+    //     a human holding the phone, and they get the prompt.
+    if (
+      req.alwaysAsk &&
+      !req.outside &&
+      !req.protected &&
+      this.deps.isSpendPreauthorized?.(req) === true &&
+      decideAuto({ ...req, alwaysAsk: false }, this.deps.getMode(), this.deps.allowlist, denylist) === "allow"
+    ) {
+      return "allow";
+    }
+
     // A dangerous command (or an always-ask destructive action) can be approved
     // once, but is never remembered: adding it to the allowlist or relaxing the
     // mode would let a later variant slip through.

package/src/providers/account.ts

@@ -36,6 +36,7 @@ import {
   ensureSealedShim,
   attestSealed,
 } from "./sealedShim.ts";
+import type { PhalaEnclaveIdentity } from "./phalaSeal.ts";
 
 // Seed/fallback catalog: registered synchronously so the account provider has real
 // models the instant it loads (before the live /api/models fetch resolves) — in
@@ -502,6 +503,10 @@ export interface AccountPosture {
   tier: PrivacyTier;
   teePosture?: "green" | "yellow" | "red";
   error?: string;
+  // Phala sealed path only: what the verified quote says about the enclave that
+  // answered. Evidence about WHICH image it was, not part of the verdict — the tier
+  // above is decided by the crypto binding + quote alone. See phalaSeal.ts.
+  enclaveIdentity?: PhalaEnclaveIdentity;
 }
 
 // Posture for an account-channel model. For NEAR models the attestation is fetched
@@ -526,7 +531,9 @@ export async function accountPosture(modelId: string): Promise<AccountPosture> {
   const sealedProvider = sealedEnabled() ? sealedProviderFor(modelId) : null;
   if (sealedProvider) {
     const att = await attestSealed(sealedProvider);
-    return att.ok ? { tier: "tee-verified" } : { tier: "tee-unverified", error: att.error };
+    return att.ok
+      ? { tier: "tee-verified", enclaveIdentity: att.enclaveIdentity }
+      : { tier: "tee-unverified", error: att.error };
   }
   // Honest labelling for the non-NEAR enclaves when we are NOT sealing — sealed mode
   // explicitly disabled (PRIVATEER_SEALED=0), or on but the shim never came up. Tinfoil

package/src/providers/phala/measurements.ts

@@ -0,0 +1,170 @@
+// TDX measurement verification for the Phala ACI report — the layer above the quote
+// signature check in ../phalaSeal.ts.
+//
+// The quote proves genuine Intel silicon and binds the E2EE key we seal to. It does
+// NOT say which image answered. These are the checks that start to close that gap,
+// and they split into two kinds that must never be confused:
+//
+//   SELF-CONSISTENCY (gates, verified here from the report alone)
+//     - the event log replays to the RTMRs the hardware signed
+//     - sha256(app_compose) equals the compose-hash the log claims
+//     Both are checkable with no outside knowledge, so a failure means the report is
+//     malformed or doctored and we refuse it.
+//
+//   IDENTITY (evidence, NOT a gate)
+//     - is this the same image we saw last time?
+//     Phala publishes no registry of known-good measurements; expected MRTD/RTMR0-2
+//     are computed with dstack-mr from the reproducible dstack OS build. Until we do
+//     that, first contact is trust-on-first-use: we can detect that the image CHANGED,
+//     never that it is the RIGHT one. Reporting drift as a hard failure would be a
+//     false alarm on every legitimate upgrade; reporting first-sight as "verified"
+//     would be the overclaim. So it surfaces as its own state and moves no verdict.
+//
+// Verified against the live gateway 2026-08-17: all four RTMRs replay and the
+// compose-hash matches.
+
+import { createHash } from "node:crypto";
+
+// One entry of the dstack event log. `imr` selects the register it extends; `digest`
+// is what actually gets hashed in. `event`/`event_payload` are the human-readable
+// name and value (app-id, compose-hash, os-image-hash, …).
+export interface TdxEvent {
+  imr: number;
+  digest: string;
+  event?: string;
+  event_payload?: string;
+}
+
+// The app-layer values the IMR3 log names. Every one is a string we can pin.
+export interface PhalaAppIdentity {
+  appId?: string;
+  composeHash?: string;
+  osImageHash?: string;
+  instanceId?: string;
+  mrKms?: string;
+  keyProvider?: string;
+}
+
+export interface ReplayedRtmrs {
+  rtMr0: string;
+  rtMr1: string;
+  rtMr2: string;
+  rtMr3: string;
+}
+
+const RTMR_KEYS = ["rtMr0", "rtMr1", "rtMr2", "rtMr3"] as const;
+
+// The event log arrives as a JSON *string* inside evidence (not an array), so it has
+// to be parsed before anything can replay it. Lenient: a shape we don't recognise
+// yields [] and the caller decides — an absent log is a missing check, not a forgery.
+export function parseEventLog(raw: unknown): TdxEvent[] {
+  let value: unknown = raw;
+  if (typeof raw === "string") {
+    try {
+      value = JSON.parse(raw);
+    } catch {
+      return [];
+    }
+  }
+  if (!Array.isArray(value)) return [];
+  return value.filter(
+    (e): e is TdxEvent =>
+      !!e && typeof e === "object" && typeof (e as TdxEvent).imr === "number" && typeof (e as TdxEvent).digest === "string",
+  );
+}
+
+// Replay the hash chain each register accumulates: starting from 48 zero bytes,
+// rtmr = SHA384(rtmr ‖ digest) for every event extending that register, in log order.
+// Order is load-bearing — the same events in a different sequence give a different
+// register, which is exactly what makes the log unforgeable against a signed quote.
+export function replayRtmrs(events: TdxEvent[]): ReplayedRtmrs {
+  const out = {} as Record<(typeof RTMR_KEYS)[number], string>;
+  RTMR_KEYS.forEach((key, imr) => {
+    let acc = Buffer.alloc(48);
+    for (const ev of events) {
+      if (ev.imr !== imr) continue;
+      let digest: Buffer;
+      try {
+        digest = Buffer.from(ev.digest, "hex");
+      } catch {
+        continue;
+      }
+      acc = createHash("sha384").update(Buffer.concat([acc, digest])).digest();
+    }
+    out[key] = acc.toString("hex");
+  });
+  return out;
+}
+
+// The named app-layer values out of the IMR3 events.
+export function appIdentityFrom(events: TdxEvent[]): PhalaAppIdentity {
+  const byName = new Map<string, string>();
+  for (const ev of events) {
+    if (ev.imr === 3 && ev.event && typeof ev.event_payload === "string" && ev.event_payload) {
+      byName.set(ev.event, ev.event_payload);
+    }
+  }
+  return {
+    appId: byName.get("app-id"),
+    composeHash: byName.get("compose-hash"),
+    osImageHash: byName.get("os-image-hash"),
+    instanceId: byName.get("instance-id"),
+    mrKms: byName.get("mr-kms"),
+    keyProvider: byName.get("key-provider"),
+  };
+}
+
+// sha256 over the app-compose document exactly as shipped. Hashing a re-serialized
+// object would silently "fix" any difference in key order or whitespace and match a
+// document that isn't the measured one, so a string is hashed verbatim.
+export function computeComposeHash(appCompose: unknown): string | undefined {
+  if (typeof appCompose !== "string" || !appCompose) return undefined;
+  return createHash("sha256").update(Buffer.from(appCompose, "utf8")).digest("hex");
+}
+
+export interface ConsistencyCheck {
+  name: string;
+  ok: boolean;
+  detail?: string;
+}
+
+// The self-consistency gates. `skipped` (no material to check) is reported as its own
+// outcome rather than silently passing — a check we did not run must never read as a
+// check that succeeded.
+export function checkReportConsistency(args: {
+  events: TdxEvent[];
+  quoted: ReplayedRtmrs;
+  appCompose: unknown;
+  identity: PhalaAppIdentity;
+}): { checks: ConsistencyCheck[]; ok: boolean; skipped: string[] } {
+  const checks: ConsistencyCheck[] = [];
+  const skipped: string[] = [];
+
+  if (args.events.length === 0) {
+    skipped.push("rtmr-replay");
+  } else {
+    const replayed = replayRtmrs(args.events);
+    for (const key of RTMR_KEYS) {
+      const ok = replayed[key] === args.quoted[key];
+      checks.push({
+        name: `rtmr-replay:${key}`,
+        ok,
+        detail: ok ? undefined : `replayed ${replayed[key].slice(0, 16)}… but the quote signed ${args.quoted[key].slice(0, 16)}…`,
+      });
+    }
+  }
+
+  const computed = computeComposeHash(args.appCompose);
+  if (!computed || !args.identity.composeHash) {
+    skipped.push("compose-hash");
+  } else {
+    const ok = computed === args.identity.composeHash;
+    checks.push({
+      name: "compose-hash",
+      ok,
+      detail: ok ? undefined : `sha256(app_compose)=${computed.slice(0, 16)}… but the log attests ${args.identity.composeHash.slice(0, 16)}…`,
+    });
+  }
+
+  return { checks, ok: checks.every((c) => c.ok), skipped };
+}