diff --git a/.abcd/config/identity.json b/.abcd/config/identity.json
index 9070b87..e546977 100644
--- a/.abcd/config/identity.json
+++ b/.abcd/config/identity.json
@@ -1,4 +1,4 @@
 {
-  "name": "Alex Reppel",
+  "name": "REPPL",
   "email": "77722411+REPPL@users.noreply.github.com"
 }
diff --git a/.abcd/docs-lint.json b/.abcd/docs-lint.json
index 77becfe..5581741 100644
--- a/.abcd/docs-lint.json
+++ b/.abcd/docs-lint.json
@@ -1,15 +1,15 @@
 {
   "roots": ["docs", "README.md"],
   "banned_tokens": [
-    {"id":"present_tense/previously","pattern":"(?i)\\bpreviously\\b","severity":"blocker","allow_context":["(?i)<!--\\s*docs-lint:\\s*allow\\b"],"message":"change-narration in a doc body; user-facing docs describe the present state only (version control holds the history). Rephrase, or add <!-- docs-lint: allow --> if this genuinely describes something external."},
-    {"id":"present_tense/formerly","pattern":"(?i)\\bformerly\\b","severity":"blocker","allow_context":["(?i)<!--\\s*docs-lint:\\s*allow\\b"],"message":"change-narration in a doc body; user-facing docs describe the present state only (version control holds the history). Rephrase, or add <!-- docs-lint: allow --> if this genuinely describes something external."},
-    {"id":"present_tense/to-be-implemented","pattern":"(?i)\\bto be implemented\\b","severity":"blocker","allow_context":["(?i)<!--\\s*docs-lint:\\s*allow\\b"],"message":"future-facing phrasing in a doc body; user-facing docs describe the present state only. Rephrase, or add <!-- docs-lint: allow --> if this genuinely describes something external."},
-    {"id":"present_tense/will-be-added","pattern":"(?i)\\bwill be (added|implemented|introduced)\\b","severity":"blocker","allow_context":["(?i)<!--\\s*docs-lint:\\s*allow\\b"],"message":"future-facing phrasing in a doc body; user-facing docs describe the present state only. Rephrase, or add <!-- docs-lint: allow --> if this genuinely describes something external."},
-    {"id":"present_tense/has-been-replaced","pattern":"(?i)\\b(has|have|had)\\s+been\\s+replaced\\b","severity":"blocker","allow_context":["(?i)<!--\\s*docs-lint:\\s*allow\\b"],"message":"change-narration in a doc body; user-facing docs describe the present state only (version control holds the history). Rephrase, or add <!-- docs-lint: allow --> if this genuinely describes something external."},
-    {"id":"present_tense/renamed-from","pattern":"(?i)\\brenamed from\\b","severity":"blocker","allow_context":["(?i)<!--\\s*docs-lint:\\s*allow\\b"],"message":"change-narration in a doc body; user-facing docs describe the present state only (version control holds the history). Rephrase, or add <!-- docs-lint: allow --> if this genuinely describes something external."},
-    {"id":"present_tense/no-longer","pattern":"(?i)\\bno longer\\b","severity":"warn","allow_context":["(?i)<!--\\s*docs-lint:\\s*allow\\b"],"message":"possible change-narration; if this states present reality (e.g. 'wait no longer than'), ignore, otherwise rephrase to present tense. Advisory because it collides with legitimate present-state prose."},
-    {"id":"present_tense/deprecated","pattern":"(?i)\\bdeprecated\\b","severity":"warn","allow_context":["(?i)<!--\\s*docs-lint:\\s*allow\\b"],"message":"possible change-narration; documenting a currently-deprecated external interface is present reality, so this is advisory. Rephrase if it narrates a change to Testimony itself."},
-    {"id":"paths/absolute-home","pattern":"/Users/[A-Za-z0-9_.-]+/","severity":"blocker","allow_context":["(?i)<!--\\s*docs-lint:\\s*allow\\b"],"message":"an absolute local path in user-facing content; use a relative path or ~ instead."}
+    {"id":"present_tense/previously","pattern":"(?i)\\bpreviously\\b","severity":"blocker","successor":"present-tense phrasing","allow_context":["(?i)<!--\\s*docs-lint:\\s*allow\\b"],"message":"change-narration in a doc body; user-facing docs describe the present state only (version control holds the history). Rephrase, or add <!-- docs-lint: allow --> if this genuinely describes something external."},
+    {"id":"present_tense/formerly","pattern":"(?i)\\bformerly\\b","severity":"blocker","successor":"present-tense phrasing","allow_context":["(?i)<!--\\s*docs-lint:\\s*allow\\b"],"message":"change-narration in a doc body; user-facing docs describe the present state only (version control holds the history). Rephrase, or add <!-- docs-lint: allow --> if this genuinely describes something external."},
+    {"id":"present_tense/to-be-implemented","pattern":"(?i)\\bto be implemented\\b","severity":"blocker","successor":"present-tense phrasing","allow_context":["(?i)<!--\\s*docs-lint:\\s*allow\\b"],"message":"future-facing phrasing in a doc body; user-facing docs describe the present state only. Rephrase, or add <!-- docs-lint: allow --> if this genuinely describes something external."},
+    {"id":"present_tense/will-be-added","pattern":"(?i)\\bwill be (added|implemented|introduced)\\b","severity":"blocker","successor":"present-tense phrasing","allow_context":["(?i)<!--\\s*docs-lint:\\s*allow\\b"],"message":"future-facing phrasing in a doc body; user-facing docs describe the present state only. Rephrase, or add <!-- docs-lint: allow --> if this genuinely describes something external."},
+    {"id":"present_tense/has-been-replaced","pattern":"(?i)\\b(has|have|had)\\s+been\\s+replaced\\b","severity":"blocker","successor":"present-tense phrasing","allow_context":["(?i)<!--\\s*docs-lint:\\s*allow\\b"],"message":"change-narration in a doc body; user-facing docs describe the present state only (version control holds the history). Rephrase, or add <!-- docs-lint: allow --> if this genuinely describes something external."},
+    {"id":"present_tense/renamed-from","pattern":"(?i)\\brenamed from\\b","severity":"blocker","successor":"present-tense phrasing","allow_context":["(?i)<!--\\s*docs-lint:\\s*allow\\b"],"message":"change-narration in a doc body; user-facing docs describe the present state only (version control holds the history). Rephrase, or add <!-- docs-lint: allow --> if this genuinely describes something external."},
+    {"id":"present_tense/no-longer","pattern":"(?i)\\bno longer\\b","severity":"warn","successor":"present-tense phrasing","allow_context":["(?i)<!--\\s*docs-lint:\\s*allow\\b"],"message":"possible change-narration; if this states present reality (e.g. 'wait no longer than'), ignore, otherwise rephrase to present tense. Advisory because it collides with legitimate present-state prose."},
+    {"id":"present_tense/deprecated","pattern":"(?i)\\bdeprecated\\b","severity":"warn","successor":"present-tense phrasing","allow_context":["(?i)<!--\\s*docs-lint:\\s*allow\\b"],"message":"possible change-narration; documenting a currently-deprecated external interface is present reality, so this is advisory. Rephrase if it narrates a change to Testimony itself."},
+    {"id":"paths/absolute-home","pattern":"/Users/[A-Za-z0-9_.-]+/","severity":"blocker","successor":"a repo-relative path or ~","allow_context":["(?i)<!--\\s*docs-lint:\\s*allow\\b"],"message":"an absolute local path in user-facing content; use a relative path or ~ instead."}
   ],
   "rules": {
     "links_resolve": {"enabled": true, "severity": "blocker"},
diff --git a/.abcd/work/CONTEXT.md b/.abcd/work/CONTEXT.md
index 1909af4..8ffe89d 100644
--- a/.abcd/work/CONTEXT.md
+++ b/.abcd/work/CONTEXT.md
@@ -16,7 +16,9 @@ request, then validate the answer into `findings.jsonl`) and `review`
 host-delegated: the CLI never calls a model, holds no keys, and adds no
 network dependency; every finding is born `unverified` and ingest is the sole
 validation boundary. Next is codebase mapping (itd-3), then Mode B / the
-pattern library (itd-4). Design in `docs/architecture.md`.
+pattern library (itd-4). Command and file contracts in
+[`../../docs/reference/cli.md`](../../docs/reference/cli.md) and
+[`../../docs/reference/session-directory.md`](../../docs/reference/session-directory.md).
 
 ## Live constraints / sharp edges
 
diff --git a/.abcd/work/DECISIONS.md b/.abcd/work/DECISIONS.md
index 5d54cff..4903325 100644
--- a/.abcd/work/DECISIONS.md
+++ b/.abcd/work/DECISIONS.md
@@ -244,3 +244,14 @@ Architecture-shaping decisions graduate to an ADR under
   silently recorded in the real mic's place; startRecorders logs the detected
   audio-input roster so a surprising default stays visible. NOTE: the avfoundation
   capture path is not exercised by CI — verify on macOS hardware before release.
+- 2026-07-29 — Bug-hunt round 8 (first loop round): four hunters, six
+  adversarial refuters, 21 confirmed findings (10 substantive, 11 nitpick),
+  5 candidates refuted. Headlines: transcribe resolves the audio offset
+  before the conversion mutates the session (a refused external run no
+  longer strands converted audio without its sidecar); install.sh installs
+  v0.4.0 and release.yml gates the pin against the tag; usage errors
+  uniformly exit 2; docs corrected against the code (installer prompts and
+  verification, endpoint caps, offset provenance, session file inventory,
+  AGENTS.md current state). The /dev/null TTY-gate nitpick is recorded but
+  unfixed (a true isatty check needs a dependency); the AGENTS.md fence's
+  dangling brief link is an upstream abcd defect, not fixable here.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5c663da..9d4a5cd 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -65,8 +65,8 @@ jobs:
 
       # The full pipeline against the bundled sample session: merge must produce
       # a timeline, report must render it, and both outputs must be non-empty.
-      # Runs on both OSes — it also proves the freshly built binary actually runs
-      # the pipeline on each host.
+      # Ubuntu-only, like the rest of this job — it also proves the freshly built
+      # binary actually runs the pipeline, not merely that it compiles.
       - name: Pipeline smoke test
         run: |
           set -euo pipefail
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index fea3f0c..ee551f1 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -39,7 +39,8 @@ permissions:
 
 jobs:
   # Gate the release on the pushed commit, mirroring ci.yml's check job (gofmt,
-  # build, vet, the race leg, and the pipeline smoke). A red step here aborts
+  # build, vet, the race leg, and the pipeline smoke) plus one release-only check:
+  # that install.sh's pinned version matches the tag. A red step here aborts
   # before anything is built or published. Checked out at github.sha — the commit
   # the pushed tag pointed at, never the default-branch tip or the re-resolvable
   # tag name — so the gate exercises exactly the commit whose tarballs will ship.
@@ -58,6 +59,31 @@ jobs:
           ref: ${{ github.sha }}
           persist-credentials: false
 
+      - name: Assert install.sh pins the released version
+        # install.sh carries a default VERSION= pin naming the release a one-line
+        # `curl … | sh` install fetches. Nothing else notices when a release moves
+        # on and the pin does not, and a stale pin hands every new user an old
+        # binary — or, once that old release predates build attestations, an
+        # install that dies in the gh verification step. This workflow pushes to no
+        # branch, so the pin cannot be corrected from here: the check only compares
+        # and fails, which forces the bump to land in the tagged commit itself,
+        # where install.sh must already name the version it installs. Plain string
+        # equality against the checked-out file. TAG arrives via env and is read as
+        # a shell variable, never interpolated into this script (injection-safe).
+        run: |
+          set -euo pipefail
+          pinned="$(sed -n 's/^VERSION="\(.*\)"$/\1/p' install.sh)"
+          if [ -z "$pinned" ]; then
+            echo "could not read the VERSION pin from install.sh (has the assignment moved?)" >&2
+            exit 1
+          fi
+          if [ "$pinned" != "$TAG" ]; then
+            echo "install.sh pins VERSION=\"$pinned\", but this release is $TAG." >&2
+            echo "Bump the pin in install.sh and re-tag: the tagged commit must name the release it installs." >&2
+            exit 1
+          fi
+          echo "install.sh pins $pinned, matching the released tag."
+
       - name: Set up Go
         uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6
         with:
diff --git a/AGENTS.md b/AGENTS.md
index 737b441..87e4e17 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -50,9 +50,15 @@ Testimony captures usability evidence, on the record.
 
 ## Current state
 
-Walking skeleton. A Go CLI (`testimony`) with the capture → merge → report
-pipeline working end-to-end on the bundled sample; `record` and `transcribe`
-are honest stubs. See [`docs/architecture.md`](docs/architecture.md).
+v0.4.0. A Go CLI (`testimony`, standard library only) whose seven pipeline
+commands are all implemented and dispatched from `internal/cli` behind the
+`cmd/testimony` entry point: `record` and `demo`
+(capture), `transcribe`, `merge`, `report`, and the analysis layer `analyze`
+and `review` — plus `version` and `help`. The model work is host-delegated —
+the CLI never calls a model, holds no keys, and adds no network dependency. The user-facing documentation
+is [`docs/README.md`](docs/README.md); the exact command and file contracts are
+[`docs/reference/cli.md`](docs/reference/cli.md) and
+[`docs/reference/session-directory.md`](docs/reference/session-directory.md).
 
 Orientation lives in [`.abcd/work/CONTEXT.md`](.abcd/work/CONTEXT.md).
 
diff --git a/docs/README.md b/docs/README.md
index 27b6134..58c3142 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,6 +1,6 @@
 # Testimony documentation
 
 - **[Tutorials](tutorials/getting-started.md)** — learn by doing: capture, transcribe, and report on your first session in about five minutes.
-- **[How-to guides](how-to/)** — recipes for specific tasks: [transcribe a recording](how-to/transcribe-a-recording.md), [instrument your own app](how-to/instrument-your-own-app.md).
+- **[How-to guides](how-to/)** — recipes for specific tasks: [transcribe a recording](how-to/transcribe-a-recording.md), [instrument your own app](how-to/instrument-your-own-app.md), [analyse a session](how-to/analyse-a-session.md).
 - **[Reference](reference/)** — exact descriptions of the [command line](reference/cli.md) and the [session directory](reference/session-directory.md).
 - **[Explanation](explanation/)** — background and reasoning: [how alignment works](explanation/how-alignment-works.md), [privacy](explanation/privacy.md).
diff --git a/docs/explanation/privacy.md b/docs/explanation/privacy.md
index 58a8eb7..e41e8fa 100644
--- a/docs/explanation/privacy.md
+++ b/docs/explanation/privacy.md
@@ -7,7 +7,7 @@ A think-aloud session captures two of the most sensitive things a person can han
 The rule is simple: **raw recordings stay local; only derived text is ever analysed.**
 
 - Your voice recording and any screen recording remain files on your machine. No part of the pipeline uploads them anywhere.
-- Speech recognition runs locally — the transcription engines execute on your own hardware, and the transcription step makes no network requests.
+- Speech recognition runs locally — the transcription engines execute on your own hardware, and no part of your session is sent anywhere. The one network request transcription can make is the engine fetching its own model files from their publisher the first time it needs them; your recording plays no part in it, and once the models are on disk the step runs offline.
 - The capture server listens on your machine and writes to a local session directory.
 - What the pipeline produces for analysis is derived text: the transcript, the normalised event stream, the merged timeline, and the report. These are small, readable files you can inspect line by line before sharing them with anyone — or with any analysis tool.
 
diff --git a/docs/how-to/instrument-your-own-app.md b/docs/how-to/instrument-your-own-app.md
index 871851f..dcad005 100644
--- a/docs/how-to/instrument-your-own-app.md
+++ b/docs/how-to/instrument-your-own-app.md
@@ -15,7 +15,7 @@ This creates a fresh session directory (with `manifest.json` anchoring the sessi
 | `POST /api/interactions` | one normalised interaction (a single JSON object) | `interactions.jsonl` (one line per request) |
 | `POST /api/events` | a batch of raw rrweb events (a JSON array) | `events.rrweb.jsonl` (one line per array element) |
 
-Both endpoints accept POST only (anything else returns 405), cap the body at 8 MiB, and return `204 No Content` on success. `/api/interactions` rejects invalid JSON with 400; `/api/events` rejects anything that is not a JSON array with 400.
+Both endpoints accept POST only (anything else returns 405) and return `204 No Content` on success. `/api/interactions` caps the body at 4 MiB — the readable JSONL line limit, since one request becomes one line — and rejects invalid JSON with 400; `/api/events` caps the batch body at 8 MiB and rejects anything that is not a JSON array with 400. A body over its cap gets 413, as does a batch element that would itself exceed the 4 MiB line limit.
 
 To defend the evidence against cross-origin forgery (CSRF) and DNS-rebinding, the write endpoints require `Content-Type: application/json`, a loopback `Host`, and — when present — a same-origin `Origin`. Post from your app's own origin (see the proxy in step 5) and always set the JSON content type, as the snippet below does. Each accepted body is re-encoded to a single line, so one request is always exactly one JSONL record.
 
diff --git a/docs/how-to/transcribe-a-recording.md b/docs/how-to/transcribe-a-recording.md
index d5e9744..eb8cc46 100644
--- a/docs/how-to/transcribe-a-recording.md
+++ b/docs/how-to/transcribe-a-recording.md
@@ -1,8 +1,28 @@
 # Transcribe a recording
 
-This guide covers the common `testimony transcribe` tasks: choosing an engine, transcribing other languages, tuning WhisperX, and correcting a wrong clock offset. All transcription runs locally; the recording never leaves your machine.
+This guide covers the common `testimony transcribe` tasks: transcribing the session's own recording or an external one, choosing an engine, transcribing other languages, tuning WhisperX, and correcting a wrong clock offset. All transcription runs locally; the recording never leaves your machine.
 
-Prerequisite for every variant: ffmpeg on your PATH (`brew install ffmpeg`). The command accepts `.m4a`, `.mov`, and `.wav` recordings and always writes a 16 kHz mono `audio.wav` into the session directory first.
+## Transcribe the session's own recording
+
+A session captured with `testimony record` already holds its voice recording as `audio.wav`, so name the session and nothing else:
+
+```sh
+testimony transcribe -session sessions/<dir>
+```
+
+The command reads that `audio.wav` in place: no conversion runs, and ffmpeg is not needed.
+
+## Transcribe an external recording
+
+When the voice was recorded separately — a `testimony demo` session with QuickTime Player alongside it, say — pass the file with `-audio`:
+
+```sh
+testimony transcribe -session sessions/<dir> -audio recording.m4a
+```
+
+This variant needs ffmpeg on your PATH (`brew install ffmpeg`). It accepts `.m4a`, `.mov`, and `.wav` recordings, converts the file into a 16 kHz mono `audio.wav` in the session directory, and persists the clock offset it works out beside it in `audio.offset.json`, so a later bare re-run keeps the same alignment.
+
+The recipes below use the bare form; add `-audio FILE` to any of them to transcribe an external recording instead.
 
 ## Choose an engine
 
@@ -13,7 +33,7 @@ By default (`-engine auto`) Testimony prefers WhisperX and falls back to whisper
 ```sh
 uv tool install whisperx        # or: pipx install whisperx
 
-testimony transcribe -session sessions/<dir> -audio recording.m4a -engine whisperx
+testimony transcribe -session sessions/<dir> -engine whisperx
 ```
 
 WhisperX produces word-level timestamps, which make the utterance-to-event join in reports precise. `-model` names a Whisper model; the default is `large-v3-turbo`.
@@ -23,7 +43,7 @@ WhisperX produces word-level timestamps, which make the utterance-to-event join
 ```sh
 brew install whisper-cpp
 
-testimony transcribe -session sessions/<dir> -audio recording.m4a -engine whispercpp
+testimony transcribe -session sessions/<dir> -engine whispercpp
 ```
 
 whisper.cpp needs a ggml model file. `-model` accepts either:
@@ -38,7 +58,7 @@ whisper.cpp needs a ggml model file. `-model` accepts either:
 - **A file path** to an existing ggml model, used as-is:
 
   ```sh
-  testimony transcribe -session sessions/<dir> -audio recording.m4a \
+  testimony transcribe -session sessions/<dir> \
     -engine whispercpp -model ~/models/ggml-base.en.bin
   ```
 
@@ -47,7 +67,7 @@ whisper.cpp needs a ggml model file. `-model` accepts either:
 Pass the spoken language code:
 
 ```sh
-testimony transcribe -session sessions/<dir> -audio recording.m4a -language de
+testimony transcribe -session sessions/<dir> -language de
 ```
 
 The default is `en`.
@@ -63,7 +83,7 @@ These three flags apply to WhisperX only.
 Example, forcing CPU with int8:
 
 ```sh
-testimony transcribe -session sessions/<dir> -audio recording.m4a \
+testimony transcribe -session sessions/<dir> \
   -device cpu -compute_type int8
 ```
 
@@ -79,12 +99,14 @@ If the report shows speech clearly misaligned with events, correct the offset us
 
 1. Find the "session start" utterance in `transcript.jsonl` and note its `t0` — call it `m`.
 2. If you said the marker at the moment the session began, it belongs at roughly 0 seconds, so the corrected offset is the printed offset minus `m`. Example: printed offset `+0.00`, marker at `t0: 12.40` → corrected offset `-12.4`.
-3. Re-run with the explicit value (an explicit `-offset` always wins over derivation):
+3. Re-run with the explicit value (an explicit `-offset` always wins over derivation). The bare form works whichever way the audio arrived, because the session already holds `audio.wav`:
 
    ```sh
-   testimony transcribe -session sessions/<dir> -audio recording.m4a -offset -12.4
+   testimony transcribe -session sessions/<dir> -offset -12.4
    ```
 
+   On a session whose audio came from an external recording, this rewrites the offset in `audio.offset.json`, so later bare re-runs keep the correction. On a `record` session there is no sidecar and the value applies to this run. Naming the recording again — `-audio recording.m4a -offset -12.4` — works too, at the cost of converting it a second time.
+
 4. Re-run `testimony merge` and `testimony report` to rebuild the timeline and report.
 
 See [how alignment works](../explanation/how-alignment-works.md) for why the offset exists.
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 07e977e..cd1bb94 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -12,7 +12,7 @@ Running `testimony` with no command, or with an unknown command, prints the usag
 |---|---|
 | 0 | success |
 | 1 | runtime error — the message is printed to stderr as `testimony: <error>` |
-| 2 | usage error or unknown command |
+| 2 | usage error — no command, an unknown command, an unparseable or invalid flag value, a missing required flag, or a flag combination that is not allowed |
 
 ## `testimony demo`
 
@@ -32,7 +32,7 @@ Behaviour: creates a new session directory named after the current time (`YYYY-M
 - `POST /api/interactions` — one JSON object per request, appended as one line of `interactions.jsonl`.
 - `POST /api/events` — a JSON array per request, each element appended as one line of `events.rrweb.jsonl`.
 
-Both accept POST only (405 otherwise), limit the body to 8 MiB, return 204 on success, and 400 on malformed bodies. The command blocks until interrupted (`Ctrl+C`).
+Both accept POST only (405 otherwise), return 204 on success, and 400 on malformed bodies. `POST /api/interactions` limits the body to 4 MiB — the readable JSONL line limit, since one request becomes one line — and `POST /api/events` limits the batch body to 8 MiB; a body over its limit is refused with 413, as is a batch element that would itself exceed the 4 MiB line limit. The command blocks until interrupted (`Ctrl+C`).
 
 ## `testimony transcribe`
 
@@ -56,9 +56,17 @@ testimony transcribe -session DIR [-audio FILE]
 | `-device` | `auto` | (whisperx) inference device: `auto`, `cpu`, or `cuda`. `auto` picks `cuda` only when an NVIDIA GPU is present, and never on macOS |
 | `-compute_type` | `auto` | (whisperx) compute type: `auto`, `int8`, `float16`, … . `auto` follows the device: `float16` on CUDA, `int8` on CPU |
 | `-vad` | `auto` | (whisperx) VAD method: `auto`, `silero`, or `pyannote`. `auto` picks `silero`; `pyannote` fails under newer torch versions |
-| `-offset` | derived | audio-to-session clock offset in seconds. When not given, derived from the recording's creation time minus the manifest's `t0_epoch_ms`; 0 when derivation is impossible |
+| `-offset` | derived | audio-to-session clock offset in seconds. When not given: with `-audio`, derived from the recording's creation time minus the manifest's `t0_epoch_ms`, or 0 when derivation is impossible; without it, read back from `audio.offset.json` when the session has one, else 0 |
 
-Behaviour: with `-audio`, requires ffmpeg on PATH and converts the recording to 16 kHz mono `audio.wav` in the session directory; without it (or when `-audio` points at the session's own `audio.wav`), it uses the existing `audio.wav` in place and skips the conversion. It then runs the engine, applies the offset, and writes `transcript.jsonl`. Always prints the offset it used and its provenance (`from -offset flag`, `derived: audio creation_time − manifest t0`, or `default 0: audio creation time unavailable`), then `transcribed N utterances → <path>`.
+Behaviour: with `-audio`, requires ffmpeg on PATH and converts the recording to 16 kHz mono `audio.wav` in the session directory; without it (or when `-audio` points at the session's own `audio.wav`), it uses the existing `audio.wav` in place and skips the conversion. It then runs the engine, applies the offset, and writes `transcript.jsonl`. Always prints the offset it used and its provenance — one of:
+
+- `from -offset flag` — the explicit flag, which always wins;
+- `derived: audio creation_time − manifest t0` — derived for an external recording;
+- `default 0: audio creation time unavailable` — an external recording whose creation time could not be read;
+- `persisted: audio.wav converted from an external recording (+3.20s)` — read back from `audio.offset.json`, the printed value being the persisted offset;
+- `default 0: session audio.wav captured at t0` — a session whose `audio.wav` was captured here and has no sidecar.
+
+It then prints `transcribed N utterances → <path>`. With `-audio`, the offset in force is written to `audio.offset.json`; without it, the sidecar is rewritten only when an explicit `-offset` is given and the session already has one. A later bare run reuses the persisted value.
 
 ## `testimony merge`
 
diff --git a/docs/reference/session-directory.md b/docs/reference/session-directory.md
index d36c656..473b344 100644
--- a/docs/reference/session-directory.md
+++ b/docs/reference/session-directory.md
@@ -4,11 +4,12 @@ Every capture session lives in one directory (by default under `sessions/`):
 
 ```
 sessions/<timestamp>/
-  manifest.json        # session metadata, including t0_epoch_ms (written by demo)
-  audio.wav            # 16 kHz mono ASR input (written by transcribe; local only)
+  manifest.json        # session metadata, including t0_epoch_ms (written by demo and record)
+  audio.wav            # 16 kHz mono ASR input (captured by record, or converted by transcribe -audio; local only)
   audio.offset.json    # audio→session offset for an external recording (written by transcribe; local only)
-  events.rrweb.jsonl   # raw rrweb stream, archival (written by demo)
-  interactions.jsonl   # normalised interaction events (written by demo)
+  screen.mp4           # screen capture, H.264, 30 fps with cursor (written by record -video; local only)
+  events.rrweb.jsonl   # raw rrweb stream, archival (written by demo and record -demo)
+  interactions.jsonl   # normalised interaction events (written by demo and record -demo)
   transcript.jsonl     # time-aligned utterances (written by transcribe)
   timeline.jsonl       # merged, session-relative timeline (written by merge)
   findings.jsonl       # analysis findings + appended verdicts (written by analyze/review)
@@ -77,7 +78,7 @@ One utterance per line. Times are session-relative seconds (audio time plus the
 
 ## `audio.offset.json`
 
-Written by `transcribe` only when the audio came from an external recording (a `-audio FILE` that is not the session's own `audio.wav`), which is not captured at `t0`. It records the audio→session offset so a later bare `transcribe` (for example, a re-run with a different model that reuses `audio.wav`) recovers the same offset instead of assuming `0`. A session recorded with `testimony record` captures `audio.wav` at `t0` and has no sidecar; its offset is `0`. If the sidecar is present but unreadable or malformed, `transcribe` refuses rather than guess, and asks for an explicit `-audio` or `-offset`.
+Written by `transcribe` only when the audio came from an external recording (a `-audio FILE` that is not the session's own `audio.wav`), which is not captured at `t0`. It records the audio→session offset so a later bare `transcribe` (for example, a re-run with a different model that reuses `audio.wav`) recovers the same offset instead of assuming `0`. A session recorded with `testimony record` captures `audio.wav` at `t0` and has no sidecar; its offset is `0`, and an explicit `-offset` on such a session applies to that run alone rather than creating a sidecar. On a session that already has one, an explicit `-offset` rewrites it, so the correction carries into later bare runs. If the sidecar is present but unreadable or malformed, `transcribe` refuses rather than guess, and asks for an explicit `-audio` or `-offset`. The sidecar must be a regular file: `transcribe` refuses to read — or rewrite — one that is a symlink.
 
 | Field | Type | Required | Meaning |
 |---|---|---|---|
diff --git a/docs/tutorials/getting-started.md b/docs/tutorials/getting-started.md
index ff97a42..2cde3e1 100644
--- a/docs/tutorials/getting-started.md
+++ b/docs/tutorials/getting-started.md
@@ -7,17 +7,28 @@ You follow the same path Alice takes on her first session: she installs Testimon
 ## 1. Install Testimony
 
 One command installs the `testimony` binary into `~/.local/bin` — no admin
-rights needed — and then offers to set up the transcription dependencies
-(ffmpeg and a local speech-recognition engine), which step 6 relies on:
+rights needed — and then offers to set up two dependencies: ffmpeg, which
+step 2's recording needs, and a local speech-recognition engine, which step 6
+relies on:
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/REPPL/Testimony/main/install.sh | sh
 ```
 
-Answer **y** when it offers ffmpeg and choose **whisperx** as the engine. The
-installer verifies the binary against the release's published checksums and SLSA
-build-provenance attestation (when the GitHub CLI is installed), verifies each
-dependency against the publisher's signature, and tells you if `~/.local/bin`
+Each prompt lists the exact replies it accepts. Answer **brew** when it offers
+ffmpeg — or **local** if you have no Homebrew, which is the only install option
+the prompt then lists — and **whisperx** when it offers the engine. At those
+two prompts any other reply, including `y`, skips that dependency — and step 2
+needs ffmpeg. The one yes/no confirmation inside the whisperx setup (installing
+its `uv` tool) is the exception: there `y` accepts.
+
+The installer verifies the `testimony` binary against the release's published
+`SHA256SUMS` and, when the GitHub CLI (`gh`) is installed, against its SLSA
+build-provenance attestation too, refusing to install on a mismatch. The
+dependencies carry weaker guarantees: the **local** ffmpeg build for macOS is
+checked against a pinned publisher key only when `gpg` is on your machine, and
+it warns you when it installs one unverified; `uv` and whisperx are fetched from
+their publishers unverified. The installer also tells you if `~/.local/bin`
 still needs adding to your `PATH`.
 
 Check the install:
diff --git a/install.sh b/install.sh
index 3876ffb..98cc7cc 100644
--- a/install.sh
+++ b/install.sh
@@ -33,7 +33,7 @@
 set -eu
 
 REPO="REPPL/Testimony"
-VERSION="v0.1.0"
+VERSION="v0.4.0"
 
 # Pinned OpenPGP fingerprint of the evermeet.cx ffmpeg publisher key
 # (Helmut K. C. Tessarek, key id 0x476C4B611A660874). The local-macOS ffmpeg
@@ -64,12 +64,15 @@ ask() {
     return 1
 }
 
-# choose "Question" "option-a" "option-b" → prints the chosen word.
+# choose "Question" "option-a" "option-b" → prints the chosen word. When both
+# options are the same word there is only one choice to offer, so it is rendered
+# (and matched) once: [local/skip], never [local/local/skip].
 choose() {
     q="$1"; a="$2"; b="$3"
     if [ "$ASSUME_YES" = 1 ]; then printf '%s' "$a"; return; fi
+    if [ "$a" = "$b" ]; then opts="$a"; else opts="$a/$b"; fi
     if [ -r /dev/tty ] && [ -w /dev/tty ]; then
-        printf '%s [%s/%s/skip] ' "$q" "$a" "$b" > /dev/tty
+        printf '%s [%s/skip] ' "$q" "$opts" > /dev/tty
         IFS= read -r reply < /dev/tty || reply=""
         case "$reply" in
             "$a") printf '%s' "$a" ;;
@@ -116,7 +119,14 @@ install_binary() {
     trap 'rm -rf "$tmp"' EXIT INT TERM
 
     say "Downloading $tarball ..."
-    fetch "$base/$tarball" "$tmp/$tarball"
+    # A bad --version (or a platform the release never published) surfaces from
+    # curl/wget as a bare 404 in the middle of "Downloading". Name the actual
+    # cause instead. Still fail-closed: die exits non-zero, nothing is retried.
+    fetch "$base/$tarball" "$tmp/$tarball" || die "could not download $tarball
+  Release \"$VERSION\" — or its $plat asset — was not found at
+    $base/$tarball
+  Release tags are of the form vX.Y.Z (note the leading 'v').
+  Releases: https://github.com/$REPO/releases"
 
     # Integrity: verify the tarball against the release's published SHA256SUMS.
     # No hash is pinned in this script — it is fetched from the release itself.
diff --git a/internal/cli/cli.go b/internal/cli/cli.go
index ecf9f0c..497e25e 100644
--- a/internal/cli/cli.go
+++ b/internal/cli/cli.go
@@ -4,6 +4,7 @@ package cli
 import (
 	"flag"
 	"fmt"
+	"math"
 	"os"
 	"path/filepath"
 	"strings"
@@ -66,7 +67,7 @@ func Run(args []string) int {
 		dir := fs.String("session", "", "session directory")
 		fs.Parse(rest)
 		if *dir == "" {
-			return fail(fmt.Errorf("merge: -session is required"))
+			return usageErr(fmt.Errorf("merge: -session is required"))
 		}
 		speech, events, err := timeline.Merge(*dir)
 		if err != nil {
@@ -82,7 +83,17 @@ func Run(args []string) int {
 		window := fs.Float64("window", 2.5, "utterance↔event join window, seconds")
 		fs.Parse(rest)
 		if *dir == "" {
-			return fail(fmt.Errorf("report: -session is required"))
+			return usageErr(fmt.Errorf("report: -session is required"))
+		}
+		// A non-finite window is not a join window at all, and Render has no way to
+		// notice: every comparison against NaN is false, so a NaN window silently
+		// detaches every event from the speech it accompanied, while +Inf puts every
+		// event inside the first utterance's window and files them all under it.
+		// Either way report.md — the human evidence artefact — misstates what the
+		// participant was doing while they spoke, and the command exits 0. A negative
+		// window is legitimate (it narrows the join), so only finiteness is required.
+		if math.IsNaN(*window) || math.IsInf(*window, 0) {
+			return usageErr(fmt.Errorf("report: -window must be a finite number of seconds, got %v", *window))
 		}
 		md, err := report.Render(*dir, *window)
 		if err != nil {
@@ -136,7 +147,7 @@ func Run(args []string) int {
 		offset := fs.Float64("offset", 0, "audio→session clock offset in seconds (default: derived from the recording's creation time)")
 		fs.Parse(rest)
 		if *dir == "" {
-			return fail(fmt.Errorf("transcribe: -session is required"))
+			return usageErr(fmt.Errorf("transcribe: -session is required"))
 		}
 		offsetSet := false
 		fs.Visit(func(f *flag.Flag) {
@@ -170,11 +181,11 @@ func Run(args []string) int {
 		ingest := fs.String("ingest", "", "validate answer JSON at FILE (or \"-\" for stdin) into findings.jsonl")
 		fs.Parse(rest)
 		if *dir == "" {
-			return fail(fmt.Errorf("analyze: -session is required"))
+			return usageErr(fmt.Errorf("analyze: -session is required"))
 		}
 		if *ingest != "" {
 			if *out != "" {
-				return fail(fmt.Errorf("analyze: -out and -ingest cannot be combined"))
+				return usageErr(fmt.Errorf("analyze: -out and -ingest cannot be combined"))
 			}
 			in := os.Stdin
 			if *ingest != "-" {
@@ -224,7 +235,7 @@ func Run(args []string) int {
 		verdict := fs.String("verdict", "", "non-interactive: confirmed | rejected | duplicate-of-F-NNN")
 		fs.Parse(rest)
 		if *dir == "" {
-			return fail(fmt.Errorf("review: -session is required"))
+			return usageErr(fmt.Errorf("review: -session is required"))
 		}
 		if err := review.Run(review.Options{
 			Dir:     *dir,
@@ -253,11 +264,28 @@ func Run(args []string) int {
 	}
 }
 
-func fail(err error) int {
+// printErr writes an operator-facing error in the one shape every command uses.
+func printErr(err error) {
 	fmt.Fprintln(os.Stderr, "testimony:", err)
+}
+
+// fail reports a runtime failure of a well-formed command — the invocation was
+// right and the work could not be done (exit 1).
+func fail(err error) int {
+	printErr(err)
 	return 1
 }
 
+// usageErr reports a wrong invocation (exit 2), the status the no-command,
+// unknown-command, and flag-parse paths already use. A missing required flag
+// belongs with them: reported as a runtime error it was indistinguishable to a
+// caller — a script, CI — from a session that genuinely could not be read.
+// docs/reference/cli.md states the contract.
+func usageErr(err error) int {
+	printErr(err)
+	return 2
+}
+
 // isCharDevice reports whether f is an interactive terminal, gating review's
 // interactive walk so CI (where stdin is a pipe) never blocks.
 func isCharDevice(f *os.File) bool {
diff --git a/internal/cli/cli_test.go b/internal/cli/cli_test.go
index 37fc853..3722763 100644
--- a/internal/cli/cli_test.go
+++ b/internal/cli/cli_test.go
@@ -1,8 +1,10 @@
 package cli
 
 import (
+	"io"
 	"os"
 	"path/filepath"
+	"strings"
 	"syscall"
 	"testing"
 	"time"
@@ -10,6 +12,30 @@ import (
 	"github.com/REPPL/Testimony/internal/session"
 )
 
+// captureStderr runs fn with os.Stderr redirected to a pipe and returns
+// everything it wrote there, so a test can assert on the operator-facing
+// message and not merely on the exit code.
+func captureStderr(t *testing.T, fn func()) string {
+	t.Helper()
+	r, w, err := os.Pipe()
+	if err != nil {
+		t.Fatalf("pipe: %v", err)
+	}
+	old := os.Stderr
+	os.Stderr = w
+	read := make(chan string, 1)
+	go func() {
+		b, _ := io.ReadAll(r)
+		read <- string(b)
+	}()
+	fn()
+	os.Stderr = old
+	w.Close()
+	got := <-read
+	r.Close()
+	return got
+}
+
 // miniSession writes a minimal but valid session (manifest + one timeline entry)
 // so `analyze` reaches its -out write / -ingest read without failing earlier.
 func miniSession(t *testing.T) string {
@@ -69,3 +95,81 @@ func TestAnalyzeIngestRefusesFIFO(t *testing.T) {
 		t.Fatal("analyze -ingest blocked on a FIFO instead of refusing it")
 	}
 }
+
+// TestReportRejectsNonFiniteWindow is the fabricated-join regression: -window
+// took any float64 strconv would parse, so NaN and ±Inf reached report.Render.
+// Every comparison against NaN is false, so a NaN window detached every event
+// from the speech it accompanied; +Inf made every event fall inside the first
+// utterance's window and be filed under it. Both wrote a report.md that misstates
+// what the participant was doing while they spoke, and both exited 0. A negative
+// window is legitimate (it narrows the join) and must stay accepted.
+func TestReportRejectsNonFiniteWindow(t *testing.T) {
+	for _, w := range []string{"NaN", "Inf", "-Inf"} {
+		dir := miniSession(t)
+		var code int
+		stderr := captureStderr(t, func() {
+			code = Run([]string{"report", "-session", dir, "-window", w})
+		})
+		if code != 2 {
+			t.Fatalf("-window %s: exit %d, want 2 (usage error, like every other bad invocation)", w, code)
+		}
+		if !strings.Contains(stderr, "testimony: report: -window must be a finite number") {
+			t.Fatalf("-window %s: want the finite-window refusal on stderr, got %q", w, stderr)
+		}
+		if _, err := os.Stat(filepath.Join(dir, session.ReportFile)); !os.IsNotExist(err) {
+			t.Fatalf("-window %s rendered a report anyway (err=%v)", w, err)
+		}
+	}
+
+	for _, w := range []string{"2.5", "-1"} {
+		dir := miniSession(t)
+		if code := Run([]string{"report", "-session", dir, "-window", w}); code != 0 {
+			t.Fatalf("-window %s must still render, got exit %d", w, code)
+		}
+		if _, err := os.Stat(filepath.Join(dir, session.ReportFile)); err != nil {
+			t.Fatalf("-window %s wrote no report: %v", w, err)
+		}
+	}
+}
+
+// TestMissingSessionIsAUsageError pins the exit-status contract of
+// docs/reference/cli.md: a wrong invocation exits 2 and a runtime failure of a
+// well-formed command exits 1. A missing required -session was reported as a
+// runtime error (1), so it was indistinguishable to a caller from a session that
+// genuinely could not be read, while the sibling usage errors — no command, an
+// unknown command, a flag-parse failure — all exited 2.
+func TestMissingSessionIsAUsageError(t *testing.T) {
+	for _, cmd := range []string{"merge", "report", "transcribe", "analyze", "review"} {
+		var code int
+		stderr := captureStderr(t, func() { code = Run([]string{cmd}) })
+		if code != 2 {
+			t.Errorf("%s without -session: exit %d, want 2 (usage error)", cmd, code)
+		}
+		if want := "testimony: " + cmd + ": -session is required"; !strings.Contains(stderr, want) {
+			t.Errorf("%s without -session: want %q on stderr, got %q", cmd, want, stderr)
+		}
+	}
+
+	// Mutually exclusive flags are a wrong invocation too.
+	{
+		var code int
+		stderr := captureStderr(t, func() {
+			code = Run([]string{"analyze", "-session", t.TempDir(), "-out", "f.md", "-ingest", "-"})
+		})
+		if code != 2 {
+			t.Errorf("analyze -out with -ingest: exit %d, want 2 (usage error)", code)
+		}
+		if want := "testimony: analyze: -out and -ingest cannot be combined"; !strings.Contains(stderr, want) {
+			t.Errorf("analyze -out with -ingest: want %q on stderr, got %q", want, stderr)
+		}
+	}
+
+	// A well-formed command that fails at runtime keeps exit 1.
+	var code int
+	captureStderr(t, func() {
+		code = Run([]string{"merge", "-session", filepath.Join(t.TempDir(), "absent")})
+	})
+	if code != 1 {
+		t.Errorf("merge on an unreadable session: exit %d, want 1 (runtime error)", code)
+	}
+}
diff --git a/internal/report/report.go b/internal/report/report.go
index efb9539..c9b2f73 100644
--- a/internal/report/report.go
+++ b/internal/report/report.go
@@ -36,6 +36,16 @@ func Render(dir string, window float64) (string, error) {
 	if err != nil {
 		return "", fmt.Errorf("read timeline (run `testimony merge` first?): %w", err)
 	}
+	// Order the record by time rather than trusting the file's line order. The
+	// timeline this reads is not necessarily the one merge wrote: a hand-edited or
+	// exchanged timeline.jsonl reaches Render directly — the same assumption the
+	// join step below already refuses to make about ids — and an out-of-order one
+	// rendered [00:50] above [00:10], so report.md, which is read as the
+	// chronological record of the session, silently misstated when things happened.
+	// The standalone-event flush below also walks events forward on the assumption
+	// they ascend. sort.SliceStable with the same less function timeline.Merge uses
+	// keeps the two orderings identical, so a merge-produced timeline is unchanged.
+	sort.SliceStable(entries, func(i, j int) bool { return entries[i].T < entries[j].T })
 
 	var speech, events []timeline.Entry
 	for _, e := range entries {
diff --git a/internal/report/report_test.go b/internal/report/report_test.go
index 2ebcd4f..3a22548 100644
--- a/internal/report/report_test.go
+++ b/internal/report/report_test.go
@@ -533,3 +533,40 @@ func TestReportFlushesEventPastLegacySentinel(t *testing.T) {
 		t.Fatalf("standalone event at the legacy 1e18 sentinel was dropped from the report:\n%s", md)
 	}
 }
+
+// TestRenderSortsByTime is the out-of-order-report regression. Render consumed
+// timeline.jsonl in file order, so a hand-edited or exchanged timeline — the case
+// Render's own join step already defends against — rendered utterances and
+// standalone events in whatever order the lines happened to sit in, printing
+// [00:50] before [00:10]. report.md is read as the chronological record of the
+// session, so the file order silently rewrote when things happened. Render now
+// applies the same stable sort by t that timeline.Merge does.
+func TestRenderSortsByTime(t *testing.T) {
+	const unsorted = `{"t":50,"src":"speech","id":"utt-002","payload":{"speaker":"P1","t1":52,"text":"Second remark."}}
+{"t":10,"src":"speech","id":"utt-001","payload":{"speaker":"P1","t1":12,"text":"First remark."}}
+{"t":40,"src":"event","id":"ev-002","payload":{"kind":"scroll"}}
+{"t":5,"src":"event","id":"ev-001","payload":{"kind":"click"}}
+`
+	dir := setupSession(t)
+	if err := os.WriteFile(filepath.Join(dir, session.TimelineFile), []byte(unsorted), 0o644); err != nil {
+		t.Fatalf("write timeline: %v", err)
+	}
+
+	md, err := Render(dir, 2.5)
+	if err != nil {
+		t.Fatalf("Render: %v", err)
+	}
+	// Every entry is outside every join window here, so all four appear at the top
+	// level and must read in chronological order.
+	prev := -1
+	for _, want := range []string{"[00:05] click", "[00:10]", "First remark", "[00:40] scroll", "[00:50]", "Second remark"} {
+		at := strings.Index(md, want)
+		if at < 0 {
+			t.Fatalf("report is missing %q:\n%s", want, md)
+		}
+		if at < prev {
+			t.Fatalf("report is out of chronological order at %q:\n%s", want, md)
+		}
+		prev = at
+	}
+}
diff --git a/internal/transcribe/ffmpeg.go b/internal/transcribe/ffmpeg.go
index 1ad3064..8760baa 100644
--- a/internal/transcribe/ffmpeg.go
+++ b/internal/transcribe/ffmpeg.go
@@ -18,22 +18,38 @@ import (
 // and plain WAV. Everything is normalised through ffmpeg regardless.
 var audioExts = map[string]bool{".m4a": true, ".mov": true, ".wav": true}
 
-// convertAudio produces the canonical ASR input — 16 kHz mono PCM WAV — from
-// the original recording via an ffmpeg subprocess.
-func convertAudio(in, out string) error {
+// checkExternalAudio validates the operator-named recording before anything
+// opens it. It lives apart from convertAudio because the conversion is no longer
+// the first thing to touch the path: transcribe.Run resolves the audio→session
+// offset first (so a refused run cannot destroy the session's audio.wav), and
+// that derivation hands the same path to an ffprobe subprocess. Both subprocesses
+// open without O_NONBLOCK, so a FIFO at -audio blocks their open(2) for ever and
+// hangs the command; and ffprobe is a media parser, so pointing it at a file
+// whose container the pipeline does not even accept widens its exposure for
+// nothing. Run calls this on the external branch and convertAudio calls it again,
+// so the guard keeps one home and neither entry point is unguarded.
+//
+// os.Stat resolves a symlink, so an operator pointing -audio at a symlinked
+// recording is fine; what must be refused is a non-regular target.
+func checkExternalAudio(in string) error {
 	ext := strings.ToLower(filepath.Ext(in))
 	if !audioExts[ext] {
 		return fmt.Errorf("unsupported audio format %q: expected .m4a, .mov, or .wav", ext)
 	}
-	// os.Stat resolves a symlink, so an operator pointing -audio at a symlinked
-	// recording is fine; what must be refused is a non-regular target, because a
-	// FIFO handed to ffmpeg as its input blocks the subprocess's open(2) for ever,
-	// waiting for a writer that never arrives.
 	if fi, err := os.Stat(in); err != nil {
 		return fmt.Errorf("audio file: %w", err)
 	} else if !fi.Mode().IsRegular() {
 		return fmt.Errorf("refusing to read %s: it is not a regular file", in)
 	}
+	return nil
+}
+
+// convertAudio produces the canonical ASR input — 16 kHz mono PCM WAV — from
+// the original recording via an ffmpeg subprocess.
+func convertAudio(in, out string) error {
+	if err := checkExternalAudio(in); err != nil {
+		return err
+	}
 	if err := checkPlainOutput(out); err != nil {
 		return err
 	}
diff --git a/internal/transcribe/transcribe.go b/internal/transcribe/transcribe.go
index b0735f3..5447f0c 100644
--- a/internal/transcribe/transcribe.go
+++ b/internal/transcribe/transcribe.go
@@ -73,24 +73,56 @@ func Run(opts Options) (int, error) {
 	wav := filepath.Join(opts.SessionDir, session.AudioFile)
 	external := opts.Audio != "" && !sameFile(opts.Audio, wav)
 	if external {
-		if err := convertAudio(opts.Audio, wav); err != nil {
+		// Refuse an unusable -audio before anything opens it. The offset derivation
+		// below probes this path with ffprobe, whose open(2) on a FIFO never returns,
+		// so this guard has to fire ahead of it rather than waiting for convertAudio.
+		if err := checkExternalAudio(opts.Audio); err != nil {
 			return 0, err
 		}
 	} else if err := checkSessionAudio(wav, opts.SessionDir); err != nil {
 		return 0, err
 	}
 
+	// Resolve the offset BEFORE the conversion replaces audio.wav. Resolution
+	// reads only the manifest and the external recording, so it can run first —
+	// and it must, because every way it fails (an unusable manifest t0, an
+	// implausible derived offset) refuses the run. Converting first destroyed the
+	// session's record-origin capture and left no sidecar behind, so the session
+	// became indistinguishable from one recorded here (no sidecar ⇒ captured at
+	// t0, docs/reference/session-directory.md): the next bare `transcribe` took
+	// the in-place branch, reported "captured at t0", and wrote a silently
+	// time-shifted transcript at exit 0. A refused run now leaves the session
+	// byte-for-byte as it found it.
 	offset, provenance, err := resolveOffset(opts, man, external)
 	if err != nil {
 		return 0, err
 	}
+	if external {
+		if err := convertAudio(opts.Audio, wav); err != nil {
+			return 0, err
+		}
+	}
+
 	// An external recording's audio.wav is NOT captured at t0, and disk bytes
 	// cannot distinguish it from a record-origin audio.wav. Persist the offset
 	// beside audio.wav so a later bare `transcribe` (a re-run with a different
 	// model, reusing audio.wav) reads it back instead of silently assuming 0 and
 	// shifting every utterance by the forgotten offset. record-origin audio.wav
 	// writes no sidecar and correctly defaults to 0.
-	if external {
+	//
+	// An explicit -offset on the in-place path rewrites an EXISTING sidecar: that
+	// is the operator correcting an offset a previous external run got wrong, and
+	// leaving the stale value in place applied the correction to one transcript
+	// only, for the next bare re-run to silently resurrect. A session with no
+	// sidecar is record-origin and stays that way — inventing one would make every
+	// later bare run inherit a one-off flag.
+	persist := external
+	if !persist && opts.OffsetSet {
+		if persist, err = offsetSidecarExists(opts.SessionDir); err != nil {
+			return 0, err
+		}
+	}
+	if persist {
 		if err := writeOffsetSidecar(opts.SessionDir, offset, provenance); err != nil {
 			return 0, fmt.Errorf("persist audio offset: %w", err)
 		}
@@ -242,6 +274,24 @@ func writeOffsetSidecar(dir string, offset float64, provenance string) error {
 	return session.WriteFileNoFollow(filepath.Join(dir, session.AudioOffsetFile), append(b, '\n'), 0o644)
 }
 
+// offsetSidecarExists reports whether a sidecar is already present beside
+// audio.wav, without parsing it. The caller only needs to know whether this
+// session already carries an external-audio offset, and an unusable sidecar
+// (malformed, oversized) is precisely the one an explicit -offset repairs — the
+// guidance readOffsetSidecar prints says so — so parsing here would refuse the
+// repair. os.Lstat, not os.Stat: a symlink planted at the sidecar name must
+// count as present, so the rewrite meets session.WriteFileNoFollow's refusal
+// rather than being mistaken for absence and skipped.
+func offsetSidecarExists(dir string) (bool, error) {
+	if _, err := os.Lstat(filepath.Join(dir, session.AudioOffsetFile)); err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return false, nil
+		}
+		return false, err
+	}
+	return true, nil
+}
+
 // readOffsetSidecar reads the offset sidecar if present. ok is false with no
 // error when the file is absent (the record-origin case). A present-but-unusable
 // sidecar — unreadable, oversized, malformed, or carrying a non-finite offset —
diff --git a/internal/transcribe/transcribe_test.go b/internal/transcribe/transcribe_test.go
index b2c4bab..0f27781 100644
--- a/internal/transcribe/transcribe_test.go
+++ b/internal/transcribe/transcribe_test.go
@@ -2,6 +2,7 @@ package transcribe
 
 import (
 	"errors"
+	"io"
 	"os"
 	"os/exec"
 	"path/filepath"
@@ -392,6 +393,250 @@ func TestResolveOffsetExternalOffsetFlagNoT0(t *testing.T) {
 	}
 }
 
+// recordOriginAudio stands in for the bytes `testimony record` captured into
+// audio.wav — the irreplaceable original a failed transcribe run must not
+// destroy.
+const recordOriginAudio = "RIFF record-origin capture"
+
+// fakeTools puts a stub whisperx, ffmpeg, and ffprobe on PATH so Run's
+// detectEngine, convertAudio, and deriveOffset all resolve without any of the
+// three installed. The stub whisperx writes a minimal valid engine output into
+// the --output_dir it is handed (always its last argument). The stub ffprobe
+// READS the recording it is pointed at, exactly as the real one does — that is
+// what makes a FIFO at -audio block its open(2) for ever.
+func fakeTools(t *testing.T) {
+	t.Helper()
+	bin := t.TempDir()
+	whisperx := "#!/bin/sh\nfor last; do :; done\n" +
+		`printf '%s' '{"segments":[{"start":1,"end":2,"text":"Alice speaks."}]}' > "$last/audio.json"` + "\n"
+	// `: < FILE` opens the recording with a shell builtin — PATH here holds only
+	// these stubs, so an external reader such as cat would not be found and the
+	// open would never happen.
+	ffprobe := "#!/bin/sh\nfor last; do :; done\n: < \"$last\"\nprintf '%s' '{}'\n"
+	for name, script := range map[string]string{
+		"whisperx": whisperx,
+		"ffmpeg":   "#!/bin/sh\nexit 0\n",
+		"ffprobe":  ffprobe,
+	} {
+		if err := os.WriteFile(filepath.Join(bin, name), []byte(script), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	t.Setenv("PATH", bin)
+}
+
+// seedSession writes a manifest and a record-origin audio.wav, returning the
+// session directory and the audio path.
+func seedSession(t *testing.T, m session.Manifest) (dir, wav string) {
+	t.Helper()
+	dir = t.TempDir()
+	if err := session.SaveManifest(dir, m); err != nil {
+		t.Fatalf("SaveManifest: %v", err)
+	}
+	wav = filepath.Join(dir, session.AudioFile)
+	if err := os.WriteFile(wav, []byte(recordOriginAudio), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return dir, wav
+}
+
+// stubConvert stands in for ffmpeg and reports, through the returned pointer,
+// whether the conversion ran at all. It writes different bytes from
+// recordOriginAudio, so a conversion that reached audio.wav is visible in the
+// file's content.
+func stubConvert(t *testing.T) *bool {
+	t.Helper()
+	old := convertRunner
+	t.Cleanup(func() { convertRunner = old })
+	ran := false
+	convertRunner = func(ffmpeg, in, tmpPath string) error {
+		ran = true
+		return os.WriteFile(tmpPath, []byte("RIFF converted external recording"), 0o644)
+	}
+	return &ran
+}
+
+// externalRecording writes a stand-in recording outside the session directory.
+func externalRecording(t *testing.T) string {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "bob-interview.m4a")
+	if err := os.WriteFile(path, []byte("external recording"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return path
+}
+
+// TestRunResolvesOffsetBeforeConverting is the destroyed-capture regression.
+// Pre-fix Run converted the external recording over the session's audio.wav
+// BEFORE resolving the offset, so every way resolution can fail — an unusable
+// manifest t0, an implausible derived offset — exited 1 with the record-origin
+// capture already overwritten and no audio.offset.json written. The session was
+// then indistinguishable from a record-origin one (no sidecar ⇒ captured at t0,
+// docs/reference/session-directory.md), so a later bare `transcribe` took the
+// in-place branch, reported the false provenance "captured at t0", and wrote a
+// silently time-shifted transcript at exit 0. Resolution now runs first, so a
+// refused run leaves the session exactly as it found it.
+func TestRunResolvesOffsetBeforeConverting(t *testing.T) {
+	t.Run("unusable t0", func(t *testing.T) {
+		fakeTools(t)
+		// No t0_epoch_ms: a received or hand-edited manifest.
+		dir, wav := seedSession(t, session.Manifest{Session: "2026-07-22_bob-received"})
+		converted := stubConvert(t)
+
+		_, err := Run(Options{SessionDir: dir, Audio: externalRecording(t), Engine: EngineWhisperX, Log: io.Discard})
+		if err == nil {
+			t.Fatal("an external recording with no usable t0 must fail the run")
+		}
+		if !errors.Is(err, session.ErrNoT0) {
+			t.Fatalf("want an ErrNoT0-based error, got %v", err)
+		}
+		assertSessionUntouched(t, dir, wav, converted)
+	})
+
+	t.Run("implausible derived offset", func(t *testing.T) {
+		fakeTools(t)
+		dir, wav := seedSession(t, session.Manifest{Session: "s", T0EpochMS: 1_700_000_000_000})
+		converted := stubConvert(t)
+		old := deriveOffsetFn
+		t.Cleanup(func() { deriveOffsetFn = old })
+		deriveOffsetFn = func(audio string, t0EpochMS int64) (float64, bool) { return 5e9, true }
+
+		_, err := Run(Options{SessionDir: dir, Audio: externalRecording(t), Engine: EngineWhisperX, Log: io.Discard})
+		if err == nil || !strings.Contains(err.Error(), "exceeds") {
+			t.Fatalf("an implausible derived offset must fail the run, got %v", err)
+		}
+		assertSessionUntouched(t, dir, wav, converted)
+	})
+}
+
+// assertSessionUntouched checks that a refused run left neither a converted
+// audio.wav nor a sidecar behind.
+func assertSessionUntouched(t *testing.T, dir, wav string, converted *bool) {
+	t.Helper()
+	if *converted {
+		t.Error("the conversion ran before the offset was resolved; a refused run must not touch the session's audio")
+	}
+	if b, err := os.ReadFile(wav); err != nil || string(b) != recordOriginAudio {
+		t.Errorf("the record-origin %s was replaced by a refused run: %q (err=%v)", session.AudioFile, b, err)
+	}
+	if _, err := os.Stat(filepath.Join(dir, session.AudioOffsetFile)); !os.IsNotExist(err) {
+		t.Errorf("a refused run wrote %s (err=%v); the session now claims an offset it never resolved", session.AudioOffsetFile, err)
+	}
+}
+
+// TestRunRefusesNonRegularExternalAudio is the hang regression on the offset
+// derivation. The refusals that make -audio safe to open — the accepted-container
+// check and the regular-file check — lived inside convertAudio, so hoisting the
+// offset resolution above the conversion put an ffprobe subprocess on the
+// operator-named path AHEAD of them: ffprobe opens without O_NONBLOCK, so a FIFO
+// at -audio (a session bundle is an exchange unit, and tar preserves FIFOs)
+// blocked its open(2) for ever and `testimony transcribe` hung with no error
+// instead of refusing in milliseconds. The guard now runs before anything opens
+// the recording. The run happens in a goroutine and the test fails on a timeout,
+// so a regression reports a failure rather than hanging the suite for ever.
+func TestRunRefusesNonRegularExternalAudio(t *testing.T) {
+	fakeTools(t)
+	dir, _ := seedSession(t, session.Manifest{Session: "s", T0EpochMS: 1_700_000_000_000})
+	fifo := filepath.Join(t.TempDir(), "bob-interview.m4a")
+	if err := syscall.Mkfifo(fifo, 0o644); err != nil {
+		t.Skipf("FIFOs unavailable on this platform: %v", err)
+	}
+
+	done := make(chan error, 1)
+	go func() {
+		_, err := Run(Options{SessionDir: dir, Audio: fifo, Engine: EngineWhisperX, Log: io.Discard})
+		done <- err
+	}()
+	select {
+	case err := <-done:
+		if err == nil || !strings.Contains(err.Error(), "not a regular file") {
+			t.Fatalf("want a non-regular-file refusal, got %v", err)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("transcribe blocked on a FIFO -audio instead of refusing it")
+	}
+}
+
+// TestRunRefusesUnsupportedExternalAudioBeforeProbing is the same ordering
+// invariant on the container check: a file whose extension the pipeline does not
+// accept must be refused by name, before ffprobe is asked to parse it — the
+// probe is a media parser, and pointing it at arbitrary operator-named files
+// widens its attack surface for nothing.
+func TestRunRefusesUnsupportedExternalAudioBeforeProbing(t *testing.T) {
+	fakeTools(t)
+	dir, _ := seedSession(t, session.Manifest{Session: "s", T0EpochMS: 1_700_000_000_000})
+	notes := filepath.Join(t.TempDir(), "notes.txt")
+	if err := os.WriteFile(notes, []byte("not a recording"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	old := deriveOffsetFn
+	t.Cleanup(func() { deriveOffsetFn = old })
+	probed := false
+	deriveOffsetFn = func(audio string, t0EpochMS int64) (float64, bool) {
+		probed = true
+		return 0, false
+	}
+
+	_, err := Run(Options{SessionDir: dir, Audio: notes, Engine: EngineWhisperX, Log: io.Discard})
+	if err == nil || !strings.Contains(err.Error(), "unsupported audio format") {
+		t.Fatalf("want an unsupported-format refusal, got %v", err)
+	}
+	if probed {
+		t.Error("the recording was probed before its container was accepted")
+	}
+}
+
+// TestRunExplicitOffsetUpdatesExistingSidecar is the discarded-correction
+// regression: an operator who spots a wrong offset re-runs with -offset N, but
+// pre-fix the in-place path never rewrote the sidecar, so the correction applied
+// to that one transcript and the next bare re-run silently resurrected the stale
+// value. An existing sidecar is the session's record of an external audio origin,
+// so an explicit -offset now rewrites it.
+func TestRunExplicitOffsetUpdatesExistingSidecar(t *testing.T) {
+	fakeTools(t)
+	man := session.Manifest{Session: "s", T0EpochMS: 1_700_000_000_000}
+	dir, _ := seedSession(t, man)
+	if err := writeOffsetSidecar(dir, 12.5, "derived: audio creation_time − manifest t0"); err != nil {
+		t.Fatalf("writeOffsetSidecar: %v", err)
+	}
+
+	if _, err := Run(Options{SessionDir: dir, Engine: EngineWhisperX, Offset: 30, OffsetSet: true, Log: io.Discard}); err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+
+	off, _, ok, err := readOffsetSidecar(dir)
+	if err != nil || !ok {
+		t.Fatalf("sidecar after the correction: ok=%v err=%v", ok, err)
+	}
+	if off != 30 {
+		t.Fatalf("sidecar offset: got %v, want 30 (the operator's correction, not the stale 12.5)", off)
+	}
+	// The next bare run must resolve to the corrected value.
+	got, _, err := resolveOffset(Options{SessionDir: dir}, man, false)
+	if err != nil {
+		t.Fatalf("bare re-run: %v", err)
+	}
+	if got != 30 {
+		t.Fatalf("bare re-run offset: got %v, want 30", got)
+	}
+}
+
+// TestRunExplicitOffsetWritesNoSidecarForRecordOrigin guards the other half of
+// the sidecar model: a session with no sidecar is record-origin (audio.wav
+// captured at t0), and an explicit -offset for one transcript must not invent a
+// sidecar that would make every later bare run inherit it.
+func TestRunExplicitOffsetWritesNoSidecarForRecordOrigin(t *testing.T) {
+	fakeTools(t)
+	dir, _ := seedSession(t, session.Manifest{Session: "s", T0EpochMS: 1_700_000_000_000})
+
+	if _, err := Run(Options{SessionDir: dir, Engine: EngineWhisperX, Offset: 30, OffsetSet: true, Log: io.Discard}); err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(dir, session.AudioOffsetFile)); !os.IsNotExist(err) {
+		t.Fatalf("a record-origin session must stay sidecar-free, got err=%v", err)
+	}
+}
+
 // TestSameFileTreatedInPlace proves -audio pointing at the session's own
 // audio.wav is recognised as the in-place case (no self-conversion).
 func TestSameFileTreatedInPlace(t *testing.T) {