screenforge 0.7.0__tar.gz → 0.11.0__tar.gz

{screenforge-0.7.0 → screenforge-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: screenforge
-Version: 0.7.0
+Version: 0.11.0
 Summary: AI-driven cross-platform UI automation engine with test script generation
 License: MIT
 Project-URL: Homepage, https://github.com/jhinzzz/ScreenForge
@@ -120,6 +120,8 @@ Each step: **inspect → decide → act → verify**. The AI decides, ScreenForg
 - **Structured output**: JSON Lines events + `report/runs/<id>/` artifacts for CI integration
 - **Live Mirror playground**: Watch the generated pytest code grow line-by-line beside a live screenshot as the test runs — `screenforge --playground`. See the [Playground Guide](https://github.com/jhinzzz/ScreenForge/blob/main/docs/playground-guide.md)
 - **Execution-replay review report**: Run any test with `REVIEW_RECORD=1` and get a self-contained, shareable offline `report.html` — a drag-timeline of each step's screenshot + the test source line that triggered it + the DOM tree, plus a `video.gif` filmstrip. Default off, zero overhead. (Web verified; mobile registry/recording seam in place but unverified.)
+- **Case memory hints on `inspect_ui`**: pass an optional `task` label and the payload's `memory` field carries what the last run of that task did — locator, counts, and outcome — a hint the Agent weighs against the live tree, seen before it acts, never auto-replayed. It records failures too, so check `last_status`/`success_count` before trusting a hint. The label must match the one the earlier run recorded (`--action-name`, else `"{action}:{locator_value}"`); `load_case_memory` lists them. See the [Agent Guide](https://github.com/jhinzzz/ScreenForge/blob/main/docs/agent_guide.md).
+- **Plain-language element lookup on `inspect_ui`**: pass an optional `intent` phrase (e.g. `"登录按钮"`) and the payload's `candidates` field returns up to 3 ranked elements with ready-to-use locators — additive to the full `ui_tree`, never a replacement. Matching is literal string similarity, not semantic, so phrase `intent` in the same language as the UI. See the [Agent Guide](https://github.com/jhinzzz/ScreenForge/blob/main/docs/agent_guide.md).
 
 ## Agent Integration (Claude Code / Cursor / Codex)
 

{screenforge-0.7.0 → screenforge-0.11.0}/README.md

@@ -75,6 +75,8 @@ Each step: **inspect → decide → act → verify**. The AI decides, ScreenForg
 - **Structured output**: JSON Lines events + `report/runs/<id>/` artifacts for CI integration
 - **Live Mirror playground**: Watch the generated pytest code grow line-by-line beside a live screenshot as the test runs — `screenforge --playground`. See the [Playground Guide](https://github.com/jhinzzz/ScreenForge/blob/main/docs/playground-guide.md)
 - **Execution-replay review report**: Run any test with `REVIEW_RECORD=1` and get a self-contained, shareable offline `report.html` — a drag-timeline of each step's screenshot + the test source line that triggered it + the DOM tree, plus a `video.gif` filmstrip. Default off, zero overhead. (Web verified; mobile registry/recording seam in place but unverified.)
+- **Case memory hints on `inspect_ui`**: pass an optional `task` label and the payload's `memory` field carries what the last run of that task did — locator, counts, and outcome — a hint the Agent weighs against the live tree, seen before it acts, never auto-replayed. It records failures too, so check `last_status`/`success_count` before trusting a hint. The label must match the one the earlier run recorded (`--action-name`, else `"{action}:{locator_value}"`); `load_case_memory` lists them. See the [Agent Guide](https://github.com/jhinzzz/ScreenForge/blob/main/docs/agent_guide.md).
+- **Plain-language element lookup on `inspect_ui`**: pass an optional `intent` phrase (e.g. `"登录按钮"`) and the payload's `candidates` field returns up to 3 ranked elements with ready-to-use locators — additive to the full `ui_tree`, never a replacement. Matching is literal string similarity, not semantic, so phrase `intent` in the same language as the UI. See the [Agent Guide](https://github.com/jhinzzz/ScreenForge/blob/main/docs/agent_guide.md).
 
 ## Agent Integration (Claude Code / Cursor / Codex)
 

screenforge-0.11.0/cli/_version.py

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

{screenforge-0.7.0 → screenforge-0.11.0}/cli/modes/action.py

@@ -26,6 +26,7 @@ from cli.shared import (
     save_to_disk,
 )
 from common.failure_diagnosis import diagnose
+from common.observation import build_observation
 from common.runtime_modes import MODE_RUN
 
 
@@ -69,9 +70,11 @@ def build_failure_payload(
         ui_elements=ui_tree.get("ui_elements", []) or [],
     )
     payload.update(diag.to_dict())
-    payload["ui_tree"] = ui_tree
-    payload["element_count"] = len(ui_tree.get("ui_elements", []) or [])
-    payload["current_url"] = current_url
+    observation = build_observation(ui_tree=ui_tree, current_url=current_url)
+    observation.pop("screenshot_base64")  # engine_error has never carried one
+    observation.pop("memory")             # decision-time hint; action is post-decision
+    observation.pop("candidates")  # engine_error already has its own diagnosis candidates
+    payload.update(observation)
     return payload
 
 
@@ -88,14 +91,16 @@ def build_success_payload(
     Single source of truth shared by the shell --json stdout write and the MCP
     observation stash, so the two can never drift. Pure: no I/O, no device.
     """
+    observation = build_observation(ui_tree=ui_tree, current_url=current_url)
+    observation.pop("screenshot_base64")  # action payloads have never carried one
+    observation.pop("memory")             # decision-time hint; action is post-decision
+    observation.pop("candidates")  # engine_error already has its own diagnosis candidates
     return {
         "ok": True,
         "action": action_name,
         "platform": platform,
-        "ui_tree": ui_tree,
-        "element_count": len(ui_tree.get("ui_elements", []) or []),
+        **observation,
         "output_script": output_script,
-        "current_url": current_url,
     }
 
 

{screenforge-0.7.0 → screenforge-0.11.0}/cli/modes/default.py

@@ -58,6 +58,7 @@ def run_default_mode(
         step_count = 0
         last_error = ""
         consecutive_failures = 0
+        consecutive_not_found = 0
         last_ui_json = ""
 
         while step_count < args.max_steps:
@@ -177,11 +178,27 @@ def run_default_mode(
                         success=False,
                         action_description="not_found",
                     )
+                    # not_found is exempt from the failure circuit breaker so vision
+                    # gets a chance, but a model stuck returning it makes no progress
+                    # and burns one LLM call per step up to max_steps (token bleed).
+                    # Cap consecutive not_found at the same threshold and stop.
+                    consecutive_not_found += 1
+                    if consecutive_not_found >= args.max_retries:
+                        final_error = (
+                            f"Stopped after {consecutive_not_found} consecutive 'not_found' — "
+                            f"target never appeared in the UI tree."
+                        )
+                        log.error(
+                            f"[E025] {consecutive_not_found} consecutive 'not_found'. "
+                            f"Fix: re-run with --vision, or refine --goal / scroll the target into view."
+                        )
+                        return 1
                     continue
                 else:
                     result = executor.execute_and_record(action_data)
                     if result.get("success"):
                         consecutive_failures = 0
+                        consecutive_not_found = 0
                         history_manager.add_step(
                             result["code_lines"], result["action_description"]
                         )

{screenforge-0.7.0 → screenforge-0.11.0}/cli/session.py

@@ -108,6 +108,30 @@ def start_session_recording(session_id: str, platform: str, udid: str = "") -> s
     return video_path
 
 
+def _reap_with_timeout(pid: int, timeout: float) -> None:
+    """Wait for a signalled recording process to exit, then SIGKILL if it won't.
+
+    Bare os.waitpid(pid, 0) blocks forever — if `xcrun simctl recordVideo` ever
+    ignores SIGINT, --session-end would hang the whole CLI. Poll with WNOHANG up
+    to `timeout`, then SIGKILL and reap so we never block indefinitely.
+    """
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            reaped, _ = os.waitpid(pid, os.WNOHANG)
+        except ChildProcessError:
+            return  # already reaped elsewhere
+        if reaped:
+            return
+        time.sleep(0.1)
+    # Still alive after the grace period — kill hard and reap the zombie.
+    try:
+        os.kill(pid, signal.SIGKILL)
+        os.waitpid(pid, 0)
+    except OSError:
+        pass
+
+
 def stop_session_recording(session_id: str) -> str:
     session = load_session(session_id)
     if not session:
@@ -120,7 +144,7 @@ def stop_session_recording(session_id: str) -> str:
     try:
         pgid = os.getpgid(pid)
         os.killpg(pgid, signal.SIGINT)
-        os.waitpid(pid, 0)
+        _reap_with_timeout(pid, timeout=10.0)
     except OSError:
         try:
             os.kill(pid, signal.SIGINT)

{screenforge-0.7.0 → screenforge-0.11.0}/cli/tool_protocol_handlers.py

@@ -20,6 +20,8 @@ from cli.shared import (
     current_url,
     log,
 )
+from common.failure_diagnosis import rank_candidates
+from common.observation import build_observation
 from common.run_resume import RunContextLoadError, load_run_bundle
 from common.runtime_modes import MODE_DOCTOR, resolve_execution_mode
 from common.tool_protocol import (
@@ -137,6 +139,30 @@ def _find_case_memory_hit(args, execution_mode: str) -> dict | None:
     )
 
 
+def _lookup_task_memory(platform: str, task: str) -> dict:
+    """Case-memory hint for an inspect_ui request, or {} when there's nothing.
+
+    A HINT, not an instruction — see common/observation.py. Matching is fuzzy by
+    design (find_entry ORs control_label with source_ref), so a wrong hit costs
+    one useless hint, never a wrong click. control_kind is "action" because an
+    inspect precedes a single action, and that's the kind those runs record under.
+    Any read failure degrades to {}: a missing hint must never cost the agent
+    its UI tree.
+    """
+    if not str(task).strip():
+        return {}
+    try:
+        entry = _load_case_memory_store().find_entry(
+            platform=platform,
+            control_kind="action",
+            control_label=task,
+        )
+    except Exception as e:
+        log.warning(f"⚠️ [Warning] Case-memory lookup failed, continuing without hint: {e}")
+        return {}
+    return entry or {}
+
+
 def build_load_case_memory_payload(
     platform: str = "",
     control_kind: str = "",
@@ -182,13 +208,6 @@ def build_inspect_ui_payload(request, shared_adapter_manager: _SharedAdapterMana
             1,
         )
 
-        if not screenshot_base64:
-            try:
-                img_bytes = adapter.take_screenshot()
-                screenshot_base64 = base64.b64encode(img_bytes).decode("utf-8")
-            except Exception as e:
-                log.warning(f"⚠️ [Warning] inspect_ui screenshot capture failed: {e}")
-
         try:
             ui_tree = json.loads(ui_json)
         except json.JSONDecodeError:
@@ -207,30 +226,36 @@ def build_inspect_ui_payload(request, shared_adapter_manager: _SharedAdapterMana
             except Exception as e:
                 log.warning(f"⚠️ [Warning] Failed to sync ref cache from inspect_ui: {e}")
 
-        annotated_screenshot_base64 = ""
+        # Annotate in place: ref labels are only meaningful where the compressor
+        # emits ref + bbox + clickable (web). Mobile trees carry none of those, so
+        # annotate_screenshot draws nothing and just re-encodes the image — same
+        # picture, no labels. Either way exactly ONE image ships.
         if screenshot_base64 and ui_tree.get("ui_elements"):
             try:
                 from utils.screenshot_annotator import annotate_screenshot
                 raw_bytes = base64.b64decode(screenshot_base64)
                 annotated_bytes = annotate_screenshot(raw_bytes, ui_tree["ui_elements"])
-                annotated_screenshot_base64 = base64.b64encode(annotated_bytes).decode("utf-8")
+                screenshot_base64 = base64.b64encode(annotated_bytes).decode("utf-8")
             except Exception as e:
                 log.warning(f"⚠️ [Warning] Annotated screenshot generation failed: {e}")
 
-        page_url = current_url(adapter, request.platform)
-
         return {
             "ok": True,
             "operation": "inspect_ui",
             "exit_code": 0,
             "platform": request.platform,
             "env": request.env,
-            "ui_json": ui_json,
-            "ui_tree": ui_tree,
-            "element_count": len(ui_tree.get("ui_elements", []) or []),
-            "screenshot_base64": screenshot_base64 or "",
-            "annotated_screenshot_base64": annotated_screenshot_base64,
-            "current_url": page_url,
+            **build_observation(
+                ui_tree=ui_tree,
+                current_url=current_url(adapter, request.platform),
+                screenshot_base64=screenshot_base64 or "",
+                memory=_lookup_task_memory(request.platform, request.task),
+                candidates=(
+                    rank_candidates(request.intent, ui_tree.get("ui_elements") or [])
+                    if str(request.intent).strip()
+                    else []
+                ),
+            ),
         }
     except Exception as e:
         return {
@@ -241,6 +266,8 @@ def build_inspect_ui_payload(request, shared_adapter_manager: _SharedAdapterMana
             "env": request.env,
             "error": str(e),
             "current_url": "",
+            "memory": {},
+            "candidates": [],
         }
     finally:
         if owns_adapter and adapter:

{screenforge-0.7.0 → screenforge-0.11.0}/common/ai.py

@@ -1,4 +1,5 @@
 import json
+import re
 import time
 
 from openai import OpenAI
@@ -18,6 +19,39 @@ def _strip_json_fences(text: str) -> str:
     return text
 
 
+# Endpoints (base_url) that 400'd on response_format — never retried with it.
+# response_format={"type":"json_object"} cuts malformed responses (fewer retries,
+# fewer tokens), but is NOT universal across OpenAI-compatible endpoints, which
+# this tool promises to support. So: try once per endpoint, remember a rejection,
+# and fall back to a plain call forever after. Prompts already say "output JSON".
+_JSON_MODE_UNSUPPORTED: set = set()
+
+
+def chat_completion_json(client, **kwargs):
+    """chat.completions.create that requests JSON mode when the endpoint allows.
+
+    Detect-once per endpoint: on the first 400-style rejection of response_format
+    we record the base_url and never send it again, so an endpoint without JSON
+    mode pays one failed call total, not one per request.
+    """
+    endpoint = str(getattr(client, "base_url", ""))
+    if endpoint not in _JSON_MODE_UNSUPPORTED:
+        try:
+            return client.chat.completions.create(
+                response_format={"type": "json_object"}, **kwargs
+            )
+        except Exception as e:
+            # Only json-mode-shaped rejections fall back; real network/auth errors
+            # must surface to the caller's existing try/except unchanged.
+            msg = str(e).lower()
+            if "response_format" in msg or "json" in msg or "not support" in msg:
+                log.warning(f"[AI] Endpoint rejected JSON mode, falling back for {endpoint}")
+                _JSON_MODE_UNSUPPORTED.add(endpoint)
+            else:
+                raise
+    return client.chat.completions.create(**kwargs)
+
+
 class AIBrain:
     def __init__(self):
         # 实例化文本专属客户端
@@ -39,20 +73,48 @@ class AIBrain:
 
     def _verify_locator_in_ui(self, decision: dict, ui_dict: dict) -> bool:
         """
-        校验缓存中推荐的动作，其元素是否真实存在于当前的 UI 树中
+        校验缓存中推荐的动作，其元素是否真实存在于当前的 UI 树中。
+
+        L2 是跨页面的全局语义缓存，一条决策可能命中一个并不存在该元素的页面。
+        本方法是那道安全网：能确认元素不存在时返回 False 丢弃该命中；无法确认
+        （元素无该属性、选择器无法解析）时放行，绝不误伤有效缓存。
         """
         loc_type = decision.get("locator_type")
         loc_val = decision.get("locator_value")
 
-        # 如果动作不需要特定元素 (比如 answer 或某些全局操作)，直接放行
-        if (
-            not loc_type
-            or not loc_val
-            or loc_type not in ["text", "description", "resourceId", "id"]
-        ):
+        # 无定位需求 (swipe / press 等全局动作) 直接放行
+        if not loc_type or not loc_val:
             return True
 
         elements = ui_dict.get("ui_elements", [])
+
+        # css 是 Web 端最常用的定位器 (Prompt 铁律排第一)，且 L2 是跨页面全局缓存，
+        # 因此必须校验而非放行。压缩后的 Web 树只能确认执行器自己产出的两种形态:
+        # `#id` -> 元素 id，`[name="x"]` -> 元素 name (见 executor.LocatorBuilder)。
+        # 其它选择器 (class/标签/后代) 树里无法还原，判为无法确认 -> 放行。
+        if loc_type == "css":
+            # Only a SIMPLE selector round-trips to a tree attribute. The charset
+            # excludes CSS combinators/escapes (space > + ~ , . [ : \) on purpose:
+            # `#form input` and `#user\.email` are compound or escaped, so the raw
+            # string never equals an `id` value — comparing anyway would discard a
+            # VALID L2 hit and force a fresh paid LLM call, inverting this method's
+            # purpose. Unverifiable → pass through.
+            simple = r"[^\s>+~,.\[\]:\\#]+"
+            m = re.fullmatch(rf"#({simple})", loc_val) or re.fullmatch(
+                rf'\[name="({simple})"\]', loc_val
+            )
+            if not m:
+                return True
+            attr = "id" if loc_val.startswith("#") else "name"
+            target = m.group(1)
+            values = [el.get(attr) for el in elements if el.get(attr)]
+            if not values:  # 树里没有任何该属性 -> 无从确认 -> 放行
+                return True
+            return target in values
+
+        if loc_type not in ["text", "description", "resourceId", "id"]:
+            return True
+
         for el in elements:
             if loc_type == "text" and el.get("text") == loc_val:
                 return True
@@ -263,7 +325,8 @@ class AIBrain:
         result_text = ""
         try:
             with ai_status(f"Thinking ({model_name})..."):
-                response = client.chat.completions.create(
+                response = chat_completion_json(
+                    client,
                     model=model_name,
                     messages=[
                         {"role": "system", "content": system_prompt},

{screenforge-0.7.0 → screenforge-0.11.0}/common/ai_autonomous.py

@@ -1,7 +1,7 @@
 import json
 
 import config.config as config
-from common.ai import AIBrain, _strip_json_fences
+from common.ai import AIBrain, _strip_json_fences, chat_completion_json
 from common.logs import log
 from common.progress import ai_status
 
@@ -80,7 +80,8 @@ class AutonomousBrain(AIBrain):
         result_text = ""
         try:
             with ai_status("Planning execution steps..."):
-                response = active_client.chat.completions.create(
+                response = chat_completion_json(
+                    active_client,
                     model=active_model,
                     messages=[
                         {"role": "system", "content": system_prompt},
@@ -225,7 +226,8 @@ class AutonomousBrain(AIBrain):
         result_text = ""
         try:
             with ai_status("Reasoning about next action..."):
-                response = active_client.chat.completions.create(
+                response = chat_completion_json(
+                    active_client,
                     model=active_model,
                     messages=[
                         {"role": "system", "content": system_prompt},

screenforge-0.11.0/common/cache/cache_hash.py

@@ -0,0 +1,88 @@
+import hashlib
+import json
+import re
+from typing import Any, Dict
+
+_BLOCKLIST = frozenset(
+    [
+        "加密货币",
+        "比特币",
+        "meme币",
+        "美股代币",
+        "贵金属代币",
+        "热门资产",
+        "已上线",
+        "已上架",
+        "上架",
+        "下架",
+        "公告",
+        "活动",
+    ]
+)
+
+
+def _latin_anchor(raw_text: str) -> str:
+    """A Latin/non-CJK anchor from an element's text, or '' if not anchor-like.
+
+    Mirrors the CJK path's dynamic-data immunity: digits and symbols are
+    stripped so a changing price/balance/count doesn't move the skeleton hash
+    ("Balance 100" and "Balance 9999" both reduce to "balance"). Whitespace is
+    collapsed and case is folded so render noise doesn't fork the fingerprint.
+
+    ponytail: 2..24 chars keeps button/nav labels ("login", "delete account")
+    and drops long description sentences — the Latin analogue of the CJK 2..6
+    window. Raise the ceiling only if a real multi-word control exceeds it.
+    """
+    letters_only = re.sub(r"[^a-zA-Z\s]", "", raw_text)
+    normalized = " ".join(letters_only.split()).lower()
+    return normalized if 2 <= len(normalized) <= 24 else ""
+
+
+def _extract_semantic_fingerprint(ui_json: Dict[str, Any]) -> list:
+    """
+    提取页面锚点指纹，免疫动态数据和渲染顺序波动。
+    """
+    fingerprint_features = set()
+    elements = ui_json.get("ui_elements", [])
+
+    for el in elements:
+        raw_text = el.get("text", "") or el.get("desc", "")
+        # 抹除所有数字、字母、符号，只保留纯汉字
+        cn_text = re.sub(r"[^\u4e00-\u9fa5]", "", raw_text)
+
+        # 标准的 UI 导航或按钮，通常在 2 到 6 个汉字之间
+        if 2 <= len(cn_text) <= 6 and cn_text not in _BLOCKLIST:
+            fingerprint_features.add(f"{el.get('class')}|{cn_text}")
+
+    # Non-CJK pages (English etc.) carry NO Chinese anchors, so the loop above
+    # yields nothing and every such page collapsed to one constant hash — L1's
+    # exact key then replayed an action recorded on a DIFFERENT page. Fall back
+    # to Latin anchors so those pages get distinct identities too. Page-level,
+    # not per-element: a page WITH usable CJK anchors keeps exactly its old
+    # fingerprint (Chinese behavior frozen); only a fully-anchorless page falls
+    # through here.
+    if not fingerprint_features:
+        for el in elements:
+            anchor = _latin_anchor(el.get("text", "") or el.get("desc", ""))
+            if anchor:
+                fingerprint_features.add(f"{el.get('class')}|{anchor}")
+
+    # 强制排序并转为列表，保证哈希的绝对一致性
+    return sorted(list(fingerprint_features))
+
+
+def compute_ui_hash(ui_json: Dict[str, Any]) -> str:
+    """计算用于混合缓存匹配的页面骨架 Hash"""
+    fingerprint = _extract_semantic_fingerprint(ui_json)
+    fingerprint_str = json.dumps(fingerprint)
+    hash_obj = hashlib.sha256()
+    hash_obj.update(fingerprint_str.encode("utf-8"))
+    return hash_obj.hexdigest()
+
+
+def compute_instruction_hash(instruction: str) -> str:
+    """计算用于混合缓存 O(1) 精确匹配的指令 Hash"""
+    normalized_inst = re.sub(r"\s+", " ", instruction).strip().lower()
+    hash_obj = hashlib.sha256()
+    hash_obj.update(normalized_inst.encode("utf-8"))
+    return hash_obj.hexdigest()

{screenforge-0.7.0 → screenforge-0.11.0}/common/cache/cache_manager.py

@@ -1,3 +1,4 @@
+import json
 import os
 
 os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"
@@ -30,6 +31,7 @@ class CacheManager:
         self._cache_dir = cache_dir
         self._enabled = enabled
         self._ttl_seconds = ttl_days * 24 * 60 * 60
+        self._max_size_bytes = max_size_mb * 1024 * 1024
         self._stats = CacheStats(cache_dir)
         self._model_loader = EmbeddingModelLoader()
 
@@ -178,6 +180,10 @@ class CacheManager:
             return False
         try:
             cache_data = load_cache(self._cache_dir)
+            # Prune expired entries here: the write path reloads and re-saves the
+            # whole file, so without this it re-persists dead entries forever. The
+            # read path only saves on a hit, so misses can't be relied on to prune.
+            cache_data = cleanup_expired_entries(cache_data, self._ttl_seconds)
             entries = cache_data.setdefault("entries", {})
             current_vector = self._get_embedding(instruction)
             keys_to_delete = []
@@ -219,12 +225,45 @@ class CacheManager:
             if ui_hash is not None:
                 entry["ui_hash"] = ui_hash
             entries[exact_key] = entry
+            self._evict_to_fit(cache_data, exact_key)
             save_cache(self._cache_dir, cache_data)
             return True
         except Exception as e:
             log.error(f"[Cache Error] Write failed: {e}")
             return False
 
+    def _evict_to_fit(self, cache_data: Dict, keep_key: str) -> None:
+        """Evict least-recently-accessed entries until the cache fits max_size_bytes.
+
+        TTL bounds age; this bounds size within the TTL window. The just-written
+        key is never evicted (a single entry larger than the cap still persists —
+        the cap is a soft ceiling, not a hard reject of the current write).
+        """
+        entries = cache_data.get("entries", {})
+
+        # ponytail: re-serializes on each eviction (O(n²) worst case). Fine —
+        # TTL already bounds entry count and eviction is rare; switch to a running
+        # byte tally if a cache ever evicts hundreds of entries in one write.
+        def size() -> int:
+            return len(json.dumps(cache_data, ensure_ascii=False).encode("utf-8"))
+
+        if size() <= self._max_size_bytes:
+            return
+        # Oldest access first; the current write is pinned last so it survives.
+        ordered = sorted(
+            entries.keys(),
+            key=lambda k: (
+                k == keep_key,
+                entries[k].get("metadata", {}).get("last_accessed", ""),
+            ),
+        )
+        for k in ordered:
+            if k == keep_key or len(entries) <= 1:
+                break
+            del entries[k]
+            if size() <= self._max_size_bytes:
+                break
+
     def get(self, instruction: str, ui_json: Dict[str, Any], platform: str) -> Optional[Dict[str, Any]]:
         try:
             ui_hash = compute_ui_hash(ui_json)

{screenforge-0.7.0 → screenforge-0.11.0}/common/case_memory.py

@@ -24,6 +24,17 @@ def _slugify(value: str) -> str:
     return text.lower() or "memory"
 
 
+# Inline `--action` runs all record this same source_ref: it says "typed on the
+# command line", not "which control". Treating it as an identity made the first
+# inline action on a platform absorb every later one, so a named action could
+# never get its own entry — or be found by its name.
+_NON_IDENTIFYING_SOURCE_REFS = frozenset({"inline://action"})
+
+
+def _identifying_source_ref(source_ref: str) -> str:
+    return "" if source_ref in _NON_IDENTIFYING_SOURCE_REFS else source_ref
+
+
 def _build_memory_id(
     platform: str,
     control_kind: str,
@@ -240,7 +251,7 @@ class CaseMemoryStore:
         normalized_platform = _normalize_text(platform).lower()
         normalized_kind = _normalize_text(control_kind).lower()
         normalized_label = _normalize_text(control_label)
-        normalized_source_ref = _normalize_text(source_ref)
+        normalized_source_ref = _identifying_source_ref(_normalize_text(source_ref))
         document = self.load_document()
 
         for entry in document.entries:
@@ -277,10 +288,11 @@ class CaseMemoryStore:
 
         document = self.load_document()
         existing_entry = None
+        identifying_source_ref = _identifying_source_ref(source_ref)
         for entry in document.entries:
             if entry.platform != platform or entry.control_kind != control_kind:
                 continue
-            if source_ref and entry.source_ref == source_ref:
+            if identifying_source_ref and entry.source_ref == identifying_source_ref:
                 existing_entry = entry
                 break
             if entry.control_label == control_label: