switchroom 0.18.29 → 0.18.30

package/vendor/hindsight-memory/scripts/backfill_transcripts.py

@@ -98,6 +98,12 @@ from lib.config import debug_log, load_config
 from lib.content import _is_tool_result_only_user_message
 from lib.daemon import get_api_url
 from lib.pacing import inflight_lock
+from lib.turnlog import (
+    read_candidate_turns,
+    resolve_transcript_for_turn,
+    resolve_true_bank,
+    transcript_span,
+)
 from retain import build_retain_payload, read_transcript
 
 # Injectable sleep so tests assert pacing via a fake clock, not wall time.
@@ -146,6 +152,36 @@ def _min_idle_s(override: Optional[int] = None) -> float:
         return 3600.0
 
 
+def _window_slack_s(override: Optional[int] = None) -> float:
+    """Slack (seconds) added to each side of a transcript's event span when
+    resolving the historical span-containment join (turnlog #3). Default 120s;
+    override with ``--window-slack-s`` / ``HINDSIGHT_BACKFILL_WINDOW_SLACK_S``."""
+    if override is not None:
+        return max(0, override)
+    try:
+        return max(0.0, float(os.environ.get("HINDSIGHT_BACKFILL_WINDOW_SLACK_S", "120")))
+    except ValueError:
+        return 120.0
+
+
+def _switchroom_yaml_path(agents_root: str) -> str:
+    """Path to switchroom.yaml. Override with ``HINDSIGHT_SWITCHROOM_YAML``;
+    otherwise the sibling of the agents root (``~/.switchroom/switchroom.yaml``)."""
+    override = os.environ.get("HINDSIGHT_SWITCHROOM_YAML")
+    if override:
+        return override
+    return os.path.join(os.path.dirname(os.path.normpath(agents_root)), "switchroom.yaml")
+
+
+def _registry_tmpl(agents_root: str) -> str:
+    """Template (with ``{agent}``) for a per-agent turns registry. Override with
+    ``HINDSIGHT_REGISTRY_TMPL``; default ``<agents>/{agent}/telegram/registry.db``."""
+    override = os.environ.get("HINDSIGHT_REGISTRY_TMPL")
+    if override:
+        return override
+    return os.path.join(agents_root, "{agent}", "telegram", "registry.db")
+
+
 def _is_dynamic_bank(config: dict) -> bool:
     """True when the loaded config resolves banks dynamically (per project /
     channel / user). A transcript scan cannot reliably reconstruct such a bank
@@ -338,6 +374,11 @@ class Backfill:
         min_idle_s: Optional[int] = None,
         client: Optional[HindsightClient] = None,
         progress: Optional[Progress] = None,
+        from_logs: bool = False,
+        switchroom_yaml: Optional[str] = None,
+        registry_tmpl: Optional[str] = None,
+        window_slack_s: Optional[int] = None,
+        require_direct_sessionid: bool = False,
     ):
         self.config = config
         self.commit = commit
@@ -347,6 +388,12 @@ class Backfill:
         self.agents_root = agents_root or agents_dir()
         self.min_idle_s = _min_idle_s(min_idle_s)
         self.dynamic_bank = _is_dynamic_bank(config)
+        # --from-logs (log-driven recovery) wiring.
+        self.from_logs = from_logs
+        self.switchroom_yaml = switchroom_yaml or _switchroom_yaml_path(self.agents_root)
+        self.registry_tmpl = registry_tmpl or _registry_tmpl(self.agents_root)
+        self.window_slack_ms = int(_window_slack_s(window_slack_s) * 1000)
+        self.require_direct_sessionid = require_direct_sessionid
         self.client = client
         self.progress = progress or Progress()
         self._api_url = None
@@ -473,14 +520,27 @@ class Backfill:
             "sessions": [],
         })
 
+    def _registry_path(self, agent: str) -> str:
+        return self.registry_tmpl.replace("{agent}", agent)
+
+    def _settings_path(self, agent: str) -> str:
+        return os.path.join(self.agents_root, agent, ".claude", "settings.json")
+
     def run(self, agent_filter: Optional[set] = None) -> dict:
         # F2: on a commit run, pin the id-affecting slice_turns; refuse to resume
         # a progress file written with a different value (raises ValueError).
         if self.commit:
             self.progress.ensure_slice_turns(self.slice_turns)
+        self.report["mode"] = "from_logs" if self.from_logs else "watermark"
         for agent in self._list_agents(agent_filter):
-            self._backfill_agent(agent)
-        self._finalize_report()
+            if self.from_logs:
+                self._backfill_agent_from_logs(agent)
+            else:
+                self._backfill_agent(agent)
+        if self.from_logs:
+            self._finalize_report_from_logs()
+        else:
+            self._finalize_report()
         return self.report
 
     def _backfill_agent(self, agent: str) -> None:
@@ -600,6 +660,259 @@ class Backfill:
             else:
                 self.progress.record(agent, session, "failed")
 
+    # -- from-logs (log-driven recovery) ------------------------------------ #
+    def _logs_agent_report(self, agent: str) -> dict:
+        return self.report["agents"].setdefault(agent, {
+            "bank_id": None,
+            "bank_refused": False,
+            "refuse_reason": None,
+            "candidate_turns": 0,
+            "candidate_sessions": 0,
+            "ambiguous_turns": 0,
+            "unmatched_turns": 0,
+            "sessions_has_documents": 0,
+            "sessions_total_loss": 0,
+            "sessions_membership_error": 0,
+            "sessions_active_skipped": 0,
+            "sessions_already_done": 0,
+            "sessions_restored": 0,
+            "slices_restored": 0,
+            "turns_recovered": 0,
+            "posts_ok": 0,
+            "posts_failed": 0,
+            "sessions": [],
+        })
+
+    def _session_membership(self, bank_id: str, session_id: str) -> str:
+        """SESSION-LEVEL, id-scheme-AGNOSTIC membership (BLOCKER-1 fix).
+
+        Returns ``"present"`` when the bank holds ANY document belonging to the
+        session, ``"absent"`` when it holds NONE (true total loss), or
+        ``"error"`` on any query failure (caller fails CLOSED — treats it as
+        present ⇒ skip, never restores on uncertainty).
+
+        We deliberately do NOT compare against the tool's ``-r{uuid}`` slice ids:
+        the deployed production banks are keyed with the LEGACY
+        ``{session_id}-{epoch_ms}`` scheme (``retain.py``'s not-yet-live
+        ``slice_document_id`` at line ~430 is the replacement), so an exact slice
+        id set would never match a legacy doc → every slice looks "missing" →
+        every intact session gets duplicated. Presence is decided by the id
+        PREFIX ``{session_id}`` which BOTH schemes share (``{session_id}-...``
+        legacy/new, or the bare ``{session_id}`` chunk-0 id). Restore fires ONLY
+        for a session with ZERO documents — so partial-within-a-populated-session
+        recovery is OUT OF SCOPE on legacy banks (we cannot tell WHICH turns a
+        legacy epoch-ms id covers) and can only be added once the ``-r{uuid}``
+        scheme is deployed and banks are re-keyed.
+
+        The GET is paced through the shared inflight lock so must-fix #1's broad
+        candidate set can never create a read storm (should-fix 4b)."""
+        client = self._ensure_client()
+        if client is None:
+            return "error"
+        self._pace_before_post()
+        try:
+            with inflight_lock(blocking=True) as acquired:
+                if not acquired:  # pragma: no cover - blocking acquire fails open
+                    return "error"
+                ids = client.list_session_document_ids(bank_id, session_id)
+        except Exception as e:
+            debug_log(self.config, f"backfill(from-logs): membership query failed "
+                                   f"for {session_id}: {e} — failing closed (skip)")
+            return "error"
+        finally:
+            # A membership GET counts toward pacing state just like a POST.
+            self._posted_count += 1
+            self._post_times.append(time.monotonic())
+        prefix = f"{session_id}-"
+        for did in ids:
+            if isinstance(did, str) and (did == session_id or did.startswith(prefix)):
+                return "present"
+        return "absent"
+
+    def _backfill_agent_from_logs(self, agent: str) -> None:
+        ar = self._logs_agent_report(agent)
+
+        # Correct-bank targeting: resolve TRUE bank or REFUSE (zero writes).
+        res = resolve_true_bank(
+            agent,
+            switchroom_yaml_path=self.switchroom_yaml,
+            settings_path=self._settings_path(agent),
+        )
+        if not res.ok:
+            ar["bank_refused"] = True
+            ar["refuse_reason"] = res.reason
+            print(f"[Hindsight] backfill(from-logs): REFUSING {agent} — {res.reason} "
+                  f"(no writes).", file=sys.stderr)
+            return
+        bank_id = res.bank_id
+        ar["bank_id"] = bank_id
+
+        # BROAD candidate classifier over the durable turn-lifecycle log.
+        turns = read_candidate_turns(self._registry_path(agent))
+        ar["candidate_turns"] = len(turns)
+        if not turns:
+            return
+
+        # Event-span containment join (must-fix #3).
+        spans = [transcript_span(p) for p in self._agent_transcripts(agent)]
+        sessions: dict = {}
+        for t in turns:
+            jr = resolve_transcript_for_turn(
+                t, spans,
+                slack_ms=self.window_slack_ms,
+                require_direct_sessionid=self.require_direct_sessionid,
+            )
+            if jr.kind in ("span", "direct") and jr.session_id:
+                sessions.setdefault(jr.session_id, {"path": jr.transcript_path, "join": jr.kind})
+            elif jr.kind == "ambiguous":
+                ar["ambiguous_turns"] += 1
+                ar["sessions"].append({"turn_key": t.turn_key, "class": "ambiguous",
+                                       "action": "refused", "detail": jr.detail})
+            else:
+                ar["unmatched_turns"] += 1
+        ar["candidate_sessions"] = len(sessions)
+
+        now = time.time()
+        for session, info in sessions.items():
+            path = info["path"]
+
+            if self.progress.is_done(agent, session):
+                ar["sessions_already_done"] += 1
+                continue
+
+            # Never touch an ACTIVE / recently-written session.
+            try:
+                idle = now - os.path.getmtime(path)
+            except OSError:
+                continue
+            if idle < self.min_idle_s:
+                ar["sessions_active_skipped"] += 1
+                ar["sessions"].append({"session": session, "class": "active",
+                                       "action": "skipped_recent", "idle_s": round(idle, 1)})
+                continue
+
+            # SESSION-LEVEL, scheme-agnostic membership (BLOCKER-1 fix): restore
+            # ONLY a session the bank has ZERO documents for (true total loss).
+            # A session with ANY doc (legacy epoch-ms OR new -r{uuid} scheme) is
+            # PRESENT ⇒ skipped — we cannot safely fill a partial tail on a
+            # legacy-keyed bank without duplicating the intact head. Fail CLOSED
+            # (error ⇒ treated present ⇒ skip).
+            membership = self._session_membership(bank_id, session)
+            if membership == "error":
+                ar["sessions_membership_error"] += 1
+                ar["sessions"].append({"session": session, "class": "membership_error",
+                                       "join": info["join"], "action": "skipped_fail_closed"})
+                continue
+            if membership == "present":
+                ar["sessions_has_documents"] += 1
+                ar["sessions"].append({"session": session, "class": "has_documents",
+                                       "join": info["join"], "action": "skip_has_documents"})
+                continue
+
+            # membership == "absent" → true total loss → restore the whole session.
+            messages = read_transcript(path)
+            if not messages:
+                continue
+            slices = chunk_by_human_turns(messages, self.slice_turns)
+            if not slices:
+                continue
+            built_slices = []
+            for sl in slices:
+                built = build_retain_payload(
+                    self.config, session, sl, messages,
+                    bank_id=bank_id, api_url=self._api_url or "http://backfill-client",
+                    api_token=self._api_token, retain_full_window=True, document_id=None,
+                )
+                if built is not None:
+                    built_slices.append((built, sl))
+            if not built_slices:
+                continue
+
+            total = len(built_slices)
+            n_turns = sum(len(_human_turn_indices(sl)) for _, sl in built_slices)
+            ar["sessions_total_loss"] += 1
+
+            session_entry = {
+                "session": session, "class": "total_loss",
+                "join": info["join"], "bank_id": bank_id,
+                "slices": total, "turns": n_turns,
+                "document_ids": [b["document_id"] for b, _ in built_slices],
+                "action": None,
+            }
+
+            if not self.commit:
+                # Dry-run: build-only, ZERO writes. Report the gap it WOULD fill.
+                session_entry["action"] = "would_restore"
+                ar["turns_recovered"] += n_turns
+                ar["slices_restored"] += total
+                ar["sessions"].append(session_entry)
+                continue
+
+            all_ok = True
+            last_built = None
+            for built, _ in built_slices:
+                if self._post_slice(bank_id, built):
+                    ar["posts_ok"] += 1
+                    ar["slices_restored"] += 1
+                    last_built = built
+                else:
+                    ar["posts_failed"] += 1
+                    all_ok = False
+
+            if all_ok and last_built is not None:
+                ar["sessions_restored"] += 1
+                ar["turns_recovered"] += n_turns
+                session_entry["action"] = "restored"
+                # Advance the live watermark so the agent's own boot reconcile
+                # sees the tail as committed.
+                try:
+                    watermark.commit(
+                        session, last_built["last_uuid"], last_built["document_id"],
+                        transcript_path=path, ordered_uuids=last_built["ordered_uuids"],
+                    )
+                except Exception:  # pragma: no cover - defensive
+                    pass
+                self.progress.record(agent, session, "done", slices=total, turns=n_turns)
+            else:
+                session_entry["action"] = "restore_failed"
+                self.progress.record(agent, session, "failed")
+            ar["sessions"].append(session_entry)
+
+    def _finalize_report_from_logs(self) -> None:
+        roll = {
+            "mode": "from_logs",
+            "agents": len(self.report["agents"]),
+            "banks_refused": 0,
+            "candidate_turns": 0,
+            "candidate_sessions": 0,
+            "ambiguous_turns": 0,
+            "unmatched_turns": 0,
+            "sessions_has_documents": 0,
+            "sessions_total_loss": 0,
+            "sessions_membership_error": 0,
+            "sessions_active_skipped": 0,
+            "sessions_already_done": 0,
+            "sessions_restored": 0,
+            "slices_restored": 0,
+            "turns_recovered": 0,
+            "posts_ok": 0,
+            "posts_failed": 0,
+            "slice_turns": self.slice_turns,
+            "committed": self.commit,
+        }
+        for ar in self.report["agents"].values():
+            if ar.get("bank_refused"):
+                roll["banks_refused"] += 1
+            for k in (
+                "candidate_turns", "candidate_sessions", "ambiguous_turns",
+                "unmatched_turns", "sessions_has_documents", "sessions_total_loss",
+                "sessions_membership_error", "sessions_active_skipped",
+                "sessions_already_done", "sessions_restored", "slices_restored",
+                "turns_recovered", "posts_ok", "posts_failed",
+            ):
+                roll[k] += ar.get(k, 0)
+        self.report["rollup"] = roll
+
     def _finalize_report(self) -> None:
         roll = {
             "agents": len(self.report["agents"]),
@@ -631,7 +944,68 @@ class Backfill:
 # --------------------------------------------------------------------------- #
 # Reporting / CLI.
 # --------------------------------------------------------------------------- #
+def format_report_from_logs(report: dict) -> str:
+    roll = report.get("rollup", {})
+    mode = "COMMIT" if roll.get("committed") else "DRY-RUN (no writes)"
+    lines = [f"[Hindsight] log-driven recovery report — {mode}", ""]
+    for agent in sorted(report.get("agents", {})):
+        ar = report["agents"][agent]
+        if ar.get("bank_refused"):
+            lines.append(f"  {agent}: BANK REFUSED — {ar.get('refuse_reason')} (no writes)")
+            continue
+        lines.append(
+            f"  {agent} [bank={ar.get('bank_id')}]: "
+            f"cand_turns={ar['candidate_turns']} cand_sessions={ar['candidate_sessions']} "
+            f"ambiguous={ar['ambiguous_turns']} unmatched={ar['unmatched_turns']} "
+            f"has_documents={ar['sessions_has_documents']} "
+            f"total_loss={ar['sessions_total_loss']} "
+            f"membership_err={ar['sessions_membership_error']} "
+            f"active_skip={ar['sessions_active_skipped']} "
+            f"already_done={ar['sessions_already_done']} "
+            f"restored={ar['sessions_restored']} "
+            f"slices_restored={ar['slices_restored']} "
+            f"turns={ar['turns_recovered']} "
+            f"posts_ok={ar['posts_ok']} posts_failed={ar['posts_failed']}"
+        )
+        for s in ar.get("sessions", []):
+            if s.get("class") in ("total_loss", "membership_error", "ambiguous"):
+                lines.append(
+                    f"      - {s.get('session', s.get('turn_key'))} [{s.get('class')}] "
+                    f"join={s.get('join', '-')} "
+                    f"slices={s.get('slices', '-')} "
+                    f"action={s.get('action')} {s.get('detail', '')}".rstrip()
+                )
+    lines.append("")
+    lines.append(
+        f"  ROLLUP: agents={roll.get('agents', 0)} "
+        f"banks_refused={roll.get('banks_refused', 0)} "
+        f"candidate_sessions={roll.get('candidate_sessions', 0)} "
+        f"ambiguous={roll.get('ambiguous_turns', 0)} "
+        f"has_documents(skipped)={roll.get('sessions_has_documents', 0)} "
+        f"total_loss={roll.get('sessions_total_loss', 0)} "
+        f"membership_err={roll.get('sessions_membership_error', 0)} "
+        f"restored={roll.get('sessions_restored', 0)} "
+        f"slices_restored={roll.get('slices_restored', 0)} "
+        f"turns_would_recover={roll.get('turns_recovered', 0)} "
+        f"posts_ok={roll.get('posts_ok', 0)} posts_failed={roll.get('posts_failed', 0)}"
+    )
+    lines.append("  NOTE: recovers only ZERO-document (total-loss) sessions. "
+                 "Partial-tail recovery within a populated session is OUT OF SCOPE "
+                 "on legacy epoch-ms banks (needs the -r{uuid} id scheme deployed).")
+    if not roll.get("committed"):
+        est_posts = roll.get("slices_restored", 0)
+        delay_ms = _delay_ms()
+        est_secs = est_posts * (delay_ms / 1000.0)
+        lines.append(
+            f"  ESTIMATE (at {delay_ms}ms/post): ~{est_posts} restore POSTs, "
+            f"~{est_secs:.0f}s wall-clock. Re-run with --commit --agent <name> to write."
+        )
+    return "\n".join(lines)
+
+
 def format_report(report: dict) -> str:
+    if report.get("mode") == "from_logs" or report.get("rollup", {}).get("mode") == "from_logs":
+        return format_report_from_logs(report)
     roll = report.get("rollup", {})
     mode = "COMMIT" if roll.get("committed") else "DRY-RUN (no writes)"
     lines = [f"[Hindsight] backfill report — {mode}", ""]
@@ -707,6 +1081,24 @@ def main(argv=None) -> int:
     parser.add_argument("--min-idle-s", type=int, default=None,
                         help="Skip sessions whose transcript was modified within this many seconds "
                              "(treated as active/in-flight). Default 3600.")
+    parser.add_argument("--from-logs", action="store_true", dest="from_logs",
+                        help="Log-driven recovery mode: narrow candidate sessions via the per-agent "
+                             "turns registry, then restore ONLY sessions the agent's true bank has ZERO "
+                             "documents for (session-level, scheme-agnostic total-loss gate). "
+                             "Partial-tail recovery within a populated session is OUT OF SCOPE on legacy "
+                             "epoch-ms banks (needs the -r{uuid} id scheme deployed).")
+    parser.add_argument("--switchroom-yaml", default=None,
+                        help="Path to switchroom.yaml for true-bank resolution (--from-logs). "
+                             "Default: sibling of the agents dir.")
+    parser.add_argument("--registry-tmpl", default=None,
+                        help="Template (with {agent}) for a per-agent turns registry.db (--from-logs). "
+                             "Default: <agents>/{agent}/telegram/registry.db")
+    parser.add_argument("--window-slack-s", type=int, default=None,
+                        help="Slack (seconds) on each side of a transcript event-span for the "
+                             "historical containment join (--from-logs). Default 120.")
+    parser.add_argument("--require-direct-sessionid", action="store_true",
+                        help="Refuse any turn without a stamped session_id rather than use the "
+                             "span-containment join (strict, going-forward-only; --from-logs).")
     parser.add_argument("--json", action="store_true", help="Emit the machine-readable report as JSON.")
     args = parser.parse_args(argv)
 
@@ -736,6 +1128,11 @@ def main(argv=None) -> int:
             max_per_min=args.max_per_min,
             agents_root=args.agents_dir,
             min_idle_s=args.min_idle_s,
+            from_logs=args.from_logs,
+            switchroom_yaml=args.switchroom_yaml,
+            registry_tmpl=args.registry_tmpl,
+            window_slack_s=args.window_slack_s,
+            require_direct_sessionid=args.require_direct_sessionid,
         )
         agent_filter = set(args.agents) if args.agents else None
         try:

package/vendor/hindsight-memory/scripts/lib/client.py

@@ -206,6 +206,53 @@ class HindsightClient:
         }
         return self._request("POST", path, body, timeout=timeout)
 
+    def list_session_document_ids(
+        self,
+        bank_id: str,
+        session_id: str,
+        page: int = 200,
+        max_pages: int = 50,
+        timeout: int = 10,
+    ) -> set:
+        """Return the set of document ids in ``bank_id`` whose id contains
+        ``session_id`` (switchroom #3244 log-driven recovery, session-level
+        membership).
+
+        Uses the daemon's server-side ``q=`` filter — a case-insensitive
+        substring match on the document id (``GET .../documents?q=...``,
+        ``http.py:api_list_documents``). Every per-turn transcript retain the
+        live path OR this backfill ever wrote for a session carries the session
+        id as an id prefix — BOTH the legacy ``{session_id}-{epoch_ms}`` scheme
+        (what production banks hold today) and the new ``{session_id}-r{uuid}``
+        scheme — so this ONE server-side query (paged, bounded by ``max_pages``)
+        returns exactly this session's docs without a per-slice GET storm. The
+        caller tests the returned ids for the ``{session_id}`` PREFIX (scheme-
+        agnostic) to decide presence: ANY doc ⇒ present ⇒ skip; ZERO ⇒
+        total-loss ⇒ restore.
+
+        Raises on any HTTP/transport error so the caller can fail CLOSED (treat
+        the session as PRESENT ⇒ skip) and never risk a duplicate restore.
+        """
+        found: set = set()
+        offset = 0
+        q = urllib.parse.quote(session_id, safe="")
+        bank = urllib.parse.quote(bank_id, safe="")
+        for _ in range(max(1, max_pages)):
+            path = (
+                f"/v1/default/banks/{bank}/documents"
+                f"?q={q}&limit={int(page)}&offset={int(offset)}"
+            )
+            resp = self._request("GET", path, timeout=timeout)
+            items = resp.get("items") or []
+            for it in items:
+                did = it.get("id") if isinstance(it, dict) else None
+                if did:
+                    found.add(did)
+            if len(items) < page:
+                break
+            offset += page
+        return found
+
     def list_directives(
         self,
         bank_id: str,

package/vendor/hindsight-memory/scripts/lib/content.py

@@ -255,7 +255,13 @@ def format_memories(results: list) -> str:
         mem_type = r.get("type", "")
         mentioned_at = r.get("mentioned_at", "")
         type_str = f" [{mem_type}]" if mem_type else ""
-        date_str = f" ({mentioned_at})" if mentioned_at else ""
+        # switchroom #tz-fix (recall side): mentioned_at arrives as a UTC ISO
+        # timestamp from the Hindsight server. Render it through the same
+        # SWITCHROOM_TIMEZONE→TZ→UTC zoneinfo conversion as format_current_time
+        # so recall lines never inject a UTC "when". Date-only / unparseable
+        # values are surfaced verbatim rather than crashing recall.
+        display_at = _format_local_timestamp(mentioned_at) if mentioned_at else ""
+        date_str = f" ({display_at})" if display_at else ""
         lines.append(f"- {text}{type_str}{date_str}")
     return "\n\n".join(lines)
 
@@ -271,6 +277,52 @@ def _resolve_agent_timezone() -> str:
     return os.environ.get("SWITCHROOM_TIMEZONE") or os.environ.get("TZ") or "UTC"
 
 
+def _format_local_timestamp(value: str) -> str:
+    """Render a UTC ISO timestamp in the agent's LOCAL timezone (am/pm form).
+
+    Used by ``format_memories`` to convert the server-supplied ``mentioned_at``
+    (UTC ISO, e.g. ``2026-07-16T04:09:00Z``) through the same
+    SWITCHROOM_TIMEZONE→TZ→UTC zoneinfo cascade as ``format_current_time``,
+    so recalled memories never surface a UTC "when".
+
+    Guarding: only full ISO *datetime* values (those carrying a time component,
+    i.e. containing ``T``) are converted. Date-only strings (``2024-01-01``) and
+    anything unparseable are returned verbatim rather than crashing recall or
+    fabricating a midnight time.
+    """
+    if not isinstance(value, str):
+        return value
+    raw = value.strip()
+    # Only convert full ISO datetimes — a bare date has no wall-clock to shift.
+    if "T" not in raw:
+        return value
+    parsed = None
+    try:
+        # Python <3.11 fromisoformat rejects a trailing 'Z'; normalise it.
+        iso = raw[:-1] + "+00:00" if raw.endswith("Z") else raw
+        parsed = datetime.fromisoformat(iso)
+    except (ValueError, TypeError):
+        return value
+    # Naive value → server sends UTC, so assume UTC before converting.
+    if parsed.tzinfo is None:
+        if ZoneInfo is not None:
+            try:
+                parsed = parsed.replace(tzinfo=ZoneInfo("UTC"))
+            except Exception:
+                return value
+        else:
+            return value
+    tz_name = _resolve_agent_timezone()
+    if ZoneInfo is not None:
+        try:
+            local = parsed.astimezone(ZoneInfo(tz_name))
+        except Exception:  # unknown/invalid zone — degrade to process-local.
+            local = parsed.astimezone()
+    else:
+        local = parsed.astimezone()
+    return local.strftime("%Y-%m-%d %I:%M %p %Z")
+
+
 def format_current_time() -> str:
     """Format the current time in the agent's LOCAL timezone for recall context.