screenforge 0.7.0__tar.gz → 0.10.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: screenforge
-Version: 0.7.0
+Version: 0.10.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.10.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.10.0/cli/_version.py

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

{screenforge-0.7.0 → screenforge-0.10.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.10.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.10.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:

{screenforge-0.7.0 → screenforge-0.10.0}/common/failure_diagnosis.py

@@ -17,9 +17,12 @@ from common.error_codes import lookup
 CANDIDATE_THRESHOLD = 0.55  # difflib ratio floor; below this is not a candidate
 MAX_CANDIDATES = 3
 
-# Element text fields to match against, in locator-priority order. `ref` is web
-# only; mobile elements omit it, so a text/description match is the fallback.
-_MATCH_FIELDS = ("text", "desc", "name")
+# Element text fields to match against. Every compressor's label-bearing keys
+# must appear here or that platform silently yields zero candidates:
+# utils_xml.py (Android) writes text/desc, utils_web.py writes text/desc/name,
+# utils_ios.py writes ONLY label/name — and suppresses `name` when it equals
+# `label`, so without "label" the typical iOS control matched nothing at all.
+_MATCH_FIELDS = ("text", "desc", "label", "name")
 
 
 @dataclass
@@ -62,12 +65,27 @@ def _best_field(el: dict, target: str) -> tuple[float, str, str]:
 
 
 def _suggested_locator(el: dict, matched_text: str, matched_field: str) -> dict:
-    """Locator priority: ref (web) > text > description. Mirrors agent_guide."""
+    """Locator priority: ref (web) > resourceId > text > description.
+
+    Mirrors the repo's locator law (CLAUDE.md, and the brain prompt in
+    common/ai.py). Mobile compressors (utils/utils_xml.py, utils/utils_ios.py)
+    emit `id` but never `ref`, so without the resourceId branch every mobile
+    candidate degraded to a text locator — weaker than what the page offered.
+    """
     ref = str(el.get("ref", "")).strip()
     if ref:
         return {"type": "ref", "value": ref}
+    resource_id = str(el.get("id", "")).strip()
+    if resource_id:
+        return {"type": "resourceId", "value": resource_id}
     if matched_field == "text":
         return {"type": "text", "value": matched_text}
+    # iOS is the only platform that reaches here on a `name` match (web always
+    # carries a ref, Android an id). executor.py's ios_key_map sends
+    # resourceId->name and description->label, so a name match MUST say
+    # resourceId or the agent would query the wrong attribute.
+    if matched_field == "name":
+        return {"type": "resourceId", "value": matched_text}
     return {"type": "description", "value": matched_text}
 
 
@@ -91,6 +109,24 @@ def _rank_candidates(locator_value: str, ui_elements: list[dict]) -> list[Candid
     return scored[:MAX_CANDIDATES]
 
 
+def rank_candidates(phrase: str, ui_elements: list[dict]) -> list[dict]:
+    """Rank elements against a plain-language phrase; JSON-ready dicts.
+
+    The forward half of did-you-mean: instead of explaining a locator that just
+    failed, answer "which elements could the agent mean by this sentence?" Same
+    ranking, same 0.55 floor, same at-most-3, same rather-nothing-than-a-guess.
+
+    ponytail: difflib is LITERAL similarity, not semantic — "登录" vs "Sign in"
+    scores ~0, so this returns [] on mixed-language pages. Upgrade path if that
+    matters: embed phrase + labels and rank by cosine, reusing the embedding
+    infrastructure already behind the L2 semantic cache (common/cache/).
+    """
+    return [
+        {"text": c.text, "score": c.score, "locator": c.locator}
+        for c in _rank_candidates(phrase, ui_elements)
+    ]
+
+
 def _recommend(error_code: str, fix: str, candidates: list[Candidate]) -> dict:
     if candidates:
         top = candidates[0]

{screenforge-0.7.0 → screenforge-0.10.0}/common/mcp_server.py

@@ -167,6 +167,14 @@ def _build_inspect_ui_tool_schema() -> dict:
                 "type": "boolean",
                 "description": "是否同时返回截图 base64",
             },
+            "task": {
+                "type": "string",
+                "description": "可选的任务标签（如 \"点击登录\"）。提供时，返回该任务上次成功的定位器作为提示（memory 字段）；不提供则 memory 为空对象。",
+            },
+            "intent": {
+                "type": "string",
+                "description": "可选的人话短语（如 \"登录按钮\"）。提供时，返回按字面相似度排序的候选元素及可直接使用的定位器（candidates 字段）；匹配不到则为空数组，不会瞎猜。",
+            },
         },
         "additionalProperties": False,
     }
@@ -280,15 +288,25 @@ def _build_initialize_result(protocol_version: str) -> dict:
 
 
 def _build_tool_result(payload: dict) -> dict:
+    # structuredContent IS the payload — the MCP client reads it directly. The
+    # content array must be present and non-empty per spec, so it carries a SHORT
+    # summary rather than a second json.dumps of the same dict. Duplicating a
+    # payload that holds a UI tree plus a screenshot was the largest avoidable
+    # cost on the wire.
+    ok = bool(payload.get("ok", False))
+    operation = payload.get("operation", "unknown")
+    if ok:
+        summary = f"{operation}: ok"
+        count = payload.get("element_count")
+        if count is not None:
+            summary += f" ({count} elements)"
+    else:
+        detail = str(payload.get("error", "") or payload.get("result", "") or "failed")
+        summary = f"{operation}: failed — {detail[:120]}"
     return {
-        "content": [
-            {
-                "type": "text",
-                "text": json.dumps(payload, ensure_ascii=False, indent=2),
-            }
-        ],
+        "content": [{"type": "text", "text": summary}],
         "structuredContent": payload,
-        "isError": not bool(payload.get("ok", False)),
+        "isError": not ok,
     }
 
 

screenforge-0.10.0/common/observation.py

@@ -0,0 +1,48 @@
+"""The ONE agent-facing observation envelope.
+
+Every payload the external agent reads — inspect_ui, --action --json success and
+engine_error, the MCP observation stash — composes this function. Adding a field
+means editing THIS file and nothing else; that is the whole point. Two
+constructors used to hand-assemble their own keys and drifted (the inspect
+payload shipped the tree twice and two screenshots; case-memory reached the
+agent only AFTER it had already acted).
+
+Pure: no I/O, no device, no config reads — same contract as
+cli/modes/action.py::build_success_payload.
+
+Invariants:
+  1. Additive only. Never shrink or truncate ui_tree — a trimmed tree makes the
+     agent hit [E030] Ref not found and re-inspect, which costs MORE tokens.
+  2. Honest empties. Absent data is {} / [] / "", never a guess (same rule as
+     common/failure_diagnosis.py's below-threshold behavior).
+  3. element_count is DERIVED here, never accepted from a caller, so it can
+     never disagree with the tree it describes.
+"""
+
+
+def build_observation(
+    *,
+    ui_tree: dict,
+    current_url: str = "",
+    screenshot_base64: str = "",
+    memory: dict | None = None,
+    candidates: list[dict] | None = None,
+) -> dict:
+    elements = (ui_tree or {}).get("ui_elements") or []
+    return {
+        "ui_tree": ui_tree or {},
+        "element_count": len(elements),
+        "current_url": current_url,
+        "screenshot_base64": screenshot_base64,
+        # A HINT, never an instruction: what the last run of this task DID —
+        # its locator and its outcome, success or failure (case_memory records
+        # both, so `last_status`/`success_count` are what say which). The agent
+        # reads it alongside the live tree and decides whether to trust it. We
+        # deliberately do NOT replay it (that is Midscene's XPath-cache route,
+        # which silently clicks the wrong thing after a redesign).
+        "memory": memory or {},
+        # Elements matching the agent's plain-language phrase, best first. Empty
+        # is a valid answer — below the similarity floor we return nothing rather
+        # than a confident wrong guess.
+        "candidates": candidates or [],
+    }

{screenforge-0.7.0 → screenforge-0.10.0}/common/tool_protocol.py

@@ -65,6 +65,12 @@ class ToolRequest(BaseModel):
     resume_run_id: str = ""
     run_id: str = ""
     goal: str = ""
+    # Optional task label for inspect_ui: lets the payload carry the case-memory
+    # hint for THIS task at decision time. Omitted → no lookup, no hint.
+    task: str = ""
+    # Optional plain-language phrase for inspect_ui: returns ranked candidate
+    # elements (the `candidates` field). Omitted → no ranking, empty list.
+    intent: str = ""
     query: str = ""
     source_ref: str = ""
     control_kind: str = ""

{screenforge-0.7.0 → screenforge-0.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "screenforge"
-version = "0.7.0"
+version = "0.10.0"
 description = "AI-driven cross-platform UI automation engine with test script generation"
 readme = "README.md"
 requires-python = ">=3.11"

{screenforge-0.7.0 → screenforge-0.10.0}/screenforge.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: screenforge
-Version: 0.7.0
+Version: 0.10.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.10.0}/screenforge.egg-info/SOURCES.txt

@@ -33,6 +33,7 @@ common/failure_diagnosis.py
 common/history_manager.py
 common/logs.py
 common/mcp_server.py
+common/observation.py
 common/preflight.py
 common/progress.py
 common/run_reporter.py
@@ -69,6 +70,7 @@ tests/test_android_smoke_live.py
 tests/test_cache_hash.py
 tests/test_cache_manager.py
 tests/test_capabilities.py
+tests/test_case_memory_identity.py
 tests/test_cli_action_json.py
 tests/test_codegen_quality.py
 tests/test_dispatch.py
@@ -77,13 +79,22 @@ tests/test_dom_capture.py
 tests/test_error_codes.py
 tests/test_executor.py
 tests/test_failure_diagnosis.py
+tests/test_failure_diagnosis_ios.py
+tests/test_failure_diagnosis_mobile.py
+tests/test_forward_candidates.py
+tests/test_inspect_ui_candidates.py
+tests/test_inspect_ui_envelope.py
+tests/test_inspect_ui_memory.py
 tests/test_interaction_actions.py
 tests/test_ios_smoke_live.py
 tests/test_mcp_execute_observation.py
 tests/test_mcp_execute_parity_live.py
 tests/test_mcp_ref_cache.py
+tests/test_mcp_tool_result.py
 tests/test_ml_optional.py
 tests/test_mode_error_code_threading.py
+tests/test_observation.py
+tests/test_observation_action_parity.py
 tests/test_parser.py
 tests/test_playground_app.py
 tests/test_playground_sink.py

screenforge-0.10.0/tests/test_case_memory_identity.py

@@ -0,0 +1,93 @@
+"""Inline actions must not all collapse into one case-memory entry.
+
+Every inline `--action` run writes the same sentinel `source_ref`
+("inline://action"), and both the upsert and the lookup matched `source_ref`
+BEFORE `control_label`. So the first inline action recorded on a platform
+absorbed every later one: `--action-name "点击登录"` bumped the counter on the
+pre-existing `swipe:up` entry instead of creating its own, and `task="点击登录"`
+could never hit. The sentinel is provenance for reports, never an identity.
+"""
+
+import tempfile
+from pathlib import Path
+
+from common.case_memory import CaseMemoryStore
+
+_SENTINEL = "inline://action"
+
+
+def _store() -> CaseMemoryStore:
+    return CaseMemoryStore(file_path=Path(tempfile.mkdtemp()) / "case_memory.json")
+
+
+def _run(store: CaseMemoryStore, label: str, source_ref: str = _SENTINEL) -> None:
+    store.upsert_from_run(
+        summary={
+            "execution_mode": "run",
+            "platform": "android",
+            "status": "success",
+            "run_id": "r1",
+            "finished_at": "2026-07-27T20:00:00",
+            "control_summary": {
+                "control_kind": "action",
+                "control_label": label,
+                "source_ref": source_ref,
+            },
+        },
+        step_records=[],
+    )
+
+
+def test_distinct_action_labels_get_distinct_entries():
+    store = _store()
+    _run(store, "swipe:up")
+    _run(store, "点击登录")
+    labels = sorted(e.control_label for e in store.load_document().entries)
+    assert labels == ["swipe:up", "点击登录"]
+
+
+def test_repeating_the_same_label_still_updates_one_entry():
+    store = _store()
+    _run(store, "swipe:up")
+    _run(store, "swipe:up")
+    entries = store.load_document().entries
+    assert len(entries) == 1
+    assert entries[0].success_count == 2
+
+
+def test_named_action_is_findable_by_its_label():
+    store = _store()
+    _run(store, "swipe:up")
+    _run(store, "点击登录")
+    hit = store.find_entry(
+        platform="android", control_kind="action", control_label="点击登录"
+    )
+    assert hit is not None
+    assert hit["control_label"] == "点击登录"
+
+
+def test_sentinel_source_ref_never_matches_a_different_label():
+    # The bug's read half: a lookup carrying the sentinel returned whichever
+    # inline entry came first, regardless of the label asked for.
+    store = _store()
+    _run(store, "swipe:up")
+    assert (
+        store.find_entry(
+            platform="android",
+            control_kind="action",
+            control_label="点击登录",
+            source_ref=_SENTINEL,
+        )
+        is None
+    )
+
+
+def test_real_source_ref_still_identifies_across_a_rename():
+    # Workflows carry a real path: renaming the workflow must not orphan its
+    # history. This is the behavior the sentinel was free-riding on.
+    store = _store()
+    _run(store, "old_name", source_ref="/tmp/flow.yaml")
+    _run(store, "new_name", source_ref="/tmp/flow.yaml")
+    entries = store.load_document().entries
+    assert len(entries) == 1
+    assert entries[0].success_count == 2

screenforge-0.10.0/tests/test_failure_diagnosis_ios.py

@@ -0,0 +1,62 @@
+"""iOS elements carry `label`/`name` and nothing else — match on them.
+
+utils/utils_ios.py's compress_ios_source writes only type/label/name/value/
+accessible/disabled: no `text`, no `desc`, no `id`, no `ref`. While _MATCH_FIELDS
+was ("text", "desc", "name") the whole did-you-mean feature was dead on iOS —
+and dead in the worst way, because the compressor drops `name` when it equals
+`label`, so the ordinary control matched nothing while an odd one matched by its
+internal identifier and got handed back as a `description` locator. That is the
+wrong attribute: executor.py's ios_key_map sends description->label.
+
+Threshold note: CANDIDATE_THRESHOLD = 0.55, and probes here are exact or near
+matches so they clear it comfortably.
+"""
+
+from common.failure_diagnosis import diagnose, rank_candidates
+
+
+def test_label_only_element_is_a_candidate():
+    """The common iOS shape: label present, name suppressed as a duplicate."""
+    diag = diagnose(
+        error_code="E030",
+        locator_value="登录",
+        ui_elements=[{"type": "Button", "label": "登录"}],
+    )
+    assert diag.candidates
+    assert diag.candidates[0].locator == {"type": "description", "value": "登录"}
+
+
+def test_label_match_wins_over_name_and_maps_to_label_lookup():
+    """A label match must not be reported as resourceId — that would query `name`."""
+    diag = diagnose(
+        error_code="E030",
+        locator_value="登录",
+        ui_elements=[{"type": "Button", "label": "登录", "name": "loginBtn"}],
+    )
+    assert diag.candidates[0].locator == {"type": "description", "value": "登录"}
+
+
+def test_name_match_maps_to_resource_id_not_description():
+    """`name` is iOS's identifier: resourceId->name in executor's ios_key_map."""
+    diag = diagnose(
+        error_code="E030",
+        locator_value="loginBtn",
+        ui_elements=[{"type": "Button", "label": "Sign in", "name": "loginBtn"}],
+    )
+    assert diag.candidates[0].locator == {"type": "resourceId", "value": "loginBtn"}
+
+
+def test_forward_lookup_also_sees_ios_labels():
+    """rank_candidates() shares the matcher, so `intent` works on iOS too."""
+    hits = rank_candidates("登录", [{"type": "Button", "label": "登录"}])
+    assert [h["locator"] for h in hits] == [{"type": "description", "value": "登录"}]
+
+
+def test_web_name_attribute_still_yields_ref():
+    """Adding `label` must not disturb web: ref outranks every text field."""
+    diag = diagnose(
+        error_code="E030",
+        locator_value="username",
+        ui_elements=[{"class": "input", "name": "username", "ref": "@3", "id": "user"}],
+    )
+    assert diag.candidates[0].locator == {"type": "ref", "value": "@3"}