switchroom 0.18.28 → 0.18.30

package/telegram-plugin/tests/session-model-file.test.ts

@@ -17,8 +17,10 @@ import {
   readSessionModelFileRaw,
   restoreSessionModelFileRaw,
   clearSessionModelFile,
+  consumeSessionModelCarrierOnHealthyBoot,
   readConfiguredDefaultModel,
   SESSION_MODEL_FILE,
+  SESSION_MODEL_BOOT_ATTEMPTS_FILE,
   CONFIGURED_DEFAULT_MODEL_FILE,
   parseSessionEffort,
   writeSessionEffortFile,
@@ -80,6 +82,27 @@ describe('rollback snapshot (scheduleModelRelaunch dispatch failure)', () => {
   })
 })
 
+describe('consumeSessionModelCarrierOnHealthyBoot (#3284 healthy-boot consume)', () => {
+  it('deletes BOTH the carrier and the bounded-retry attempt counter', () => {
+    writeFileSync(join(dir, SESSION_MODEL_FILE), 'whatever\n')
+    writeFileSync(join(dir, SESSION_MODEL_BOOT_ATTEMPTS_FILE), '2\n')
+    consumeSessionModelCarrierOnHealthyBoot(dir)
+    expect(existsSync(join(dir, SESSION_MODEL_FILE))).toBe(false)
+    expect(existsSync(join(dir, SESSION_MODEL_BOOT_ATTEMPTS_FILE))).toBe(false)
+  })
+
+  it('is idempotent / best-effort when neither file exists (no throw)', () => {
+    expect(() => consumeSessionModelCarrierOnHealthyBoot(dir)).not.toThrow()
+    expect(existsSync(join(dir, SESSION_MODEL_FILE))).toBe(false)
+  })
+
+  it('clears the counter even when the carrier is already gone (wedge that lost its carrier mid-race)', () => {
+    writeFileSync(join(dir, SESSION_MODEL_BOOT_ATTEMPTS_FILE), '1\n')
+    consumeSessionModelCarrierOnHealthyBoot(dir)
+    expect(existsSync(join(dir, SESSION_MODEL_BOOT_ATTEMPTS_FILE))).toBe(false)
+  })
+})
+
 describe('readConfiguredDefaultModel', () => {
   it('reads the trimmed value; null when absent or empty', () => {
     expect(readConfiguredDefaultModel(dir)).toBeNull()

package/telegram-plugin/tests/turn-flush-safety.test.ts

@@ -629,6 +629,40 @@ describe('selectFlushDeliveryText — deliver the terminal answer, strip only na
     expect(selectFlushDeliveryText([])).toBe('')
   })
 
+  // #3276 guard 8 — the NARRATION_OPENER regex alone misses progress narration
+  // that does NOT open with "Let me…/I'll…" but trails off into an ellipsis or
+  // colon ("Checking now…"). Pre-fix, `isNarrationBlock` returned false for it,
+  // so the whole `narration\n\nanswer` blob was delivered. FAILS pre-fix.
+  it('strips a non-opener progress narration ("Checking now…") that precedes the answer', () => {
+    const out = selectFlushDeliveryText(['Checking now…', 'The build is green.'])
+    expect(out).toBe('The build is green.')
+    expect(out).not.toContain('Checking now')
+  })
+
+  it('strips a colon-terminated progress narration ("Pulling the numbers:")', () => {
+    const out = selectFlushDeliveryText(['Pulling the numbers:', 'Revenue was 4.2M.'])
+    expect(out).toBe('Revenue was 4.2M.')
+  })
+
+  it('still delivers a SHORT terminal answer after progress narration (no min-char re-gate)', () => {
+    // "yes, done" is well under FLUSH_SUBSTANTIVE_MIN_CHARS and MUST still deliver.
+    const out = selectFlushDeliveryText(['Looking into that...', 'yes, done'])
+    expect(out).toBe('yes, done')
+  })
+
+  // #3276 finding 7 — the narration heuristic only ever strips PRECEDING blocks;
+  // the terminal answer block is always preserved. A colon-terminated line that
+  // IS the whole answer (e.g. a lead-in the model never continued) must NOT be
+  // dropped, whether it stands alone or is the terminal block after narration.
+  it('never drops a colon-terminated line that IS the whole answer (single block)', () => {
+    expect(selectFlushDeliveryText(['Here are the results:'])).toBe('Here are the results:')
+  })
+
+  it('keeps a colon-terminated TERMINAL block (it is the answer, not narration)', () => {
+    const out = selectFlushDeliveryText(['Checking now…', 'Here are the results:'])
+    expect(out).toBe('Here are the results:')
+  })
+
   it('decideTurnFlush delivers the narrowed answer, not the whole blob', () => {
     const decision = decideTurnFlush({
       chatId: 'chat1',

package/telegram-plugin/tier-downgrade.ts

@@ -20,9 +20,10 @@
  * account-swap, never by a downgrade.
  *
  * There is NO automatic return to the premium model. The `/model` override is
- * SESSION-SCOPED and in-memory only (`recordTypedModelSwitch` writes NO carrier
- * — reference/rfcs/session-model-stickiness.md §0.1 rev 4), so it dies on the
- * downgrade SIGTERM. The downgrade writes a consume-once `.session-model`
+ * SESSION-SCOPED: rev 5 (reference/rfcs/session-model-stickiness.md §0.05) makes
+ * every switch a consume-once `.session-model` carrier relaunch, so the override
+ * dies on the downgrade SIGTERM (the carrier was consumed on its own apply-boot).
+ * The downgrade writes a consume-once `.session-model`
  * carrier for the CONFIGURED DEFAULT: start.sh applies+deletes it on the resume
  * boot, and every subsequent restart boots the configured default too. The
  * premium model is never restored on its own — the user must re-issue

package/telegram-plugin/turn-flush-safety.ts

@@ -193,8 +193,32 @@ export function selectFlushDeliveryText(blocks: string[]): string {
 const NARRATION_OPENER =
   /^(let me\b|lemme\b|i'?ll\b|i will\b|i am going to\b|i'?m going to\b|i'?m about to\b|going to\b|first,?\s+(?:let me|i'?ll|i will)\b|now,?\s+(?:let me|i'?ll|i will)\b|next,?\s+(?:let me|i'?ll|i will)\b|let'?s\b)/i
 
+/**
+ * #3276 guard 8 — the `NARRATION_OPENER` regex alone misses common progress
+ * narration that opens with a gerund/present-continuous verb and trails off
+ * into an ellipsis or colon: "Checking now…", "Pulling the numbers:",
+ * "Looking into that…". Relying on the opener regex leaked those blocks into
+ * the delivered answer. This recognises a NON-terminal narration line
+ * deterministically, WITHOUT re-gating on a min-char floor (a short real
+ * answer like "Yes, done." must still deliver): a single short line that ends
+ * with an ellipsis or a colon is progress narration, not the terminal answer.
+ *
+ * Kept conservative on purpose — only a SINGLE-line block (no internal
+ * paragraph) under the substantive floor, ending in `…` / `...` / `:`, so a
+ * genuine multi-paragraph answer that happens to end a paragraph with a colon
+ * is never mistaken for narration.
+ */
+const NARRATION_TRAILER = /(?:\.{3}|…|:)\s*$/
+
+function isTrailingNarrationLine(block: string): boolean {
+  const t = block.trim()
+  if (t.length === 0 || t.length >= FLUSH_SUBSTANTIVE_MIN_CHARS) return false
+  if (t.includes('\n')) return false
+  return NARRATION_TRAILER.test(t)
+}
+
 function isNarrationBlock(block: string): boolean {
-  return NARRATION_OPENER.test(block.trimStart())
+  return NARRATION_OPENER.test(block.trimStart()) || isTrailingNarrationLine(block)
 }
 
 export type FlushDecision =

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,