Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
{
"name": "devscope",
"description": "Real-time developer activity monitoring for Claude Code sessions",
"version": "0.32.0",
"version": "0.33.0",
"author": {
"name": "Lucas Dow",
"email": "lucdow7@gmail.com"
Expand Down
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "devscope",
"version": "0.32.0",
"version": "0.33.0",
"description": "Real-time developer activity monitoring for Claude Code sessions",
"author": {
"name": "Lucas Dow",
Expand Down
24 changes: 24 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,30 @@ All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

## [0.33.0] - 2026-10-08

### Fixed
- **Sessions finishing together are all heard, in order.** Speakers now take a
ticket and the oldest live one speaks next (first come, first served). Before,
a waiter gave up after 120 s, so with three or four sessions finishing at once
the later replies were silently dropped, and `flock` woke waiters in no
particular order. A turn is now skipped only after 15 minutes
(`DS_VOICE_QUEUE_MAX_WAIT`, stale) or when its process died.
- **No more voices talking over a long explanation on macOS.** The `mkdir`
lock was taken over once it was two minutes old, which a three-minute
explanation reaches; it is now taken over only when its holder has exited.
- **Reply summaries are fetched before waiting for a turn**, so sessions do
not wait on each other's summary requests as well as their speech. (The voice
bar therefore no longer shows a "summarizing" phase.)
- **Endings cut off.** A clip whose download was cut short (curl timed out
after the `200` headers) was played with its end missing; it now counts as
failed and is fetched again. With a server that supports it, every voiced
text ends with trailing silence so outputs that close the stream early
(Bluetooth headphones) keep the last word; in long speech only the final
piece is padded, so pieces still run straight on (`pad_ms: 0`).
- `/devscope:voice stop` removes the macOS lock directory, which now holds the
holder's pid.

## [0.32.0] - 2026-10-08

### Added
Expand Down
10 changes: 10 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -219,6 +219,16 @@ claude plugin disable devscope@devscope # Disable
no voice or is unreachable it falls back to Piper if installed (`/devscope:voice setup`),
else `say`/`spd-say`/`espeak`. What is sent follows the
privacy mode: `standard` sends no more than its events do. Tests: `tests/voice/run.sh`.
- **Speech queue** (`_ds_voice_with_lock`): every speaker (timer announcements, `speak.sh`
replies and explanations) writes `queue/<ns>-<pid>`; the oldest ticket whose pid is alive is
next, and the lock (flock, or on macOS a `speak.lock.d/pid` taken over only when that pid is
dead) makes overlap impossible. No fixed wait: a turn is dropped only after
`DS_VOICE_QUEUE_MAX_WAIT` (900 s) or when its process died. Reply summaries are fetched before
the turn (in `speak.sh`), not under it. Tests set `DS_VOICE_NO_FLOCK=1` to exercise the macOS
path, and `DS_VOICE_TEST_SPEAK_SEC` / `DS_VOICE_TIMELINE` to give fake speech a duration.
- **Endings**: `_ds_voice_server_fetch` needs curl's exit status 0 as well as `200 audio/*` (a
timeout mid-body still reports 200). It passes `pad_ms` to voice-audio: `0` for every piece of
long speech but the last, so only the end carries the server's trailing silence.
- **Session labels** (`labels/<session>`): every summary request sends `session_id` and, once known,
the session's `label`. The server answers with text that already starts with the label and returns
`label` ("project, topic" from the session title, else its branch); `_ds_voice_summary` keeps the
Expand Down
5 changes: 3 additions & 2 deletions scripts/voice/cli.sh
Original file line number Diff line number Diff line change
Expand Up @@ -223,8 +223,9 @@ stop() {
rm -f "$f"
done
rm -f "$DS_VOICE_DIR/say/"*.json "$DS_VOICE_DIR/replies/"*.json "$DS_VOICE_PROGRESS" 2>/dev/null
# macOS lock: a killed holder leaves its directory behind.
[ "$n" -gt 0 ] && rmdir "$DS_VOICE_DIR/speak.lock.d" 2>/dev/null
# macOS lock: a killed holder leaves its directory (with its pid) behind.
# Queue tickets of killed speakers are pruned by the next one to look.
[ "$n" -gt 0 ] && rm -rf "$DS_VOICE_DIR/speak.lock.d" 2>/dev/null
echo "Stopped ($n speaking)."
}

Expand Down
104 changes: 81 additions & 23 deletions scripts/voice/lib.sh
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,9 @@
# progress.json what the speaking speak.sh is doing, for the
# devscope-live mod's progress bar.
# speak.lock serializes speech across all sessions.
# queue/<ns>-<pid> one ticket per process waiting to speak; the oldest
# live ticket speaks next, so speech is first come,
# first served.
# voice.log errors and announcements.

DS_VOICE_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
Expand All @@ -44,6 +47,9 @@ DS_VOICE_REMINDER_INTERVAL=300
DS_VOICE_MAX_REMINDERS=3
# Floor for reminder_interval, so a 0 cannot loop speech back to back.
DS_VOICE_MIN_REMINDER_INTERVAL=5
# How long a text may wait its turn to be spoken before it is dropped as stale.
# Several sessions finishing together each speak in full, in order.
DS_VOICE_QUEUE_MAX_WAIT="${DS_VOICE_QUEUE_MAX_WAIT:-900}"
# Longest single sleep in timer.sh, so off/unmute/re-arm are noticed promptly.
DS_VOICE_MAX_SLEEP=30
# While the screen is locked, a due announcement is checked again this often,
Expand Down Expand Up @@ -84,7 +90,7 @@ DS_VOICE_REPLY_TAIL=1100
# State and log can hold summaries of the user's work: keep them owner-only.
_ds_voice_mkdirs() {
( umask 077; mkdir -p "$DS_VOICE_PENDING" "$DS_VOICE_DIR/replies" "$DS_VOICE_DIR/say" \
"$DS_VOICE_DIR/spoke" "$DS_VOICE_DIR/speakers" "$DS_VOICE_DIR/auto" "$DS_VOICE_DIR/labels" ) 2>/dev/null
"$DS_VOICE_DIR/spoke" "$DS_VOICE_DIR/speakers" "$DS_VOICE_DIR/auto" "$DS_VOICE_DIR/labels" "$DS_VOICE_DIR/queue" ) 2>/dev/null
}

# --- Session labels ---
Expand Down Expand Up @@ -708,26 +714,69 @@ _ds_voice_announce_due() {
}

# Run a command while holding the global speak lock.
# Run a command when it is this process's turn to speak. Every speaker takes a
# ticket; the oldest ticket whose process is alive goes next, and the lock
# keeps two speakers from ever overlapping. Nothing waits on a fixed timeout:
# a turn is skipped only when it waited DS_VOICE_QUEUE_MAX_WAIT (stale) or its
# holder died, so sessions finishing at the same time are all heard, in order.
_ds_voice_with_lock() {
local lock="$DS_VOICE_DIR/speak.lock" i=0
local q="$DS_VOICE_DIR/queue" lock="$DS_VOICE_DIR/speak.lock" ticket start
_ds_voice_mkdirs
if command -v flock >/dev/null 2>&1; then
( flock -w 120 9 || exit 0; "$@" ) 9>"$lock"
ticket="$q/$(_ds_now_ns)-$$"
( umask 077; : > "$ticket" ) 2>/dev/null || return 0
start=$(date +%s)
while [ -e "$ticket" ]; do
if [ "$(_ds_voice_queue_head)" = "$ticket" ]; then
# DS_VOICE_NO_FLOCK (tests): take the macOS path on Linux too.
if [ -z "${DS_VOICE_NO_FLOCK:-}" ] && command -v flock >/dev/null 2>&1; then
# The ticket goes once the turn is over, so the next one waits for it.
( flock -w 5 9 || exit 0; "$@"; rm -f "$ticket" ) 9>"$lock"
elif _ds_voice_mkdir_lock "$lock.d"; then
"$@"; rm -f "$ticket"
rm -rf "$lock.d"
fi
fi
[ -e "$ticket" ] || break
if [ $(( $(date +%s) - start )) -ge "$DS_VOICE_QUEUE_MAX_WAIT" ]; then
_ds_voice_log "waited ${DS_VOICE_QUEUE_MAX_WAIT}s to speak: dropped as stale"
rm -f "$ticket"
break
fi
sleep 0.2
done
return 0
}

# The oldest ticket whose process is still alive. Tickets of processes that
# died (killed, crashed, closed laptop) are removed, so they never block.
_ds_voice_queue_head() {
local t pid
for t in $(ls "$DS_VOICE_DIR/queue" 2>/dev/null | sort); do
pid=${t##*-}
if kill -0 "$pid" 2>/dev/null; then
printf '%s/queue/%s' "$DS_VOICE_DIR" "$t"
return 0
fi
rm -f "$DS_VOICE_DIR/queue/$t"
done
}

# macOS has no flock: mkdir is atomic. The holder writes its pid inside, and
# the lock is taken over only when that process is gone, never because speech
# ran long (an age rule let a waiter talk over a long explanation).
_ds_voice_mkdir_lock() { # lock-dir
local holder
if mkdir "$1" 2>/dev/null; then
printf '%s' "$$" > "$1/pid"
return 0
fi
# macOS has no flock: mkdir is atomic. A holder killed mid-speech leaves the
# directory behind, so one older than two minutes is taken over.
until mkdir "$lock.d" 2>/dev/null; do
holder=$(cat "$1/pid" 2>/dev/null)
if { [ -n "$holder" ] && ! kill -0 "$holder" 2>/dev/null; } || \
{ [ -z "$holder" ] && [ -n "$(find "$1" -maxdepth 0 -mmin +1 2>/dev/null)" ]; }; then
# Rename before removing: only one waiter can win the rename.
[ -n "$(find "$lock.d" -maxdepth 0 -mmin +2 2>/dev/null)" ] && \
mv "$lock.d" "$lock.d.stale.$$" 2>/dev/null && rmdir "$lock.d.stale.$$" 2>/dev/null
i=$((i + 1))
[ "$i" -gt 400 ] && return 0
sleep 0.3
done
"$@"
rmdir "$lock.d" 2>/dev/null
return 0
mv "$1" "$1.stale.$$" 2>/dev/null && rm -rf "$1.stale.$$"
fi
return 1
}

# --- Speech engines ---
Expand All @@ -747,25 +796,29 @@ _ds_voice_server() { # text privacy

# Fetch the server voice for a text (at most 440 characters) into a WAV file,
# trying a passing failure again up to `attempts` times in all (default 2).
_ds_voice_server_fetch() { # text privacy out-file [attempts]
local body code cfg="" attempt=1 attempts="${4:-2}"
_ds_voice_server_fetch() { # text privacy out-file [attempts] [pad-ms]
local body code cfg="" attempt=1 attempts="${4:-2}" pad="${5:-}" rc
[ "${2:-standard}" != "private" ] && [ -n "${DEVSCOPE_API_KEY:-}" ] || return 1
# volume is only sent when set, so the server's default applies otherwise.
# `model` picks the server's voice by name (/devscope:voice model); unset, the
# server's default. `voice` is a Kokoro voice name, ignored by other voices.
body=$(jq -nc --arg t "$1" --arg v "$(_ds_voice_conf .voice "$DS_VOICE_SERVER_VOICE")" \
--arg model "$(_ds_voice_conf .model "")" \
--argjson s "$(_ds_voice_speed)" \
--arg vol "$(_ds_voice_conf .volume "")" \
--arg vol "$(_ds_voice_conf .volume "")" --arg pad "$pad" \
'{text: $t, voice: $v, speed: $s} + (if $vol == "" then {} else {volume: ($vol | tonumber)} end)
+ (if $model == "" then {} else {model: $model} end)' 2>/dev/null) || return 1
+ (if $model == "" then {} else {model: $model} end)
+ (if $pad == "" then {} else {pad_ms: ($pad | tonumber)} end)' 2>/dev/null) || return 1
cfg="header = \"x-api-key: ${DEVSCOPE_API_KEY}\""
while :; do
code=$(printf '%s' "$cfg" | curl --config - -s -o "$3" -w '%{http_code} %{content_type}' \
-X POST "${DEVSCOPE_URL}/api/ai/voice-audio" -H "x-requested-with: devscope-cli" \
-H "Content-Type: application/json" -d "$body" --max-time "$DS_VOICE_SERVER_TIMEOUT" 2>/dev/null)
rc=$?
# The status arrives with the headers: a download cut short (curl timed out
# mid-body) still says 200 and would play with its ending missing.
case "$code" in
"200 audio/"*) return 0 ;;
"200 audio/"*) [ "$rc" -eq 0 ] && return 0; code="000 partial (curl $rc)" ;;
esac
case "${code%% *}" in
401|429|502|503|504|000|'') ;;
Expand Down Expand Up @@ -876,6 +929,9 @@ _ds_voice_speak() { # text [privacy]
engine=$(_ds_voice_conf .engine auto)
[ "$engine" = "off" ] && return 0
if [ -n "${DS_VOICE_SPEAK_LOG:-}" ]; then # test hook
[ -n "${DS_VOICE_TIMELINE:-}" ] && printf 'start %s %s\n' "$(_ds_now_ns)" "$1" >> "$DS_VOICE_TIMELINE"
[ -n "${DS_VOICE_TEST_SPEAK_SEC:-}" ] && sleep "$DS_VOICE_TEST_SPEAK_SEC"
[ -n "${DS_VOICE_TIMELINE:-}" ] && printf 'end %s %s\n' "$(_ds_now_ns)" "$1" >> "$DS_VOICE_TIMELINE"
printf '%s\n' "$1" >> "$DS_VOICE_SPEAK_LOG"
[ -n "${DS_VOICE_PRIVACY_LOG:-}" ] && printf '%s\n' "$privacy" >> "$DS_VOICE_PRIVACY_LOG"
return 0
Expand Down Expand Up @@ -1004,7 +1060,8 @@ _ds_voice_speak_long() { # text [privacy]
_ds_voice_can_play || { _ds_voice_log "screen locked: speech not started"; return 0; }
dir=$(mktemp -d "${TMPDIR:-/tmp}/ds-voice.XXXXXX") || return 0
_ds_voice_progress voicing 0 "$n"
if ! _ds_voice_server_fetch "${chunks[0]}" "$privacy" "$dir/0.wav"; then
# Only the last piece ends with padding; the others run straight on.
if ! _ds_voice_server_fetch "${chunks[0]}" "$privacy" "$dir/0.wav" 2 "$( [ "$n" -gt 1 ] && echo 0)"; then
while [ "$i" -lt "$n" ]; do
_ds_voice_can_play || { _ds_voice_log "screen locked: speech stopped"; break; }
_ds_voice_progress speaking "$i" "$n"
Expand All @@ -1019,7 +1076,8 @@ _ds_voice_speak_long() { # text [privacy]
if [ $((i + 1)) -lt "$n" ]; then
# Mid-speech, a switch to the local voice is jarring: try harder (this
# runs while the current piece plays, so the wait is mostly hidden).
_ds_voice_server_fetch "${chunks[$((i + 1))]}" "$privacy" "$dir/$((i + 1)).wav" 4 &
_ds_voice_server_fetch "${chunks[$((i + 1))]}" "$privacy" "$dir/$((i + 1)).wav" 4 \
"$( [ $((i + 2)) -lt "$n" ] && echo 0)" &
next=$!
fi
if ! _ds_voice_can_play; then
Expand Down
11 changes: 5 additions & 6 deletions scripts/voice/speak.sh
Original file line number Diff line number Diff line change
Expand Up @@ -31,18 +31,17 @@ case "${1:-}" in
export DS_VOICE_PROGRESS_KIND=reply
DS_VOICE_PROGRESS_PROJECT=$(jq -r '.project // ""' "$JOB" 2>/dev/null)
export DS_VOICE_PROGRESS_PROJECT
# Summarized before waiting for a turn: sessions that finish together get
# their summaries in parallel instead of each waiting on the others' calls.
TEXT=$(_ds_voice_reply_text "$JOB") || exit 0
PRIVACY=$(jq -r '.privacy' "$JOB" 2>/dev/null)
speak_reply() {
local text privacy
local text="$TEXT" privacy="$PRIVACY"
# A newer reply from the same session replaces this one.
current || return 0
_ds_voice_muted && return 0
# Locked while it waited its turn: skip, as when queued.
_ds_voice_can_play || return 0
# Summarized under the lock, so the progress bar covers it too.
_ds_voice_progress summarizing
text=$(_ds_voice_reply_text "$JOB") || return 0
privacy=$(jq -r '.privacy' "$JOB" 2>/dev/null)
current || return 0
_ds_voice_log "speak reply: $text"
_ds_voice_speak_long "$text" "$privacy"
current && rm -f "$JOB"
Expand Down
79 changes: 79 additions & 0 deletions tests/voice/run.sh
Original file line number Diff line number Diff line change
Expand Up @@ -495,6 +495,85 @@ for p in alpha beta gamma; do DEVSCOPE_PRIVACY=private hook permission-request.s
wait_spoken 1 10; sleep 1
[ "$(spoken)" = "three sessions need you: oauth login in alpha, rate limit in beta and gamma." ] && ok "labels: batch names topic in project" || bad "label batch" "$(spoken)"

# 16. Several sessions finishing at once: every reply is spoken, one at a time,
# first come first served (speech takes 1.5 s each here).
TL="$TMP/timeline"
queue_case() { # label [env...]
local label="$1"; shift
reset; rm -f "$TL"; "$S/voice/cli.sh" auto-default on >/dev/null
respond '{"text": "summary"}'
for n in 1 2 3 4; do
respond "{\"text\": \"session $n done.\"}"
env "$@" DS_VOICE_TIMELINE="$TL" DS_VOICE_TEST_SPEAK_SEC=1.5 \
bash -c 'jq -n --arg s "q'"$n"'" "{session_id: \$s, cwd: \"/work/p'"$n"'\", hook_event_name: \"Stop\", last_assistant_message: \"Done.\"}" | "$0/response-stop.sh" >/dev/null 2>&1' "$S"
sleep 0.3
done
wait_spoken 4 20
local starts ends overlap order
starts=$(grep -c "^start" "$TL" 2>/dev/null || true); ends=$(grep -c "^end" "$TL" 2>/dev/null || true)
# No speech starts before the previous one ended.
overlap=$(awk '$1 == "start" { if (busy) bad = 1; busy = 1 } $1 == "end" { busy = 0 } END { print bad + 0 }' "$TL" 2>/dev/null || true)
order=$(grep "^start" "$TL" 2>/dev/null | grep -o "session [0-9]" | tr -d "session " | tr -d "\n" || true)
[ "$starts" = 4 ] && [ "$ends" = 4 ] && ok "queue ($label): all four replies spoken" || bad "queue $label count" "$(cat "$TL")"
[ "$overlap" = 0 ] && ok "queue ($label): never two voices at once" || bad "queue $label overlap" "$(cat "$TL")"
[ "$order" = 1234 ] && ok "queue ($label): spoken in the order the sessions finished" || bad "queue $label order" "$order"
"$S/voice/cli.sh" auto-default off >/dev/null
}
queue_case flock
queue_case "macOS lock" DS_VOICE_NO_FLOCK=1

# A ticket left by a process that died does not block the queue.
reset; Q="$HOME/.cache/devscope/voice/queue"; mkdir -p "$Q"
sleep 0.01 & deadpid=$!; wait "$deadpid"
: > "$Q/0000000000000000001-$deadpid"
out=$( . "$S/_helpers.sh"; . "$S/voice/lib.sh"; DS_VOICE_QUEUE_MAX_WAIT=5; _ds_voice_with_lock echo ran )
[ "$out" = ran ] && [ ! -e "$Q/0000000000000000001-$deadpid" ] && ok "queue: a dead process's ticket is skipped and removed" || bad "dead ticket" "$out $(ls "$Q")"

# macOS lock: a live holder is waited for however long it speaks; a dead one is taken over.
LD="$HOME/.cache/devscope/voice/speak.lock.d"
sleep 3 & holder=$!
rm -rf "$LD"; mkdir -p "$LD"; printf '%s' "$holder" > "$LD/pid"; touch -d '10 minutes ago' "$LD" 2>/dev/null || true
t0=$(date +%s)
out=$( . "$S/_helpers.sh"; . "$S/voice/lib.sh"; DS_VOICE_NO_FLOCK=1; _ds_voice_with_lock echo ran )
waited=$(( $(date +%s) - t0 ))
[ "$out" = ran ] && [ "$waited" -ge 2 ] && ok "macOS lock: an old but live holder is not talked over" || bad "mkdir live" "out=$out waited=${waited}s"
rm -rf "$LD"; mkdir -p "$LD"; printf '%s' "$deadpid" > "$LD/pid"
out=$( . "$S/_helpers.sh"; . "$S/voice/lib.sh"; DS_VOICE_NO_FLOCK=1; _ds_voice_with_lock echo ran )
[ "$out" = ran ] && ok "macOS lock: a dead holder's lock is taken over" || bad "mkdir dead" "$out"
rm -rf "$LD"

# 17. Endings. A fake curl logs each request and plays back a status.
FAKE="$TMP/fakebin"; mkdir -p "$FAKE"
cat > "$FAKE/curl" <<'EOF'
#!/usr/bin/env bash
out=""; body=""
while [ $# -gt 0 ]; do
case "$1" in -o) out="$2"; shift ;; -d) body="$2"; shift ;; esac; shift
done
printf '%s\n' "$body" >> "$FAKE_CURL_LOG"
[ -n "$out" ] && printf 'RIFFxxxxWAVE' > "$out"
printf '200 audio/wav'
exit "${FAKE_CURL_EXIT:-0}"
EOF
chmod +x "$FAKE/curl"
fetch() { ( export PATH="$FAKE:$PATH" FAKE_CURL_LOG="$TMP/curl.log" FAKE_CURL_EXIT="$1"
. "$S/_helpers.sh"; . "$S/voice/lib.sh"; DS_VOICE_SERVER_RETRY_DELAY=0
_ds_voice_server_fetch "hello" standard "$TMP/out.wav" 1 ); }
rm -f "$TMP/curl.log"
fetch 0 && ok "endings: a complete download plays" || bad "fetch ok" "$(cat "$TMP/curl.log")"
fetch 28 && bad "endings: partial download" "a 200 cut short by a timeout was accepted" || ok "endings: a 200 cut short (curl timeout) is not played"

# Long speech: only the last piece is padded with silence.
rm -f "$TMP/curl.log"
( export PATH="$FAKE:$PATH" FAKE_CURL_LOG="$TMP/curl.log"; unset DS_VOICE_SPEAK_LOG
. "$S/_helpers.sh"; . "$S/voice/lib.sh"
_ds_voice_play() { :; }
_ds_voice_speak_long "$LONG" standard )
pieces=$(grep -c . "$TMP/curl.log")
pads=$(jq -r '.pad_ms // "default"' "$TMP/curl.log" | tr '\n' ' ')
expected="$(printf '0 %.0s' $(seq 2 "$pieces"))default "
[ "$pieces" -ge 2 ] && [ "$pads" = "$expected" ] && ok "endings: pieces run on, only the last gets trailing silence ($pieces pieces)" || bad "pad" "$pads"

reset
echo "---"; echo "$pass passed, $fail failed"
[ "$fail" -eq 0 ]
Loading