feat: add verifiable checkpoint provenance

Author: lcalderon

.planning/REQUIREMENTS.md

@@ -143,6 +143,15 @@
 - [x] **RECOLLECT-06**: Operator/NOC surfaces expose recent recollection decisions, skipped-search reasons, false-positive rate, and the downstream answer/tool step that used or ignored injected memory.
 - [x] **RECOLLECT-07**: Recollection and context-pack receipts label each memory item by belief stage: bronze raw source snapshot, silver candidate claim, or gold admitted operational truth; agents may rely on gold directly, must caveat silver, and may use bronze only as source evidence unless promotion policy admits it.
 
+## PROV Verifiable Action Provenance + Tamper-Evident Audit (Proposed)
+
+*Source: 2026-07-01 external developer question (Arden) on crash-consistent, auditable "proof" linking agent output to consumed memories and tools. See ROADMAP.md Backlog item 18.*
+
+- [ ] **PROV-01**: Provenance is captured at the read/tool-call boundary (which memories were read, which tools/commands ran, with source id + hash) rather than self-reported by the agent at checkpoint time, so every output carries a verified set of consumed inputs.
+- [ ] **PROV-02**: The audit entry for a significant action is written inside the same database transaction as the action itself, so the action and its audit row commit or fail together and rows cannot be silently dropped; the current "audit never breaks the primary action" contract is preserved or explicitly redesigned.
+- [ ] **PROV-03**: Audit entries are hash-chained (each row references the prior row's hash) so tampering, deletion, or gaps in the trail are detectable, with a verification path that reports the first broken link.
+- [ ] **PROV-04**: On crash/restart, the resumed checkpoint plus the transactional audit chain reconstruct a verifiable trail with no unaccounted actions between the last checkpoint and the crash; verification work stays off the hot path and provenance receipts expose no raw sensitive payloads.
+
 ---
 
 ## Future Requirements (Bounded Spikes Complete; Adoption Deferred)

.planning/ROADMAP.md

@@ -538,6 +538,13 @@ Full archive: `.planning/milestones/v1.7-ROADMAP.md`
    - Requirements: `UX-FOLLOWUP-07` and `INSTALL-FOLLOWUP-01` in `.planning/REQUIREMENTS.md`.
    - Goal: make service health and ownership visible from the UI, then preserve Docker as an explicit optional test/demo path instead of letting local containers, images, or demo volumes become the default operator footprint.
 
+18. **P1 — Plan Verifiable Action Provenance + Tamper-Evident Audit.**
+   - Source signal: 2026-07-01 external developer question (Arden) on whether agent action "proof" — binding an output to the memories it consumed and tools it used — stays consistent and auditable across crashes/restarts. Current state does not enforce this: `provenancePointers` are agent-supplied and pass straight through (`apps/memroos/src/app/api/agent-checkpoints/route.ts`), and `writeAuditLog` is fire-and-forget and never throws (`apps/memroos/src/lib/audit.ts`), so rows can drop silently.
+   - Related backlog: overlaps the P1 Harness Control Plane evidence-bundle work (item 5) and the "Universal evidence bundles" / "Audit/HIL hardening: hash chaining" Later Ideas; this item is the integrity/consistency slice of that surface.
+   - Requirements: `PROV-01..04` in `.planning/REQUIREMENTS.md`.
+   - Goal: move provenance from honor-system to enforced — capture consumed memories/tools at the read/tool-call boundary rather than self-report, write the audit entry in the same transaction as the action so they commit or fail atomically, and hash-chain audit entries so gaps or edits are detectable; on crash/restart the resumed checkpoint reconstructs a verifiable trail.
+   - Gate: the availability contract that audit failures must not break the primary action must be preserved or explicitly redesigned; no heavy verification work on the hot path; no raw sensitive payloads exposed in provenance receipts.
+
 ### Later Ideas
 
 - [ ] HIL edit-and-continue semantics (modify task state before resuming graph)

AGENTS.md

@@ -7,7 +7,7 @@ This version has breaking changes — APIs, conventions, and file structure may
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **memroos** (16021 symbols, 30129 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **memroos** (16216 symbols, 30433 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
 > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
 

CLAUDE.md

@@ -3,7 +3,7 @@
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **memroos** (16021 symbols, 30129 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **memroos** (16216 symbols, 30433 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
 > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
 

apps/memroos/src/__tests__/proxy.test.ts

@@ -78,6 +78,18 @@ describe("proxy", () => {
     expect(await response.json()).toEqual({ error: "authentication required" });
   });
 
+  it("lets runtime health respond without a session token", async () => {
+    const response = await proxy(
+      new NextRequest("http://localhost:3002/api/health", {
+        method: "GET",
+        headers: { host: "localhost:3002" },
+      })
+    );
+
+    expect(response.status).toBe(200);
+    expect(await response.text()).toBe("");
+  });
+
   it("lets agent onboarding bootstrap routes handle their own signed-token authorization", async () => {
     const scriptResponse = await proxy(
       new NextRequest("http://localhost:3002/api/onboarding/script?token=signed-token", {

apps/memroos/src/app/api/agent-checkpoints/__tests__/route.test.ts

@@ -1,10 +1,28 @@
 // @vitest-environment node
-import { describe, expect, it } from "vitest";
+import Database from "better-sqlite3";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { initSchema } from "@/lib/db-schema";
+
+let db: Database.Database;
+
+vi.mock("@/lib/db", () => ({
+  getDb: () => db,
+  closeDb: () => {},
+}));
 
 const checkpointsRoute = await import("../route");
 const metricsRoute = await import("../metrics/route");
 
 describe("/api/agent-checkpoints", () => {
+  beforeEach(() => {
+    db = new Database(":memory:");
+    initSchema(db);
+  });
+
+  afterEach(() => {
+    db.close();
+  });
+
   it("blocks direct non-local checkpoint writes without operator authorization", async () => {
     const req = new Request("https://memroos.example.com/api/agent-checkpoints", {
       method: "POST",

apps/memroos/src/lib/__tests__/agent-checkpoints.test.ts

@@ -2,8 +2,14 @@
 import Database from "better-sqlite3";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
-import { createAgentCheckpoint, resumeFromCheckpoint, getCheckpointMetrics } from "@/lib/agent-checkpoints";
+import {
+  createAgentCheckpoint,
+  getCheckpointMetrics,
+  resumeFromCheckpoint,
+  verifyCheckpointAuditChain,
+} from "@/lib/agent-checkpoints";
 import { initSchema } from "@/lib/db-schema";
+import { recordEfficiencyEvent } from "@/lib/efficiency-telemetry";
 
 let db: Database.Database;
 
@@ -61,4 +67,130 @@ describe("agent lightweight checkpoint/resume", () => {
     expect(metrics.avgWriteLatencyMs).toBeGreaterThan(0);
     expect(metrics.avgCheckpointSize).toBeGreaterThan(0);
   });
+
+  it("writes a checkpoint audit entry with verified boundary provenance receipts", () => {
+    const runId = "test-run-provenance";
+
+    recordEfficiencyEvent(db, {
+      eventType: "source_read",
+      taskId: runId,
+      agentId: "codex",
+      payload: {
+        sourceId: "README.md",
+        sourceHash: "sha256:readme",
+        toolId: "read_file",
+      },
+      createdAt: "2026-07-02T08:00:00.000Z",
+    });
+    recordEfficiencyEvent(db, {
+      eventType: "memory_write",
+      taskId: runId,
+      agentId: "codex",
+      payload: {
+        source: "agent_memory",
+        dedupHash: "sha256:memory",
+        firstSeenAt: "2026-07-02T07:59:00.000Z",
+        isRediscovery: false,
+      },
+      createdAt: "2026-07-02T08:01:00.000Z",
+    });
+
+    const checkpoint = createAgentCheckpoint(db, {
+      runId,
+      ownerAgentId: "codex",
+      objective: "Capture verified provenance",
+      nextSafeAction: "Resume from checkpoint",
+      provenancePointers: ["agent-supplied-pointer"],
+    });
+
+    expect(checkpoint.provenanceAudit).toMatchObject({
+      provenanceReceiptCount: 2,
+      previousEntryHash: null,
+    });
+    expect(checkpoint.provenanceAudit?.checkpointHash).toMatch(/^sha256:[a-f0-9]{64}$/);
+    expect(checkpoint.provenanceAudit?.entryHash).toMatch(/^sha256:[a-f0-9]{64}$/);
+
+    const row = db
+      .prepare("SELECT * FROM audit_entries WHERE event_type = 'agent.checkpointed' AND entity_id = ?")
+      .get(`agent_checkpoint:${checkpoint.id}`) as { metadata_json: string } | undefined;
+    expect(row).toBeDefined();
+
+    const metadata = JSON.parse(row!.metadata_json) as {
+      provenanceReceipts: Array<{ kind: string; sourceId: string; sourceHash: string }>;
+      legacyPointerCount: number;
+    };
+    expect(metadata.legacyPointerCount).toBe(1);
+    expect(metadata.provenanceReceipts).toHaveLength(2);
+    expect(metadata.provenanceReceipts.map((receipt) => receipt.kind).sort()).toEqual([
+      "memory_write",
+      "source_read",
+    ]);
+    expect(JSON.stringify(metadata.provenanceReceipts)).not.toContain("agent-supplied-pointer");
+
+    const resumed = resumeFromCheckpoint(db, "default-tenant", runId);
+    expect(resumed?.provenanceAudit?.entryHash).toBe(checkpoint.provenanceAudit?.entryHash);
+
+    expect(verifyCheckpointAuditChain(db, "default-tenant")).toMatchObject({
+      valid: true,
+      checked: 1,
+    });
+  });
+
+  it("rolls back the checkpoint insert when the transactional audit write fails", () => {
+    db.exec("DROP TABLE audit_entries");
+
+    expect(() =>
+      createAgentCheckpoint(db, {
+        runId: "test-run-rollback",
+        ownerAgentId: "codex",
+        objective: "Prove checkpoint audit atomicity",
+        nextSafeAction: "Retry after schema repair",
+      })
+    ).toThrow(/audit_entries/);
+
+    expect(db.prepare("SELECT COUNT(*) AS count FROM agent_checkpoints").get()).toEqual({
+      count: 0,
+    });
+  });
+
+  it("detects a broken checkpoint audit chain row", () => {
+    createAgentCheckpoint(db, {
+      runId: "test-run-chain",
+      ownerAgentId: "codex",
+      objective: "Create a valid checkpoint audit row",
+      nextSafeAction: "Insert forged audit row",
+    });
+
+    db.prepare(
+      `INSERT INTO audit_entries
+        (id, tenant_id, actor_id, actor_role, event_type, entity_type, entity_id, reason, metadata_json, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    ).run(
+      "forged-checkpoint-audit",
+      "default-tenant",
+      "codex",
+      "system",
+      "agent.checkpointed",
+      "agent_checkpoint",
+      "agent_checkpoint:forged",
+      "forged checkpoint audit row",
+      JSON.stringify({
+        schemaVersion: 1,
+        checkpointId: "forged",
+        runId: "test-run-chain",
+        checkpointHash: "sha256:forged",
+        previousEntryHash: "sha256:not-the-prior-row",
+        provenanceReceipts: [],
+        legacyPointerCount: 0,
+        entryHash: "sha256:not-a-real-entry-hash",
+      }),
+      "2026-07-02T08:02:00.000Z"
+    );
+
+    expect(verifyCheckpointAuditChain(db, "default-tenant")).toMatchObject({
+      valid: false,
+      checked: 2,
+      firstBrokenEntryId: "forged-checkpoint-audit",
+    });
+  });
 });