feat(diag): stage breadcrumbs for the process pipeline to localize the Windows hang (#415)

[silverstein]

What

Adds immediate, flushed stage breadcrumbs to the minutes process / process_audio pipeline, written to ~/.minutes/logs/process-audio-trace.jsonl. Each marker is flush() + sync_all()'d to disk the instant it's written, so if a stage hangs, the last-completed marker stays on disk — pinpointing exactly where.

Diagnostic-only: no change to decode/whisper/timeout behavior.

Why (#415)

On Windows, process_audio hangs unconditionally with zero trace — no job record, no log line, no error. Root cause (investigated): the in-process native whisper call (model load / integrated VAD / inference) wedges on Windows where the parent can't observe or kill it, and MCP's execFile buffers stderr until exit, so nothing surfaces. The reporter (Cedric-Duchene) explicitly asked for Windows diagnostic logging to localize it — this is that instrument.

Stages emitted: process.start → decode.start/done → whisper.model_load.start/done → whisper.vad_setup.start/done → whisper.full.start/done → transcribe.done → pipeline.write.start/done → pipeline.done. Each carries input path, language, content_type, model_path, vad_enabled, audio samples/duration; whisper.full.start also records the internal timeout_secs (which confirms the ~331s internal deadline exceeds MCP's fixed 300s — why even a 10s file times out).

Safety

Best-effort by construction: the writer opens with let Ok(file) else { return } (no panic), swallows flush/sync errors, and a trace failure never affects processing. Gated by is_active() so it only traces the process path; MINUTES_TRACE=0 disables. Cross-platform, negligible overhead (a dozen lines per run).

Verified

Real macOS run produced the full ordered trace (attached in the dev log). cargo test -p minutes-core --no-default-features green (incl. a new test asserting ordered markers), fmt + clippy clean.

Next

Once this ships, the reporter runs a build and the trace names the wedge stage (model-load vs VAD vs inference) — then the targeted fix (likely gating VAD on Windows or moving whisper behind a killable worker with an honest timeout+error) is small. Tracked on #415.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
useminutes.app	Ready	Preview, Comment	Jul 6, 2026 5:35pm

[Cedric-Duchene]

Thanks for the fast turnaround — ran both checks:

1. .wav also hangs. Converted the 10s test clip to .wav (bypassing ffmpeg entirely) and called process_audio on it directly. Same result: MCP error -32001: Request timed out, and list_processing_jobs / list_meetings both still show nothing afterward. This matches your read — the decode path looks innocent, the hang is downstream in whisper.

2. ~/.minutes/logs/minutes.log doesn't exist. Only mcp-crash.log is present in that folder — no minutes.log at all on this machine.

Happy to test the stage-breadcrumb tracing once it's in a published release — building from source isn't something I can easily do on this machine, so I'll wait for the next version rather than build main myself. Let me know if there's anything else useful to check in the meantime.