switchroom 0.18.24 → 0.18.26

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

@@ -72,7 +72,18 @@ def _budget_seconds() -> float:
 
 
 def _retry_one(entry: dict, timeout: int) -> None:
-    """POST a single queued retain. Raises on failure."""
+    """POST a single queued retain. Raises on failure.
+
+    Posts ``async_processing=False`` (commit-before-ack, switchroom #3244 §1.1):
+    the drain is a DURABILITY path — it deletes the pending entry on a 200, so
+    the 200 must prove durable persistence, not merely ack-of-receipt. A bare
+    async 200 followed by a dropped extraction would delete the queue entry
+    while the content never lands, and (for boot-reconcile remainders whose
+    watermark already advanced) there is no reconcile backstop — silent loss
+    (the #3244 bug). All drained entries — Stop-hook A2 failures, SessionEnd
+    failures, and reconcile-remainder deferrals — are durability retries, so
+    sync is correct for every one.
+    """
     client = HindsightClient(entry["api_url"], entry.get("api_token"))
     client.retain(
         bank_id=entry["bank_id"],
@@ -82,6 +93,7 @@ def _retry_one(entry: dict, timeout: int) -> None:
         metadata=entry.get("metadata") or {},
         tags=entry.get("tags"),
         timeout=timeout,
+        async_processing=False,
     )
 
 

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

@@ -173,12 +173,22 @@ class HindsightClient:
         metadata: Optional[dict] = None,
         tags: Optional[list] = None,
         timeout: int = 15,
+        async_processing: bool = True,
     ) -> dict:
         """Retain content into a bank's memory.
 
-        Posts with async=true so the server processes in the background.
-        The context field helps Hindsight cluster memories by provenance
-        (e.g. "claude-code" vs manual retains).
+        By default posts with ``async=true`` so the server processes extraction
+        in the background (a 200 is an ack-of-receipt, not proof of durable
+        persistence). The context field helps Hindsight cluster memories by
+        provenance (e.g. "claude-code" vs manual retains).
+
+        ``async_processing=False`` (switchroom #3244 §1.1) posts ``async=false``
+        so the 200 is returned only after the daemon has durably committed the
+        item — commit-before-ack. Durability paths whose success advances the
+        retain watermark (the Stop-hook durability retain and boot
+        reconciliation) MUST use this so a bare async 200 can never falsely mark
+        unpersisted work as committed. (Merge precondition: the daemon honours
+        ``async=false`` as commit-before-ack — verified by the §1.1 probe.)
         """
         path = f"/v1/default/banks/{urllib.parse.quote(bank_id, safe='')}/memories"
         item = {
@@ -192,7 +202,7 @@ class HindsightClient:
             item["tags"] = tags
         body = {
             "items": [item],
-            "async": True,
+            "async": bool(async_processing),
         }
         return self._request("POST", path, body, timeout=timeout)
 

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

@@ -95,6 +95,12 @@ DEFAULTS = {
     "retainContext": "claude-code",
     "retainTags": [],
     "retainMetadata": {},
+    # Switchroom #3244 — boot reconciliation of un-committed transcript tails.
+    # On by default; the load-bearing recovery for work an abrupt session death
+    # (SIGKILL/OOM/watchdog) skipped. Disable per-agent via
+    # HINDSIGHT_RECONCILE_ON_START=false. reconcile_tail.py also honours the
+    # HINDSIGHT_RECONCILE_{LOOKBACK_H,MAX_TURNS,BUDGET_S} bounds (read directly).
+    "reconcileOnStart": True,
     "recallAdditionalBanks": [],
     # Connection
     "hindsightApiUrl": None,
@@ -134,6 +140,8 @@ ENV_OVERRIDES = {
     "HINDSIGHT_AUTO_RECALL": ("autoRecall", bool),
     "HINDSIGHT_AUTO_RETAIN": ("autoRetain", bool),
     "HINDSIGHT_RETAIN_MODE": ("retainMode", str),
+    # Switchroom #3244 — boot reconciliation on/off (default on).
+    "HINDSIGHT_RECONCILE_ON_START": ("reconcileOnStart", bool),
     "HINDSIGHT_RECALL_BUDGET": ("recallBudget", str),
     "HINDSIGHT_RECALL_MAX_TOKENS": ("recallMaxTokens", int),
     # Switchroom-local: count cap. Set by start.sh from

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

@@ -0,0 +1,102 @@
+"""Shared fleet pacing lock for Hindsight retain POSTs (switchroom #3244 §1.5).
+
+A single per-agent advisory flock, ``$HOME/.hindsight/retain-inflight.lock``,
+serialises the durability-path retain POSTs so at most ONE is in flight for an
+agent at a time — covering the live Stop-hook retain, boot reconciliation, and
+(PR2) the one-time backfill collectively. This is the "never storm the daemon"
+guard.
+
+Usage::
+
+    from lib.pacing import inflight_lock
+
+    with inflight_lock(blocking=False) as acquired:
+        if not acquired:
+            ...  # someone else holds it — enqueue and return, do NOT wait
+        client.retain(...)
+
+* Boot reconcile / backfill acquire it **blocking** (they are batch work and
+  should wait their turn).
+* The live Stop hook acquires it **non-blocking** (``blocking=False``): if a
+  reconcile/backfill holds it the live retain must NOT wait (turn latency must
+  not regress) — the caller enqueues its payload to ``pending-retains/`` and
+  returns, and the next boot drain delivers it.
+
+The context manager yields ``True`` when the lock was acquired (and releases it
+on exit) and ``False`` when a non-blocking acquire failed (nothing to release).
+It never raises on lock-infrastructure errors: if flock is unavailable it
+fails OPEN (yields ``True``) so durability is never blocked by the lock itself.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import sys
+from typing import Iterator
+
+if sys.platform != "win32":
+    import fcntl
+else:  # pragma: no cover - switchroom agents are Linux only
+    fcntl = None
+
+
+def lock_path() -> str:
+    """Path of the shared inflight lock. Override with ``HINDSIGHT_INFLIGHT_LOCK``."""
+    override = os.environ.get("HINDSIGHT_INFLIGHT_LOCK")
+    if override:
+        return override
+    return os.path.join(os.path.expanduser("~"), ".hindsight", "retain-inflight.lock")
+
+
+@contextlib.contextmanager
+def inflight_lock(blocking: bool = True) -> Iterator[bool]:
+    """Acquire the shared inflight lock.
+
+    Yields ``True`` if acquired (released on exit), ``False`` if a non-blocking
+    acquire could not get it. Fails OPEN (yields ``True``, no real lock) when
+    flock is unavailable so the durability path is never blocked by lock
+    infrastructure.
+    """
+    if fcntl is None:
+        yield True
+        return
+
+    path = lock_path()
+    d = os.path.dirname(path)
+    try:
+        if d and not os.path.isdir(d):
+            os.makedirs(d, mode=0o700, exist_ok=True)
+    except OSError:
+        # Can't even create the dir — fail open rather than block durability.
+        yield True
+        return
+
+    lock_fd = None
+    acquired = False
+    try:
+        lock_fd = open(path, "w")
+        flags = fcntl.LOCK_EX | (0 if blocking else fcntl.LOCK_NB)
+        try:
+            fcntl.flock(lock_fd, flags)
+            acquired = True
+        except OSError:
+            if blocking:
+                # A blocking acquire that errored (not a would-block) — fail
+                # open so batch work still makes progress.
+                acquired = True
+            else:
+                acquired = False
+        yield acquired
+    except OSError:
+        # Could not open the lock file at all — fail open.
+        yield True
+        return
+    finally:
+        if lock_fd is not None:
+            try:
+                if acquired:
+                    fcntl.flock(lock_fd, fcntl.LOCK_UN)
+            except OSError:
+                pass
+            lock_fd.close()

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

@@ -0,0 +1,213 @@
+"""Durable per-session retain watermark (switchroom #3244).
+
+Records, per ``(agent, session_id)``, the identity of the last transcript
+entry that has been *confirmed* committed to the Hindsight bank. This is the
+fact-on-disk that boot reconciliation (``reconcile_tail.py``) diffs against
+the surviving ``.jsonl`` transcript to recover work an abrupt session death
+(SIGKILL / OOM / watchdog) would otherwise silently drop.
+
+Design (design-20260715.md §1.1):
+
+* **Key = the message ``uuid`` of the last committed transcript entry.** Not
+  a turn ordinal (compaction re-indexes) and not a byte offset (shifts on
+  compaction); the ``uuid`` Claude Code stamps on every ``.jsonl`` entry is
+  stable across compaction and unambiguous. A ``byte_offset_hint`` is stored
+  as a fast-path only and never trusted alone.
+* **Advance ONLY on confirmed persistence.** ``commit()`` is called only after
+  a retain POST the caller made with commit-before-ack semantics
+  (``async_processing=False``) returned ok. A watermark that is *behind*
+  reality is safe (the reconciler re-POSTs, which upserts idempotently on the
+  deterministic ``document_id``); a watermark *ahead* of reality would skip
+  real work, so we never write it speculatively.
+* **Never moves backward.** ``commit()`` compares the incoming ``last_uuid``'s
+  position against the stored one *in the current transcript*; a stored uuid
+  that compaction removed is treated as stale (accept the incoming commit) —
+  a lost anchor can only cause a safe re-upsert, never a skip.
+* **Atomic + flock.** ``write tmp -> fsync -> os.replace`` under an exclusive
+  flock (mirrors ``lib/state.py`` / ``lib/pending.py``) so a concurrent async
+  Stop hook and a SessionEnd force-retain writing the same session serialize
+  and never observe a torn file.
+
+Location: ``$HOME/.hindsight/retained/<session_id>.json`` — same
+container-lifetime persistence semantics as ``pending-retains/``. Losing it on
+container recreate is safe: no watermark => the reconciler treats the bounded
+transcript tail as the gap and re-upserts.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from typing import Optional
+
+if sys.platform != "win32":
+    import fcntl
+else:  # pragma: no cover - switchroom agents are Linux only
+    fcntl = None
+
+SCHEMA = 1
+
+
+def watermark_dir() -> str:
+    """Return the retained-watermark directory.
+
+    Override with ``HINDSIGHT_RETAINED_DIR`` (tests). Default:
+    ``$HOME/.hindsight/retained/``.
+    """
+    override = os.environ.get("HINDSIGHT_RETAINED_DIR")
+    if override:
+        return override
+    return os.path.join(os.path.expanduser("~"), ".hindsight", "retained")
+
+
+def _ensure_dir() -> str:
+    d = watermark_dir()
+    if not os.path.isdir(d):
+        os.makedirs(d, mode=0o700, exist_ok=True)
+    else:
+        try:
+            mode = os.stat(d).st_mode & 0o777
+            if mode != 0o700:
+                os.chmod(d, 0o700)
+        except OSError:
+            pass
+    return d
+
+
+def _safe_session(session_id: str) -> str:
+    """Sanitise a session id for use as a filename (no path traversal)."""
+    keep = [c if (c.isalnum() or c in "-_.") else "_" for c in (session_id or "unknown")]
+    name = "".join(keep)[:200]
+    # Never allow a name that resolves to a traversal component.
+    return name.replace("..", "_") or "unknown"
+
+
+def _path(session_id: str) -> str:
+    return os.path.join(watermark_dir(), f"{_safe_session(session_id)}.json")
+
+
+def _lock_path(session_id: str) -> str:
+    return os.path.join(watermark_dir(), f"{_safe_session(session_id)}.lock")
+
+
+def load(session_id: str) -> Optional[dict]:
+    """Return the stored watermark dict for ``session_id``, or ``None``."""
+    p = _path(session_id)
+    if not os.path.isfile(p):
+        return None
+    try:
+        with open(p, encoding="utf-8") as f:
+            return json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def _atomic_write(session_id: str, entry: dict) -> None:
+    d = _ensure_dir()
+    final = os.path.join(d, f"{_safe_session(session_id)}.json")
+    tmp = final + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(entry, f, ensure_ascii=False)
+        f.flush()
+        os.fsync(f.fileno())
+    os.chmod(tmp, 0o600)
+    os.replace(tmp, final)
+
+
+def _would_regress(stored: Optional[dict], last_uuid: str, ordered_uuids) -> bool:
+    """True if committing ``last_uuid`` would move the watermark BACKWARD.
+
+    Uses the position of each uuid *in the current transcript* (``ordered_uuids``,
+    transcript order). Explicit stale-anchor branch (design §1.1): if the stored
+    ``last_uuid`` is not present in the current transcript it was compacted away
+    and cannot be positionally compared — treat the stored watermark as stale and
+    accept the incoming commit (never a skip, at worst a safe re-upsert).
+    """
+    if not stored:
+        return False
+    stored_uuid = stored.get("last_uuid")
+    if not stored_uuid or stored_uuid == last_uuid:
+        # No stored anchor, or an idempotent re-commit of the same anchor —
+        # neither is a backward move.
+        return False
+    if not ordered_uuids:
+        # Without transcript ordering we cannot prove regression; accept
+        # (safety leans toward re-upsert, never skip).
+        return False
+    try:
+        stored_idx = ordered_uuids.index(stored_uuid)
+    except ValueError:
+        # Stored anchor compacted away -> stale -> accept incoming.
+        return False
+    try:
+        incoming_idx = ordered_uuids.index(last_uuid)
+    except ValueError:
+        # Incoming uuid not in transcript (shouldn't happen); accept.
+        return False
+    # Regress only if the stored anchor is strictly AHEAD of the incoming one.
+    return stored_idx > incoming_idx
+
+
+def commit(
+    session_id: str,
+    last_uuid: str,
+    document_id: str,
+    transcript_path: str = "",
+    ordered_uuids=None,
+    byte_offset_hint: Optional[int] = None,
+) -> Optional[dict]:
+    """Advance the watermark for ``session_id`` to ``last_uuid``.
+
+    Refuses to move backward (see ``_would_regress``). Returns the persisted
+    watermark dict, or the existing one if the commit was a no-op (regression /
+    idempotent). Best-effort: a write failure returns ``None`` and never raises
+    — a successful retain must never be failed by a watermark write.
+
+    ``ordered_uuids`` is the list of transcript entry uuids in transcript order,
+    used for the monotonic comparison; the caller (retain / reconcile) has the
+    transcript in hand.
+    """
+    if not last_uuid:
+        # Nothing to anchor on (legacy/flat transcript with no uuids). We do
+        # not persist a uuid-less watermark: the reconciler falls back to
+        # treating the bounded tail as the gap, which upserts idempotently.
+        return None
+    lock_path = _lock_path(session_id)
+    entry = {
+        "schema": SCHEMA,
+        "session_id": session_id,
+        "last_uuid": last_uuid,
+        "last_document_id": document_id,
+        "committed_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "transcript_path": transcript_path,
+    }
+    if byte_offset_hint is not None:
+        entry["byte_offset_hint"] = int(byte_offset_hint)
+
+    def _do() -> Optional[dict]:
+        stored = load(session_id)
+        if _would_regress(stored, last_uuid, ordered_uuids):
+            return stored
+        _atomic_write(session_id, entry)
+        return entry
+
+    if fcntl is not None:
+        try:
+            _ensure_dir()
+            lock_fd = open(lock_path, "w")
+            try:
+                fcntl.flock(lock_fd, fcntl.LOCK_EX)
+                return _do()
+            finally:
+                fcntl.flock(lock_fd, fcntl.LOCK_UN)
+                lock_fd.close()
+        except OSError:
+            pass
+
+    # Fallback without lock (best-effort).
+    try:
+        return _do()
+    except OSError:
+        return None