Adr/Proposals/ADR 002 Structured Hook Logging Copy Section

ADR-002: Structured Hook Logging via Inline Phase Emitters

Status: Accepted | Date: 2026-03-25 | Accepted: 2026-03-25 | Deciders: cameron

Context Copy Chapter

peon-ping's hook scripts (peon.sh and peon.ps1) are silent-failure-by-design: every try/except falls back to defaults, every missing config key gets a safe value. This means the system keeps running even when it's broken — but gives users zero visibility into why sounds stopped, notifications vanished, or hooks started timing out.

The current diagnostic surface is:

- Unix: A commented-out echo line in peon.sh that dumps raw stdin to /tmp/peon-ping-debug.log. Requires editing source. Additionally, the Python block's stderr is redirected to /dev/null (2>/dev/null on the python3 -c invocation), meaning any diagnostic output from the decision pipeline is silently swallowed.
- Windows: PEON_DEBUG=1 env var in win-play.ps1 that emits Write-Warning for audio failures only — covers none of config loading, event routing, pack selection, or state management.
- All platforms: .state.json is readable but has no timestamps and no event history.

Three pressures make this urgent now:

1. Dual-codebase parity. The Windows hook script (peon.ps1, deployed from install.ps1) is a separate ~1,650-line implementation with its own failure modes and essentially no diagnostics.
2. Pipeline complexity. The Unix Python block is ~765 lines handling 11 event types across 7 CESP categories, with pack rotation (3 modes), path rules, trainer reminders, notification templates, and multi-IDE adapter translation. When something breaks mid-pipeline, the only signal is absence of sound.
3. Worktree concurrency. Sprint dispatchers running 5-20 parallel agents in worktrees fire hooks concurrently against shared global state. Suppression decisions (delegate mode, debounce, cooldowns) are invisible — there's no way to tell which agent's hook fired, what it decided, or whether it was killed by timeout.

The fundamental tension is: observability vs. performance and simplicity. The hook runs in a constrained environment (8-second self-imposed timeout, 10-second Claude Code timeout, ~120-200ms typical execution) and must never break audio playback. Any logging architecture must have zero cost when disabled and negligible cost when enabled.

Decision Copy Chapter

We will add inline phase-emitting log calls at each decision point in both peon.sh (Python block) and peon.ps1 (PowerShell), writing append-only log lines to daily-rotated files under $PEON_DIR/logs/. Logging is gated on a debug boolean in config.json (default false) with a PEON_DEBUG=1 env var override. A peon debug on|off CLI command toggles the config key. A peon logs CLI command reads log files with basic filtering.

Log format is human-readable key=value lines, one per phase. Every line carries a short invocation ID (inv=) so concurrent hook executions can be correlated even when interleaved:

2026-03-25T14:22:01.003 [hook] inv=7a3f event=Stop session=abc123 cwd=/home/user/proj
2026-03-25T14:22:01.005 [config] inv=7a3f loaded=/home/user/.openpeon/config.json volume=0.5 pack=glados
2026-03-25T14:22:01.008 [route] inv=7a3f category=task.complete suppressed=false
2026-03-25T14:22:01.010 [sound] inv=7a3f file=mission-complete.wav pack=glados candidates=4
2026-03-25T14:22:01.012 [play] inv=7a3f backend=afplay pid=48291 async=true
2026-03-25T14:22:01.013 [exit] inv=7a3f duration_ms=10 exit=0

Values containing spaces or special characters are double-quoted. Values without spaces are unquoted. This keeps simple cases scannable while remaining unambiguous:

2026-03-25T14:22:01.003 [hook] inv=7a3f event=Stop session=abc123 cwd="/home/user/my project"
2026-03-25T14:22:01.010 [notify] inv=7a3f desktop=true template="✅ {project}: done" rendered="✅ my project: done"

Each invocation logs 6-10 lines covering phases: [hook], [config], [state], [route], [sound], [play], [notify], [trainer], [exit]. Every suppression, debounce, fallback, and error path logs why it happened. If a hook is killed by timeout before emitting [exit], the incomplete invocation is identifiable by its inv= prefix — all preceding lines for that invocation are present and the absence of [exit] is itself diagnostic.

Log files are daily (peon-ping-YYYY-MM-DD.log), pruned on each invocation based on debug_retention_days (default 7). Files live in $PEON_DIR/logs/, created on first write.

Rationale Copy Chapter

Key Factors Copy Section

1. Inline emitters over a logging framework. The Python block runs inside a bash here-doc and the PowerShell script is embedded in install.ps1. Neither environment supports importing external logging libraries cleanly. Inline log("phase", "key=val ...") calls — where log is a no-op lambda when disabled — match the existing code structure and keep the dependency footprint at zero.

2. Daily file rotation over size-based rotation. Size-based rotation requires tracking file size on every write and handling rollover atomically during concurrent appends. Date-based rotation is trivially correct: each invocation opens today's file and deletes files whose datestamp is older than the retention window. Solo developers generate 10-50 invocations/day; sprint dispatch operators running 20 concurrent agents may hit 200-500. At ~100 bytes per log line and 8 lines per invocation, even the sprint case produces ~400 KB/day — well under 1 MB per daily file.

3. Key=value format over JSON lines. The PRD explicitly identifies the primary consumer as a human reading a file. Key=value lines are immediately scannable, grep-able, and don't require jq to read. Values containing spaces or special characters are double-quoted; values without spaces are unquoted. Both implementations must follow this convention — the shared test fixture includes edge-case inputs (paths with spaces, notification templates with braces and emoji) to enforce it. If machine-parseable output becomes necessary later, a debug_format: "jsonl" config key can be added — the call sites pass structured data already, so adding a JSON formatter is a small refactor (~10 sites per platform).

4. Single boolean over leveled logging. Adding info/debug/trace levels introduces a decision at every call site ("is this info or debug?") and a usability question for users ("which level do I need?"). The PRD's three user segments (solo debugger, sprint operator, contributor) all need the same information: the full decision chain. Starting with a single boolean that emits everything keeps the implementation simple. Levels can be added later if the single level proves too noisy, with the no-op-when-disabled pattern unchanged.

5. Global log directory over per-worktree logs. Worktrees are temporary directories cleaned up when the agent finishes. Per-worktree logs would be lost. Global logs with cwd and session fields per line let users filter by worktree path (grep "/tmp/worktrees/feature-auth") while keeping all activity visible in one place for sprint operators.

Consequences Copy Chapter

Positive Copy Section

- Users can diagnose the five most common failure modes (missing audio backend, bad config, pack not installed, timeout, state lock contention) from log output alone, without reading source or filing a GitHub issue.
- Sprint operators can correlate concurrent hook invocations by session ID and worktree path, making delegate-mode suppression, debounce decisions, and timeout kills visible.
- Contributors testing new adapters or modifying the Python block can see the full event-to-sound decision chain without adding temporary print statements.

Negative Copy Section

- Every code change to the decision pipeline requires adding or updating log calls in two independent implementations (Python and PowerShell). There is no shared code — format drift between platforms is a real risk. Mitigated by shared test fixtures: known JSON input producing expected log output, validated by both BATS and Pester.
- The debug config key and peon debug/peon logs CLI commands add surface area to the CLI and config schema. These are permanent additions that must be maintained across both platforms.
- On Windows, Add-Content uses a lock-open-seek-write-close cycle rather than POSIX O_APPEND atomic semantics. Under heavy concurrent load (20+ agents in sprint dispatch), lock contention may cause an IOException, which the try/catch guard handles by disabling logging for the remainder of that invocation. This means some Windows log entries may be dropped under extreme concurrency — an acceptable tradeoff given the "logging must never break the hook" principle, but an asymmetry with Unix where O_APPEND writes under PIPE_BUF are guaranteed atomic.

Neutral Copy Section

- The PEON_DEBUG=1 env var in win-play.ps1 continues to work as before (stderr Write-Warning for audio failures). When the new logging is also active, both outputs fire — they are additive, not conflicting.
- Log files are not a stable API. Users who build tooling on top of the log format do so at their own risk. This is documented explicitly.

Alternatives Considered Copy Chapter

Alternative 1: External Logging Library (Python logging / PowerShell Start-Transcript) logging / PowerShell Start-Transcript)')" title="Copy section prompt for LLMs"> Copy Section

Description: Use Python's built-in logging module in peon.sh's Python block and PowerShell's Start-Transcript or a third-party module in peon.ps1. Configure handlers for file output with rotation.

Pros:
- Python logging provides leveled output, configurable formatters, and RotatingFileHandler out of the box.
- Start-Transcript captures all PowerShell output automatically — zero manual instrumentation.

Cons:
- The Python block runs inside a bash here-doc (python3 -c "..."). Importing logging and configuring handlers adds ~10 lines of boilerplate and a measurable startup cost (~15-30ms for module import + handler setup) on every invocation, even when logging is disabled, unless the import itself is gated behind the debug check — which negates the benefit of using the module.
- Start-Transcript captures everything (verbose/debug streams, command output, errors) with no phase structure. The output is a wall of text, not parseable log entries. It also writes to a separate file per session, not a shared daily log — breaking the "one log directory, filter by session" model.
- Neither approach produces cross-platform-identical output. Format drift risk remains, just hidden behind framework differences.

Why not chosen: The overhead of importing logging on every invocation (even when disabled) violates the zero-cost-when-disabled requirement. Start-Transcript produces unstructured output that doesn't serve the debugging use cases. Inline emitters are lighter, more predictable, and produce identical format on both platforms by construction.

Alternative 2: Structured JSON Log Lines (JSONL) Copy Section

Description: Each log entry is a JSON object on one line. Tools like jq can filter and transform. Format: {"ts":"2026-03-25T14:22:01.003","phase":"hook","event":"Stop","session":"abc123","cwd":"/home/user/proj"}.

Pros:
- Machine-parseable out of the box. Enables future tooling (log viewers, CI analysis, peon logs --json).
- No ambiguity in parsing — keys and values are always properly quoted and escaped.
- Could support a peon logs --filter 'phase=route AND suppressed=true' command trivially.

Cons:
- Less scannable for humans. Reading raw JSONL requires mental parsing or jq for any non-trivial query. The primary user segment (solo developer reading a log file to find why sounds stopped) would have a worse experience.
- JSON serialization on every log call adds overhead: json.dumps() in Python, ConvertTo-Json in PowerShell. Small per-call, but 6-10 calls per invocation adds up vs. simple string formatting.
- Requires escaping values that contain special characters (file paths with spaces, notification template strings with quotes). Key=value format handles this with simpler conventions.

Why not chosen: The primary consumer is a human reading a file. Key=value lines serve that use case better. If machine-parseable output becomes necessary, adding debug_format: "jsonl" as a config option later is straightforward — the inline emitters already pass structured data, so adding a JSON code path is a small refactor, not a rewrite.

Alternative 3: Stderr-Based Logging — Remove 2>/dev/null and Print Diagnostics to Stderr 2>/dev/null and Print Diagnostics to Stderr')" title="Copy section prompt for LLMs"> Copy Section

Description: Instead of building file-based logging infrastructure, remove the 2>/dev/null redirect on the Python block invocation (peon.sh:3780), gate print(..., file=sys.stderr) calls behind the debug flag, and let users capture diagnostics via shell redirection (peon.sh 2>>debug.log). On Windows, use Write-Warning (which already writes to the warning stream) for diagnostic output beyond the existing audio-only scope.

Pros:
- Dramatically simpler implementation. No log directory management, no daily rotation, no peon logs CLI command, no file I/O in the hot path. The only code change is adding print() calls to stderr behind a boolean check.
- Zero new infrastructure — uses the OS-provided diagnostic channel that already exists.
- Users who want persistent logs can redirect stderr themselves. Users who want one-off debugging see output immediately in the terminal.

Cons:
- Claude Code captures hook stdout but does not surface hook stderr to the user — stderr from hooks is discarded by the host process. Removing 2>/dev/null in peon.sh would let stderr flow to Claude Code's process, but the user would never see it. This is the fundamental reason stderr-based logging doesn't work for the primary use case: a user who runs peon debug on and then uses Claude Code normally needs diagnostics to land in a file they can read later, not in a stream that Claude Code silently discards.
- On Windows, peon.ps1 is invoked by Claude Code as a hook subprocess. PowerShell's warning stream (Write-Warning) is similarly not surfaced to the user — it would only be visible if the user ran peon.ps1 manually from a terminal, which is not the normal execution path.
- No historical log — stderr is ephemeral. Sprint operators debugging an issue that happened 10 minutes ago in one of 20 concurrent agents have nothing to look at. The "what just happened" use case requires persistent storage.
- No worktree correlation — stderr output from concurrent hooks interleaves with no session or invocation identifier unless the user manually sets up per-agent redirection, which is impractical in automated dispatch.

Why not chosen: The hook's execution context makes stderr non-viable as the primary diagnostic channel. Claude Code discards hook stderr, so the user never sees it. The 2>/dev/null on peon.sh's Python block exists because stderr output was never useful in hook context — removing it wouldn't change that, because the output would flow to Claude Code's process and be discarded there instead. File-based logging is more infrastructure, but it's the only approach that produces output the user can actually read after the fact.

Alternative 4: Do Nothing — Improve Ad-Hoc Debugging Guides Copy Section

Description: Instead of building logging infrastructure, document the existing debugging approaches better: how to uncomment the debug line in peon.sh, how to use PEON_DEBUG=1 on Windows, how to read .state.json, and common failure patterns.

Pros:
- Zero code changes. No new config keys, no new CLI commands, no dual-implementation maintenance burden.
- No risk of logging I/O causing timeout issues.
- Unblocks no-one but also breaks nothing.

Cons:
- Does not actually solve the problem. Users still can't diagnose issues without editing source code (Unix) or getting only audio-layer diagnostics (Windows). The five most common failure modes (missing backend, bad config, missing pack, timeout, state lock) remain invisible.
- Worktree concurrency debugging remains impossible — .state.json has no per-invocation history.
- Every GitHub issue about "peon-ping doesn't work" will still require a back-and-forth to establish basic facts about the execution environment, because there's no log to attach.
- Contributors and adapter authors still resort to temporary print statements.

Why not chosen: The problem is real and recurring (GitHub #402, #397). Documentation can help users who already know what to look for, but it cannot surface information that the system doesn't record. The maintenance cost of inline log calls is modest compared to the ongoing support cost of debugging blind.

Implementation Notes Copy Chapter

Phase 1: Core Logging in Hook Scripts Copy Section

- Add debug (boolean, default false) and debug_retention_days (integer, default 7) to config.json.
- In the Python block (peon.sh:~3016): define a log() function gated on cfg.get('debug', False) or os.environ.get('PEON_DEBUG') == '1'. When disabled, log is a no-op lambda assigned before any I/O. When enabled, it opens $PEON_DIR/logs/peon-ping-YYYY-MM-DD.log in append mode and writes formatted lines.
- In peon.ps1: equivalent $peonLog function using Add-Content. Same gating logic.
- Add log calls at each phase: [hook], [config], [state], [route], [sound], [play], [notify], [trainer], [exit].
- Rotation: when logging is enabled and the invocation opens a new daily log file (today's file didn't exist yet), prune files older than debug_retention_days via os.listdir() / Get-ChildItem. This avoids redundant directory scans on every invocation — pruning only runs once per day, on the first hook invocation that creates the new file.
- All logging wraps in try/catch — any I/O failure disables logging for the rest of the invocation. Logging must never break the hook.

Phase 2: CLI Commands Copy Section

- peon debug on|off|status — modifies debug in config.json.
- peon logs [--last N] [--session ID] [--clear] — reads/filters/manages log files.
- Update completions.bash and completions.fish.

Phase 3: Documentation Copy Section

- README.md "Debugging" section, README_zh.md translated equivalent, docs/public/llms.txt.

Cross-Platform Test Fixture Copy Section

To prevent format drift between the Python and PowerShell implementations, create a shared test fixture: a set of known JSON hook inputs with expected log output. Both BATS tests (validating peon.sh output) and Pester tests (validating peon.ps1 output) assert against the same expected output. Any format divergence fails CI on both platforms.

Validation Copy Chapter

- Zero-overhead when disabled: Benchmark peon.sh with debug: false vs. a version with no logging code at all. Target: <1ms difference (measured as the delta in $_PEON_PYOUT generation time).
- Actionable diagnosis: Given the 5 common failure modes (missing audio backend, bad config, pack not installed, hook timeout, state lock contention), a tester enables debug logging, triggers the failure, and identifies the root cause from log output alone — all 5 must be diagnosable without reading source.
- Log rotation: After 7 simulated days of logging (create 10 dated log files), rotation prunes files older than debug_retention_days. Verified in both BATS and Pester.
- Worktree safety: 10 concurrent hook invocations appending to the same log file produce 10 complete, non-interleaved log entries. Verified via a BATS test that runs hooks in parallel and asserts line integrity.
- Cross-platform parity: The shared test fixture (same JSON input, same expected log output) passes on both macOS (BATS) and Windows (Pester) in CI.
- Revisit trigger: If typical invocation time with logging enabled exceeds 250ms (current baseline ~120-200ms + 5ms logging budget), investigate whether log I/O is the cause and consider buffering writes to a single flush.

Related Decisions Copy Chapter

- ADR-001: Async Audio and Safe State on Windows — M0 reliability work that established the 8-second safety timeout, atomic state writes, and PEON_DEBUG env var in win-play.ps1. ADR-001 was never formally written; its docs_ref in the roadmap is aspirational. The decisions it covers (detached audio, atomic state I/O) are prerequisites for this ADR's logging design.

References Copy Chapter

- PRD-002: Hook Observability — product requirements driving this decision
- CESP v1.0 Specification — the event category schema that logging must cover
- Claude Code hooks documentation — hook timeout behavior, JSON payload schema
- POSIX write(2) atomicity — guarantees for concurrent O_APPEND writes under PIPE_BUF
- GitHub #402, #397 — open bugs that motivated this work

---

Revision History Copy Chapter

---

Adr/ADR 001 Tts Backend Architecture Copy Section

ADR-001: TTS Backend Architecture — Independent Scripts over Plugin Registry

Status: Accepted | Date: 2026-03-28 | Deciders: cameron

Context Copy Chapter

peon-ping is adding text-to-speech (TTS) as a new output modality alongside pre-recorded sound files (v2/m5, PRD-003). The hook pipeline currently plays audio through a single play_sound() function that uses a platform case switch — one monolithic function handling macOS (afplay), WSL2 (PowerShell SoundPlayer), Linux (six-backend priority chain), SSH/devcontainer (relay HTTP), and MSYS2 (player chain + PowerShell fallback). This pattern grew organically and works, but it concentrates all platform logic in ~110 lines of shell with no separation between "what to play" and "how to play it."

TTS introduces a second axis of variation. Sound playback varies by platform (macOS vs. Windows vs. Linux). TTS varies by both platform (native engines differ per OS) and engine (native, ElevenLabs API, Piper local neural, future others). The roadmap explicitly plans three backend categories shipping at different times:

- Platform-native (Phase 1): macOS say, Windows SAPI5, Linux espeak-ng/piper
- ElevenLabs (future): Cloud API with audio caching, API key management, cost controls
- Piper (future): Local neural TTS with model management, BYO binary

These backends have fundamentally different operational characteristics. Native backends are synchronous CLI commands that speak directly to the audio device. ElevenLabs is an HTTP API that returns audio files requiring caching and playback. Piper is a local binary that writes WAV to stdout or file. A single abstraction that handles all three elegantly would need to bridge direct-to-device speech, cached file playback, and piped audio — three different I/O models.

Meanwhile, the existing win-play.ps1 establishes a precedent: platform-specific audio logic extracted into a standalone script, invoked via Start-Process as a fire-and-forget background process. The Windows adapter ecosystem (.ps1 counterparts for every .sh adapter) shows the codebase already handles dual-platform scripts as a known pattern.

The forces in tension:

1. Extensibility: New TTS engines must be addable without modifying the core hook pipeline. The roadmap plans at least three backends, and community contributions could add more.
2. Simplicity: peon-ping is a shell script, not a framework. Each layer of abstraction adds cognitive overhead for contributors and debugging surface area for users.
3. Operational diversity: Backends differ in I/O model (direct speech vs. file output vs. HTTP), lifecycle (stateless vs. cached), and configuration (none vs. API keys vs. model paths).
4. Platform parity: Both peon.sh (Unix) and peon.ps1 (Windows) must implement the same TTS behavior, doubling the surface area of any abstraction layer.

Decision Copy Chapter

We will implement TTS backends as independent, self-contained scripts — one per backend per platform — invoked by the hook pipeline through a minimal calling convention rather than a formal plugin interface.

Each backend is a script that accepts speech parameters as command-line arguments and handles its own audio output asynchronously. The hook pipeline's only responsibility is: resolve the speech text, select the backend based on config, and invoke the corresponding script as a background process. There is no backend registry, no discovery mechanism, no shared backend library, and no abstract interface definition.

Calling convention (the entire "contract"):

Unix (bash scripts) — text on stdin, options as arguments

echo "<text>" | scripts/tts-native.sh  "<voice>" "<rate>" "<volume>"
Windows (PowerShell scripts) — text on stdin, options as named params

"<text>" | scripts/tts-native.ps1 -voice "<voice>" -rate <rate> -vol <volume>

Speech text is passed on stdin, not as a CLI argument. Dynamic text from template interpolation ({project}, {summary}) can contain shell metacharacters, quotes, newlines, and other content that is unsafe to pass as positional arguments without careful escaping. Stdin avoids this class of problems entirely — the backend reads one line from stdin and speaks it, with no shell interpretation of the content.

Each script:
- Reads speech text from stdin (one line)
- Handles its own platform detection internally (for native: macOS say vs. Linux espeak-ng/piper)
- Manages its own dependencies (ElevenLabs: HTTP + caching; Piper: binary + model detection)
- Exits cleanly on failure (no error propagation to hook — TTS failure is never a hook failure)
- Runs as a background process via the same nohup ... & / Start-Process -WindowStyle Hidden pattern as play_sound()

Speech text resolution happens in the hook pipeline's Python block (Unix) / PowerShell block (Windows) — centralized, before any backend is invoked:

1. If the selected sound entry has speech_text and TTS is enabled → interpolate template variables
2. Else if a notification template exists for this category → use rendered template text
3. Else → use default template "{project} — {status}"
4. If resolved text is empty after interpolation → skip TTS entirely

Pipeline integration in _run_sound_and_notify (or equivalent):

Pseudocode — actual implementation adapts to mode config

if mode == "sound-then-speak":
    play_sound(file, volume)        # existing, backgrounded
    speak(text, voice, rate, vol)   # new, backgrounded after sound
elif mode == "speak-only":
    speak(text, voice, rate, vol)   # replaces sound
elif mode == "speak-then-sound":
    speak(text, voice, rate, vol)   # new, backgrounded
    play_sound(file, volume)        # existing, after TTS

TTS gets its own PID tracking (.tts.pid) separate from .sound.pid, enabling independent kill-previous behavior and the sequencing modes.

File organization:

scripts/
  tts-native.sh       # macOS say / Linux espeak-ng|piper
  tts-native.ps1      # Windows SAPI5
  tts-elevenlabs.sh   # (future) ElevenLabs API
  tts-elevenlabs.ps1  # (future) ElevenLabs API
  tts-piper.sh        # (future) Piper standalone
  tts-piper.ps1       # (future) Piper standalone
  win-play.ps1        # (existing) Windows audio playback

Rationale Copy Chapter

The current sound playback system is a cautionary example of what happens when platform variation accumulates in a single function. play_sound() started as a simple afplay call and grew to 110 lines spanning six platform paths with nested conditionals for relay modes, WSL format conversion, and player priority chains. It works, but it's the single hardest function to modify confidently — every platform path must be mentally held in context for any change.

TTS would compound this problem because it adds engine variation on top of platform variation. An inline approach would mean the hook script grows a second 100+ line function with case branches for native × {mac, linux, wsl, windows}, elevenlabs × {all platforms}, and piper × {all platforms}. Each new backend multiplies the branch count.

Independent scripts avoid this by giving each backend its own file with its own concerns. tts-native.sh can have a platform case for say vs. espeak-ng without carrying ElevenLabs caching logic. tts-elevenlabs.sh can manage its HTTP client and cache directory without knowing anything about SAPI5. The complexity of each backend is contained rather than composed.

Key Factors Copy Section

1. Operational isolation prevents cascade failures. A bug in ElevenLabs caching logic cannot affect native TTS. A SAPI5 PowerShell quirk cannot break espeak-ng. This matters in practice — peon-ping runs in hook context where any failure delays the user's IDE. Independent scripts fail independently, and the hook pipeline's error handling is trivially simple: if the background process exits non-zero, nothing happens (fire-and-forget).

2. The calling convention is the contract, and it's deliberately minimal. Four arguments in, audio out. No interface file, no type system, no registration. This is a shell tool — the filesystem is the registry (scripts/tts-*.sh is the set of backends). A contributor adding a new backend writes one script, adds one case branch in the backend selector, and they're done. The barrier to contribution is "can you write a shell script that speaks text?" — not "can you navigate a plugin framework?"

3. Backend diversity is real and resists unification. Native TTS speaks directly to the audio device (no file output). ElevenLabs returns MP3 bytes over HTTP that need caching and playback through the existing audio pipeline. Piper writes WAV to stdout. A unified interface that abstracts these I/O models would either be so generic it provides no value (just "make audio happen") or so specific it forces backends into unnatural patterns (e.g., requiring file output from say, which natively speaks to device). The independent script model lets each backend use its natural I/O pattern.

4. win-play.ps1 already proves the pattern. Windows audio playback was extracted into a standalone script precisely because it needed platform-specific complexity (MediaPlayer WPF dispatcher pumping, CLI player priority chains) that didn't belong inline. It works well — invoked via Start-Process, fire-and-forget, self-contained. TTS backends follow the same proven model.

Consequences Copy Chapter

Positive Copy Section

- Each backend is independently testable. tts-native.sh can be tested by invoking it directly with known arguments — no hook pipeline setup required. BATS tests call the script, Pester tests call the .ps1. This matches the existing test pattern for win-play.ps1.

- New backends don't touch existing code. Adding ElevenLabs means creating tts-elevenlabs.sh and adding a case branch in the backend selector — two changes, both additive. Zero risk to native TTS behavior.

- Debugging is straightforward. peon debug on can log the exact command invoked ([tts] backend=native cmd="scripts/tts-native.sh 'hello' 'Alex' '1.0' '0.5'" pid=48291). Users can run the same command manually to reproduce issues. The [tts] log phase slots naturally into the existing structured logging format.

- Contributors face a minimal learning curve. "Write a script that takes text/voice/rate/volume and speaks" is a self-contained task. No framework concepts to learn, no interfaces to implement, no registration to configure.

Negative Copy Section

- Duplicated platform detection across backends. tts-native.sh and a hypothetical tts-festival.sh would both need to detect macOS vs. Linux. This is a small amount of duplication (a uname check) and acceptable — the alternative (a shared platform library) adds a dependency chain to every backend script, creating the coupling we're trying to avoid.

- Each backend requires parallel bash and PowerShell implementations. Three planned backends means six script files with mirrored logic. This is the same dual-platform cost every peon-ping feature pays (every .sh adapter has a .ps1 counterpart), but it multiplies with the backend count. Acceptable because each script is self-contained and small (~50-100 lines), and the alternative — a unified cross-platform layer — would introduce a new dependency or abstraction that doesn't exist in the codebase today.

- No compile-time contract enforcement. If a backend script ignores the volume argument or takes arguments in the wrong order, the only feedback is wrong behavior at runtime. For a shell-based CLI tool with 3-5 backends, this is manageable — backends are tested individually, and the argument list is documented in the script headers. A formal interface would only help if we had dozens of backends.

- Backend selection is a hardcoded switch, not dynamic discovery. The hook pipeline has a case block mapping config values to script paths. Adding a backend requires editing this block. Automatic discovery (scanning scripts/tts-*.sh) would eliminate this, but introduces ordering ambiguity and makes the "which backend runs?" question harder to answer from reading the code. Explicit is better than implicit for a system with <10 backends.

Neutral Copy Section

- Speech text resolution stays centralized in the hook pipeline. The Python block (Unix) and PowerShell block (Windows) handle template interpolation, manifest speech_text lookup, and variable resolution. Backends receive already-resolved plain text. This means the resolution logic exists in two places (Python and PowerShell), but this is the same pattern as every other hook feature — the Windows port mirrors the Python logic.

- TTS PID tracking (.tts.pid) is separate from sound PID (.sound.pid). This enables the three modes (sound-then-speak, speak-only, speak-then-sound) but means two PID files to manage. The kill-previous logic needs to respect both PIDs and the active mode. This is a small complexity increase with clear benefits for sequencing control.

Alternatives Considered Copy Chapter

Alternative 1: Inline Platform Branching (Extend play_sound Pattern) Copy Section

Description: Add TTS as another case block in the main hook script, mirroring how play_sound() handles platform variation. A single speak() function contains all backend logic — native platform detection, ElevenLabs HTTP calls, Piper invocation — as branches in a nested case structure (outer: backend, inner: platform).

Pros:
- All TTS logic visible in one place — no script-hopping to understand the full flow
- No process overhead — avoids the ~200ms PowerShell startup cost of a separate Start-Process on Windows (though this cost is already budgeted for win-play.ps1 and fires in background)
- Consistent with how play_sound() currently works — contributors familiar with the codebase already know the pattern

Cons:
- Compounds the monolith problem. play_sound() at 110 lines is already the hardest function to modify; adding a speak() of similar size with backend × platform branching doubles the cognitive load. Each new backend adds branches to both Unix and Windows code paths
- Cross-backend contamination risk. A change to ElevenLabs caching could introduce a bug in native TTS if they share control flow or variables — even with careful scoping, inline proximity encourages shared state
- Testing requires the full hook pipeline. You can't invoke "just the native backend" without setting up mock config, event JSON, and platform detection — all the surrounding context that the inline function depends on

Why not chosen: play_sound() demonstrates the long-term trajectory of this pattern — organic growth into a function that's correct but increasingly difficult to modify with confidence. TTS would follow the same path with the added dimension of backend variation. The operational diversity of backends (direct speech vs. HTTP + cache vs. local binary) makes inline branches increasingly awkward as each backend's unique concerns bleed into shared scope.

Alternative 2: Plugin Registry with Auto-Discovery Copy Section

Description: Create a formal backend plugin system. Backend scripts live in a tts-backends/ directory and self-register by implementing a standard interface. The hook pipeline scans the directory, loads available backends, and dispatches to the selected one. Each backend exports metadata (name, platform support, capabilities) that the registry uses for auto resolution and the peon tts voices enumeration.

A backend script would follow a defined structure:

tts-backends/native.sh

BACKEND_NAME="native"
BACKEND_PLATFORMS="mac linux wsl"
backend_available() { ... }  # returns 0 if this backend can run
backend_voices() { ... }     # lists available voices
backend_speak() { ... }      # speaks text with given parameters

Pros:
- Maximum extensibility — community backends drop into a directory and "just work" without any core code changes
- Formalized contract prevents argument-order mistakes and documents the expected interface
- Auto-discovery enables features like peon tts backends listing all available engines with their capabilities

Cons:
- Overengineered for the expected scale. The roadmap plans 3-4 backends (native, ElevenLabs, Piper, maybe OpenAI). A discovery framework serves a plugin ecosystem of dozens — we're building for 3
- Introduces framework concepts foreign to the codebase. peon-ping is a shell script that reads JSON and plays sounds. Plugin registries, self-registration, and capability metadata are patterns from application frameworks, not CLI tools. Contributors now need to understand the plugin model before adding a backend
- Discovery ordering creates implicit behavior. If multiple backends claim to support a platform, which wins? Priority ordering, explicit preference configuration, and conflict resolution add complexity that explicit backend selection avoids entirely
- Shell-based plugin systems are fragile. Sourcing arbitrary scripts (source tts-backends/*.sh) in the hook's execution context risks variable collisions, function name conflicts, and error propagation. Subprocess isolation (what the independent scripts approach uses naturally) must be explicitly engineered

Why not chosen: The plugin registry solves a problem we don't have — managing a large, open-ended set of backends contributed by a distributed community. With 3-4 planned backends, each shipping as a deliberate feature with its own roadmap entry, the editorial overhead of "add a case branch" is negligible. The registry's value proposition — "zero-touch extensibility" — comes at the cost of framework complexity that makes the first three backends harder to build, debug, and maintain. If peon-ping ever reaches 10+ TTS backends (unlikely given the TTS market), a registry can be introduced then with the independent scripts as migration targets.

Alternative 3: Unified Audio Pipeline (TTS as a Sound Source) Copy Section

Description: Instead of TTS being a separate pipeline, treat synthesized speech as another sound source feeding into the existing play_sound() function. TTS backends produce audio files (WAV/MP3) written to a temp directory, and play_sound() plays them like any pack sound. This unifies PID tracking, volume control, kill-previous behavior, and platform playback under a single code path.

Pros:
- Maximal code reuse — every platform's audio playback is already solved in play_sound(). TTS backends only need to produce files, not handle audio output
- Single PID tracking (.sound.pid) — no dual-PID complexity, modes reduce to "play this file, then play that file"
- ElevenLabs and Piper naturally produce files (MP3/WAV), so this model fits them natively

Cons:
- Forces native TTS through an unnatural path. macOS say and espeak-ng speak directly to the audio device — requiring them to write files first adds latency (synthesis + write + read + play vs. just synthesis + speak) and temp file management (creation, cleanup, disk usage). A 2-second phrase would need to fully synthesize before any audio plays, rather than streaming word-by-word as say does natively
- Eliminates streaming playback. say begins speaking immediately as it processes text; file-based playback requires full synthesis first. For longer phrases (trainer progress with multiple exercises), the difference is perceptible — 1-2 seconds of silence before speech begins
- Conflates two concerns in play_sound(). Sound files are static assets selected from a manifest. TTS output is dynamically generated text. Adding "is this a real file or a temp file that needs cleanup?" logic to play_sound() spreads TTS concerns into the sound pipeline
- The sequencing modes (sound-then-speak, speak-then-sound) become harder — they're now "play file A, then play file B" which requires chaining play_sound() calls with wait-for-completion logic, adding the same PID coordination complexity we were trying to avoid

Why not chosen: The appeal of this approach — reusing play_sound() — breaks down precisely for the most important backend (platform-native). Native TTS's strength is low-latency direct-to-device speech, and forcing it through file intermediation sacrifices that advantage. The approach optimizes for API backends (ElevenLabs, which naturally produces files) at the cost of the baseline experience. Since native TTS is the first and default backend — the one every user encounters — penalizing it to benefit future backends is the wrong tradeoff ordering. API backends that produce files can simply call play_sound() internally if they want to reuse it, without forcing native backends into the same path.

Alternative 4: Python Cross-Platform TTS (Single Script per Backend) Copy Section

Description: Leverage the Python runtime already present in the hook pipeline (peon.sh embeds a Python block for config loading, event parsing, and sound selection). Each TTS backend becomes a single .py script that handles all platforms internally — tts-native.py would call say via subprocess on macOS, espeak-ng on Linux, and either pyttsx3 or win32com.client for SAPI5 on Windows. This halves the file count by eliminating the .sh / .ps1 duplication.

Pros:
- One script per backend instead of two — three backends means three files, not six
- Eliminates the "duplicated platform detection across backends" negative consequence entirely
- Python's subprocess module provides consistent cross-platform process invocation
- The hook pipeline already depends on Python (Unix side), so no new runtime dependency there

Cons:
- peon.ps1 (native Windows) deliberately avoids Python — it's a pure PowerShell implementation with no Python dependency. Introducing Python TTS scripts would break this architectural boundary, requiring Python on Windows or maintaining a PowerShell fallback path anyway
- pyttsx3 (the main cross-platform TTS library) is a pip dependency peon-ping has never required. The existing Python usage is stdlib-only. Adding pip dependencies changes the install story and creates a new failure mode
- Without pyttsx3, the Python scripts would just be subprocess wrappers around say/espeak-ng/SAPI5 — the same platform branching as shell scripts but in a different language, adding Python startup overhead (~100ms) without reducing complexity
- Python is not available in all environments where peon-ping runs (minimal containers, some CI images, MSYS2 without Python installed)

Why not chosen: The value proposition — halving file count — only materializes if a cross-platform Python TTS library is used, which introduces peon-ping's first pip dependency. Without it, Python scripts are just shell scripts in a different language with worse startup performance. More fundamentally, peon.ps1 exists specifically to avoid a Python dependency on Windows, and that boundary is load-bearing — Windows users install peon-ping via install.ps1 with no Python requirement. Forcing Python into the Windows path to reduce file count trades a real user-facing simplicity (no Python needed) for a developer-facing convenience (fewer files).

Implementation Notes Copy Chapter

Phase 1 ships one backend script (native) with the integration layer:

1. Add tts section to config.json defaults — enabled: false, backend: "auto", voice: "default", rate: 1.0, volume: 0.5, mode: "sound-then-speak"
2. Create scripts/tts-native.sh — platform detection (uname), macOS say, Linux espeak-ng/piper priority chain, async via nohup ... &
3. Create scripts/tts-native.ps1 — Windows TTS via System.Speech.Synthesis.SpeechSynthesizer (SAPI5), async via the script being invoked through Start-Process -WindowStyle Hidden (same pattern as win-play.ps1). Note: Microsoft is steering toward Windows.Media.SpeechSynthesis (WinRT), which offers neural voices on Windows 11 with notably higher quality. Phase 1 uses SAPI5 for broader compatibility (Windows 10 support, simpler PowerShell integration), but the independent script architecture means tts-native.ps1 can adopt WinRT internally without affecting any other backend or the hook pipeline
4. Add speech text resolution to the Python block in peon.sh — template interpolation using existing _tpl_vars machinery, outputting TTS_TEXT variable
5. Add TTS invocation to _run_sound_and_notify — mode-aware sequencing, .tts.pid tracking, safety timeout
6. Add peon tts CLI subcommands — on/off/status/test/voices/voice/backend
7. Port all of the above to peon.ps1 (PowerShell)
8. peon update backfills tts config section for existing installs

Future backends add files, not framework:

- scripts/tts-elevenlabs.sh: HTTP client (curl), text-hash caching to $PEON_DIR/cache/tts/, plays cached MP3 via play_sound() internally
- scripts/tts-piper.sh: Detects piper binary and model, pipes text to piper --output-raw | aplay (or writes WAV + play_sound())
- Each backend adds one case branch to the backend selector in peon.sh and peon.ps1

The auto backend resolution for Phase 1 is trivially native — it's the only backend. When ElevenLabs ships, auto can prefer it when an API key is configured, falling back to native. This logic lives in the hook pipeline's backend selector, not in any backend script.

Validation Copy Chapter

- Backend isolation holds: Each backend can be invoked directly from the command line (echo "test" | bash scripts/tts-native.sh "Alex" "1.0" "0.5") and produces speech without any hook pipeline context. BATS/Pester tests validate this independently.
- Hook latency unchanged: Before/after timing of hook return shows no measurable increase. The structured logging [exit] duration_ms=N metric (from v2/m4) provides automated measurement. Target: <50ms delta.
- Adding ElevenLabs backend requires no changes to tts-native scripts: When tts-elevenlabs.sh ships, the diff touches zero lines in tts-native.sh or tts-native.ps1. Only the backend selector in peon.sh/peon.ps1 and config schema gain additions.
- Failure isolation: Kill espeak-ng mid-utterance, corrupt the ElevenLabs cache, remove Piper's model file — each failure is contained to its backend with no impact on sound playback or other backends. The hook exits 0 regardless.
- Contributor test: The calling convention and one example script (tts-native.sh) are sufficient documentation for a new backend — implementing a backend requires no reading of peon.sh internals. If a contributor must understand the hook pipeline to write a backend, the contract has grown too complex.

Related Decisions Copy Chapter

- Async Audio and Safe State on Windows: The Start-Process -WindowStyle Hidden pattern, atomic state writes, and 8-second safety timeout established during the Windows native port. TTS backends inherit this pattern. (Implementation reference: scripts/win-play.ps1 and peon.ps1 async invocation.)
- Structured Hook Logging (v2/m4): The [phase] key=value log format defined for hook observability. TTS adds a [tts] phase following this convention.

References Copy Chapter

- PRD-003: TTS Spoken Feedback — product requirements driving this decision
- v2/m5 "The peon speaks to you" — parent roadmap milestone defining feature sequencing and success criteria
- macOS say man page — native macOS TTS capabilities
- System.Speech.Synthesis (SAPI5) — Windows native TTS API
- espeak-ng — open-source speech synthesizer for Linux
- Piper — fast local neural TTS for Linux

---

Revision History Copy Chapter

---

Designs/2026 05 09 Omp Adapter Design Copy Section

omp (oh-my-pi) Adapter

Date: 2026-05-09
Status: Approved
Type: New Adapter + minor peon.sh wiring + docs

Problem Statement Copy Chapter

oh-my-pi (CLI binary omp) is a bun/TypeScript coding-agent CLI. peon-ping currently has no adapter for it, so omp users get no sound, notification, trainer, or relay support — even though every primitive peon-ping needs is already in place. The work is purely the adapter layer.

Background Copy Chapter

How omp exposes lifecycle Copy Section

omp ships an ExtensionAPI (and a deprecated-but-supported HookAPI superset) that fires typed lifecycle events. Extensions are default-exporting TS modules auto-discovered from:

1. <cwd>/.omp/extensions/ (project scope)
2. ~/.omp/agent/extensions/ (user scope)
3. ~/.omp/plugins/node_modules/ (marketplace plugins)
4. omp --extension / omp --hook (CLI override)

A directory entry is resolved as package.json (with omp.extensions field) → index.ts → index.js → directory scan.

Relevant events for an audio adapter (full catalog: docs/skills/authoring-hooks.md):

How peon-ping accepts events Copy Section

peon.sh reads JSON on stdin and dispatches on hook_event_name + source. Existing adapters (Codex, Cursor, OpenCode, Kilo, Kiro, Gemini, Copilot, Windsurf, Antigravity, Amp, DeepAgents, OpenClaw, Rovodev) all share the same shape: receive IDE events, translate, spawn peon.sh with a CESP-shaped payload.

peon.sh already has IDE-aware tables that need an omp entry to display correctly:
- IDE_ALIASES (line 4887) — normalizes source field strings
- IDE_DISPLAY_NAMES (line 4952) — human-readable label
- prefix_map inside detect_session_ide (line 4931) — fallback IDE detection from session-id prefix

Closest precedent Copy Section

adapters/opencode/peon-ping.ts is a thin TS plugin (~160 lines) that subscribes to OpenCode events and spawns peon.sh with { hook_event_name, source: "opencode", session_id, cwd }. The omp adapter follows the same shape, swapping the event surface.

Proposed Solution Copy Chapter

Add a thin omp extension that mirrors the OpenCode adapter, plus the small peon.sh table updates so the existing IDE-detection paths recognize omp.

Architecture Copy Section

omp session
  │
  │  omp ExtensionAPI events (session_start, turn_start, turn_end,
  │                            tool_result, auto_compaction_start,
  │                            session_shutdown)
  ▼
adapters/omp/peon-ping.ts
  │
  │  spawn("bash", [peon.sh]) with stdin =
  │    { hook_event_name, source: "omp", session_id: "omp-…",
  │      cwd, notification_type, permission_mode }
  ▼
peon.sh  →  IDE_ALIASES["omp"] → "omp"
         →  IDE_DISPLAY_NAMES["omp"] → "oh-my-pi"
         →  existing routing: sounds, notifications, trainer, relay

The adapter does no event-translation logic that peon-ping doesn't already do for other IDEs. It is purely a transport.

Implementation Plan Copy Chapter

1. New files Copy Section

#### adapters/omp/peon-ping.ts (the extension)

Default-exports an ExtensionAPI factory. On load:

1. Locate peon.sh from the same candidate paths as the OpenCode adapter:
- ~/.claude/hooks/peon-ping/peon.sh
- ~/.openclaw/hooks/peon-ping/peon.sh
2. If not found, log a one-line warning with install instructions and return without registering handlers.
3. Generate sessionId = "omp-" + Date.now() so peon.sh's prefix-based IDE detection fires correctly even if source somehow gets dropped.
4. Register handlers:

Unlike the OpenCode adapter (which fires an extra setTimeout-delayed SessionStart because OpenCode's session.created event fires before the plugin can subscribe), omp's documented lifecycle delivers session_start after all extensions load — registering the handler synchronously during the factory call is sufficient. No initial-fire timeout.

5. firePeon(event) shape (identical to the OpenCode adapter):

const proc = spawn("bash", [peonSh], { stdio: ["pipe", "ignore", "ignore"] });
proc.stdin.write(JSON.stringify({
  hook_event_name: event,
  notification_type: "",
  cwd,
  session_id: sessionId,
  permission_mode: "",
  source: "omp",
}));
proc.stdin.end();
proc.unref();

6. Use only node:* modules + the omp ExtensionAPI type — no third-party deps. Tab title is set via OSC-0 \x1b]0;…\x07, guarded on ctx.hasUI so headless/subagent runs don't paint over each other's TTY.

Imports:

import * as fs from "node:fs"
import * as path from "node:path"
import * as os from "node:os"
import { spawn } from "node:child_process"
import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent"

The ExtensionAPI type is imported type-only, so the file resolves without that package being installed at runtime — omp itself supplies the value at extension-load time.

#### adapters/omp/package.json (the manifest)

Directory-style omp extensions need a package.json with the omp.extensions field so omp's directory loader picks the entry point reliably (per docs/skills/authoring-extensions.md):

{
  "name": "peon-ping",
  "version": "1.0.0",
  "description": "peon-ping adapter for oh-my-pi (omp) — routes lifecycle events through peon.sh.",
  "omp": {
    "extensions": ["./peon-ping.ts"]
  }
}

This also lets us ship the adapter as a marketplace plugin later without restructuring.

#### adapters/omp.sh (the installer)

Same shape as adapters/opencode.sh:

1. Preflight: locate peon.sh (candidates above); fail with install instructions if missing.
2. Create ~/.omp/agent/extensions/peon-ping/.
3. Download peon-ping.ts and package.json from raw.githubusercontent.com/PeonPing/peon-ping/main/adapters/omp/….
4. Print success block with paths and "Restart omp to activate".
5. --uninstall flag removes the extension directory.

No PowerShell installer for v1 (see Non-Goals).

2. peon.sh table updates peon.sh table updates')" title="Copy section prompt for LLMs"> Copy Section

Three small additions in the IDE-resolution block (lines 4887–4967):

IDE_ALIASES = {
    # ...existing entries...
    'omp': 'omp',
    'oh-my-pi': 'omp',
    'oh_my_pi': 'omp',
    'pi': 'omp',
}
inside detect_session_ide, prefix_map tuple:

('omp-', 'omp'),
IDE_DISPLAY_NAMES = {
    # ...existing entries...
    'omp': 'oh-my-pi',
}

These three edits are the entire peon.sh change.

3. README + docs Copy Section

- README.md — add omp badge in the badges row, add omp row to the Multi-IDE support section, point users at bash adapters/omp.sh (or curl …/adapters/omp.sh | bash).
- README_zh.md, README_ko.md, README_ja.md — equivalent translations.
- docs/public/llms.txt — add omp adapter line.
- CLAUDE.md-mandated cross-repo updates (see "Change Enforcement Rules" at the top of CLAUDE.md):
- ../homebrew-tap/Formula/peon-ping.rb — only if a phase needs to detect omp; for an installer-only adapter no formula change is needed. Verify before claiming this is done.
- ../peonping-x-bot/workspace/SOUL.md — bump supported-tools count.
- Version bump: minor (new adapter).

4. Tests Copy Section

#### tests/omp.bats — installer + IDE-table tests

- Installer: with mocked HOME and a stubbed curl (or PEON_PING_LOCAL_ADAPTER_DIR env var pointing at the working tree's adapters/omp/), bash adapters/omp.sh writes peon-ping.ts and package.json into <HOME>/.omp/agent/extensions/peon-ping/; second run is idempotent; --uninstall removes the directory.
- IDE detection: pipe {"hook_event_name":"Stop","source":"omp","session_id":"omp-123","cwd":"/tmp"} through peon.sh against a mocked manifest; assert that the resolved IDE in logs/state is omp and the display name is oh-my-pi.
- Session-id-prefix fallback: pipe the same event with source: "" (empty) but session_id: "omp-456"; assert IDE still resolves to omp via the prefix table.

#### adapters/omp/peon-ping.ts runtime smoke test

Out-of-scope for the BATS suite (peon-ping CI doesn't run TS), but the file must:
- Compile cleanly with bun build --target=node (manual verification step in PR).
- Match the type contract documented in docs/skills/authoring-extensions.md.

5. Things explicitly not in scope (YAGNI) Copy Section

- Windows-native omp.ps1. omp on Windows runs through bun, which calls into the same bash peon.sh if it's on PATH. A real PowerShell installer can be added when a user reports needing it.
- Permission-prompt mapping (PermissionRequest). omp's tool_call blocking is a hook-author surface, not a user-facing permission UI. There is no clean signal to fire PermissionRequest; defer until omp exposes one.
- Subagent suppression beyond the existing suppress_delegate_sessions config. omp's subagent surface is ctx.hasUI === false; we can use that to skip tab-title writes, but we don't try to invent a per-session suppression scheme. Users who care set suppress_delegate_sessions: true.
- Branch / tree / TTSR events. Out of scope for an audio adapter.
- A --local flag for the installer that copies from a checkout instead of downloading. Other adapter installers don't have one; tests instead use the PEON_PING_LOCAL_ADAPTER_DIR test-only env var (set in the BATS harness only) to redirect the source. No production user-visible flag.

Testing Strategy Copy Chapter

Automated (BATS) Copy Section

Three new tests under tests/omp.bats:

1. Installer happy path: empty ~/.omp/, run installer, assert files exist with expected contents (use grep for the omp.extensions field and source: "omp" literal).
2. IDE alias + display: drive peon.sh with a synthetic stdin event, assert log contains ide=omp and (where exposed) display oh-my-pi.
3. Session-id prefix fallback: as above with empty source, assert IDE still resolves to omp.

Manual Copy Section

- bun build --target=node adapters/omp/peon-ping.ts succeeds (verifies type compatibility with @oh-my-pi/pi-coding-agent ExtensionAPI).
- Drop the built file into ~/.omp/agent/extensions/peon-ping/peon-ping.ts, start omp, send a prompt, hear the existing peon-ping pack play, check tab title updates.

CI Copy Section

GitHub Actions BATS job (macos-latest) will pick up tests/omp.bats automatically — no workflow changes.

Files Changed Copy Chapter

New Copy Section

Modified Copy Section

Verified-not-modified Copy Section

Success Criteria Copy Chapter

1. ✅ bash adapters/omp.sh installs the extension into ~/.omp/agent/extensions/peon-ping/ on a clean machine that has peon-ping already installed.
2. ✅ With the extension active, an omp session fires existing peon-ping sounds on session start, turn end, tool error, compaction, and session shutdown — verified manually.
3. ✅ peon.sh recognizes source: "omp" (and omp-… session-id fallback) and displays oh-my-pi as the IDE name.
4. ✅ All tests/omp.bats cases pass; existing tests remain green.
5. ✅ README badges + Multi-IDE matrix include omp, with translations updated.

Open Questions / Risks Copy Chapter

- Type-only import resilience. If omp's @oh-my-pi/pi-coding-agent ever moves the ExtensionAPI symbol, the adapter's import type will fail at install time. Mitigation: keep the adapter on the documented public type path; if it breaks, fall back to a structural type definition inline (no import) — same workaround Kilo uses for OpenCode.
- turn_start vs. before_agent_start. Both fire near the start of a turn. Approved mapping uses turn_start because it's the documented stable surface; before_agent_start is more about message injection. If field testing shows turn_start fires too eagerly (e.g., on continuations after compaction), we can switch — single-line change, no schema impact.
- Tab-title contention. Writing OSC-0 from a backgrounded extension while omp itself owns the TTY can flicker. Adapter writes are guarded on ctx.hasUI so headless / subagent runs don't compete for the TTY; the interactive case has been stable in practice for the OpenCode adapter using the same approach.

References Copy Chapter

- omp extension authoring: ../oh-my-pi/docs/skills/authoring-extensions.md
- omp hook event catalog: ../oh-my-pi/docs/skills/authoring-hooks.md
- omp extension loading: ../oh-my-pi/docs/extension-loading.md
- Closest precedent: adapters/opencode/peon-ping.ts, adapters/opencode.sh
- peon.sh IDE-resolution tables: peon.sh lines 4887–4967
- CESP v1.0: https://github.com/PeonPing/openpeon

---

Designs/Structured Hook Logging Copy Section

Design Doc: Structured Hook Logging via Inline Phase Emitters

ADR: ADR-002 | Date: 2026-03-25 | Author: cameron

Overview Copy Chapter

peon-ping's hook scripts (peon.sh and peon.ps1) are silent-failure-by-design — every error path
falls back to defaults, giving users zero visibility into why sounds stopped, notifications vanished,
or hooks timed out. ADR-002 decided to add inline phase-emitting log calls at each decision point in
both codepaths, writing append-only key=value lines to daily-rotated files under $PEON_DIR/logs/.

This design doc specifies how to implement that decision: where the log() function lives in each
codebase, what each phase emitter captures, how daily rotation and pruning work, the CLI commands
(peon debug, peon logs), and the cross-platform test fixture that prevents format drift between
the Python and PowerShell implementations.

Requirements Copy Chapter

The implementation is complete when:

1. Zero overhead when disabled: Hook execution with debug: false adds <1ms compared to a
version with no logging code at all. The log function is a no-op lambda/scriptblock assigned
before any I/O when disabled.
2. Full decision chain visibility: All 8 pipeline phases ([hook], [config], [state],
[route], [sound], [play], [notify], [trainer]) emit log lines that trace why a
given invocation produced (or suppressed) a specific sound/notification.
3. Five failure modes diagnosable: Missing audio backend, bad config, pack not installed,
hook timeout, and state lock contention are all identifiable from log output alone.
4. Concurrent invocation correlation: Every log line carries an inv= prefix (short random
ID) so interleaved output from 20+ concurrent agents can be grouped per invocation.
5. Cross-platform parity: The same JSON hook input produces identical log output (modulo
timestamps and paths) on both macOS/Linux (BATS) and Windows (Pester), validated by shared
test fixtures in CI.
6. Daily rotation with pruning: Log files are named peon-ping-YYYY-MM-DD.log, pruned
based on debug_retention_days (default 7), with pruning running at most once per day.
7. CLI control: peon debug on|off|status toggles the config key; peon logs reads and
filters log files with --last, --session, and --clear options.
8. Logging never breaks the hook: All logging I/O wraps in try/catch. Any failure disables
logging for the remainder of that invocation.

Current State Copy Chapter

peon.sh (Unix/WSL2) Copy Section

The main hook script delegates the entire decision pipeline to a single Python block
(peon.sh:3016-3780). The Python code runs inside a bash heredoc (python3 -c "...") and
outputs shell variables via print() statements that bash consumes via eval. Stderr is
redirected to /dev/null on the invocation (peon.sh:3780: " <<< "$INPUT" 2>/dev/null),
silencing all diagnostic output.

The Python block handles these phases sequentially:
1. Config load (3031-3062): Read config.json, extract all settings
2. Event parse (3064-3090): JSON from stdin, map Cursor camelCase → PascalCase
3. State load (3092-3129): Atomic read of .state.json with retry
4. Agent detection (3095-3106): Suppress sounds for delegate-mode sessions
5. Pack selection (3131-3241): Session override → path rules → rotation → default
6. Event routing (3329-3509): Map hook events to CESP categories with suppression logic
7. Sound selection (3552-3614): Load manifest, no-repeat filter, random pick
8. Notification template (3715-3740): Resolve {project}, {summary} placeholders
9. Trainer (3616-3670): Check exercise goals, emit reminder sounds
10. State write (3672-3692): Atomic persist, relay sync
11. Output (3742-3779): Print shell variables for bash to eval

After eval, bash handles audio playback (play_sound() at lines 254-505), desktop notifications
(send_notification() at 639-858), mobile push (759-859), and tab title/color (3884-3925).

The only existing debug mechanism is a commented-out line at 2992:

echo "$(date): peon hook — $INPUT" >> /tmp/peon-ping-debug.log

peon.ps1 (Windows) Copy Section

Embedded in install.ps1 (lines 323-1975). Pure PowerShell — no Python dependency. Same
decision pipeline but implemented with PowerShell constructs (switch, hashtables,
ConvertFrom-Json). Audio playback delegates to scripts/win-play.ps1.

The only existing debug mechanism is PEON_DEBUG=1 in win-play.ps1 (line 9), which emits
Write-Warning for audio failures only — covering none of config loading, event routing, pack
selection, or state management.

CLI Copy Section

Top-level case statement at peon.sh:924. Existing commands: pause, resume, mute,
unmute, toggle, status, volume, rotation, packs, notifications, mobile,
relay, trainer, help. Tab completions in completions.bash (84 lines) and
completions.fish (140 lines).

config.json Copy Section

44-line template with no debug or debug_retention_days keys. The config merge logic
in peon update backfills new keys from the template into existing user configs.

Tests Copy Section

BATS tests (tests/peon.bats) use tests/setup.bash which creates isolated temp directories
with mock afplay, manifests, and config. Pester tests (tests/adapters-windows.Tests.ps1)
validate PowerShell adapter syntax and behavior. CI runs BATS on macos-latest and Pester
on windows-latest.

Target State Copy Chapter

/ Detailed source-code truncated for AI context efficiency. /

After all phases, a user who runs peon debug on and then uses Claude Code normally will find
a daily log file at $PEON_DIR/logs/peon-ping-YYYY-MM-DD.log containing 6-10 key=value lines
per hook invocation, each prefixed with a timestamp and invocation ID. The log traces the full
decision chain from event receipt to sound playback (or suppression reason).

Design Copy Chapter

Architecture Copy Section

Logging is implemented as a thin function defined at the top of each decision pipeline — a
Python log() function in peon.sh's Python block and a PowerShell $peonLog scriptblock in
peon.ps1. Both are gated on the same condition: config.debug == true OR PEON_DEBUG=1. When
disabled, the function is a no-op (Python: log = lambda a, *kw: None; PowerShell:
$peonLog = { }) — zero cost, no file I/O, no string formatting.

When enabled, the function:
1. Opens today's daily log file in append mode
2. Formats a key=value line with ISO-8601 timestamp and [phase] tag
3. Writes the line (Python: print() to file handle; PowerShell: Add-Content)
4. On first invocation of a new day's file, prunes old files beyond retention window

The log function is defined once per invocation — it does not re-evaluate the debug flag on
every call. This means toggling PEON_DEBUG mid-invocation has no effect (acceptable, since
invocations last 10-200ms).

Key Design Decisions Copy Section

1. Log function defined in the pipeline, not as a library import.

The Python block runs inside a bash heredoc. Importing external modules adds startup cost and
complexity. A 10-line log() function defined inline — with the file handle opened once at
the top and closed implicitly at exit — is simpler, faster, and has zero dependency overhead.
The alternative of import logging was evaluated in the ADR and rejected for its per-invocation
import cost (~15-30ms even when disabled, unless the import itself is gated).

2. Invocation ID generated once, carried through all log lines.

Each hook invocation generates a 4-character hex ID (inv=7a3f) from os.urandom(2) (Python)
or [System.Random]::new().Next(0, 65535).ToString('x4') (PowerShell). This is cheaper than
UUIDs and sufficient for correlation — collisions within a single day's log file are unlikely
at <500 invocations/day. The ID is generated before the first log() call and passed as a
closure variable, so it appears on every line without being passed as an argument.

3. File handle opened once per invocation, not per log call.

Python's open(path, 'a') with O_APPEND semantics is called once when logging is enabled.
All subsequent log() calls write to this handle. This avoids 6-10 open/close cycles per
invocation and ensures atomic append semantics on POSIX systems (writes under PIPE_BUF are
guaranteed atomic with O_APPEND). On Windows, Add-Content opens/writes/closes per call —
this is PowerShell's design constraint, and the ADR documents the resulting atomicity asymmetry
under heavy concurrency.

4. Pruning runs once per day, not per invocation.

When a log invocation opens a file for today and today's file didn't exist before this
invocation, it also prunes files older than debug_retention_days. This is detected by
attempting to create the file with exclusive mode (Python: check os.path.exists() before
first write; PowerShell: test Test-Path). Subsequent invocations on the same day skip
pruning entirely — they just append.

5. Values with spaces are double-quoted; values without spaces are unquoted.

This keeps simple cases (event=Stop volume=0.5) scannable while handling edge cases
(cwd="/home/user/my project") unambiguously. The quoting logic is a simple conditional:
if the value contains spaces, quotes, or equals signs, wrap in double quotes with internal
quotes escaped. Both implementations use the same convention, enforced by shared test fixtures
with edge-case inputs.

6. Shell-side phases ([play], [notify]) log from bash/PowerShell, not Python.

The Python block handles phases [hook] through [exit] (the decision pipeline). But audio
playback and notification dispatch happen in bash after eval "$_PEON_PYOUT". To log [play]
and [notify] phases, the Python block exports _PEON_LOG_FILE and _PEON_INV_ID as shell
variables. A small bash _peon_log() function (5 lines) appends to the same file using the
same format. On Windows, peon.ps1 handles everything in PowerShell, so no handoff is needed.

7. Log format is explicitly unstable — no backward compatibility commitment.

The ADR states log files are "not a stable API." This design doc reinforces that: the format
may change between any version. The README Debugging section will document this explicitly.
Committing to format stability would constrain improvements to a feature whose primary consumer
is a human reading a file, not a machine parsing it. If machine-parseable output becomes
necessary, the ADR already identifies debug_format: "jsonl" as a small future refactor — at
that point, the JSON format would get stability guarantees while key=value stays unstable.

8. peon logs writes to stdout without a pager.

No $PAGER integration. Users who want paging pipe through less themselves
(peon logs | less). This keeps peon logs composable (peon logs | grep route works
without --session), avoids platform differences in pager availability (Windows has no
default pager), and avoids the complexity of detecting interactive vs. piped contexts. The
--last N flag provides output limiting for interactive use.

9. Windows CLI commands stay inline in install.ps1.

The debug and logs CLI branches add ~60 lines to peon.ps1 (embedded in install.ps1).
This follows the existing pattern: every CLI command lives in the main hook script's case/switch
block. Extracting to standalone scripts would add file management complexity, break the
single-file deployment model, and diverge from how Unix handles it. install.ps1 is already
large; 60 more lines is marginal.

Interface Design Copy Section

#### Config Keys

{
  "debug": false,
  "debug_retention_days": 7
}

Both keys are added to config.json (the template). The peon update config merge logic
already backfills new template keys into existing user configs, so no migration code is needed.

#### Log Line Format

YYYY-MM-DDTHH:MM:SS.mmm [phase] inv=XXXX key1=val1 key2=val2 ...

Timestamp is ISO-8601 with millisecond precision. Phase tags are bracketed. All remaining
fields are key=value pairs separated by spaces. Values containing spaces, quotes, or =
are double-quoted with \" escaping.

#### Phase Emitters

Each phase logs specific fields:

[hook]    inv=XXXX event=Stop session=abc123 cwd=/path/to/project paused=false
[config]  inv=XXXX loaded=/path/to/config.json volume=0.5 pack=glados enabled=true
[state]   inv=XXXX sessions=3 rotation_index=2 last_stop=1711368121
[route]   inv=XXXX category=task.complete suppressed=false reason=""
[sound]   inv=XXXX file=mission-complete.wav pack=glados candidates=4 no_repeat=true
[play]    inv=XXXX backend=afplay pid=48291 async=true volume=0.5
[notify]  inv=XXXX desktop=true mobile=false template="✅ {project}: done" rendered="✅ myproj: done"
[trainer] inv=XXXX active=true exercise=pushups reps=150 goal=300 reminder=false
[exit]    inv=XXXX duration_ms=10 exit=0

Suppressed invocations log the reason:

[route]   inv=XXXX category=none suppressed=true reason=delegate_mode
[route]   inv=XXXX category=task.complete suppressed=true reason=debounce_5s
[route]   inv=XXXX category=none suppressed=true reason=paused

Error paths log the failure:

[config]  inv=XXXX error="FileNotFoundError: config.json" fallback=defaults
[sound]   inv=XXXX error="pack 'glados' not found" fallback=none
[play]    inv=XXXX error="afplay not found" backend=none

#### Python log() Function

Defined at top of Python block, after config load

_inv = os.urandom(2).hex()
_log_enabled = cfg.get('debug', False) or os.environ.get('PEON_DEBUG') == '1'
if _log_enabled:
    import datetime
    _log_dir = os.path.join(peon_dir, 'logs')
    os.makedirs(_log_dir, exist_ok=True)
    _log_date = datetime.date.today().isoformat()
    _log_path = os.path.join(_log_dir, f'peon-ping-{_log_date}.log')
    _log_is_new = not os.path.exists(_log_path)
    _log_fh = open(_log_path, 'a')
    def _log_quote(v):
        s = str(v)
        if ' ' in s or '"' in s or '=' in s or not s:
            return '"' + s.replace('\\', '\\\\').replace('"', '\\"') + '"'
        return s
    def log(phase, kw):
        ts = datetime.datetime.now().strftime('%Y-%m-%dT%H:%M:%S.') + \
             f'{datetime.datetime.now().microsecond // 1000:03d}'
        parts = [f'{ts} [{phase}] inv={_inv}']
        for k, v in kw.items():
            parts.append(f'{k}={_log_quote(v)}')
        try:
            print(' '.join(parts), file=_log_fh, flush=True)
        except Exception:
            pass  # logging must never break the hook
    # Prune old logs on first file of the day
    if _log_is_new:
        _retention = cfg.get('debug_retention_days', 7)
        try:
            for f in os.listdir(_log_dir):
                if f.startswith('peon-ping-') and f.endswith('.log'):
                    fdate = f[len('peon-ping-'):-len('.log')]
                    if fdate < (datetime.date.today() -
                                datetime.timedelta(days=_retention)).isoformat():
                        os.remove(os.path.join(_log_dir, f))
        except Exception:
            pass
else:
    log = lambda phase, kw: None

#### PowerShell $peonLog Function

$peonInv = '{0:x4}' -f [System.Random]::new().Next(0, 65535)
$peonLogEnabled = ($config.debug -eq $true) -or ($env:PEON_DEBUG -eq '1')
if ($peonLogEnabled) {
    $logDir = Join-Path $InstallDir 'logs'
    if (-not (Test-Path $logDir)) { New-Item -ItemType Directory -Path $logDir -Force | Out-Null }
    $logDate = (Get-Date).ToString('yyyy-MM-dd')
    $logPath = Join-Path $logDir "peon-ping-$logDate.log"
    $logIsNew = -not (Test-Path $logPath)
    $peonLog = {
        param([string]$Phase, [hashtable]$Fields)
        $ts = (Get-Date).ToString('yyyy-MM-ddTHH:mm:ss.fff')
        $parts = "$ts [$Phase] inv=$peonInv"
        foreach ($kv in $Fields.GetEnumerator()) {
            $v = [string]$kv.Value
            if ($v -match '[ "=]' -or $v -eq '') {
                $v = '"' + ($v -replace '\\','\\' -replace '"','\"') + '"'
            }
            $parts += " $($kv.Key)=$v"
        }
        try { Add-Content -Path $logPath -Value $parts -ErrorAction Stop }
        catch { $script:peonLogEnabled = $false }  # disable for rest of invocation
    }
    # Prune old logs on first file of the day
    if ($logIsNew) {
        $retention = if ($config.debug_retention_days) { $config.debug_retention_days } else { 7 }
        $cutoff = (Get-Date).AddDays(-$retention).ToString('yyyy-MM-dd')
        Get-ChildItem -Path $logDir -Filter 'peon-ping-*.log' -ErrorAction SilentlyContinue |
            Where-Object { $_.BaseName -replace 'peon-ping-','' -lt $cutoff } |
            Remove-Item -Force -ErrorAction SilentlyContinue
    }
} else {
    $peonLog = { }
}

#### Bash _peon_log() Function (for [play] and [notify] phases)

After eval "$_PEON_PYOUT", if logging is active:

if [ -n "${_PEON_LOG_FILE:-}" ]; then
  _peon_log() {
    local phase="$1"; shift
    local ts
    ts=$(date '+%Y-%m-%dT%H:%M:%S.000')
    printf '%s [%s] inv=%s %s\n' "$ts" "$phase" "$_PEON_INV_ID" "$*" >> "$_PEON_LOG_FILE" 2>/dev/null
  }
else
  _peon_log() { :; }
fi

The Python block exports these variables when logging is enabled:

if _log_enabled:
    print('_PEON_LOG_FILE=' + q(_log_path))
    print('_PEON_INV_ID=' + q(_inv))

#### CLI Commands

peon debug on|off|status — Modifies debug in config.json.

peon debug on

python3 -c "
import json
cfg = json.load(open('$CONFIG_PY'))
cfg['debug'] = True
json.dump(cfg, open('$CONFIG_PY', 'w'), indent=2)
"
echo "peon-ping: debug logging enabled — logs at $PEON_DIR/logs/"
peon debug off

Same pattern, cfg['debug'] = False
peon debug status

Read config.debug, count log files, show total size

peon logs [--last N] [--session ID] [--clear] — Reads log files.

peon logs (no args) — tail today's log, last 50 lines

peon logs --last 100 — last 100 lines across all log files

peon logs --session abc123 — grep for session=abc123

peon logs --clear — rm $PEON_DIR/logs/peon-ping-*.log

On Windows, peon.cmd delegates to peon.ps1 which handles debug and logs subcommands
with equivalent PowerShell logic.

Implementation Phases Copy Chapter

Phase 1: Core Logging in peon.sh (Python Block + Bash) Copy Section

Goal: A Unix user who runs peon debug on sees structured log output for every hook
invocation, covering all decision phases.

Deliverables:
- config.json: Add "debug": false and "debug_retention_days": 7 keys
- peon.sh Python block (~3020): Insert log() function definition after config load
- peon.sh Python block: Add log() calls at each phase:
- After config load: log('config', loaded=config_path, volume=..., pack=...)
- After event parse: log('hook', event=..., session=..., cwd=...)
- After state load: log('state', sessions=..., rotation_index=...)
- At route decision: log('route', category=..., suppressed=..., reason=...)
- At sound pick: log('sound', file=..., pack=..., candidates=...)
- At notification template: log('notify', desktop=..., template=..., rendered=...)
- At trainer check: log('trainer', active=..., reminder=...)
- At output: log('exit', duration_ms=..., exit=0)
- peon.sh Python block output: Export _PEON_LOG_FILE and _PEON_INV_ID when logging active
- peon.sh bash (after eval): Define _peon_log() shell function for [play] phase
- peon.sh bash play_sound(): Add _peon_log play backend=... pid=... async=...
- peon.sh bash send_notification(): Add _peon_log notify ... for desktop/mobile
- Daily rotation: Prune on new-day file creation in Python block
- Error paths: Every except block that currently silently falls back gets a log() call
explaining the fallback

Test strategy:
- Unit (BATS): Shared test fixture — feed known JSON event input, assert log file contains
expected key=value lines in correct phase order. Fixture includes edge cases: paths with
spaces, notification templates with emoji and braces, suppressed events (delegate mode,
debounce), missing pack.
- Unit (BATS): debug: false produces no log file and no logs/ directory
- Unit (BATS): PEON_DEBUG=1 env var enables logging even when debug: false
- Unit (BATS): Rotation test — create 10 dated log files, set retention to 3, invoke hook,
assert only 3 remain
- Integration (BATS): Run 5 concurrent hook invocations via &, assert all produce
complete entries (each has [hook] through [exit]) with distinct inv= IDs

Infrastructure: None — pure file I/O to existing $PEON_DIR/.

Documentation: None this phase — Phase 3 covers docs.

Dependencies: None.

Definition of done:
- [ ] debug: false (default) adds <1ms to hook execution time
- [ ] debug: true produces a log file at $PEON_DIR/logs/peon-ping-YYYY-MM-DD.log
- [ ] Log file contains [hook], [config], [state], [route], [sound], [play],
[notify], [exit] phases for a normal Stop event
- [ ] Suppressed events (delegate mode, debounce, paused) log [route] with reason=
- [ ] Error paths (missing pack, bad config) log error= with fallback
- [ ] 5 concurrent invocations produce non-corrupted output with distinct inv= IDs
- [ ] Rotation prunes files older than debug_retention_days
- [ ] All existing BATS tests continue to pass (logging is invisible when disabled)

Phase 2: PowerShell Parity in peon.ps1 Copy Section

Goal: A Windows user who runs peon debug on sees identical log output to Unix, validated
by the same test fixtures.

Deliverables:
- install.ps1 (peon.ps1 section): Insert $peonLog scriptblock definition after config load
- install.ps1 (peon.ps1 section): Add & $peonLog calls at each phase, matching Unix phases
- install.ps1 (peon.ps1 section): Add [play] logging around win-play.ps1 invocation
- install.ps1 (peon.ps1 section): [notify] logging around win-notify.ps1 invocation
- install.ps1 (peon.ps1 section): Add-Content with try/catch guard that disables logging
on IOException
- tests/hook-logging.Tests.ps1: New Pester test file validating log output against shared
fixtures

Test strategy:
- Unit (Pester): Same shared fixture inputs as Phase 1 — feed JSON, assert log output
matches expected format character-for-character (excluding timestamp/path/inv values)
- Unit (Pester): debug: false produces no log file
- Unit (Pester): PEON_DEBUG=1 env var override works
- Unit (Pester): Rotation prunes correctly
- Unit (Pester): Add-Content failure disables logging for remainder of invocation
(simulated via read-only file)

Infrastructure: None.

Documentation: None this phase.

Dependencies: Phase 1 (shared fixture format must be established first).

Definition of done:
- [ ] PowerShell log output matches Unix format for the shared test fixture inputs
- [ ] debug: false adds no measurable overhead
- [ ] Add-Content IOException disables logging gracefully (no hook failure)
- [ ] Rotation prunes correctly on Windows
- [ ] All existing Pester tests continue to pass
- [ ] CI runs both BATS and Pester test suites against the shared fixture

Phase 3: CLI Commands, Completions, and Documentation Copy Section

Goal: Users can toggle debug logging and read logs via peon debug and peon logs
commands on all platforms, with tab completion and documentation.

Deliverables:
- peon.sh CLI section (~line 924): Add debug) and logs) case branches
- peon debug on — set config.debug = true, print confirmation with log directory path
- peon debug off — set config.debug = false, print confirmation
- peon debug status — show debug state, log file count, total size, retention days
- peon logs — tail today's log file (last 50 lines)
- peon logs --last N — last N lines across log files (newest first)
- peon logs --session ID — grep all log files for session=ID
- peon logs --clear — delete all log files with confirmation prompt
- install.ps1 (peon.ps1 CLI section): Add equivalent debug and logs commands
- completions.bash: Add debug and logs to top-level commands, on off status for debug,
--last --session --clear for logs
- completions.fish: Add same completions with descriptions
- README.md: Add "Debugging" section documenting peon debug, peon logs, log format, and
common failure diagnosis patterns
- README_zh.md: Translated equivalent of Debugging section
- docs/public/llms.txt: Update with debugging commands and log format

Test strategy:
- Unit (BATS): peon debug on sets config.debug to true in config file
- Unit (BATS): peon debug off sets config.debug to false
- Unit (BATS): peon debug status outputs current state
- Unit (BATS): peon logs --last 10 outputs correct number of lines
- Unit (BATS): peon logs --session abc123 filters correctly
- Unit (BATS): peon logs --clear removes log files
- Unit (Pester): Equivalent tests for Windows CLI commands

Infrastructure: None.

Documentation: README.md, README_zh.md, docs/public/llms.txt (all part of this phase).

Dependencies: Phase 1 (Unix logging), Phase 2 (Windows logging).

Definition of done:
- [ ] peon debug on enables logging, peon debug off disables it (both platforms)
- [ ] peon debug status shows debug state and log statistics
- [ ] peon logs displays recent log entries with correct formatting
- [ ] peon logs --session filters by session ID
- [ ] peon logs --clear removes log files with confirmation
- [ ] Tab completion works in bash, zsh, and fish for all new commands
- [ ] README.md Debugging section explains the 5 common failure patterns and how to diagnose
each from log output
- [ ] README_zh.md has translated equivalent
- [ ] docs/public/llms.txt updated
- [ ] All new CLI commands have BATS and Pester test coverage

Migration & Rollback Copy Chapter

Migration: Pure addition. Two new keys (debug, debug_retention_days) added to
config.json template. The peon update config merge logic already backfills missing keys
from the template, so existing users get the new keys with defaults on next update. Users
who never update still work — the Python/PowerShell code defaults to False/7 when keys
are absent.

Backward compatibility: The existing PEON_DEBUG=1 env var in win-play.ps1 continues
to work independently. When both the new config-based logging and the legacy PEON_DEBUG
are active, both outputs fire — they are additive, covering different scopes (full pipeline
vs. audio-only).

Rollback: Clean git revert. No state migration, no external dependencies, no schema
changes. Log files in $PEON_DIR/logs/ can be deleted manually or via peon logs --clear.

Risks Copy Chapter

Roadmap Connection Copy Chapter

This design implements v2/m4 ("When something breaks, you can see why"), which currently
has no features or projects defined. After this design doc is accepted:

1. Create features under m4 for each phase (or a single feature with 3 projects matching the
3 implementation phases)
2. The sprint-architect can create cards directly from the phase definitions of done
3. M4's docs_ref should be updated to point to this design doc (the milestone already
references PRD-002)

Known Asymmetries Copy Chapter

paused.expected.txt fixture is Unix-only paused.expected.txt fixture is Unix-only')" title="Copy section prompt for LLMs"> Copy Section

The shared test fixture tests/fixtures/hook-logging/paused.expected.txt validates log output
when the hook is invoked while peon-ping is paused (enabled: false). This fixture applies only
to the Unix (BATS) side.

On Windows, peon.ps1 exits early when paused — if (-not $config.enabled) { exit 0 } fires
before the logging infrastructure is initialized, so no log file is created. The Pester test
validates only that the exit code is 0 in the paused case.

This diverges from peon.sh, where the Python block runs past the enabled check and logs the
paused state mid-pipeline (the [hook] ... paused=true line appears in the log before the
script exits). The asymmetry is inherent to the implementation: Python evaluates the full
decision pipeline and emits log lines along the way, while PowerShell's early-exit guard
precedes all logging setup.

Open Questions Copy Chapter

None — all resolved during design.

---

Revision History Copy Chapter

---

Designs/Tts Integration Copy Section

Design Doc: TTS Integration Layer and Backend Contract

ADR: ADR-001 | Date: 2026-03-28 | Author: cameron

Overview Copy Chapter

This document designs the TTS integration layer for peon-ping — the foundation that every TTS
feature builds on. ADR-001 decided that TTS backends ship as independent, self-contained scripts
invoked through a minimal calling convention (text on stdin, voice/rate/volume as arguments). This
design doc works out the specifics: where the hook pipeline gains TTS awareness, how speech text is
resolved from multiple sources, how mode sequencing coordinates sound and speech, how backend
resolution selects the right script, and how the config schema and state management extend to
support TTS.

The integration layer is deliberately inert on its own — it resolves text and invokes a backend
script, but without a backend installed (tts-native ships separately), peon tts on detects no
available engine and tells the user. This separation means the integration layer can be tested
against mock backends without platform-specific TTS dependencies.

Requirements Copy Chapter

The implementation is complete when:

1. The hook pipeline in peon.sh resolves speech text from the configured source chain and invokes
the selected TTS backend as an async background process after (or instead of, per mode) sound
playback — without increasing hook return latency.
2. The hook pipeline in install.ps1 (embedded peon.ps1 engine) provides identical TTS behavior
to the Unix implementation — same config keys, same text resolution, same mode sequencing, same
async contract.
3. A TTS backend script receives text on stdin with voice, rate, and volume as arguments — nothing
else. No hook context, no config access, no state file. The contract is the calling convention
and nothing more.
4. config.json gains a tts section with enabled, backend, voice, rate, volume, and
mode fields, and peon update backfills this section for existing installs without overwriting
user-modified values.
5. Backend resolution maps config.tts.backend to a script path via an explicit case/switch
block. "auto" resolves to the best available backend by probing for installed scripts in
priority order. When no backend is available, TTS is silently skipped during hooks and explicitly
reported during peon tts on.
6. Speech text resolution follows a defined chain: manifest speech_text field (when present) →
notification template for the active category → default template "{project} — {status}". Empty
resolved text skips TTS entirely.
7. TTS PID tracking (.tts.pid) is independent from sound PID (.sound.pid), enabling the three
sequencing modes and independent kill-previous behavior.
8. All existing suppression rules (headphones_only, meeting_detect, suppress_sound_when_tab_focused,
pause/mute state) apply to TTS identically to how they apply to sound playback.

Current State Copy Chapter

Hook pipeline (Unix — peon.sh) peon.sh)')" title="Copy section prompt for LLMs"> Copy Section

The embedded Python block (lines ~3329–3778) handles event routing, category mapping, sound
selection, notification template resolution, and trainer reminder logic. It outputs shell variables
via print() statements:

SOUND_FILE=/path/to/sound.mp3
VOLUME=0.5
NOTIFY=true
MSG="api-server — Task complete"
TRAINER_SOUND=/path/to/trainer.mp3
TRAINER_MSG="Time for reps!"

Shell code evals these variables, then _run_sound_and_notify() (line 3927) handles playback:

1. Check suppression rules (headphones, meeting, tab focus)
2. play_sound "$SOUND_FILE" "$VOLUME" — platform-dispatched, async via nohup ... &
3. send_notification — desktop notification with template-rendered text
4. send_mobile_notification — push notification if configured

After _run_sound_and_notify returns (backgrounded via & disown in production), trainer reminder
logic (line 3968) waits for the main sound PID to finish, pauses 0.5s, then plays the trainer
sound and sends a trainer notification.

Hook pipeline (Windows — embedded in install.ps1) install.ps1)')" title="Copy section prompt for LLMs"> Copy Section

The peon.ps1 engine (lines ~1400–1900 of install.ps1) mirrors the Python logic in pure
PowerShell. Sound selection, anti-repeat, icon resolution, and notification template resolution
all follow the same patterns. Audio delegates to scripts/win-play.ps1 via
Start-Process -WindowStyle Hidden. Trainer reminder logic follows the same wait-then-play
pattern.

Sound PID tracking Copy Section

- save_sound_pid() writes PID to $PEON_DIR/.sound.pid
- kill_previous_sound() reads and kills the previous PID before playing a new sound
- Trainer reminder waits for .sound.pid to finish before playing its sound

Notification template resolution Copy Section

The Python block (lines 3715–3740) resolves templates using _tpl_vars:

_tpl_vars = defaultdict(str, {
    'project': project,
    'summary': event_data.get('transcript_summary', '').strip()[:120],
    'tool_name': event_data.get('tool_name', ''),
    'status': status,
    'event': event,
})
msg = _tpl.format_map(_tpl_vars)

Template key mapping: task.complete → stop, task.error → error,
PermissionRequest → permission, idle/question from notification subtypes.

Config structure Copy Section

config.json has 44 keys. The trainer section (nested object) establishes the pattern for
feature namespaces. No tts section exists today.

State management Copy Section

.state.json uses atomic writes (temp file + os.replace() on Unix, Write-StateAtomic on
Windows). Stores last_played, session_packs, prompt_timestamps, trainer, etc. Read with
retry logic (3 attempts with backoff).

Target State Copy Chapter

After this implementation, the hook pipeline gains a TTS phase between sound playback and
notification dispatch. The flow becomes:

Event JSON → Python/PS routing → Category → Sound selection
                                          → Speech text resolution (NEW)
                                          ↓
                              _run_sound_and_notify()
                                  ├── play_sound()         [existing]
                                  ├── speak()              [NEW]
                                  ├── send_notification()  [existing]
                                  └── send_mobile_notif()  [existing]
                                          ↓
                              Trainer reminder (if applicable)
                                  ├── wait for .sound.pid  [existing]
                                  ├── wait for .tts.pid    [NEW — avoids overlap]
                                  ├── play trainer sound   [existing]
                                  ├── speak trainer text   [NEW]
                                  └── send trainer notif   [existing]

Architecture Copy Section

┌──────────────────────┐
                          │   Hook Pipeline       │
                          │  (peon.sh / peon.ps1) │
                          └──────┬───────────────┘
                                 │
                    ┌────────────┼────────────────┐
                    │            │                 │
            ┌───────▼──┐  ┌─────▼─────┐   ┌──────▼──────┐
            │play_sound│  │  speak()  │   │send_notif() │
            │ .sound.pid│  │ .tts.pid │   │             │
            └──────────┘  └─────┬─────┘   └─────────────┘
                                │
                    ┌───────────┼───────────────┐
                    │           │               │
              ┌─────▼────┐ ┌───▼─────┐  ┌──────▼──────┐
              │tts-native│ │tts-11lab│  │  tts-piper  │
              │   .sh    │ │   .sh   │  │    .sh      │
              │   .ps1   │ │   .ps1  │  │    .ps1     │
              └──────────┘ └─────────┘  └─────────────┘

The speak() function is the integration layer's single responsibility: resolve the backend,
construct the invocation, and fire it as a background process. Each backend script is a black box
that reads text from stdin and produces audio.

Mode sequencing in _run_sound_and_notify _run_sound_and_notify')" title="Copy section prompt for LLMs"> Copy Section

sound-then-speak (default):
  play_sound() → speak()       → notifications
speak-only:
  [skip sound] → speak()       → notifications
speak-then-sound:
  speak()      → play_sound()  → notifications

In sound-then-speak and speak-then-sound, both sound and speech fire as independent background
processes — no waiting. The perceptual ordering comes from invocation order and the ~200ms startup
delta. speak-only skips play_sound() entirely.

Design Copy Chapter

Key Design Decisions Copy Section

1. Speech text resolution happens in the Python/PowerShell routing block, not in speak().

The Python block already has access to the manifest (pick variable with the chosen sound entry),
notification templates (_tpl_vars), and event context (project, status, summary). Resolving
speech text here means speak() receives already-interpolated plain text — no template engine, no
manifest access, no event context needed in the shell function or backend scripts.

Alternative considered: having speak() accept template strings and variables, resolving text
at invocation time. Rejected because it duplicates the template resolution already done for
notifications and splits the "what text to produce" logic across two locations.

2. _run_sound_and_notify() handles mode sequencing; speak() is mode-unaware.

_run_sound_and_notify() is the only place that knows about both play_sound() and speak(), so
it owns the ordering decision. A case on TTS_MODE determines whether sound fires first, speech
fires first, or sound is skipped entirely. speak() itself is a thin wrapper — resolve backend,
invoke script, track PID — with no knowledge of modes. This keeps each function to a single
responsibility: the caller sequences, the speaker speaks.

Alternative considered: having speak() handle mode logic internally, checking TTS_MODE and
coordinating with play_sound(). Rejected because speak() would need to know about sound
playback state and SOUND_FILE availability — concerns that belong to the caller.

_run_sound_and_notify() {
  # ... suppression checks (applied to both sound and TTS) ...
  if [ "$_skip_sound" = "false" ]; then
    case "${TTS_MODE:-sound-then-speak}" in
      sound-then-speak)
        [ -n "$SOUND_FILE" ] && [ -f "$SOUND_FILE" ] && play_sound "$SOUND_FILE" "$VOLUME"
        [ -n "$TTS_TEXT" ] && speak "$TTS_TEXT"
        ;;
      speak-only)
        [ -n "$TTS_TEXT" ] && speak "$TTS_TEXT"
        ;;
      speak-then-sound)
        [ -n "$TTS_TEXT" ] && speak "$TTS_TEXT"
        [ -n "$SOUND_FILE" ] && [ -f "$SOUND_FILE" ] && play_sound "$SOUND_FILE" "$VOLUME"
        ;;
    esac
  fi
  # ... notifications (unchanged) ...
}

Each branch guards both SOUND_FILE (may be empty if no sound for this category) and TTS_TEXT
(may be empty if TTS disabled or text resolved empty). When SOUND_FILE is empty, only TTS fires
regardless of mode. When TTS_TEXT is empty, only sound fires — existing behavior preserved
exactly.

3. Backend resolution is a static case block, not filesystem scanning.

The ADR explicitly chose this: "Explicit is better than implicit for a system with <10 backends."
The hook pipeline maps config values to script paths:

Unix — always returns a script filename (e.g., "tts-native.sh"), never an absolute path.

The caller (speak()) resolves to absolute via find_bundled_script.

_resolve_tts_backend() {
  local backend="${1:-auto}"
  case "$backend" in
    native)     echo "tts-native.sh" ;;
    elevenlabs) echo "tts-elevenlabs.sh" ;;
    piper)      echo "tts-piper.sh" ;;
    auto)
      # Probe in priority order: prefer premium when installed.
      # At Phase 1 launch, only native exists — probes are ~1ms each.
      for b in elevenlabs piper native; do
        local script_name
        script_name="$(_resolve_tts_backend "$b")" || continue
        find_bundled_script "$script_name" >/dev/null 2>&1 || continue
        echo "$script_name" && return 0
      done
      return 1  # no backend available
      ;;
    *) return 1 ;;
  esac
}

Windows — always returns a script filename (e.g., "tts-native.ps1"), never a full path.

The caller (Invoke-TtsSpeak) resolves to absolute via Join-Path $InstallDir "scripts\$name".

function Resolve-TtsBackend {
    param([string]$Backend = "auto")
    switch ($Backend) {
        "native"     { return "tts-native.ps1" }
        "elevenlabs" { return "tts-elevenlabs.ps1" }
        "piper"      { return "tts-piper.ps1" }
        "auto" {
            # Probe in priority order: prefer premium when installed.
            # At Phase 1 launch, only native exists — probes are ~1ms each.
            foreach ($b in @("elevenlabs", "piper", "native")) {
                $scriptName = Resolve-TtsBackend -Backend $b
                $full = Join-Path $InstallDir "scripts\$scriptName"
                if (Test-Path $full) { return $scriptName }
            }
            return $null
        }
        default { return $null }
    }
}

The auto probe order prefers premium backends when installed (ElevenLabs > Piper > native). At
Phase 1 launch, only native exists, so auto trivially resolves to native. This ordering
means users who later install ElevenLabs get an automatic upgrade without config changes.

4. TTS PID tracking uses .tts.pid separate from .sound.pid.

The ADR specified this for mode independence. The speak() function manages .tts.pid with the
same kill-previous pattern as kill_previous_sound():

kill_previous_tts() {
  local pidfile="$PEON_DIR/.tts.pid"
  if [ -f "$pidfile" ]; then
    local old_pid
    old_pid=$(cat "$pidfile" 2>/dev/null)
    if [ -n "$old_pid" ] && kill -0 "$old_pid" 2>/dev/null; then
      kill "$old_pid" 2>/dev/null
    fi
    rm -f "$pidfile"
  fi
}
save_tts_pid() {
  echo "$1" > "$PEON_DIR/.tts.pid"
}

The trainer subshell waits for both .sound.pid and .tts.pid to complete before playing
trainer content. In sound-then-speak mode, main TTS starts after main sound — so .sound.pid
can finish while .tts.pid is mid-utterance. Waiting for both PIDs prevents the trainer sound
from overlapping with the main event's TTS phrase. The wait logic uses the same poll pattern as
the existing .sound.pid wait (10s timeout, 100ms poll interval).

5. PEON_TEST=1 makes TTS synchronous for test capture.

The existing test pattern: PEON_TEST=1 causes play_sound() to run synchronously (no nohup,
no &). TTS follows the same convention — speak() runs the backend in the foreground when
PEON_TEST=1, allowing BATS tests to capture the invocation and verify arguments. In production,
the backend runs via nohup ... & (Unix) or Start-Process -WindowStyle Hidden (Windows).

Interface Design Copy Section

#### speak() shell function (Unix)

speak() {
  local text="$1"
  [ -z "$text" ] && return 0
  kill_previous_tts
  # _resolve_tts_backend returns a script filename (e.g., "tts-native.sh").
  # find_bundled_script resolves it to an absolute path.
  local script_name
  script_name="$(_resolve_tts_backend "${TTS_BACKEND:-auto}")" || return 0
  local abs_script
  abs_script="$(find_bundled_script "$script_name")" 2>/dev/null || return 0
  [ -x "$abs_script" ] || return 0
  local voice="${TTS_VOICE:-default}"
  local rate="${TTS_RATE:-1.0}"
  local vol="${TTS_VOLUME:-0.5}"
  if [ "${PEON_TEST:-0}" = "1" ]; then
    printf '%s\n' "$text" | "$abs_script" "$voice" "$rate" "$vol" >/dev/null 2>&1
  else
    # printf '%s\n' is used instead of echo to avoid flag interpretation
    # (e.g., text starting with "-n" or "-e"). Text is passed as $0 to sh -c,
    # avoiding shell interpolation of metacharacters in the text content.
    nohup sh -c 'printf "%s\n" "$0" | "$1" "$2" "$3" "$4"' \
      "$text" "$abs_script" "$voice" "$rate" "$vol" >/dev/null 2>&1 &
    save_tts_pid $!
  fi
}

#### Invoke-TtsSpeak PowerShell function (Windows)

function Invoke-TtsSpeak {
    param(
        [string]$Text,
        [string]$Backend = "auto",
        [string]$Voice = "default",
        [double]$Rate = 1.0,
        [double]$Volume = 0.5
    )
    if (-not $Text) { return }
    # Kill previous TTS
    $pidFile = Join-Path $InstallDir ".tts.pid"
    if (Test-Path $pidFile) {
        $oldPid = Get-Content $pidFile -ErrorAction SilentlyContinue
        if ($oldPid) {
            try { Stop-Process -Id $oldPid -Force -ErrorAction SilentlyContinue } catch {}
        }
        Remove-Item $pidFile -Force -ErrorAction SilentlyContinue
    }
    $scriptName = Resolve-TtsBackend -Backend $Backend
    if (-not $scriptName) { return }
    $scriptPath = Join-Path $InstallDir "scripts\$scriptName"
    if (-not (Test-Path $scriptPath)) { return }
    # Text is Base64-encoded to avoid shell metacharacter injection. Dynamic text
    # from template variables ({summary}, {project}) can contain double quotes,
    # dollar signs, backticks, and other PowerShell-interpreted characters that
    # would corrupt or break a directly-interpolated -Command string. This matches
    # the Unix side's safety guarantee (text passed as $0, never interpolated).
    $b64 = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($Text))
    $proc = Start-Process -FilePath "powershell.exe" 
        -ArgumentList "-NoProfile", "-NonInteractive", "-Command",
            "[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('$b64')) | & '$scriptPath' -voice '$Voice' -rate $Rate -vol $Volume" 
        -WindowStyle Hidden -PassThru
    $proc.Id | Set-Content $pidFile
}

#### Python block output (new variables)

The Python block gains these additional print() outputs:

print('TTS_ENABLED=' + ('true' if tts_enabled else 'false'))
print('TTS_TEXT=' + q(tts_text))
print('TTS_BACKEND=' + q(tts_backend))
print('TTS_VOICE=' + q(tts_voice))
print('TTS_RATE=' + q(str(tts_rate)))
print('TTS_VOLUME=' + q(str(tts_volume)))
print('TTS_MODE=' + q(tts_mode))
print('TRAINER_TTS_TEXT=' + q(trainer_tts_text))

#### Speech text resolution (Python block addition)

--- TTS speech text resolution ---

tts_cfg = cfg.get('tts', {})
tts_enabled = tts_cfg.get('enabled', False) and not paused
tts_text = ''
tts_backend = tts_cfg.get('backend', 'auto')
tts_voice = tts_cfg.get('voice', 'default')
tts_rate = tts_cfg.get('rate', 1.0)
tts_volume = tts_cfg.get('volume', 0.5)
tts_mode = tts_cfg.get('mode', 'sound-then-speak')
if tts_enabled and category:
    # Chain: manifest speech_text → notification template → default
    if pick and pick.get('speech_text'):
        _speech_tpl = pick['speech_text']
    elif _tpl:
        _speech_tpl = _tpl  # already resolved notification template
    else:
        _speech_tpl = '{project} \u2014 {status}'
    try:
        tts_text = _speech_tpl.format_map(_tpl_vars)
    except Exception:
        tts_text = ''
    # Empty after interpolation → skip
    tts_text = tts_text.strip()
    if tts_text == '\u2014' or not tts_text:
        tts_text = ''

The pick variable (the chosen manifest sound entry) is already in scope from sound selection
(line 3571). The _tpl_vars dict is already populated from notification template resolution
(line 3730). This placement — after both sound selection and template resolution — means all
inputs are available.

TRAINER_TTS_TEXT reuses the existing trainer progress string verbatim — the same string that
currently renders into TRAINER_MSG for desktop notifications. No reformatting for speech in
this phase (resolved question #1):

After trainer reminder logic (which already computes trainer_msg):

trainer_tts_text = trainer_msg if (tts_enabled and trainer_msg) else ''

#### Speech text resolution (PowerShell addition)

--- TTS speech text resolution ---

$ttsCfg = if ($config.tts) { $config.tts } else { @{} }
$ttsEnabled = ($ttsCfg.enabled -eq $true) -and (-not $paused)
$ttsText = ""
$ttsBackend = if ($ttsCfg.backend) { $ttsCfg.backend } else { "auto" }
$ttsVoice = if ($ttsCfg.voice) { $ttsCfg.voice } else { "default" }
$ttsRate = if ($ttsCfg.rate) { $ttsCfg.rate } else { 1.0 }
$ttsVolume = if ($ttsCfg.volume) { $ttsCfg.volume } else { 0.5 }
$ttsMode = if ($ttsCfg.mode) { $ttsCfg.mode } else { "sound-then-speak" }
if ($ttsEnabled -and $category) {
    $speechTpl = ""
    if ($chosen -and $chosen.speech_text) {
        $speechTpl = $chosen.speech_text
    } elseif ($resolvedTemplate) {
        $speechTpl = $resolvedTemplate
    } else {
        $speechTpl = "{project} u{2014} {status}"
    }
    # Interpolate template variables (same set as notification templates)
    $ttsText = $speechTpl
    foreach ($key in $tplVars.Keys) {
        $ttsText = $ttsText.Replace("{$key}", $tplVars[$key])
    }
    $ttsText = $ttsText.Trim()
    if ($ttsText -eq "u{2014}" -or -not $ttsText) { $ttsText = "" }
}

#### PowerShell mode sequencing (Windows)

The PowerShell sound playback section gains the same mode-aware branching as Unix:

if (-not $skipSound) {
    switch ($ttsMode) {
        "sound-then-speak" {
            if ($soundFile -and (Test-Path $soundFile)) { Play-Sound $soundFile $volume }
            if ($ttsText) { Invoke-TtsSpeak -Text $ttsText -Backend $ttsBackend -Voice $ttsVoice -Rate $ttsRate -Volume $ttsVolume }
        }
        "speak-only" {
            if ($ttsText) { Invoke-TtsSpeak -Text $ttsText -Backend $ttsBackend -Voice $ttsVoice -Rate $ttsRate -Volume $ttsVolume }
        }
        "speak-then-sound" {
            if ($ttsText) { Invoke-TtsSpeak -Text $ttsText -Backend $ttsBackend -Voice $ttsVoice -Rate $ttsRate -Volume $ttsVolume }
            if ($soundFile -and (Test-Path $soundFile)) { Play-Sound $soundFile $volume }
        }
    }
}

#### Config schema addition

{
  "tts": {
    "enabled": false,
    "backend": "auto",
    "voice": "default",
    "rate": 1.0,
    "volume": 0.5,
    "mode": "sound-then-speak"
  }
}

Added to config.json defaults. Runtime code uses cfg.get('tts', {}) with per-field defaults,
so missing keys in existing configs are safe.

#### Debug logging

TTS adds a [tts] log phase following the existing structured logging format:

[tts] enabled=true backend=native voice=Alex rate=1.0 volume=0.5 mode=sound-then-speak
[tts] text="api-server — all tests passing" source=template
[tts] cmd="scripts/tts-native.sh" pid=48291

Or when skipped:

[tts] enabled=true backend=auto resolved=none skip=no_backend
[tts] enabled=true text="" skip=empty_text
[tts] enabled=false skip=disabled

Implementation Phases Copy Chapter

Phase 1: Config schema and peon update backfill peon update backfill')" title="Copy section prompt for LLMs"> Copy Section

Goal: Existing installs gain the tts config section on next update, and new installs include
it by default.

Deliverables:
- config.json updated with tts section (6 keys, all with safe defaults)
- peon update config merge logic extended to backfill tts section without overwriting
user-modified values (same merge pattern as every prior config addition)
- install.ps1 Windows installer includes tts section in generated config

Test strategy:
- Unit (BATS): peon update on a config without tts section adds it with correct defaults.
peon update on a config with existing tts section preserves user values.
- Unit (Pester): Same two cases for the Windows config generation path.

Infrastructure: None.

Documentation: None (config key docs ship with tts-docs feature).

Dependencies: None.

Definition of done:
- [ ] config.json contains tts section with 6 keys
- [ ] peon update backfills tts section on configs that lack it
- [ ] peon update preserves existing tts values when section already present
- [ ] Windows installer generates config with tts section
- [ ] All existing BATS and Pester tests pass (no regressions)

Phase 2: Speech text resolution in Python block Copy Section

Goal: The Python routing block resolves TTS speech text from the manifest/template/default
chain and outputs TTS_* shell variables.

Deliverables:
- Speech text resolution logic added to peon.sh Python block (after sound selection and template
resolution)
- 8 new print() outputs: TTS_ENABLED, TTS_TEXT, TTS_BACKEND, TTS_VOICE, TTS_RATE,
TTS_VOLUME, TTS_MODE, TRAINER_TTS_TEXT
- TTS config loading with safe defaults (cfg.get('tts', {}))

Test strategy:
- Unit (BATS): Mock events with TTS enabled verify correct TTS_TEXT output for each source
in the resolution chain: (a) manifest speech_text present → uses it, (b) notification template
configured → uses it, (c) neither → uses default "{project} — {status}". (d) Empty text after
interpolation → TTS_TEXT is empty. (e) TTS disabled → TTS_ENABLED=false, no TTS_TEXT.

Infrastructure: None.

Documentation: None.

Dependencies: Phase 1 (config schema).

Definition of done:
- [ ] Python block reads tts config section with safe defaults
- [ ] TTS_TEXT resolves from manifest speech_text when present
- [ ] TTS_TEXT falls back to notification template when no speech_text
- [ ] TTS_TEXT falls back to default template "{project} — {status}" when no notification template
- [ ] Empty resolved text produces empty TTS_TEXT
- [ ] TTS_ENABLED=false when TTS disabled or hook is paused
- [ ] TRAINER_TTS_TEXT populated with trainer progress string when trainer fires and TTS enabled
- [ ] All 8 TTS_* variables printed in output block

Phase 3: speak() function, PID tracking, and mode sequencing (Unix) speak() function, PID tracking, and mode sequencing (Unix)')" title="Copy section prompt for LLMs"> Copy Section

Goal: peon.sh gains the speak() shell function, TTS PID management, backend resolution,
and mode-aware sequencing in _run_sound_and_notify().

Deliverables:
- speak() function: backend resolution → script invocation → PID tracking
- _resolve_tts_backend() function: config value → script path mapping with auto probing
- kill_previous_tts() and save_tts_pid() functions
- _run_sound_and_notify() updated with mode-aware sound/TTS ordering
- Trainer reminder block updated to wait for both .sound.pid and .tts.pid, then speak
TRAINER_TTS_TEXT after trainer sound
- All suppression rules (headphones_only, meeting_detect, suppress_sound_when_tab_focused,
pause) applied to TTS
- PEON_TEST=1 synchronous mode for test capture
- [tts] debug log phase entries

Test strategy:
- Unit (BATS): Mock backend script (logs invocation args to a file instead of speaking).
Tests verify: (a) speak() invokes backend with correct args order, (b) text passed on stdin,
(c) mode sequencing — sound-then-speak plays sound then speaks, speak-only skips sound,
speak-then-sound speaks then plays sound, (d) empty TTS_TEXT skips TTS invocation entirely,
(e) TTS_ENABLED=false skips all TTS, (f) suppression rules suppress TTS same as sound,
(g) kill-previous kills old .tts.pid before new speak, (h) auto backend resolution probes
scripts in order, (i) missing backend script → graceful skip.
- Integration (BATS): Full hook invocation with TTS enabled, mock backend, and mock afplay
— verify both sound and TTS fire in correct order for each mode.

Infrastructure: None.

Documentation: None.

Dependencies: Phase 2 (speech text resolution).

Definition of done:
- [ ] speak() invokes resolved backend script with text on stdin
- [ ] Backend receives voice, rate, volume as positional args
- [ ] .tts.pid written after background TTS process starts
- [ ] kill_previous_tts() kills old TTS before new invocation
- [ ] _run_sound_and_notify() respects TTS_MODE for ordering
- [ ] speak-only mode skips play_sound() entirely
- [ ] All suppression rules apply to TTS
- [ ] PEON_TEST=1 runs TTS synchronously
- [ ] [tts] debug log entries emitted when debug enabled
- [ ] Trainer subshell waits for both .sound.pid and .tts.pid before playing trainer content
- [ ] Trainer speaks TRAINER_TTS_TEXT after trainer sound when TTS enabled
- [ ] Hook return latency unchanged (TTS is async)
- [ ] Missing backend → silent skip, no error

Phase 4: PowerShell port (Windows) Copy Section

Goal: The Windows hook engine (install.ps1 embedded peon.ps1) provides identical TTS
behavior to the Unix implementation.

Deliverables:
- Invoke-TtsSpeak function: backend resolution → Start-Process invocation → PID tracking
- Resolve-TtsBackend function: config value → script path mapping
- TTS PID management (.tts.pid read/write/kill)
- Mode-aware sequencing in the sound playback section
- Speech text resolution in the PowerShell routing block (mirrors Python block output)
- Trainer TTS integration
- Suppression rules applied to TTS

Test strategy:
- Unit (Pester): (a) Resolve-TtsBackend returns correct paths for each named backend,
(b) Resolve-TtsBackend -Backend auto probes in priority order, (c) speech text resolution
chain produces correct output for manifest/template/default sources, (d) TTS disabled → no
Start-Process call, (e) mode sequencing logic branches correctly, (f) .tts.pid file
management (write on speak, read/kill on next speak).

Infrastructure: None.

Documentation: None.

Dependencies: Phase 3 (Unix implementation validates the design; Windows mirrors it).

Definition of done:
- [ ] Invoke-TtsSpeak invokes resolved backend via Start-Process -WindowStyle Hidden
- [ ] Backend receives text on stdin via PowerShell pipeline
- [ ] .tts.pid managed (write/read/kill)
- [ ] Mode sequencing matches Unix behavior
- [ ] Speech text resolution chain matches Python block logic
- [ ] All suppression rules apply
- [ ] Trainer speaks progress when TTS enabled
- [ ] All existing Pester tests pass (no regressions)

Migration & Rollback Copy Chapter

Migration: peon update backfills the tts section into existing configs. Runtime code
defaults every tts field individually via .get() with fallbacks, so partially-populated
configs are safe. tts.enabled defaults to false, meaning TTS has no effect until explicitly
activated — zero behavior change for existing users.

Rollback: Clean git revert. The tts section in config is inert when enabled: false (the
default). Reverting the code leaves the config section harmless. No state migration — .tts.pid
is only created when TTS runs and is cleaned up by kill_previous_tts.

Risks Copy Chapter

Roadmap Connection Copy Chapter

This design implements the tts-integration feature under v2/m5 ("The peon speaks to you").
It's the P1 foundation that tts-native, tts-cli, and tts-notifications all depend on.

The roadmap correctly sequences the dependency chain:
tts-integration → tts-native → tts-cli → tts-notifications / tts-docs / tts-elevenlabs / tts-piper

No roadmap changes needed — the existing feature breakdown and dependencies match this design.

Resolved Questions Copy Chapter

1. Trainer TTS text format: Use the existing trainer progress string as-is (e.g., "75 of 300
pushups. 50 of 300 squats. 21 percent."). Optimize for speech later if user feedback warrants it.

2. TTS volume in speak-only mode: Always use tts.volume, independent from the top-level
volume. Users choosing speak-only set tts.volume to their preferred level.

3. Tab-focused suppression: Suppress both sound and TTS uniformly when
suppress_sound_when_tab_focused is true. Granular per-modality suppression
(suppress_tts_when_tab_focused) is tracked as a separate roadmap feature under v2/m5.

---

Revision History Copy Chapter

---

Designs/Win Notification Templates Copy Section

Windows Notification Template Resolution Engine

Date: 2026-03-24
Card: kr62ia
Status: Implementation

Overview Copy Chapter

Port the notification template resolution logic from peon.sh (Python block, lines 3698-3723) to PowerShell in peon.ps1 (embedded in install.ps1). This achieves feature parity for Windows users.

Unix Reference Implementation (peon.sh:3698-3723) Copy Chapter

The Python block:
1. Maps categories to template keys: task.complete -> stop, task.error -> error
2. Applies event-specific overrides: PermissionRequest -> permission, idle_prompt -> idle, elicitation_dialog -> question
3. Looks up template string from config.notification_templates[key]
4. Substitutes variables using format_map() with a defaultdict(str) (unknown vars -> empty string)
5. Truncates transcript_summary to 120 chars

PowerShell Implementation Copy Chapter

Insertion Point Copy Section

After the sound-picking block closes (} # end if (-not $skipSound) at ~line 1342) and before the desktop notification dispatch section (~line 1344). This ensures $notifyMsg is overwritten with the resolved template before it reaches win-notify.ps1.

Template Key Mapping Copy Section

$tplKeyMap = @{ 'task.complete' = 'stop'; 'task.error' = 'error' }
$tplKey = if ($category -and $tplKeyMap.ContainsKey($category)) { $tplKeyMap[$category] } else { $null }
Event-specific overrides

if ($hookEvent -eq 'PermissionRequest') { $tplKey = 'permission' }
if ($ntype -eq 'idle_prompt') { $tplKey = 'idle' }
if ($ntype -eq 'elicitation_dialog') { $tplKey = 'question' }

Variable Substitution Copy Section

Uses [regex]::Replace with a ScriptBlock evaluator (available since PS 2.0):

$tplVars = @{
    project   = $project
    summary   = ($summaryRaw).Substring(0, [Math]::Min($summaryRaw.Length, 120))
    tool_name = ($event.tool_name -as [string])
    status    = $notifyStatus
    event     = $hookEvent
}
$notifyMsg = [regex]::Replace($tpl, '\{(\w+)\}', {
    param($m)
    $key = $m.Groups[1].Value
    if ($tplVars.ContainsKey($key)) { $tplVars[$key] } else { "" }
})

Fallback Behavior Copy Section

- Missing or empty notification_templates config: $notifyMsg retains its original value (project name)
- Missing template key: no substitution, original $notifyMsg preserved
- Unknown {variable}: replaced with empty string

Test Strategy Copy Chapter

8 Pester scenarios in tests/win-notification-templates.Tests.ps1:

1. Stop with {summary} template
2. Stop without transcript_summary (resolves to empty)
3. PermissionRequest with {tool_name}
4. No template configured (fallback to project name)
5. Unknown variable renders as empty
6. All five template keys map from correct events
7. Summary truncation at 120 chars
8. Special characters in project/tool names

---

Plans/2026 02 16 Trainer Mode Design Copy Section

Trainer Mode Design

Date: 2026-02-16
Status: Approved

Overview Copy Chapter

The peon IS your personal trainer. Pavel-style daily exercise mode where your Warcraft peon nags you to do 300 pushups and 300 squats throughout the day. Same orc who tells you "work work" now tells you to drop and give him twenty. ElevenLabs orc voice. Piggybacks on IDE hook events — no daemon, no cron.

The meme: "I replaced my personal trainer with a Warcraft peon."

Config Copy Chapter

New trainer section in config.json:

{
  "trainer": {
    "enabled": false,
    "exercises": {
      "pushups": 300,
      "squats": 300
    },
    "reminder_interval_minutes": 20,
    "reminder_min_gap_minutes": 5
  }
}

- exercises — exercise name to daily goal. Default Pavel 300/300, configurable to 100 or 200.
- reminder_interval_minutes — how often to nag (clock time, checked on each hook event).
- reminder_min_gap_minutes — minimum gap between reminders to prevent spam during rapid task completions.

State Copy Chapter

Trainer state in .state.json:

{
  "trainer": {
    "date": "2026-02-16",
    "reps": { "pushups": 75, "squats": 50 },
    "last_reminder_ts": 1739721600
  }
}

- Auto-resets when date doesn't match today.
- last_reminder_ts — unix timestamp for hybrid timing logic.

Sounds Copy Chapter

Orc peon voice lines generated via ElevenLabs (voice ID: llD6rmWjUTFZjqbsK8zS). The peon is your drill sergeant — broken English, orcish grunts, deadpan humor.

Trainer sounds live in a dedicated directory, separate from packs:

~/.claude/hooks/peon-ping/trainer/
  sounds/
    remind/          # Peon nagging you to do reps
    log/             # Peon acknowledging your work
    complete/        # Peon celebrating daily goal
    slacking/        # Peon disappointed in you
  manifest.json

Voice Line Examples Copy Section

trainer.remind (fired every ~20 min of coding):
- "You sit too long! Peon say do pushups NOW!"
- "Human weak! Need more squats! Peon demand it!"
- "Work work... on MUSCLES! Drop and give peon twenty!"
- "Peon no let you be lazy! Squat time!"
- "Me notice you just sitting there. Floor. Pushups. Now."
- "Something need doing? YES. PUSHUPS."
- "Peon tired of watching human just type type type. MOVE BODY!"
- "You think code review hard? Try three hundred squats!"

trainer.log (when you log reps):
- "Hmm, not bad for puny human."
- "Peon approve. Keep going!"
- "Work work! Muscles getting bigger maybe!"
- "Good good! Peon proud... a little."
- "Okie dokie. More later!"

trainer.complete (daily goal hit):
- "THREE HUNDRED! Human strong like orc now! ...almost."
- "Peon... Peon impressed. You done good today."
- "GOAL COMPLETE! Peon give you rest. For now."
- "Zug zug! Human finish all reps! Maybe you not so weak after all."

trainer.slacking (behind pace, past noon):
- "Peon very disappointed. You barely do anything today."
- "Half day gone and you still weak! MORE REPS!"
- "Human, you falling behind. Peon no like lazy."
- "Me not that kind of orc... but me WILL nag you more."

manifest.json maps categories to files:

/ Detailed source-code truncated for AI context efficiency. /

CLI Copy Chapter

peon trainer on                  # enable trainer mode
peon trainer off                 # disable trainer mode
peon trainer status              # show today's progress
peon trainer log 25 pushups      # log 25 pushups
peon trainer log 30 squats       # log 30 squats
peon trainer goal 200            # set both exercises to 200
peon trainer goal pushups 100    # set just pushups to 100

peon trainer status output example:

Peon Trainer -- 2026-02-16
  pushups:  ████████░░░░░░░░  125/300  (42%)
  squats:   ██░░░░░░░░░░░░░░   50/300  (17%)
  Next reminder in ~12 min

Reminder Logic Copy Chapter

On every hook event, after normal sound logic:

1. Check trainer.enabled — if false, skip.
2. Check trainer.date vs today — if different, reset reps to 0.
3. Check if daily goal already hit for all exercises — if so, skip reminders.
4. Calculate time since last_reminder_ts.
5. If >= reminder_interval_minutes AND >= reminder_min_gap_minutes:
- Pick random sound from trainer.remind (or trainer.slacking if behind pace).
- Output trainer sound variables.
- Update last_reminder_ts.
- Desktop notification with progress summary.

Pace check: If current time is past noon and reps below 25% of goal, use trainer.slacking.

Sound priority: Trainer reminder plays after the normal hook sound with ~1s delay. Skip trainer reminder on session.start to avoid stacking.

On rep log: Play trainer.log sound. If log pushes total to goal, play trainer.complete instead.

Files Touched Copy Chapter

- peon.sh — trainer logic in Python block + CLI subcommand + delayed trainer sound playback
- config.json — add trainer section defaults
- tests/ — new BATS tests for trainer logic
- README.md — trainer section in docs

Not In Scope Copy Chapter

- No daemon or background process.
- No generalized exercise framework — Pavel pushups + squats with configurable goal number.
- No web UI or dashboard.
- No trainer-specific mobile notifications (reuses existing mobile infra).

---

Plans/2026 02 16 Trainer Mode Plan Copy Section

Trainer Mode Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Add a Pavel-style daily exercise trainer to peon-ping that nags you to do pushups and squats during coding sessions.

Architecture: Trainer logic lives inside the existing peon.sh Python block. On each hook event, after normal sound routing, the Python block checks trainer config/state and optionally outputs a second set of sound variables for a trainer reminder. CLI subcommands (peon trainer ...) are added to the existing case statement. Trainer sounds use a dedicated trainer/ directory with its own manifest.json.

Tech Stack: Bash, embedded Python 3, BATS for testing

Design doc: docs/plans/2026-02-16-trainer-mode-design.md

Branch: Create feat/trainer-mode from current HEAD before starting.

---

Task 1: Create branch and trainer sound directory scaffold Copy Section

Files:
- Create: trainer/sounds/remind/.gitkeep
- Create: trainer/sounds/log/.gitkeep
- Create: trainer/sounds/complete/.gitkeep
- Create: trainer/sounds/slacking/.gitkeep
- Create: trainer/manifest.json

Step 1: Create branch

cd /Users/garysheng/Documents/github-repos/peonping-repos/peon-ping
git checkout -b feat/trainer-mode

Step 2: Create trainer directory structure

mkdir -p trainer/sounds/{remind,log,complete,slacking}
touch trainer/sounds/remind/.gitkeep
touch trainer/sounds/log/.gitkeep
touch trainer/sounds/complete/.gitkeep
touch trainer/sounds/slacking/.gitkeep

Step 3: Create manifest.json

Create trainer/manifest.json:

{
  "trainer.remind": [
    { "file": "sounds/remind/placeholder.wav", "label": "Time for reps!" }
  ],
  "trainer.log": [
    { "file": "sounds/log/placeholder.wav", "label": "Logged." }
  ],
  "trainer.complete": [
    { "file": "sounds/complete/placeholder.wav", "label": "Goal reached!" }
  ],
  "trainer.slacking": [
    { "file": "sounds/slacking/placeholder.wav", "label": "You're falling behind." }
  ]
}

Note: placeholder entries will be replaced with real ElevenLabs audio later. The code should gracefully handle missing sound files.

Step 4: Update config.json with trainer defaults

Add trainer section to config.json (the default template):

{
  "active_pack": "peon",
  "volume": 0.5,
  "enabled": true,
  "desktop_notifications": true,
  "categories": {
    "session.start": true,
    "task.acknowledge": true,
    "task.complete": true,
    "task.error": true,
    "input.required": true,
    "resource.limit": true,
    "user.spam": true
  },
  "annoyed_threshold": 3,
  "annoyed_window_seconds": 10,
  "silent_window_seconds": 0,
  "pack_rotation": [],
  "pack_rotation_mode": "random",
  "session_ttl_days": 7,
  "linux_audio_player": "",
  "trainer": {
    "enabled": false,
    "exercises": {
      "pushups": 300,
      "squats": 300
    },
    "reminder_interval_minutes": 20,
    "reminder_min_gap_minutes": 5
  }
}

Step 5: Commit

git add trainer/ config.json
git commit -m "feat(trainer): add directory scaffold and config defaults"

---

Task 2: Add trainer CLI subcommands (on/off/status/log/goal) Copy Section

Files:
- Modify: peon.sh (lines 599-1288, the case statement)

Step 1: Write BATS tests for trainer CLI

Create tests/trainer.bats:

/ Detailed source-code truncated for AI context efficiency. /

Step 2: Run tests to verify they fail

bats tests/trainer.bats

Expected: All tests FAIL (trainer subcommand not implemented yet).

Step 3: Add trainer subcommand to peon.sh case statement

Insert before the --*) catch-all (line 1282) in the case statement. Add a trainer) branch:

/ Detailed source-code truncated for AI context efficiency. /

Step 4: Run tests to verify they pass

bats tests/trainer.bats

Expected: All tests PASS.

Step 5: Commit

git add peon.sh tests/trainer.bats
git commit -m "feat(trainer): add CLI subcommands (on/off/status/log/goal)"

---

Task 3: Add trainer reminder logic to Python hook block Copy Section

Files:
- Modify: peon.sh (lines 1310-1672, the embedded Python block)

Step 1: Write BATS tests for trainer reminders on hook events

Append to tests/trainer.bats:

/ Detailed source-code truncated for AI context efficiency. /

Step 2: Run tests to verify they fail

bats tests/trainer.bats

Expected: New hook-event tests FAIL.

Step 3: Add trainer reminder logic to the Python block

In the embedded Python block (around line 1650, after the main sound selection but before the final variable output), add trainer check logic. The Python block should:

1. Read trainer from config — if not enabled, set TRAINER_SOUND="" and skip.
2. Load trainer state from .state.json — auto-reset if date doesn't match today.
3. Check if event is SessionStart — if so, skip trainer.
4. Check if all exercises at or above goal — if so, skip.
5. Check elapsed time vs interval/min_gap — if not due, skip.
6. Load trainer/manifest.json, pick random sound from trainer.remind (or trainer.slacking if behind pace).
7. Update last_reminder_ts in state, save state.
8. Output TRAINER_SOUND, TRAINER_VOL, TRAINER_MSG variables.

The exact insertion point is near the end of the Python block, after SOUND_FILE is determined but before the final print() statements that output shell variables. Add these output lines:

/ Detailed source-code truncated for AI context efficiency. /

Then in the output section, add:

print(f"TRAINER_SOUND='{trainer_sound}'")
print(f"TRAINER_MSG='{trainer_msg}'")

Step 4: Add trainer sound playback to shell section

After the main _run_sound_and_notify call (around line 1781), add trainer sound playback:

--- Trainer reminder sound (delayed, after main sound) ---

if [ -n "${TRAINER_SOUND:-}" ] && [ -f "$TRAINER_SOUND" ]; then
  (
    sleep 1
    play_sound "$TRAINER_SOUND" "$VOLUME"
    if [ "${NOTIFY:-}" = "1" ]; then
      send_notification "Trainer" "${TRAINER_MSG:-Time for reps!}" "${NOTIFY_COLOR:-blue}"
    fi
  ) &
  if [ "${PEON_TEST:-0}" != "1" ]; then
    disown 2>/dev/null
  fi
fi

For test mode (PEON_TEST=1), the delayed playback needs to be synchronous. Adjust to:

if [ -n "${TRAINER_SOUND:-}" ] && [ -f "$TRAINER_SOUND" ]; then
  if [ "${PEON_TEST:-0}" = "1" ]; then
    play_sound "$TRAINER_SOUND" "$VOLUME"
  else
    (
      sleep 1
      play_sound "$TRAINER_SOUND" "$VOLUME"
      if [ "${NOTIFY:-}" = "1" ]; then
        send_notification "Trainer" "${TRAINER_MSG:-Time for reps!}" "${NOTIFY_COLOR:-blue}"
      fi
    ) & disown 2>/dev/null
  fi
fi

Step 5: Run tests to verify they pass

bats tests/trainer.bats

Expected: All tests PASS.

Step 6: Run full test suite to ensure no regressions

bats tests/peon.bats

Expected: All existing tests still PASS.

Step 7: Commit

git add peon.sh tests/trainer.bats
git commit -m "feat(trainer): add reminder logic to hook event pipeline"

---

Task 4: Add trainer help text and README docs Copy Section

Files:
- Modify: peon.sh (help text around line 1245)
- Modify: README.md

Step 1: Add trainer to main help output

In the help) case (around line 1245), add a trainer section to the help text:

trainer on|off           Enable/disable daily exercise trainer
  trainer status           Show today's progress
  trainer log N exercise   Log reps (e.g. peon trainer log 25 pushups)
  trainer goal N           Set goal for all exercises
  trainer goal EX N        Set goal for one exercise
  trainer help             Show trainer help

Step 2: Add trainer section to README.md

Add a section after the existing features documentation:

Trainer Mode  Copy Chapter
Built-in Pavel-style daily exercise trainer. Reminds you to do pushups and squats
while you code — uses custom voice lines that play alongside your normal peon-ping sounds.
Quick Start  Copy Section

... code for a while, get reminded to do reps ...

How It Works  Copy Section
Trainer reminders piggyback on your coding session — every ~20 minutes of active
coding, you'll hear a voice line reminding you to do reps. No background daemon needed.
Log your reps with peon trainer log, and progress resets automatically at midnight.
Custom Voice Lines  Copy Section
Drop your own audio files into ~/.claude/hooks/peon-ping/trainer/sounds/:

Update trainer/manifest.json to register your sound files.

Step 3: Commit

git add peon.sh README.md
git commit -m "docs: add trainer mode to help text and README"

---

Task 5: Final integration test and cleanup Copy Section

Step 1: Run full test suite

bats tests/

Expected: All tests pass across all test files.

Step 2: Manual smoke test

Enable trainer

peon trainer on
Check status

peon trainer status
Log some reps

peon trainer log 25 pushups
peon trainer log 30 squats
Check progress updated

peon trainer status
Set custom goal

peon trainer goal 100
Disable

peon trainer off

Step 3: Verify config.json template is clean

Read config.json and confirm the trainer section is present with correct defaults.

Step 4: Commit any fixups if needed

If any issues found during smoke testing, fix and commit.

---

Summary Copy Chapter

---

Plans/2026 02 19 Path Rules Design Copy Section

Design: path_rules + Override Hierarchy Cleanup

Date: 2026-02-19
Scope: peon-ping CLI (peon.sh, config.json, peon update migration)

---

Problem Copy Chapter

There is no way to assign a specific sound pack to a project/repo automatically. The workarounds are:
- Drop a config.json in ${PWD}/.claude/hooks/peon-ping/ (manual, per-repo file)
- Use /peon-ping-use each session (ephemeral, not persistent)

Also, two existing config keys have misleading names:
- active_pack sounds like the currently-playing pack, but it's just the global fallback
- agentskill (rotation mode) names the mechanism (a skill) not the behavior (per-session override)

---

Design Copy Chapter

Override Hierarchy Copy Section

From most to least authoritative. Each layer is only consulted if all layers above it produce no result.

Philosophy: more specific and more immediate beats more general. A temporary in-session choice (session_override) beats a standing rule (path_rules), which beats a global default. path_rules is a floor for matched repos, not a ceiling — you can always escape it for a session.

---

Config Schema Changes Copy Section

#### New: path_rules

Array of objects. First match wins. Evaluated against cwd using Python fnmatch (glob-style).

"path_rules": [
  { "pattern": "/peonping-repos/", "pack": "peon" },
  { "pattern": "/work/clients/",   "pack": "glados" }
]

- Patterns use glob syntax (*, ?, [seq])
- First matching rule wins; remaining rules are not evaluated
- If matched pack is not installed, falls through to next layer
- rotation per rule is not supported (YAGNI)

#### Renamed: active_pack → default_pack

active_pack was misleading — it implied the currently-playing pack, not the fallback. default_pack reflects its role as the baseline when nothing more specific matches.

#### Renamed: agentskill mode → session_override mode

The pack_rotation_mode value "agentskill" named the mechanism (a Claude Code skill). "session_override" names the behavior (pack is overridden per session via explicit assignment).

---

Migration (via peon update) peon update)')" title="Copy section prompt for LLMs"> Copy Section

Both renames are handled automatically during peon update:

1. If active_pack exists and default_pack does not → rename key in-place
2. If pack_rotation_mode is "agentskill" → rewrite to "session_override"
3. Write updated config back to disk

During the transition window, the runtime reads both old and new key names (new preferred, old as fallback). This ensures configs not yet migrated continue to work.

---

Matching Logic Copy Section

Inserted in peon.sh Python block after config load and cwd extraction, before the rotation/default block. Only runs if session_override mode has not already assigned a pack.

import fnmatch
for rule in cfg.get('path_rules', []):
    if cwd and fnmatch.fnmatch(cwd, rule.get('pattern', '')):
        candidate = rule.get('pack', '')
        if candidate and os.path.isdir(os.path.join(peon_dir, 'packs', candidate)):
            active_pack = candidate
            break  # first match wins

---

CLI / UX Copy Section

- peon status should show active path rule when one is matched (e.g. path rule: /peonping-repos/ → peon)
- peon config set path_rules ... is out of scope — JSON arrays are awkward to set via CLI; users edit config.json directly
- README and peon help should document path_rules alongside pack_rotation

---

Out of Scope Copy Chapter

- Per-path rotation ("rotation": [...] in a rule)
- path_rules inside local project config (redundant — local config already scopes to that exact directory)
- A dedicated peon path-rules subcommand

---

Files Affected Copy Chapter

---

Plans/2026 02 20 Ide Click To Focus Design Copy Section

IDE Click-to-Focus Design

Date: 2026-02-20
Status: Approved

Problem Copy Chapter

When peon-ping runs inside an IDE's embedded terminal (Cursor, VS Code, Windsurf, Zed), clicking the notification overlay does nothing. _mac_terminal_bundle_id() returns empty because TERM_PROGRAM is vscode (not a standalone terminal), so the click handler never gets registered.

The _mac_ide_pid() function already detects IDE ancestor PIDs and passes them as argv[6] to mac-overlay.js, but that value is currently unused ("reserved for future").

Solution Copy Chapter

When bundle_id is empty, fall back to deriving the bundle ID from the IDE ancestor PID using lsappinfo (macOS built-in). This populates bundle_id for both the overlay and terminal-notifier notification paths with no additional changes to those paths.

Changes Copy Chapter

1. peon.sh — Add _mac_bundle_id_from_pid() peon.sh — Add _mac_bundle_id_from_pid()')" title="Copy section prompt for LLMs"> Copy Section

_mac_bundle_id_from_pid() {
  local pid="$1"
  [ -z "$pid" ] || [ "$pid" = "0" ] && return
  lsappinfo info -only bundleid -app pid="$pid" 2>/dev/null \
    | grep -o '"[^"]*"' | tr -d '"'
}

2. peon.sh — Fallback logic in send_notification() peon.sh — Fallback logic in send_notification()')" title="Copy section prompt for LLMs"> Copy Section

After computing bundle_id and ide_pid, if bundle_id is empty and ide_pid > 0, set bundle_id from _mac_bundle_id_from_pid(ide_pid).

3. mac-overlay.js — PID-based NSRunningApplication fallback mac-overlay.js — PID-based NSRunningApplication fallback')" title="Copy section prompt for LLMs"> Copy Section

When bundleId is empty but idePid > 0, use NSRunningApplication.runningApplicationWithProcessIdentifier_() to activate the IDE app. Belt-and-suspenders fallback for cases where lsappinfo might fail.

4. Tests Copy Section

- BATS: mock lsappinfo returning a bundle ID for a given PID
- BATS: _mac_bundle_id_from_pid with pid=0 returns empty
- Overlay: verify ide_pid activates app when bundle_id is empty

Files Touched Copy Chapter

Scope Exclusions Copy Chapter

- No attempt to switch to the terminal panel within the IDE (just brings window to front)
- No new dependencies (lsappinfo is macOS built-in)
- No changes to Windows/Linux paths

---

Plans/2026 02 20 Multi Window Focus Copy Section

Multi-Window Click-to-Focus (Tabled)

Problem Copy Chapter

What works Copy Chapter

Approaches tried (all failed for multi-window) Copy Chapter

1. System Events AXRaise after activateWithOptions Copy Section

2. System Events AXRaise before set frontmost Copy Section

3. System Events AXRaise + frontmost in one AppleScript Copy Section

4. open -a "Cursor" /path/to/project open -a "Cursor" /path/to/project')" title="Copy section prompt for LLMs"> Copy Section

5. cursor /path/to/project CLI cursor /path/to/project CLI')" title="Copy section prompt for LLMs"> Copy Section

Technical notes Copy Chapter

Current state Copy Chapter

---

Plans/2026 02 24 Notification Templates Design Copy Section

Notification Message Templates

Date: 2026-02-24
Branch: feat/configurable-notifications
Status: Approved

Problem Copy Chapter

Notification message content is hardcoded (just the project name for most events). Users who want richer context (e.g., transcript summary on task completion, tool name on permission requests) have no way to configure it.

Design: Format String Templates Copy Chapter

Config Schema Copy Section

New key notification_templates in config.json:

{
  "notification_templates": {
    "stop": "{project}: {summary}",
    "permission": "{project}: {tool_name}",
    "error": "{project}: error",
    "idle": "{project}",
    "question": "{project}"
  }
}

- Omitted keys fall back to "{project}" (current default behavior).
- Empty or missing notification_templates object = 100% backward-compatible.
- Unknown {variables} render as empty string (no crash).

Available Variables Copy Section

Category-to-Template Key Mapping Copy Section

Implementation Location Copy Section

Python event parser in peon.sh, after per-event msg construction (~line 2860), before the shell variable output block. Uses str.format_map() with collections.defaultdict(str) for safe missing-key handling.

CLI Interface Copy Section

peon notifications template stop "{project}: {summary}"
peon notifications template permission "{project}: {tool_name}"
peon notifications template --reset

Writes to notification_templates in config.json.

What Doesn't Change Copy Section

- Position, dismiss, label configs (already shipped)
- Sound/category routing
- Default behavior with no template config

---

Plans/2026 02 24 Notification Templates Plan Copy Section

Notification Message Templates — Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Let users configure notification message content with format string templates per event type, defaulting to current behavior.

Architecture: Single config key notification_templates holds per-event format strings. A template resolution block in the Python event parser applies str.format_map() with available variables after each event sets its default msg. CLI subcommand peon notifications template provides get/set/reset.

Tech Stack: Bash + embedded Python (peon.sh), BATS tests

---

Task 1: Template Resolution in Python Event Parser Copy Section

Files:
- Modify: peon.sh:2620-2625 (revert hardcoded summary concat)
- Modify: peon.sh:2863 (insert template resolution before shell variable output block)

Step 1: Revert the hardcoded transcript_summary change

Replace the current Stop message block (lines 2620-2624):

_summary = event_data.get('transcript_summary', '').strip()
        if _summary:
            msg = project + ': ' + _summary[:120]
        else:
            msg = project

Back to the original default:

msg = project

This keeps msg = project as the default for all events. Templates will handle enrichment.

Step 2: Add template resolution block

Insert this Python block at peon.sh just BEFORE the line # --- Output shell variables --- (currently line 2864), after the tab color block ends:

--- Notification message template resolution ---

from collections import defaultdict as _defaultdict
_templates = cfg.get('notification_templates', {})
_tpl_key_map = {
    'task.complete': 'stop',
    'task.error': 'error',
}
_tpl_key = _tpl_key_map.get(category, '')
if event == 'Notification':
    if ntype == 'idle_prompt': _tpl_key = 'idle'
    elif ntype == 'elicitation_dialog': _tpl_key = 'question'
elif event == 'PermissionRequest':
    _tpl_key = 'permission'
_tpl = _templates.get(_tpl_key, '')
if _tpl:
    _tpl_vars = _defaultdict(str, {
        'project': project,
        'summary': event_data.get('transcript_summary', '').strip()[:120],
        'tool_name': event_data.get('tool_name', ''),
        'status': status,
        'event': event,
    })
    try:
        msg = _tpl.format_map(_tpl_vars)
    except Exception:
        pass

Step 3: Run existing tests to verify no regression

Run: cd ~/iWorld/projects/peon-ping && bats tests/mac-overlay.bats
Expected: All existing tests pass (the default msg = project behavior is unchanged when no templates configured).

Step 4: Commit

git add peon.sh
git commit -m "feat: notification message template resolution engine
Reads notification_templates from config.json and applies format_map
with available variables ({project}, {summary}, {tool_name}, {status},
{event}). Defaults to current behavior when no templates configured."

---

Task 2: CLI Subcommand — peon notifications template peon notifications template')" title="Copy section prompt for LLMs"> Copy Section

Files:
- Modify: peon.sh:1068 (add template) case before the *) fallback)
- Modify: peon.sh:1070 (update usage string)

Step 1: Add the template case

Insert before line 1069 (*)):

/ Detailed source-code truncated for AI context efficiency. /

Step 2: Update usage string

Change line 1070 from:

echo "Usage: peon notifications <on|off|overlay|standard|position|dismiss|label|test>" >&2; exit 1 ;;

echo "Usage: peon notifications <on|off|overlay|standard|position|dismiss|label|template|test>" >&2; exit 1 ;;

Step 3: Update help text

Find the help text block (~line 1981-1982) and add after the label line:

notifications template [key] [fmt]  Get/set message templates (keys: stop, permission, error, idle, question)

Step 4: Add template display to peon status

In the Python status output block (~lines 765-770), after the label/project_name_map display, add:

_tpls = c.get('notification_templates', {})
if _tpls:
    print('peon-ping: notification templates:')
    for _tk, _tv in _tpls.items():
        print(f'  {_tk} = "{_tv}"')

Step 5: Run tests

Run: cd ~/iWorld/projects/peon-ping && bats tests/mac-overlay.bats
Expected: All existing tests still pass.

Step 6: Commit

git add peon.sh
git commit -m "feat: peon notifications template CLI for get/set/reset"

---

Task 3: BATS Tests for Notification Templates Copy Section

Files:
- Modify: tests/mac-overlay.bats (append new test section after the label priority chain tests, ~line 663)

Step 1: Write the tests

Append to tests/mac-overlay.bats:

/ Detailed source-code truncated for AI context efficiency. /

Step 2: Run the new tests

Run: cd ~/iWorld/projects/peon-ping && bats tests/mac-overlay.bats
Expected: All tests pass including the new template tests.

Step 3: Run full test suite

Run: cd ~/iWorld/projects/peon-ping && bats tests/
Expected: All 55+ tests pass.

Step 4: Commit

git add tests/mac-overlay.bats
git commit -m "test: BATS tests for notification message templates"

---

Task 4: Integration Test with Live Hooks Copy Section

Step 1: Configure template in the dev config

~/iWorld/projects/peon-ping/peon.sh notifications template stop '{project}: {summary}'
~/iWorld/projects/peon-ping/peon.sh notifications template permission '{project}: {tool_name} needs approval'

Step 2: Fire test notifications

echo '{"hook_event_name":"Stop","session_id":"tpl-test","cwd":"/path/to/my-project","transcript_summary":"Added notification templates"}' | ~/.claude/hooks/peon-ping/peon.sh 2>/dev/null &

Expected: Overlay shows "My Project: Added notification templates" at top-right, persistent.

Step 3: Verify stacking still works

Fire a second notification. Both should stack vertically, no overlap.

Step 4: Verify default behavior

Reset templates and fire again — notification should show just "My Project".

~/iWorld/projects/peon-ping/peon.sh notifications template --reset

---

Plans/2026 02 25 Selective Sound Control Copy Section

Selective Sound Control: Documentation & CLI Improvements Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Improve discoverability of the existing desktop_notifications: false feature that lets users keep voice reminders while disabling desktop notification popups.

Architecture: Pure documentation and CLI enhancement. The core feature already works (sounds and notifications are independent). We're adding help text, verbose status output, README sections, and skill documentation updates.

Tech Stack: Bash (peon.sh CLI), Markdown (README, skills), no build tools

---

Task 1: Add verbose status output to CLI Copy Chapter

Files:
- Modify: peon.sh (status command section around line 800-850)

Step 1: Locate the status command section

Search for the status) case in peon.sh:

grep -n "status)" peon.sh | head -3

Expected: Find the status command handler around line 800-850

Step 2: Read current status implementation

Read the status command section to understand current output format:

Look for lines like:

echo "peon-ping: enabled"

echo "peon-ping: volume $vol"

Step 3: Add --verbose flag support

Modify the status command to support --verbose flag:

status)
    # Existing status output
    eval "$(_py_status)"
    # Add verbose flag support
    if [ "${1:-}" = "--verbose" ]; then
      # Read desktop_notifications and mobile_notify from config
      _verbose_out="$(python3 -c "
import json
try:
    cfg = json.load(open('$CONFIG_PY'))
    dn = cfg.get('desktop_notifications', True)
    mn = cfg.get('mobile_notify', {})
    mobile_on = bool(mn and mn.get('service') and mn.get('enabled', True))
    dn_status = 'on' if dn else 'off (sounds still play)'
    mobile_status = 'on' if mobile_on else 'off'
    print('peon-ping: desktop notifications ' + dn_status)
    print('peon-ping: mobile notifications ' + mobile_status)
except Exception:
    pass
")"
      echo "$_verbose_out"
    fi
    exit 0 ;;

Step 4: Test the verbose output

Run the status command with and without verbose:

peon status
Expected: Current output (enabled, volume, pack)
peon status --verbose
Expected: Above + desktop notifications status + mobile notifications status

Step 5: Commit

git add peon.sh
git commit -m "feat: add --verbose flag to peon status command
Shows desktop and mobile notification states with clarifying text
that sounds continue when desktop notifications are disabled."

---

Task 2: Improve help text for notifications command Copy Chapter

Files:
- Modify: peon.sh (help text section around line 1900-1910)

Step 1: Locate notifications help text

Search for the help text:

grep -n "notifications on\|off" peon.sh | grep -v "^#"

Expected: Find help text around line 1905

Step 2: Update help text

Modify the help text to clarify that sounds continue:

Before:

notifications on|off  # Toggle desktop notifications
After:

notifications on|off  # Toggle desktop notification popups (sounds continue playing)

Step 3: Verify help output

peon help | grep notifications
Expected: See updated text with "(sounds continue playing)"

Step 4: Commit

git add peon.sh
git commit -m "docs: clarify notifications command help text
Makes it clear that toggling notifications only affects popups,
not audio playback."

---

Task 3: Add popups alias command Copy Chapter

Files:
- Modify: peon.sh (command routing section where notifications command is handled)

Step 1: Locate notifications command handler

grep -n "notifications)" peon.sh

Expected: Find the case statement around line 900-940

Step 2: Add popups alias

Add a new case that routes to the same handler:

Find this section:

notifications)
  case "${1:-status}" in
    on)
      # ... existing code ...
    off)
      # ... existing code ...
  esac ;;
Add right after:

popups)
  # Alias for 'notifications' command - same behavior
  case "${1:-status}" in
    on)
      # Call same Python code as notifications on
      python3 -c "
import json
try:
    cfg = json.load(open('$CONFIG_PY'))
except Exception:
    cfg = {}
cfg['desktop_notifications'] = True
json.dump(cfg, open('$CONFIG_PY', 'w'), indent=2)
print('peon-ping: desktop notifications on')
"
      sync_adapter_configs; exit 0 ;;
    off)
      python3 -c "
import json
try:
    cfg = json.load(open('$CONFIG_PY'))
except Exception:
    cfg = {}
cfg['desktop_notifications'] = False
json.dump(cfg, open('$CONFIG_PY', 'w'), indent=2)
print('peon-ping: desktop notifications off')
"
      sync_adapter_configs; exit 0 ;;
    *)
      echo "Usage: peon popups on|off" >&2
      exit 1 ;;
  esac ;;

Step 3: Add to help text

Add the popups alias to the help output:

In the help section, add:

popups on|off         # Alias for 'notifications' - toggle desktop notification popups

Step 4: Test the alias

peon popups off
Expected: "peon-ping: desktop notifications off"
peon status --verbose
Expected: Shows "desktop notifications off (sounds still play)"
peon popups on
Expected: "peon-ping: desktop notifications on"

Step 5: Commit

git add peon.sh
git commit -m "feat: add 'peon popups' alias for notifications command
Provides clearer alternative to 'peon notifications' since popups
is more specific than the ambiguous 'notifications' term."

---

Task 4: Update README.md with Common Use Cases section Copy Chapter

Files:
- Modify: README.md (insert after Configuration section around line 270)

Step 1: Find insertion point

grep -n "^## Configuration" README.md

Expected: Find the Configuration section heading

Step 2: Add Common Use Cases section

After the Configuration section and before the next ## heading, insert:

Common Use Cases  Copy Chapter
Sounds without popups  Copy Section
Want voice feedback but no visual distractions?

This keeps all sound categories playing while suppressing desktop notification banners. Mobile notifications (if configured) continue working.
You can also use the alias:

Silent mode with notifications only  Copy Section
Want visual alerts but no audio?

With desktop_notifications: true, you'll get popups but no sounds.
Complete silence  Copy Section
Disable everything:

Step 3: Verify markdown formatting

Preview the section (if you have a markdown viewer)

Or just verify syntax manually

grep -A20 "^## Common Use Cases" README.md

Step 4: Commit

git add README.md
git commit -m "docs: add Common Use Cases section to README
Highlights the 'sounds without popups' use case and clarifies
the three independent toggle controls (enabled, desktop_notifications,
mobile_notify)."

---

Task 5: Add Independent Controls table to README Copy Chapter

Files:
- Modify: README.md (Configuration section around line 240)

Step 1: Locate the Configuration section details

Find where config keys are documented:

grep -n "desktop_notifications" README.md | head -3

Step 2: Add table before the config key descriptions

Insert this table at the start of the Configuration section, right after the JSON example:

Independent Controls  Copy Section
peon-ping has three independent controls that can be mixed and matched:
Config Key
Controls
Affects Sounds
Affects Desktop Popups
Affects Mobile Push
enabled
 Master audio switch | ✅ Yes | ❌ No | ❌ No |
| desktop_notifications | Desktop popup banners | ❌ No | ✅ Yes | ❌ No |
| mobile_notify.enabled | Phone push notifications | ❌ No | ❌ No | ✅ Yes |
This means you can:
- Keep sounds but disable desktop popups: peon notifications off
- Keep desktop popups but disable sounds: peon pause
- Enable mobile push without desktop popups: set desktop_notifications: false and mobile_notify.enabled: true

Step 3: Update desktop_notifications description

Find the existing desktop_notifications description and enhance it:

- desktop_notifications: true/false — toggle desktop notification popups independently from sounds (default: true). When disabled, sounds continue playing but visual popups are suppressed. Mobile notifications are unaffected.

Step 4: Verify table renders correctly

Check the markdown syntax

grep -A10 "^### Independent Controls" README.md

Step 5: Commit

git add README.md
git commit -m "docs: add Independent Controls table to README
Clarifies that enabled, desktop_notifications, and mobile_notify
are three separate toggles that can be combined for different
notification strategies."

---

Task 6: Update Chinese README (README_zh.md) Copy Chapter

Files:
- Modify: README_zh.md

Step 1: Find corresponding sections in Chinese README

grep -n "## Configuration\|## 配置" README_zh.md

Step 2: Add Chinese translation of Common Use Cases

Insert after the Configuration section:

常见用例  Copy Chapter
保留声音但禁用弹窗  Copy Section
想要语音反馈但不想要视觉干扰？

这会保持所有声音类别的播放，同时禁用桌面通知横幅。手机通知（如果已配置）继续工作。
您也可以使用别名：

静音模式但保留通知  Copy Section
想要视觉提醒但不要音频？

当 desktop_notifications: true 时，您将收到弹窗但没有声音。
完全静音  Copy Section
禁用所有功能：

Step 3: Add Chinese translation of Independent Controls table

独立控制  Copy Section
peon-ping 有三个独立的控制开关，可以混合使用：
配置键
控制项
影响声音
影响桌面弹窗
影响手机推送
enabled
 主音频开关 | ✅ 是 | ❌ 否 | ❌ 否 |
| desktop_notifications | 桌面弹窗横幅 | ❌ 否 | ✅ 是 | ❌ 否 |
| mobile_notify.enabled | 手机推送通知 | ❌ 否 | ❌ 否 | ✅ 是 |
这意味着您可以：
- 保留声音但禁用桌面弹窗：peon notifications off
- 保留桌面弹窗但禁用声音：peon pause
- 启用手机推送但不显示桌面弹窗：设置 desktop_notifications: false 和 mobile_notify.enabled: true

Step 4: Update desktop_notifications description in Chinese

Find and enhance the Chinese description of desktop_notifications.

Step 5: Commit

git add README_zh.md
git commit -m "docs: add Chinese translations for Common Use Cases and Independent Controls
Maintains documentation parity between English and Chinese versions."

---

Task 7: Update /peon-ping-toggle skill documentation Copy Chapter

Files:
- Modify: skills/peon-ping-toggle/SKILL.md

Step 1: Read current skill content

cat skills/peon-ping-toggle/SKILL.md

Step 2: Add clarification about what gets toggled

Update the description or add a note section:

What This Toggles  Copy Chapter
This command toggles the master audio switch (enabled config). When disabled:
- ❌ Sounds stop playing
- ❌ Desktop notifications also stop (they require sounds to be enabled)
- ❌ Mobile notifications also stop
For notification-only control, use /peon-ping-config to set desktop_notifications: false. This keeps sounds playing while suppressing desktop popups.
Examples  Copy Chapter
"Mute peon-ping completely" → Sets enabled: false
"Just disable the popups but keep sounds" → Sets desktop_notifications: false (use /peon-ping-config instead)

Step 3: Commit

git add skills/peon-ping-toggle/SKILL.md
git commit -m "docs: clarify peon-ping-toggle behavior
Explains that toggle affects master switch, and directs users
to peon-ping-config for notification-only control."

---

Task 8: Update /peon-ping-config skill documentation Copy Chapter

Files:
- Modify: skills/peon-ping-config/SKILL.md

Step 1: Read current skill content

cat skills/peon-ping-config/SKILL.md

Step 2: Add example for notification control

Add to the examples section (or create one if it doesn't exist):

Common Configuration Examples  Copy Chapter
Disable desktop notification popups but keep sounds  Copy Section
User request: "Disable desktop notifications"
Action:
Set desktop_notifications: false in config
Result:
- ✅ Sounds continue playing (voice reminders)
- ❌ Desktop notification popups suppressed
- ✅ Mobile notifications unaffected (separate toggle)
Alternative CLI command:

or

Adjust volume  Copy Section
User request: "Set volume to 30%"
Action:
Set volume: 0.3 in config
Enable round-robin pack rotation  Copy Section
User request: "Enable round-robin pack rotation with peon and glados"
Action:
Set:

Step 3: Commit

git add skills/peon-ping-config/SKILL.md
git commit -m "docs: add notification control examples to peon-ping-config skill
Shows how to disable desktop popups while keeping sounds, and
clarifies the independent toggle system."

---

Task 9: Update docs/public/llms.txt Copy Chapter

Files:
- Modify: docs/public/llms.txt

Step 1: Read current llms.txt structure

head -50 docs/public/llms.txt

Step 2: Add Common Use Cases section

Find an appropriate location (likely near configuration or features) and add:

Common Use Cases  Copy Chapter
Sounds without popups:
- User wants voice feedback but no visual distractions
- Solution: peon notifications off
- Result: Sounds play, desktop popups suppressed, mobile notifications continue
- Config: desktop_notifications: false
Silent mode with notifications only:
- User wants visual alerts but no audio
- Solution: peon pause (or enabled: false in config)
- Result: Desktop popups show, no sounds play
Independent Controls:
- enabled: master audio switch (affects sounds only)
- desktop_notifications: desktop popup banners (affects popups only)
- mobile_notify.enabled: phone push notifications (affects mobile only)

Step 3: Commit

git add docs/public/llms.txt
git commit -m "docs: add notification control patterns to llms.txt
Helps AI assistants recommend correct solution for sounds-without-popups
use case."

---

Task 10: Manual verification testing Copy Chapter

Files:
- None (testing only)

Step 1: Test desktop_notifications=false behavior

Setup

peon notifications off
Verify config

grep desktop_notifications ~/.claude/hooks/peon-ping/config.json
Expected: "desktop_notifications": false
Trigger a hook event (Stop event)

echo '{"event":"Stop","sessionId":"test-$(date +%s)"}' | ~/.claude/hooks/peon-ping/peon.sh
Manual verification:

✅ Did you hear a sound?

❌ Did you see a desktop notification popup?

Step 2: Test CLI commands

Test status

peon status
Expected: Shows enabled, volume, pack
peon status --verbose
Expected: Above + "desktop notifications off (sounds still play)"
Test notifications command

peon notifications on
peon status --verbose
Expected: "desktop notifications on"
peon notifications off
peon status --verbose
Expected: "desktop notifications off (sounds still play)"
Test popups alias

peon popups on
peon status --verbose
Expected: "desktop notifications on"
peon popups off
peon status --verbose
Expected: "desktop notifications off (sounds still play)"

Step 3: Test help output

peon help | grep -A1 "notifications"
Expected: See "(sounds continue playing)" in help text
peon help | grep "popups"
Expected: See popups alias listed

Step 4: Verify documentation

Check README has new sections

grep "## Common Use Cases" README.md
grep "### Independent Controls" README.md
Check Chinese README

grep "## 常见用例" README_zh.md
grep "### 独立控制" README_zh.md
Check skills

grep "notification-only control" skills/peon-ping-toggle/SKILL.md
grep "desktop_notifications: false" skills/peon-ping-config/SKILL.md

Step 5: Document test results

Create a test report comment or note:

Manual testing completed:
✅ desktop_notifications=false keeps sounds, suppresses popups
✅ peon status --verbose shows notification state
✅ peon notifications on/off works correctly
✅ peon popups on/off alias works correctly
✅ Help text shows clarifying text
✅ README sections added (EN and ZH)
✅ Skills updated with examples
✅ llms.txt updated

---

Task 11: Final commit and summary Copy Chapter

Files:
- None (wrap-up)

Step 1: Review all commits

git log --oneline -11
Expected: See all 10 commits from this plan

Step 2: Verify working tree is clean

git status
Expected: "nothing to commit, working tree clean"

Step 3: Create summary of changes

Document what was changed:

Summary  Copy Chapter
Enhanced discoverability of desktop_notifications feature:
CLI Enhancements:
- Added peon status --verbose flag
- Improved notifications command help text
- Added peon popups alias
Documentation:
- Added Common Use Cases section to README (EN + ZH)
- Added Independent Controls table to README (EN + ZH)
- Updated skill documentation (toggle + config)
- Updated llms.txt with use case patterns
Testing:
- Manual verification confirms feature works correctly
- Sounds play independently from desktop notifications
- CLI provides clear feedback
No code changes to core functionality - feature already worked correctly.

Step 4: Optional: Update CHANGELOG.md

If this warrants a version bump, add to CHANGELOG.md:

[Unreleased]  Copy Chapter
Added  Copy Section

- peon status --verbose flag showing desktop and mobile notification states
- peon popups alias for peon notifications command
- Common Use Cases section in README (sounds without popups, etc.)
- Independent Controls table clarifying the three toggle system
Changed  Copy Section

- Improved help text for notifications command to clarify sounds continue
- Enhanced skill documentation with notification control examples

Step 5: Done

Implementation complete! All documentation and CLI improvements are in place.

---