dev-bubble 0.7.11__tar.gz → 0.7.17__tar.gz

{dev_bubble-0.7.11 → dev_bubble-0.7.17}/.claude/CLAUDE.md

@@ -96,7 +96,7 @@ created → running ⇄ paused → destroyed
 ```
 
 ### Network Allowlisting
-Uses iptables rules inside containers (not Incus ACLs) for portability across Colima/native setups. IPv6 is blocked entirely. DNS restricted to container resolver only. No outbound SSH. Base allowlist comes from config.toml; hooks contribute additional domains (e.g., Lean adds `releases.lean-lang.org`); enabled tools contribute runtime domains (e.g., vscode adds marketplace.visualstudio.com).
+Uses iptables rules inside containers (not Incus ACLs) for portability across runtimes (e.g., Colima on macOS, native Incus on Linux). IPv6 is blocked entirely. DNS restricted to container resolver only. No outbound SSH. Base allowlist comes from config.toml; hooks contribute additional domains (e.g., Lean adds `releases.lean-lang.org`); enabled tools contribute runtime domains (e.g., vscode adds marketplace.visualstudio.com).
 
 ### Editor Selection
 The default editor is VSCode via Remote SSH. Use `--shell` for a plain SSH session, `--emacs` or `--neovim` for those editors. The editor is installed as a tool in the base image (so it's pre-baked, not installed per-container). The `open_editor()` function in `vscode.py` dispatches to the appropriate launcher.
@@ -139,6 +139,8 @@ The auth proxy (`auth_proxy.py`) provides repo-scoped GitHub authentication with
 
 **gh CLI flow:** `gh` configured with `http_unix_socket: /bubble/gh-proxy.sock` (via `GH_CONFIG_DIR=/etc/bubble/gh`) → sends requests through Unix socket → proxy validates token from `Authorization` header → enforces access level (REST repo-scoping, GraphQL mutation filtering) → adds real token → forwards to `https://api.github.com`.
 
+**gh host discovery:** `git remote -v` applies `insteadOf` to displayed URLs, so `gh` sees only proxy URLs for HTTPS remotes and can't match them to `github.com`. Two mechanisms ensure `gh` works reliably: (1) `GH_REPO=owner/repo` bypasses remote URL parsing entirely — set via `/etc/profile.d/bubble-gh.sh` for login shells and via a wrapper at `/usr/local/bin/gh` that reads `/etc/bubble/gh/repo` for non-login shells; (2) a `github` remote with SSH-format URL (`git@github.com:owner/repo.git`) is added after clone as a fallback for commands that don't respect `GH_REPO`. SSH URLs bypass the HTTPS `insteadOf` rule. The `github` remote is not used for git operations — all pushes/pulls go through `origin` (which routes through the proxy).
+
 **GraphQL validation** (`graphql_validator.py`): GraphQL access is controlled by two independent axes — `graphql_read` and `graphql_write` — each supporting `whitelisted`, `unrestricted`, or `none` modes. The default is `whitelisted` for both. In whitelisted mode, a lightweight tokenizer/parser validates structure (single operation, single top-level field, no aliases/directives, no fragments in mutations) and semantics. Read validation repo-scopes `repository` queries via variables, verifies `node` queries via pre-flight ownership checks, and checks second-level fields against an allowlist. Write validation checks mutations against an allowlist (createPullRequest, addComment, mergePullRequest, etc.) with repo-scoping via repositoryId comparison or pre-flight node ownership verification.
 
 **REST security:** REST paths validated against `/repos/{owner}/{repo}/...` (repo-scoped). All HTTP methods are allowed when REST access is enabled, since path validation already constrains access to the scoped repo. API redirects (e.g. CI log downloads) followed with hardened rules: GET/HEAD only, HTTPS only, allowlisted hosts, max 2 hops, auth headers stripped. GitHub 4xx errors are passed through to clients (not collapsed to 502).

{dev_bubble-0.7.11 → dev_bubble-0.7.17}/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## Unreleased
+- Remove `--native` mode entirely
+  - `bubble --native <target>` is no longer accepted (use `bubble open` for containerized bubbles)
+  - `bubble.native` module deleted; `check_native_clean`, `open_editor_native`, and `NATIVE_DIR` removed
+  - `register_bubble()` no longer accepts `native` / `native_path`
+  - Legacy `native: true` registry entries are silently dropped on next registry load
+
+## 0.7.16 — 2026-05-07
+- Granular Claude/Codex config mounts (#264)
+  - `--claude-config/--no-claude-config` and `--codex-config/--no-codex-config` flags on `bubble open`
+  - `[claude] config` / `[codex] config` keys in `~/.bubble/config.toml`
+  - Allows mounting credentials without exposing personal `~/.claude` config items (CLAUDE.md, skills, commands, settings.json, keybindings.json) — useful for autonomous agents that need to authenticate but should not be biased by the host user's preferences
+  - `SafeConfigDir.config_mounts` gains `include_config_items` parameter (default `True`, preserves existing behavior)
+  - Flags forwarded to remote/cloud bubbles
+
 ## 0.7.1 — 2026-03-12
 - Deprecate `config security`, `config lockdown`, `config accept-risks` in favor of `security` subcommands (#150)
   - Add deprecation warnings (to stderr) when deprecated commands are used

{dev_bubble-0.7.11/dev_bubble.egg-info → dev_bubble-0.7.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dev-bubble
-Version: 0.7.11
+Version: 0.7.17
 Summary: Containerized development environments powered by Incus
 Author-email: Kim Morrison <kim@tqft.net>
 License-Expression: Apache-2.0
@@ -182,7 +182,7 @@ Each "bubble" is a lightweight Linux container (via Incus) with:
 - **IPv6 blocked**: All IPv6 traffic is dropped
 - **DNS restricted**: DNS queries only go to the container's configured resolver
 - **No outbound SSH**: Containers cannot SSH out (VSCode uses `incus exec` ProxyCommand)
-- **SSH key-only auth**: Password authentication is disabled
+- **SSH key-only auth**: Password authentication is disabled. By default only `~/.ssh/id_ed25519.pub` is injected as `authorized_keys` (with `id_rsa.pub`/`id_ecdsa.pub` as fallbacks if no ed25519 key exists). Override with `[ssh] authorized_keys = "~/.ssh/yubikey.pub"` (or a list) in `~/.bubble/config.toml`, or with the `BUBBLE_AUTHORIZED_KEYS` env var (colon-separated paths).
 - **Shell injection hardening**: All user-supplied values are quoted with `shlex.quote()`
 - **Per-repo git mount**: Each container only sees its own bare repo, not the entire git store
 - **Bubble-in-bubble relay**: Containers can open new bubbles on the host, but only for repos already cloned in `~/.bubble/git/`. Disable with `bubble security set relay off`

{dev_bubble-0.7.11 → dev_bubble-0.7.17}/README.md

@@ -148,7 +148,7 @@ Each "bubble" is a lightweight Linux container (via Incus) with:
 - **IPv6 blocked**: All IPv6 traffic is dropped
 - **DNS restricted**: DNS queries only go to the container's configured resolver
 - **No outbound SSH**: Containers cannot SSH out (VSCode uses `incus exec` ProxyCommand)
-- **SSH key-only auth**: Password authentication is disabled
+- **SSH key-only auth**: Password authentication is disabled. By default only `~/.ssh/id_ed25519.pub` is injected as `authorized_keys` (with `id_rsa.pub`/`id_ecdsa.pub` as fallbacks if no ed25519 key exists). Override with `[ssh] authorized_keys = "~/.ssh/yubikey.pub"` (or a list) in `~/.bubble/config.toml`, or with the `BUBBLE_AUTHORIZED_KEYS` env var (colon-separated paths).
 - **Shell injection hardening**: All user-supplied values are quoted with `shlex.quote()`
 - **Per-repo git mount**: Each container only sees its own bare repo, not the entire git store
 - **Bubble-in-bubble relay**: Containers can open new bubbles on the host, but only for repos already cloned in `~/.bubble/git/`. Disable with `bubble security set relay off`

{dev_bubble-0.7.11 → dev_bubble-0.7.17}/SPEC.md

@@ -51,7 +51,6 @@ equivalent to `bubble open <url>`.
 | `--network/--no-network` | flag | `--network` | Apply network allowlist |
 | `--name` | string | | Custom container name |
 | `--command` | string | | Run command via SSH (implies shell) |
-| `--native` | flag | | Non-containerized workspace |
 | `--path` | flag | | Force interpretation as local path |
 | `-b`, `--new-branch` | string | | Create a new branch |
 | `--base` | string | | Base branch for `-b` |
@@ -59,6 +58,8 @@ equivalent to `bubble open <url>`.
 | `--ai-config/--no-ai-config` | flag | enabled | Mount AI provider configs read-only |
 | `--claude-credentials/--no-claude-credentials` | flag | enabled | Mount Claude credentials |
 | `--codex-credentials/--no-codex-credentials` | flag | enabled | Mount Codex credentials |
+| `--claude-config/--no-claude-config` | flag | enabled | Mount Claude config items (CLAUDE.md, skills, commands, ...) |
+| `--codex-config/--no-codex-config` | flag | enabled | Mount Codex config items |
 | `--ssh HOST` | string | | Run on remote host |
 | `--cloud` | flag | | Run on Hetzner Cloud server |
 | `--local` | flag | | Force local execution |
@@ -251,7 +252,10 @@ forwarding doesn't work reliably through Colima on macOS.
 | `neovim` | `ssh bubble-<name> -t "cd /home/user/<repo> && nvim ."` |
 | `shell` | `ssh bubble-<name>` |
 
-For `--command CMD`: `ssh bubble-<name> <cmd args...>`
+For `--command CMD`: `ssh bubble-<name> <CMD>` — the `CMD` string is passed
+to ssh as a single argument, so it is parsed by the remote shell exactly
+as if typed after `ssh bubble-<name>` interactively. Quoting is preserved
+verbatim; no host-side `shlex.split` is performed.
 
 ### 1.10 Reattachment
 
@@ -508,9 +512,9 @@ directory's git remote.
 
 **`bubble list [--json] [-v|--verbose] [-c|--clean]`**
 
-List active bubbles. Shows local containers, native workspaces, and remote
-bubbles. Verbose mode includes IP and disk usage. Clean mode checks each
-container's cleanness status.
+List active bubbles. Shows local containers and remote bubbles. Verbose mode
+includes IP and disk usage. Clean mode checks each container's cleanness
+status.
 
 JSON output format:
 ```json
@@ -547,9 +551,6 @@ Destroy a bubble permanently:
 6. Remove relay tokens
 7. Unregister from registry
 
-**For native workspaces:** Delete the directory under `~/.bubble/native/`.
-Safety check: refuse to delete paths not under `~/.bubble/native/`.
-
 ### 4.2 Cleanness checking
 
 A container is "clean" (safe to discard) when ALL of:
@@ -579,9 +580,7 @@ A container is "clean" (safe to discard) when ALL of:
       "pr": 12345,
       "created_at": "2026-03-12T10:30:00+00:00",
       "base_image": "lean-v4.16.0",
-      "remote_host": "user@example.com",
-      "native": true,
-      "native_path": "/home/user/.bubble/native/project"
+      "remote_host": "user@example.com"
     }
   }
 }
@@ -589,7 +588,7 @@ A container is "clean" (safe to discard) when ALL of:
 
 **Always present:** `org_repo`, `branch`, `commit`, `pr`, `created_at`.
 **Conditionally present** (only written when truthy): `base_image`,
-`remote_host`, `native`, `native_path`.
+`remote_host`.
 
 Registry modifications MUST use file locking to prevent concurrent corruption.
 Writes MUST be atomic (write to temp file, rename).
@@ -617,8 +616,9 @@ on next use.
 ### 5.1 Mechanism
 
 Network allowlisting uses iptables rules **inside the container** (not Incus
-ACLs), for portability across Colima/native setups. Rules are applied by
-`incus exec` as root — the `user` account has no sudo and cannot modify them.
+ACLs), for portability across runtimes (e.g., Colima on macOS, native Incus on
+Linux). Rules are applied by `incus exec` as root — the `user` account has no
+sudo and cannot modify them.
 
 ### 5.2 Rules
 
@@ -1180,19 +1180,6 @@ enforces rate limits and (for levels below `write-graphql`) repo-scoping.
 
 ---
 
-## Native workspaces
-
-`bubble open --native <target>` creates a non-containerized workspace:
-- Clones to `~/.bubble/native/<name>/`
-- Tracked in registry with `native: true`
-- No network isolation, no container
-- `pop` deletes the directory (safety check: only under `~/.bubble/native/`)
-- `pause` is not supported
-
-**Incompatible with:** `--ssh`, `--cloud`, `--no-network`, `--machine-readable`
-
----
-
 ## Additional commands
 
 These commands support infrastructure management and are not core to the
@@ -1224,7 +1211,6 @@ container lifecycle, but a complete implementation should include them:
 | `~/.bubble/git/<repo>.git.lock` | Per-repo file locks |
 | `~/.bubble/repos.json` | Learned repo short name mappings |
 | `~/.bubble/registry.json` | Bubble state tracking |
-| `~/.bubble/native/` | Native workspace clones |
 | `~/.bubble/relay.sock` | Relay daemon Unix socket (Linux) |
 | `~/.bubble/relay.port` | Relay daemon TCP port (macOS) |
 | `~/.bubble/relay-tokens.json` | Relay auth tokens (mode 0600) |

{dev_bubble-0.7.11 → dev_bubble-0.7.17}/bubble/__init__.py

@@ -1,3 +1,3 @@
 """bubble: Containerized development environments."""
 
-__version__ = "0.7.11"
+__version__ = "0.7.17"

{dev_bubble-0.7.11 → dev_bubble-0.7.17}/bubble/ai.py

@@ -10,6 +10,7 @@ import json
 import re
 import shlex
 import subprocess
+import textwrap
 from pathlib import Path
 
 from .config import DATA_DIR
@@ -422,18 +423,27 @@ def inject_ai_task(
     )
     runtime.exec(container, ["su", "-", "user", "-c", script])
 
-    # Configure settings.json for automatic tasks
-    settings_script = (
-        f"cd {q_dir} && "
-        f'python3 -c "'
-        f"import json,os; "
-        f"p='.vscode/settings.json'; "
-        f"s=json.load(open(p)) if os.path.exists(p) else {{}}; "
-        f"s['terminal.integrated.defaultLocation']='editor'; "
-        f"s['task.allowAutomaticTasks']='on'; "
-        f"json.dump(s,open(p,'w'),indent=2)"
-        f'"'
-    )
+    # Configure settings.json for automatic tasks.
+    # The existing file may be JSONC (comments, trailing commas), so we
+    # strip those before parsing and fall back to an empty dict on failure.
+    settings_py = textwrap.dedent("""\
+        import json, re, os
+        p = '.vscode/settings.json'
+        s = {}
+        if os.path.exists(p):
+            t = open(p).read()
+            t = re.sub(r'//[^\\n]*', '', t)
+            t = re.sub(r'/\\*.*?\\*/', '', t, flags=re.DOTALL)
+            t = re.sub(r',\\s*([}\\]])', r'\\1', t)
+            try:
+                s = json.loads(t)
+            except Exception:
+                pass
+        s['terminal.integrated.defaultLocation'] = 'editor'
+        s['task.allowAutomaticTasks'] = 'on'
+        json.dump(s, open(p, 'w'), indent=2)
+    """)
+    settings_script = f"cd {q_dir} && python3 -c {shlex.quote(settings_py)}"
     runtime.exec(container, ["su", "-", "user", "-c", settings_script])
 
     # Add generated files to git exclude

{dev_bubble-0.7.11 → dev_bubble-0.7.17}/bubble/auth_proxy.py

@@ -39,6 +39,7 @@ import os
 import re
 import ssl
 import threading
+import time
 from http.server import BaseHTTPRequestHandler, HTTPServer
 from urllib.error import HTTPError
 from urllib.parse import urlparse
@@ -74,6 +75,14 @@ RATE_LIMIT_PER_HOUR = 600
 # Maximum tracked containers
 MAX_TRACKED_CONTAINERS = 100
 
+# Pre-flight result cache TTLs (seconds). Positive results are cached longer
+# to avoid re-querying for legitimate repeated mutations on the same node.
+# Negative results are cached briefly to blunt loops on bad/never-resolving IDs
+# without keeping stale "missing" answers around.
+PREFLIGHT_POSITIVE_CACHE_TTL = 300.0
+PREFLIGHT_NEGATIVE_CACHE_TTL = 60.0
+MAX_PREFLIGHT_CACHE_ENTRIES = 1024
+
 # ---------------------------------------------------------------------------
 # Path patterns
 # ---------------------------------------------------------------------------
@@ -118,6 +127,40 @@ _REDIRECT_ALLOWED_HOSTS = [
     "*.githubusercontent.com",
 ]
 
+# Response headers stripped before forwarding to the container. The container
+# authenticates to the proxy with its bubble token only — no other state should
+# bridge container and GitHub. The hop-by-hop entries are stripped because the
+# proxy terminates the upstream connection (RFC 7230 §6.1). The remaining
+# entries close auxiliary channels: Authorization / Proxy-Authorization could
+# echo upstream credentials; Set-Cookie would let GitHub (or an attacker
+# substituting an upstream response) plant client-side state the container
+# could replay against an exfil target; WWW-Authenticate / Proxy-Authenticate
+# prompt the client into a separate auth scheme outside the bubble token model.
+_STRIPPED_RESPONSE_HEADERS = frozenset(
+    {
+        # Hop-by-hop (RFC 7230 §6.1)
+        "transfer-encoding",
+        "connection",
+        "keep-alive",
+        "te",
+        "trailer",
+        "upgrade",
+        "proxy-authenticate",
+        "proxy-authorization",
+        # Auxiliary auth/state channels
+        "authorization",
+        "set-cookie",
+        "www-authenticate",
+    }
+)
+
+# On 4xx responses the Location header is purely informational (no redirect
+# follow happens) and would disclose upstream redirect targets — including
+# blob-storage URLs that already passed our redirect allowlist. Strip it on
+# error pass-through but keep it on 3xx so the container can follow redirects
+# the proxy explicitly chose not to handle.
+_STRIPPED_4XX_RESPONSE_HEADERS = _STRIPPED_RESPONSE_HEADERS | {"location"}
+
 logger = logging.getLogger("bubble.auth_proxy")
 
 
@@ -467,10 +510,13 @@ def _is_redirect_host_allowed(host: str) -> bool:
 
 def _follow_redirect(
     location: str, hops_remaining: int, method: str = "GET"
-) -> tuple[int, dict, bytes]:
+) -> tuple[int, list[tuple[str, str]], bytes]:
     """Follow a redirect URL with hardened rules.
 
-    Returns (status_code, headers_dict, body).
+    Returns (status_code, headers_list, body). Headers are returned as a
+    list of (name, value) tuples to preserve repeated headers (e.g. Link
+    pagination headers).
+
     Raises ValueError on policy violations.
     """
     parsed = urlparse(location)
@@ -513,8 +559,7 @@ def _follow_redirect(
             raise ValueError("Redirect response too large")
         body_parts.append(chunk)
 
-    headers = {k: v for k, v in resp.getheaders()}
-    return resp.status, headers, b"".join(body_parts)
+    return resp.status, resp.getheaders(), b"".join(body_parts)
 
 
 # ---------------------------------------------------------------------------
@@ -604,6 +649,18 @@ class AuthProxyHandler(BaseHTTPRequestHandler):
     _repo_node_id_cache: dict[tuple[str, str], str] = {}
     _repo_node_id_lock = threading.Lock()
 
+    # Pre-flight node-id resolution cache. Stores both positive and negative
+    # results with TTLs to avoid re-querying GitHub for repeated probes.
+    # Maps node_id -> (resolved_repo_or_None, expiry_unix_ts).
+    _preflight_cache: dict[str, tuple[str | None, float]] = {}
+    _preflight_cache_lock = threading.Lock()
+
+    # In-flight singleflight tracking. Prevents the threaded HTTP server from
+    # firing N concurrent host-side preflights for the same node id when N
+    # handlers all miss the cache simultaneously.
+    _preflight_inflight: dict[str, threading.Event] = {}
+    _preflight_inflight_lock = threading.Lock()
+
     def log_message(self, format, *args):
         """Route HTTP server logs to our logger."""
         logger.info(format, *args)
@@ -625,6 +682,13 @@ class AuthProxyHandler(BaseHTTPRequestHandler):
             return auth[7:].strip()
         return None
 
+    def _copy_response_headers(self, headers_iter, stripped=_STRIPPED_RESPONSE_HEADERS):
+        """Forward upstream response headers, dropping anything in `stripped`."""
+        for header, value in headers_iter:
+            if header.lower() in stripped:
+                continue
+            self.send_header(header, value)
+
     def _authenticate(self) -> dict | None:
         """Authenticate the request via X-Bubble-Token.
 
@@ -842,8 +906,8 @@ class AuthProxyHandler(BaseHTTPRequestHandler):
                     parsed,
                     owner,
                     repo,
-                    preflight_fn=self._preflight_check,
-                    repo_node_id_fn=self._get_repo_node_id,
+                    preflight_fn=lambda nid: self._preflight_check(nid, container),
+                    repo_node_id_fn=lambda o, r: self._get_repo_node_id(o, r, container),
                 )
                 if error:
                     self._send_error(403, f"GraphQL mutation validation failed: {error}")
@@ -867,7 +931,7 @@ class AuthProxyHandler(BaseHTTPRequestHandler):
                     parsed,
                     owner,
                     repo,
-                    preflight_fn=self._preflight_check,
+                    preflight_fn=lambda nid: self._preflight_check(nid, container),
                 )
                 if error:
                     self._send_error(403, f"GraphQL read validation failed: {error}")
@@ -898,14 +962,28 @@ class AuthProxyHandler(BaseHTTPRequestHandler):
         resp = opener.open(req, timeout=30)
         return json.loads(resp.read())
 
-    def _get_repo_node_id(self, owner: str, repo: str) -> str | None:
-        """Get the GitHub node ID for a repository. Cached."""
+    def _get_repo_node_id(self, owner: str, repo: str, container: str) -> str | None:
+        """Get the GitHub node ID for a repository. Cached.
+
+        Counts uncached upstream queries against the originating container's
+        rate window so misbehaving containers can't burn the host's GitHub
+        quota through preflight traffic.
+        """
         key = (owner.lower(), repo.lower())
         with self._repo_node_id_lock:
             cached = self._repo_node_id_cache.get(key)
             if cached is not None:
                 return cached
 
+        if not self.rate_limiter.check(container):
+            logger.info(
+                "PREFLIGHT rate-limited container=%s repo_id_lookup=%s/%s",
+                container,
+                owner,
+                repo,
+            )
+            return None
+
         from .graphql_validator import REPO_ID_QUERY
 
         try:
@@ -919,19 +997,114 @@ class AuthProxyHandler(BaseHTTPRequestHandler):
             logger.info("PREFLIGHT repo_node_id failed for %s/%s", owner, repo)
             return None
 
-    def _preflight_check(self, node_id: str) -> str | None:
+    def _preflight_cache_get(self, node_id: str) -> tuple[bool, str | None]:
+        """Look up a preflight result in the cache. Returns (hit, value)."""
+        now = time.time()
+        with self._preflight_cache_lock:
+            cached = self._preflight_cache.get(node_id)
+            if cached is None:
+                return False, None
+            value, expiry = cached
+            if expiry <= now:
+                # Expired: drop and miss.
+                self._preflight_cache.pop(node_id, None)
+                return False, None
+            return True, value
+
+    def _preflight_cache_put(self, node_id: str, value: str | None) -> None:
+        """Cache a preflight result with TTL based on positive/negative."""
+        ttl = PREFLIGHT_POSITIVE_CACHE_TTL if value else PREFLIGHT_NEGATIVE_CACHE_TTL
+        expiry = time.time() + ttl
+        with self._preflight_cache_lock:
+            # Bound the cache: drop the entry with the soonest expiry if full.
+            if (
+                len(self._preflight_cache) >= MAX_PREFLIGHT_CACHE_ENTRIES
+                and node_id not in self._preflight_cache
+            ):
+                oldest = min(self._preflight_cache, key=lambda k: self._preflight_cache[k][1])
+                self._preflight_cache.pop(oldest, None)
+            self._preflight_cache[node_id] = (value, expiry)
+
+    def _preflight_check(self, node_id: str, container: str) -> str | None:
         """Check which repo a node belongs to.
 
-        Returns "owner/repo" string or None on failure.
+        Returns "owner/repo" string or None on failure / unverifiable.
+
+        Counts uncached upstream queries against the originating container's
+        rate window so misbehaving containers can't burn the host's GitHub
+        quota through preflight traffic. Caches both positive results and
+        definitive negative answers from GitHub with short TTLs so repeated
+        probes for the same ID don't re-query at all. Transient failures
+        (network errors, timeouts, GraphQL-level errors) are NOT cached, to
+        avoid one upstream blip locking out a legitimate node ID for 60s.
+
+        Concurrent misses for the same node id are serialized via a per-id
+        singleflight so a flood of parallel handlers can't fan out into N
+        host-side calls before the first one populates the cache.
         """
-        from .graphql_validator import PREFLIGHT_QUERY, extract_repo_from_preflight
+        hit, value = self._preflight_cache_get(node_id)
+        if hit:
+            return value
+
+        # Singleflight: at most one upstream query per node id at a time.
+        # If another handler is already querying, wait for its result then
+        # re-check the cache. If the cache still misses (transient failure
+        # — those aren't cached), fall through and try again ourselves,
+        # subject to the rate limiter.
+        while True:
+            with self._preflight_inflight_lock:
+                event = self._preflight_inflight.get(node_id)
+                if event is None:
+                    event = threading.Event()
+                    self._preflight_inflight[node_id] = event
+                    is_leader = True
+                else:
+                    is_leader = False
+            if is_leader:
+                break
+            # Wait modestly longer than the upstream timeout (30s) so a
+            # stuck leader can't pin us forever.
+            event.wait(timeout=35)
+            hit, value = self._preflight_cache_get(node_id)
+            if hit:
+                return value
+            # Cache miss after the leader finished — leader saw a transient
+            # failure and didn't cache. Loop to take the leader role.
 
         try:
-            data = self._github_graphql_query(PREFLIGHT_QUERY, {"id": node_id})
-            return extract_repo_from_preflight(data)
-        except Exception:
-            logger.info("PREFLIGHT check failed for node %s", node_id)
-            return None
+            if not self.rate_limiter.check(container):
+                logger.info(
+                    "PREFLIGHT rate-limited container=%s node_id=%s",
+                    container,
+                    node_id,
+                )
+                # Don't cache: the rate-limit decision is per-container/
+                # per-window, not a property of the node ID.
+                return None
+
+            from .graphql_validator import PREFLIGHT_QUERY, extract_repo_from_preflight
+
+            try:
+                data = self._github_graphql_query(PREFLIGHT_QUERY, {"id": node_id})
+            except Exception:
+                logger.info("PREFLIGHT check failed for node %s", node_id)
+                # Transient (HTTP error / timeout / network): don't cache.
+                return None
+
+            # Treat GraphQL-level errors as transient too: a 200 with an
+            # `errors` array can be a server hiccup ("Something went wrong",
+            # secondary rate limit, etc.) and shouldn't poison the cache.
+            if isinstance(data, dict) and data.get("errors"):
+                logger.info("PREFLIGHT graphql errors for node %s", node_id)
+                return None
+
+            result = extract_repo_from_preflight(data)
+            self._preflight_cache_put(node_id, result)
+            return result
+        finally:
+            with self._preflight_inflight_lock:
+                self._preflight_inflight.pop(node_id, None)
+            event.set()
 
     def _forward_to_github(
         self,
@@ -991,11 +1164,7 @@ class AuthProxyHandler(BaseHTTPRequestHandler):
                     return
                 # For git or non-followable redirects, return as-is
                 self.send_response(e.code)
-                for header, value in e.headers.items():
-                    lower = header.lower()
-                    if lower in ("transfer-encoding", "connection", "keep-alive"):
-                        continue
-                    self.send_header(header, value)
+                self._copy_response_headers(e.headers.items())
                 self.end_headers()
                 body_data = e.read()
                 if body_data:
@@ -1035,14 +1204,9 @@ class AuthProxyHandler(BaseHTTPRequestHandler):
             # Pass through 4xx errors from GitHub (auth failures, not found, etc.)
             if 400 <= e.code < 500:
                 self.send_response(e.code)
-                for header, value in e.headers.items():
-                    lower = header.lower()
-                    if lower in ("transfer-encoding", "connection", "keep-alive"):
-                        continue
-                    # Strip GitHub's auth-related headers
-                    if lower == "authorization":
-                        continue
-                    self.send_header(header, value)
+                self._copy_response_headers(
+                    e.headers.items(), stripped=_STRIPPED_4XX_RESPONSE_HEADERS
+                )
                 self.end_headers()
                 body_data = e.read()
                 if body_data:
@@ -1079,11 +1243,7 @@ class AuthProxyHandler(BaseHTTPRequestHandler):
 
         # Send response back to client
         self.send_response(resp.status)
-        for header, value in resp.getheaders():
-            lower = header.lower()
-            if lower in ("transfer-encoding", "connection", "keep-alive"):
-                continue
-            self.send_header(header, value)
+        self._copy_response_headers(resp.getheaders())
         self.end_headers()
 
         # Stream response body
@@ -1119,11 +1279,13 @@ class AuthProxyHandler(BaseHTTPRequestHandler):
             return
 
         self.send_response(status)
-        for header, value in headers.items():
-            lower = header.lower()
-            if lower in ("transfer-encoding", "connection", "keep-alive"):
-                continue
-            self.send_header(header, value)
+        # Defensive: today _follow_redirect only returns on 2xx (HTTPError is
+        # raised above and converted to 502), but if that ever changes, keep
+        # the same Location-strip rule that direct 4xx pass-through uses.
+        stripped = (
+            _STRIPPED_4XX_RESPONSE_HEADERS if 400 <= status < 500 else _STRIPPED_RESPONSE_HEADERS
+        )
+        self._copy_response_headers(headers, stripped=stripped)
         self.end_headers()
         if body:
             self.wfile.write(body)
@@ -1234,23 +1396,45 @@ def _get_github_token() -> str:
     the stored access token has expired, then reads the (now-current)
     token via ``gh auth token``.
     """
+    import shutil
     import subprocess
 
+    gh_path = shutil.which("gh")
+    if not gh_path:
+        raise RuntimeError(
+            "Cannot find 'gh' CLI on PATH. Install gh (https://cli.github.com) "
+            "and ensure it is on your PATH.\n"
+            f"Current PATH: {os.environ.get('PATH', '(not set)')}"
+        )
+
     # Trigger OAuth refresh (gh auth token alone returns the stale token)
     try:
         subprocess.run(
-            ["gh", "auth", "status"],
+            [gh_path, "auth", "status"],
             capture_output=True,
             timeout=15,
         )
-    except (FileNotFoundError, subprocess.TimeoutExpired):
+    except subprocess.TimeoutExpired:
         pass  # Best-effort; get_host_gh_token may still succeed
 
     from .github_token import get_host_gh_token
 
     token = get_host_gh_token()
     if not token:
-        raise RuntimeError("No GitHub token available. Run 'gh auth login' first.")
+        # Try to get more diagnostic info
+        try:
+            result = subprocess.run(
+                [gh_path, "auth", "token"],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            detail_msg = f"gh auth token exited {result.returncode}"
+            if result.stderr.strip():
+                detail_msg += f": {result.stderr.strip()}"
+        except Exception as e:
+            detail_msg = f"gh auth token failed: {e}"
+        raise RuntimeError(f"No GitHub token available. {detail_msg}\nRun 'gh auth login' first.")
     return token