@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/ensure-store-windows.py

@@ -0,0 +1,509 @@
+#!/usr/bin/env python3
+"""ensure-store-windows —— 一条命令把「该开的店铺窗口」开好、CDP 端口对齐、可驱动性断言过。
+
+    python3 scripts/ensure-store-windows.py            # 预演（**默认 dry-run**，零写入）
+    python3 scripts/ensure-store-windows.py --apply    # 真做（开窗 + 写 cdp-port-map.json）
+    python3 scripts/ensure-store-windows.py --apply --json
+
+退出码：`0` 全部就绪（含本次已开/已对齐）；`1` 有店不可用或**还需要动作**（逐店打印状态与原因）；
+`2` 用法错误（未知 `--store` 名 / 未实现的开关 / 缺 stores.json 的条目）。
+
+## 为什么要有它（2026-10-11 生产现场，已恢复，但过程暴露了缺口）
+
+客户机 FULL 触发器**瞬时**报「Bridge 正常但**没有任何店铺**」（13:13/13:18），随后自愈
+（13:35/13:41 又报「就绪（6 个店铺）」）。恢复窗口里 Lead 是用**引擎已有能力**一步步拼出来的：
+
+  ① 用引擎既有的「安全重启客户端」实现 + `ensure_webdriver_client` 重启客户端；
+  ② **WebDriver API 仍不可用**：`getBrowserList` 返回 `statusCode=0, data=None`（0 个店铺）
+     ⇒ `startBrowser` 报 `-10004 browserId或browserOauth缺失`；
+  ③ 改用 **CLI 通道**（客户端自带的命令行）`store open --id <storeId> --expected-name <店名>`
+     ⇒ `✓ 店铺已打开`（`launchSource: cli`）；
+  ④ 但 `~/.dsh/argent/cdp-port-map.json` 里还是**旧端口**（1 店 32826 已随重启消失、
+     2 店 15079 过期）⇒ **引擎找不到窗口**；
+  ⑤ 用引擎**自己的对齐判据**收口：`_discover_cdp_ports()` → `[13018, 27893]`，
+     `_match_port_by_user_data_dir(store_id, ports)` → 1 店=27893 / 2 店=13018，
+     再 `write_cdp_port_map()` 写映射；
+  ⑥ 复测（**不给 `--cdp-url`**，让引擎自解析）：两店 `query_runner --mode shipment` 都 `found=True`。
+
+**缺的不是能力，而是「CLI 开窗后没人把新端口写进映射」这一步**——正常路径是引擎 `startBrowser`
+时顺手写，而 CLI 开的窗口**绕过了它**。本脚本把那 ⑥ 步收成一条**幂等**命令。
+
+## 只复用引擎既有实现（⛔ 不新造第二套）
+
+| 用到的既有实现 | 干什么 |
+|---|---|
+| `orchestrator._discover_cdp_ports()` | 端口发现（`lsof` 客户端进程 + `/json/version` 逐个校验）—— **薄委托**到 `scripts/lib/cdp_ports.py` |
+| `orchestrator._match_port_by_user_data_dir()` | **归属判据**：进程命令行含 `chrome_<store_id>` —— 同上，**薄委托** |
+| `orchestrator.write_cdp_port_map()` | 写 `cdp-port-map.json`（**唯一**写入口） |
+| `orchestrator.Orchestrator._port_from_cdp_map()` | 读映射（同一份解析，⛔ 不另写第二份） |
+| `orchestrator._is_cdp_port()` | `/json/version` 校验（端口是不是浏览器调试端口）—— **薄委托** |
+| `orchestrator._acquire_open_port_lock()` / `_release_open_port_lock()` | 全局开店互斥（差集不被别进程污染） |
+| `orchestrator.close_store_bridge()` | 关窗 —— **仅** `--force-reopen <店>` 显式点名时 |
+
+⚠️ 2026-10-11 起**端口发现/归属/`/json/list` 探针的实现**都在 `scripts/lib/cdp_ports.py`
+（编排器与认领前环境预检的第二层回退共用同一份）⇒ 上面两个 `orchestrator._*` 名字仍在、语义不变，
+但它们是**薄委托**；本脚本的调用点**一个都没改**（回归里 `esw.orch is orchestrator` 的断言照旧成立）。
+
+开窗的**唯一**出口 = 客户端自带的命令行 `store open --id <storeId> --expected-name <店名>`；
+`--expected-name` **必带**（id 与店名对不上时客户端自己拒绝 ⇒ 防「按 id 开错店」）。
+它的可执行名**不在本文件里写第二份字面量**：见下面 `CLI_BIN` 的取值注释。
+
+## ⛔ 不做的事
+
+· ⛔ **不 `startBrowser`**（API 通道今天实测不可用；`--api-first` 会**明确拒绝**而不是假装已做）；
+· ⛔ 不关任何窗口（**只有** `--force-reopen <店>` 才关，且只在 `--apply` 下）；
+· ⛔ 不写任何业务流程数据、不碰票、不连飞书、不碰客户机；
+· ⛔ 归属确认不到就**拒绝乱连**（绝不"猜一个端口"），且**不写映射**。
+
+## 可注入（离线回归用：⛔ 不碰真客户端、⛔ 不联网）
+
+· **引擎桩**：本脚本一律**按模块属性**调用引擎（`orch.X(...)`，取属性发生在每次调用时）
+  ⇒ 回归替换 `orchestrator._discover_cdp_ports` / `._match_port_by_user_data_dir` /
+  `._is_cdp_port` / `.write_cdp_port_map` / `.close_store_bridge` 即可。
+· **本模块的两个出口**：`cli_open()`（外部命令）与 `cdp_page_targets()`（`/json/list` 只读探针 ——
+  自 2026-10-11 起它是 `scripts/lib/cdp_ports.py#page_targets` 的**薄委托**，`fetch(url, timeout)`
+  形参原样保留，故回归仍按本模块属性替换 `esw.cdp_page_targets`）。
+· **隔离点**（既有 env，非本脚本新造）：`ARGENT_DATA_DIR` / `STORES_JSON` / `CDP_PORT_MAP`。
+
+回归：`python3 scripts/tests/ensure-store-windows.test.py`（52 断言纯夹具，见该文件页首）。
+
+## 为什么本文件里看不到客户端/平台的名字
+
+`verticals/_engine-words.json` 规定引擎文件（`scripts/**`，不含 `scripts/tests/`）不得**新增**业务词，
+`node scripts/vertical-lint.mjs` 的 engine-words 档按 `verticals/_engine-words.baseline.txt` 只拦新增
+（⛔ 不抬基线 —— 2026-10-09 的 `scripts/ml_hub_status.py` 就是这么把平台域名移出去的）。
+所以：① 客户端可执行名**引用**既有唯一字面量（见 `CLI_BIN`）；② 其余一律用中性说法
+（「客户端」「店铺浏览器」「店铺窗口」）。这不是洁癖：它保证这个文件可以随任一能力包分发而不带业务绑定。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import subprocess
+import sys
+import time
+from typing import Any, Optional
+
+HERE = pathlib.Path(__file__).resolve().parent
+# `scripts/` 与 `scripts/lib/` 进 sys.path：让 `import orchestrator` 及其同级依赖
+# （`flow_registry` / `argent_datadir` / `argent_filelock` / `webdriver_ipc`…）都能解析。
+# ⚠️ 顺序**必须先于** import orchestrator：否则它内部的 `import flow_registry` 会静默走
+# fallback（读到未合并的 base 注册表），那种"降级产出错值"在本仓库已踩过多次。
+sys.path.insert(0, str(HERE))
+sys.path.insert(0, str(HERE / "lib"))
+
+import env_probe  # noqa: E402  —— 只为借它的 `DEFAULT_STORE_CMD` 取客户端可执行名（见下）
+import cdp_ports  # noqa: E402  —— `/json/list` 只读探针的**唯一实现**（与 `env_probe` 共用）
+import orchestrator as orch  # noqa: E402  —— 引擎既有实现的**唯一**来源（⛔ 本文件不复制一份）
+
+# 客户端 CLI 的可执行名：**引用** `env_probe.DEFAULT_STORE_CMD` 的第 0 项，⛔ 不在本文件里写第二份字面量。
+# 为什么必须绕这一下：该名字是 `verticals/_engine-words.json` 里的业务词，engine-words 门禁
+# **只拦新增且不许抬基线** ⇒ 新引擎文件里出现它就是红的。而 `env_probe.py` 里那份字面量早已带基线记账，
+# 且它自己的注释就写着「**唯一字面量**：多处默认值都引用它 —— 第二份字面量会被 engine-words 记成新增」。
+# ⇒ 引用它，而不是复制它。（`env_probe` 只依赖 stdlib + `scripts/lib/*`，import 无副作用。）
+CLI_BIN = env_probe.DEFAULT_STORE_CMD[0]
+
+# ── 每店状态（**稳定字符串**，`--json` 与退出码都按它判）──────────────────────────────
+ST_READY = "ready"                 # 已就绪（映射对 + 可驱动）⇒ 零副作用跳过
+ST_ALIGNED = "aligned"             # 窗口在跑、映射过期 ⇒ 本次只对齐映射（⛔ 没开窗/关窗）
+ST_OPENED = "opened"               # 本次开了窗并写入映射
+ST_REOPENED = "reopened"           # 本次按 --force-reopen 关掉再开
+ST_WOULD_ALIGN = "would-align"     # dry-run：需要对齐映射
+ST_WOULD_OPEN = "would-open"       # dry-run：需要开窗
+ST_WOULD_REOPEN = "would-reopen"   # dry-run：需要关掉再开
+ST_FAILED = "failed"               # 不可用（原因见 reason）
+DONE_STATES = (ST_READY, ST_ALIGNED, ST_OPENED, ST_REOPENED)
+
+# `--api-first` 的拒绝文案（见模块 docstring「⛔ 不做的事」）。
+API_FIRST_REFUSAL = (
+    "WebDriver API 通道（startBrowser）**当前不可用**，本脚本不实现它。"
+    "依据 = 2026-10-11 生产实测：`getBrowserList` 返回 `statusCode=0, data=None`（0 个店铺）"
+    "⇒ `startBrowser` 报 `-10004 browserId或browserOauth缺失`；而 CLI 通道"
+    "（客户端自带的命令行 `store open --id … --expected-name …`）当场可用。"
+    "⇒ 现在只用 CLI 通道。将来 API 恢复后若要加成**优先**路径，须先在 orchestrator 侧验通"
+    "`getBrowserList` 非空，再在此实现、并保留 `--apply` 门。此刻给出 `--api-first` 只为一件事："
+    "**绝不假装已做**。"
+)
+
+
+def log(msg: str) -> None:
+    """进度一律走 stderr（stdout 只留最终结论，`--json` 时更是**只有**一个 JSON 对象）。"""
+    print(f"[{time.strftime('%H:%M:%S')}] {msg}", file=sys.stderr, flush=True)
+
+
+# ── 只读探针：/json/list（**唯一实现**已下沉到 `scripts/lib/cdp_ports.py`）──────────────
+def cdp_page_targets(port: int, timeout: float = 2.0,
+                     fetch=None) -> list[dict[str, Any]]:
+    """只读 `GET http://127.0.0.1:<port>/json/list` ⇒ 可附加的 `type=="page"` 目标。
+
+    「**页面可达**」判据用它：`/json/version` 只证明浏览器进程在，**不证明有可驱动的标签页**。
+
+    **薄委托**：实现在 `scripts/lib/cdp_ports.py#page_targets` —— 认领前环境预检的第二层回退
+    （`scripts/env_probe.py`）也要判「页面可达」，**两处共用同一份**（⛔ 不复制）。
+    `fetch(url, timeout)` 仍是本模块的注入点（既有回归按本模块属性替换本函数）。
+    """
+    return cdp_ports.page_targets(int(port), timeout=timeout, fetch=fetch)
+
+
+def cdp_drivable(port: Optional[int], timeout: float) -> tuple[bool, str]:
+    """**可驱动性**判据（两条都要过）：`/json/version` 可达 ∧ `/json/list` 有 page 目标。"""
+    if not port:
+        return False, "没有端口"
+    if not orch._is_cdp_port(int(port), timeout):
+        return False, f"CDP `/json/version` 不可达（127.0.0.1:{port} 没在监听，或不是浏览器调试端口）"
+    pages = cdp_page_targets(int(port), timeout)
+    if not pages:
+        return False, f"CDP `/json/list` 没有可附加的 page 目标（127.0.0.1:{port} 的窗口还没就绪？）"
+    return True, f"CDP 可驱动（{len(pages)} 个 page 目标）"
+
+
+def cli_open(store_id: str, expected_name: str, timeout: float) -> tuple[int, str]:
+    """客户端命令行 `store open --id <storeId> --expected-name <店名>`（**唯一**开窗出口，可注入）。
+
+    `--expected-name` **必带**：CLI 会逐字比对 id 与店名，对不上就拒绝 ⇒ 防"按 id 开错店"。
+    返回 `(returncode, 合并输出)`，**不抛**（命令缺失/超时一律折成非零 + 文案）。
+    """
+    cmd = [CLI_BIN, "store", "open",
+           "--id", str(store_id), "--expected-name", str(expected_name)]
+    try:
+        p = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout,
+                           stdin=subprocess.DEVNULL)
+    except FileNotFoundError as exc:
+        return 127, f"{CLI_BIN} 不在 PATH 上：{exc}"
+    except subprocess.TimeoutExpired as exc:
+        return 124, f"{CLI_BIN} store open 超时（{timeout:g}s）：{exc}"
+    except Exception as exc:                                     # noqa: BLE001
+        return 1, f"{type(exc).__name__}: {exc}"
+    return p.returncode, ((p.stdout or "") + (p.stderr or "")).strip()
+
+
+# ── 映射读回（复用引擎解析，⛔ 不另写第二份）──────────────────────────────────────
+def map_port(store_id: str) -> Optional[int]:
+    """从 `cdp-port-map.json` 按 store_id 读端口。
+
+    直接调引擎的 `Orchestrator._port_from_cdp_map` —— 它**不使用 self**（只调
+    `_cdp_port_map_path()` 读文件），故以 `None` 作 self 调用是安全的；这么做的唯一理由是
+    **解析只有一份**（⛔ 不在本文件里重写一遍"读 JSON + 取 cdp_port"）。
+    """
+    try:
+        return orch.Orchestrator._port_from_cdp_map(None, store_id)   # type: ignore[arg-type]
+    except Exception:                                            # noqa: BLE001
+        return None
+
+
+def _assert_aligned(store_id: str, port: int, probe_timeout: float) -> tuple[bool, str]:
+    """写映射后的**读回验收**（三条都要过）：映射读回 == port ∧ 可驱动 ∧ 归属仍指向该店。
+
+    "写进去了" ≠ "写得对"：映射是**运行时事实源**，写错等于把引擎指向别人家的窗口。
+    """
+    back = map_port(store_id)
+    if back != port:
+        return False, f"写后读回不一致：映射 {back} ≠ 目标 {port}"
+    ok, why = cdp_drivable(port, probe_timeout)
+    if not ok:
+        return False, f"写后断言失败：{why}"
+    try:
+        owned = orch._match_port_by_user_data_dir(store_id, [port])
+    except Exception as exc:                                     # noqa: BLE001
+        return False, f"写后归属复核失败：{type(exc).__name__}: {exc}"
+    if owned != port:
+        return False, f"写后断言失败：端口 {port} 的归属确认不到 `chrome_{store_id}`"
+    return True, f"映射已写并读回一致（{port}）；{why}；归属 `chrome_{store_id}` 已确认"
+
+
+def _wait_for_owned_port(store_id: str, before: list[int],
+                         args: argparse.Namespace) -> tuple[Optional[int], str]:
+    """开窗后**轮询直到确认归属**（归属 + 可驱动），或到点/撞歧义。
+
+    归属判据 = 引擎的 `_match_port_by_user_data_dir`（`chrome_<store_id>`）。
+    `before` 是开窗前快照，仅用来在原因里区分"本次新增"与"复用既有窗口"。
+    **多个新端口且一个都匹配不上 ⇒ 立刻拒绝**（⛔ 不猜一个、⛔ 不写映射）。
+    """
+    deadline = time.time() + max(0.0, float(args.timeout))
+    last_ports: list[int] = []
+    last_reason = "还没有可用的端口快照"
+    while True:
+        ports = orch._discover_cdp_ports()
+        new = [p for p in ports if p not in before]
+        last_ports = ports
+        try:
+            owned = orch._match_port_by_user_data_dir(store_id, ports)
+        except Exception as exc:                                 # noqa: BLE001
+            owned = None
+            last_reason = f"归属匹配查询异常：{type(exc).__name__}: {exc}"
+        if owned is not None:
+            ok, why = cdp_drivable(owned, args.probe_timeout)
+            if ok:
+                tag = "本次新增" if owned in new else "复用的既有窗口"
+                return int(owned), f"端口 {owned}（{tag}）"
+            last_reason = f"端口 {owned} 归属已确认但还不可驱动：{why}"
+        else:
+            last_reason = f"端口归属未确认（`chrome_{store_id}` 一个都没命中）"
+            if len(new) >= 2:
+                return None, (f"**归属歧义**：本次开窗新增 {len(new)} 个端口 {new}，"
+                              f"其中没有一个属于 `chrome_{store_id}` ⇒ **拒绝乱连**"
+                              f"（⛔ 不猜一个端口，⛔ 不写映射）")
+        if time.time() >= deadline:
+            return None, (f"{args.timeout:g}s 内没能确认可驱动的店铺窗口：{last_reason}"
+                          f"（已发现端口 {last_ports}；开窗前 {before}）")
+        time.sleep(max(0.01, float(args.interval)))
+
+
+# ── 店铺解析 ────────────────────────────────────────────────────────────────────
+def _pick_store(stores: dict[str, dict], name: str) -> tuple[Optional[str], Optional[dict]]:
+    """按 stores.json 的 **key**（= 客户端环境名）或 value 的 `name` 字段解析（与
+    `orchestrator._resolve_store` 同一口径：两种写法都认）。找不到 ⇒ `(None, None)`。"""
+    if name in stores:
+        return name, stores[name]
+    for k, v in stores.items():
+        if str((v or {}).get("name") or "") == name:
+            return k, v
+    return None, None
+
+
+def build_targets(args: argparse.Namespace, stores: dict[str, dict]
+                  ) -> tuple[list[dict[str, Any]], list[str]]:
+    """要处理的店铺清单。缺省 = stores.json **全部**（排序保证可复现）；`--store` 收窄。
+
+    返回 `(targets, problems)`；`problems` 非空 ⇒ 用法错误（exit 2）。
+    """
+    names = list(dict.fromkeys(list(args.store) + list(args.force_reopen)))  # 保序去重
+    names = names or sorted(stores)
+    targets: list[dict[str, Any]] = []
+    problems: list[str] = []
+    for n in names:
+        key, info = _pick_store(stores, n)
+        if key is None:
+            problems.append(f"店铺 {n!r} 不在 stores.json 里（可用：{'、'.join(sorted(stores))}）")
+            continue
+        sid = str((info or {}).get("store_id") or "").strip()
+        if not sid:
+            problems.append(f"店铺 {key!r} 的 stores.json 条目缺 `store_id`（开不了窗）")
+            continue
+        targets.append({
+            "env_name": key,                                     # stores.json 的 key
+            "store_id": sid,
+            "name": str((info or {}).get("name") or key),         # 传给 CLI 的店名（--expected-name）
+            "platform": str((info or {}).get("platform") or ""),
+        })
+    return targets, problems
+
+
+# ── 每店：对齐 / 开窗 / 断言 ───────────────────────────────────────────────────────
+def process_store(t: dict[str, Any], args: argparse.Namespace,
+                  apply: bool, force: bool) -> dict[str, Any]:
+    """幂等处理一个店，返回状态 dict（**不抛**：所有失败都折成 ST_FAILED + reason）。"""
+    sid = str(t["store_id"])
+    name = str(t["name"])
+    r: dict[str, Any] = {"store": t["env_name"], "storeId": sid, "name": name,
+                         "status": ST_FAILED, "port": None, "mapPort": None,
+                         "changed": False, "reason": ""}
+    try:
+        ports = orch._discover_cdp_ports()
+    except Exception as exc:                                     # noqa: BLE001
+        r["reason"] = f"CDP 端口发现失败：{type(exc).__name__}: {exc}"
+        return r
+    r["mapPort"] = map_port(sid)
+
+    # ── ① 本机已有窗口 ⇒ 只对齐映射（⛔ 不开窗、⛔ 不关窗；这是"CLI 开窗后没人写映射"的正解）──
+    try:
+        owned = orch._match_port_by_user_data_dir(sid, ports)
+    except Exception as exc:                                     # noqa: BLE001
+        owned = None
+        log(f"  ⚠️ 归属匹配查询异常（按未确认处理）：{type(exc).__name__}: {exc}")
+    if owned is not None:
+        ok, why = cdp_drivable(owned, args.probe_timeout)
+        # `--force-reopen` 是**显式要求重开**：窗口此刻再健康也照办（⛔ 不被幂等短路掉）。
+        if ok and not force:
+            if r["mapPort"] == owned:
+                r.update(status=ST_READY, port=int(owned),
+                         reason=f"跳过（幂等，零副作用）：映射已是实际端口 {owned}；{why}")
+                return r
+            if not apply:
+                r.update(status=ST_WOULD_ALIGN, port=int(owned),
+                         reason=f"端口漂移：映射 {r['mapPort']} → 实际 {owned}"
+                                f"（dry-run 未写；{why}）")
+                return r
+            orch.write_cdp_port_map(store_id=sid, store_name=t["env_name"],
+                                    env_name=t["platform"], port=int(owned))
+            good, why2 = _assert_aligned(sid, int(owned), args.probe_timeout)
+            r.update(status=ST_ALIGNED if good else ST_FAILED, port=int(owned), changed=True,
+                     reason=(f"端口漂移已对齐：映射 {r['mapPort']} → {owned}；{why}"
+                             if good else why2))
+            return r
+        need = (f"端口 {owned} 归属已确认、{why}"
+                if ok else f"端口 {owned} 归属已确认但不可驱动：{why}")
+    else:
+        need = (f"本机没有属于该店的 CDP 端口（`chrome_{sid}` 未命中；"
+                f"已发现 {ports}）")
+
+    # ── ② 需要开窗（dry-run 到此为止）──────────────────────────────────────────────
+    if not apply:
+        r.update(status=ST_WOULD_REOPEN if force else ST_WOULD_OPEN,
+                 reason=f"{need} ⇒ 需要开窗（dry-run 未开）")
+        return r
+
+    # ⚠️ 这里**刻意不调**引擎的云端店铺清单硬校验（`store list` 那条「店名必须逐字在云端清单里」）。
+    #    不是忘了，两条理由：① 它的判据是**云端清单**，而 2026-10-11 现场正是清单拉不到（0 项）
+    #    ⇒ 它恰好在"最需要恢复"的那一刻不构成判据；② 那份硬校验的名字是业务词，本文件写不得
+    #    （见文件头「为什么本文件里看不到客户端/平台的名字」）。
+    #    防「开错店」改由**在开窗路径上真正生效**的两道判据兜住：
+    #      ① 客户端自己的 `--expected-name`：逐字校验 id ↔ 店名，对不上直接拒绝；
+    #      ② 开窗后的归属断言：端口必须命中 `chrome_<store_id>`，否则**不写映射**（见 `_assert_aligned`）。
+    #    若将来要把云端清单门也加上，请把它加在**引擎侧**（与 `store list` 的既有实现放一起），
+    #    ⛔ 不要在引擎文件里写下第二份客户端字面量。
+
+    # ── ③ 关窗：**只有** --force-reopen 显式点名才关 ────────────────────────────────
+    if force:
+        try:
+            orch.close_store_bridge(sid, log=lambda m: log(f"  {m}"))
+        except Exception as exc:                                 # noqa: BLE001
+            r["reason"] = f"关窗失败（--force-reopen）：{exc}"
+            return r
+
+    # ── ④ 开窗：**持全局开店互斥**（差集临界区，⛔ 无锁绝不开）──────────────────────
+    try:
+        lock = orch._acquire_open_port_lock()
+    except Exception as exc:                                     # noqa: BLE001
+        r["reason"] = f"拿不到全局开店互斥锁（fail-closed，⛔ 不无锁开店）：{exc}"
+        return r
+    try:
+        before = orch._discover_cdp_ports()
+        rc, out = cli_open(sid, name, args.timeout)
+        if rc != 0:
+            r["reason"] = f"{CLI_BIN} store open 失败（rc={rc}）：{out[:300]}"
+            return r
+        log(f"  ✓ 店铺已打开（{name}，launchSource=cli）")
+        port, why = _wait_for_owned_port(sid, before, args)
+        if port is None:
+            r["reason"] = why
+            return r
+        orch.write_cdp_port_map(store_id=sid, store_name=t["env_name"],
+                                env_name=t["platform"], port=int(port))
+        good, why2 = _assert_aligned(sid, int(port), args.probe_timeout)
+        r.update(status=(ST_REOPENED if force else ST_OPENED) if good else ST_FAILED,
+                 port=int(port), changed=True,
+                 reason=(f"已开窗并写入映射：{why}；{why2}" if good else why2))
+        return r
+    finally:
+        orch._release_open_port_lock(lock)
+
+
+# ── CLI ────────────────────────────────────────────────────────────────────────
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="ensure-store-windows",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description="幂等地把该开的店铺窗口开好、CDP 端口对齐、可驱动性断言过"
+                    "（**默认 dry-run**，真做要 --apply；只复用 orchestrator 既有实现）",
+        epilog="例子：\n"
+               "  python3 scripts/ensure-store-windows.py                 # 预演（零写入）\n"
+               "  python3 scripts/ensure-store-windows.py --apply         # 恢复窗口 + 写映射\n"
+               "  python3 scripts/ensure-store-windows.py --apply --store <店名>\n")
+    ap.add_argument("--store", action="append", default=[], metavar="名",
+                    help="店铺名（stores.json 的 key 或 name 字段）；可重复；缺省 = stores.json 全部")
+    ap.add_argument("--force-reopen", action="append", default=[], metavar="名",
+                    help="显式关掉再开（复用 close_store_bridge）；可重复。"
+                         "⛔ 不带它绝不关任何窗口")
+    ap.add_argument("--apply", action="store_true",
+                    help="真做（开窗 + 写 cdp-port-map.json）。缺省 = dry-run")
+    ap.add_argument("--dry-run", action="store_true",
+                    help="显式 dry-run（**本来就是默认**；A3：写类动作默认安全态）。"
+                         "与 --apply 同时给时 dry-run 赢")
+    ap.add_argument("--timeout", type=float, default=60.0, metavar="秒",
+                    help="每店预算：CLI 调用超时 + 开窗后轮询确认归属的总时长（默认 60）")
+    ap.add_argument("--interval", type=float, default=1.0, metavar="秒",
+                    help=argparse.SUPPRESS)
+    ap.add_argument("--probe-timeout", type=float, default=2.0, metavar="秒",
+                    help=argparse.SUPPRESS)
+    ap.add_argument("--json", action="store_true", help="stdout 只输出一个 JSON 对象")
+    ap.add_argument("--api-first", action="store_true",
+                    help="⛔ 未实现：走 WebDriver API（startBrowser）优先路径。"
+                         "今天该通道不可用 ⇒ 本脚本明确拒绝（绝不假装已做）")
+    return ap
+
+
+def _emit(args: argparse.Namespace, results: list[dict[str, Any]], apply: bool,
+          timeout: float) -> int:
+    keys = ("ready", "aligned", "opened", "reopened",
+            "would-align", "would-open", "would-reopen", "failed")
+    counts = {k: sum(1 for r in results if r["status"] == k) for k in keys}
+    actionable = counts["would-align"] + counts["would-open"] + counts["would-reopen"]
+    ok = counts["failed"] == 0 and actionable == 0
+    if args.json:
+        print(json.dumps({
+            "ok": ok, "dryRun": not apply, "applied": apply, "timeout": timeout,
+            "stores": results,
+            "summary": dict(counts, total=len(results)),
+        }, ensure_ascii=False, indent=2))
+        return 0 if ok else 1
+
+    icons = {ST_READY: "✅", ST_ALIGNED: "🛠", ST_OPENED: "🪟", ST_REOPENED: "♻️",
+             ST_WOULD_ALIGN: "•", ST_WOULD_OPEN: "•", ST_WOULD_REOPEN: "•", ST_FAILED: "❌"}
+    print(f"{'预演（dry-run，零写入）' if not apply else '真做（--apply）'}"
+          f"：{len(results)} 个店铺")
+    for r in results:
+        port = r["port"] if r["port"] is not None else "-"
+        print(f"  {icons.get(r['status'], '?')} {r['store']}（storeId={r['storeId']}）"
+              f"  [{r['status']}]  端口={port}")
+        print(f"      {r['reason']}")
+    tail = "、".join(f"{k}={counts[k]}" for k in keys if counts[k]) or "无"
+    print(f"  ⇒ {'全部就绪' if ok else '**未全部就绪**'}（{tail}）")
+    if not apply and actionable:
+        print("  ⇒ 预演发现需要动作：加 `--apply` 真做（会开窗 / 写 cdp-port-map.json）")
+    return 0 if ok else 1
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.api_first:
+        print(f"❌ --api-first：{API_FIRST_REFUSAL}", file=sys.stderr)
+        return 2
+    # A3：**默认 dry-run**；`--dry-run` 显式给出时永远赢（安全方向）。
+    apply = bool(args.apply) and not bool(args.dry_run)
+    if args.timeout <= 0:
+        print("❌ --timeout 必须 > 0", file=sys.stderr)
+        return 2
+
+    try:
+        stores = orch._load_stores()
+    except Exception as exc:                                     # noqa: BLE001
+        print(f"❌ 读 stores.json 失败：{type(exc).__name__}: {exc}", file=sys.stderr)
+        return 1
+    if not stores:
+        print("❌ stores.json 里没有任何店铺（文件缺失 / 损坏？）——先跑初始化向导"
+              f"（`{orch.STORES_JSON}`）", file=sys.stderr)
+        return 1
+
+    targets, problems = build_targets(args, stores)
+    if problems:
+        for p in problems:
+            print(f"❌ {p}", file=sys.stderr)
+        return 2
+    if not targets:
+        print("❌ 没有要处理的店铺", file=sys.stderr)
+        return 2
+
+    forced = set(args.force_reopen)
+    log(f"{'APPLY' if apply else 'DRY-RUN'}：{len(targets)} 个店铺"
+        f"（每店超时 {args.timeout:g}s）"
+        + (f"；--force-reopen {sorted(forced)}" if forced else ""))
+    results: list[dict[str, Any]] = []
+    for t in targets:
+        force = t["env_name"] in forced or str(t["name"]) in forced
+        log(f"── {t['env_name']}（storeId={t['store_id']}）"
+            + ("  [force-reopen]" if force else ""))
+        try:
+            r = process_store(t, args, apply, force)
+        except Exception as exc:                                 # noqa: BLE001
+            r = {"store": t["env_name"], "storeId": t["store_id"], "name": t["name"],
+                 "status": ST_FAILED, "port": None, "mapPort": None, "changed": False,
+                 "reason": f"未预期异常：{type(exc).__name__}: {exc}"}
+        results.append(r)
+        log(f"   {r['status']}：{r['reason']}")
+    return _emit(args, results, apply, float(args.timeout))
+
+
+if __name__ == "__main__":
+    sys.exit(main())