luckiest-co 1.0.47 → 1.0.49

package/skills/trends/scripts/lib/subproc.py

@@ -1,8 +1,7 @@
-"""Subprocess helpers: safe timeout + process-group cleanup.
+"""Subprocess helpers: safe timeout + process-tree cleanup.
 
-Used by bird_x.py (Node.js Bird search) and youtube_yt.py (yt-dlp search
-and transcript download). Both need the same os.setsid/killpg cleanup
-dance on timeout to avoid orphaning child processes.
+Used by Bird/X search and other external-source clients. POSIX children use
+their own process group; Windows children run inside a kill-on-close job.
 """
 
 from __future__ import annotations
@@ -10,6 +9,10 @@ from __future__ import annotations
 import os
 import signal
 import subprocess
+import tempfile
+import threading
+import time
+from contextlib import ExitStack
 from dataclasses import dataclass
 from typing import Optional, Sequence
 
@@ -17,6 +20,138 @@ from typing import Optional, Sequence
 class SubprocTimeout(Exception):
     """Raised when a subprocess exceeds its timeout and is killed."""
 
+    def __init__(self, message: str = "", *, started: bool = True):
+        super().__init__(message)
+        self.started = started
+
+
+# Live run_with_timeout children, process-wide. Each child is a session
+# leader (os.setsid), so a group kill aimed at the engine never reaches it;
+# the engine's SIGTERM handler and atexit hook drain this set instead. It
+# lives here, not in last30days.py, because the entrypoint runs as
+# __main__: importing it by name from lib/ executes a second module copy
+# with its own empty registry, and on a worker thread that copy cannot
+# install its signal handler either. RLock because cleanup_children runs
+# inside a signal handler on the main thread, which may already hold the
+# lock in register_child_pid.
+_child_pids: set[int] = set()
+_child_pids_lock = threading.RLock()
+_child_jobs: dict[int, object] = {}
+# Set once cleanup_children starts. Worker threads keep running while the
+# handler sleeps through the grace, so a source can spawn a child after the
+# snapshot; register_child_pid kills such late children itself.
+_shutting_down = False
+_WINDOWS = os.name == "nt"
+
+
+def register_child_pid(pid: int) -> None:
+    with _child_pids_lock:
+        _child_pids.add(pid)
+        late = _shutting_down
+    if late:
+        _kill_child_group(pid, getattr(signal, "SIGKILL", signal.SIGTERM))
+
+
+def unregister_child_pid(pid: int) -> None:
+    with _child_pids_lock:
+        _child_pids.discard(pid)
+        job = _child_jobs.pop(pid, None)
+        if job is not None:
+            job.close()
+
+
+# Upper bound on how long cleanup_children waits for SIGTERMed groups before
+# SIGKILLing them. It runs inside the engine's SIGTERM handler, so it must
+# finish well inside the MCP server's termGracePeriod
+# (mcp/internal/engine/run.go), after which the engine group is SIGKILLed and
+# the handler never reaches the escalation. Pinned by tests/test_subproc.py.
+CLEANUP_TERM_GRACE_SECONDS = 0.8
+_CLEANUP_POLL_SECONDS = 0.05
+
+
+def _signal_group(pgid: int, sig: int) -> bool:
+    """Signal a child's process group; False once the group has no members."""
+    try:
+        os.killpg(pgid, sig)
+    except (ProcessLookupError, PermissionError, OSError):
+        return False
+    return True
+
+
+def _taskkill_pid(pid: int, timeout: float = 2) -> bool:
+    try:
+        result = subprocess.run(
+            ["taskkill", "/F", "/T", "/PID", str(pid)],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            timeout=timeout,
+            check=False,
+            creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    return result.returncode == 0
+
+
+def _kill_windows_tree(pid: int) -> bool:
+    return _taskkill_pid(pid)
+
+
+def _kill_windows_managed_tree(pid: int) -> bool:
+    with _child_pids_lock:
+        job = _child_jobs.get(pid)
+        if job is not None and job.terminate():
+            return True
+        return _kill_windows_tree(pid)
+
+
+def _kill_child_group(pid: int, sig: int) -> None:
+    if hasattr(os, "setsid") and hasattr(os, "killpg"):
+        _signal_group(pid, sig)
+        return
+    if _WINDOWS and _kill_windows_managed_tree(pid):
+        return
+    try:
+        os.kill(pid, sig)
+    except (ProcessLookupError, PermissionError, OSError):
+        pass
+
+
+def cleanup_children(grace: float = CLEANUP_TERM_GRACE_SECONDS) -> None:
+    """Terminate the process group of every registered child.
+
+    Windows jobs terminate immediately. On POSIX, SIGTERM every group, wait
+    up to ``grace`` seconds for the groups to empty, then SIGKILL survivors.
+    run_with_timeout starts each POSIX child with os.setsid, so the child's
+    pid is its pgid; signalling the pgid directly still reaches grandchildren
+    after the leader has been reaped,
+    and the kernel does not reuse a pid while a group of that id has
+    members. A group whose only member is an unreaped zombie still reads as
+    live, which at worst costs the full grace and a harmless SIGKILL.
+    Children registered after this call starts are SIGKILLed as they
+    register, since the caller is about to exit.
+    """
+    global _shutting_down
+    with _child_pids_lock:
+        _shutting_down = True
+        pids = list(_child_pids)
+    if not pids:
+        return
+    if not (hasattr(os, "setsid") and hasattr(os, "killpg")):
+        for pid in pids:
+            with _child_pids_lock:
+                if pid in _child_pids:
+                    _kill_child_group(pid, signal.SIGTERM)
+        return
+    live = [pgid for pgid in pids if _signal_group(pgid, signal.SIGTERM)]
+    deadline = time.monotonic() + grace
+    while live and time.monotonic() < deadline:
+        time.sleep(_CLEANUP_POLL_SECONDS)
+        live = [pgid for pgid in live if _signal_group(pgid, 0)]
+    for pgid in live:
+        _signal_group(pgid, signal.SIGKILL)
+
 
 @dataclass
 class SubprocResult:
@@ -30,84 +165,203 @@ class SubprocResult:
 def run_with_timeout(
     cmd: Sequence[str],
     *,
-    timeout: int,
+    timeout: float,
     env: Optional[dict] = None,
     on_pid: Optional[callable] = None,
+    input_text: Optional[str] = None,
+    deadline_monotonic: Optional[float] = None,
+    cancel: Optional[threading.Event] = None,
+    cleanup_grace: float = 5.0,
+    capture_limit_bytes: Optional[int] = None,
 ) -> SubprocResult:
     """Run a subprocess with process-group cleanup on timeout.
 
-    Spawns ``cmd`` inside its own process group via ``os.setsid`` where
-    available. If ``communicate(timeout=...)`` raises ``TimeoutExpired``,
-    signals ``SIGTERM`` to the entire group, falls back to ``proc.kill()``
-    if the signal fails, then waits up to 5 seconds for cleanup, and
-    raises ``SubprocTimeout``.
+    Spawns ``cmd`` inside its own process group via ``start_new_session`` where
+    available. On Windows, the child enters a kill-on-close job before it runs,
+    so cleanup reaches descendants that inherit the job after launchers exit.
+    Closing the job on normal return also stops detached descendants. Job setup
+    failure aborts the suspended child. POSIX signals the group with SIGTERM,
+    then escalates to SIGKILL if needed.
 
     Args:
         cmd: Command and arguments to spawn.
         timeout: Timeout in seconds passed to ``communicate()``.
         env: Optional environment dict. If None, inherits parent env.
         on_pid: Optional callable invoked with the child PID right after
-            spawn. Used by bird_x.py to register child PIDs for cleanup
-            tracking. Exceptions raised by the callback are suppressed.
+            spawn. Exceptions raised by the callback are suppressed. The
+            child is registered for cleanup_children() regardless.
+        input_text: Optional UTF-8 text supplied on stdin, never argv.
+        deadline_monotonic: Absolute operation deadline, including startup.
+        cancel: Optional event checked while waiting for the command.
+        cleanup_grace: Maximum TERM wait and subsequent KILL/reap wait, each.
+        capture_limit_bytes: Capture to temporary files instead of pipes,
+            reading at most this many bytes from each stream after exit.
 
     Returns:
         SubprocResult with returncode, stdout, and stderr as strings.
 
     Raises:
-        SubprocTimeout: If the process exceeded ``timeout``.
+        SubprocTimeout: If the process timed out, was cancelled, or its
+            absolute deadline elapsed.
         FileNotFoundError: If the executable is not found.
         OSError: For other spawn failures.
     """
-    preexec = os.setsid if hasattr(os, "setsid") else None
-
-    proc = subprocess.Popen(
-        list(cmd),
-        stdout=subprocess.PIPE,
-        stderr=subprocess.PIPE,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-        preexec_fn=preexec,
-        env=env,
-    )
-
-    if on_pid is not None:
-        try:
-            on_pid(proc.pid)
-        except Exception:
-            pass
+    if deadline_monotonic is not None and time.monotonic() >= deadline_monotonic:
+        raise SubprocTimeout("Command deadline exceeded before spawn", started=False)
+    if cancel is not None and cancel.is_set():
+        raise SubprocTimeout("Command cancelled before spawn", started=False)
+    if capture_limit_bytes is not None and capture_limit_bytes < 0:
+        raise ValueError("capture limit must be nonnegative")
+    own_group = hasattr(os, "setsid") and hasattr(os, "killpg")
+    native_windows = _WINDOWS
+    capture = ExitStack()
+    job = None
+    try:
+        stdout_file = capture.enter_context(tempfile.TemporaryFile()) if capture_limit_bytes is not None else None
+        stderr_file = capture.enter_context(tempfile.TemporaryFile()) if capture_limit_bytes is not None else None
+        if native_windows:
+            from .windows_job import CREATE_SUSPENDED, WindowsJob
 
+            job = WindowsJob()
+        proc = subprocess.Popen(
+            list(cmd),
+            stdout=stdout_file if stdout_file is not None else subprocess.PIPE,
+            stderr=stderr_file if stderr_file is not None else subprocess.PIPE,
+            stdin=subprocess.PIPE if input_text is not None else None,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            start_new_session=own_group,
+            env=env,
+            **({"creationflags": CREATE_SUSPENDED} if native_windows else {}),
+        )
+    except BaseException as exc:
+        if isinstance(exc, OSError):
+            exc._last30days_subproc_launch_failed = True
+        if job is not None:
+            job.close()
+        capture.close()
+        raise
     try:
-        stdout, stderr = proc.communicate(timeout=timeout)
-    except subprocess.TimeoutExpired:
-        try:
-            if hasattr(os, "killpg") and hasattr(os, "getpgid"):
-                os.killpg(os.getpgid(proc.pid), signal.SIGTERM)
-            else:
-                proc.kill()
-        except (ProcessLookupError, PermissionError, OSError, AttributeError):
-            proc.kill()
+        if native_windows:
+            from .windows_job import resume_suspended_process
+
+            try:
+                job.assign(proc._handle)
+                with _child_pids_lock:
+                    _child_pids.add(proc.pid)
+                    _child_jobs[proc.pid] = job
+                    late = _shutting_down
+                    if late:
+                        if not job.terminate():
+                            proc.kill()
+                    else:
+                        resume_suspended_process(proc.pid)
+                if late:
+                    raise SubprocTimeout("Command cancelled during shutdown")
+            except BaseException as exc:
+                if isinstance(exc, OSError):
+                    exc._last30days_subproc_launch_failed = True
+                if proc.poll() is None:
+                    try:
+                        proc.kill()
+                    except OSError:
+                        pass
+                try:
+                    proc.wait(timeout=min(cleanup_grace, 2))
+                except subprocess.TimeoutExpired:
+                    pass
+                raise
+        else:
+            register_child_pid(proc.pid)
+        if on_pid is not None:
+            try:
+                on_pid(proc.pid)
+            except Exception:
+                pass
         try:
-            proc.wait(timeout=5)
+            deadline = time.monotonic() + timeout
+            if deadline_monotonic is not None:
+                deadline = min(deadline, deadline_monotonic)
+            first = True
+            while True:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0 or (cancel is not None and cancel.is_set()):
+                    raise subprocess.TimeoutExpired(cmd, timeout)
+                try:
+                    stdout, stderr = proc.communicate(
+                        input=input_text if first else None,
+                        timeout=min(remaining, 0.05) if cancel is not None else remaining,
+                    )
+                    if deadline_monotonic is not None and time.monotonic() >= deadline_monotonic:
+                        raise subprocess.TimeoutExpired(cmd, timeout)
+                    break
+                except subprocess.TimeoutExpired:
+                    if cancel is None or time.monotonic() >= deadline or cancel.is_set():
+                        raise
+                finally:
+                    first = False
         except subprocess.TimeoutExpired:
-            # Child ignored SIGTERM (or our killpg lost the race); escalate.
-            # Guard killpg/getpgid the same way the SIGTERM path above does:
-            # they are POSIX-only and raise AttributeError on Windows. The
-            # primary path was hardened in #552; this mirrors that guard on the
-            # escalation path (added later in #433) so the same crash can't
-            # re-surface here (#588).
+            term_deadline = time.monotonic() + cleanup_grace
+            pgid = None
             try:
-                if hasattr(os, "killpg") and hasattr(os, "getpgid"):
-                    os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
-                else:
+                if own_group:
+                    pgid = proc.pid
+                    os.killpg(pgid, signal.SIGTERM)
+                elif not (_WINDOWS and _kill_windows_managed_tree(proc.pid)):
                     proc.kill()
             except (ProcessLookupError, PermissionError, OSError, AttributeError):
+                pgid = None
                 proc.kill()
             try:
-                proc.wait(timeout=5)
+                proc.wait(timeout=cleanup_grace)
+            except subprocess.TimeoutExpired:
+                # Child ignored SIGTERM (or our killpg lost the race); escalate.
+                try:
+                    if pgid is not None:
+                        os.killpg(pgid, signal.SIGKILL)
+                    elif not (_WINDOWS and _kill_windows_managed_tree(proc.pid)):
+                        proc.kill()
+                except (ProcessLookupError, PermissionError, OSError, AttributeError):
+                    proc.kill()
+                try:
+                    proc.wait(timeout=cleanup_grace)
+                except subprocess.TimeoutExpired:
+                    pass  # process unkillable (e.g. D-state); leave as zombie
+            else:
+                if pgid is not None:
+                    # Reaping the leader does not end its process group. Keep
+                    # the remaining members inside the original TERM grace.
+                    while _signal_group(pgid, 0):
+                        remaining = term_deadline - time.monotonic()
+                        if remaining <= 0:
+                            _signal_group(pgid, signal.SIGKILL)
+                            break
+                        time.sleep(min(_CLEANUP_POLL_SECONDS, remaining))
+            raise SubprocTimeout(f"Command {cmd[0]} timed out after {timeout}s")
+        if capture_limit_bytes is not None:
+            stdout_file.seek(0)
+            stderr_file.seek(0)
+            stdout = stdout_file.read(capture_limit_bytes).decode("utf-8", errors="replace")
+            stderr = stderr_file.read(capture_limit_bytes).decode("utf-8", errors="replace")
+    except SubprocTimeout:
+        raise
+    except BaseException:
+        if proc.poll() is None:
+            _kill_child_group(proc.pid, getattr(signal, "SIGKILL", signal.SIGTERM))
+            try:
+                proc.wait(timeout=cleanup_grace)
             except subprocess.TimeoutExpired:
-                pass  # process unkillable (e.g. D-state); leave as zombie
-        raise SubprocTimeout(f"Command {cmd[0]} timed out after {timeout}s")
+                pass
+        raise
+    finally:
+        unregister_child_pid(proc.pid)
+        if job is not None:
+            job.close()
+        for pipe in (proc.stdin, proc.stdout, proc.stderr):
+            if pipe is not None:
+                pipe.close()
+        capture.close()
 
     return SubprocResult(
         returncode=proc.returncode,

package/skills/trends/scripts/lib/techmeme.py

@@ -1,8 +1,8 @@
 """Techmeme tech-news source for last30days.
 
-Shells out to ``techmeme-pp-cli`` (no auth) to surface current tech-news
-headlines relevant to a topic. Techmeme caches headlines locally, so the
-adapter ensures a one-time sync per run, then searches the cache.
+Shells out to ``techmeme-pp-cli`` (no auth). The CLI's ``search`` command hits
+Techmeme's live archive search endpoint (results back to ~2005) -- it never
+reads the locally synced headline cache, so the adapter performs no ``sync``.
 
 Activation gate: only available when ``techmeme-pp-cli`` is on PATH.
 ``pipeline.available_sources`` checks ``shutil.which`` before including
@@ -11,23 +11,31 @@ Activation gate: only available when ``techmeme-pp-cli`` is on PATH.
 Surface choice: ``search "<topic>" --json`` (NOT ``--agent``). ``--agent``
 implies ``--compact``, which on older binaries stripped headline records to
 ``{}`` (fixed upstream in printing-press-library PR #1383); ``--json`` without
-``--compact`` returns the populated ``{num, source, headline, link}`` shape on
-every binary version, so the adapter is robust regardless of the installed
-build.
-
-The search shape carries no per-item date or velocity, so headlines are dated
-to the sync time (Techmeme's cache is the current news cycle) and ranked on
-topic relevance plus source quality. Publication-name header rows (very short
-``headline`` values) are dropped.
+``--compact`` returns the populated record shape on every binary version, so
+the adapter is robust regardless of the installed build.
+
+Dates: current binaries emit ``{num, source, headline, link, date}`` where
+``date`` is ISO ``YYYY-MM-DD`` (or ``""`` when Techmeme's markup was
+unparseable). The adapter windows records to the research range
+(``from_date <= date <= to_date``) so archive hits from years past never
+masquerade as current news. Records with no usable date -- old binaries emit
+no ``date`` key at all -- are kept but flow downstream with no date, so
+``normalize._normalize_techmeme`` assigns ``date_confidence: low``. Headlines
+are never stamped with today's date. (This deliberately diverges from
+``lib/arxiv.py``, which drops entries with unparseable dates -- arXiv's feed
+reliably carries dates, so an unparseable one is anomalous; Techmeme's old
+binaries emit no ``date`` key at all, so dropping would zero out the source
+for every user on an old binary.) Old binaries also print prose
+(``No results for "q"``) to stdout on zero hits; that parses as an empty
+result set, not a decode failure. Publication-name header rows (very short
+``headline`` values) are dropped; ranking is topic relevance plus rank decay.
 """
 
 from __future__ import annotations
 
 import json
+import re
 import shutil
-import threading
-import time
-from datetime import datetime, timezone
 from typing import Any, Dict, List
 
 from . import log, subproc
@@ -48,19 +56,12 @@ DEPTH_CONFIG = {
 MIN_HEADLINE_WORDS = 4
 
 SEARCH_TIMEOUT = 30
-SYNC_TIMEOUT = 40
 
-# Refresh the local cache at most once per TTL window, guarded by a lock so
-# concurrent fan-out threads do not double-sync (two processes writing the same
-# cache file). A monotonic timestamp -- not a bare bool -- so a long-lived host
-# process or multi-report fan-out re-syncs instead of serving a stale cache
-# indefinitely (headlines are dated to the sync time, so staleness would
-# misrepresent old news as current).
-_SYNC_LOCK = threading.Lock()
-_SYNC_TTL = 600.0  # seconds
-_LAST_SYNC = 0.0
-# Sentinel used by tests to force a sync regardless of the TTL window.
-_NEVER_SYNCED = float("-inf")
+# Old binaries print this prose to stdout (exit 0) on zero hits, even in JSON
+# mode. It is a zero-result response, not malformed output.
+_NO_RESULTS_PREFIX = "No results"
+
+_ISO_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
 
 
 def _log(msg: str) -> None:
@@ -72,33 +73,10 @@ def _is_available() -> bool:
     return shutil.which(CLI_BIN) is not None
 
 
-def _today_iso() -> str:
-    return datetime.now(timezone.utc).date().isoformat()
-
-
-def _ensure_synced() -> None:
-    """Refresh the local headline cache at most once per TTL window.
-
-    Lock-guarded so concurrent fan-out threads do not double-sync. Best-effort:
-    a sync failure is logged and ignored (search can still run on an existing
-    cache), and the timestamp is stamped before the call so a failing sync does
-    not retry on every subquery within the window."""
-    global _LAST_SYNC
-    with _SYNC_LOCK:
-        if time.monotonic() - _LAST_SYNC < _SYNC_TTL:
-            return
-        _LAST_SYNC = time.monotonic()  # stamp first: a failure does not retry
-        try:
-            subproc.run_with_timeout([CLI_BIN, "sync", "--agent"], timeout=SYNC_TIMEOUT)
-            _log("synced headline cache")
-        except (subproc.SubprocTimeout, FileNotFoundError, OSError) as exc:
-            _log(f"sync skipped: {exc}")
-
-
 def _build_search_args(topic: str) -> List[str]:
     # --json (not --agent) avoids --compact, which blanks headline records on
     # pre-PR-1383 binaries. Techmeme's `search` has no result-limit flag, so the
-    # depth cap is applied client-side after parsing.
+    # depth cap is applied client-side after windowing.
     return [CLI_BIN, "search", topic, "--json"]
 
 
@@ -114,6 +92,18 @@ def _coerce_list(data: Any) -> List[Dict[str, Any]]:
     return []
 
 
+def _record_iso_date(rec: Dict[str, Any]) -> str | None:
+    """The record's ``date`` as a valid ISO YYYY-MM-DD string, else None.
+
+    Old binaries emit no ``date`` key; current binaries emit ``""`` when
+    Techmeme's markup was unparseable. Anything that isn't a clean ISO date is
+    treated as absent."""
+    value = rec.get("date")
+    if isinstance(value, str) and _ISO_DATE_RE.match(value.strip()):
+        return value.strip()
+    return None
+
+
 def _run_cli(cmd: List[str], timeout: int) -> Dict[str, Any]:
     """Invoke techmeme-pp-cli and return ``{"results": [...records...]}``.
     Never raises."""
@@ -140,6 +130,10 @@ def _run_cli(cmd: List[str], timeout: int) -> Dict[str, Any]:
     stdout = result.stdout or ""
     if not stdout.strip():
         return {"results": []}
+    # Old binaries print `No results for "q"` prose (exit 0) even in JSON
+    # mode: a legitimate zero-hit response, not a decode failure.
+    if stdout.strip().startswith(_NO_RESULTS_PREFIX):
+        return {"results": []}
     try:
         data = json.loads(stdout)
     except json.JSONDecodeError as exc:
@@ -155,24 +149,55 @@ def search_techmeme(
     to_date: str,
     depth: str = "default",
 ) -> Dict[str, Any]:
-    """Search Techmeme headlines via techmeme-pp-cli.
-
-    Ensures a one-time cache sync, then searches. Returns a dict with a
-    ``results`` list of raw records. On failure, ``results`` is empty.
+    """Search Techmeme's live archive via techmeme-pp-cli.
+
+    Windows records to ``from_date..to_date`` on each record's own ISO date
+    (lexicographic compare is exact for ISO strings). Records with no usable
+    date are kept -- their recency is resolved downstream as low confidence.
+    There is deliberately no keep-all fallback when nothing is in-window:
+    Techmeme's archive reaches back decades, so zero in-window records means
+    zero results, not "serve stale news". Returns a dict with a ``results``
+    list of raw records; on failure ``results`` is empty.
     """
     if not topic or not topic.strip():
         return {"results": []}
     if not _is_available():
         return {"results": [], "error": f"{CLI_BIN} not on PATH"}
-    _ensure_synced()
     limit = DEPTH_CONFIG.get(depth, DEPTH_CONFIG["default"])
     cmd = _build_search_args(topic)
     _log(f"search '{topic}' (cap={limit})")
     response = _run_cli(cmd, timeout=SEARCH_TIMEOUT)
-    # Techmeme returns all matches; apply the depth cap client-side.
     records = response.get("results") or []
-    if isinstance(records, list) and len(records) > limit:
-        response["results"] = records[:limit]
+    if isinstance(records, list):
+        # Hard date window: drop records whose date falls outside the research
+        # range; keep undated records (old binaries / unparseable markup).
+        dated_in_window = []
+        undated = []
+        dropped = 0
+        for rec in records:
+            iso = _record_iso_date(rec)
+            if iso is None:
+                undated.append(rec)
+            elif from_date <= iso <= to_date:
+                dated_in_window.append(rec)
+            else:
+                dropped += 1
+        if dropped:
+            _log(f"dropped {dropped} records outside {from_date}..{to_date}")
+        if records and not dated_in_window and not dropped:
+            # Every record lacks a usable date: old techmeme-pp-cli (no date
+            # key) or a Techmeme markup change upstream. Windowing is inactive.
+            _log(
+                "no records carry usable dates; date windowing inactive "
+                "(old techmeme-pp-cli binary or upstream markup change; upgrade "
+                "via `npx -y @mvanhorn/printing-press-library install techmeme "
+                "--cli-only`)"
+            )
+        # Techmeme returns all matches; apply the depth cap after windowing.
+        # Dated in-window records take cap slots first so undated archive
+        # hits can never evict confirmed-fresh stories; undated records fill
+        # whatever slots remain.
+        response["results"] = (dated_in_window + undated)[:limit]
     _log(f"found {len(response.get('results') or [])} records")
     return response
 
@@ -195,16 +220,16 @@ def parse_techmeme_response(
 ) -> List[Dict[str, Any]]:
     """Parse a Techmeme search envelope into normalized item dicts.
 
-    Drops publication-name header rows and records missing a link. Dates each
-    headline to today (the cache is the current news cycle) and computes a
-    token-overlap relevance hint. Returns dicts ready for
-    ``normalize._normalize_techmeme``.
+    Drops publication-name header rows and records missing a link. Each item
+    carries the record's own ISO date, or None when the record has no usable
+    date (never today's date -- undated items get ``date_confidence: low``
+    downstream). Computes a token-overlap relevance hint. Returns dicts ready
+    for ``normalize._normalize_techmeme``.
     """
     raw = response.get("results") if isinstance(response, dict) else None
     if not isinstance(raw, list):
         return []
 
-    today = _today_iso()
     items: List[Dict[str, Any]] = []
     for i, rec in enumerate(raw):
         if not isinstance(rec, dict):
@@ -227,7 +252,7 @@ def parse_techmeme_response(
                 "title": headline,
                 "url": link,
                 "source_name": source_name,
-                "date": today,
+                "date": _record_iso_date(rec),
                 "engagement": {},
                 "relevance": round(relevance, 2),
                 "why_relevant": (