Troubleshooting

Troubleshooting

Start with three checks:

jarvis-line status
jarvis-line doctor
jarvis-line tts test --text "Jarvis line test is ready."

This separates runtime health, integration/config health, and actual playback.

TTS Test Works, Agent Speech Does Not

1. Confirm the instruction block is in the file the active agent reads.
2. Confirm the line begins with an accepted prefix such as Jarvis line:.
3. Check speech policy:

jarvis-line config get speech_enabled
jarvis-line config get speak_mode
jarvis-line config get quiet_hours
jarvis-line config get quiet_days

4. For Codex, refresh the hooks:

jarvis-line install codex

5. Restart and inspect diagnostics:

jarvis-line restart
jarvis-line trace --limit 20

No Sound From The TTS Test

jarvis-line config get tts
jarvis-line tts capabilities
jarvis-line doctor

• Kokoro: run jarvis-line kokoro status and jarvis-line kokoro verify.
• macOS system TTS: leave system_voice and system_rate as null to follow Read & Speak.
• Windows system TTS: verify PowerShell and System.Speech are available.
• Linux system TTS: install one of spd-say, espeak-ng, or espeak.
• Custom command: run your wrapper independently and confirm placeholders/output mode.

Final Speech Has No Completion Chime

The ordinary TTS test does not play the completion cue. Test a real final event:

jarvis-line config set final_chime_enabled true
jarvis-line emit \
  --source manual \
  --session chime-check \
  --phase final \
  --line "The final completion chime is ready."

The expected order is the short cue followed by the spoken line. Commentary and attention events intentionally remain silent. If final speech works but the cue does not, inspect jarvis-line logs tail for final-chime-error; cue failure is fail-open and will not block TTS.

Wrong Language Or Robotic Pronunciation

The generated instruction language and TTS voice/model language must match.

jarvis-line config get line_language
jarvis-line config get tts

Kokoro defaults are English-focused. On macOS, use System Settings → Accessibility → Read & Speak to choose a matching language and natural system voice, leave the Jarvis Line system voice override unset, and regenerate the instruction in that full language name.

See TTS and Voices.

Attention Alerts Do Not Speak

jarvis-line config get attention_enabled
jarvis-line config get speech_enabled
jarvis-line config get speak_mode
jarvis-line install codex
jarvis-line trace --limit 20

Entering Plan mode is not a request. Codex must produce an actual PermissionRequest or structured request_user_input. Plan-question detection is fail-soft and may need an adapter update if Codex changes its session format.

Duplicate, Stale, Or Overlapping Speech

Jarvis Line should use one audio worker across sessions. Check:

jarvis-line status
jarvis-line queue status
jarvis-line trace --limit 30

Clear stale queued work and restart:

jarvis-line queue clear
jarvis-line restart

Do not run multiple installed copies or manually launch a second watcher. The macOS app and CLI should control the same runtime.

High Memory Use

The audio worker releases the TTS engine after an idle period and exits after a configured RSS ceiling once queued work drains. Since v0.8.3, the ceiling is checked immediately after Kokoro warm-up, and worker shutdown rechecks the shared queue atomically so a newly arrived line cannot be left waiting without an active worker.

jarvis-line config get audio_worker_idle_exit_seconds
jarvis-line config get audio_worker_max_rss_mb
jarvis-line status

If memory remains high with an empty queue, capture a support report before restarting so the bounded diagnostics are available.

Repair

jarvis-line doctor --fix

Review the output. The repair command is preferable to deleting runtime files or starting multiple workers manually.

Open An Issue Safely

Create a local redacted Markdown report:

jarvis-line support-report --output ./jarvis-line-issue.md

Open it, review every section, remove anything you do not want public, and paste the relevant text into the issue form. Do not upload raw session files, raw logs, configuration files containing credentials, or an opaque ZIP archive. Automated redaction reduces risk but cannot guarantee that every private value is recognized.

Use the bug report form for reproducible defects and private Security Advisories for vulnerabilities.