webbee 0.3.33__tar.gz → 0.3.35__tar.gz

{webbee-0.3.33 → webbee-0.3.35}/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.3.35
+
+Reliability and speed of the terminal itself.
+
+- Code intelligence no longer dies silently at startup. On many repositories it
+  failed while building its index and the terminal simply said "code intel off"
+  with no reason — semantic search and the code graph were quietly unavailable
+  for the whole session. It now builds correctly (and old broken caches are
+  rebuilt automatically).
+- Resizing the window is smooth again: dragging a split no longer re-wraps the
+  text on every intermediate width, so the terminal stops freezing mid-drag.
+- Ctrl+V no longer blocks the terminal while reading the clipboard, so pasting
+  a large image can't lock up the interface.
+- Switching tabs with Shift+TAB is instant again — it no longer runs a `git`
+  command each time (which could stall if git itself hung).
+- Building the project index skips virtualenvs and dependency caches, so a
+  large in-tree environment can no longer crowd out your own source files.
+  On this repository the full pass went from ~31s to ~1s.
+- Fixed a rare case where a remote approval prompt could vanish before you
+  answered it.
+
+## 0.3.34
+
+Paste images with Ctrl+V. Copy a screenshot (or any image) and press Ctrl+V in
+a session tab — Webbee Code uploads it and drops a reference into your prompt,
+so the next thing you ask can be about that image. Text on the clipboard
+pastes inline. Nothing is sent until you send your message; if image upload
+isn't available the image is saved locally and referenced by path.
+
 ## 0.3.33
 
 Performance.

{webbee-0.3.33 → webbee-0.3.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webbee
-Version: 0.3.33
+Version: 0.3.35
 Summary: Webbee 🐝 — the Imperal Cloud coding agent in your terminal
 Project-URL: Homepage, https://imperal.io
 Project-URL: Documentation, https://docs.imperal.io

{webbee-0.3.33 → webbee-0.3.35}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "webbee"
-version = "0.3.33"
+version = "0.3.35"
 description = "Webbee 🐝 — the Imperal Cloud coding agent in your terminal"
 readme = "README.md"
 license = "MIT"

webbee-0.3.35/src/webbee/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.35"

webbee-0.3.35/src/webbee/clipboard_read.py

@@ -0,0 +1,154 @@
+"""Read the OS clipboard OUT-OF-BAND for Ctrl+V paste (W3 Wave A).
+
+A terminal's bracketed paste is text-only — a clipboard IMAGE never reaches the
+app that way — so an image must be pulled from the OS clipboard via the
+platform tool. Same discipline as `clipboard.py` (copy-out): `shutil.which`-
+gated, bounded timeout, output CAPTURED so it never inherits the dock's tty
+(the 0.3.32 lesson: a chatty child scrambles the full-screen renderer), and it
+NEVER raises. macOS + Linux are the verified paths; Windows is best-effort and
+UNVERIFIED (no Windows host to test on) — it fails soft to None."""
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ClipboardItem:
+    kind: str          # "image" | "text"
+    data: object       # bytes (PNG) for image, str for text
+    name: str = ""     # suggested filename for an image
+    mime: str = ""
+
+
+def _run(cmd):
+    """Captured, bounded, never-raises subprocess. `capture_output=True` keeps
+    stdout/stderr OFF the dock's tty. Returns CompletedProcess or None."""
+    try:
+        return subprocess.run(cmd, capture_output=True, timeout=2)
+    except Exception:
+        return None
+
+
+def _read_via_tempfile(argv_for_path) -> "bytes | None":
+    """Run a tool that WRITES a PNG to a temp path (osascript / PowerShell),
+    then read+delete it. `argv_for_path(path)` returns the argv. Never raises."""
+    import os
+    import tempfile
+    fd, path = tempfile.mkstemp(suffix=".png")
+    os.close(fd)
+    try:
+        p = _run(argv_for_path(path))
+        if p is not None and p.returncode == 0 and os.path.getsize(path) > 0:
+            with open(path, "rb") as f:
+                return f.read() or None
+        return None
+    except Exception:
+        return None
+    finally:
+        try:
+            os.remove(path)
+        except OSError:
+            pass
+
+
+def _mac_image() -> "bytes | None":
+    if shutil.which("pngpaste"):
+        p = _run(["pngpaste", "-"])
+        if p is not None and p.returncode == 0 and p.stdout:
+            return p.stdout
+    if not shutil.which("osascript"):
+        return None
+    # osascript returns non-zero when the clipboard holds no «class PNGf» image.
+    def _argv(path):
+        script = ('set p to (POSIX file "%s")\n'
+                  'set d to (the clipboard as «class PNGf»)\n'
+                  'set fh to open for access p with write permission\n'
+                  'write d to fh\nclose access fh' % path)
+        return ["osascript", "-e", script]
+    return _read_via_tempfile(_argv)
+
+
+def _linux_image() -> "bytes | None":
+    if shutil.which("wl-paste"):
+        types = _run(["wl-paste", "--list-types"])
+        if types is not None and types.returncode == 0 and b"image/png" in (types.stdout or b""):
+            p = _run(["wl-paste", "--type", "image/png"])
+            if p is not None and p.returncode == 0 and p.stdout:
+                return p.stdout
+    if shutil.which("xclip"):
+        tgt = _run(["xclip", "-selection", "clipboard", "-t", "TARGETS", "-o"])
+        if tgt is not None and tgt.returncode == 0 and b"image/png" in (tgt.stdout or b""):
+            p = _run(["xclip", "-selection", "clipboard", "-t", "image/png", "-o"])
+            if p is not None and p.returncode == 0 and p.stdout:
+                return p.stdout
+    return None
+
+
+def _windows_image() -> "bytes | None":
+    # UNVERIFIED (no Windows host). Best-effort; fail-soft to None.
+    if not shutil.which("powershell"):
+        return None
+
+    def _argv(path):
+        ps = ("Add-Type -AssemblyName System.Windows.Forms;"
+              "$i=[System.Windows.Forms.Clipboard]::GetImage();"
+              "if($i){$i.Save('%s')}" % path.replace("\\", "\\\\"))
+        return ["powershell", "-NoProfile", "-Command", ps]
+    return _read_via_tempfile(_argv)
+
+
+def read_clipboard_image() -> "bytes | None":
+    """Raw PNG bytes on the clipboard, or None. Platform-dispatched, captured
+    (tty-safe), never raises."""
+    try:
+        if sys.platform == "darwin":
+            return _mac_image()
+        if sys.platform == "win32":
+            return _windows_image()
+        return _linux_image()
+    except Exception:
+        return None
+
+
+def _text_cmd() -> "list[str] | None":
+    if sys.platform == "darwin":
+        return ["pbpaste"] if shutil.which("pbpaste") else None
+    if shutil.which("wl-paste"):
+        return ["wl-paste", "--no-newline"]
+    if shutil.which("xclip"):
+        return ["xclip", "-selection", "clipboard", "-o"]
+    if sys.platform == "win32" and shutil.which("powershell"):
+        return ["powershell", "-NoProfile", "-Command", "Get-Clipboard"]
+    return None
+
+
+def read_clipboard_text() -> "str | None":
+    """The clipboard's text, or None. Captured (tty-safe), never raises."""
+    cmd = _text_cmd()
+    if cmd is None:
+        return None
+    p = _run(cmd)
+    if p is not None and p.returncode == 0 and p.stdout:
+        try:
+            return p.stdout.decode("utf-8", "replace")
+        except Exception:
+            return None
+    return None
+
+
+def read_clipboard(ts: str) -> "ClipboardItem | None":
+    """One paste's worth of clipboard content: an IMAGE if present (PNG bytes,
+    named `pasted-<ts>.png`), else TEXT, else None. `ts` is a caller-supplied
+    timestamp string for the image name (the dock has no wall-clock in a pure
+    function, so it's passed in)."""
+    img = read_clipboard_image()
+    if img:
+        return ClipboardItem(kind="image", data=img, name=f"pasted-{ts}.png",
+                             mime="image/png")
+    txt = read_clipboard_text()
+    if txt:
+        return ClipboardItem(kind="text", data=txt)
+    return None

{webbee-0.3.33 → webbee-0.3.35}/src/webbee/home_view.py

@@ -368,6 +368,9 @@ class HomeView:
     def flash(self) -> str:
         return self._out.flash()
 
+    def flash_note(self, msg: str, secs: float = 4.0) -> None:
+        self._out.flash_note(msg, secs)
+
     def scroll(self, delta: int) -> None:
         # Wheel (via the control) and PageUp/PageDown (tui routes here) move the
         # top visible line; clamped so you can't scroll past the ends.

{webbee-0.3.33 → webbee-0.3.35}/src/webbee/intel/chunker.py

@@ -27,8 +27,31 @@ def _hash(text: str) -> str:
 
 
 def _mk(path: str, symbol: str, kind: str, s: int, e: int, lines: list[str]) -> Chunk:
+    """Build one chunk. The id MUST be unique across everything chunk_index
+    yields, because it is the primary key in BOTH VectorStore._pos and
+    IntelService._chunk_hashes.
+
+    path+line-span alone is NOT unique: a symbol longer than
+    _CHUNK_MAX_LINES is split by `_windows` into windows that step by
+    (_WINDOW_LINES - _WINDOW_OVERLAP), and such a window can land on exactly
+    the span of a trailing nested symbol -- e.g. a class spanning 1..61 has
+    its last window at 51..61, and a method spanning 51..61 then produced the
+    SAME id ("path#51-61"). Two consequences, both silent:
+      * VectorStore.add took its "id already known" branch and wrote
+        _mat[pos] while _mat was still the empty (0, dim) array -> IndexError
+        -> boot.start_intel swallowed it -> code intel OFF for the session;
+      * _chunk_hashes collapsed both chunks onto one hash entry, so an
+        incremental re-embed could skip a genuinely changed chunk.
+    `kind` alone is not enough either: an outer symbol and a long nested one
+    can BOTH be windowed (kind="chunk" for each) and a window of each can
+    cover the same span -- observed on real dependency code, e.g. jinja2's
+    `Environment` vs its `__init__` both yielding "environment.py#294-353".
+    So the id carries `kind` AND `symbol`, which is what actually
+    distinguishes them. The id stays deterministic across runs -- stability
+    matters because apply_changes diffs chunk ids to decide what to re-embed.
+    """
     text = "\n".join(lines[s - 1:e])
-    return Chunk(id=f"{path}#{s}-{e}", symbol=symbol, kind=kind, path=path,
+    return Chunk(id=f"{path}#{s}-{e}:{kind}:{symbol}", symbol=symbol, kind=kind, path=path,
                  start_line=s, end_line=e, text=text, content_hash=_hash(text))
 
 

{webbee-0.3.33 → webbee-0.3.35}/src/webbee/intel/query.py

@@ -69,7 +69,15 @@ def _lexical_search(svc, q, kind, path_glob, items_by_id: dict) -> list[str]:
 
 
 def _chunk_item(svc, cid: str, score: float) -> dict | None:
-    """Map an embed-chunk id ('<path>#<start>-<end>') back to a search item.
+    """Map an embed-chunk id back to a search item.
+
+    Id shape is '<path>#<start>-<end>:<kind>:<symbol>' (chunker._mk). The
+    ':<kind>:<symbol>' tail was added 2026-07-25 to make ids unique -- see
+    chunker._mk -- so the line range is only the part BEFORE the first ':'.
+    Ids written by an older cache have no tail at all, hence the partition
+    (not a required split): both shapes parse, and a schema bump means the
+    old ones are normally gone anyway.
+
     Title/kind = the enclosing symbol's when the graph has one covering the
     chunk's line range, else the bare '<path>:<start>' / 'chunk' fallback --
     a hardcoded kind="chunk" would make every vector hit invisible to a
@@ -77,6 +85,7 @@ def _chunk_item(svc, cid: str, score: float) -> dict | None:
     if "#" not in cid or "-" not in cid.rpartition("#")[2]:
         return None
     path, _, rng = cid.rpartition("#")
+    rng = rng.partition(":")[0]          # drop the ':<kind>:<symbol>' tail
     start_s, end_s = rng.split("-", 1)
     try:
         start, end = int(start_s), int(end_s)

{webbee-0.3.33 → webbee-0.3.35}/src/webbee/intel/service.py

@@ -25,10 +25,39 @@ def _git_ref(root: str) -> str:
         return ""
 
 
+# Dependency / build trees are pruned from the index walk. This is not only a
+# speed win, it is a CORRECTNESS one: `_walk` stops at `limit`, so on a repo
+# with a big in-tree dependency directory the cap could be spent on
+# third-party files while the project's OWN sources went unindexed.
+#
+# Measured on this checkout (it carries an in-tree `venv/`): 3062 files -> 111
+# candidates, and build_index 30.0s -> well under a second.
+#
+# ".git" and every DOTTED directory were already pruned (covering .venv/,
+# .tox/, .mypy_cache/, ...). These are the undotted ones that were not.
+# Deliberately conservative -- only names that are unambiguous dependency
+# caches. Names that a real project might legitimately use for its OWN source
+# ("build", "dist", "target", "env", "vendor") are NOT pruned by name here: a
+# virtualenv called "venv"/"env" is instead detected by its `pyvenv.cfg`
+# marker below, which is a fact about the directory rather than a guess about
+# its name.
+_SKIP_DIRS = frozenset({"node_modules", "site-packages", "__pycache__"})
+
+
+def _is_virtualenv(path: str) -> bool:
+    """True for a real Python virtualenv root: PEP 405 puts `pyvenv.cfg` at
+    the top of every one. Checking the MARKER (not the folder name) means a
+    project module that merely happens to be called `env/` keeps being
+    indexed, while an in-tree `venv/` is skipped whatever it is named."""
+    return os.path.exists(os.path.join(path, "pyvenv.cfg"))
+
+
 def _walk(root: str, limit: int = 20000) -> list[str]:
     out = []
     for dp, dns, fns in os.walk(root):
-        dns[:] = [d for d in dns if d != ".git" and not d.startswith(".") and d != "node_modules"]
+        dns[:] = [d for d in dns
+                  if d != ".git" and not d.startswith(".") and d not in _SKIP_DIRS
+                  and not _is_virtualenv(os.path.join(dp, d))]
         for fn in fns:
             out.append(os.path.relpath(os.path.join(dp, fn), root))
             if len(out) >= limit:

{webbee-0.3.33 → webbee-0.3.35}/src/webbee/intel/store.py

@@ -18,7 +18,12 @@ from webbee.intel.models import ProjectIndex, FileIndex, Symbol
 # extra) can still import this whole module (index.json save/load, the
 # graph plane) with no numpy on the system at all.
 
-SCHEMA_VERSION = 2
+# 3 (2026-07-25): chunk ids gained a ":{kind}" suffix (chunker._mk) to fix a
+# collision that silently disabled code intel. Every cached `ids` list from
+# schema 2 holds the OLD id format, so both the index and the vector cache
+# must be treated as a clean miss and rebuilt -- bumping the version is what
+# makes load()/load_vectors() do exactly that.
+SCHEMA_VERSION = 3
 
 
 def _path(cache_dir: str, repo_key: str) -> str:

webbee-0.3.35/src/webbee/intel/vectors.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+import numpy as np
+
+
+def _normalize(m: np.ndarray) -> np.ndarray:
+    n = np.linalg.norm(m, axis=1, keepdims=True)
+    n[n == 0] = 1.0
+    return (m / n).astype(np.float32)
+
+
+class VectorStore:
+    def __init__(self, dim: int) -> None:
+        self.dim = dim
+        self._ids: list[str] = []
+        self._pos: dict[str, int] = {}
+        self._mat = np.zeros((0, dim), dtype=np.float32)
+
+    def add(self, ids, vecs) -> None:
+        """Insert new ids and/or overwrite the rows of ids already present.
+
+        ORDER MATTERS: appends are materialised into `_mat` FIRST, overwrites
+        are applied only afterwards. Doing it the other way round (the pre-
+        2026-07-25 shape) wrote `_mat[self._pos[_id]]` while the rows for this
+        very batch were still sitting in a pending `rows` list, so any id
+        whose position had already been assigned but not yet vstacked indexed
+        past the end of the array -- on a fresh store that is `_mat` with
+        shape (0, dim) and the write raised IndexError. `IntelService.
+        _embed_build` calls this once with the whole repo's chunk set and
+        `boot.start_intel` swallows exceptions, so that IndexError silently
+        disabled code intel for the entire session.
+
+        A duplicate id WITHIN one batch is now also handled coherently: the
+        first occurrence appends, later ones overwrite that same row (last
+        value wins) instead of exploding.
+        """
+        vecs = np.asarray(vecs, dtype=np.float32).reshape(-1, self.dim)
+        rows = []
+        updates = []            # (row_index, vec) -- applied after the append
+        for i, _id in enumerate(ids):
+            pos = self._pos.get(_id)
+            if pos is None:
+                self._pos[_id] = len(self._ids)
+                self._ids.append(_id)
+                rows.append(vecs[i])
+            else:
+                updates.append((pos, vecs[i]))
+        if rows:
+            new_rows = np.array(rows, dtype=np.float32)
+            self._mat = (np.vstack([self._mat, new_rows])
+                         if self._mat.shape[0] else new_rows)
+        if updates:
+            if not self._mat.flags.writeable:
+                # Copy-on-write: _mat may be a read-only mmap loaded straight
+                # off the vector cache (store.load_vectors' mmap_mode="r" perf
+                # win) via from_arrays. A read-only boot+search session never
+                # reaches this branch; only an incremental re-embed of an
+                # existing chunk id (same id, changed content) needs to mutate
+                # a row in place, so pay for exactly one full copy here, lazily.
+                self._mat = np.array(self._mat)
+            for pos, vec in updates:
+                self._mat[pos] = vec
+
+    def remove(self, ids) -> None:
+        drop = {i for i in ids if i in self._pos}
+        if not drop:
+            return
+        keep = [(i, _id) for i, _id in enumerate(self._ids) if _id not in drop]
+        self._mat = self._mat[[i for i, _ in keep]] if keep else np.zeros((0, self.dim), dtype=np.float32)
+        self._ids = [_id for _, _id in keep]
+        self._pos = {_id: n for n, _id in enumerate(self._ids)}
+
+    def search(self, qvec, top_n: int):
+        if not self._ids:
+            return []
+        q = np.asarray(qvec, dtype=np.float32).reshape(self.dim)
+        qn = q / (np.linalg.norm(q) or 1.0)
+        sims = _normalize(self._mat) @ qn
+        n = min(top_n, len(self._ids))
+        idx = np.argpartition(-sims, n - 1)[:n]
+        idx = idx[np.argsort(-sims[idx])]
+        return [(self._ids[i], float(sims[i])) for i in idx]
+
+    def ids(self):
+        return list(self._ids)
+
+    def to_arrays(self):
+        return list(self._ids), self._mat.copy()
+
+    @classmethod
+    def from_arrays(cls, dim, ids, matrix):
+        vs = cls(dim)
+        vs._ids = list(ids)
+        vs._pos = {_id: n for n, _id in enumerate(vs._ids)}
+        vs._mat = np.asarray(matrix, dtype=np.float32).reshape(-1, dim)
+        return vs

{webbee-0.3.33 → webbee-0.3.35}/src/webbee/intel/watch.py

@@ -11,7 +11,9 @@ def _ignored(path: str) -> bool:
     filter works on Windows too (watchfiles yields backslash paths there --
     unfiltered .git churn re-indexed the repo on every checkpoint)."""
     p = path.replace(os.sep, "/").replace("\\", "/")
-    return "/.git/" in p or "/node_modules/" in p
+    # `.webbee/` = our own per-workspace scratch (pasted images, gitignore) —
+    # never re-index/checkpoint on a paste (W3).
+    return "/.git/" in p or "/node_modules/" in p or "/.webbee/" in p
 
 
 async def watch_workspace(root: str, on_change) -> None:

{webbee-0.3.33 → webbee-0.3.35}/src/webbee/mode_store.py

@@ -28,9 +28,33 @@ from webbee.repo import compute_repo_key, find_repo_root
 _CACHE_DIR = os.path.expanduser("~/.cache/webbee")   # test seam: monkeypatch this name
 
 
+# repo_key is derived from `git remote get-url origin` (compute_repo_key,
+# timeout=5) -- measured ~11ms per call on a warm local repo, worst case the
+# full 5s on a repo whose git call hangs. It is also INVARIANT for the life of
+# the process: a workspace's git remote does not change under a running dock.
+# Every OTHER caller already keeps that subprocess off the event loop via
+# asyncio.to_thread (repl.py's boot paths), but save_mode is reached
+# SYNCHRONOUSLY from the Shift-TAB key binding (tui `_cycle` ->
+# repl.set_slot_mode -> save_mode), i.e. straight on the event loop, where it
+# froze the dock on every single mode switch.
+#
+# Memoising per workspace fixes that for every switch after the first: the
+# repeat cost is a dict lookup. The first call in a process still pays, which
+# is acceptable because boot's own load_mode already warms this cache off-loop
+# before any key can be pressed.
+_KEY_CACHE: dict[str, str] = {}
+
+
+def _repo_key_for(workspace: str) -> str:
+    key = _KEY_CACHE.get(workspace)
+    if key is None:
+        key = compute_repo_key(find_repo_root(workspace))
+        _KEY_CACHE[workspace] = key
+    return key
+
+
 def _path_for(workspace: str) -> str:
-    repo_key = compute_repo_key(find_repo_root(workspace))
-    return os.path.join(_CACHE_DIR, f"mode-{repo_key}")
+    return os.path.join(_CACHE_DIR, f"mode-{_repo_key_for(workspace)}")
 
 
 def load_mode(workspace: str) -> "str | None":

{webbee-0.3.33 → webbee-0.3.35}/src/webbee/output_pane.py

@@ -65,6 +65,7 @@ class OutputPane:
         self._follow = True                # stick to the tail unless the user scrolled up
         self._sel = None                   # (abs_start, abs_end) during a drag → live highlight
         self._edge_drag = 0                # +1/-1 while dragging at the bottom/top edge, else 0
+        self._resize_pending = 0           # width seen but not yet reflowed (tui._width_watch debounce)
         self._edge_ticks = 0                # consecutive edge_tick()s since the last drag MOUSE_MOVE
         self._plain_cache = (0, [""])      # (write-pos, ANSI-stripped lines) for select/highlight
         self.copy_flash = ""               # transient toolbar note after a copy
@@ -335,6 +336,13 @@ class OutputPane:
         import time as _t
         return self.copy_flash if _t.monotonic() < self._flash_until else ""
 
+    def flash_note(self, msg: str, secs: float = 4.0) -> None:
+        """Show a transient toolbar note (paste progress, hints) — same channel
+        as the copy toast, reused so there's one flash mechanism."""
+        import time as _t
+        self.copy_flash = msg
+        self._flash_until = _t.monotonic() + secs
+
     # ---- W2 Task 8: selection capture past the pane's own Window --------
     def forward_mouse(self, ev, clamp: str = "bottom") -> bool:
         """Public seam neighbor windows call FIRST (via `tui._forwarding` /

{webbee-0.3.33 → webbee-0.3.35}/src/webbee/repl.py

@@ -200,6 +200,12 @@ def set_slot_mode(slot: SessionSlot, mode: str) -> None:
     save_mode(slot.workspace, mode)
 
 
+# Strong refs for in-flight autopilot confirms (see _on_mode). A module-level
+# set is safe here: entries are removed by their own done-callback, and it is
+# never read as state -- purely GC ballast.
+_CONFIRM_TASKS: set = set()
+
+
 def _on_mode(slot: SessionSlot, mode: str, surface: str) -> None:
     """Remote coding-mode request (TG/panel → gateway one-shot req_mode →
     the pending-steer poll). AUTOPILOT SAFE ASYMMETRY (Valentin-chosen): a
@@ -225,7 +231,19 @@ def _on_mode(slot: SessionSlot, mode: str, surface: str) -> None:
         set_slot_mode(slot, mode)
         _say(slot, f"mode → {mode} [{surface}]")
         return
-    asyncio.ensure_future(_confirm_autopilot(slot, surface))
+    # Keep a STRONG reference until the confirm finishes: asyncio only holds a
+    # weak one, so a bare ensure_future() can be garbage-collected mid-await
+    # and the autopilot prompt would vanish silently, leaving the user's remote
+    # upgrade request unanswered with no trace in the transcript.
+    #
+    # Deliberately NOT slot.bg_tasks: everything parked there is cancelled by
+    # the slot-close/exit teardown, and this confirm must be allowed to COMPLETE
+    # (the local yes/no is the security gate for the whole upgrade -- see
+    # _confirm_autopilot). The task removes itself via the done callback, so the
+    # set cannot grow without bound.
+    _t = asyncio.ensure_future(_confirm_autopilot(slot, surface))
+    _CONFIRM_TASKS.add(_t)
+    _t.add_done_callback(_CONFIRM_TASKS.discard)
 
 
 async def _confirm_autopilot(slot: SessionSlot, surface: str) -> None:
@@ -676,6 +694,43 @@ def _schedule_home_refill(slots: SlotManager, idx: int, fill_kwargs: dict, *,
     return True
 
 
+def _save_pasted(workspace: str, name: str, data: bytes) -> str:
+    """Save a pasted image into `<workspace>/.webbee/pasted/<name>` (that dir
+    ships a `.gitignore` of `*` so pasted files never pollute the repo or its
+    shadow-git). Returns the saved path, or "" on any failure. Never raises."""
+    try:
+        base = os.path.join(workspace, ".webbee")
+        pdir = os.path.join(base, "pasted")
+        os.makedirs(pdir, exist_ok=True)
+        gi = os.path.join(base, ".gitignore")
+        if not os.path.exists(gi):
+            with open(gi, "w", encoding="utf-8") as f:
+                f.write("*\n")
+        path = os.path.join(pdir, name)
+        with open(path, "wb") as f:
+            f.write(data)
+        return path
+    except Exception:
+        return ""
+
+
+def _extract_file_id(resp) -> str:
+    """Pull `file_id` from a file-reader `receive_files` response. Canon: it
+    lives at `data.items[].file_id` (== `.id`), NOT `data.received` (the panel's
+    Round-3 lesson). Handles dict + object shapes; "" if absent."""
+    try:
+        data = resp.get("data") if isinstance(resp, dict) else getattr(resp, "data", None)
+        items = data.get("items") if isinstance(data, dict) else getattr(data, "items", None)
+        if items:
+            it = items[0]
+            if isinstance(it, dict):
+                return str(it.get("file_id") or it.get("id") or "")
+            return str(getattr(it, "file_id", "") or getattr(it, "id", "") or "")
+    except Exception:
+        pass
+    return ""
+
+
 async def run_repl(cfg, mode: str = "default", *, once: bool = False, sink=None, read_line=input,
                    agent_factory=None, auth=None, account_fetcher=None,
                    sessions_client=None, intel_factory=None, shadow_factory=None) -> None:
@@ -1337,6 +1392,32 @@ async def run_repl(cfg, mode: str = "default", *, once: bool = False, sink=None,
                         from prompt_toolkit.application import get_app
                         get_app().exit()
 
+                async def _on_paste(ws: str, name: str, data: bytes) -> str:
+                    # W3 Wave A: save the pasted image into the tab's workspace
+                    # then upload it through the SAME file-reader door the panel
+                    # and Telegram use; return the reference to drop into the
+                    # task. Degrades honestly on 402 / no cloud (local path +
+                    # note). Never raises.
+                    import base64
+                    saved = _save_pasted(ws, name, data)
+                    try:
+                        from imperal_mcp.client import ImperalClient
+                        client = ImperalClient(cfg, token_provider)
+                        b64 = base64.b64encode(data).decode("ascii")
+                        resp = await client.run_tool(
+                            "file-reader", "receive_files",
+                            {"files": [{"name": name, "mime_type": "image/png",
+                                        "data_base64": b64}]})
+                        fid = _extract_file_id(resp)
+                        if fid:
+                            return f"📎 {name} (file_id={fid})"
+                    except Exception:
+                        pass
+                    if saved:
+                        return (f"📎 {name} — saved to {saved}; a file-reader "
+                                "plan is needed to send it to the model")
+                    return f"📎 {name} — could not upload"
+
                 try:
                     ok = await tui.run_session(
                         slots=slots, on_line=_on_line, on_cycle=_cycle,
@@ -1359,6 +1440,7 @@ async def run_repl(cfg, mode: str = "default", *, once: bool = False, sink=None,
                             spawn_poller=_spawn_slot_poller),
                         on_switch=lambda idx: _schedule_home_refill(slots, idx, home_fill_kwargs),
                         on_new=lambda: _open_new_tab(),
+                        on_paste=_on_paste,
                     )
                 finally:
                     _cancel_background()