# Agentic run records and recovery: source review

Status: **counterexamples verified; the three source corrections are applied**.
The [application record](../authoring/agentic-source-application.json) binds the
reviewed content and preserves the historical proposal at commit `7167e08ce5`.
Rendering, narration and reader acceptance require their separate current
checks. This review does not accept the current Agentic Studio guide. Its
remaining registry, invocation, governance, grants, handoff, isolation, mode and
pipeline explanations need their own source review. No source-unit teaching
assignment is added by this document.

Source pin: `1ceae52c7896a59ac74a4429d410f3218f0b91c6`. Primary evidence is
`libs/oshun/agentic-studio/src/runs/{agent-run,checkpoint,run-controls,replay,streaming-progress}.ts`.
The existing `runs.test.ts` suite and the new
`tools/presentations/tests/pinned-agentic-recovery.test.mjs` execute the
relevant functions. The feature page is useful context, but several of its broad
claims are narrower in code. Do not copy those claims into reviewed
explanations.

## Corrections that must precede guide acceptance

| Current slide            | Problem                                                                                                                                              | Required correction                                                                                                                                |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agents-lifecycle`       | General terminal-guard wording hides the different fork/retry contracts and can make these helpers sound like a scheduler or authorization boundary. | Distinguish ordinary resume from a new attempt; explain suffix-based retry, caller validation and each actual guard.                               |
| `agents-checkpoints`     | “Matching snapshot” / “mutated envelope” wording overstates a selected-field serialization; the narrative omits the unenforced resume budget.        | Name the compared fields, include unchanged-ID/changed-content and zero-budget counterexamples, and separate returned state from durable recovery. |
| `agentic-studio-failure` | The title implies resume requires remaining budget; “envelope changed” overstates what the comparison rejects.                                       | Remove the implied budget gate and full-envelope integrity claim; retain the need for current authority, verified storage and restart evidence.    |

The exact proposed text and source references are in
[the pending replacements](agentic-run-recovery-corrections.json). The dated
[verification receipt](../verification/agentic-recovery-source-review-2026-09-07/README.md)
binds the current assembled slide hashes, source bytes, tests and draft.
Applying the draft requires rechecking those hashes; do not overwrite a newer
editorial revision blindly.

Visual thesis: keep the cream, ink and terracotta reading plane; make the
comparison's limited scope the dominant idea, without depicting a checkpoint as
a seal of trust.

Content plan: retain the lifecycle vocabulary; contrast the checkpoint helper's
actual checks with caller obligations; finish with a changed-artifact worked
case. Keep detail in natural explanatory narration and exact source excerpts.

Interaction thesis: preserve existing navigation, source disclosure and
reduced-motion-aware transitions. The checkpoint comparison must stand alone in
static HTML/PDF; no new motion or interaction is needed to understand it.

The checkpoint draft uses an existing table treatment because the rows describe
independent boundaries, not a four-stage execution chain. This is a proposed
treatment, not a reviewed visual benchmark. Real embedded/mobile table fit,
reading order, all text preservation and PDF legibility remain unverified.

## What the checkpoint functions actually establish

`takeCheckpoint` records the last completed step **in plan-array order**, not
the most recent completion timestamp. It keeps the intermediate-artifact array
by reference. `readonly` types do not deeply freeze or persist its contents.
`resumeBudgetUnits`, checkpoint identity and time are supplied by the caller;
this function does not validate them.

`fingerprintEnvelope` joins these six groups into a string:

1. Run ID.
2. Root agent ID and version.
3. Sorted completed-step IDs.
4. Sorted intermediate-artifact IDs.
5. Sorted output-bundle IDs.
6. Total cost units.

The serialization is not a cryptographic hash and does not escape identifier
delimiters. Two different identifier arrays can therefore serialize equally.
More routinely, it omits the tenant, input payload, step descriptions,
step-agent assignments and dependencies, tool calls, artifact content
fingerprints and persistence keys, bundle membership, evidence and individual
resource dimensions. “The envelope is unchanged” is not an inference supported
by equal strings.

`resumeFromCheckpoint` first compares run IDs, then that string. A run-ID
mismatch yields `unknown-checkpoint`; this does not look up a checkpoint in a
store. A different recomputed serialization yields `fingerprint-mismatch`. It
does not consult the checkpoint ID, recorded last step, artifact manifest,
checkpoint time or resume budget. Zero, negative and nonfinite supplied budgets
can pass this local helper. This does not establish that a separate deployed
admission boundary would permit execution.

On success, completed step objects are preserved; all non-completed statuses,
including `failed` and `skipped`, become `pending` with cleared step timestamps.
The returned envelope becomes `queued`. Terminal inputs are accepted, and the
old envelope completion timestamp is not cleared. No queue call, object-store
read, content verification or grant resolution occurs here.

`preservePartialOutputs` appends a `<runId>.partial` bundle for failed,
cancelled or killed runs with intermediate artifacts. Otherwise it returns the
existing output array. It does not mutate the input envelope or persist an
artifact. Passing its returned outputs back into another call can append a
duplicate bundle ID; preservation is not an idempotent storage transaction.

## A worked case to teach before discussing recovery readiness

Use a clearly labeled controlled example: run `run-1` has completed an outline
step, produced `artifact-1`, and recorded 12 cost units. Its checkpoint records
a zero resume budget. Change `artifact-1`'s content fingerprint and object-store
key without changing its ID.

The local comparison still matches and returns a queued envelope. That result
does **not** mean the revised content was verified, the budget admitted another
call or the original objects were restored. A caller needs separate authority,
artifact-integrity, admission, persistence and dispatch evidence. Conversely,
changing the run ID rejects with `unknown-checkpoint`; changing a compared
artifact ID or total cost rejects with `fingerprint-mismatch`. The contrast
teaches exactly what a successful comparison says, rather than making success
sound meaningless or universally safe.

This example is executed against the pinned helper, not a production incident or
a live tenant recovery. No provider, network, credentials or object store is
used by the probes.

## Control contracts: do not imply one universal terminal guard

`pause` accepts queued, starting, running, awaiting-tool and
awaiting-branch-selection. It rejects terminal runs explicitly; paused and
awaiting-approval have their own invalid-status result. Ordinary `resume`
accepts only paused. `cancel` and `kill` reject terminal inputs, then record
distinct cancelled/killed outcomes and completion times.

`fork` and `retryWithChanges` do not reject terminal inputs. Fork checks only
that the supplied ID differs from the source ID; it does not check nonblankness
or reserve a globally unique ID. It queues the copied envelope and records the
parent, retaining all existing plan states, artifacts, calls and cost. The fork
audit uses the parent's run ID. Caller-side validation is essential before
calling this a legitimate new run.

Retry locates the chosen step in the array, then resets that suffix. It does not
compute graph descendants: a later independent step is reset, while an earlier
dependent entry is untouched. Supplied step overrides can change agent and
dependency fields; status and step timestamps are subsequently forced to
pending/null. Existing calls, artifacts, outputs and costs remain. These are
transformation rules, not permission to reuse effects or widen authority.

`chooseBranch` requires the waiting status and an existing step ID, even if that
step is already completed; it records the choice in the rationale and returns
running without modifying the plan. It does not evaluate the separate branch
policy. `operatorStep` advances the first pending entry from paused and returns
running, without validating dependency readiness. A second step requires another
appropriate transition. None of these pure controls authenticates its supplied
actor or requires a nonblank rationale; app/operator policy is a separate layer.

## Further learning material required, beyond the three corrections

The following mechanisms deserve focused implementation explanations, not an
expanded claim that the current fourteen-slide overview already teaches them.
These proposed learning outcomes do not set a final guide or slide-count cap.

| Learning outcome                                          | Evidence-backed distinction                                                                                                                                              | Worked task                                                                                    |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| Interpret run accounting                                  | Measured usage attributes cost plus tokens, GPU/voice/avatar time, retrievals, external calls and storage; the legacy call helper increments external-call count by one. | Compare a measured local call with legacy accounting; explain what the counters actually mean. |
| Choose a recovery operation                               | Pause/resume, fork, retry and checkpoint recovery have different guards and preservation behavior.                                                                       | Predict retained effects and reset steps before selecting an operation.                        |
| Read replay without mistaking it for a full snapshot      | Timeline entries retain referenced records. Historical projection rewinds selected collections, not the entire envelope.                                                 | Stop at time 25 and identify data that still reflects a later result.                          |
| Separate customer narrative from subscriber authorization | Subscriber filtering checks run, tenant and visibility. Customer summarization only filters visibility and sorts sequence.                                               | Scope a mixed event collection before presenting any customer narrative.                       |
| Validate progress-log inputs                              | Append compares the last event's tenant/run and sequence; it does not validate the whole history or typed input shape.                                                   | Contrast an increasing valid sequence with malformed or mixed earlier history.                 |

For replay specifically, calls are included by **start time**, and their later
completion/outcome/result fields are retained. A cutoff does not rewind cost,
evidence or the envelope's completion timestamp. Plan entries with a completion
timestamp at or before the cutoff are preserved regardless of their status;
other started entries become running, later entries pending. Artifact/output
timestamps use inclusive bounds. The latest supplied applicable status event is
chosen without filtering its tenant or run. Callers must supply a correctly
scoped collection; the helper is neither an authorization boundary nor a full
event-sourced reconstruction.

For progress, `shouldDeliverToSubscriber` enforces the run match even for a
platform operator. Other roles also require a tenant match, then the appropriate
visibility tier. `summarizeForCustomer` has no subscriber argument; passing
mixed tenants/runs can expose their customer-visible messages together. Append
accepts sequence gaps, compares only the last existing record and permits an
empty log's first supplied value without a finite/nonnegative validation pass.
The new tests deliberately distinguish these functions' responsibilities.

## Source units are still awaiting substantive teaching

The affected `V1/features/agentic-registry-jobs-plans.md` units remain
unassigned; source-review notes and executable probes are not slide assignments.

| Unit ID                    | Section                           | What remains                                                                             |
| -------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------- |
| `023a9ac2ae791fed9a4bb403` | AgentRunEnvelope                  | Reconcile the fuller code record, optional redacted telemetry and result/effect fields.  |
| `8c484761022155aa472f3999` | Run cost ledger                   | Teach both accounting helpers and the storage dimension, without inferring actual usage. |
| `e1968ba8a5efcef95fd4f27b` | Run-status enum                   | Correct the broad universal-control-guard implication.                                   |
| `03513316ef2f93abe2feb2f2` | Checkpoint/resume/partial outputs | Apply the bounded comparison and recovery corrections above.                             |
| `3d3d0ac0f0d99b4da235a8b3` | Streaming progress                | Teach subscriber checks separately from summary and append helpers.                      |
| `74f015a044313ae18b415beb` | Run controls                      | Explain precise guards, suffix retry, preservation and caller obligations.               |
| `74bd80aaf786d69fe577a0a5` | Replay                            | Replace a full historical-state inference with the actual partial projection.            |

## Apply and verify after the active narration inputs are stable

1. Revalidate this review's source pin, current assembled slide hashes and draft
   fields. Inspect any intervening source/content changes before merging.
2. Apply the three pending patches deliberately. Preserve stable IDs and the
   remaining guide explanations; do not copy this draft into the live catalog
   without source, editorial and composition review.
3. Rebuild scripts and preview artifacts. Re-render the three changed tracks,
   invalidating their old speech fingerprints. None of these, including
   `agentic-studio-failure`, was current in the original 177-track baseline.
   Preserve all 177 without an exception. This corrects the original review's
   mistaken membership claim; retain its receipt as historical evidence.
4. Run the new pinned probes, relevant existing package tests, full applicable
   presentation tests, source/citation freshness and narration decode/pause
   checks. Added code citations will also require repository/workflow inventory
   input-hash refreshes where their bound citation index changes.
5. Run the full Agentic Studio standalone checks, affected embedded center/table
   checks, actual-audio controls and PDF rendering. Inspect actual-size captures
   and complete the natural-speed listening/editorial pass. None is supplied by
   this source-only receipt.
6. Add reviewed source-unit assignments only after the final slides genuinely
   explain those units. Then publish the verified corrections and update this
   pending review, counts and evidence. Do not accept the old guide merely
   because its audio becomes mechanically current.
