The Replay Bundle That Remembers What Happened

It's 2am. A customer complains about something an agent did. The next morning the CEO is already asking the only question that matters: did the agent do something it shouldn't have?

"I'm pretty sure our guardrails are solid" isn't an answer anyone wants to give the boss. It certainly won't fly with a customer, an auditor, or with legal. What they want is proof, and proof means being able to answer specifically: what did the agent try to do, on this exact run, and what happened when it tried?

If that answer lives in the timestamps of a few hundred servers and a half-dozen tool integrations, you don't have proof. You have a scavenger hunt. "Trust us, it's fine" does not survive a scavenger hunt.

Cognous' Open Control Stack exists to close that gap. It follows four steps: Declare → Control → Replay → Evidence.

• Declare: Agents need guardrails to tell them what they can and cannot do — that's a manifest, declared up front.
• Control: They need something enforcing those guardrails live — that's a control plane, deciding allow/block/escalate on every proposal in real time.

In this post, we'll cover Replay: no longer defining and patrolling the guardrails, but the receipts that the rails held. Taking what the Control Plane recorded during a run and turning it into one portable file — the thing you actually hand someone instead of a text file with pasted logs from a dozen systems.

What The Control Plane Hands Off

Picture a workflow mid-run: actions getting proposed, the gate deciding each one, live.

Now what? The Control Plane made the right calls in the moment — but how do you actually know that, after the fact, without having watched it happen live? That's the question Replay answers: it takes what already happened and turns it into something you can go back and inspect.

The Control Plane keeps a recorder running for the life of a run — that's what's actually holding the frame, the proposals, the decisions, the traces as they happen. At the end of the run, the recorder exports everything it captured as a replay bundle: one file you can store, ship, or hand off for later analysis.

bundle = recorder.generate_replay_bundle()
with open("run_bundle.json", "w") as f:
    f.write(bundle.model_dump_json(indent=2))

run_bundle.json is the full playback of the workflow — every decision, every trace, and the evidence behind the one blocked action, send_email, all in one place. It's exactly what you'd look at to understand an error, or hand over if there's a deeper investigation.

The Replay Tool

Agent Replay Bundle ships its own CLI, arb, for working with files like this one — validating, summarizing, redacting, signing. Start with validation, pointed at the bundle the Control Plane just exported:

$ arb validate run_bundle.json
Error: Replay bundle failed model validation: 1 validation error for AgentReplayBundle
bundle_id
  Field required [type=missing]

It fails immediately. The Control Plane's export calls the field replay_bundle_id; arb's schema — the AgentReplayBundle model that validate checks against — calls it bundle_id.

The Agent Replay Bundle is a public interchange format, meant for any system, and Agent Control Plane's internal run record shapes several of the schema terms differently than the Replay Bundle. Running validation means performing a mapping step between the two first — small, mostly renames:

mapped = {
    "bundle_id": run["replay_bundle_id"],
    "run_id": run["run_id"],
    "generated_at": run["generated_at"],
    "frame": run["frame"],
    "action_proposals": run["actions"],
    "policy_decisions": run["decisions"],
    "policy_traces": run["policy_traces"],
    "authority_records": run["authority_records"],
    "reliance_records": run["reliance_records"],
    "blocked_actions": run["blocked_actions"],
    "final_output": run["final_output"],
}

Run that, and the same run record now validates:

$ arb validate mapped_replay_bundle.json
VALID  bundle_id=ae564206-8daf-4b19-9d60-db54f56387a5  issues=2
  WARNING W005: Bundle has no authority records.
  WARNING W012: signature_metadata is missing.

Valid — with two warnings, not zero. Neither one blocks validity, and both are honest about the bundle's actual state: no authority was granted for this run (which is why two of the three actions didn't just allow), and nothing's been signed yet.

Worth building into your own pipeline: none of this runs automatically. generate_replay_bundle() builds the object; arb validate is a separate command a human has to think to run. Nothing stops a bundle from sitting unvalidated for months until the day someone actually needs it — which is the worst possible time to find out it doesn't pass. Wire the mapping and the validation into the end of every run, not into the moment an auditor asks for one.

What A Reviewer Sees First

arb summarize is the one-screen version — what you'd look at before deciding whether to open the full bundle:

$ arb summarize mapped_replay_bundle.json
bundle_id:          ae564206-8daf-4b19-9d60-db54f56387a5
run_id:             c3f474dd-952b-4f27-ab5c-98de868b3c67
status:             complete
actor:              support-agent-v1
environment:        production
policy_version:     v1.0
action_proposals:   3
policy_decisions:   3
policy_traces:      3
blocked_actions:    1
authority_records:  0
reliance_records:   1
final_output:       present
redacted:           no
signed:             no

Three proposals, three decisions, one block, zero authority records. That last number is the tell — it's the same fact the warning surfaced, now visible at a glance instead of buried in a rule name.

Redacting For Export

mapped_replay_bundle.json — the bundle we just validated — still has raw targets and payloads in it: customer IDs, draft email bodies, potentially PII. Fine for an internal review, not fine to hand to outside counsel.

Redaction isn't content-aware — it doesn't scan text and detect what looks sensitive. It replaces a fixed set of fields wholesale: payload (redacted by default), plus target and final_output if you opt in with flags. Everything structural — IDs, timestamps, decision results, policy names — is preserved no matter what:

$ arb redact mapped_replay_bundle.json --out redacted_bundle.json --targets --final-output
Redacted bundle written to redacted_bundle.json

"redaction_metadata": {
  "redacted": true,
  "redacted_at": "2026-08-18T19:47:34Z",
  "redacted_fields": [
    "action_proposals[0].payload",
    "action_proposals[0].target",
    "action_proposals[1].payload",
    "action_proposals[1].target",
    "action_proposals[2].payload",
    "action_proposals[2].target",
    "final_output"
  ],
  "replacement": "[REDACTED]"
}

A redacted bundle still validates clean — the whole point is that a reviewer can see what was blocked and why, without seeing the customer's actual email address.

Signing For Export Integrity

Once a bundle is ready to leave the building, sign it so anyone downstream can tell if it was altered in transit — the redacted version, since that's the one actually going out the door:

$ arb sign redacted_bundle.json --secret "demo-secret" --key-id "cognous-demo-key-01" --out signed_bundle.json
Signed bundle written to signed_bundle.json

$ arb verify signed_bundle.json --secret "demo-secret"
Signature VALID

$ arb verify signed_bundle.json --secret "wrong-secret"
Signature INVALID

That's HMAC-SHA256 over a canonical serialization of the bundle. Worth being precise about what it proves: it tells you the bundle hasn't changed since it was signed, given the secret. It does not prove who signed it — there's no identity binding, no PKI, no protection if the secret itself leaks. For production use, that's a job for a real key management system. For a shared-secret export check between two parties who already trust each other, HMAC does what it says.

Reading The Verified File

The auditor gets signed_bundle.json, runs verify, and knows immediately whether it matches what left your hands. Signing isn't encryption, though — verify is the only command that speaks the signed wrapper (signed_bundle_id, replay_bundle, signature_metadata). To actually read the run, pull the inner bundle back out first:

import json
with open("signed_bundle.json") as f:
    signed = json.load(f)
with open("extracted.json", "w") as f:
    json.dump(signed["replay_bundle"], f, indent=2)

Now extracted.json is a plain AgentReplayBundle again — summarize, validate, everything else works on it. Verify first, extract second: confirm nothing's been tampered with before you trust a single field inside it.

The signature also doesn't prove anything about the gap between when the run happened and when you got around to signing it. signed_at is just whatever time you ran the sign command — there's no check against generated_at. A bundle that sits unsigned for three days is three days an editor could have touched the file with no trace of it; sign it on day three, and verify comes back clean regardless. The signature only covers the window it's actually been alive for. So the real answer isn't "sign it before you send it" — it's validate, redact, and sign as part of the run itself, the moment the bundle is generated, so there's no gap for anything to slip into.

Proving The Guardrails Held

Back to that morning-after meeting: the complaint, and the question from the boss. What was once a stressful scavenger hunt across servers matching timestamps and logfiles is now just opening one file.

Agentic runs get their guardrails from two layers: a manifest declaring what's allowed, and a control plane enforcing that live. Replay is the layer that lets your team prove those guardrails actually held — turning what the control plane recorded into one validated, signed file anyone can check independently, long after the run itself is over.

Clone Agent Replay Bundle and try arb against the example bundles in the repo, or your own control plane exports.

Learn more about Agent Replay Bundle at cogno.us.