Implement operator overlay improvements and refine bus demux skills

.env.debug.example

@@ -7,6 +7,11 @@
 # Runtime precedence: process env / ~/.codescribe/.env > settings.json > defaults.
 # Secrets belong in Settings / macOS Keychain; placeholders are never real keys.
 
+# =============================================================================
+# APPLICATION RUNTIME
+# =============================================================================
+# CODESCRIBE_APP_RUNTIME_WORKERS=4  # Default: 4 — Named Tokio async workers owned by Codescribe.app (1-16; restart required)
+
 # =============================================================================
 # STT / WHISPER
 # =============================================================================

.env.example

@@ -9,6 +9,11 @@
 # Runtime precedence: process env / ~/.codescribe/.env > settings.json > defaults.
 # Prefer Settings for user-facing options and macOS Keychain for secrets.
 
+# =============================================================================
+# APPLICATION RUNTIME
+# =============================================================================
+# CODESCRIBE_APP_RUNTIME_WORKERS=4  # Default: 4 — Named Tokio async workers owned by Codescribe.app (1-16; restart required)
+
 # =============================================================================
 # STT / WHISPER
 # =============================================================================
@@ -26,7 +31,7 @@
 # CODESCRIBE_ONNX_REPO=onnx-community/whisper-large-v3-turbo  # Default: onnx-community/whisper-large-v3-turbo — HuggingFace repo for ONNX model download
 # CODESCRIBE_SILERO_FUSION=0  # Default: 0 — W13-3B Silero-identity conservative fusion lane (Supervisor edges + time-sliced Apple finals). Default OFF.
 # CODESCRIBE_SILERO_FUSION_CONTEXT=utterance  # Default: utterance — Bounded-context A/B: utterance | left_pad | stable_prompt. Never crosses a long-silence fence.
-# CODESCRIBE_SPAN_IDEMPOTENCE=0  # Default: 0 — W13-4 sealed-span replay refusal + in-span loop fence (range identity, never content). Default OFF.
+# CODESCRIBE_SPAN_IDEMPOTENCE=1  # Default: 1 — PCM-range replay refusal + in-span loop fence; 0 is diagnostic only.
 # CODESCRIBE_STT_COMMIT_MIN_INTERVAL_MS=180  # Default: 180 — Minimum interval between committed/final STT inference jobs in milliseconds
 # CODESCRIBE_STT_ENGINE=auto  # Default: auto — STT engine: auto (Apple on supported macOS, Candle fallback), candle, onnx, or apple
 # CODESCRIBE_STT_INITIAL_PROMPT_ENABLED=0  # Default: 0 — Opt-in gate for Candle Whisper runtime-lexicon initial_prompt. Default OFF after W2-F measured a 100% WER regression with the active prompt.

.grok/skills/bus-demux/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: bus-demux
+description: >
+  Run scripts/bus-demux.py against codescribe.transcript.v1. Flags: --become,
+  --name, --follow, --once. Use when the operator says bus-demux flags, kielbasa
+  follower, or needs the CLI. Session attach and naming live in the codescribe
+  skill — do not reimplement them here.
+---
+
+# Bus demux — CLI
+
+Session attach lives in `codescribe`. This file is flags only.
+
+```bash
+python3 scripts/bus-demux.py --become --follow
+python3 scripts/bus-demux.py --name james --follow
+python3 scripts/bus-demux.py --name james --once
+```
+
+Unnamed agents do not pass (exit 2). No microphone. No Lab.

.grok/skills/codescribe

@@ -0,0 +1 @@
+../../skills/codescribe

AGENTS.md

@@ -1,6 +1,6 @@
 # Codescribe Local Agent Contract
 
-The VetCoders Global Agent Charter is authoritative in this repository. This
+The Vetcoders Global Agent Charter is authoritative in this repository. This
 file adds only Codescribe-specific runtime laws and pointers; it does not create
 a second workflow, dispatch plane, or worktree policy.
 

AGENT_BUS.md

@@ -226,3 +226,18 @@ ours).
 5. **Overlay Timer:** Dodanie widocznego licznika sekundowego do ekranu transkrypcji live.
 
 Authored-By: antigravity <agents@vetcoders.io>
+
+---
+
+## SIGNAL · LAYER1_FAIL_CLOSED · 2026-08-21
+
+**Od:** codex → wszyscy agenci / operator
+
+Field falsification supersedes `POLARIZE_LAYER1_DEFAULT_AND_LBRX_BENCH` on one
+point only: `CODESCRIBE_LAYERED_TRANSCRIPTION` is now **OFF by default**.
+Unset preserves Apple live + lexicon; explicit `phase1` remains an experimental
+operator path. Do not restore stock Layer 1 until PCM/span identity reaches one
+rewrite fence, gap append is structurally idempotent, deliberate repetition
+survives, and bounded stop-drain emits complete receipts.
+
+Authored-By: codex <agents@vetcoders.io>

CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **The signed app can install the live named-agent bridge.** Agentic Readiness
+  keeps the 13-step Setup Wizard intact while letting the operator explicitly
+  select Codex and/or Claude Code. A checksumed bundle payload installs to the
+  stable `~/.codescribe/agent-bridge/` runtime with one receipt and managed
+  markers; foreign skill folders are visible conflicts. The demux follows live
+  drafts, waits for `transcript_sealed` before state changes, and persists a
+  provider-session lease/cursor plus active names across provider recovery.
+
 ### Fixed
 
 - **`make install-app` accepts keys from Get license.** A keyed local

Makefile

@@ -648,21 +648,20 @@ engine-auth: $(ENGINE_BRIDGE)
 # until streaming bridge v2 lands — that is the point, not a flake. Every run
 # prints token similarity + a word-level diff for the grinding loop.
 #
-# LANE PINNED, not inherited. `CODESCRIBE_LAYERED_TRANSCRIPTION` is a power-user
-# key (not promoted to settings.json), so `Config::inject_file_env_for_runtime`
-# copies it out of ~/.codescribe/.env into the process environment. An operator
-# running their daily dictation on `phase1` therefore armed Layer 1 *inside this
-# Layer-0 target* — and Layer 1 is supposed to diverge from Apple, so the bar
-# went red for doing its job. Measured 2026-08-08, one binary, consecutive runs:
+# LANE PINNED, not inherited. This key is now promoted to settings.json, but a
+# test process still accepts an explicit env override. Before promotion, an
+# operator's `phase1` leaked into this Layer-0 target — and Layer 1 is supposed
+# to diverge from Apple, so the bar went red for doing its job. Measured
+# 2026-08-08, one binary, consecutive runs:
 # `Other: 1` → 0.931 PASS, then `Other: 22` → 0.833 FAIL. Explicit `off` also
-# blocks the injection at source (it only fills keys absent from the env).
+# pins the intended measurement at the process boundary.
 
 # The lane the CALLER asked for — and it is exactly what the recipe pins below
 # throw away. `make` cannot see a recipe-level `VAR=x cmd` assignment, but it
 # does see `VAR=x make …` / `make VAR=x`, so `origin` separates "the caller
 # pinned a lane" from "nobody asked". The operator's own `~/.codescribe/.env` is
-# injected in-process by the core, never into this shell, so a daily `phase1`
-# dotenv leaves this empty and the guard below stays silent for daily runs.
+# is no longer an unpromoted injection path; the guard still rejects a caller
+# request that contradicts the recipe's explicit lane pin.
 ifneq ($(origin CODESCRIBE_LAYERED_TRANSCRIPTION),undefined)
 PARITY_LANE_REQUEST := $(CODESCRIBE_LAYERED_TRANSCRIPTION)
 endif

README.md

@@ -5,17 +5,17 @@
 [![CI](https://github.com/vetcoders/codescribe/actions/workflows/rust.yml/badge.svg)](https://github.com/vetcoders/codescribe/actions/workflows/rust.yml)
 [![Landing](https://img.shields.io/badge/site-vetcoders.github.io%2Fcodescribe-788c5d)](https://vetcoders.github.io/codescribe/)
 
-**Native macOS tray dictation and assistive voice overlay: instant Apple-neural live canvas, Whisper filling the gaps on the go, lexicon correction last — append-only, never rewritten — plus quality tooling.**
+**Native macOS tray dictation and assistive voice overlay: instant Apple-neural live canvas, Whisper repairing the same PCM-bound spans on the go, lexicon correction last — plus quality tooling.**
 
 ## Overview
 
 Codescribe is a native macOS menu-bar application that captures audio through global hotkeys, shows live local
 transcription while you speak, and pastes or routes the final result into the focused application. The shipped product
 in this repo is a tray app whose SwiftUI front-end has two explicit surfaces: settings and overlays.
 
-The transcription shape is layered and append-only (see `AGENTS.md`, the one rule): Apple Speech is the instant
-letter-level live canvas; local Whisper transcribes partials on the go to fill the canvas gaps — it is not the live
-engine and not a stop-time authority; lexicon correction by dictionary substitution is the final automated layer, and
+The transcription shape is layered and span-bound (see `docs/THE_ENGINE_CONTRACT.md`): Apple Speech is the instant
+letter-level live canvas; in Local Power mode, local Whisper transcribes partials on the go to repair weaker wording
+inside the same proven audio spans — it is not a stop-time authority; lexicon correction by dictionary substitution is the final automated layer, and
 human corrections feed the lexicon. Cloud STT is optional and used as a post-capture transcript backend, not as live
 cloud preview. AI formatting and assistive mode use OpenAI Responses API (`/v1/responses`) by default, configured in
 Settings or `~/.codescribe/.env`.

app/controller/final_pass.rs

@@ -11,14 +11,14 @@
 //!   adopted onto the committed words (`punctuation_transplant`; word sequence
 //!   invariant at THIS stage
 //!   because shape is the deficit here — live word corrections belong to the
-//!   Layer 1 tail patch, which is a core element, on by default). When
+//!   Local Power's exact-span Layer 1 tail-patch lane). When
 //!   incomplete, only the uncommitted audio tail (from the last committed
 //!   utterance end) is transcribed and **appended** to the committed streaming
 //!   text. The doctrine behind all of this forbids TRUNCATING overlay text and
 //!   DROPPING transcripts the user already saw (the pre-0.8.0 full-replace
 //!   failure) — it does not forbid live correction of committed words.
-//!   Pair with `CODESCRIBE_LAYERED_TRANSCRIPTION` (orthogonal toggle) for live
-//!   Whisper tail-patches during hold — Smart does not force layered on.
+//!   Local Power arms live Whisper tail-patches independently of this stop
+//!   policy; the compatibility override is not a final-pass switch.
 //! - **Off**: hard off at stop — zero Whisper invocation on the stop path;
 //!   streaming (+ post-process) is final.
 //!

app/controller/helpers.rs

@@ -1963,6 +1963,7 @@ mod tests {
             compression_ratio: None,
             quality_gate_dropped: false,
             confidence_flags: vec![],
+            acoustic: None,
         });
         let sealed = snapshot_session_telemetry(&shared);
         assert!(!sealed.pending_tail);
@@ -2022,6 +2023,7 @@ mod tests {
                 compression_ratio: None,
                 quality_gate_dropped: false,
                 confidence_flags: vec![],
+                acoustic: None,
             };
 
         sink.on_event(&utterance_final(1, 0.0, 3.2));
@@ -2076,6 +2078,7 @@ mod tests {
                 compression_ratio: None,
                 quality_gate_dropped: false,
                 confidence_flags: vec![],
+                acoustic: None,
             };
 
         sink.on_event(&utterance_final(1, 0.0, 3.2));
@@ -2133,6 +2136,7 @@ mod tests {
             compression_ratio: None,
             quality_gate_dropped: false,
             confidence_flags: vec![],
+            acoustic: None,
         };
 
         // Near misses: the sibling receipt code, a truncation, an extension, a

app/controller/mod.rs

@@ -74,7 +74,8 @@ use crate::os::hold_badge::BadgeMode;
 use crate::os::hotkeys::{self, HoldMode};
 use crate::os::selection::{
     AssistiveContext, capture_assistive_context,
-    capture_assistive_context_with_image_with_prior_frontmost, capture_frontmost_app_only,
+    capture_assistive_context_with_image_with_prior_frontmost,
+    capture_frontmost_app_only_with_prior_frontmost,
 };
 use crate::os::shortcut_registry;
 use codescribe_core::asr_session::gateway_session_availability;
@@ -994,7 +995,8 @@ impl RecordingController {
         let mut deferred_insert_failure = None;
         let delivery = match disposition {
             OverlayPasteDisposition::Paste => {
-                clipboard::paste_text(&paste_text).context("Failed to paste overlay text")?;
+                clipboard::paste_and_restore(&paste_text)
+                    .context("Failed to paste overlay text")?;
                 OverlayPasteDelivery::Pasted
             }
             OverlayPasteDisposition::CopyAccessibilityDenied => {
@@ -2168,9 +2170,12 @@ impl RecordingController {
                 .clone()
                 .unwrap_or_default()
         } else {
-            tokio::task::spawn_blocking(capture_frontmost_app_only)
-                .await
-                .unwrap_or_default()
+            let prior = self.pre_overlay_frontmost_app.read().await.clone();
+            tokio::task::spawn_blocking(move || {
+                capture_frontmost_app_only_with_prior_frontmost(prior)
+            })
+            .await
+            .unwrap_or_default()
         };
         *self.pre_overlay_frontmost_app.write().await = trigger_context.frontmost_app.clone();
         *self.assistive_context.write().await = Some(trigger_context);
@@ -2434,9 +2439,12 @@ impl RecordingController {
                 .await
                 .unwrap_or_default()
         } else {
-            tokio::task::spawn_blocking(capture_frontmost_app_only)
-                .await
-                .unwrap_or_default()
+            let prior = self.pre_overlay_frontmost_app.read().await.clone();
+            tokio::task::spawn_blocking(move || {
+                capture_frontmost_app_only_with_prior_frontmost(prior)
+            })
+            .await
+            .unwrap_or_default()
         };
         *self.pre_overlay_frontmost_app.write().await = trigger_context.frontmost_app.clone();
         *self.assistive_context.write().await = Some(trigger_context);
@@ -3969,8 +3977,8 @@ impl RecordingController {
             {
                 let lang_str = language_opt.map(String::from);
                 // W13-1: consume the inline-format buffer when armed — stop
-                // pays only for the unformatted tail; falls back to the classic
-                // full-text format when the buffer cannot prove coverage.
+                // closes only the unformatted tail. An active ledger mismatch
+                // fails open to complete L2 text, never a hidden full-text call.
                 let result = codescribe_core::llm::inline_format::format_text_with_inline_buffer(
                     &clean_text,
                     lang_str.as_deref(),
@@ -4025,7 +4033,7 @@ impl RecordingController {
                 info!("Formatting mode (Left Option): correcting transcript via AI");
 
                 let lang_str = language_opt.map(String::from);
-                // W13-1: inline buffer first, classic full format as fallback.
+                // W13-1: span-keyed inline close; active failure keeps full L2.
                 let result = codescribe_core::llm::inline_format::format_text_with_inline_buffer(
                     &clean_text,
                     lang_str.as_deref(),
@@ -4071,7 +4079,7 @@ impl RecordingController {
                 info!("Formatting mode (Toggle): correcting transcript via AI");
 
                 let lang_str = language_opt.map(String::from);
-                // W13-1: inline buffer first, classic full format as fallback.
+                // W13-1: span-keyed inline close; active failure keeps full L2.
                 let result = codescribe_core::llm::inline_format::format_text_with_inline_buffer(
                     &clean_text,
                     lang_str.as_deref(),

app/controller/overlay_paste.rs

@@ -136,22 +136,40 @@ pub(super) fn overlay_paste_disposition(
     OverlayPasteDisposition::CopyTargetMismatch
 }
 
+/// Whether a successful `activate` still counts when `NSWorkspace` has not
+/// flipped yet. The overlay panel can keep the process named Codescribe after
+/// Alacritty/Chrome actually took the key window — requiring a name match here
+/// parks every auto-paste as ⌘⌥V.
+pub(super) fn overlay_float_still_confirms_activation(
+    wait_confirmed: bool,
+    frontmost_after_activate: Option<&str>,
+) -> bool {
+    wait_confirmed
+        || frontmost_after_activate
+            .map(str::trim)
+            .is_some_and(|name| !name.is_empty() && target_is_self_app(name))
+}
+
 /// Activate the latched ambulance and confirm it owns focus.
 ///
 /// Codescribe (Agent window) is already this process — no activate. A foreign
-/// app must both activate and match `NSWorkspace` within the budget. The
-/// floating overlay can leave workspace still naming Codescribe; callers pass
-/// this bit into [`overlay_paste_disposition`] so a confirmed Alacritty is
-/// not vetoed as "frontmost is Codescribe".
+/// app must activate. Matching `NSWorkspace` within the budget is sufficient
+/// but not required when the overlay still names this process.
 pub(super) fn confirm_latched_paste_target(target_app: Option<&str>) -> bool {
     let Some(name) = target_app.map(str::trim).filter(|n| !n.is_empty()) else {
         return false;
     };
     if target_is_self_app(name) {
         return true;
     }
-    crate::os::selection::activate_app_by_name(name)
-        && crate::os::selection::wait_for_frontmost_app(name, OVERLAY_PASTE_FOCUS_BUDGET)
+    if !crate::os::selection::activate_app_by_name(name) {
+        return false;
+    }
+    let waited = crate::os::selection::wait_for_frontmost_app(name, OVERLAY_PASTE_FOCUS_BUDGET);
+    overlay_float_still_confirms_activation(
+        waited,
+        crate::os::selection::current_frontmost_app_name().as_deref(),
+    )
 }
 
 /// Park a refused synthetic paste in the process-local Paste Here slot.

app/controller/production_replay.rs

@@ -243,6 +243,7 @@ mod tests {
             compression_ratio: None,
             quality_gate_dropped: false,
             confidence_flags: Vec::new(),
+            acoustic: None,
         }
     }
 

app/controller/quality_delivery.rs

@@ -202,7 +202,7 @@ pub(super) struct ClipboardDeliverySink;
 impl AutomaticDeliverySink for ClipboardDeliverySink {
     /// Paste delivery path: type/paste corrected text into the frontmost app.
     fn paste(&self, text: &str) -> Result<()> {
-        clipboard::paste_text(text).context("Failed to paste text")
+        clipboard::paste_and_restore(text).context("Failed to paste text")
     }
 }