[P0] ZARA-005 — Fix dictation lifecycle state, stale PID handling, and self-stop recovery #6

New issue

Closed

opened 2026-07-18 19:18:40 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-07-18 19:18:40 +00:00

(Migrated from github.com)

Problem

modules/dictate.pl documents dictation_active/0 as reflecting the PID file, but it only checks an in-process dynamic flag. When zara-dictate hears its own stop phrase, the subprocess exits/removes its PID file but cannot reset the parent Prolog flag. The wake loop can remain stuck in dictation mode forever.

A stale PID file is also treated as a running process, and stop_dictation/0 trusts PID-file text when constructing a shell command.

Required fix

Make process liveness/PID-file state the source of truth, with the dynamic flag only as a cache if retained.
Detect and clean stale/empty/invalid PID files.
Stop processes without constructing sh -c "kill ..."; validate the PID and use a direct process/signal API.
Ensure normal exit, voice stop, crash, and SIGTERM all return the wake listener to non-dictation mode.
Make start/stop idempotent.

Required tests

Unit/integration tests for start, duplicate start, voice self-stop, stale PID, invalid PID content, already-dead process, and cleanup after exception.
Use fake child processes; never kill arbitrary real processes.
Add scripts/test-dictation-lifecycle.sh using a temporary PID/log directory or injected paths.

Acceptance

dictation_active/0 becomes false after the child exits for any reason.
A stale PID cannot trap Zara in active dictation.
No shell interpolation is used for PID termination.
Repeated start/stop cycles pass deterministically.

Branch

fix/zara-005-dictation-lifecycle

Dependencies

ZARA-003, ZARA-004.

## Problem `modules/dictate.pl` documents `dictation_active/0` as reflecting the PID file, but it only checks an in-process dynamic flag. When `zara-dictate` hears its own stop phrase, the subprocess exits/removes its PID file but cannot reset the parent Prolog flag. The wake loop can remain stuck in dictation mode forever. A stale PID file is also treated as a running process, and `stop_dictation/0` trusts PID-file text when constructing a shell command. ## Required fix - Make process liveness/PID-file state the source of truth, with the dynamic flag only as a cache if retained. - Detect and clean stale/empty/invalid PID files. - Stop processes without constructing `sh -c "kill ..."`; validate the PID and use a direct process/signal API. - Ensure normal exit, voice stop, crash, and SIGTERM all return the wake listener to non-dictation mode. - Make start/stop idempotent. ## Required tests - Unit/integration tests for start, duplicate start, voice self-stop, stale PID, invalid PID content, already-dead process, and cleanup after exception. - Use fake child processes; never kill arbitrary real processes. - Add `scripts/test-dictation-lifecycle.sh` using a temporary PID/log directory or injected paths. ## Acceptance - `dictation_active/0` becomes false after the child exits for any reason. - A stale PID cannot trap Zara in active dictation. - No shell interpolation is used for PID termination. - Repeated start/stop cycles pass deterministically. ## Branch `fix/zara-005-dictation-lifecycle` ## Dependencies ZARA-003, ZARA-004.