verbalcoding 0.2.12 → 0.2.13

package/docs/superpowers/plans/2026-05-21-audio-overview-narrated-diffs.md

@@ -0,0 +1,95 @@
+# Audio Overview — Two-Voice Narrated Diffs Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: superpowers:subagent-driven-development or superpowers:executing-plans.
+
+**Goal:** Replace the "diff too long to read aloud" dead-end (`app-node/main.mjs:1033-1037`) with a NotebookLM-style two-voice audio overview: a 30–60 s scripted Host A / Host B dialogue summarizing long agent outputs (diffs, test logs, listings) instead of skipping them.
+
+**Architecture:** New `audio_overview.mjs` sits between `spokenResultOnly` (`app-node/main.mjs:1031`) and the streaming TTS queue. On trigger it (a) asks the active cheap-LLM adapter to script `[A]/[B]` dialogue, (b) feeds the script to the sentencer (`app-node/stream_sentencer.mjs:18`) which now also splits on speaker markers, (c) the queue (`app-node/streaming_tts_queue.mjs:1`) calls `synth(text, { voice })` with `AUDIO_OVERVIEW_VOICE_A` / `_B`. Any failure falls back to the existing notice.
+
+**Tech Stack:** Node 20 ESM, active adapter (`adapterForBackend` at `app-node/main.mjs:730`) for scripting, Edge TTS multi-voice (`createEdgeTtsBackend` at `app-node/tts_backends.mjs:206`) — `voiceProvider` becomes per-call.
+
+---
+
+## Spec
+
+### API
+
+```javascript
+const overview = createAudioOverview({
+  thresholdChars: Number(env.AUDIO_OVERVIEW_THRESHOLD || 1500),
+  voiceA: env.AUDIO_OVERVIEW_VOICE_A || 'en-US-GuyNeural',
+  voiceB: env.AUDIO_OVERVIEW_VOICE_B || 'en-US-JennyNeural',
+  scriptModel: () => adapterForBackend(routingStateFor(key).activeRouting?.backend),
+  language: settings.voiceLanguage,
+  timeoutMs: 4000,
+});
+const result = await overview.maybeScript({ userPrompt, answer });
+// result: { kind: 'overview', segments: [{ voice, text }, ...] } | { kind: 'skip' }
+```
+
+### Behavior
+
+- **Trigger** (`shouldNarrate`): `answer.length > thresholdChars` OR `isPatchLikeOutput(answer)` already at `app-node/main.mjs:1033`. Re-export helper.
+- **Script prompt** (fixed system): _"Script a 30–60 s podcast summary of this coding agent answer. Output 4–6 turns alternating `[A]` (asks) / `[B]` (explains). No markdown, no fences, no paths unless essential. Language: {language}."_ User = first 2 KB of `stripMarkdownNoise(answer)`.
+- **Cache** identical answers 10 min (Map keyed by sha1). **Timeout** 4 s. **Disabled** when `AUDIO_OVERVIEW=0` or toggled off in routing state.
+
+### Integration
+
+- `stream_sentencer.mjs`: add `speakerMarkers: ['[A]', '[B]']` option to `createSentencer` (`app-node/stream_sentencer.mjs:18`). When set, `ingest()` splits on each marker; `'sentence'` event payload becomes `{ text, voice }`.
+- `streaming_tts_queue.mjs:40`: `enqueue(text, opts)` stores `{ text, voice }` in the queue (`app-node/streaming_tts_queue.mjs:5`); pump (`app-node/streaming_tts_queue.mjs:11`) passes `voice` to `synth(text, { voice })`.
+- `tts_backends.mjs`: `synthesize(text, { signal, voice })` in `createEdgeTtsBackend` (`app-node/tts_backends.mjs:225`) overrides `currentVoice()` when `voice` is set. Other backends keep default voice (logged once).
+- `main.mjs`: in `spokenResultOnly` (`app-node/main.mjs:1031-1051`), before the "diff too long" return, call `overview.maybeScript()`; on `'overview'` push `segments` through the streaming path; `synth` closure (`app-node/main.mjs:1320`) upgraded to `synth(text, { voice })`.
+- **User control**: at the `voiceCommandFromTranscript` callsite (`app-node/main.mjs:984`) parse `"audio overview off|on"` / `"오디오 오버뷰 꺼|켜"` and toggle `routingStateFor(key).audioOverviewEnabled` (default `true`).
+
+---
+
+## File Structure
+
+- Create: `app-node/audio_overview.mjs`, `app-node/audio_overview.test.mjs`.
+- Modify: `app-node/stream_sentencer.mjs` — speaker-marker split.
+- Modify: `app-node/streaming_tts_queue.mjs` — per-chunk voice passthrough.
+- Modify: `app-node/tts_backends.mjs` — `voice` override in `createEdgeTtsBackend`.
+- Modify: `app-node/main.mjs` — wire trigger, voice command, routing flag.
+- Modify: `.env.example` — `AUDIO_OVERVIEW`, `AUDIO_OVERVIEW_THRESHOLD`, `AUDIO_OVERVIEW_VOICE_A`, `AUDIO_OVERVIEW_VOICE_B`.
+
+---
+
+## Tasks
+
+### Task 1: TDD — trigger + parser
+
+- [ ] Step 1: `audio_overview.test.mjs`: short answer → `{ kind: 'skip' }`; long answer or `isPatchLikeOutput` short diff → `maybeScript` invoked.
+- [ ] Step 2: Mock adapter returns `"[A] What changed?\n[B] Two files in router."`; expect `segments[0].voice === voiceA`. Malformed output (no `[A]/[B]`) → `{ kind: 'skip' }`.
+
+### Task 2: Implement `audio_overview.mjs`
+
+- [ ] Step 1: `createAudioOverview({...})` returning `{ maybeScript }`. Cache `Map<sha1, segments>` 10 min TTL.
+- [ ] Step 2: Script call via injected `scriptModel()` (`.ask(system, user, { signal, timeoutMs })`); strip fences + markdown per segment.
+- [ ] Step 3: Run, expect PASS, commit.
+
+### Task 3: Extend `stream_sentencer.mjs`
+
+- [ ] Step 1: Add `speakerMarkers` to `createSentencer` (`app-node/stream_sentencer.mjs:18`). Emit `{ text, voice }`; keep back-compat with `{ text, voice: null }` when option absent.
+- [ ] Step 2: Update listener at `app-node/main.mjs:1333` for the object form.
+- [ ] Step 3: Add `stream_sentencer.test.mjs` covering marker split + fence preservation.
+
+### Task 4: Extend `streaming_tts_queue.mjs`
+
+- [ ] Step 1: `enqueue(text, { voice } = {})`; queue stores objects; pump calls `synth(text, { voice })`.
+- [ ] Step 2: Test: two enqueues with distinct voices both reach mock synth with matching arg.
+
+### Task 5: Extend `createEdgeTtsBackend`
+
+- [ ] Step 1: `synthesize` at `app-node/tts_backends.mjs:225` accepts `voice` and substitutes into `-v` argv.
+- [ ] Step 2: Non-edge backends log "audio overview voice swap unsupported on {backend}" once.
+
+### Task 6: Wire into `main.mjs`
+
+- [ ] Step 1: Instantiate `audioOverview` after `createTtsBackend` (`app-node/main.mjs:253`).
+- [ ] Step 2: In `spokenResultOnly` (`app-node/main.mjs:1031`), when trigger fires and `routingStateFor(key).audioOverviewEnabled !== false`, `await overview.maybeScript(...)`; on `'overview'` enqueue segments; on `'skip'` keep existing notice.
+- [ ] Step 3: Parse `"audio overview on|off"` / Korean in the `handleTtsVoiceCommand` chain (`app-node/main.mjs:983`). Routing state only — no env write.
+
+### Task 7: Document
+
+- [ ] Step 1: `.env.example` adds four keys after `STREAMING_TTS` (line 26).
+- [ ] Step 2: Note the two-voice fallback rule in `docs/superpowers/` README. Commit.

package/docs/superpowers/plans/2026-05-21-autoresearch-ontology.md

@@ -0,0 +1,83 @@
+# Voice Autoresearch + Session Ontology — Implementation Plan
+
+**Status: in flight, 2026-05-21.** This is a 1-hour innovation push driven by 6 parallel research agents that surveyed 2026 autoresearch frameworks, LLM-driven ontology construction, agent memory systems, voice-first UX, agent design patterns, and the VerbalCoding code surface.
+
+## Why now
+
+VerbalCoding's cross-agent voice routing landed but the handoff still passes a flat string ("last 4 utterances + last plan decisions") to the routed backend. That string drops surrounding context — *which file was touched 6 turns ago that still matters*, *which tool was used*, *which decisions are now superseded*. Every 2026 production agent-memory system (Graphiti/Zep, Mem0g, Anthropic Memory tool, Letta MemFS, ACE) converged on **typed graph or filesystem persistence with append-only semantics + idempotent dedup**. We can carry the smallest viable shape of that across CLI invocations.
+
+Simultaneously, the autoresearch wave (STORM, OpenScholar, GPT-Researcher, Anthropic multi-agent research) shows a stable architecture: **plan → parallel fan-out → outline-as-compression → cited synthesis**. VerbalCoding has every piece needed (plan-mode, streaming TTS, sentencer, per-channel state) — we just don't have the voice command or the orchestrator.
+
+Both extensions share infrastructure: the session ontology is where autoresearch results land and where handoff context comes from.
+
+## Module 1 — `app-node/session_ontology.mjs`
+
+A per-channel typed graph. Fixed schema (no induction tax). Append-only with `superseded_by`. Serializable to <2KB JSON. Persists to `~/.verbalcoding/memory/<channelId>.json`.
+
+**Node types (single char `t`):** `D` Decision, `F` File, `T` Tool, `C` Concept, `A` Agent, `R` Result.
+
+**Edge predicates (single char `p`):** `d` decided, `t` touched, `u` used, `p` produced, `r` referenced, `s` superseded_by.
+
+**Shape:**
+```js
+{
+  v: 1,                                    // schema version
+  channelKey: 'voice/123',
+  nodes: [{ id: 'n1', t: 'D', n: 'oauth_provider=github', ts: 1716100000, by: 'claude' }],
+  edges: [{ s: 'n1', p: 't', o: 'n2', ts: 1716100000 }],
+  meta: { updatedAt: 1716100000, nodeCount: 1, edgeCount: 1 },
+}
+```
+
+**Public API:**
+- `createSessionOntology({ rootDir, channelKey, maxNodes = 40, maxEdges = 80 })` → store handle
+- `store.add({ nodes, edges, supersedes })` — idempotent on `(t, lowercase(n))`
+- `store.serializeForHandoff({ language = 'en', maxBytes = 1500 })` → compact markdown block ready for the cross-agent prompt
+- `store.entitiesFromText(text, opts)` — convenience extractor (regex-only, no LLM, see below)
+- `store.save() / store.load()`
+
+**Why regex-only extraction (for v1):** the research summary said the EDC-style LLM extraction is the dominant 2025 pattern, but it costs an LLM call per turn on the voice critical path. v1 uses lightweight regex extraction so it never blocks a turn. The extraction is upgradeable later (slot in an LLM-backed extractor behind the same `entitiesFromText` signature).
+
+**Eviction:** LRU on non-`Decision` nodes when over `maxNodes`. `Decision` nodes are sticky.
+
+**Conflict resolution:** new fact does not delete old fact; it adds a `superseded_by` edge. `serializeForHandoff` skips superseded nodes by default. Graphiti-pattern, simplified.
+
+## Module 2 — `app-node/research_mode.mjs`
+
+Voice command parser + pipeline. Maps STORM's outline-as-compression and GPT-Researcher's plan→executors pattern, but compressed to fit a voice turn.
+
+**Public API:**
+- `parseResearchCommand(text, language)` — returns `{type:'research', query, depth, sticky?} | {type:'none'}`. English `"research X"`, `"look up X"`, `"deep research X"`; Korean `"X 리서치", "X 조사해"`.
+- `runResearchTurn({ query, depth, fetchImpl, llmAdapter, signal, language })` — async generator yielding `{phase, payload}` events: `'plan'`, `'fetch'`, `'summarize'`, `'narration'`, `'done'`. The main dispatcher routes `narration` chunks to the existing sentencer / streaming TTS queue.
+
+**Backends:** primary search via Tavily (`TAVILY_API_KEY`), fallback Brave (`BRAVE_SEARCH_API_KEY`), then a "search backend not configured" voice notice. Synthesis via the active agent adapter (whichever CLI is current) so we don't add a separate API key requirement.
+
+**Output shape:** spoken = 3-bullet outline narrated as one sentence each; text-channel = full markdown with sources and a one-line summary at the top (Perplexity-Voice-style citation-defer).
+
+**Ontology integration:** after `done`, write `Concept` nodes for the query and main topics, `Result` nodes for each summary bullet, with `referenced` edges to URLs (stored as `File` nodes with a `t:'F'` and `n` set to the URL hash).
+
+## Module 3 — wire into `main.mjs`
+
+1. Import both new modules near the existing `agent_routing` import block.
+2. In the per-turn dispatcher (~`main.mjs:1844`, before `parseAgentRoutingCommand`), insert `parseResearchCommand`. If it returns `{type:'research', …}`, run the research turn and short-circuit the rest.
+3. Add `ontologyStateFor(channelKey)` next to `routingStateFor`. Lazy-create, persist on every mutation.
+4. Replace the cross-agent prompt's `priorUtterances` + `resolvedDecisions` inputs with `ontology.serializeForHandoff()` when the ontology is non-empty. Fall back to the existing flat string otherwise.
+5. After every successful agent turn, call `ontology.entitiesFromText(prompt + answer, { by: backend })` non-blocking.
+
+## Tests
+
+- `app-node/session_ontology.test.mjs` — add, supersede, dedup, eviction, serializeForHandoff shape, save/load round-trip.
+- `app-node/research_mode.test.mjs` — parser EN/KO, runResearchTurn pipeline with mocked fetch + llm.
+- Extend `cross_agent_routing.test.mjs` — ontology projection replaces flat string when present.
+
+## Out of scope (this push)
+
+- LLM-driven entity extraction (regex v1; upgradeable later).
+- Streaming TTS prefix for "Research finding: " (TODO `bet-2.1` — wire via the existing prefix mechanism).
+- Citation-defer Discord embed formatting (TODO `bet-2.2`).
+- Per-agent voice ID + pre-warm (separate workstream).
+- The voice-coding benchmark suggestion from the agent-pattern survey (this is a positioning play, separate from code).
+
+## Commit boundary
+
+One commit per module + one for the wiring + one for the docs. Land green or revert.

package/docs/superpowers/plans/2026-05-21-phase11-push-to-talk-wakeword-v2.md

@@ -0,0 +1,77 @@
+# Phase 11 — Push-to-Talk + Wake-Word v2 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Eliminate wake misses and unwanted barge-ins by (a) adding an opt-in **push-to-talk gate** that suppresses whisper-cli unless the user opens a turn, and (b) replacing regex-on-transcript wake detection with a **continuous neural wake-word detector** tapped off the PCM stream — both behind feature flags in one increment.
+
+**Motivation:** `subscribeUser()` records every Discord speaking-start to WAV (`main.mjs:2089-2141`), runs whisper-cli, then post-filters via `acceptsWake()` (`main.mjs:1582-1585`, `:1792`). This wastes 300-900 ms per false trigger and leaks nearby-conversation transcripts. Hardware PTT keys aren't visible to bots, so we need a software gate. Wake-word v2 reacts in <200 ms on a user-trained phrase without relying on whisper accuracy.
+
+**Architecture:**
+
+1. **PTT gate (`app-node/ptt_gate.mjs`, new).** Pure module: `createPttGate({ mode })` with `isOpen(userId)`, `open(userId, { ttlMs })`, `close(userId)`. `subscribeUser()` consults it before WAV-writer allocation (`main.mjs:2100`); when closed, the opus stream is drained and whisper skipped. **Decision: slash-command pair `/ptt start|stop|status`**, registered via `client.application.commands` on `ready`. Justification:
+   - Discord's built-in *Push to Talk* setting only affects the human's outbound audio — bots receive packets either way, so it's invisible server-side.
+   - A WebRTC companion needs a sidecar per user, OS keybinding daemons, signalling channel; high install cost.
+   - Slash commands work on desktop + mobile, zero install, per-guild ACL'd. Default `ttlMs=20000` auto-closes on forgotten stop.
+   - **Future work (out of scope):** WebRTC companion using `node-global-key-listener` + localhost WS toggling the same gate for true hold-to-talk.
+
+2. **Wake-Word v2 (`app-node/wake_detector.mjs`, new).** Streaming detector wrapping **openWakeWord** (Apache-2.0, `onnxruntime-node`, ~30 ms hop, CPU-only). Picovoice rejected (per-user license, closed weights); Kyutai rejected (no shipped wake model). Consumes a tee of the 16 kHz mono PCM from the `prism.opus.Decoder` chain in `subscribeUser()` (`main.mjs:2109-2141`) — insert a `PassThrough` between `decoder` and `writer`, fork a downsampler into the detector. On score >`WAKE_WORD_THRESHOLD` (default 0.55) it calls `pttGate.open(userId, { ttlMs: WAKE_WORD_TURN_MS })`. Custom phrases via openWakeWord's `train_custom_verifier`; models in `models/wake/`.
+
+3. **State plumbing (`app-node/bridge_state.mjs`).** Extend `createBridgeState()` (`bridge_state.mjs:1`) with `setGateMode/getGateMode` so `/ptt`, voice commands ("PTT 켜"/"push to talk on" per `voice_messages.mjs`), and wake hits share one source of truth. `barge_in.mjs` unchanged; gate runs **before** `createLiveBargeInMonitor()` (`main.mjs:2115`), so explicit barge-in still works while gated.
+
+**Tech Stack:** Node 20 ESM, `onnxruntime-node`, `discord.js` slash commands, `node --test`. Models: openWakeWord baseline + user-trained `hermes_v1.onnx`.
+
+## Tasks
+
+### Task 1: Failing tests for `ptt_gate`
+
+**Files:** Create `app-node/ptt_gate.test.mjs`. Cover: default closed in `mode='ptt'`; always open in `mode='off'` (legacy); `open()` expires after `ttlMs`; `close()` is idempotent; per-user isolation.
+
+### Task 2: Implement `ptt_gate.mjs`
+
+Pure module, no Discord deps. Inject `now`/`setTimeout` for testability. Export `createPttGate({ mode, defaultTtlMs, log })`.
+
+### Task 3: Register `/ptt` + wire gate into `subscribeUser`
+
+**Files:** `app-node/main.mjs`. On `ClientReady`, register guild command `ptt` (`start|stop|status`). Add `interactionCreate` handler. In `subscribeUser()` insert gate check after the allow-check at `main.mjs:2090` — if closed, drain `receiver.subscribe(...)` and return before line 2109. Short-circuit the whisper post-filter at `main.mjs:1792` to skip `acceptsWake` when the detector confirmed the turn (carry a `viaWakeDetector` flag on the pending utterance).
+
+### Task 4: Failing tests for `wake_detector`
+
+**Files:** `app-node/wake_detector.test.mjs`. Inject a fake ORT session; feed canned PCM frames; assert callback fires once per detection with cooldown.
+
+### Task 5: Implement `wake_detector.mjs`
+
+Streaming class with 1280-sample (80 ms) frame buffer, 480 ms ring, cooldown 1500 ms, score smoothing over 3 frames. Lazy-load the ONNX model from `WAKE_WORD_MODEL` (default `models/wake/hermes_v1.onnx`). Fallback to legacy `acceptsWake` when model load fails — log once, never crash bridge.
+
+### Task 6: Tap PCM stream + integrate detector
+
+**Files:** `app-node/main.mjs:2109-2141`. Replace `opusStream.pipe(decoder).pipe(writer)` with a fork: decoder → PassThrough → [writer, downsampler16k → detector.feed()]. Detector callback flips the gate open and stamps `pending.viaWakeDetector = true` via `bridgeState.setPending` (`bridge_state.mjs:28`).
+
+### Task 7: Settings + voice commands
+
+**Files:** `.env.example`, `main.mjs:205-220`, `voice_messages.mjs`. Add `PTT_MODE=off|ptt|wake|wake+ptt` (default `off`), `WAKE_WORD_MODEL`, `WAKE_WORD_THRESHOLD`, `WAKE_WORD_TURN_MS`. Recognize "PTT 켜/꺼", "wake word on/off" per `docs/HARNESSES.md` shared-semantics.
+
+### Task 8: Docs
+
+Update `docs/HARNESSES.md` shared-semantics with PTT + wake-v2 entries. Add `docs/PTT_AND_WAKEWORD.md` covering custom-verifier training and latency budget (detection→gate-open <200 ms).
+
+## Verification
+
+- `node --test app-node/ptt_gate.test.mjs app-node/wake_detector.test.mjs` → PASS.
+- Full `node --test` suite → no regressions in `barge_in.test.mjs`, `bridge_state.test.mjs`.
+- Manual `PTT_MODE=ptt`: speaking without `/ptt start` → zero whisper invocations (no `pcmBytes` log at `main.mjs:2133`).
+- Manual `PTT_MODE=wake`: trained phrase opens gate <200 ms (new `wakeDetectMs` field in `latency_metrics.mjs`).
+- Manual: barge-in during TTS still aborts (`main.mjs:2115` path unaffected).
+
+## Out of scope
+
+- WebRTC/keyboard PTT companion (future task; gate is companion-ready).
+- Multi-wake-word arbitration per user.
+- Server-side VAD replacement (`SUBSCRIBE_AFTER_SILENCE_MS` stays).
+- Whisper streaming partials.
+
+## Self-Review
+
+- Gate + detector share one bridge_state field → no split-brain.
+- Default `PTT_MODE=off` keeps current behavior; opt-in only.
+- ONNX load failure degrades to today's regex path, never crashes.
+- All new modules are pure + injected deps → unit-testable without Discord.

package/docs/superpowers/plans/2026-05-21-phase12-multi-user-voice.md

@@ -0,0 +1,147 @@
+# Phase 12 — Per-Speaker Multi-User Voice State Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Scope routing, plan-mode, recent-utterance buffer, and ontology projection to `(channelId, userId)` so two humans in one Discord voice channel get independent agent state, while keeping a shared channel-level ontology layer and serializing agent invocations (TTS audio remains a single broadcast stream).
+
+**Architecture:** Extend the channel-key helpers in `app-node/main.mjs` with a `For(userId)` variant; rekey `routingStateByChannel`, `planStates`, and `ontologyByChannel` to `<channelId>:<userId>` with channel-only fallback for unattributed paths and default-agent reads. Add a per-channel agent-invocation queue (FIFO with brief inter-speaker narration) layered on top of the existing `bridgeState` deferred queue. Ontology becomes a two-tier read: per-speaker overlay merged onto a channel-shared base. Audio output stays unicast-to-channel — only **state** is per-user.
+
+**Tech Stack:** Node 20 ESM, existing `bridgeState` (`createBridgeState`), `createSessionOntology`, `node --test`.
+
+---
+
+## Spec
+
+### Key shape
+
+- New helper `speakerKey(channelId, userId)` → `"<channelId>:<userId>"`. Channel-only key (`"<channelId>"`) remains valid as the fallback / shared layer.
+- `planChannelKeyFor(userId)` companion to `planChannelKey()` at `app-node/main.mjs:399`. `planChannelKey()` retained for non-turn paths (default-agent reads, channel-wide resets, push notifications, voice-clone capture).
+- `routingStateFor(key)` (`main.mjs:639`) accepts either key shape; on miss for `"chan:user"` it **copies** from `"chan"` once (so first-time user inherits channel default), then diverges.
+
+### Plan mode
+
+- `planStates` (`main.mjs:397`) rekeyed to `speakerKey`. `dispatchPlanModeUtterance(prompt, signal)` (`main.mjs:422`) takes a `userId` arg and uses `planChannelKeyFor(userId)`. Concurrent plan sessions per user are independent; `"cancel"` / `"approve"` only affect the speaker's plan.
+
+### Ontology projection
+
+- `ontologyByChannel` (`main.mjs:663`) becomes two stores per channel: `baseOntology(channelKey)` (shared) + `speakerOntology(channelKey, userId)` (overlay).
+- New `ontologyProjectionFor(channelKey, userId)` returns a read-through view: search/serialize merges base first, overlay second (overlay supersedes on slot collision).
+- `captureOntologyFromTurn` (`main.mjs:675`) writes to overlay; a low-frequency promoter (every N turns or on `!session save`) lifts overlay nodes whose `by` set spans ≥2 users into base. Promotion is pure; unit-testable.
+- Persisted file layout: `.verbalcoding/ontology/<channel>.json` (base) and `.verbalcoding/ontology/<channel>/<user>.json` (overlay). `createSessionOntology` already takes `channelKey`; reuse with a composite key for overlay.
+
+### Turn taking
+
+- New module `app-node/turn_queue.mjs`: per-channel FIFO of `{ userId, runFn, enqueuedAt }`. Drains serially; emits `onWaiting(userId, aheadOf)` when a second speaker arrives mid-run.
+- `handleRecording(userId, ...)` (`main.mjs:1756`) submits work via the queue rather than calling the adapter directly. Existing `bridgeState.enqueueDeferred` path (`main.mjs:1647`) remains for per-user segment accumulation; the queue layers above it.
+- When `onWaiting` fires and channel has ≥2 distinct waiting users, speak one short notice: e.g. `"User B, queued after User A."` Throttled to once per consecutive wait.
+- `clearTransientRouting(planChannelKey())` (`main.mjs:2064`) is rewritten to `clearTransientRouting(planChannelKeyFor(userId))` so a barge-in by User A does not nuke User B's sticky route.
+
+### Audio (explicit non-goal)
+
+- TTS remains a single shared stream per `VoiceConnection`. No per-user audio routing. Document this in `docs/USAGE.md` so users know responses are heard by everyone.
+
+---
+
+## File Structure
+
+- Create: `app-node/turn_queue.mjs` — per-channel serial FIFO with `enqueue`, `length`, `onWaiting`.
+- Create: `app-node/turn_queue.test.mjs` — serializes overlapping submissions; emits waiting notice once.
+- Create: `app-node/speaker_key.mjs` — `speakerKey`, `planChannelKeyFor`, `splitSpeakerKey`.
+- Create: `app-node/speaker_key.test.mjs`.
+- Create: `app-node/ontology_projection.mjs` — `ontologyProjectionFor`, `promoteCrossUserNodes`.
+- Create: `app-node/ontology_projection.test.mjs` — overlay supersedes base; promotion threshold; isolation between users.
+- Modify: `app-node/main.mjs` — rekey `routingStateByChannel` (`:640`), `planStates` (`:397`), `ontologyByChannel` (`:663`); add `planChannelKeyFor`; thread `userId` through `dispatchPlanModeUtterance` (`:422`), `captureOntologyFromTurn` (`:675`), `clearTransientRouting` (`:2064`), and the final-block cleanup in `handleRecording` (`:1756`). Wire `turn_queue` around the adapter call inside `handleRecording`.
+- Modify: `app-node/session_ontology.mjs` — accept composite `channelKey` (`/Users/neo/Developer/Projects/VerbalCoding/app-node/session_ontology.mjs:35`) without sanitizing `:` out of the path; verify `safeChannelKey` allows the separator.
+- Modify: `app-node/plan_mode.test.mjs` — add two-user concurrent plan-mode case.
+- Modify: `docs/USAGE.md` — add "Multi-user voice channels" section; note shared audio, per-user state.
+- Modify: `docs/CONFIGURATION.md` — document `MULTI_USER_TURN_NOTICE=on|off`, `MULTI_USER_TURN_NOTICE_THROTTLE_MS` (default 8000).
+
+---
+
+## Tasks
+
+### Task 1: Failing test for `speakerKey` + `planChannelKeyFor`
+
+**Files:** Create `app-node/speaker_key.test.mjs`.
+
+- [ ] Step 1: Write failing test.
+
+```javascript
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { speakerKey, planChannelKeyFor, splitSpeakerKey } from './speaker_key.mjs';
+
+test('speakerKey composes channel and user', () => {
+  assert.equal(speakerKey('chan1', 'user9'), 'chan1:user9');
+});
+test('planChannelKeyFor falls back when channel missing', () => {
+  assert.equal(planChannelKeyFor(null, 'u1'), 'default:u1');
+});
+test('splitSpeakerKey round-trips and tolerates channel-only', () => {
+  assert.deepEqual(splitSpeakerKey('chan1:user9'), { channelId: 'chan1', userId: 'user9' });
+  assert.deepEqual(splitSpeakerKey('chan1'), { channelId: 'chan1', userId: null });
+});
+```
+
+- [ ] Step 2: `node --test app-node/speaker_key.test.mjs` → FAIL (module missing).
+
+### Task 2: Implement `speaker_key.mjs` + green test
+
+- [ ] Step 1: Implement; `planChannelKeyFor(channelId, userId)` mirrors `planChannelKey()` (`main.mjs:399`) plus `:userId` suffix.
+- [ ] Step 2: Run test → PASS.
+- [ ] Step 3: Commit: `feat(multi-user): per-(channel,user) key helpers`.
+
+### Task 3: Failing test for `turn_queue`
+
+- [ ] Step 1: Test (a) serializes two overlapping `enqueue` calls (second runFn starts only after first resolves); (b) `onWaiting` fires exactly once per distinct waiting userId across consecutive waits within throttle window.
+- [ ] Step 2: Run → FAIL.
+
+### Task 4: Implement `turn_queue.mjs` + green test
+
+- [ ] Step 1: FIFO per `channelId`. `enqueue({channelId, userId, runFn})` returns a Promise resolving to runFn's result. Internal state: `Map<channelId, { running, queue, lastNoticeAt, lastNoticeUserId }>`.
+- [ ] Step 2: Run → PASS. Commit: `feat(multi-user): per-channel serial turn queue with waiting notice`.
+
+### Task 5: Failing test for ontology projection
+
+- [ ] Step 1: Two users in same channel write distinct nodes; `ontologyProjectionFor(chan, userA).serialize()` contains A's nodes + shared base, not B's. `promoteCrossUserNodes(...)` lifts nodes whose `by` covers ≥2 distinct users.
+- [ ] Step 2: Run → FAIL.
+
+### Task 6: Implement `ontology_projection.mjs` + green test
+
+- [ ] Step 1: Wrap two `createSessionOntology` instances (base + overlay). Implement merged read; promotion checks node-level `by` set.
+- [ ] Step 2: Run → PASS. Commit: `feat(multi-user): two-tier ontology projection (shared base + per-user overlay)`.
+
+### Task 7: Rekey state maps in `main.mjs`
+
+**Files:** `app-node/main.mjs`.
+
+- [ ] Step 1: Import `speakerKey`, `planChannelKeyFor` from `./speaker_key.mjs`.
+- [ ] Step 2: Update `routingStateFor` (`:639`) — first-time `chan:user` lookup clones from `chan` if present (inheritance), then stored independently. Keep channel-only `routingStateFor(chan)` working for status commands.
+- [ ] Step 3: Thread `userId` through `dispatchPlanModeUtterance` (`:422`), `recordUtterance` (`:656`), `captureOntologyFromTurn` (`:675`), `resetRoutingState` (`:686`), `clearTransientRouting` (`:2064`). Call sites in `handleRecording` (`:1756`) and the plan-mode dispatcher pass `userId`.
+- [ ] Step 4: Keep one channel-level call site: the `voiceCloneCapture` flow at `main.mjs:1535` reads channel-level state (no rekey needed). Document with a comment.
+- [ ] Step 5: Run full suite: `node --test app-node`. Expected PASS; any new flake means missing `userId` propagation.
+- [ ] Step 6: Commit: `feat(multi-user): scope routing/plan/ontology to (channel,user)`.
+
+### Task 8: Wire `turn_queue` into `handleRecording`
+
+- [ ] Step 1: Inside `handleRecording` (`main.mjs:1756`), wrap the adapter dispatch in `turnQueue.enqueue({ channelId: activeVoiceChannelId, userId, runFn: () => actualWork() })`.
+- [ ] Step 2: On `onWaiting`, gated by `MULTI_USER_TURN_NOTICE !== 'off'`, call `speakText(noticeFor(userId, language), null, null)`. Notice strings live in a small map; localized for `en`/`ko`.
+- [ ] Step 3: Existing `bridgeState.deferredSize` drain (`main.mjs:2083`) keeps working — it operates per-user upstream of the queue.
+- [ ] Step 4: Add `app-node/multi_user_turn.test.mjs`: two simulated `handleRecording` calls overlap; verify they run sequentially and a single notice TTS is emitted.
+- [ ] Step 5: Run, commit: `feat(multi-user): serialize per-channel agent turns with waiting notice`.
+
+### Task 9: Docs
+
+- [ ] Step 1: `docs/USAGE.md` — add **Multi-user voice channels** section: per-user routing/plan/ontology, **shared TTS audio**, turn-taking notice.
+- [ ] Step 2: `docs/CONFIGURATION.md` — `MULTI_USER_TURN_NOTICE`, `MULTI_USER_TURN_NOTICE_THROTTLE_MS`.
+- [ ] Step 3: Update `docs/HARNESS_*` "Shared semantics" bullet to read "per (channel, user) routing and plan-mode".
+- [ ] Step 4: Commit: `docs(multi-user): document per-speaker state and shared audio`.
+
+---
+
+## Self-Review
+
+- Spec coverage: per-user routing ✓ (`:640`), per-user plan ✓ (`:397`), two-tier ontology ✓ (`:663`), turn queue ✓ (new), shared-audio caveat documented ✓.
+- No placeholders. Composite keys backward-compatible via channel-only fallback in `routingStateFor`.
+- Tests precede code in every task. `node --test app-node` is the only runner; no new deps.
+- Cross-cutting risk: `safeChannelKey` in `session_ontology.mjs:35` must permit `:` — Task 6 explicitly verifies.

package/docs/superpowers/plans/2026-05-21-phase14-verbalbench.md

@@ -0,0 +1,136 @@
+# Phase 14 — VerbalBench: Voice-Coding Agent Benchmark Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Ship "VerbalBench" — the first end-to-end benchmark for voice-mediated coding agents. SWE-bench / Terminal-Bench measure text-only batch tool loops; nothing measures speech-to-first-tool-action latency, barge-in resilience, TTS-while-acting throughput, or cross-agent handoff fidelity. Deliver a 50-task suite, Discord-free harness, JSON leaderboard, CI smoke-bench.
+
+**Architecture:** Node driver synthesizes user audio (Edge-TTS + samples), feeds it through a mock `receiver` matching the `@discordjs/voice` surface in `main.mjs:2089–2161` (`receiver.subscribe → prism.opus.Decoder → wav.FileWriter` at `main.mjs:2107–2118`). Harness boots the bridge in-process with `MOCK_DISCORD=1`, captures timing via `createLatencyTurn` (`main.mjs:314`, `latency_metrics.mjs:29`) plus a new `metricsTurn.mark('first_tool_action')`, writes JSONL.
+
+**Tech Stack:** Node 20 ESM, `node --test`, Edge-TTS, existing `tts_backends.mjs` + `stt_whisper.mjs`, GitHub Actions.
+
+## Spec
+
+### Task taxonomy (10 × 5 = 50)
+
+| Category | Seed |
+|---|---|
+| codegen | "Write a Python flatten-nested-list." |
+| refactor | "Extract auth in `routes/user.js` into middleware." |
+| run-tests | "Run the suite; tell me what fails." |
+| debug-failing-test | "Fix the failing test in `test_parser.py`." |
+| web-research-then-code | "Look up OpenAI Realtime audio schema, patch our client." |
+| switch-backend-mid-task | "Use Codex." → mid-turn: "Switch to Claude." |
+| plan-mode-then-execute | "Plan a refactor of `bridge_state.mjs`, then do it." |
+| barge-in-and-redirect | Mid-TTS: "Stop. Tests first." |
+| push-handoff-and-resume | "Push to my desktop; pick up there." |
+| multi-file-edit | "Rename `whisperBin` to `sttBin` project-wide." |
+
+Five fixtures per category at `bench/tasks/<category>/NN-<slug>.json` with `{ id, prompt_audio_seed, expected_tool_classes, success_predicate, max_wall_ms }`.
+
+### Mock receiver (`bench/mock_discord.mjs`)
+
+Implements only what `main.mjs:2089–2118, 2148–2165` touches:
+
+- `joinVoiceChannel` → returns `{ receiver, on('stateChange'), subscribe(player) }`; emits `VoiceConnectionStatus.Ready` synchronously.
+- `receiver.speaking.on('start', cb)` driven by harness `inject(userId, wavPath)`.
+- `receiver.subscribe(userId, opts)` → `Readable` yielding Opus packets re-encoded from `bench/audio/*.wav`; honors `EndBehaviorType.AfterSilence`.
+- `createAudioPlayer/createAudioResource` → captures PCM into `turn.tts_pcm[]` with first-byte timestamp.
+
+### Metrics (`bench/metrics.mjs`, extends `latency_metrics.mjs`)
+
+- `speech_to_first_tool_action_ms` — `voice_first_packet` (`main.mjs:1665,1694`) → first adapter tool-event (`main.mjs:~1985`, new `metricsTurn.mark('first_tool_action')`).
+- `first_utterance_of_speech_ms` — `voice_first_packet` → first TTS PCM byte from the mock player.
+- `task_completion` — `success_predicate(workdir)` boolean.
+- `barge_in_success_rate` — `barge-in-and-redirect` only: second-utterance onset → `metricsTurn.finish({ status: /barge_in_/ })` (`main.mjs:1726,1737`). Pass ≤ 600 ms.
+- `handoff_fidelity` — `switch-backend-mid-task` only: assert routed `promptForAgent` contains `[Session ontology]` block (`main.mjs:1955–1958`) and that turn-N ontology nodes appear in turn-N+1 prompt.
+
+### Baselines
+
+Run across all eight backends in `buildAgentSettings` defaults (`agent_adapters.mjs:217–276`): hermes, claude, codex, gemini, opencode, openclaw, aider, cursor. Publish backend × category matrix.
+
+### JSON result row (sample)
+
+```json
+{
+  "bench_version": "0.1.0",
+  "run_id": "2026-05-21T14:22:01Z-abc123",
+  "backend": "claude",
+  "task_id": "barge-in-and-redirect/03-stop-run-tests",
+  "speech_to_first_tool_action_ms": 1820,
+  "first_utterance_of_speech_ms": 2410,
+  "barge_in_ms": 420,
+  "task_completion": true,
+  "handoff_fidelity": null,
+  "wall_ms": 18430,
+  "tts_chars": 312,
+  "tool_calls": ["read_file", "terminal"],
+  "harness_sha": "b76257f",
+  "agent_command": "claude -p"
+}
+```
+
+Superset of HF Open Leaderboard rows (`task_id`, `model`→`backend`, numeric metrics) so the same parser ingests both.
+
+### Publishing
+
+- `bench/results/` JSONL pushed by CI to `gh-pages`; static leaderboard in `bench/site/` (Vite + sortable table).
+- `npm run bench:smoke` — 10 tasks (1/category, ≤ 3 min) on every PR via `.github/workflows/verbalbench-smoke.yml`.
+- `npm run bench:full` — 50 × 8 nightly; artifact uploaded, PR-commented if `speech_to_first_tool_action_ms` p95 regresses > 15 % vs. baseline.
+
+## File Structure
+
+- Create: `bench/mock_discord.mjs` — `@discordjs/voice` doubles for `main.mjs:2089–2165`.
+- Create: `bench/driver.mjs`, `bench/metrics.mjs`, `bench/predicates/*.mjs`.
+- Create: `bench/tasks/<10 dirs>/*.json` (50 fixtures), `bench/audio/` (Edge-TTS WAVs, ko+en).
+- Create: `bench/results/baseline-2026-05-21.jsonl`, `bench/site/`.
+- Create: `.github/workflows/verbalbench-{smoke,nightly}.yml`.
+- Modify: `app-node/main.mjs:1985` — `metricsTurn.mark('first_tool_action')` gated by `VERBALBENCH_INSTRUMENT=1`.
+- Modify: `app-node/main.mjs:165` — `MOCK_DISCORD=1` skips real Discord login.
+- Modify: `app-node/agent_adapters.mjs:594` — `ask` accepts optional `plan.onFirstToolEvent`; fired on first parsed tool-call. No-op when absent.
+- Modify: `app-node/latency_metrics.mjs:29` — record `first_tool_action`, `barge_in_ms`.
+- Modify: `package.json` — `bench:smoke`, `bench:full`, `bench:render`.
+- Modify: `README.md` — Benchmarks section.
+- Create: `docs/VERBALBENCH.md` — contributor guide + `npm run bench:adapter -- --adapter ./my-adapter.mjs`.
+
+## Tasks
+
+### Task 1: Failing test for mock receiver
+
+**Files:** Create `bench/mock_discord.test.mjs`.
+
+- [ ] Step 1: Assert `mockReceiver.subscribe(userId, { end: { behavior: EndBehaviorType.AfterSilence, duration: 2200 } })` emits bytes of `bench/audio/fixtures/hello.wav` then `end`s. Run `node --test bench/mock_discord.test.mjs` — expect FAIL.
+
+### Task 2: Implement `bench/mock_discord.mjs`
+
+- [ ] Step 1: Implement Spec surface. Wrap WAV as Opus `Readable` at 48 kHz/2-ch (matches `prism.opus.Decoder` at `main.mjs:2110`).
+- [ ] Step 2: PASS → commit `feat(bench): mock @discordjs/voice receiver`.
+
+### Task 3: Driver + metrics + instrumentation
+
+- [ ] Step 1: `bench/driver.mjs` boots bridge with `MOCK_DISCORD=1`, calls `mockReceiver.inject(...)`, awaits `metricsTurn.finish`, writes JSONL.
+- [ ] Step 2: `bench/metrics.mjs` extensions.
+- [ ] Step 3: Wire `main.mjs:1985` and `agent_adapters.mjs:594` per File Structure. Tests for both. Commit.
+
+### Task 4: First 10 fixtures + smoke CI
+
+- [ ] Step 1: One task per category with Edge-TTS audio + predicate.
+- [ ] Step 2: `npm run bench:smoke` green locally.
+- [ ] Step 3: `.github/workflows/verbalbench-smoke.yml` (hermes on PR; full matrix on `workflow_dispatch`). Commit.
+
+### Task 5: Remaining 40 fixtures + baseline
+
+- [ ] Step 1: Author 4 more per category.
+- [ ] Step 2: Run full matrix on installed backends (`detectInstalledAgents`); commit `bench/results/baseline-2026-05-21.jsonl` + nightly workflow.
+
+### Task 6: Leaderboard site + docs
+
+- [ ] Step 1: `bench/site/` (sortable, per-metric filters, JSON download).
+- [ ] Step 2: `docs/VERBALBENCH.md` + `README.md` update. Commit.
+
+## Self-Review
+
+- Coverage: taxonomy, mock, metrics, baselines, publishing — present.
+- No placeholders; units ms; sample row included.
+- Mock enumerates every `@discordjs/voice` symbol at `main.mjs:2089–2165`.
+- Prod untouched unless `VERBALBENCH_INSTRUMENT=1` or `MOCK_DISCORD=1`.
+- Row is HF Open Leaderboard superset.

package/docs/superpowers/plans/2026-05-21-phase15-phone-companion.md

@@ -0,0 +1,72 @@
+# Phase 15 — Phone Companion PWA Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans.
+
+**Goal:** When a Phase 10 push notification fires while no human is in the bound voice channel, tapping it opens a PWA that (a) replays the agent's `spokenAnswer` audio, (b) lets the user re-engage by voice — speech captured in the PWA is delivered to the bot as if uttered in the bound VC, and (c) shows an optional markdown summary plus progress events.
+
+**Architecture:** A new `app-node/companion_server.mjs` boots an Express HTTP server in the same Node process as `main.mjs`. It serves a static PWA from `app-node/companion_pwa/` (manifest, service worker, single-page UI). Each push notification carries a one-time-use, HMAC-signed token scoped to `(userId, messageId, ttl=600s)` and a `Click` URL pointing at `https://<COMPANION_BASE>/c/#<token>`. On load the PWA POSTs `/companion/session` to redeem the token, fetches the pre-rendered `spokenAnswer.opus` (cached in-memory by messageId), and renders the markdown body. Re-engage records mic audio via MediaRecorder, uploads to `/companion/utterance`, and main.mjs dispatches it through the existing voice transcript pipeline bound to `activeVoiceChannelId`.
+
+**Tech Stack:** Node 20 ESM, `express` (new dep), `crypto.timingSafeEqual` for token verify, existing `ttsBackend` for pre-render, browser `MediaRecorder` (opus) + `Web Audio` for playback, no build step (single hand-written PWA bundle).
+
+## Spec
+
+### Token grammar
+- Payload: `base64url({uid, mid, vcid, gid, exp})` + `.` + `base64url(HMAC-SHA256(payload, COMPANION_SECRET))`.
+- TTL default 600s. Single-use: redeemed tokens recorded in an in-memory `Set<string>` cleared on bot restart.
+- `COMPANION_SECRET` required when `COMPANION_BASE` is set; bot refuses to boot otherwise.
+
+### Pre-rendered audio
+- `maybeNotifyTaskComplete` (`app-node/main.mjs:369-394`) gains a sibling helper `prerenderSpokenAnswer(spokenText, lang)` that calls the existing `ttsBackend.synthesize` (same path used at `main.mjs:1495-1496`) and stashes the resulting opus bytes in a bounded LRU keyed by `messageId` (cap 32, 10 MB).
+- `notify.mjs` `send()` is extended with optional `audioUrl` and `summaryUrl` fields; the ntfy provider sets `X-Attach` and `X-Actions` headers, pushover sets `url`/`url_title`. Existing redaction in `notify.mjs:5-10` still applies to title/body.
+
+### Re-engage path
+- PWA POSTs WebM/opus blob + token to `/companion/utterance`.
+- Server hands the blob to a new `dispatchCompanionUtterance({userId, vcid, blob})` that resamples (existing `prism.opus.Decoder`) and feeds the same downstream `processVoiceTranscript(text)` path used by the VC listener (call site near `main.mjs:1488-1497`). Result: the bot answers as if the user spoke in `activeVoiceChannelId`.
+- If `vcid` differs from `activeVoiceChannelId`, the bot rebinds (mirrors `pickOccupiedUserVoiceChannel`) before replying.
+
+### Summary view
+- `/companion/summary/:mid` returns `{markdown, progressEvents}`. Markdown is the existing `fullAnswerText` (`main.mjs:1491`). Progress events come from the existing `summarizeProgressEvents` output already collected per-turn.
+
+### Security
+- All `/companion/*` routes require a valid token in `Authorization: Bearer`.
+- Tokens single-use, 10-min TTL, scoped to `(uid, mid, vcid)`. Replay → 401.
+- Mic upload capped at 1 MB and 30 s.
+- Rate-limit: 10 req/min per token (in-memory bucket).
+
+## File Structure
+- Create: `app-node/companion_server.mjs`, `app-node/companion_tokens.mjs`, `app-node/companion_tokens.test.mjs`, `app-node/companion_pwa/{index.html,app.js,sw.js,manifest.webmanifest,styles.css}`.
+- Modify: `app-node/notify.mjs` — accept `audioUrl`, `summaryUrl`; build companion deep link helper `buildCompanionLink({base, token})`.
+- Modify: `app-node/main.mjs` — pre-render audio inside `maybeNotifyTaskComplete` (line 369), mint token, swap `deepLink` for the companion URL, boot companion server at startup, add `dispatchCompanionUtterance` near the text-agent path (line 1488).
+- Modify: `.env.example` — `COMPANION_BASE`, `COMPANION_SECRET`, `COMPANION_PORT`, `COMPANION_TTL_SEC`.
+- Modify: `package.json` — add `express` dep.
+
+## Tasks
+
+### Task 1: TDD — token mint/verify
+- [ ] Step 1: Write `companion_tokens.test.mjs` covering: roundtrip ok, tampered payload fails, expired fails, single-use replay fails, wrong secret fails.
+- [ ] Step 2: Implement `companion_tokens.mjs` exporting `mint({uid,mid,vcid,gid,ttlSec,secret})` and `verify(token, {secret, redeemed})`.
+- [ ] Step 3: Run `node --test app-node/companion_tokens.test.mjs`, expect PASS. Commit.
+
+### Task 2: Pre-render audio + extend notifier
+- [ ] Step 1: Add bounded LRU `companionAudioCache` in `main.mjs` and `prerenderSpokenAnswer()` reusing `ttsBackend`.
+- [ ] Step 2: Extend `notify.mjs send()` signature with `audioUrl`, `summaryUrl`; map per-provider headers.
+- [ ] Step 3: Add `notify.test.mjs` cases for ntfy `X-Actions` and pushover `url` carrying the companion link.
+- [ ] Step 4: Commit.
+
+### Task 3: companion_server.mjs + PWA
+- [ ] Step 1: Boot Express on `COMPANION_PORT` from `main.mjs` startup; mount `/c/*` static and `/companion/*` API.
+- [ ] Step 2: Routes — `POST /companion/session`, `GET /companion/audio/:mid`, `GET /companion/summary/:mid`, `POST /companion/utterance`.
+- [ ] Step 3: PWA — manifest (standalone), SW (cache-first for static, network-only for API), `app.js` handles token redeem, autoplay (user-gesture fallback), MediaRecorder upload, summary render via lightweight markdown renderer.
+- [ ] Step 4: Add `companion_server.test.mjs` exercising token flow and utterance dispatch with a stub agent adapter.
+- [ ] Step 5: Commit.
+
+### Task 4: Wire re-engage into agent pipeline
+- [ ] Step 1: Factor the text-agent dispatch at `main.mjs:1488-1497` into `runAgentForUtterance({text, vcid, gid, speakResponse})` reused by VC and companion paths.
+- [ ] Step 2: Companion utterance → Whisper STT (existing `transcribeWav`) → `runAgentForUtterance({speakResponse: vcOccupied})`.
+- [ ] Step 3: If VC empty, response is delivered as a second push (re-uses Phase 10), creating a conversational loop entirely over phone.
+- [ ] Step 4: Commit.
+
+### Task 5: Document
+- [ ] Step 1: `.env.example` entries + `docs/USAGE.md` companion section with QR-code suggestion for first-pair UX.
+- [ ] Step 2: Note out-of-scope: native push reliability, multi-device replay.
+- [ ] Step 3: Commit.