docs: 固化 L1 端口冲突退让流程

.agents/skills/unidesk-webdev/SKILL.md

@@ -75,7 +75,15 @@ description: UniDesk Web 开发与受控浏览器验证技能。用户提到 Web
   - 通过 native auth/access profile 只授权当前调试微服务的 `navId`；
   - 左侧根导航必须存在，但只能显示当前微服务的一个页面入口；
   - 只代理当前微服务 API 路径，禁止为了渲染产品壳层启动其他 HWLAB 后端；
-  - 当前微服务前端、API 和 Worker 使用独立端口与生命周期，不得抢占或停止其他 L1 会话；
+  - 当前微服务前端、API 和 Worker 使用 YAML-first 固定端口与独立生命周期；
+  - YAML 声明的 L1 端口被占用时：
+    - 同一服务的旧 L1 进程只通过项目 CLI 停止或重启；
+    - 其他服务不得停止、复用或接管；
+    - 先用有界监听状态确认一个空闲端口；
+    - 再修改本 L1 服务的 owning YAML 端口并通过 parser/CLI 读取新值；
+    - 禁止用命令行覆盖、临时环境变量或隐藏 fallback 绕过 YAML；
+    - 端口退让后继续启动，并从 YAML 新端口执行 `web-probe native-readiness`；
+  - L1 进程的启动、停止、重启、状态和日志只通过项目 CLI 管理；
   - Vite 必须绑定可访问的 native 端口并保持 HMR，浏览器端 HMR 地址不得写成 `0.0.0.0`。
 - L1 公网调试入口交给用户前必须完成浏览器 readiness 验收：
   - 使用 `bun scripts/cli.ts web-probe native-readiness --node <node> --lane <lane> --profile <profile>` 一次完成验收；

config/hwlab-node-lanes.yaml

@@ -142,7 +142,7 @@ lanes:
             web:
               bindHost: 0.0.0.0
               probeHost: 127.0.0.1
-              port: 5173
+              port: 5174
               runtimeConfig:
                 displayTime:
                   timeZone: Asia/Shanghai

docs/reference/hwlab.md

@@ -180,6 +180,14 @@ AgentRun terminal `failed`、`blocked` 或 `canceled` 也是最终结果，不
 
 Workbench 浏览器回归需求以 UniDesk OA [PJ2026-010401 Web工作台](../../project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md) 为权威；具体 Web 开发、受控 fake-server、fixture 采集脱敏、移动端断言、截图 artifact 和线上 web-probe 闭环统一见 `$unidesk-webdev`。HWLAB repo 只保留入口边界：专项代码位于 `web/hwlab-cloud-web`，命令必须在 issue/CLI 选中的目标 node/lane workspace 或独立 worktree 上运行，不得在 master server 本地跑浏览器或仓库级前端 check。
 
+- L1 Native 端口冲突处理：
+  - 端口被同一 L1 服务的旧进程占用时，只能通过项目 CLI 停止或重启该服务；
+  - 端口被其他服务占用时，禁止停止、接管或复用其他服务；
+  - 必须先确认空闲端口，再修改 `config/hwlab-node-lanes.yaml#lanes.<lane>.targets.<node>.nativeDevelopment.workbench` 中本服务的端口；
+  - API、Worker、Web 的启动、状态和公网入口继续由同一 YAML 与 `hwlab nodes native-development workbench` 解析；
+  - 禁止用命令行参数、临时环境变量或代码 fallback 形成第二端口真相；
+  - 端口退让后必须从 YAML 新端口执行 `web-probe native-readiness`，确认公网页面、DOM、交互和浏览器错误均通过后再向用户披露入口。
+
 MDTODO/Project Management Web 的重写或布局类 issue 以 UniDesk OA 对应 SPEC 为权威；关闭时必须用选中 node/lane 的 public origin 和 `$unidesk-webdev` 的 `observe command` 证据证明默认任务正文、Rxx 树、Source/File 选择、报告侧栏和报告全屏状态。`observe` 同时采集 control/observer 页面时，显式 command result、control URL 和截图是用户动作证据；被动 observer 周期刷新或 stop 后根路由空态只能作为对照，不能覆盖用户入口截图和 command JSON。
 
 Workbench session lifecycle、空 session 后台回收、archived/deleted deep link 和 GET 纯读投影的判定口径统一见 `$unidesk-webdev`。指挥侧关闭这类 issue 时只记录选中 node/lane、受控配置来源、后台 mutation/GC 证据、list/detail/messages/deep link 摘要和截图 SHA；TTL、interval、batch 等可调数值以选中 lane 的受控配置为准，不在本参考维护第二份数值真相。