Status: counterexamples verified; the three source corrections are applied.
The application record 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. The dated verification receipt 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:
- Run ID.
- Root agent ID and version.
- Sorted completed-step IDs.
- Sorted intermediate-artifact IDs.
- Sorted output-bundle IDs.
- 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#
- Revalidate this review's source pin, current assembled slide hashes and draft fields. Inspect any intervening source/content changes before merging.
- 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.
- 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. - 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.
- 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.
- 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.