pipulate 2.57__tar.gz → 2.59__tar.gz

{pipulate-2.57/pipulate.egg-info → pipulate-2.59}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pipulate
-Version: 2.57
+Version: 2.59
 Summary: The context compiler that helps you prompt well — local-first, Nix-reproducible, replayable. The successor to AI SEO software.
 Author-email: Mike Levin <pipulate@gmail.com>
 License-Expression: AGPL-3.0-or-later

{pipulate-2.57 → pipulate-2.59}/__init__.py

@@ -12,7 +12,7 @@ Usage:
     pipulate
 """
 
-__version__ = "2.57"
+__version__ = "2.59"
 # APOSTROPHES RESTORED (2026-08-04). They were stripped as a workaround for
 # flake.nix's descMatch regex, whose character class excluded ' from the
 # CAPTURE and truncated the banner to "(So)". That regex was fixed in the same
@@ -23,7 +23,7 @@ __version__ = "2.57"
 # is not a property of the system; the regex is. Blast radius is one banner:
 # nothing but flake.nix reads this name -- version_sync.py syncs __version__
 # and __description__, never this. So'wI' chu' -- "engage the cloaking device."
-__version_description__ = "NPvg.org Walk Walking"
+__version_description__ = "NPvg.org New-B Empathy"
 # SPDX expression, single source of truth, synced into pyproject.toml by
 # scripts/release/version_sync.py. "-or-later" (not bare AGPL-3.0, which is
 # deprecated SPDX) because the header below grants "any later version".

{pipulate-2.57 → pipulate-2.59}/apps/010_introduction.py

@@ -155,10 +155,18 @@ class IntroductionPlugin:
 
         
         from imports.voice_synthesis import chip_voice_system
-        if chip_voice_system and chip_voice_system.voice_ready:
-             chip_voice_system.stop_speaking()  # 🛑 INTERRUPT: Prevent voice overlapping on Back button
-             logger.info(f"🎤 Speaking: {step_id}")
-             asyncio.create_task(asyncio.to_thread(chip_voice_system.speak_text, text))
+        if chip_voice_system:
+            chip_voice_system.stop_speaking()  # 🛑 INTERRUPT: Prevent voice overlapping on Back button
+            def _speak():
+                # THE FLAG WENT COLD (2026-09-18): the gate moved off the event
+                # loop. can_speak() reads the consent card and loads the model
+                # on first use, seconds long, so it runs here, in the thread; a
+                # declined or unanswered card returns False with no download,
+                # and speak_text keeps its own barrier behind this one.
+                if chip_voice_system.can_speak():
+                    logger.info(f"🎤 Speaking: {step_id}")
+                    chip_voice_system.speak_text(text)
+            asyncio.create_task(asyncio.to_thread(_speak))
              
         return ""
 

{pipulate-2.57 → pipulate-2.59}/imports/voice_synthesis.py

@@ -12,9 +12,12 @@ import wave
 import subprocess
 import tempfile
 import signal
+import sys
 from pathlib import Path
 from typing import Optional, Dict, Any
+import contextlib
 import logging
+import warnings
 
 # Try to import voice synthesis dependencies
 try:
@@ -34,6 +37,128 @@ except ImportError:
 
 logger = logging.getLogger(__name__)
 
+
+@contextlib.contextmanager
+def _quiet_hub():
+    """Silence the hub for the length of the one download it ever makes.
+
+    THE QUIET WALK (2026-09-18, Mac receipt, deed 1480): the first consent
+    printed a three-line deprecation notice, a token nag and three progress
+    bars between the card and the first spoken step. The hub speaks through
+    two channels, its logger and the warnings module, and draws its bars
+    through its own switch; all three are turned down here and restored on
+    the way out, so nothing outside this block changes. The download itself
+    is announced by one plain line in the caller.
+    """
+    try:
+        from huggingface_hub.utils import (
+            are_progress_bars_disabled,
+            disable_progress_bars,
+            enable_progress_bars,
+        )
+    except ImportError:
+        are_progress_bars_disabled = disable_progress_bars = enable_progress_bars = None
+    hub_logger = logging.getLogger("huggingface_hub")
+    previous_level = hub_logger.level
+    hub_logger.setLevel(logging.ERROR)
+    bars_were_disabled = True if disable_progress_bars is None else are_progress_bars_disabled()
+    if not bars_were_disabled:
+        disable_progress_bars()
+    try:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            yield
+    finally:
+        hub_logger.setLevel(previous_level)
+        if not bars_were_disabled:
+            enable_progress_bars()
+
+# ---------------------------------------------------------------------------
+# THE VOICE ASKS BEFORE IT SPEAKS (2026-09-17). Two functions, one file.
+# voice_consent() is the BARRIER: every path to sound reads it, fresh, on every
+# call. The answer comes from PIPULATE_VOICE (an unattended shell declaring
+# intent, the way PIPULATE_BOOT_MENU=0 does) or from ~/.config/pipulate/voice,
+# outside the worktree, so it survives rm -rf on the folder and is asked once
+# per machine rather than once per install.
+# ask_voice_consent() is the CEREMONY: it prints the card and reads one line
+# from /dev/tty. The two are SEPARATE on purpose. flake.nix's door-1 greeting
+# runs as a backgrounded python with stdout on /dev/null while the server holds
+# the foreground on the same terminal; a speaker that ASKED would print the
+# card into /dev/null and take the keystrokes meant for a prompt nobody can
+# see. So the speaker never asks. The rider asks at the start of a walk, and
+# the `voice` word asks again later; both own a terminal.
+# NOTHING IS DOWNLOADED BEFORE A YES: the model loads in ensure_voice(), on
+# the first speak after consent, never at import. Importing this module used
+# to fetch the voice and spend seconds before anyone had asked to speak or
+# been asked whether it may; that was also the import tax the tool roster
+# measured at ~3.8 s.
+# ---------------------------------------------------------------------------
+VOICE_CONSENT_FILE = Path.home() / ".config" / "pipulate" / "voice"
+VOICE_CARD = (
+    "\nThe steps can be read aloud.\n\n"
+    "The voice is Piper, a small text-to-speech program that runs on this\n"
+    "computer; it was made for a Raspberry Pi. It reads sentences a person\n"
+    "typed in advance. No AI writes them, and nothing you say or type is\n"
+    "sent anywhere. Answering yes downloads the voice once, about 60 MB.\n\n"
+    "Read the steps aloud? [y/N] "
+)
+
+
+def voice_consent() -> str:
+    """'yes', 'no' or 'unset': the environment first, then the recorded answer."""
+    env = os.environ.get("PIPULATE_VOICE", "").strip().lower()
+    if env in ("0", "no", "off", "false"):
+        return "no"
+    if env in ("1", "yes", "on", "true"):
+        return "yes"
+    try:
+        recorded = VOICE_CONSENT_FILE.read_text(encoding="utf-8").strip().lower()
+    except OSError:
+        return "unset"
+    if recorded in ("yes", "no"):
+        return recorded
+    return "unset"
+
+
+def ask_voice_consent(later_hint: str = "voice", force: bool = False) -> str:
+    """Ask on /dev/tty and record the answer. Returns 'yes', 'no' or 'unavailable'.
+
+    Asks only when nothing is recorded, unless force is set (the `voice` word),
+    and never when PIPULATE_VOICE decides. Without a terminal to ask on -- a
+    pipe, a compile-lane probe, a backgrounded job -- it prints nothing and
+    returns 'unavailable', so no prompt can ever block an unattended caller.
+    Enter alone means no. A Ctrl+C is not recorded, so the question returns.
+    """
+    env = os.environ.get("PIPULATE_VOICE", "").strip().lower()
+    if env in ("0", "no", "off", "false", "1", "yes", "on", "true"):
+        return voice_consent()
+    recorded = voice_consent()
+    if recorded != "unset" and not force:
+        return recorded
+    if not sys.stdout.isatty():
+        return "unavailable"
+    try:
+        tty = open("/dev/tty", "r", encoding="utf-8")
+    except OSError:
+        return "unavailable"
+    try:
+        print(VOICE_CARD, end="", flush=True)
+        answer = tty.readline()
+    except (OSError, KeyboardInterrupt):
+        print()
+        return "no"
+    finally:
+        tty.close()
+    decision = "yes" if answer.strip().lower() in ("y", "yes") else "no"
+    try:
+        VOICE_CONSENT_FILE.parent.mkdir(parents=True, exist_ok=True)
+        VOICE_CONSENT_FILE.write_text(decision + "\n", encoding="utf-8")
+    except OSError as exc:
+        print(f"(could not record the answer, so it will be asked again: {exc})")
+    if decision == "no":
+        print(f"Staying quiet. To turn the voice on later, type: {later_hint}")
+    return decision
+
 class ChipVoiceSystem:
     """
     Voice synthesis system for Chip O'Theseus
@@ -49,9 +174,9 @@ class ChipVoiceSystem:
         self.current_process = None  # Track the running audio process
         self.last_error = None       # Populated by synthesize_and_play on failure
         
-        if VOICE_SYNTHESIS_AVAILABLE:
-            self.setup_voice_model()
-        else:
+        # No download and no model load here: see ensure_voice(). Importing
+        # this module must cost nothing and ask nothing.
+        if not VOICE_SYNTHESIS_AVAILABLE:
             logger.warning(f"🎤 Voice synthesis not available: {IMPORT_ERROR}")
     
     def setup_voice_model(self):
@@ -70,34 +195,76 @@ class ChipVoiceSystem:
             self.model_path = str(local_model_dir / model_path_in_repo)
             self.config_path = str(local_model_dir / config_path_in_repo)
             
+            downloaded = False
             # Download files if they don't exist
             if not os.path.exists(self.model_path):
+                print("Downloading the voice, about 60 MB, once...", flush=True)
                 logger.info(f"🎤 Downloading voice model: {model_path_in_repo}...")
-                hf_hub_download(
-                    repo_id=repo_id, 
-                    filename=model_path_in_repo, 
-                    local_dir=local_model_dir, 
-                    local_dir_use_symlinks=False
-                )
+                with _quiet_hub():
+                    hf_hub_download(
+                        repo_id=repo_id,
+                        filename=model_path_in_repo,
+                        local_dir=local_model_dir,
+                    )
+                downloaded = True
             
             if not os.path.exists(self.config_path):
                 logger.info(f"🎤 Downloading voice config: {config_path_in_repo}...")
-                hf_hub_download(
-                    repo_id=repo_id, 
-                    filename=config_path_in_repo, 
-                    local_dir=local_model_dir, 
-                    local_dir_use_symlinks=False
-                )
+                with _quiet_hub():
+                    hf_hub_download(
+                        repo_id=repo_id,
+                        filename=config_path_in_repo,
+                        local_dir=local_model_dir,
+                    )
+                downloaded = True
             
             # Load the voice model
             self.voice = PiperVoice.load(self.model_path, config_path=self.config_path)
             self.voice_ready = True
             logger.info("🎤 Voice model loaded successfully")
+            if downloaded:
+                print("Voice ready.", flush=True)
             
         except Exception as e:
             logger.error(f"🎤 Failed to setup voice model: {e}")
+            self.last_error = f"voice model setup failed: {e}"
             self.voice_ready = False
 
+    def ensure_voice(self) -> bool:
+        """Load the voice on first use, never at import. Returns readiness.
+
+        Reached only after voice_consent() read yes, so the download the card
+        announces happens after the answer and not before it.
+        """
+        if self.voice_ready:
+            return True
+        if not VOICE_SYNTHESIS_AVAILABLE:
+            self.last_error = f"voice synthesis not installed: {IMPORT_ERROR}"
+            return False
+        # THE PHONEME LINE (TODO of 2026-09-15, discharged 2026-09-18): piper
+        # warns, through a logger nobody configured, about one syllabic mark
+        # in the word "written", and Python's last-resort handler prints the
+        # bare message on every walk. The flake's door-1 greeting already sets
+        # this level; the speaker now sets it for every caller.
+        logging.getLogger("piper").setLevel(logging.ERROR)
+        self.setup_voice_model()
+        return self.voice_ready
+
+    def can_speak(self) -> bool:
+        """True only once a human has said yes AND the voice is loaded.
+
+        THE FLAG WENT COLD (2026-09-17, the census after the lazy load).
+        voice_ready read True at import on any machine with the model on disk,
+        and four files gate on it BEFORE they ever call speak_text:
+        apps/010_introduction.py, pipulate/core.py, server.py and
+        tools/mcp_tools.py. With the load deferred to first use the flag reads
+        False in every fresh process until something speaks, so none of those
+        gates opens. This is the question they meant to ask: consent first,
+        then the load, which downloads only after a yes. A status read that
+        must never download keeps reading voice_ready, which now means loaded.
+        """
+        return voice_consent() == "yes" and self.ensure_voice()
+
     def stop_speaking(self):
         """
         Silence! Kill the current audio process if it exists.
@@ -129,7 +296,13 @@ class ChipVoiceSystem:
         Returns:
             bool: True if successful, False otherwise
         """
-        if not self.voice_ready:
+        if voice_consent() != "yes":
+            # THE BARRIER. Every path to sound passes here, and the answer is
+            # read fresh each time, so a no recorded mid-session holds at once.
+            self.last_error = "voice not allowed"
+            logger.info("🎤 Voice not allowed; nothing spoken")
+            return False
+        if not self.ensure_voice():
             logger.warning("🎤 Voice synthesis not ready")
             return False
         
@@ -318,10 +491,22 @@ class ChipVoiceSystem:
         Returns:
             Dict with success status and details
         """
-        if not self.voice_ready:
+        consent = voice_consent()
+        if consent != "yes":
+            # DECLINED IS NOT FAILED. Callers read success=False either way;
+            # this key is how they tell a human's answer from a broken player.
+            return {
+                "success": False,
+                "declined": True,
+                "consent": consent,
+                "text": text,
+                "error": "voice declined" if consent == "no"
+                         else "voice not yet allowed: the voice card has not been answered",
+            }
+        if not self.ensure_voice():
             return {
                 "success": False,
-                "error": "Voice synthesis not available",
+                "error": self.last_error or "Voice synthesis not available",
                 "details": "Piper TTS model not loaded"
             }
         
@@ -467,7 +652,7 @@ def test_voice_synthesis():
     # Test basic voice synthesis
     test_text = "Hello Mike, this is Chip O'Theseus speaking. I can now remember what happened before the server restart!"
     
-    if chip_voice_system and chip_voice_system.voice_ready:
+    if chip_voice_system and chip_voice_system.can_speak():
         result = chip_voice_system.speak_text(test_text)
         if result["success"]:
             print("✅ Voice synthesis test successful")
@@ -510,6 +695,23 @@ def test_memory_voice_integration():
         print("❌ No memories found to test")
         return False
 
+if __name__ == "__main__" and sys.argv[1:2] == ["ask"]:
+    # `voice`, the word the card names: re-ask and record, then speak one
+    # sentence on yes so the audio path is heard rather than assumed.
+    _env = os.environ.get("PIPULATE_VOICE", "").strip()
+    if _env:
+        print(f"voice: PIPULATE_VOICE={_env!r} decides; unset it to be asked.")
+        raise SystemExit(0)
+    _decision = ask_voice_consent(later_hint="voice", force=True)
+    if _decision == "unavailable":
+        print("voice: no terminal to ask on; run this from a terminal.")
+        raise SystemExit(1)
+    print(f"voice: {_decision}  (recorded in {VOICE_CONSENT_FILE})")
+    if _decision == "yes" and chip_voice_system is not None:
+        _result = chip_voice_system.speak_text("This is Piper, reading a script. The voice is on.")
+        if not _result.get("success"):
+            print(f"voice: nothing was heard: {_result.get('error')}")
+    raise SystemExit(0)
 if __name__ == "__main__":
     # Run tests if script is executed directly
     print("🎤🧠 Chip O'Theseus Voice System Tests")

{pipulate-2.57 → pipulate-2.59}/pipulate/core.py

@@ -555,7 +555,7 @@ class Pipulate:
             try:
                 # Import here to avoid circular dependencies
                 from imports.voice_synthesis import chip_voice_system
-                if chip_voice_system and chip_voice_system.voice_ready:
+                if chip_voice_system and chip_voice_system.can_speak():
                      # Acoustic Sanitization (Using the voice_text so it doesn't read URLs!)
                      safe_text = voice_text.replace('\u0329', '')
                      safe_text = safe_text.replace('—', ', ').replace('–', ', ')

{pipulate-2.57 → pipulate-2.59/pipulate.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pipulate
-Version: 2.57
+Version: 2.59
 Summary: The context compiler that helps you prompt well — local-first, Nix-reproducible, replayable. The successor to AI SEO software.
 Author-email: Mike Levin <pipulate@gmail.com>
 License-Expression: AGPL-3.0-or-later

{pipulate-2.57 → pipulate-2.59}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "pipulate"
 # VERSION NOTE: Synced from pipulate/__init__.py.__version__ via python version_sync.py
-version = "2.57"
+version = "2.59"
 authors = [
   { name="Mike Levin", email="pipulate@gmail.com" },
 ]

{pipulate-2.57 → pipulate-2.59}/server.py

@@ -3156,7 +3156,7 @@ async def test_voice_synthesis_endpoint(request):
             return JSONResponse({"success": False, "error": "Voice synthesis not available"})
 
         # Check if voice system is ready
-        if not chip_voice_system.voice_ready:
+        if not chip_voice_system.can_speak():
             logger.error("🎤 Voice system not ready")
             return JSONResponse({"success": False, "error": "Voice system not ready"})
 

{pipulate-2.57 → pipulate-2.59}/tools/connector_tools.py

@@ -1,5 +1,5 @@
 """
-connector_tools.py -- the registry face of scripts/connectors/*.py: one tool
+connector_tools.py -- the registry face of connectors/*.py: one tool
 per connector, SAME argument shape, SAME backend, SAME docstring.
 
 This file exists for the two-arm experiment (shell verb vs registry tool) and
@@ -33,7 +33,7 @@ from pathlib import Path
 from tools import auto_tool
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
-CONNECTORS = REPO_ROOT / "scripts" / "connectors"
+CONNECTORS = REPO_ROOT / "connectors"
 TIMEOUT = 120
 KEY_TRAILER = (
     "\n\nRegistry form: --json-args keys mirror the connector's argument names --"
@@ -52,7 +52,7 @@ def _connector_doc(name):
 
 
 async def _run_connector(name, params):
-    """Run scripts/connectors/<name>.py as a subprocess; return its three channels."""
+    """Run connectors/<name>.py as a subprocess; return its three channels."""
     if not isinstance(params, dict):
         return {"success": False, "error": "params must be a JSON object"}
     argv = [sys.executable, str(CONNECTORS / f"{name}.py")]
@@ -90,7 +90,7 @@ async def _run_connector(name, params):
 
 @auto_tool
 async def botify(params: dict) -> dict:
-    """Registry face of scripts/connectors/botify.py; __doc__ is replaced at
+    """Registry face of connectors/botify.py; __doc__ is replaced at
     import with that file's own docstring so both arms read one description."""
     return await _run_connector("botify", params)
 

{pipulate-2.57 → pipulate-2.59}/tools/mcp_tools.py

@@ -1464,7 +1464,7 @@ async def voice_synthesis(params: dict) -> dict:
                 "error": "Voice synthesis not available - missing dependencies"
             }
 
-        if not chip_voice_system or not chip_voice_system.voice_ready:
+        if not chip_voice_system:
             return {
                 "success": False,
                 "error": "Voice system not ready - check model initialization"

{pipulate-2.57 → pipulate-2.59}/tools/scraper_tools.py

@@ -3,6 +3,7 @@ import asyncio
 import hashlib
 import json
 import os
+import shlex
 import sys
 import shutil
 import tempfile
@@ -21,6 +22,18 @@ from selenium.webdriver.common.by import By
 from tools import auto_tool
 from . import dom_tools
 
+# THE HEAL HAPPENS ONCE PER RUN (2026-09-18, Mac receipt, deed 1480). The
+# flake pins no Chrome on a Mac, so the driver is matched to the host's
+# Chrome at launch: the first uc.Chrome raises on the version mismatch, the
+# window it had opened closes, and the retry below relaunches with
+# version_main set to the browser's major version. That version was thrown
+# away after every stop, so a three-stop walk paid the close-and-reopen at
+# every stop and printed a WARNING three times for the ordinary case. It is
+# remembered here for the life of the process: the next launch passes it in
+# and never mismatches. A dict, not a bare name, so no function needs a
+# global statement to write it.
+_HEAL = {"version_main": None}
+
 async def generate_optics_subprocess(target_dir_path: str):
     """Isolated wrapper to call llm_optics.py as a subprocess, protecting the event loop."""
     script_path = Path(__file__).resolve().parent / "llm_optics.py"
@@ -59,35 +72,38 @@ def _guided_path_component(url: str) -> tuple[str, str]:
 
 
 # --- Optional audio during browser startup ---
-# Forked from stream.py's start_updating_music/stop_updating_music pattern:
-# a marker-tagged shell loop in its OWN process group (os.setsid), killed as
-# a group, with an idempotent pkill backstop keyed to the marker so it can
-# never touch any other aplay pipeline. The wav lives in repo negative space
-# (gitignored) or ~/.local/share/pipulate/; absent file = silent no-op.
+# Operator-owned courtesy sounds live outside the repo. tick.wav loops while
+# the browser is opening; ding.wav plays once when the page-load phase ends.
+# No file means no sound. Linux uses aplay; Darwin uses afplay.
 SCRAPE_MUSIC_MARKER = "pipulate-scrape-music"
+SOUND_DIR = Path.home() / ".local/share/pipulate"
 
 
-def _find_music_file():
-    candidates = [
-        Path(__file__).resolve().parent.parent / "jeopardy.wav",
-        Path.home() / ".local/share/pipulate/jeopardy.wav",
-        Path.home() / ".local/share/honeybot/jeopardy.wav",
-    ]
-    for c in candidates:
-        if c.exists():
-            return c
-    return None
+def _sound_file(name):
+    path = SOUND_DIR / name
+    return path if path.is_file() else None
+
+
+def _player_args(sound):
+    if sound is None:
+        return None
+    if sys.platform == "darwin":
+        player = shutil.which("afplay")
+        return [player, str(sound)] if player else None
+    player = shutil.which("aplay")
+    return [player, "-q", "-D", "default", str(sound)] if player else None
 
 
 def _start_scrape_music(verbose=True):
     import subprocess
-    music = _find_music_file()
-    if not music:
-        return None
 
+    args = _player_args(_sound_file("tick.wav"))
+    if not args:
+        return None
+    command = " ".join(shlex.quote(part) for part in args)
     try:
         return subprocess.Popen(
-            ["sh", "-c", f'while :; do aplay -q -D default "{music}"; done # {SCRAPE_MUSIC_MARKER}'],
+            ["sh", "-c", f"while :; do {command}; done # {SCRAPE_MUSIC_MARKER}"],
             stdout=subprocess.DEVNULL,
             stderr=subprocess.DEVNULL,
             preexec_fn=os.setsid,
@@ -96,18 +112,36 @@ def _start_scrape_music(verbose=True):
         return None
 
 
-def _stop_scrape_music(proc):
+def _stop_scrape_music(proc, ding=False):
     import signal
     import subprocess
+
     if proc is not None:
         try:
             os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
         except Exception:
             pass
     try:
-        subprocess.run(["pkill", "-f", SCRAPE_MUSIC_MARKER], check=False)
+        subprocess.run(
+            ["pkill", "-f", SCRAPE_MUSIC_MARKER],
+            check=False,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
     except Exception:
         pass
+    if ding:
+        args = _player_args(_sound_file("ding.wav"))
+        if args:
+            try:
+                subprocess.run(
+                    args,
+                    check=False,
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                )
+            except Exception:
+                pass
 
 
 def _simplify_html_for_llm(html_content, default_title=""):
@@ -223,7 +257,7 @@ def _document_candidates(cdp_events: list, domain: str, final_url: str = "") ->
     return on_host
 
 
-def _capture_checkpoint(stdin=None, stdout=None) -> dict:
+def _capture_checkpoint(stdin=None, stdout=None, before_prompt=None) -> dict:
     """Require an explicit CAPTURE token from the human's keyboard.
 
     /DEV/TTY PREFERENCE (convicted 2026-07-29, public_walk stop 1): the
@@ -265,8 +299,16 @@ def _capture_checkpoint(stdin=None, stdout=None) -> dict:
             }
 
         try:
+            if before_prompt is not None:
+                try:
+                    before_prompt()
+                except Exception as exc:
+                    output_stream.write(f"\n(checkpoint narration unavailable: {exc})\n")
+            else:
+                output_stream.write(
+                    "\nWhen the page you want is ready, type CAPTURE and press Enter.\n"
+                )
             output_stream.write(
-                "\nWhen the page you want is ready, type CAPTURE and press Enter.\n"
                 "Any other response aborts without capturing artifacts.\n"
                 "CAPTURE> "
             )
@@ -560,7 +602,8 @@ async def _selenium_capture(params: dict, checkpoint=None) -> dict:
             driver = uc.Chrome(options=options, 
                                user_data_dir=str(profile_path), 
                                browser_executable_path=browser_path,
-                               driver_executable_path=driver_path)
+                               driver_executable_path=driver_path,
+                               version_main=_HEAL["version_main"])
         except Exception as e:
             error_msg = str(e)
             if "Current browser version is" in error_msg:
@@ -568,7 +611,10 @@ async def _selenium_capture(params: dict, checkpoint=None) -> dict:
                 match = re.search(r'Current browser version is (\d+)', error_msg)
                 if match:
                     fallback_version = int(match.group(1))
-                    logger.warning(f"⚠️ Chrome version mismatch detected. Auto-healing with version_main={fallback_version}")
+                    _HEAL["version_main"] = fallback_version
+                    logger.info(f"Chrome {fallback_version}: driver matched; relaunching once for this run")
+                    if verbose:
+                        print(f"Chrome closed and is reopening once while its driver is matched to Chrome {fallback_version}; that is normal.", flush=True)
                     # UC consumes the options object. We must forge a fresh one.
                     fresh_options = uc.ChromeOptions()
                     fresh_options.set_capability("goog:loggingPrefs", {"performance": "ALL"})
@@ -592,20 +638,25 @@ async def _selenium_capture(params: dict, checkpoint=None) -> dict:
         logger.info(f"Navigating to: {url}")
         driver.get(url)
 
-        try:
-            if verbose: logger.info("Waiting for security challenge to trigger a reload (Stage 1)...")
-            initial_body = driver.find_element(By.TAG_NAME, 'body')
-            WebDriverWait(driver, 20).until(EC.staleness_of(initial_body))
-            if verbose: logger.success("✅ Page reload detected!")
-            
-            if verbose: logger.info("Waiting for main content to appear after reload (Stage 2)...")
-            WebDriverWait(driver, 10).until(EC.presence_of_element_located((By.CSS_SELECTOR, "body")))
-            if verbose: logger.success("✅ Main content located!")
-        except Exception as e:
-            if verbose: logger.info(f"Did not detect a page reload for security challenge. Proceeding anyway.")
+        # A human-guided ride already has the CAPTURE fence as its settle
+        # detector. The 20-second staleness wait exists for unattended sigil
+        # scrapes, where a security interstitial may reload underneath us.
+        if not interactive:
+            try:
+                if verbose: logger.info("Waiting for security challenge to trigger a reload (Stage 1)...")
+                initial_body = driver.find_element(By.TAG_NAME, 'body')
+                WebDriverWait(driver, 20).until(EC.staleness_of(initial_body))
+                if verbose: logger.success("✅ Page reload detected!")
+
+                if verbose: logger.info("Waiting for main content to appear after reload (Stage 2)...")
+                WebDriverWait(driver, 10).until(EC.presence_of_element_located((By.CSS_SELECTOR, "body")))
+                if verbose: logger.success("✅ Main content located!")
+            except Exception:
+                if verbose: logger.info("Did not detect a page reload for security challenge. Proceeding anyway.")
 
-        # The wait is over one way or the other: cut the think-music sharply.
-        _stop_scrape_music(music_proc)
+        # The page-load phase is over: stop ticking and, if the operator
+        # supplied one, play the ready sound exactly once.
+        _stop_scrape_music(music_proc, ding=True)
         music_proc = None
 
         if checkpoint is not None:
@@ -737,8 +788,8 @@ async def _selenium_capture(params: dict, checkpoint=None) -> dict:
             # ledger-only so it can be replayed offline over any cached capture.
             #
             # [-1] SURVIVES, and its rationale is still UNWITNESSED: the
-            # staleness_of() wait above exists because a security challenge
-            # serves an interstitial Document and then reloads, making the LAST
+            # non-interactive staleness_of() wait above exists because a security
+            # challenge serves an interstitial Document and then reloads, making the LAST
             # candidate the real page. No capture on this machine has ever been
             # challenged -- every scrape logs "Did not detect a page reload."
             # The reasoning is sound from the code and has no receipt behind it.
@@ -956,7 +1007,7 @@ async def selenium_automation(params: dict) -> dict:
     return await _selenium_capture(params)
 
 
-async def guided_browser_capture(params: dict, stdin=None, stdout=None) -> dict:
+async def guided_browser_capture(params: dict, stdin=None, stdout=None, before_prompt=None) -> dict:
     """Capture one human-guided page through one visible persistent driver."""
     if not isinstance(params, dict):
         return {
@@ -1029,5 +1080,6 @@ async def guided_browser_capture(params: dict, stdin=None, stdout=None) -> dict:
         checkpoint=lambda: _capture_checkpoint(
             stdin=input_stream,
             stdout=stdout,
+            before_prompt=before_prompt,
         ),
     )