sliceagent 0.1.0__py3-none-any.whl

sliceagent/onboarding.py

@@ -0,0 +1,323 @@
+"""First-run onboarding + config discovery — the `sliceagent init` / `config` / `help` / `version` subcommands.
+
+Turns the cold start from "copy .env.example, learn 28 env vars, hand-edit a TOML" into "run `sliceagent init`":
+pick a provider, paste a key, we test it, and write ~/.sliceagent/config.toml so the next bare `sliceagent`
+just works. `sliceagent config --list` makes every knob discoverable; `sliceagent help` shows the surface.
+
+All entry points take injectable input/getpass/llm/home so the wizard is testable without a tty or a key.
+"""
+from __future__ import annotations
+
+import os
+
+from .envspec import GROUPS, REGISTRY, current_value
+
+# provider presets: key → (label, base_url, default_model). 'custom' prompts for the base_url.
+PROVIDERS = {
+    "1": ("moonshot", "Moonshot (Kimi)", "https://api.moonshot.cn/v1", "kimi-k2.7-code"),
+    "2": ("openai", "OpenAI", "", "gpt-5.5"),
+    "3": ("deepseek", "DeepSeek", "https://api.deepseek.com/v1", "deepseek-chat"),
+    "4": ("custom", "Custom OpenAI-compatible endpoint", "", ""),
+}
+
+
+def _version() -> str:
+    try:
+        from . import __version__
+        return __version__
+    except Exception:  # noqa: BLE001
+        return "0.0.0"
+
+
+def _toml_str(v: str) -> str:
+    s = ((v or "").replace("\\", "\\\\").replace('"', '\\"')
+         .replace("\n", "\\n").replace("\r", "\\r").replace("\t", "\\t"))
+    return '"' + s + '"'
+
+
+def _toml_key(k: str) -> str:
+    """A TOML table-header key: bare if it's a simple identifier, else a quoted key (so a provider id with a
+    dot/space/quote — e.g. 'my.host' — round-trips as one key instead of a nested table or a parse error)."""
+    if k and all(c.isalnum() or c in "-_" for c in k):
+        return k
+    return '"' + k.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def _toml_val(v) -> str:
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, (int, float)):
+        return str(v)
+    if isinstance(v, list):
+        return "[" + ", ".join(_toml_val(x) for x in v) + "]"
+    return _toml_str(str(v))
+
+
+def _emit_section(prefix: str, d: dict, lines: list) -> None:
+    """Emit one TOML table RECURSIVELY. Scalars first (TOML requires them before any sub-table header),
+    then each nested dict as a sub-table at ANY depth — so a nested dict like mcp_servers.<id>.env
+    becomes a proper [mcp_servers.<id>.env] sub-table instead of being stringified into a corrupt value
+    (the old code only handled two levels). A pure container of sub-tables (e.g. `providers`) gets no
+    header of its own; the sub-table headers imply it."""
+    scalars = [(k, v) for k, v in d.items() if not isinstance(v, dict)]
+    subtables = [(k, v) for k, v in d.items() if isinstance(v, dict)]
+    if prefix and (scalars or not subtables):
+        lines.append(f"\n[{prefix}]")
+    for k, v in scalars:
+        lines.append(f"{_toml_key(k)} = {_toml_val(v)}")
+    for k, v in subtables:
+        child = f"{prefix}.{_toml_key(k)}" if prefix else _toml_key(k)
+        _emit_section(child, v, lines)
+
+
+def _emit_toml(data: dict) -> str:
+    """Minimal TOML emitter for sliceagent's config shape (scalars, sections, table-of-tables for
+    [providers.<id>], and arbitrarily-nested sub-tables like [mcp_servers.<id>.env]). Round-trips a
+    tomllib-parsed dict so editing one provider/server preserves the rest."""
+    lines = ["# sliceagent config — managed by `sliceagent init` / `config`. ENV overrides any value here."]
+    _emit_section("", data, lines)
+    return "\n".join(lines) + "\n"
+
+
+def _config_path(home: str | None = None) -> str:
+    home = home or os.path.expanduser("~")
+    return os.path.join(home, ".sliceagent", "config.toml")
+
+
+def _read_config(path: str) -> dict:
+    import tomllib
+    try:
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    except (OSError, tomllib.TOMLDecodeError):
+        return {}
+
+
+def _atomic_write(path: str, body: str) -> None:
+    """ATOMIC 0600 write (the file holds an API key — never leave it half-written): write a temp in the same
+    dir, fsync, then os.replace(); on ANY failure remove the temp so no key-bearing fragment is left behind."""
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    import tempfile
+    fd, tmp = tempfile.mkstemp(dir=os.path.dirname(path) or ".", prefix=".sliceagent-cfg-", suffix=".tmp")
+    ok = False
+    try:
+        os.fchmod(fd, 0o600)
+        os.write(fd, body.encode("utf-8"))
+        os.fsync(fd)
+        os.close(fd)
+        os.replace(tmp, path)
+        ok = True
+    finally:
+        if not ok:
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+            try:
+                os.remove(tmp)
+            except OSError:
+                pass
+
+
+def _save_provider(path: str, *, pid: str, model: str, api_key: str, base_url: str) -> None:
+    """Merge a provider into the config: add/update [providers.<pid>], set it as the default, keep the rest."""
+    data = _read_config(path)
+    provs = data.setdefault("providers", {})
+    if not isinstance(provs, dict):              # a corrupt non-dict providers must not crash on provs[pid]=
+        provs = data["providers"] = {}
+    entry = {"api_key": api_key, "model": model}
+    if base_url:
+        entry["base_url"] = base_url
+    provs[pid] = entry
+    agent = data.setdefault("agent", {})
+    if not isinstance(agent, dict):
+        agent = data["agent"] = {}
+    agent["default_provider"] = pid
+    agent["model"] = model                                     # keep top-level model in sync (back-compat)
+    _atomic_write(path, _emit_toml(data))
+
+
+def _test_key(model: str, api_key: str, base_url: str, llm_factory) -> tuple[bool, str]:
+    """One cheap completion to confirm the key/endpoint work. Returns (ok, message)."""
+    prev = {k: os.environ.get(k) for k in ("LLM_API_KEY", "LLM_BASE_URL", "OPENAI_BASE_URL")}
+    try:
+        os.environ["LLM_API_KEY"] = api_key
+        if base_url:
+            os.environ["LLM_BASE_URL"] = base_url
+        else:
+            # empty preset base_url ⇒ provider default; clear BOTH aliases (OpenAILLM also resolves
+            # OPENAI_BASE_URL) so a stale exported endpoint can't hijack the key-test probe.
+            os.environ.pop("LLM_BASE_URL", None)
+            os.environ.pop("OPENAI_BASE_URL", None)
+        llm = llm_factory(model)
+        resp = llm.complete([{"role": "user", "content": "Reply with the single word: ok"}], [])
+        txt = (getattr(resp, "content", "") or "").strip()
+        return (True, txt[:40] or "(empty reply, but the call succeeded)")
+    except Exception as e:  # noqa: BLE001
+        return (False, f"{type(e).__name__}: {e}")
+    finally:
+        for k, v in prev.items():
+            if v is None:
+                os.environ.pop(k, None)
+            else:
+                os.environ[k] = v
+
+
+def run_init(*, inp=input, getpw=None, llm_factory=None, home=None) -> int:
+    """Interactive setup wizard. Returns a process exit code."""
+    import getpass
+    getpw = getpw or getpass.getpass
+    if llm_factory is None:
+        def llm_factory(model):
+            from .llm import OpenAILLM
+            return OpenAILLM(model=model)
+    out = print
+    path = _config_path(home)
+    out("\n  sliceagent setup\n  ─────────────")
+    if os.path.exists(path):
+        try:
+            ans = inp(f"  A config already exists at {path}. Add/update a provider in it? [Y/n] ").strip().lower()
+        except (EOFError, KeyboardInterrupt):
+            out("\n  cancelled."); return 1
+        if ans in ("n", "no"):
+            out("  Leaving the existing config unchanged. Run `sliceagent` to start."); return 0
+
+    out("\n  Choose a provider:")
+    for k, (_id, label, base, model) in PROVIDERS.items():
+        out(f"    {k}. {label}" + (f"  ({model})" if model else ""))
+    try:
+        choice = inp("  > ").strip() or "1"
+        pid, label, base_url, model = PROVIDERS.get(choice, PROVIDERS["1"])
+        if pid == "custom":
+            base_url = inp("  Base URL (OpenAI-compatible, e.g. https://host/v1): ").strip()
+        # RE-CONFIGURING an ALREADY-SAVED provider (re-running `sliceagent init` to update the model,
+        # or just re-confirming) must not force a blind full-key retype: pressing Enter keeps the
+        # existing key/model. A BRAND-NEW provider has no existing entry, so blank still means "no
+        # key entered" and falls through to the abort below — same as before.
+        existing = _read_config(path).get("providers")
+        existing = existing.get(pid) if isinstance(existing, dict) else None
+        existing = existing if isinstance(existing, dict) else {}
+        existing_key = existing.get("api_key") or ""
+        key_prompt = "  API key (hidden, Enter to keep existing): " if existing_key else "  API key (hidden): "
+        key = getpw(key_prompt).strip() or existing_key
+        model = (inp(f"  Model [{existing.get('model') or model or 'required'}]: ").strip()
+                 or existing.get("model") or model)
+    except (EOFError, KeyboardInterrupt):
+        out("\n  cancelled."); return 1
+    if not key:
+        out("  No API key entered — aborting."); return 1
+    if not model:
+        out("  No model specified — aborting."); return 1
+
+    out("\n  Testing the key with one request…")
+    ok, msg = _test_key(model, key, base_url, llm_factory)
+    out(f"  {'✓ works' if ok else '✗ failed'}: {msg}")
+    if not ok:
+        try:
+            cont = inp("  Save the config anyway? [y/N] ").strip().lower()
+        except (EOFError, KeyboardInterrupt):
+            cont = "n"
+        if cont not in ("y", "yes"):
+            out("  Not saved. Re-run `sliceagent init` to try again."); return 1
+
+    _save_provider(path, pid=pid, model=model, api_key=key, base_url=base_url)
+    out(f"\n  Saved provider '{pid}' (model {model}) → {path} (0600)")
+    out("  Ready. Run:  sliceagent\n")
+    return 0
+
+
+def run_config(argv=None, *, home=None, env=None) -> int:
+    """`sliceagent config` shows the resolved settings + config path; `--list` shows every env var."""
+    argv = argv or []
+    env = env if env is not None else os.environ
+    out = print
+    path = _config_path(home)
+    if "--path" in argv:
+        out(path); return 0
+    if argv and argv[0] == "--use":
+        pid = argv[1] if len(argv) > 1 else ""
+        data = _read_config(path)
+        provs = data.get("providers", {}) if isinstance(data.get("providers"), dict) else {}
+        if not pid or pid not in provs:
+            out(f"  usage: sliceagent config --use <provider>  "
+                f"(configured: {', '.join(provs) or 'none — run `sliceagent init`'})")
+            return 1
+        agent = data.setdefault("agent", {})
+        if not isinstance(agent, dict):                 # a corrupt non-dict [agent] must not crash on item-assign
+            agent = data["agent"] = {}
+        agent["default_provider"] = pid
+        if isinstance(provs[pid], dict) and provs[pid].get("model"):
+            agent["model"] = provs[pid]["model"]
+        _atomic_write(path, _emit_toml(data))
+        out(f"  default provider → {pid} (model {provs[pid].get('model', '?') if isinstance(provs[pid], dict) else '?'})")
+        return 0
+    if "--list" in argv:
+        out("\n  sliceagent environment variables (ENV overrides config file):")
+        for g in GROUPS:
+            out(f"\n  [{g}]")
+            for e in [e for e in REGISTRY if e.group == g]:
+                cur = current_value(e.name, env)
+                shown = f" = {cur}" if cur else (f"  (default: {e.default})" if e.default else "")
+                choices = f"  {{{', '.join(e.choices)}}}" if e.choices else ""
+                out(f"    {e.name}{shown}{choices}")
+                out(f"        {e.desc}")
+        out("")
+        return 0
+    out(f"\n  sliceagent {_version()}")
+    out(f"  config file: {path}  ({'exists' if os.path.exists(path) else 'not created — run `sliceagent init`'})")
+    data = _read_config(path)
+    provs = data.get("providers", {}) if isinstance(data.get("providers"), dict) else {}
+    if provs:
+        _agent = data.get("agent")
+        default = _agent.get("default_provider", "") if isinstance(_agent, dict) else ""
+        out("  providers (* = default · `config --use <id>` to switch):")
+        for pid, p in provs.items():
+            mark = "*" if pid == default else " "
+            out(f"    {mark} {pid}  ({(p or {}).get('model', '?')})")
+    out("  set values:")
+    any_set = False
+    for e in REGISTRY:
+        cur = current_value(e.name, env)
+        if cur:
+            out(f"    {e.name} = {cur}")
+            any_set = True
+    if not any_set:
+        out("    (none — all defaults)")
+    out("\n  `sliceagent config --list` for all knobs · `sliceagent init` to (re)configure\n")
+    return 0
+
+
+def print_usage() -> int:
+    out = print
+    out(f"""
+  sliceagent {_version()} — a memory-native coding agent (the slice/cache-not-log kernel)
+
+  usage:
+    sliceagent                 start the interactive agent (inline UI; AGENT_TUI=live|off to switch)
+    sliceagent init            interactive first-run setup (provider, key, model) → ~/.sliceagent/config.toml
+    sliceagent config          show resolved settings, providers, and config path
+    sliceagent config --list   list every environment variable, default, and current value
+    sliceagent config --use <id>   switch the default provider
+    sliceagent help            show this help
+    sliceagent version         show the version
+
+  first run:  sliceagent init   then   sliceagent
+  docs: README.md · QUICKSTART.md
+""")
+    return 0
+
+
+def dispatch(argv) -> int:
+    """Route a recognized subcommand; return an exit code. cli.main() calls this before any key gate."""
+    cmd = argv[0] if argv else ""
+    if cmd in ("--version", "-V", "version"):
+        print(f"sliceagent {_version()}"); return 0
+    if cmd in ("help", "--help", "-h"):
+        return print_usage()
+    if cmd == "init":
+        return run_init()
+    if cmd == "config":
+        return run_config(argv[1:])
+    print(f"unknown command: {cmd!r}\n")
+    print_usage()
+    return 1                          # non-zero so shell scripts see the failure

sliceagent/oracle.py

@@ -0,0 +1,36 @@
+"""Oracle implementations — ground-truth verification, independent of retrieval accuracy.
+
+The loop can gate "done" on this so a retrieval miss can't masquerade as completion.
+"""
+from __future__ import annotations
+
+import subprocess
+
+
+class CommandOracle:
+    """Runs a verification command (e.g. the project's test suite). Pass/fail by exit code."""
+
+    def __init__(self, cmd: str, timeout: int = 120):
+        self.cmd = cmd
+        self.timeout = timeout
+
+    def verify(self) -> tuple[bool, str]:
+        try:
+            r = subprocess.run(self.cmd, shell=True, capture_output=True, text=True, timeout=self.timeout)
+        except subprocess.TimeoutExpired as e:
+            # A timed-out verification is a FAILURE, not a thrown exception — otherwise it propagates out
+            # of the oracle and silently BYPASSES the done-gate (a hung test would mark the task complete).
+            # On timeout, .stdout/.stderr may each be bytes OR str OR None (version/stream dependent) —
+            # decode EACH before concat, else a bytes+str mix (e.g. stdout bytes, stderr None→"") raises
+            # TypeError and the crash bypasses the done-gate. Coerce per-operand.
+            def _s(x):
+                return x.decode("utf-8", "replace") if isinstance(x, bytes) else (x or "")
+            out = _s(e.stdout) + _s(e.stderr)
+            return False, (out + f"\n[verification timed out after {self.timeout}s]").strip()
+        out = ((r.stdout or "") + (r.stderr or "")).strip()
+        return r.returncode == 0, out
+
+
+class NullOracle:
+    def verify(self) -> tuple[bool, str]:
+        return True, ""

sliceagent/pagetable.py

@@ -0,0 +1,255 @@
+"""PageTable — the SINGLE read/retrieval entry point for the slice.
+
+Three scattered retrieval sources used to be wired independently into the slice build:
+the code-discovery map (Retriever.retrieve/graph_map), the per-subtree project notes
+(SubdirHints.hints_for), and cross-session episode search (Memory.search_episodes).
+PageTable unifies them behind ONE call — ``lookup(focus, *, kind, k) -> list[PageRef]`` —
+so the slice has a single place that decides WHAT to page in.
+
+The PageTable owns the SubdirHints instance (constructed once per build closure, same
+lifetime as before, preserving per-task subtree dedup). It is otherwise stateless: each
+backend is a thin adapter over its source. Backends emit RAW text in the PageRef.preview;
+fencing (wrap_untrusted) stays at ONE layer — the renderer in seed.py — so there is no
+double-wrap.
+
+NO-TRANSCRIPT MOAT: lookup() reads from durable/derived sources each turn; it never
+accumulates state across turns (the only per-instance state is SubdirHints' per-task
+surfaced-subtree set, which is a bounded durable store, not a transcript).
+
+BRAIN-ANALOGY LEGEND (used in this file's section comments — a naming aid, not a new mechanism):
+  SENSORY CORTEX  — code / project-notes: re-computed live from the filesystem, never persisted;
+                    perception of the present, not memory of the past.
+  NEOCORTEX       — memory-lessons: distilled, cross-session, auto-surfaced (like consolidated
+                    semantic memory recalled associatively, with no explicit search).
+  HIPPOCAMPUS     — episode-*: the lossless per-turn log, reached only by an explicit, cue-dependent
+                    recall (recall_history) — like real hippocampal recall, prone to confabulation if
+                    the cue is weak, which the visible-manifest/recall-marker work exists to prevent.
+The Slice's own carried state (findings, conversation ring, plan, mission — see pfc.py) is the
+fourth piece: PREFRONTAL CORTEX / working memory — bounded, actively maintained, free (no lookup()
+call at all), and lost when the task resets. Only 4 of PageTable's 6 kinds fire per turn inside
+build(); the other 2 (episode-xsession, episode-search-thissession) are reached only via the
+recall_history tool (hippocampus.py) — the model's own hippocampal-recall lever.
+
+DEFERRED (next backends to fold in here):
+  - per-file code refs (fan-out of the repo map) — kept as the single '(repo map)' page.
+"""
+from __future__ import annotations
+
+import os
+
+from .interfaces import PageRef
+from .text_utils import format_ts, normalize_ws
+
+# Per-code-map preview cap — a generous PHYSICAL backstop only. The real bound is BREADTH, applied ONCE
+# in graph_map (top-N ranked files, each shown complete). This must not re-cut the breadth-bounded map.
+CODE_PREVIEW_CHARS = 12000
+
+
+class PageTable:
+    """Single entry for the slice's read/retrieval. ``lookup`` dispatches by ``kind`` to one
+    backend; ``k`` is the per-kind budget (k<=0 SKIPS that backend, returning [])."""
+
+    def __init__(self, retriever=None, memory=None, subdir_hints=None,
+                 *, session_id: str | None = None):
+        self.retriever = retriever
+        self.memory = memory
+        self.subdir_hints = subdir_hints          # OWNED here (per-task subtree dedup lives on it)
+        # ONE concept — the CURRENT session: cross-session reads EXCLUDE it, within-session reads filter
+        # ONLY to it. (Was the overloaded `exclude_session`, used as both exclude AND only — a leak waiting
+        # to happen the moment a caller left it None.)
+        self.session_id = session_id
+
+    # ------------------------------------------------------------------ public
+    def lookup(self, focus, *, kind: str, k: int = 6, paths=None) -> list[PageRef]:
+        """Page in references relevant to ``focus`` from the ``kind`` backend.
+
+        ``focus`` is the per-kind locator: a discovery QUERY (code), the active-file WORKING
+        SET (project-notes), or a search QUERY (episode-xsession). ``k`` bounds the backend
+        (k<=0 => skip, [] — honors tighten's discovery_k=0 floor). Returns PageRefs carrying
+        RAW text; the caller fences them at render time."""
+        if k <= 0:
+            return []
+        # — SENSORY CORTEX (derived views): re-computed from the LIVE filesystem/code every call,
+        # never persisted — there is nothing to "remember" here, only to look at again, more carefully.
+        if kind == "code":
+            return self._code(focus, k)
+        if kind == "project-notes":
+            return self._project_notes(focus)
+        # — NEOCORTEX (long-term memory): distilled, cross-session, auto-surfaced — like a consolidated
+        # semantic memory that comes to mind associatively, without an effortful, cue-driven search.
+        if kind == "memory-lessons":
+            return self._lessons(focus, k, paths)
+        # — HIPPOCAMPUS (episodic memory): the lossless per-turn log. Retrieval is cue-dependent and
+        # EXPLICIT (recall_history) — like real hippocampal recall, it can fail or confabulate if the
+        # retrieval cue is weak, which is exactly the class of bug the cache-manifest/recall-marker work
+        # in seed.py and regions.py exists to prevent.
+        if kind == "episode-xsession":
+            return self._episodes(focus, k)
+        if kind == "episode-thissession":
+            return self._episodes_thissession(focus, k)
+        if kind == "episode-search-thissession":
+            return self._episodes_search_thissession(focus, k)
+        return []
+
+    # ----------------------------------------------------------------- backends
+    def _code(self, query: str, k: int) -> list[PageRef]:
+        """RELATED CODE: the retriever's relevance-ranked repo MAP. KEEP the single '(repo map)'
+        shape (one PageRef wrapping the whole map text) — per-file fan-out is a deferred follow-up."""
+        if self.retriever is None:
+            return []
+        snippets = self.retriever.retrieve(query, k=k)
+        if not snippets:
+            return []
+        # The Retriever contract yields a single Snippet(path='(repo map)') today (see
+        # code_index.RipgrepCodeIndex.retrieve). Carry its map text as ONE page, RAW.
+        sn = snippets[0]
+        return [PageRef(handle=sn.path, kind="code", preview=sn.text[:CODE_PREVIEW_CHARS],
+                        score=sn.score, untrusted=True)]
+
+    def _project_notes(self, active_files) -> list[PageRef]:
+        """SUBDIRECTORY CONTEXT: convention files for any subtree in the working set not yet
+        surfaced this task. SubdirHints is owned here; its per-task dedup is preserved."""
+        if self.subdir_hints is None:
+            return []
+        text = self.subdir_hints.hints_for(active_files)
+        if not text:
+            return []
+        return [PageRef(handle="(project notes)", kind="project-notes", preview=text,
+                        score=0.0, untrusted=True)]
+
+    def _lessons(self, query: str, k: int, paths=None) -> list[PageRef]:
+        """RELEVANT MEMORY: distilled cross-session LESSONS (memem's relevance-gated retrieve), the
+        always-on per-turn recall — NEOCORTEX in brain terms: consolidated, generalized, auto-surfaced.
+        Distinct from `_episodes` (raw FTS5 episode text) — HIPPOCAMPUS: the lossless, per-session log,
+        reached only by an explicit, cue-dependent recall_history call. Each Snippet -> one PageRef
+        (preview carries the lesson text RAW; the renderer fences it). memory absent / no hits -> []."""
+        if self.memory is None:
+            return []
+        snippets = self.memory.recall(query, k=k, paths=paths)   # R1: file-context bonus at topic-start
+        return [PageRef(handle=sn.path, kind="memory-lessons", preview=sn.text,
+                        score=sn.score, untrusted=True) for sn in snippets]
+
+    def _episodes(self, query: str, k: int) -> list[PageRef]:
+        """CROSS-SESSION RECALL: FTS5 episode hits from PAST sessions (the one cross-session read
+        path). Each hit row -> one PageRef: `handle` is the session·turn locator, `preview` packs
+        ts/title/note/match for the listing. Empty/unavailable index -> []."""
+        if self.memory is None or not isinstance(query, str) or not query.strip():
+            return []
+        hits = self.memory.search_episodes(query.strip(), limit=k,
+                                           exclude_session=self.session_id)   # cross-session: drop my lineage
+        return [_episode_pageref(h) for h in hits]
+
+    def _episodes_search_thissession(self, query: str, k: int) -> list[PageRef]:
+        """WITHIN-SESSION content recall: FTS5 over the CURRENT session's episodes (the long-tail past
+        the manifest/index window). Closes the gap where an old turn was reachable only by a turn number
+        nobody knew. Each hit -> a PageRef whose handle is the TURN NUMBER, so the model pages the full
+        turn with recall_history(turns=[N]) — search by content, fetch by the number it just learned."""
+        if self.memory is None or not isinstance(query, str) or not query.strip() or not self.session_id:
+            return []                              # FAIL CLOSED: no current session → no within-session search
+        hits = self.memory.search_episodes(query.strip(), limit=k, only_session=self.session_id)
+        return [PageRef(handle=str(h.get("turn")), kind="episode-search-thissession",
+                        preview=_pack_episode_preview(h), score=float(h.get("score") or 0.0),
+                        untrusted=False) for h in hits]
+
+    def _episodes_thissession(self, session_id: str, k: int) -> list[PageRef]:
+        """PAGED-OUT HISTORY manifest: locator-only PageRefs for the last ``k`` turns of THIS session —
+        the TRIGGER that makes recall_history get called (the model cannot reach for a cache it cannot
+        see; pin/view died because their payoff was invisible). The single this-session episodic READ
+        entry (mirrors ``_episodes`` for cross-session) so the slice has ONE retrieval seam. Locators
+        only — turn/title/breadcrumb, NEVER step bodies; content pages in solely when the model calls
+        recall_history(turns=[N]). Bounded to ``k``; a trailing '…older' ref flags that more exist."""
+        if not session_id:
+            return []
+        # Use the TAIL-only manifest read (O(k)/turn) when available, so a long session doesn't re-parse the
+        # whole JSONL every slice build — that was O(n²)/session, eroding the flat-per-turn-cost moat.
+        manifest = getattr(self.memory, "episode_manifest", None)
+        if manifest is not None:
+            shown, total = manifest(session_id, k)
+            older = max(0, total - len(shown))
+        else:
+            read = getattr(self.memory, "read_episodes", None)
+            if read is None:
+                return []
+            lines = read(session_id)        # fallback: whole-session read
+            shown = lines[-k:]
+            older = len(lines) - len(shown)
+        if not shown:
+            return []
+        refs = [PageRef(handle=str(ln.get("turn")), kind="episode-thissession",
+                        preview=_pack_thissession_preview(ln),
+                        score=float(ln.get("turn") or 0), untrusted=False) for ln in shown]
+        if older:
+            refs.append(PageRef(handle="…older", kind="episode-thissession",
+                                preview=(f"{older} earlier turn(s) not shown — recall_history() for the full "
+                                         f"index, or recall_history(search=\"keywords\") to find an older turn "
+                                         f"of THIS session by content (also matches past sessions)"),
+                                score=0.0, untrusted=False))
+        return refs
+
+
+def _episode_pageref(h: dict) -> PageRef:
+    """Map one cross-session episode hit dict to a PageRef (lossless for the listing's display:
+    locator in `handle`, ts/title/note/match packed into `preview`)."""
+    handle = f"{(h.get('session_id') or '')[:14]} · turn {h.get('turn')}"
+    return PageRef(handle=handle, kind="episode-xsession",
+                   preview=_pack_episode_preview(h),
+                   score=float(h.get("score") or 0.0), untrusted=True)
+
+
+def _pack_episode_preview(h: dict) -> str:
+    ts = format_ts(h.get("ts"))                            # "06-16 12:30"
+    title = (h.get("title") or "(no title)")[:60]
+    note = (h.get("note") or "").strip()
+    snip = normalize_ws(h.get("snippet"))
+    out = f"{ts} · {title}"
+    if note:
+        out += f"\n    note: {note[:160]}"
+    if snip:
+        out += f"\n    match: {snip[:200]}"
+    return out
+
+
+def _pack_thissession_preview(ln: dict) -> str:
+    """One locator-line body for the PAGED-OUT HISTORY manifest: the turn's title + a PAYOFF
+    breadcrumb (what the turn HOLDS), so the model can decide to page it back informedly. Locators
+    only — never step bodies/observations (those page in on demand via recall_history). `ln` is a
+    raw line parsed from the on-disk episodic JSONL — a malformed/corrupt record (e.g. an older
+    schema, a hand-edited file) must degrade to an empty preview, never crash the manifest build."""
+    rec = ln.get("record")
+    rec = rec if isinstance(rec, dict) else {}
+    meta = rec.get("meta")
+    meta = meta if isinstance(meta, dict) else {}
+    title = normalize_ws(rec.get("title") or "(untitled)")[:52]
+    flag = " · FAIL" if meta.get("failing") else ""
+    crumb = _thissession_breadcrumb(rec, meta)
+    return f"turn {ln.get('turn')} · \"{title}\"{flag}" + (f" · {crumb}" if crumb else "")
+
+
+def _thissession_breadcrumb(rec: dict, meta: dict) -> str:
+    """The payoff breadcrumb (≤60 chars). An empty breadcrumb was the pin/view killer — a locator
+    with no visible payoff never gets called — so every line is GUARANTEED a content-derived hint:
+    the model's own note if it left one, else the turn's edited files, else its distinct read/grep/run
+    actions. All from data already in the record (no extra read, no LLM). `rec`/`meta` are already
+    dict-guarded by the caller; `steps`/`action` entries are guarded here since they come from the
+    same untrusted on-disk record."""
+    note = normalize_ws(rec.get("note"))
+    if note:
+        return ("note: " + note)[:60]
+    files = meta.get("files") or []
+    files = files if isinstance(files, list) else []
+    if files:
+        return ("edited: " + ", ".join(os.path.basename(str(f)) for f in files))[:60]
+    acts: list[str] = []
+    for st in rec.get("steps", []) or []:
+        if not isinstance(st, dict):
+            continue
+        for a in st.get("action", []) or []:
+            if not isinstance(a, dict):
+                continue
+            name = a.get("name") or ""
+            args = a.get("args", {}) if isinstance(a.get("args"), dict) else {}
+            arg = args.get("path") or args.get("query") or args.get("command") or ""
+            sig = (f"{name} {os.path.basename(str(arg))}").strip() if arg else name
+            if sig and sig not in acts:
+                acts.append(sig)
+    return ("did: " + ", ".join(acts[:3]))[:60] if acts else ""