Run Manifests Give Long-Running Agents Durable Records

An agent completes a task. A user asks a reasonable question:

“Why did it do that?”

The team opens a trace. There are model spans, tool calls, retries, handoffs, timing information, error events, and perhaps several background workers. The trace is useful. It may not answer the question.

It can be too detailed to read, too incomplete to explain a policy decision, or too sensitive to keep as the long-term record. A raw transcript has the opposite problem: it may preserve every word while losing the bounded, structured facts an operator needs to inspect.

A trace tells you what activity was observed. A run manifest explains the accountable shape of the work.

Long-running agents need both. Observability data helps debug an individual execution. A durable run manifest makes the system explainable across restarts, handoffs, review, incident response, and later evaluation.

This is not an argument for storing more. It is an argument for preserving the right facts deliberately.

Three records, three jobs

Teams often call every retained artifact a “log.” That collapses different jobs into one database and produces the worst of each: noisy observability, missing evidence, and accidental retention of sensitive content.

One useful design is to keep three distinct records instead.

• Record: Trace — Primary job: Diagnose timing, path, errors, and dependencies — Typical shape: Fine-grained spans and events — Retention posture: Shorter lived; access controlled
• Record: Transcript — Primary job: Preserve conversational or tool interaction history when needed — Typical shape: Ordered raw or projected messages — Retention posture: Carefully bounded and redacted
• Record: Run manifest — Primary job: Explain the accountable scope and outcome of a run — Typical shape: Compact, stable, structured record — Retention posture: Retained according to the workflow's governing policy

The OpenAI Agents SDK trace model illustrates why traces are valuable: one workflow can contain turns, agent spans, generations, tool calls, handoffs, and guardrails. The OpenTelemetry GenAI semantic conventions, whose status remains under development, add a common vocabulary for conversations, tools, and model operations.

But those same telemetry conventions warn that input messages, system instructions, tool arguments, and tool results can contain sensitive information. A durable run record should therefore not default to copying all of them. The manifest should carry stable identifiers, meaningful summaries, content references, and explicit redaction policy—not a hidden second transcript.

The retention postures above are illustrative, not universal rules. Storage duration, access, redaction, and deletion should be set by the governing product, security, contractual, privacy, and legal policies for the workflow. A manifest format does not itself authorize keeping the underlying content.

A proposed six-part agent run manifest

Virillio Code Editorial proposes a manifest that is small enough to inspect and precise enough to challenge. The six-part structure below is an editorial design model, not an OpenTelemetry schema or established industry standard.

• Part: Intent — Question it answers: What legitimate goal initiated this work? — What belongs there: Task identifier, user-visible objective, success criteria, authority source
• Part: Decision context — Question it answers: What was the agent allowed to reason from? — What belongs there: Agent and policy version, model family or selection, context version, task constraints
• Part: Capability boundary — Question it answers: What could the agent observe or change? — What belongs there: Workspace or target scope, tool and permission policy version, approval requirements, resource budget
• Part: Execution ledger — Question it answers: What meaningful operations occurred? — What belongs there: Admission and effect identifiers, important state transitions, bounded tool-operation outcomes
• Part: Evidence — Question it answers: Why should anyone trust the outcome? — What belongs there: Tests, source references, artifact links, verification results, known gaps
• Part: Lifecycle — Question it answers: How should this record be interpreted and retained? — What belongs there: Started and settled timestamps, terminal state, relationship to later runs, retention and redaction policy

The manifest does not have to be cryptographically signed to be useful. “Manifest” here means a consciously designed, stable account of a run—not an implementation choice. Some systems will need hashes, signatures, or immutable storage; many will start with a durable structured record and well-defined access controls.

A compact sample field schema

This implementation-neutral sketch shows how the six parts can fit together. It is deliberately not a normative wire format.

AgentRunManifest {
  manifestVersion: string
  runId: string
  intent: { admissionId, objective, authorityRef, successCriteria[] }
  decisionContext: { agentPolicyVersion, modelClass, contextRefs[] }
  capabilityBoundary: { workspaceRef, toolPolicyVersion, approvals[], budgetRef }
  executionLedger[]: { operationId, effectId?, state, evidenceRef? }
  evidence: { artifactRefs[], verificationResults[], knownGaps[] }
  lifecycle: { startedAt, settledAt?, state, relatedRunIds[], retentionClass, redactions[] }
}

Fields that could expose prompts, tool payloads, user content, or credentials should normally be references or redacted summaries unless the governing policy explicitly calls for the raw value.

1. Intent: record the goal, not every word

The intent field should establish why the work was allowed to begin.

For a coding task, it might identify a ticket, a user-visible acceptance criterion, and a non-goal. For a research task, it might identify the question, evidence standard, and deadline. For a support workflow, it might identify the request class and the allowed response surface.

Avoid treating a full prompt as the durable intent by default. User messages can contain private information, incidental discussion, or outdated assumptions. A manifest should instead preserve:

• a durable task or admission identifier;
• a concise, reviewable objective;
• the authority that allowed the work to proceed;
• the constraints that make an outcome acceptable;
• a pointer to the original record when policy permits access.

This makes the goal inspectable without copying sensitive details into every monitoring sink.

It also prevents a common failure mode: an agent’s final summary sounds reasonable, but no one can tell which requirement it was actually trying to satisfy.

2. Decision context: make the run reproducible enough to reason about

An agent does not act only on a user request. It acts on an effective decision context:

• selected agent role and instructions;
• active policies and approval rules;
• model selection and configuration class;
• retrieved or loaded information;
• current workspace or domain context;
• applicable feature flags, budgets, and constraints.

This field should preserve versions and stable references where possible. It should not necessarily retain raw system instructions or all retrieved documents.

Think of the difference between “policy version 27 required approval for external writes” and pasting the entire policy text into every trace. The first supports accountability and comparison. The second creates duplication, privacy risk, and context noise.

The question is not “Can we replay every bit?” It is “Can a reviewer determine whether the agent was operating under the intended rules?”

3. Capability boundary: record what the agent could actually do

Two runs with the same model and prompt can mean very different things if one can read a repository, run tests, call a production API, or operate in a read-only sandbox while the other cannot.

The capability boundary turns those invisible differences into a first-class record:

• Boundary: Read scope — Examples to record: Repository revision, document collection, approved data source, target account or project
• Boundary: Write scope — Examples to record: Permitted output directory, allowed resource class, explicitly excluded paths
• Boundary: Execution scope — Examples to record: Allowed command classes, service environment, network rule, timeout or quota
• Boundary: Approval scope — Examples to record: Which effects required confirmation and whether that confirmation was obtained
• Boundary: Resource scope — Examples to record: Time, token, concurrency, and retry budget

This is not a recipe for granting broad authority. It is the evidence that a system kept authority narrow and made exceptions visible.

For a tool-using agent, a capability boundary is often more valuable than a model transcript. It lets an operator distinguish “the agent made a poor decision” from “the system gave the agent an unsafe or incomplete operating envelope.”

4. Execution ledger: record meaningful transitions, not every keystroke

The execution ledger is the compact bridge between a high-level intent and low-level telemetry.

It should include only state transitions that matter to outcome and recovery:

• Event: Intent accepted — Why it belongs in the manifest: Establishes that user work entered the durable system
• Event: Run started, paused, resumed, or transferred — Why it belongs in the manifest: Explains the lifecycle of long-running work
• Event: Approval requested and resolved — Why it belongs in the manifest: Shows where human authority shaped the run
• Event: External effect attempted — Why it belongs in the manifest: Makes consequential work visible
• Event: Effect confirmed, rejected, partial, or unknown — Why it belongs in the manifest: Prevents a timeout from being misreported as a clean failure
• Event: Verification completed — Why it belongs in the manifest: Links the claim of success to evidence
• Event: Terminal state selected — Why it belongs in the manifest: Explains whether the run succeeded, stopped, failed, or needs follow-up

Use identifiers to relate events to detailed traces. Do not force the manifest to duplicate every tool argument or raw result. A reviewer should be able to follow the story, then drill into a permissioned trace or artifact if the risk warrants it.

This supports a clean division of labor:

• traces answer “what happened inside this operation?”;
• a manifest answers “which operation mattered, and what did it mean for the task?”.

5. Evidence: make “done” a claim with support

The most important sentence in an agent record is usually “the task is complete.” It should never stand alone.

The evidence section should include the smallest proof package appropriate to the task:

• a targeted test result for a code change;
• a checked source list for research;
• a before-and-after state comparison for a data transformation;
• an approval receipt and confirmed effect state for an external action;
• an explicit explanation of unrun checks or remaining uncertainty.

This does not mean every task needs an elaborate report. It means a result should be connected to an observable basis.

For example:

• Claim: “The regression is fixed” — Evidence: Targeted test passed against the named snapshot — Caveat: Full suite not run
• Claim: “The report is ready for approval” — Evidence: Sources and draft artifact are attached — Caveat: No external delivery was attempted
• Claim: “The requested update was stopped” — Evidence: Cancellation was acknowledged and open effects were reconciled — Caveat: One external operation remains in an unknown state pending verification

The caveat is not a weakness. It is what makes the evidence usable.

6. Lifecycle: preserve time, relationships, and privacy boundaries

Long-running work outlives the process that first ran it. A manifest needs enough lifecycle information to survive that handoff:

• started, paused, resumed, and settled timestamps;
• terminal status and reason;
• parent, child, retry, or successor run identifiers;
• retention class and deletion deadline;
• fields redacted, omitted, or stored only as restricted references.

This is where a team decides what it is actually willing to remember.

An agent run that involved private source text, credentials, or user content should not become permanently searchable simply because it was observable during execution. OpenTelemetry’s guidance about sensitive GenAI attributes is a practical reminder: collection and durable retention are separate, policy-driven decisions.

The manifest must make that separation legible.

Build the manifest as the run proceeds

Do not ask a model to reconstruct a perfect manifest after the fact. A final narrative can omit the moment an approval changed the allowed action or an external effect became uncertain.

Anthropic’s long-running application-development harness offers related evidence that structured artifacts can preserve progress across sessions. For a run manifest, update the record at trustworthy boundaries:

1. When durable intent is accepted.
2. When the effective policy and capability boundary are resolved.
3. When an approval, handoff, or workspace transition changes the run’s meaning.
4. When a consequential effect begins or settles.
5. When verification produces evidence.
6. When the run reaches a terminal or explicitly resumable state.

The final human-readable summary can be derived from the manifest. The manifest should not depend on the summary being accurate.

Common anti-patterns

Treating the trace ID as the whole audit record

A trace identifier is a useful join key. It does not state the user goal, authorization boundary, effect semantics, or verification conclusion.

Persisting raw prompts and tool payloads everywhere

This makes debugging convenient until it creates a privacy, security, or retention problem. Persist deliberate references, redacted summaries, and explicit evidence instead.

Writing a final summary with no versioned context

“The agent fixed it” is not an accountable result if the reviewer cannot identify the workspace, policy, or verification basis.

Capturing every event but no terminal truth

An event sequence can show activity forever without establishing whether the user’s goal was satisfied, interrupted, or left in an unknown state.

Treating a run manifest as a billing report

Cost and duration matter, but they are not enough. A cheap run can be unsafe; an expensive run can still lack evidence.

How to evaluate run-record quality

Measure the record, not just the agent:

• Manifest completeness: What proportion of consequential runs contain intent, policy, effect, and evidence fields?
• Evidence coverage: How many terminal success claims have at least one relevant verification artifact?
• Unknown-outcome resolution: How often do uncertain effects become verified rather than silently retried?
• Privacy load: How much raw sensitive content is retained when an identifier or restricted reference would suffice?
• Incident reconstruction time: Can an operator explain a material run without reading an unbounded transcript?
• Cross-run comparability: Can a team tell whether two outcomes differed because of context, capability, environment, or execution?

These metrics help a platform mature without turning observability into surveillance.

A practical adoption path

1. Pick one consequential agent workflow.
2. Define its terminal states and which effects require evidence.
3. Add intent, policy, capability, effect, and evidence fields to a small structured record.
4. Link that record to traces and artifacts instead of copying their full contents.
5. Add a retention class and redaction review.
6. Review three successful runs and three messy ones with the same manifest template.
7. Expand only when the record reveals a real missing question.

The goal is not bureaucratic completeness. It is a record that makes a later human decision easier, safer, and more truthful.

What we are learning building Virillio Code

Virillio Code’s long-running session architecture is still in development, but it continues to reinforce a transferable principle: user-facing durable state and a live executor have different lifetimes. A durable run record should therefore preserve the accountable boundaries of work without pretending that one transient process or one verbose transcript is the whole truth.

The agent platforms that earn trust will not merely show activity. They will leave behind compact, privacy-aware evidence of what work was authorized, what happened, and what remains uncertain.

Sources and further reading

• Tracing — OpenAI Agents SDK — Agent traces can record model turns, tools, handoffs, guardrails, custom events, metadata, and grouped workflows.
• OpenTelemetry GenAI semantic conventions — The still-developing conventions define common attributes for agents, conversations, tools, and models, while warning that payload fields can contain sensitive data.
• Harness design for long-running application development — Structured artifacts help preserve progress and handoff context across long-running coding work.

Editorial disclosure

This article was substantially researched, drafted, and revised with AI through the Virillio Code editorial workflow. Virillio Code publishes the final text under its editorial byline, and the supporting primary sources are linked above.