What an Agent Harness Does — full narration

November 2 publication integration

The author confirmed the narration sounds good and explicitly waived an additional listening check on November 2, 2026. Automated structure, decoded-waveform pauses and source coverage are checked separately. No claim of assistant perceptual listening is made. The production cue plan lives at _tests/post-audio-sync/plans/what-an-agent-harness-does.json; its source digest covers the publication metadata and otherwise unchanged article text. Generate sync-v2.json from the actual Jekyll build using scripts/build_post_audio_sync.py before release.

The original draft reproduction notes below are retained as provenance, not as the publication status.

Draft-only narration, generated locally with Kokoro-82M v1.0 (kokoro-onnx), voice af_heart, language en-us, speed 0.98. No hosted speech API, credentials, paid calls, repository changes, or publication were used.

• Duration: 5:02 (302.529333 decoded seconds; MP3 container 302.592 seconds).
• Audio: 24 kHz mono MP3, 64 kbps; PCM master was normalized using loudnorm=I=-18:TP=-2:LRA=7 before encoding.
• Coverage: title, six section headings, and every body paragraph/list item, in 33 standalone chunks; 677 spoken words.
• Exclusions: audience/reading metadata, visual alt text, and figure captions. No reference footer is present in this revision. URLs are not spoken.
• Pronunciation: AI → A.I., CSV → C.S.V., README → read-me.
• Pauses: exactly 1.0 second before each heading (also before the title), 0.7 second after; 0.46 second between ordinary paragraphs; 0.16 second for outer sentence chunks if needed.
• Audio SHA-256: 2ee67c9edf88dd8fbfb10785bf02732791198314bdd7ff8553613eb4d4b1062c.
• Shared audio/sync cache token when sync is built: 2ee67c9edf88.

Completed checks

Every source speech segment matches the transcript and appears in generation order. All chunks are non-silent, finite and unclipped; no speaking-rate outliers occurred. The entire MP3 decodes successfully. All seven spoken title/heading boundaries have the exact silence in the PCM master and quiet center intervals in the decoded MP3. The full final sentence is retained, ending at 302.069333 seconds, followed by 0.46 seconds of silence. Four deliberately broken structure fixtures are rejected.

Limitations: these are automated checks, not an auditory review. No listening tool was available. Local Chromium playback could not launch because of environment restrictions; playback, seeking, speed controls, and site highlighting are not claimed verified. No site build or publication is included in these checks.

Synchronization and draft integration

annotated-body.md has 32 cue anchors; the theme’s existing page-title is the 33rd target. Do not duplicate the title as an article-body H1. cue-blocks.json records original visible text separately from speech pronunciation. narration-timeline.json records exact sample boundaries at 24,000 samples/second.

sync-plan.pending.json is deliberately not a production synchronization file. Its final draft source is already bound to SHA-256 d8e71c459a70717a104cc0e2b49de67dd0ed6eca1398280aa4834ccef0a09aac, and all 33 annotated targets match their original visible text. Build with the site’s normal Jekyll workflow and use scripts/build_post_audio_sync.py against the real rendered .page__content; that creates sync-v2.json with the correct complete-article text hash. Do not guess a rendered article hash from Markdown. Only then enable the audio_sync URL with the same version token as the MP3. Keep published: false and newsletter: false unless publication is separately authorized.

During a heading’s lead-in silence, the preceding cue stays highlighted; the heading cue begins at its actual sample start, and its body begins only after the post-heading gap. Clear the last cue at its speech end, before trailing silence.

Run the article-specific offline checks with:

python test_agent_harness_narration.py --audio-dir . --post /path/to/final-draft-post.md

The official site build, rendered-text sync builder, browser checks, mobile checks and listening review remain separate gates. An existing article’s tests do not prove this article passes.

Reproduce without an API

Use Python 3.12, FFmpeg/ffprobe, the exact versions in dependency-versions.json, and verified existing Kokoro files. Models are not embedded here. Model SHA-256: 7d5df8ecf7d4b1878015a32686053fd0eebe2bc377234608764cc0ef3636a6c5; voices SHA-256: bca610b8308e8d99f32e6fe4197e7ec01679264efed0cac9140fe9c29f1fbf7d.

python prepare_narration.py --source approved-source.md --output regenerated
ORT_DISABLE_TELEMETRY=1 python render_narration.py --output regenerated --models /path/to/models --voice af_heart --speed 0.98 --threads 4 --basename agent-harness-full-narration --max-seconds 0
python verify_boundaries.py regenerated

The renderer saves a 24-bit PCM master, per-chunk WAVs, transcript, manifest, timeline and signal checks. Timing always comes from generated sample counts. The retained approved-source.md is the exact narration source snapshot; media-only changes do not require re-narration, but any body edit does.