add what-is-it

Promote ship to the user-facing delivery skill. Kind is short or long
from an explicit mode, then self-judgment, then a question, defaulting
to short. Old names remain deprecation stubs.

AGENTS.md

@@ -60,17 +60,17 @@ AGENTS.md         # 本文档
 | [note-style](skills/note-style/README.md) | 把材料整理成可长期查阅的知识笔记 |
 | [orc](skills/orc/README.md) | 把开发、发版、DEB / Docker 意图编排成阶段，按档位分发给对应 skill |
 | [pouch](skills/pouch/README.md) | 创建、校验、安装和维护 builtin skill |
-| [previewer](skills/previewer/README.md) | 通过 Tailscale Serve 将静态文件暴露为 tailnet 内 HTTP 预览 |
+| [previewer](skills/previewer/README.md) | 用 Node 提供 HTML/静态文件预览，返回 URL 并复用已有服务 |
 | [pr-ship](skills/pr-ship/README.md) | 把已有 PR 从检查、合并推进到回归、构建和部署 |
 | [releaser](skills/releaser/README.md) | 给已准备好的 commit 发版本：更新说明、tag、可选 Forge Release |
-| [ship](skills/ship/README.md) | short-ship / long-ship / pr-ship 共用的交付记录格式 |
+| [ship](skills/ship/README.md) | 把一次变更从说明推进到配置允许的 PR、合并或部署；short 或 long |
-| [short-ship](skills/short-ship/README.md) | 范围清楚的单次变更：小功能、文案、已确认 bug，一直交到停点 |
+| [short-ship](skills/short-ship/README.md) | 已弃用：`ship` 的旧名兼容占位，不含流程 |
-| [long-ship](skills/long-ship/README.md) | 复杂需求：specifier PRD 批准后拆任务、集成回归并交付 |
+| [long-ship](skills/long-ship/README.md) | 已弃用：`ship` 的旧名兼容占位，不含流程 |
-| [specifier](skills/specifier/README.md) | 把复杂需求整理成多轮评审的 HTML PRD，批准后交给 long-ship |
+| [specifier](skills/specifier/README.md) | 把复杂需求整理成多轮评审的 HTML PRD，批准后交给 ship |
-| [delivery-loop](skills/delivery-loop/README.md) | 三个交付入口共用的验证到部署状态机 |
+| [delivery-loop](skills/delivery-loop/README.md) | ship 与 pr-ship 共用的验证到部署状态机 |
 | [manage-release](skills/manage-release/README.md) | 已弃用：`releaser` 的旧名兼容占位，不含流程 |
-| [bugfix-ship](skills/bugfix-ship/README.md) | 已弃用：`short-ship` 的旧名兼容占位，不含流程 |
+| [bugfix-ship](skills/bugfix-ship/README.md) | 已弃用：`ship` 的旧名兼容占位，不含流程 |
-| [requirement-flow](skills/requirement-flow/README.md) | 已弃用：`long-ship` 的旧名兼容占位，不含流程 |
+| [requirement-flow](skills/requirement-flow/README.md) | 已弃用：`ship` 的旧名兼容占位，不含流程 |
 
 改名后旧名保留一个纯占位 skill，避免已装软链悬空和旧项目 `.pouch.yaml` 失效。确认没有
 项目再按旧名启用后，删除对应占位目录即可，不丢任何内容。

README.md

@@ -96,17 +96,17 @@ AGENTS.md         # 详细规范与架构说明
 | [note-style](skills/note-style/README.md)                               | 把材料整理成可长期查阅的知识笔记                            |
 | [orc](skills/orc/README.md)                                             | 把开发、发版、DEB / Docker 意图编排成阶段，按档位分发给对应 skill  |
 | [pouch](skills/pouch/README.md)                                         | 创建、校验、安装和维护 builtin skill                   |
-| [previewer](skills/previewer/README.md)                                 | 用 Node 渲染 HTML/静态文件，并通过 Tailscale 返回访问 IP 和 HTTP 预览 |
+| [previewer](skills/previewer/README.md)                                 | 用 Node 提供 HTML/静态文件预览，返回 URL 并复用已有服务 |
 | [pr-ship](skills/pr-ship/README.md)                                     | 把已有 PR 从检查、合并推进到回归、构建和部署 |
 | [releaser](skills/releaser/README.md)                                   | 给已准备好的 commit 发版本：更新说明、tag、可选 Forge Release |
-| [ship](skills/ship/README.md)                                           | short-ship / long-ship / pr-ship 共用的交付记录格式 |
+| [ship](skills/ship/README.md)                                           | 把一次变更从说明推进到配置允许的 PR、合并或部署；short 或 long |
-| [short-ship](skills/short-ship/README.md)                               | 范围清楚的单次变更：小功能、文案、已确认 bug |
+| [short-ship](skills/short-ship/README.md)                               | 已弃用：`ship` 的旧名兼容占位，不含流程 |
-| [long-ship](skills/long-ship/README.md)                                 | 复杂需求：PRD 批准后拆任务、集成回归并交付 |
+| [long-ship](skills/long-ship/README.md)                                 | 已弃用：`ship` 的旧名兼容占位，不含流程 |
-| [specifier](skills/specifier/README.md)                                 | 把复杂需求整理成多轮评审的 HTML PRD，批准后交给 long-ship |
+| [specifier](skills/specifier/README.md)                                 | 把复杂需求整理成多轮评审的 HTML PRD，批准后交给 ship |
-| [delivery-loop](skills/delivery-loop/README.md)                         | 三个交付入口共用的验证到部署状态机 |
+| [delivery-loop](skills/delivery-loop/README.md)                         | ship 与 pr-ship 共用的验证到部署状态机 |
 | [manage-release](skills/manage-release/README.md)                       | 已弃用：`releaser` 的旧名兼容占位，不含流程                  |
-| [bugfix-ship](skills/bugfix-ship/README.md)                             | 已弃用：`short-ship` 的旧名兼容占位，不含流程 |
+| [bugfix-ship](skills/bugfix-ship/README.md)                             | 已弃用：`ship` 的旧名兼容占位，不含流程 |
-| [requirement-flow](skills/requirement-flow/README.md)                   | 已弃用：`long-ship` 的旧名兼容占位，不含流程 |
+| [requirement-flow](skills/requirement-flow/README.md)                   | 已弃用：`ship` 的旧名兼容占位，不含流程 |
 
 
 ACK 是包含规范、模板与校验脚本的完整 Skill。安装后可初始化当前项目状态：

catalog.yaml

@@ -39,3 +39,13 @@ taste-skill:
     - frontend
     - design
     - skill-collection
+
+ego-lite:
+  repo: https://github.com/citrolabs/ego-lite.git
+  ref: main
+  path: skills
+  description: ego lite browser automation skill for opening, operating, testing, and reviewing websites with the user's browser context.
+  tags:
+    - browser
+    - automation
+    - skill-collection

skills/ack/README.md

@@ -18,8 +18,8 @@ ACK 是显式调用的 Agent Skill，用三种独立角色跑工程协作闭环
 | --- | --- | --- |
 | 初始化 | `/ack 初始化` | 生成并补全 `.pouch/ack/`；缺项按统一格式列出 |
 | 检查 | `/ack 检查配置` | 只读校验，默认不改文件；测试环境缺 deployer 时转交 |
-| 做需求 | `/ack 处理这个需求：…` | 先建 ship 记录；复杂需求走 specifier / long-ship，小改动走 short-ship |
+| 做需求 | `/ack 处理这个需求：…` | 先建 ship 记录；复杂需求走 specifier / ship long 模式，小改动走 ship |
-| 修 bug | `/ack 修这个 bug：…` 或处理飞书收件 | 短描述 + 验收 → 你确认（飞书须你点「已确认」）→ 缺陷板闭环，交付链接 short-ship |
+| 修 bug | `/ack 修这个 bug：…` 或处理飞书收件 | 短描述 + 验收 → 你确认（飞书须你点「已确认」）→ 缺陷板闭环，交付链接 ship |
 | 交付配置 | 说明怎么布测试环境 / 怎么发版 | 写入同一份 `delivery.yaml`；测试环境绑定 deployer |
 | 运行测试环境 | `/ack 重新布测试环境` | 内部加载 deployer，布 `.pouch/deployer/<env>` |
 | 运行版本发布 | `/ack 发布一个版本` | 按 `intents.release`；stable/生产仍要单独批准 |

skills/ack/SKILL.md

@@ -109,8 +109,8 @@ python3 <ack-skill-dir>/scripts/record_task.py .pouch/ack/tasks.yaml \
 1. `.pouch/ack` 不存在：停止并建议先 `/ack` 初始化；不要静默初始化。
 2. 读 `project.md`；若存在 `agents.yaml`，先用 `validate_agents.py` 校验并读取其 `defaults`；用 `select_tasks.py`（已知任务加 `--task-id`）和 `select_knowledge.py` 取当前任务相关 `active` 条目。超预算时缩小选择，不回退为完整 yaml。
 3. 新需求或尚未确认的计划：读 [kickoff.md](references/kickoff.md)。范围清楚的小改动转
-   `short-ship`；复杂需求转 `specifier` / `long-ship`。修 bug 写短问题说明、复现和可观测
+   `ship`；复杂需求转 `specifier` 或 `ship` long 模式。修 bug 写短问题说明、复现和可观测
-   验收，不写大 PRD；要交付时链接 `short-ship`。
+   验收，不写大 PRD；要交付时链接 `ship`。
 4. 用户已确认后，先读取并按 [closed-loop.md](references/closed-loop.md) 执行；使用 Orca 时同时读取 [orca-adapter.md](references/orca-adapter.md)。当前会话担任 Coordinator，不亲自写代码或跑测试；worker profile 按 `agents.yaml`（若存在）否则按任务板配置选择。
    这不是 fire-and-forget：Coordinator 不得在 `launch` / `dispatch` 后只回复“已派发”并结束当前会话。每个任务都必须在同一轮持续执行默认 60 秒窗口的 `check --wait`，并按 60–120 秒节奏运行 `worker_probe.py`，直到 Developer 回报 `worker_done` 或 `escalation`；随后写回 `fixed_by_dev`，主动派发 Test，并继续等待 `retest_result`。只有完成 Test 终检、重试/`leftover` 决策、回归决定和 worker 回收后，才可以结束本轮 ACK。
 5. 存在 `project.bugIntake` 时先完成「飞书收件」。创建或更换 worker 走「启动 worker」。若 `intents.testEnvironment` 已启用，派 Test 前先走「运行测试环境」。

skills/ack/references/kickoff.md

@@ -4,7 +4,7 @@
 用户确认后的三角色闭环、飞书收件、启动 worker、交付和回归由 `SKILL.md` 按条件加载，
 不要在本文件开头预读其它规范。
 
-复杂需求的规格和任务写在 `.pouch/ship/<ship-id>/`（specifier + long-ship）。ACK 任务板
+复杂需求的规格和任务写在 `.pouch/ship/<ship-id>/`（specifier + ship long 模式）。ACK 任务板
 只收缺陷。显式 `/ack` 做功能需求时也先建 ship 记录，不要把功能任务写成 `type: bug`。
 
 ---

skills/agent-runtime/SKILL.md

@@ -52,6 +52,22 @@ python3 <skill-dir>/scripts/agent.py run stop --root <project-root> --run <run-i
 `run start` 只为 builder 生成受控的 make 命令；tester/ACK 的执行入口仍由对应 skill
 适配器提供。环境、项目或精确 worktree 缺失时 fail closed，并报告需要补的字段。
 
+tester 的 test-preflight 一次性节点入口使用 JSON stdin/stdout：
+
+```bash
+printf '%s\n' '{"binding":"tester.android","operation":"platform_probe","platform":"android","node":"local"}' \
+  | python3 <skill-dir>/scripts/agent.py run exec --root <project-root>
+```
+
+入口只接受 `platform_probe`、`network_probe`、`install`、`start` 四种受控操作，命令
+由 adapter 固定生成，不读取配置中的 command/argv/shell/env/token。local binding 可执行
+固定的只读平台/网络探针和 test-preflight 已授权的 Android 安装/启动；非 local binding
+先按 `environment + host + project + path` 解析 Orca worktree，再通过 Orca 的临时 terminal
+执行固定的节点 runner，并从协议标记读取一个 JSON 结果，结束后关闭该 terminal。远程 iOS
+的安装/启动要求调用方把产物放在 Mac 节点可读路径，并在 matrix 的 `artifact.remote_path`
+中声明；协调机上的本地路径不会被错误地当成 Mac 路径。任何 transport、节点工具链或远端
+产物缺失都返回结构化 `environment-fail`，绝不在协调节点执行平台命令或伪造 `ready`。
+
 ## 验证
 
 - `python3 <skill-dir>/scripts/agent.py validate --root <project-root>` 通过。

skills/agent-runtime/scripts/agent.py

@@ -8,15 +8,24 @@ shell, and it only creates builder sessions from a fixed make invocation.
 from __future__ import annotations
 
 import argparse
+import base64
 import copy
+import gzip
 import hashlib
 import json
 import os
+import platform as host_platform
 import re
+import shlex
+import shutil
+import socket
 import subprocess
 import sys
 import time
 import uuid
+import urllib.error
+import urllib.parse
+import urllib.request
 from pathlib import Path
 from typing import Any
 
@@ -38,6 +47,9 @@ TARGET_RE = re.compile(r"^[A-Za-z0-9_.-]{1,96}$")
 MODEL_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:/+@-]{0,127}$")
 MAKEFILE_RE = re.compile(r"^[A-Za-z0-9_.-]+(?:/[A-Za-z0-9_.-]+)*$")
 FORBIDDEN_KEYS = {"command", "argv", "shell", "env", "environmentVariables", "token", "secret", "password"}
+RUNNER_OPERATIONS = {"platform_probe", "network_probe", "install", "start", "maestro", "maestro_batch", "artifact_download"}
+RUNNER_PLATFORMS = {"android", "ios"}
+LOCAL_NODE_NAMES = {"local", "localhost", "127.0.0.1", "::1"}
 
 
 class ConfigError(ValueError):
@@ -223,7 +235,17 @@ def orca_json(args: list[str], environment: str | None = None) -> dict[str, Any]
     if environment and environment != "local":
         command.extend(["--environment", environment])
     command.append("--json")
-    proc = subprocess.run(command, capture_output=True, text=True, check=False)
+    # A remote terminal read is a poll, not a blocking operation.  Some Orca
+    # providers keep the CLI open when a PTY has no new output, so bound the
+    # read and let the caller poll again.  Other commands may legitimately
+    # take longer (for example terminal creation), hence the larger default.
+    timeout = 10 if args[:2] == ["terminal", "read"] else 120
+    try:
+        proc = subprocess.run(command, capture_output=True, text=True, check=False, timeout=timeout)
+    except subprocess.TimeoutExpired as exc:
+        if args[:2] == ["terminal", "read"]:
+            return {}
+        raise ConfigError(f"Orca command timed out after {timeout}s: {' '.join(command)}") from exc
     raw = (proc.stdout or "").strip()
     try:
         data = json.loads(raw)
@@ -282,12 +304,19 @@ def worktree_for(binding_value: dict[str, Any]) -> dict[str, Any]:
         if location["environment"] == "local" and expected_host == "local" and str(item.get("hostId")) != "local":
             continue
         candidates.append(item)
-    if len(candidates) != 1:
+    if not candidates:
-        if not candidates:
+        raise ConfigError(
-            raise ConfigError(
+            f"找不到精确 worktree: environment={environment}, host={location_host(location)}, "
-                f"找不到精确 worktree: environment={environment}, host={location_host(location)}, "
+            f"project={location['project']}, path={location['path']}；先创建或登记该 worktree"
-                f"project={location['project']}, path={location['path']}；先创建或登记该 worktree"
+        )
-            )
+    if len(candidates) > 1:
+        # Orca can retain duplicate records for the same physical worktree
+        # after an environment is paired again. They are safe to collapse only
+        # when every execution-relevant field is identical; divergent records
+        # must still fail closed instead of guessing a node or checkout.
+        identity = {(str(item.get("path")), str(item.get("projectId")), str(item.get("head")), str(item.get("hostId"))) for item in candidates}
+        if len(identity) == 1:
+            return candidates[0]
         raise ConfigError(f"binding 匹配到多个 worktree: {len(candidates)}")
     return candidates[0]
 
@@ -358,6 +387,673 @@ def make_command(value: dict[str, Any]) -> str:
     return f"exec make -f {value.get('makefile', 'makefile.builder')} {value['target']}"
 
 
+def runner_response(status: str, observed: Any = "", *, checks: dict[str, Any] | None = None, remediation: str = "", **extra: Any) -> dict[str, Any]:
+    """Build the JSON response shared with test-preflight's runner contract."""
+
+    response: dict[str, Any] = {"status": status, "observed": observed}
+    if checks:
+        response["checks"] = checks
+    if remediation:
+        response["remediation"] = remediation
+    response.update(extra)
+    return response
+
+
+def run_fixed_command(command: list[str], *, cwd: str | None = None) -> tuple[int, str]:
+    """Run an adapter-owned argv; never invoke a shell or print command output."""
+
+    try:
+        process = subprocess.run(
+            command,
+            cwd=cwd,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            check=False,
+        )
+    except OSError as exc:
+        return 127, str(exc)
+    return process.returncode, (process.stdout or "").strip()
+
+
+def _runner_check(status: str, observed: Any, expected: str, remediation: str = "") -> dict[str, Any]:
+    value: dict[str, Any] = {"status": status, "observed": observed, "expected": expected}
+    if remediation:
+        value["remediation"] = remediation
+    return value
+
+
+def _local_platform_probe(platform_name: str) -> dict[str, Any]:
+    if platform_name == "android":
+        adb_code, adb_output = run_fixed_command(["adb", "version"])
+        if adb_code != 0:
+            failure = "adb unavailable on the local tester node"
+            return runner_response("environment-fail", failure, checks={
+                "adb": _runner_check("environment-fail", failure, "adb responds", "Install or expose adb on the tester node"),
+                "device": _runner_check("environment-fail", "not checked", "authorized Android device", "Make adb available first"),
+                "boot": _runner_check("environment-fail", "not checked", "Android device boot complete", "Make adb available first"),
+            })
+        devices_code, devices_output = run_fixed_command(["adb", "devices"])
+        devices: list[str] = []
+        if devices_code == 0:
+            for line in devices_output.splitlines():
+                if "\tdevice" in line:
+                    devices.append(line.split("\t", 1)[0].strip())
+        if devices_code != 0 or not devices:
+            observed = "adb responded but no authorized device is available"
+            return runner_response("environment-fail", observed, checks={
+                "adb": _runner_check("ready" if devices_code == 0 else "environment-fail", "adb responded" if devices_code == 0 else "adb devices failed", "adb responds"),
+                "device": _runner_check("environment-fail", observed, "authorized Android device", "Connect or start an authorized tester device"),
+                "boot": _runner_check("environment-fail", "not checked", "Android device boot complete", "Provide a booted authorized device"),
+            })
+        serial = devices[0]
+        boot_code, boot_output = run_fixed_command(["adb", "-s", serial, "shell", "getprop", "sys.boot_completed"])
+        booted = boot_code == 0 and boot_output.strip() == "1"
+        return runner_response("ready" if booted else "environment-fail", "adb/device probe completed", checks={
+            "adb": _runner_check("ready", "adb responded", "adb responds"),
+            "device": _runner_check("ready", "authorized", "authorized Android device"),
+            "boot": _runner_check("ready" if booted else "environment-fail", "boot complete" if booted else "device is not booted", "Android device boot complete", "Boot the Android tester device" if not booted else ""),
+        })
+
+    if platform_name != "ios":
+        return runner_response("blocked", "unsupported platform", remediation="Use platform android or ios")
+    if host_platform.system() != "Darwin":
+        observed = "iOS runner requires a macOS tester node; xcrun was not invoked"
+        return runner_response("environment-fail", observed, checks={
+            "macos": _runner_check("environment-fail", observed, "Darwin tester node", "Route iOS tests to a Mac tester binding"),
+            "xcrun": _runner_check("environment-fail", "not invoked", "xcrun available", "Route iOS tests to a Mac tester binding"),
+            "simctl": _runner_check("environment-fail", "not invoked", "simctl available", "Route iOS tests to a Mac tester binding"),
+            "boot": _runner_check("environment-fail", "not checked", "booted iOS simulator", "Route iOS tests to a Mac tester binding"),
+        })
+    xcrun_code, _ = run_fixed_command(["xcrun", "--version"])
+    simctl_code, simctl_output = run_fixed_command(["xcrun", "simctl", "list", "devices", "--json"])
+    booted = False
+    if simctl_code == 0:
+        try:
+            data = json.loads(simctl_output)
+            booted = any(
+                isinstance(device, dict) and device.get("state") == "Booted"
+                for devices in (data.get("devices") or {}).values()
+                if isinstance(devices, list)
+                for device in devices
+            )
+        except (TypeError, json.JSONDecodeError):
+            booted = False
+    status = "ready" if xcrun_code == 0 and simctl_code == 0 and booted else "environment-fail"
+    return runner_response(status, "macOS/simctl probe completed", checks={
+        "macos": _runner_check("ready", "Darwin", "Darwin tester node"),
+        "xcrun": _runner_check("ready" if xcrun_code == 0 else "environment-fail", "available" if xcrun_code == 0 else "unavailable", "xcrun available"),
+        "simctl": _runner_check("ready" if simctl_code == 0 else "environment-fail", "available" if simctl_code == 0 else "unavailable", "simctl available"),
+        "boot": _runner_check("ready" if booted else "environment-fail", "booted simulator" if booted else "no booted simulator", "booted iOS simulator", "Boot an iOS simulator" if not booted else ""),
+    })
+
+
+def _network_probe(request: dict[str, Any]) -> dict[str, Any]:
+    raw_url = request.get("url")
+    if not isinstance(raw_url, str) or not raw_url.strip():
+        return runner_response("blocked", "network_probe requires url", remediation="Provide an http(s) URL")
+    parsed = urllib.parse.urlsplit(raw_url)
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname or parsed.username or parsed.password:
+        return runner_response("blocked", "URL must be http(s) without embedded credentials", remediation="Provide a credential-free probe URL")
+    try:
+        port = parsed.port or (443 if parsed.scheme == "https" else 80)
+    except ValueError:
+        return runner_response("blocked", "URL contains an invalid port", remediation="Provide a valid http(s) probe URL")
+    try:
+        addresses = socket.getaddrinfo(parsed.hostname, port, type=socket.SOCK_STREAM)
+    except (OSError, ValueError) as exc:
+        return runner_response("environment-fail", "DNS probe failed", checks={
+            "dns": _runner_check("environment-fail", str(exc), "resolvable hostname", "Check tester-node DNS/VPN")
+        })
+    checks: dict[str, Any] = {"dns": _runner_check("ready", sorted({item[4][0] for item in addresses}), "resolvable hostname")}
+    try:
+        import socket as _socket
+        with _socket.create_connection((parsed.hostname, port), timeout=5):
+            pass
+        checks["tcp"] = _runner_check("ready", f"{parsed.hostname}:{port}", "TCP connection")
+    except OSError as exc:
+        checks["tcp"] = _runner_check("environment-fail", str(exc), f"TCP {parsed.hostname}:{port}", "Check the tester-node route and firewall")
+        return runner_response("environment-fail", "TCP probe failed", checks=checks)
+    try:
+        with urllib.request.urlopen(urllib.request.Request(raw_url, method="GET"), timeout=5) as response:
+            code = response.status
+    except urllib.error.HTTPError as exc:
+        code = exc.code
+    except (OSError, urllib.error.URLError) as exc:
+        checks["http"] = _runner_check("environment-fail", str(exc), "HTTP response", "Check service listener, proxy and TLS")
+        return runner_response("environment-fail", "HTTP probe failed", checks=checks)
+    expected = request.get("probe", {}).get("expected_status") if isinstance(request.get("probe"), dict) else None
+    matches = not isinstance(expected, list) or code in expected
+    checks["http"] = _runner_check("ready" if 200 <= code < 500 and matches else "environment-fail", code, expected or "HTTP 2xx-4xx", "Check service health or expected_status" if not matches or code >= 500 else "")
+    return runner_response("ready" if checks["http"]["status"] == "ready" else "environment-fail", "DNS/TCP/HTTP probe completed", checks=checks)
+
+
+def _request_artifact(request: dict[str, Any]) -> tuple[Path | None, str | None]:
+    value = request.get("artifact")
+    if not isinstance(value, str) or not value.strip():
+        return None, "install requires an artifact path"
+    path = Path(value)
+    if not path.is_absolute() or ".." in path.parts or path == Path("/"):
+        return None, "artifact must be a safe absolute path"
+    return path, None
+
+
+def _request_flow(request: dict[str, Any]) -> tuple[str | None, str | None]:
+    flow = request.get("flow")
+    if not isinstance(flow, str) or not flow.strip():
+        return None, "maestro requires a non-empty flow"
+    if len(flow.encode("utf-8")) > 120_000:
+        return None, "maestro flow is too large"
+    env = request.get("env", {})
+    if env is not None:
+        if not isinstance(env, dict) or any(
+            not isinstance(key, str) or not re.fullmatch(r"[A-Z][A-Z0-9_]{0,63}", key)
+            or not isinstance(value, str) or len(value) > 4096
+            for key, value in env.items()
+        ):
+            return None, "maestro env must contain safe uppercase names and text values"
+    return flow, None
+
+
+def _maestro_env(request: dict[str, Any]) -> dict[str, str]:
+    values = request.get("env") if isinstance(request.get("env"), dict) else {}
+    return {str(key): str(value) for key, value in values.items()}
+
+
+def _local_maestro(platform_name: str, request: dict[str, Any]) -> dict[str, Any]:
+    flow, error = _request_flow(request)
+    if error:
+        return runner_response("blocked", error, remediation="Generate a bounded Maestro flow from the catalog case")
+    if platform_name != "android":
+        return runner_response("blocked", "local Maestro runner only supports Android", remediation="Route iOS Maestro to tester.ios")
+    maestro = Path("/home/ace/.maestro/bin/maestro")
+    if not maestro.is_file():
+        maestro_path = shutil.which("maestro")
+        maestro = Path(maestro_path) if maestro_path else maestro
+    if not maestro.is_file():
+        return runner_response("environment-fail", "maestro is not installed on the local tester node", remediation="Install Maestro and rerun test-preflight")
+    device_code, device_output = run_fixed_command(["adb", "devices"])
+    serial = next((line.split("\t", 1)[0].strip() for line in device_output.splitlines() if "\tdevice" in line), "") if device_code == 0 else ""
+    if not serial:
+        return runner_response("environment-fail", "no authorized Android device for Maestro")
+    flow_path = Path("/tmp") / f"pouch-maestro-{uuid.uuid4().hex}.yaml"
+    flow_path.write_text(flow, encoding="utf-8")
+    try:
+        command = [str(maestro), "test", "--device", serial, "--no-color", str(flow_path)]
+        for key, value in _maestro_env(request).items():
+            command.extend(["-e", f"{key}={value}"])
+        env = os.environ.copy()
+        env["MAESTRO_CLI_NO_ANALYTICS"] = "true"
+        process = subprocess.run(command, capture_output=True, text=True, check=False, timeout=float(request.get("timeout") or 180), env=env)
+        output = ((process.stdout or "") + ("\n" + process.stderr if process.stderr else "")).strip()[-6000:]
+        return runner_response("ready", "maestro completed", checks={"maestro": _runner_check("ready", output, "Maestro flow executed")}, test_result="pass" if process.returncode == 0 else "fail", exit=process.returncode, output=output)
+    except subprocess.TimeoutExpired as exc:
+        return runner_response("ready", "maestro timed out", checks={"maestro": _runner_check("ready", "timeout", "Maestro flow executed")}, test_result="environment-fail", exit=124, output=str(exc))
+    finally:
+        flow_path.unlink(missing_ok=True)
+
+
+def _local_mutation(platform_name: str, operation: str, request: dict[str, Any]) -> dict[str, Any]:
+    if platform_name == "ios":
+        return runner_response("blocked", "local iOS mutation requires an explicit Mac transport", remediation="Use a non-local tester binding with a supported node transport")
+    if platform_name != "android":
+        return runner_response("blocked", "unsupported platform", remediation="Use platform android or ios")
+    path, error = _request_artifact(request) if operation == "install" else (None, None)
+    identity = request.get("identity")
+    if operation == "install" and error:
+        return runner_response("blocked", error, remediation="Provide the caller-supplied APK path")
+    if not isinstance(identity, str) or not re.fullmatch(r"[A-Za-z0-9_.-]{1,192}", identity):
+        return runner_response("blocked", "identity must be a safe Android package id", remediation="Provide the declared artifact package")
+    if operation == "install" and not path.is_file():
+        return runner_response("blocked", "artifact does not exist", remediation="Provide an existing caller-supplied APK")
+    probe = _local_platform_probe("android")
+    if probe.get("status") != "ready":
+        return probe
+    device_code, device_output = run_fixed_command(["adb", "devices"])
+    serial = next((line.split("\t", 1)[0].strip() for line in device_output.splitlines() if "\tdevice" in line), "") if device_code == 0 else ""
+    if not serial:
+        return runner_response("environment-fail", "no authorized Android device")
+    command = ["adb", "-s", serial, "install", "-r", str(path)] if operation == "install" else ["adb", "-s", serial, "shell", "monkey", "-p", identity, "1"]
+    code, _ = run_fixed_command(command)
+    if code != 0:
+        return runner_response("environment-fail", f"{operation} command failed", remediation=f"Inspect the tester-node {operation} evidence")
+    return runner_response("ready", f"{operation} completed", checks={operation: _runner_check("ready", "completed", "operation succeeded")})
+
+
+REMOTE_RUNNER_SOURCE = r'''
+import base64, gzip, json, os, re, shutil, socket, subprocess, sys, urllib.error, urllib.parse, urllib.request, uuid, zipfile
+from pathlib import Path
+
+request_bytes = base64.b64decode(sys.stdin.read())
+try:
+    request = json.loads(request_bytes.decode("utf-8"))
+except UnicodeDecodeError:
+    request = json.loads(gzip.decompress(request_bytes).decode("utf-8"))
+marker = request.pop("_marker")
+
+def check(status, observed, expected, remediation=""):
+    item = {"status": status, "observed": observed, "expected": expected}
+    if remediation:
+        item["remediation"] = remediation
+    return item
+
+def run(argv, env=None, timeout=180):
+    try:
+        proc = subprocess.run(argv, env=env, timeout=timeout, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, check=False)
+    except subprocess.TimeoutExpired as exc:
+        return 124, (str(exc) or "command timed out").strip()
+    except OSError as exc:
+        return 127, str(exc).strip()
+    return proc.returncode, (proc.stdout or "").strip()
+
+def response(status, observed, checks=None, remediation=""):
+    item = {"status": status, "observed": observed}
+    if checks:
+        item["checks"] = checks
+    if remediation:
+        item["remediation"] = remediation
+    return item
+
+def ios_platform():
+    uname_code, uname_output = run(["uname", "-s"])
+    darwin = uname_code == 0 and uname_output.splitlines()[-1:] == ["Darwin"]
+    checks = {"macos": check("ready" if darwin else "environment-fail", uname_output or "unavailable", "Darwin tester node", "Route iOS tests to the Mac tester node" if not darwin else "")}
+    if not darwin:
+        checks.update({
+            "xcrun": check("environment-fail", "not invoked", "xcrun available", "Use a macOS tester node"),
+            "simctl": check("environment-fail", "not invoked", "simctl available", "Use a macOS tester node"),
+            "boot": check("environment-fail", "not checked", "booted iOS simulator", "Use a macOS tester node"),
+        })
+        return response("environment-fail", "remote node is not macOS", checks)
+    xcrun_code, xcrun_output = run(["xcrun", "--version"])
+    simctl_code, simctl_output = run(["xcrun", "simctl", "list", "devices", "--json"])
+    booted = False
+    if simctl_code == 0:
+        try:
+            data = json.loads(simctl_output)
+            booted = any(
+                isinstance(device, dict) and device.get("state") == "Booted"
+                for devices in (data.get("devices") or {}).values()
+                if isinstance(devices, list)
+                for device in devices
+            )
+        except (TypeError, json.JSONDecodeError):
+            booted = False
+    checks.update({
+        "xcrun": check("ready" if xcrun_code == 0 else "environment-fail", xcrun_output or "unavailable", "xcrun available", "Install/select Xcode command-line tools" if xcrun_code else ""),
+        "simctl": check("ready" if simctl_code == 0 else "environment-fail", "available" if simctl_code == 0 else simctl_output, "simctl available", "Check Xcode simulator runtime" if simctl_code else ""),
+        "boot": check("ready" if booted else "environment-fail", "booted simulator" if booted else "no booted simulator", "booted iOS simulator", "Boot an iOS simulator" if not booted else ""),
+    })
+    status = "ready" if all(item["status"] == "ready" for item in checks.values()) else "environment-fail"
+    return response(status, "macOS/xcrun/simctl probe completed", checks)
+
+def network_probe():
+    raw_url = request.get("url")
+    parsed = urllib.parse.urlsplit(raw_url or "")
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname or parsed.username or parsed.password:
+        return response("blocked", "URL must be http(s) without embedded credentials", remediation="Provide a credential-free probe URL")
+    port = parsed.port or (443 if parsed.scheme == "https" else 80)
+    try:
+        addresses = socket.getaddrinfo(parsed.hostname, port, type=socket.SOCK_STREAM)
+    except (OSError, ValueError) as exc:
+        return response("environment-fail", "DNS probe failed", {"dns": check("environment-fail", str(exc), "resolvable hostname", "Check tester-node DNS/VPN")})
+    checks = {"dns": check("ready", sorted({item[4][0] for item in addresses}), "resolvable hostname")}
+    try:
+        with socket.create_connection((parsed.hostname, port), timeout=5):
+            pass
+        checks["tcp"] = check("ready", f"{parsed.hostname}:{port}", "TCP connection")
+    except OSError as exc:
+        checks["tcp"] = check("environment-fail", str(exc), f"TCP {parsed.hostname}:{port}", "Check tester-node route and firewall")
+        return response("environment-fail", "TCP probe failed", checks)
+    try:
+        with urllib.request.urlopen(urllib.request.Request(raw_url, method="GET"), timeout=5) as result:
+            code = result.status
+    except urllib.error.HTTPError as exc:
+        code = exc.code
+    except (OSError, urllib.error.URLError) as exc:
+        checks["http"] = check("environment-fail", str(exc), "HTTP response", "Check service listener, proxy and TLS")
+        return response("environment-fail", "HTTP probe failed", checks)
+    expected = request.get("probe", {}).get("expected_status") if isinstance(request.get("probe"), dict) else None
+    matches = not isinstance(expected, list) or code in expected
+    checks["http"] = check("ready" if 200 <= code < 500 and matches else "environment-fail", code, expected or "HTTP 2xx-4xx", "Check service health or expected_status" if not matches or code >= 500 else "")
+    return response("ready" if checks["http"]["status"] == "ready" else "environment-fail", "DNS/TCP/HTTP probe completed", checks)
+
+operation = request.get("operation")
+if operation == "platform_probe" and request.get("platform") == "ios":
+    result = ios_platform()
+elif operation == "network_probe":
+    result = network_probe()
+elif operation == "maestro" and request.get("platform") == "ios":
+    flow = request.get("flow")
+    values = request.get("env") if isinstance(request.get("env"), dict) else {}
+    if not isinstance(flow, str) or not flow.strip() or len(flow.encode("utf-8")) > 120000:
+        result = response("blocked", "maestro requires a bounded non-empty flow")
+    elif any(not isinstance(key, str) or not key.isidentifier() or not key.isupper() or not isinstance(value, str) or len(value) > 4096 for key, value in values.items()):
+        result = response("blocked", "maestro env must contain uppercase text values")
+    else:
+        flow_path = Path("/tmp") / ("pouch-maestro-" + uuid.uuid4().hex + ".yaml")
+        try:
+            flow_path.write_text(flow, encoding="utf-8")
+            env = os.environ.copy()
+            env["PATH"] = "/Users/laily/bin:/Users/laily/.maestro/bin:/opt/homebrew/bin:" + env.get("PATH", "")
+            env["JAVA_HOME"] = "/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home"
+            env["MAESTRO_CLI_NO_ANALYTICS"] = "true"
+            device = "booted"
+            sim_code, sim_output = run(["xcrun", "simctl", "list", "devices", "--json"], env=env, timeout=30)
+            if sim_code == 0:
+                try:
+                    sim_data = json.loads(sim_output)
+                    booted = [
+                        item.get("udid") for devices in (sim_data.get("devices") or {}).values()
+                        if isinstance(devices, list)
+                        for item in devices
+                        if isinstance(item, dict) and item.get("state") == "Booted" and item.get("udid")
+                    ]
+                    if booted:
+                        device = str(booted[0])
+                        # Maestro's iOS driver uses IDB for simulator I/O.  The
+                        # companion is deliberately connected through the user
+                        # local path; Homebrew cannot create /usr/local/bin here.
+                        run(["idb", "connect", device, "--json"], env=env, timeout=20)
+                except (TypeError, json.JSONDecodeError):
+                    pass
+            command = ["/Users/laily/.maestro/bin/maestro", "test", "--device", device, "--no-color", str(flow_path)]
+            for key, value in values.items():
+                command.extend(["-e", key + "=" + value])
+            code, output = run(command, env=env, timeout=float(request.get("timeout") or 180))
+            result = response("ready" if code not in {124, 127} else "environment-fail", "maestro completed" if code == 0 else ("maestro command unavailable" if code == 127 else "maestro timed out"), {"maestro": check("ready" if code == 0 else ("environment-fail" if code in {124, 127} else "ready"), output[-6000:], "Maestro flow executed")})
+            result.update({"test_result": "pass" if code == 0 else ("environment-fail" if code in {124, 127} else "fail"), "exit": code, "output": output[-6000:]})
+        finally:
+            try:
+                flow_path.unlink()
+            except OSError:
+                pass
+elif operation == "maestro_batch" and request.get("platform") == "ios":
+    cases = request.get("cases")
+    if not isinstance(cases, list) or not cases or len(cases) > 64:
+        result = response("blocked", "maestro_batch requires 1-64 cases")
+    else:
+        values = request.get("env", {})
+        if not isinstance(values, dict) or any(not isinstance(key, str) or not key.isidentifier() or not key.isupper() or not isinstance(value, str) or len(value) > 4096 for key, value in values.items()):
+            result = response("blocked", "maestro env must contain uppercase text values")
+        else:
+            env = os.environ.copy()
+            env["PATH"] = "/Users/laily/bin:/Users/laily/.maestro/bin:/opt/homebrew/bin:" + env.get("PATH", "")
+            env["JAVA_HOME"] = "/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home"
+            env["MAESTRO_CLI_NO_ANALYTICS"] = "true"
+            device = "booted"
+            sim_code, sim_output = run(["xcrun", "simctl", "list", "devices", "--json"], env=env, timeout=30)
+            if sim_code == 0:
+                try:
+                    sim_data = json.loads(sim_output)
+                    booted = [
+                        item.get("udid") for devices in (sim_data.get("devices") or {}).values()
+                        if isinstance(devices, list)
+                        for item in devices
+                        if isinstance(item, dict) and item.get("state") == "Booted" and item.get("udid")
+                    ]
+                    if booted:
+                        device = str(booted[0])
+                        run(["idb", "connect", device, "--json"], env=env, timeout=20)
+                except (TypeError, json.JSONDecodeError):
+                    pass
+            results = []
+            for item in cases:
+                case_id = item.get("id") if isinstance(item, dict) else None
+                flow = item.get("flow") if isinstance(item, dict) else None
+                case_env = item.get("env", values) if isinstance(item, dict) else values
+                if not isinstance(case_id, str) or not case_id or not isinstance(flow, str) or not flow.strip() or len(flow.encode("utf-8")) > 120000:
+                    results.append({"id": str(case_id or ""), "test_result": "environment-fail", "exit": 2, "output": "invalid maestro batch case"})
+                    continue
+                if not isinstance(case_env, dict) or any(not isinstance(key, str) or not key.isidentifier() or not key.isupper() or not isinstance(value, str) or len(value) > 4096 for key, value in case_env.items()):
+                    results.append({"id": case_id, "test_result": "environment-fail", "exit": 2, "output": "invalid maestro batch env"})
+                    continue
+                flow_path = Path("/tmp") / ("pouch-maestro-batch-" + uuid.uuid4().hex + ".yaml")
+                try:
+                    flow_path.write_text(flow, encoding="utf-8")
+                    command = ["/Users/laily/.maestro/bin/maestro", "test", "--device", device, "--no-color", str(flow_path)]
+                    for key, value in case_env.items():
+                        command.extend(["-e", key + "=" + value])
+                    code, output = run(command, env=env, timeout=float(request.get("case_timeout") or 180))
+                    test_result = "pass" if code == 0 else ("environment-fail" if code in {124, 127} else "fail")
+                    results.append({"id": case_id, "test_result": test_result, "exit": code, "output": output[-6000:]})
+                except Exception as exc:
+                    results.append({"id": case_id, "test_result": "environment-fail", "exit": 124, "output": str(exc)})
+                finally:
+                    try:
+                        flow_path.unlink()
+                    except OSError:
+                        pass
+            has_env_failure = any(item.get("test_result") == "environment-fail" for item in results)
+            result = response("environment-fail" if has_env_failure else "ready", "maestro batch completed", {"maestro": check("environment-fail" if has_env_failure else "ready", f"{len(results)} cases", "Maestro batch executed")})
+            result.update({"results": results})
+elif operation == "artifact_download":
+    url = request.get("url")
+    destination = request.get("destination")
+    if not isinstance(url, str) or not url.startswith("https://git.duguying.net/"):
+        result = response("blocked", "artifact_download only accepts the configured Gitea host")
+    elif not isinstance(destination, str) or not destination.startswith("/Users/laily/orca/workspaces/app/"):
+        result = response("blocked", "artifact destination must stay under the Mac tester artifact root")
+    else:
+        dest = Path(destination)
+        archive = dest.with_suffix(".artifact.zip")
+        try:
+            config_paths = [
+                Path.home() / ".config" / "tea" / "config.yml",
+                Path("/Users/duguying/.config/tea/config.yml"),
+            ]
+            config_path = next((item for item in config_paths if item.is_file()), None)
+            if config_path is None:
+                raise RuntimeError("Mac mini tea login for git.duguying.net is missing")
+            config_text = config_path.read_text(encoding="utf-8")
+            token_match = re.search(r"name:\s*git\.duguying\.net[\s\S]*?token:\s*([^\s]+)", config_text)
+            token = token_match.group(1) if token_match else ""
+            if not token:
+                raise RuntimeError(f"Mac mini tea login for git.duguying.net is missing in {config_path}")
+            request_obj = urllib.request.Request(url, headers={"Authorization": f"token {token}", "User-Agent": "pouch-tester/1"})
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            with urllib.request.urlopen(request_obj, timeout=120) as source, archive.open("wb") as target:
+                shutil.copyfileobj(source, target)
+            with zipfile.ZipFile(archive) as artifact_archive:
+                nested = next((name for name in artifact_archive.namelist() if name.endswith("ios-simulator.zip")), None)
+                if not nested:
+                    raise RuntimeError("Gitea artifact does not contain ios-simulator.zip")
+                nested_bytes = artifact_archive.read(nested)
+            nested_archive = dest.with_suffix(".ios-simulator.zip")
+            nested_archive.write_bytes(nested_bytes)
+            with zipfile.ZipFile(nested_archive) as app_archive:
+                app_archive.extractall(dest.parent)
+            app = dest.parent / "Writes.app"
+            if not app.is_dir() or not (app / "Info.plist").is_file():
+                raise RuntimeError("downloaded iOS artifact does not contain Writes.app/Info.plist")
+            result = response("ready", "iOS simulator artifact downloaded", {"artifact": check("ready", str(app), "remote artifact present")})
+        except Exception as exc:
+            result = response("environment-fail", "iOS simulator artifact download failed", remediation=str(exc))
+elif operation in {"install", "start"} and request.get("platform") == "ios":
+    identity = request.get("identity")
+    artifact = request.get("artifact")
+    if operation == "install":
+        if not isinstance(artifact, str) or not (Path(artifact).is_file() or Path(artifact).is_dir()):
+            result = response("environment-fail", "remote iOS artifact is not present", remediation="Provide artifact.remote_path on the Mac tester node")
+        else:
+            sim_code, sim_output = run(["xcrun", "simctl", "list", "devices", "--json"])
+            device = "booted"
+            if sim_code == 0:
+                try:
+                    sim_data = json.loads(sim_output)
+                    booted = [
+                        item.get("udid") for devices in (sim_data.get("devices") or {}).values()
+                        if isinstance(devices, list)
+                        for item in devices
+                        if isinstance(item, dict) and item.get("state") == "Booted" and item.get("udid")
+                    ]
+                    if booted:
+                        device = str(booted[0])
+                except (TypeError, json.JSONDecodeError):
+                    pass
+            code, output = run(["xcrun", "simctl", "install", device, artifact])
+            result = response("ready" if code == 0 else "environment-fail", "iOS app installed" if code == 0 else output, {"install": check("ready" if code == 0 else "environment-fail", output or "installed", "simctl install succeeds", "Check IPA and simulator" if code else "")})
+    elif not isinstance(identity, str) or not identity:
+        result = response("blocked", "start requires bundle id")
+    else:
+        code, output = run(["xcrun", "simctl", "launch", "booted", identity])
+        result = response("ready" if code == 0 else "environment-fail", "iOS app started" if code == 0 else output, {"start": check("ready" if code == 0 else "environment-fail", output or "started", "simctl launch succeeds", "Check bundle id and installed app" if code else "")})
+else:
+    result = response("blocked", "unsupported remote runner operation", remediation="Use iOS platform_probe, network_probe, install, or start")
+
+print(marker + base64.b64encode(json.dumps(result, separators=(",", ":")).encode("utf-8")).decode("ascii"))
+'''
+
+
+def _terminal_output(result: dict[str, Any]) -> str:
+    terminal = result.get("terminal") if isinstance(result, dict) else None
+    if not isinstance(terminal, dict):
+        terminal = result
+    tail = terminal.get("tail") if isinstance(terminal, dict) else None
+    if isinstance(tail, list):
+        return "\n".join(str(item) for item in tail)
+    if isinstance(tail, str):
+        return tail
+    output = terminal.get("output") if isinstance(terminal, dict) else None
+    return output if isinstance(output, str) else ""
+
+
+def remote_runner_transport(binding_value: dict[str, Any], request: dict[str, Any], worktree: dict[str, Any]) -> dict[str, Any]:
+    environment = str(binding_value["location"]["environment"])
+    marker = "POUCH_RUNNER_RESULT_" + uuid.uuid4().hex
+    source = REMOTE_RUNNER_SOURCE
+    source_b64 = base64.b64encode(gzip.compress(source.encode("utf-8"), mtime=0)).decode("ascii")
+    payload = dict(request)
+    payload["_marker"] = marker
+    payload_b64 = base64.b64encode(gzip.compress(json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8"), mtime=0)).decode("ascii")
+    handle = ""
+    try:
+        def send_text(text: str) -> None:
+            # Keep each PTY write below the provider's line-editor limit, then
+            # submit it explicitly. Long base64 lines are accepted as input
+            # but may remain unsubmitted in fish.
+            orca_json(["terminal", "send", "--terminal", handle, "--text", text], environment)
+            orca_json(["terminal", "send", "--terminal", handle, "--text", "\r"], environment)
+            # The remote PTY acknowledges accepted bytes before fish has
+            # drained its input buffer. Leave room between chunks so no
+            # base64 data is dropped on slower Mac sessions.
+            time.sleep(0.2)
+
+        created = orca_json(["terminal", "create", "--worktree", f"id:{worktree['id']}", "--title", "tester-node-runner"], environment)
+        terminal = created.get("terminal") if isinstance(created, dict) else None
+        handle = str(terminal.get("handle")) if isinstance(terminal, dict) and terminal.get("handle") else ""
+        if not handle:
+            return runner_response("environment-fail", "remote runner terminal was not created", remediation="Check the Orca macmini terminal service")
+        remote_base = f"/tmp/pouch-remote-runner-{uuid.uuid4().hex}"
+        source_file = remote_base + ".b64"
+        payload_file = remote_base + ".payload.b64"
+        send_text(f": > {source_file}")
+        for offset in range(0, len(source_b64), 400):
+            send_text(f"printf '%s' '{source_b64[offset:offset + 400]}' >> {source_file}")
+        send_text(
+            "python3 -c 'import base64,gzip;open(\"%s.py\",\"wb\").write(gzip.decompress(base64.b64decode(open(\"%s\",\"rb\").read())))'"
+            % (remote_base, source_file)
+        )
+        send_text(f": > {payload_file}")
+        for offset in range(0, len(payload_b64), 400):
+            send_text(f"printf '%s' '{payload_b64[offset:offset + 400]}' >> {payload_file}")
+        # The embedded runner accepts base64(gzip(JSON)) on stdin directly.
+        send_text(f"python3 {remote_base}.py < {payload_file}")
+        runner_wait_ms = min(
+            900000,
+            max(15000, int(float(request.get("timeout") or request.get("case_timeout") or 180) * 1000) + 15000),
+        )
+        output = ""
+        deadline = time.monotonic() + runner_wait_ms / 1000
+        while time.monotonic() < deadline:
+            output = _terminal_output(orca_json(["terminal", "read", "--terminal", handle, "--limit", "20000"], environment))
+            for line in reversed(output.splitlines()):
+                if line.startswith(marker):
+                    try:
+                        result = json.loads(base64.b64decode(line[len(marker):]).decode("utf-8"))
+                    except (ValueError, json.JSONDecodeError):
+                        break
+                    if isinstance(result, dict):
+                        result.setdefault("checks", {})
+                        result["checks"].setdefault("binding", _runner_check("ready", binding_value["id"], "tester binding resolved"))
+                        result["checks"].setdefault("worktree", _runner_check("ready", worktree.get("path", "resolved"), "exact Orca worktree"))
+                        return result
+            time.sleep(1)
+        return runner_response("environment-fail", "remote runner did not return a protocol result", checks={
+            "binding": _runner_check("ready", binding_value["id"], "tester binding resolved"),
+            "worktree": _runner_check("ready", worktree.get("path", "resolved"), "exact Orca worktree"),
+            "transport": _runner_check("environment-fail", output[-1000:], "node runner protocol result", "Inspect the macmini terminal output"),
+        })
+    except (ConfigError, OSError) as exc:
+        return runner_response("environment-fail", "remote runner transport failed", remediation=str(exc))
+    finally:
+        if handle:
+            try:
+                orca_json(["terminal", "close", "--terminal", handle], environment)
+            except ConfigError:
+                pass
+
+
+def execute_runner_request(root: Path, request: Any) -> dict[str, Any]:
+    if not isinstance(request, dict):
+        return runner_response("blocked", "runner request must be a JSON object", remediation="Send one JSON object on stdin")
+    binding_id = request.get("binding")
+    operation = request.get("operation")
+    platform_name = request.get("platform")
+    if not isinstance(binding_id, str) or not BINDING_RE.fullmatch(binding_id):
+        return runner_response("blocked", "binding must be a safe namespace.name", remediation="Use the resolved tester.<name> binding")
+    if not isinstance(operation, str) or operation not in RUNNER_OPERATIONS:
+        return runner_response("blocked", "unknown runner operation", remediation="Use platform_probe, network_probe, install, or start")
+    if not isinstance(platform_name, str) or platform_name not in RUNNER_PLATFORMS:
+        return runner_response("blocked", "platform must be android or ios", remediation="Use the matrix platform")
+    try:
+        value = binding(load_config(root), binding_id)
+    except (ConfigError, OSError) as exc:
+        return runner_response("blocked", "tester binding could not be resolved", remediation=str(exc))
+    if value.get("adapter") != "tester":
+        return runner_response("blocked", "binding is not a tester binding", remediation="Use a binding with adapter: tester")
+    location = value["location"]
+    environment = str(location.get("environment"))
+    requested_node = request.get("node")
+    if requested_node is not None and (not isinstance(requested_node, str) or not requested_node.strip()):
+        return runner_response("blocked", "node must be non-empty text when provided")
+    if environment == "local":
+        if requested_node and requested_node not in LOCAL_NODE_NAMES:
+            return runner_response("blocked", "local binding does not match requested tester node", remediation="Use node: local or a local alias")
+        if operation == "platform_probe":
+            return _local_platform_probe(platform_name)
+        if operation == "network_probe":
+            return _network_probe(request)
+        if operation == "maestro":
+            return _local_maestro(platform_name, request)
+        return _local_mutation(platform_name, operation, request)
+    try:
+        worktree = worktree_for(value)
+    except ConfigError as exc:
+        return runner_response("blocked", "remote tester worktree could not be resolved", checks={
+            "binding": _runner_check("ready", binding_id, "tester binding resolved"),
+            "worktree": _runner_check("blocked", "unresolved", "exact Orca worktree", str(exc)),
+        }, remediation="Register one exact environment/host/project/path worktree before using the remote tester")
+    return remote_runner_transport(value, request, worktree)
+
+
+def cmd_run_exec(args: argparse.Namespace) -> int:
+    root = Path(args.root).resolve()
+    try:
+        request = json.load(sys.stdin)
+    except (json.JSONDecodeError, OSError):
+        response = runner_response("blocked", "runner stdin is not one valid JSON object", remediation="Send exactly one JSON object on stdin")
+    else:
+        try:
+            response = execute_runner_request(root, request)
+        except Exception:
+            print("agent-runtime runner: unexpected adapter failure", file=sys.stderr)
+            response = runner_response("environment-fail", "runner adapter failed before producing evidence", remediation="Inspect the tester binding and adapter environment")
+    print(json.dumps(response, ensure_ascii=False, separators=(",", ":")))
+    return 0
+
+
 def cmd_run_start(args: argparse.Namespace) -> int:
     root = Path(args.root).resolve()
     value = binding(load_config(root), args.binding)
@@ -474,6 +1170,8 @@ def parser() -> argparse.ArgumentParser:
     start.add_argument("--binding", required=True)
     start.add_argument("--wait-ms", type=int, default=0)
     start.set_defaults(func=cmd_run_start)
+    execute = run_sub.add_parser("exec", parents=[root_parent])
+    execute.set_defaults(func=cmd_run_exec)
     for name, func in (("status", cmd_run_status), ("attach", cmd_run_attach), ("resume", cmd_run_resume), ("stop", cmd_run_stop)):
         item = run_sub.add_parser(name, parents=[root_parent])
         item.add_argument("--run", required=True)

skills/agent-runtime/tests/test_runner.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import importlib.util
+import base64
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+
+SCRIPT = Path(__file__).resolve().parents[1] / "scripts" / "agent.py"
+SPEC = importlib.util.spec_from_file_location("agent_runtime_runner", SCRIPT)
+assert SPEC and SPEC.loader
+agent = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(agent)
+
+
+class RunnerTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.temp = tempfile.TemporaryDirectory()
+        self.root = Path(self.temp.name)
+        pouch = self.root / ".pouch"
+        pouch.mkdir()
+        (pouch / "agent.yaml").write_text(
+            """schemaVersion: 1
+locations:
+  local-app:
+    environment: local
+    host: local
+    project: local-project
+    path: /tmp/writes
+  remote-mac:
+    environment: macmini
+    host: runtime:0123456789abcdef0123
+    project: remote-project
+    path: /Users/tester/writes
+profiles:
+  test-agent:
+    cli: codex
+    model: null
+    reasoningEffort: medium
+    permissionMode: workspace-write
+bindings:
+  tester.android:
+    adapter: tester
+    location: local-app
+    profile: test-agent
+  tester.ios:
+    adapter: tester
+    location: remote-mac
+    profile: test-agent
+""",
+            encoding="utf-8",
+        )
+
+    def tearDown(self) -> None:
+        self.temp.cleanup()
+
+    def test_local_binding_routes_to_fixed_probe(self):
+        def command(argv, **_kwargs):
+            if argv == ["adb", "version"]:
+                return 0, "Android Debug Bridge version 1"
+            if argv == ["adb", "devices"]:
+                return 0, "List of devices attached\nemulator-5554\tdevice\n"
+            self.assertEqual(argv, ["adb", "-s", "emulator-5554", "shell", "getprop", "sys.boot_completed"])
+            return 0, "1"
+
+        with mock.patch.object(agent, "run_fixed_command", side_effect=command) as runner:
+            result = agent.execute_runner_request(self.root, {
+                "binding": "tester.android", "operation": "platform_probe", "platform": "android", "node": "local",
+            })
+        self.assertEqual(result["status"], "ready")
+        self.assertEqual(set(result["checks"]), {"adb", "device", "boot"})
+        self.assertEqual(runner.call_count, 3)
+
+    def test_remote_binding_uses_orca_terminal_transport(self):
+        marker = "POUCH_RUNNER_RESULT_" + ("0" * 31) + "1"
+        payload = {"status": "ready", "observed": "Darwin/xcrun/simctl probe completed", "checks": {"macos": {"status": "ready"}}}
+
+        def fake_orca(argv, _environment=None):
+            if argv[:2] == ["terminal", "create"]:
+                return {"terminal": {"handle": "term-1"}}
+            if argv[:2] == ["terminal", "read"]:
+                return {"terminal": {"tail": [marker + base64.b64encode(json.dumps(payload).encode()).decode()]}}
+            return {}
+
+        with mock.patch.object(agent, "worktree_for", return_value={"id": "wt-1", "path": "/Users/tester/writes"}) as resolve, \
+                mock.patch.object(agent, "orca_json", side_effect=fake_orca), \
+                mock.patch.object(agent.uuid, "uuid4", return_value=mock.Mock(hex="0" * 31 + "1")):
+            result = agent.execute_runner_request(self.root, {
+                "binding": "tester.ios", "operation": "platform_probe", "platform": "ios", "node": "macmini",
+            })
+        self.assertEqual(result["status"], "ready")
+        self.assertEqual(result["checks"]["binding"]["status"], "ready")
+        resolve.assert_called_once()
+
+    def test_remote_transport_submits_startup_command_when_first_read_has_no_marker(self):
+        marker = "POUCH_RUNNER_RESULT_" + ("0" * 31) + "1"
+        payload = {"status": "ready", "observed": "Darwin/xcrun/simctl probe completed", "checks": {"macos": {"status": "ready"}}}
+        reads = [
+            {"terminal": {"tail": ["Welcome to fish"]}},
+            {"terminal": {"tail": [marker + base64.b64encode(json.dumps(payload).encode()).decode()]}},
+        ]
+
+        def fake_orca(argv, _environment=None):
+            if argv[:2] == ["terminal", "create"]:
+                return {"terminal": {"handle": "term-1"}}
+            if argv[:2] == ["terminal", "read"]:
+                return reads.pop(0)
+            return {}
+
+        with mock.patch.object(agent, "worktree_for", return_value={"id": "wt-1", "path": "/Users/tester/writes"}), \
+                mock.patch.object(agent, "orca_json", side_effect=fake_orca) as orca, \
+                mock.patch.object(agent.uuid, "uuid4", return_value=mock.Mock(hex="0" * 31 + "1")):
+            result = agent.execute_runner_request(self.root, {
+                "binding": "tester.ios", "operation": "platform_probe", "platform": "ios", "node": "macmini",
+            })
+        self.assertEqual(result["status"], "ready")
+        self.assertTrue(any(call.args[0][:2] == ["terminal", "send"] for call in orca.call_args_list))
+
+    def test_unknown_operation_and_command_failure_are_structured(self):
+        unknown = agent.execute_runner_request(self.root, {
+            "binding": "tester.android", "operation": "exec", "platform": "android",
+        })
+        self.assertEqual(unknown["status"], "blocked")
+        with mock.patch.object(agent, "run_fixed_command", return_value=(127, "adb missing")):
+            failed = agent.execute_runner_request(self.root, {
+                "binding": "tester.android", "operation": "platform_probe", "platform": "android",
+            })
+        self.assertEqual(failed["status"], "environment-fail")
+
+    def test_json_stdout_is_single_protocol_object(self):
+        process = subprocess.run(
+            [sys.executable, str(SCRIPT), "run", "exec", "--root", str(self.root)],
+            input=json.dumps({"binding": "tester.android", "operation": "unknown", "platform": "android"}),
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=False,
+        )
+        self.assertEqual(process.returncode, 0)
+        self.assertEqual(json.loads(process.stdout)["status"], "blocked")
+        self.assertEqual(process.stderr, "")
+
+
+if __name__ == "__main__":
+    unittest.main()

skills/bugfix-ship/README.md

@@ -1,8 +1,8 @@
 # bugfix-ship（已弃用）
 
-`bugfix-ship` 已改名为 [short-ship](../short-ship/README.md)。本目录只是兼容占位，
+`bugfix-ship` 已并入 [ship](../ship/README.md)。本目录只是兼容占位，
 让旧项目里的 `.pouch.yaml`、已经装好的旧软链和旧说法不至于失效；真正的说明和流程都在
-`short-ship/`。
+`ship/`。命中后按 **short 模式** 执行。
 
 ## 使用示例
 
@@ -10,15 +10,15 @@
 使用 bugfix-ship，修复这个线上回归并部署到测试环境。
 ```
 
-Agent 命中后会立刻转到 `short-ship`，按同一套规则执行。新请求建议直接用新名。
+Agent 命中后会立刻转到 `ship`，按 short 模式执行。新请求建议直接用 `ship`。
 
 ## 迁移
 
 ```bash
-pouch add short-ship          # 新名，当前项目
+pouch add ship          # 新名，当前项目
-pouch add short-ship -g       # 新名，全局
+pouch add ship -g       # 新名，全局
 ```
 
 - 旧软链保持有效，不需要先删除。
-- 各项目 `.pouch.yaml` 里的 `bugfix-ship` 可以分批改成 `short-ship`。
+- 各项目 `.pouch.yaml` 里的 `bugfix-ship` 可以分批改成 `ship`。
 - 确认没有项目再按旧名启用后，删除本目录即可；它是纯占位，删除不丢内容。

skills/bugfix-ship/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: bugfix-ship
 description: >-
-  【已弃用，兼容占位】bugfix-ship 已改名为 short-ship。命中本 skill 时不要在此执行任何
+  【已弃用，兼容占位】bugfix-ship 已并入 ship。命中本 skill 时不要在此执行任何
-  流程，直接读取 ../short-ship/SKILL.md 并按其执行。小需求、小改动、修 bug、改文案、
+  流程，直接读取 ../ship/SKILL.md 并按其执行；本次按 short 模式。小需求、小改动、
-  加按钮、修复后发 PR 或部署都属于 short-ship。
+  修 bug、改文案、加按钮、修复后发 PR 或部署都属于 ship。
 ---
 
 # bugfix-ship（已弃用）
 
-本 skill 已改名为 [short-ship](../short-ship/SKILL.md)。这里只是兼容占位，**没有流程内容**。
+本 skill 已并入 [ship](../ship/SKILL.md)。这里只是兼容占位，**没有流程内容**。
 
 - 用户提到 `bugfix-ship`、`/bugfix-ship` 或 `$bugfix-ship` 时：读取
-  [../short-ship/SKILL.md](../short-ship/SKILL.md)，按其内容与授权边界执行，不要在本目录
+  [../ship/SKILL.md](../ship/SKILL.md)，按其内容与授权边界执行，并把本次 `kind`
-  里寻找步骤、references 或 templates。
+  定为 `short`。不要在本目录里寻找步骤、references 或 templates。
-- 本目录不保留 `references/` 和 `templates/`，正文只有一份，在 `short-ship/`。
+- 本目录不保留 `references/` 和 `templates/`，正文只有一份，在 `ship/`。
 - 旧项目 `.pouch.yaml` 里仍写 `bugfix-ship` 也能正常安装，软链不会悬空；方便时改成
-  `short-ship`。
+  `ship`。
 - 确认没有项目再按旧名启用后，可以直接删除本目录。

skills/builder/README.md

@@ -47,7 +47,7 @@ pouch add builder -g       # 全局
 并负责上层编排。
 
 1. `makefile.builder` 目标：`help/build/clean/version` + 条件 `deb/docker/push*`，
-   以及 `obtain` / `venue`。变量 `ARCHES/ARCH/VERSION/DIST_DIR/PROJECT_NAME/BUILD_VENUE`。
+   以及 `obtain` / `venue`。变量 `ARCHES/ARCH/VERSION/DIST_DIR/PROJECT_NAME/BUILD_VENUE/CI_STATUS_SCRIPT`。
    `VERSION` 通过 `include <builder>/scripts/version.mk` 从 Git 推导。
    多架构清单是 `ARCHES`，见下方「多架构」。
 2. 运行 `python3 -I -S <builder>/scripts/check.py . --ready` 直到构建项 PASS。
@@ -66,7 +66,7 @@ COPY_AS=latest.apk
 # COPY_SCRIPT=                 # 仅外部/临时脚本覆盖；项目内脚本写 makefile.builder
 ```
 
-`BUILD_VENUE=ci` 写在 `makefile.builder`：产物由 CI 构建。`make -f makefile.builder obtain`（或 `push-docker`）等待该 commit 的流水线并 inspect registry，不在本机 `docker push`。
+`BUILD_VENUE=ci` 写在 `makefile.builder`：产物由 CI 构建。初始化时确认查询命令（tea / glab / gh / curl），写成 `.pouch/builder/ci-status.sh`。`make -f makefile.builder obtain`（或 `push-docker`）执行该脚本等待流水线并 inspect registry，不在本机 `docker push`。
 
 4. 日常发布就是两条命令：
    `make -f makefile.builder deb && make -f makefile.builder push-deb`、
@@ -195,7 +195,7 @@ detached HEAD 用 `detached`，CI 可注入 `BUILD_BRANCH` / `CI_COMMIT_BRANCH`
 
 ## Agent 会做什么
 
-1. 初始化：探测 DEB / Docker / Android / iOS / copy 轨道，写出 `makefile.builder` 和 `.env.builder` 骨架，按仓库证据填 `ARCHES`（不默认双架构），不改你已有的 `Makefile` 或 `.env`。
+1. 初始化：探测 DEB / Docker / Android / iOS / copy 轨道，写出 `makefile.builder` 和 `.env.builder` 骨架，确认 `BUILD_VENUE`；选 ci 时生成 `.pouch/builder/ci-status.sh`。按仓库证据填 `ARCHES`（不默认双架构），不改你已有的 `Makefile` 或 `.env`。
 2. 检查：只跑 `scripts/check.py --ready`，不改文件。
 3. 构建：走 `make -f makefile.builder`；只获构建授权时不走会自动上传的目标。
 4. 发布：先校验产物，再上传。缺发布键、未授权、或可能覆盖同版本时停下问你。
@@ -223,7 +223,9 @@ Docker 只有你点名镜像时才走。token 不会写进输出、提交或回
 | `scripts/verify_deb.sh` | 核对包元数据、内容与 SHA-256 |
 | `scripts/copy_artifact.sh` | 按 `COPY_SCRIPT` 分发产物，未配置时拷到 `COPY_DEST` |
 | `scripts/obtain.sh` | 对精确 SHA 拿到产物；`BUILD_VENUE=ci` 时等流水线再 inspect |
-| `scripts/wait_ci.sh` | 只等该 SHA 的 GitLab/GitHub/Gitea 流水线，不触发；Gitea 读取 workflow jobs |
+| `scripts/wait_ci.sh` | 轮询项目 `CI_STATUS_SCRIPT`，只等该 SHA，不触发 |
+| `scripts/init_ci_status.sh` | 初始化时把 tea/glab/gh/curl 模板拷到 `.pouch/builder/ci-status.sh` |
+| `templates/ci-status/` | tea / glab / gh / curl 查询脚本模板；契约见 [ci-status.md](references/ci-status.md) |
 | `templates/makefile.android.builder` | Android APK + copy 轨道骨架 |
 | `templates/makefile.ios.builder` | iOS IPA + copy 轨道骨架 |
 

skills/builder/SKILL.md

@@ -35,7 +35,7 @@ worktree，也可以指向已配对的远程 Mac/其它构建机；不要把远
 - 初始化、接入 builder，或还没有 `makefile.builder`：执行「初始化」。
 - 检查契约或发布配置：执行「检查」。
 - 构建、发布、上传：执行「工作流」。不要静默初始化。
-- 看构建、监听 CI、ACK/short-ship/long-ship 要产物：执行「拿到产物」。不要当成第五条轨道。
+- 看构建、监听 CI、ACK/ship 要产物：执行「拿到产物」。不要当成第五条轨道。
 - 指定 `builder.<name>`、远程构建机或跨 session：先读共享 `agent-runtime`。
 - 不适用：本地安装/卸载 DEB；RPM/语言包；从零设计打包体系（先出方案）；普通编码与 Dockerfile 编辑。
 - 改本 skill 自身：契约先改 `scripts/check.py`，再同步 [contract.md](references/contract.md) 与 templates；不在生产上传上试脚本。
@@ -47,7 +47,8 @@ worktree，也可以指向已配对的远程 Mac/其它构建机；不要把远
 3. 没有 `makefile.builder`：按轨道拷模板。deb/docker 用 `templates/makefile.builder`；仅 android 用 `templates/makefile.android.builder`；仅 ios 用 `templates/makefile.ios.builder`。按轨道删掉未使用的 deb/docker/push* 段，把 `build` 的 TODO 换成仓库里已有的真实编译命令（可从用户 Makefile 抄配方，但不要 `include` 或递归调用它），且配方必须使用 `$(ARCH)`。Android/iOS 的 `ARCHES` 是构建机 ISA（fat APK/IPA 仍只留本机一项）。按 [contract.md](references/contract.md) 填 `ARCHES`：`debian/control` / CI matrix / 用户点名的子集；否则只写本机（`x86_64`→`amd64`，`aarch64`→`arm64`）。不要默认双架构；看不出交叉编法时只留一项并说明。`include` builder 的 `scripts/version.mk`。多产物把 `push` 改成 `push: push-deb push-docker push-copy` 的子集。不要改用户 Makefile。
 4. 已有 `makefile.builder`：跑检查；按 FAIL 给出修补说明。不覆盖 `build`。用户明确要求按契约改时再加 `ARCHES`，并确认配方里有 `$(ARCH)`。不要调用 create-makefile（版本规则冲突）。
 5. 没有 `.env.builder`：把 `<skill-dir>/templates/env.builder` 拷到项目根（注释键，不含值）。缺发布键时在报告里给出可粘贴示例，并把 `.env.builder` 加入 `.gitignore`，不要提交。
-6. 运行 `python3 -I -S <skill-dir>/scripts/check.py <project-dir> --ready`。结构校验通过且当前轨道能构建才称「完成」；只缺发布键是「部分完成」。契约 FAIL 或轨道工具缺失是「阻塞」。除非用户明确要求，不提交、不推送、不上传。
+6. 确认 `BUILD_VENUE`：`local` 或 `ci`，不要猜。选 `ci` 时读 [ci-status.md](references/ci-status.md)，确认查询命令（`tea` / `glab` / `gh` / `curl`），执行 `<skill-dir>/scripts/init_ci_status.sh --root <project-dir> --kind <kind>`，在 `makefile.builder` 写入 `BUILD_VENUE=ci` 和 `CI_STATUS_SCRIPT=.pouch/builder/ci-status.sh`。用户给了自定义查询命令时，把命令写进同一份脚本并保持 `STATUS=` 输出契约。
+7. 运行 `python3 -I -S <skill-dir>/scripts/check.py <project-dir> --ready`。结构校验通过且当前轨道能构建才称「完成」；只缺发布键是「部分完成」。契约 FAIL 或轨道工具缺失是「阻塞」。除非用户明确要求，不提交、不推送、不上传。
 
 ```text
 ## builder 初始化：完成 | 部分完成 | 阻塞
@@ -86,10 +87,10 @@ COPY_AS=latest.apk
 
 ## 拿到产物
 
-调用方是 short-ship、long-ship、ACK（delivery-loop 的 `artifact_built`），或用户要看 CI 构建。
+调用方是 ship、ACK（delivery-loop 的 `artifact_built`），或用户要看 CI 构建。
 按 [obtain.md](references/obtain.md) 执行 `scripts/obtain.sh --sha <commit>`。
 
 - `BUILD_VENUE=local`：当前 HEAD 必须是该 SHA，跑 makefile 的 docker/deb。
-- `BUILD_VENUE=ci`：等该 SHA 的 GitLab/GitHub/Gitea 流水线，再 inspect `version.sh --docker` 的镜像 tag。不触发流水线，不本机 push。
+- `BUILD_VENUE=ci`：`wait_ci.sh` 轮询项目的 `CI_STATUS_SCRIPT`，再 inspect `version.sh --docker` 的镜像 tag。不触发流水线，不本机 push。缺脚本则停下，回到初始化。
 - 失败（无流水线、job 失败、digest 不对）必须原样返回给调用方，不得标 `artifact_built`。
 - 合进默认分支若项目不跑 CI，这是正确失败；预览用 `dev/*`，正式用 tag。

skills/builder/references/ci-status.md

@@ -0,0 +1,55 @@
+# CI 状态查询脚本
+
+`BUILD_VENUE=ci` 时，流水线状态由**项目脚本**查询。builder 只轮询这份脚本，
+不在 skill 里猜 gh / glab / tea / curl。
+
+## 初始化
+
+选 `ci` 后确认查询方式，再生成脚本：
+
+```bash
+<skill-dir>/scripts/init_ci_status.sh --root <project> --kind tea|glab|gh|curl
+```
+
+写出 `.pouch/builder/ci-status.sh`（可执行、进 git）。`makefile.builder` 写：
+
+```makefile
+BUILD_VENUE ?= ci
+CI_STATUS_SCRIPT ?= .pouch/builder/ci-status.sh
+```
+
+相对路径只能在 `.pouch/builder/` 下。凭据仍放 `.env.builder`（如 `GITEA_TOKEN`），
+不要写进脚本参数或日志。
+
+用户给了自定义命令时，把该命令写进同一份脚本，输出必须符合下方契约。
+
+## 调用
+
+```bash
+.pouch/builder/ci-status.sh --sha <40-character-sha>
+```
+
+只查询、不触发流水线。`BUILDER_PROJECT_ROOT` 是项目根。
+
+## 输出
+
+退出 0 且 stdout 含 `STATUS=` 键值（可多行或同一行）：
+
+| STATUS | 含义 |
+| --- | --- |
+| `empty` | 该 SHA 还没有流水线 |
+| `running` | 已出现、尚未结束 |
+| `success` | 该 SHA 的流水线成功 |
+| `failed` | 失败、取消或超时 |
+| `error` | 查询本身失败（鉴权、CLI 缺失） |
+
+可选：`ID=`、`PIPELINE=`（URL）、`JOBS=`。
+
+| 退出码 | 含义 |
+| --- | --- |
+| 0 | 已查出状态（含 empty/running/failed） |
+| 2 | 用法错误 |
+| 3 | 无法查询（缺 CLI、未登录、被拒绝） |
+
+`wait_ci.sh` 按这份输出轮询：`empty` 超过出现窗口记 `no_pipeline`；
+`success` 才继续 obtain；`failed` 原样失败。

skills/builder/references/contract.md

@@ -52,7 +52,7 @@ make -f makefile.builder <target>
 | `push-docker` | 同时有多种发布轨道的项目 | `BUILD_VENUE=local` 时仅调 `publish_docker.sh`；`ci` 时仅调 `obtain.sh` |
 | `push-copy` | 同时有多种发布轨道的项目 | 仅调 builder 的 `copy_artifact.sh`；由它按配置选择内置拷贝或自定义脚本 |
 | `push` | 单一产物类型时必备；多产物项目为聚合 | 依序调用对应 push-* 或直接调脚本；是发布的唯一 make 入口 |
-| `obtain` | 有产物的项目 | 调用 `obtain.sh`，对精确 commit SHA 拿到已存在的产物。`BUILD_VENUE=ci` 时等待该 SHA 的 forge 流水线再 inspect，不在本机 `docker push` |
+| `obtain` | 有产物的项目 | 调用 `obtain.sh`，对精确 commit SHA 拿到已存在的产物。`BUILD_VENUE=ci` 时轮询 `CI_STATUS_SCRIPT` 再 inspect，不在本机 `docker push` |
 | `venue` | 可选（新模板必备） | 打印一行 `BUILD_VENUE`（`local` 或 `ci`） |
 
 规则：
@@ -82,7 +82,8 @@ make -f makefile.builder <target>
 
 | 变量 | 默认 | 说明 |
 |------|------|------|
-| `BUILD_VENUE` | `local` | 产物在哪构建：`local` 本机 make；`ci` 由 GitLab/GitHub/Gitea 流水线构建。这不是新轨道。写在 `makefile.builder` 并提交。`ci` 时 `push-docker` 委托 `obtain.sh`（等流水线 + inspect），不跑 `publish_docker.sh` |
+| `BUILD_VENUE` | `local` | 产物在哪构建：`local` 本机 make；`ci` 由项目 CI 流水线构建。这不是新轨道。写在 `makefile.builder` 并提交。`ci` 时 `push-docker` 委托 `obtain.sh`（等流水线 + inspect），不跑 `publish_docker.sh` |
+| `CI_STATUS_SCRIPT` | `.pouch/builder/ci-status.sh` | `BUILD_VENUE=ci` 时必填。项目内查询该 SHA 流水线状态的可执行脚本，相对路径只能在 `.pouch/builder/`。初始化时按 tea / glab / gh / curl 生成，契约见 [ci-status.md](ci-status.md) |
 | `ARCHES` | `amd64` | 本项目要发布的架构清单，空格分隔，子集只能是 `amd64` `arm64`。写在 `makefile.builder` 里并提交；不要放进 `.env.builder`。缺省或无 `arches` 目标时视为单架构 `amd64`。不要默认写成双架构 |
 | `ARCH` | `$(firstword $(ARCHES))` | 这一次构建的架构。必须落在 `ARCHES` 里；非法值必须 `$(error)` 并提示合法值。命令行/环境传入时只构建/上传这一项 |
 | `VERSION` | `` （空） | 为空时按「版本号」节从 Git 祖先稳定 tag 推导；禁止 `sort -V` 取全局最新 |
@@ -189,7 +190,7 @@ include $(HOME)/.pouch/skills/builder/scripts/version.mk
 
 `PLATFORMS` 优先级（高 → 低）：用户这轮 `--platform` 或已 export 的 `PLATFORMS` → 命令行 `ARCH=` 映射的 `linux/$(ARCH)`（由 `push-docker` 传入）→ `.env.builder` 的 `PLATFORMS` → `makefile.builder` 的 `ARCHES` → `linux/amd64`。
 
-`BUILD_VENUE=ci` 时 Docker 发布路径是 `obtain.sh`：只认 **该 commit SHA** 的流水线。没有流水线、job 失败、超时、或 Harbor inspect 不到 `version.sh --docker` 算出的 tag，一律非零退出。不触发流水线。GitHub 用 `gh`、GitLab 用 `glab`、Gitea 用 `curl` 读取 Actions API；Gitea 会再次校验 `head_sha` 并读取 workflow jobs。合进默认分支若项目声明不构建，这是正确失败；调用方应打 tag 或推送到项目会构建的 ref（例如 `dev/*`）。CI job 若已经 `docker push`，obtain 成功即视为产物已在 registry，不要再本机 push 一次。
+`BUILD_VENUE=ci` 时 Docker 发布路径是 `obtain.sh`：`wait_ci.sh` 只轮询 `CI_STATUS_SCRIPT`，只认 **该 commit SHA**。没有流水线、job 失败、超时、或 Harbor inspect 不到 `version.sh --docker` 算出的 tag，一律非零退出。不触发流水线。查询命令在初始化时写成项目脚本，运行时不再猜测 gh / glab / tea / curl。合进默认分支若项目声明不构建，这是正确失败；调用方应打 tag 或推送到项目会构建的 ref（例如 `dev/*`）。CI job 若已经 `docker push`，obtain 成功即视为产物已在 registry，不要再本机 push 一次。
 
 配置来源优先级：shell 已显式设置的值 > 项目根 `.env.builder` > 失败并询问用户。
 `.env.builder` 由 builder 脚本加载（不回显任何值）；当前 shell 已设置的值优先。

skills/builder/references/obtain.md

@@ -5,7 +5,7 @@ docker / deb / android / ios / copy 仍是轨道；`BUILD_VENUE` 只说明构建
 
 ## 谁来调用
 
-- `short-ship` / `long-ship` 和 ACK 走到 delivery-loop 的 `artifact_built` 时。
+- `ship` 和 ACK 走到 delivery-loop 的 `artifact_built` 时。
 - 用户说「看构建」「监听 CI」「拿到镜像」时。
 - `make -f makefile.builder obtain` 或 `push-docker`（`BUILD_VENUE=ci`）。
 
@@ -36,13 +36,13 @@ TAG=1.4.2
 | 0 | 产物已核验 | `artifact_built` 完成 |
 | 1 | 该 SHA 无流水线、job 失败、超时、inspect 失败 | 标 `failed`，不得 publish/deploy |
 | 2 | 用法或配置错误 | 标 `blocked` |
-| 3 | glab/gh/curl 缺失或读不到该项目 | 停；可用**已打开且已登录**的同 host Orca tab 查流水线。禁止新开未登录页 |
+| 3 | 项目 CI 状态脚本无法查询 | 停；回到初始化补 `CI_STATUS_SCRIPT`，或用**已打开且已登录**的同 host Orca tab 查流水线。禁止新开未登录页 |
 
 ## `ci` 规则
 
 - 只认该 SHA 的 pipeline，不认默认分支「最新一次绿」。
 - 不触发流水线。
-- Gitea 使用 Actions REST API 的 `head_sha` 精确过滤，并读取每个 workflow run 的 jobs；私有仓库可在 `.env.builder` 配置 `GITEA_TOKEN`。自定义 Gitea host 可设置 `BUILDER_CI_FORGE=gitea`，API 前缀默认是 `https://<origin-host>/api/v1`，也可用 `GITEA_API_URL` 覆盖。
+- 查询命令是项目 `.pouch/builder/ci-status.sh`（`CI_STATUS_SCRIPT`），初始化时按 tea / glab / gh / curl 写好。凭据仍放 `.env.builder`。
 - job 变绿不够，docker 轨道必须 inspect 到 digest。
 - 合进 `main` 若项目不构建，`no_pipeline` 是正确失败。预览走项目会构建的 ref（如 `dev/*`），正式走 tag。
 

skills/builder/scripts/check.py

@@ -551,8 +551,8 @@ def configured_value(
     return os.environ.get(key, "") or env_values.get(key, "") or (make_values or {}).get(key, "")
 
 
-def resolve_copy_script(project: Path, script: str) -> tuple[Path | None, str | None]:
+def resolve_builder_local_script(project: Path, script: str) -> tuple[Path | None, str | None]:
-    """Resolve COPY_SCRIPT without allowing arbitrary project-relative paths."""
+    """Resolve a project script; relative paths must stay under .pouch/builder/."""
     configured = Path(script).expanduser()
     if configured.is_absolute():
         return configured, None
@@ -561,10 +561,17 @@ def resolve_copy_script(project: Path, script: str) -> tuple[Path | None, str |
         allowed_root = (project / ".pouch" / "builder").resolve()
         resolved.relative_to(allowed_root)
     except ValueError:
-        return None, "relative COPY_SCRIPT must be under .pouch/builder/"
+        return None, "relative script must be under .pouch/builder/"
     return resolved, None
 
 
+def resolve_copy_script(project: Path, script: str) -> tuple[Path | None, str | None]:
+    path, error = resolve_builder_local_script(project, script)
+    if error:
+        return None, "relative COPY_SCRIPT must be under .pouch/builder/"
+    return path, None
+
+
 def check_copy_script(
     report: Report,
     project: Path,
@@ -591,6 +598,9 @@ def check_copy_script(
 
 
 def read_venue(project: Path) -> str:
+    env = (os.environ.get("BUILD_VENUE") or "").strip()
+    if env in ("local", "ci"):
+        return env
     result = run_make(project, "venue")
     if not has_no_rule(result):
         echoed = parse_dry_echo(result)
@@ -604,34 +614,35 @@ def read_venue(project: Path) -> str:
     return raw or "local"
 
 
-def origin_forge(project: Path) -> str:
+def check_ci_status_script(
-    result = subprocess.run(
+    report: Report,
-        ["git", "-C", str(project), "remote", "get-url", "origin"],
+    project: Path,
-        capture_output=True,
+    env_values: dict[str, str],
-        text=True,
+    make_values: dict[str, str],
-        check=False,
+) -> None:
+    if read_venue(project) != "ci":
+        report.add(SKIP, 15, "CI_STATUS_SCRIPT 可执行", "BUILD_VENUE is not ci")
+        return
+    script = configured_value("CI_STATUS_SCRIPT", env_values, make_values)
+    problems = []
+    if not script:
+        problems.append("BUILD_VENUE=ci requires CI_STATUS_SCRIPT")
+        path = None
+        resolve_error = None
+    else:
+        path, resolve_error = resolve_builder_local_script(project, script)
+    if resolve_error:
+        problems.append(resolve_error)
+    elif path is not None and not path.is_file():
+        problems.append("CI_STATUS_SCRIPT does not point to a file")
+    elif path is not None and not os.access(path, os.X_OK):
+        problems.append("CI_STATUS_SCRIPT is not executable")
+    report.add(
+        FAIL if problems else PASS,
+        15,
+        "CI_STATUS_SCRIPT 可执行",
+        "\n".join(problems) if problems else f"ci status script: {script}",
     )
-    url = (result.stdout or "").strip()
-    configured = env_file_values(project).get("BUILDER_CI_FORGE", "").strip().lower()
-    forced = (os.environ.get("BUILDER_CI_FORGE") or configured).strip().lower()
-    if forced in ("github", "gitlab", "gitea"):
-        return forced
-    if "github.com" in url:
-        return "github"
-    host_match = re.search(r"(?:https?://|ssh://git@|git@)([^/:]+)", url)
-    host = host_match.group(1).lower() if host_match else ""
-    builder_keys = env_file_keys(project)
-    if (
-        "gitea" in host
-        or "GITEA_TOKEN" in builder_keys
-        or "GITEA_API_URL" in builder_keys
-        or os.environ.get("GITEA_TOKEN")
-        or os.environ.get("GITEA_API_URL")
-    ):
-        return "gitea"
-    if url:
-        return "gitlab"
-    return ""
 
 
 def check_ready_toolchain(
@@ -655,28 +666,7 @@ def check_ready_toolchain(
         lines.append(
             f"docker: {'found' if docker_ok else 'optional for inspect; obtain fails without it'}"
         )
-        forge = origin_forge(project) if project is not None else ""
+        lines.append("CI status: project CI_STATUS_SCRIPT (tea/glab/gh/curl)")
-        if forge == "github":
-            gh_ok = shutil.which("gh") is not None
-            lines.append(f"gh: {'found' if gh_ok else 'MISSING (blocks ci venue)'}")
-            if not gh_ok:
-                problems.append("install gh and authenticate for this GitHub repo")
-        elif forge == "gitlab":
-            glab_ok = shutil.which("glab") is not None
-            lines.append(f"glab: {'found' if glab_ok else 'MISSING (blocks ci venue)'}")
-            if not glab_ok:
-                problems.append("install glab and authenticate for this GitLab project")
-        elif forge == "gitea":
-            curl_ok = shutil.which("curl") is not None
-            lines.append(f"curl: {'found' if curl_ok else 'MISSING (blocks ci venue)'}")
-            lines.append("Gitea API: /api/v1; GITEA_TOKEN optional for public repositories")
-            if not curl_ok:
-                problems.append("install curl to read Gitea Actions for this repository")
-        else:
-            glab_ok = shutil.which("glab") is not None
-            lines.append(f"glab: {'found' if glab_ok else 'MISSING (blocks ci venue)'}")
-            if not glab_ok:
-                problems.append("install glab and authenticate for this GitLab project")
     elif docker_project:
         docker_ok = shutil.which("docker") is not None
         lines.append(f"docker: {'found' if docker_ok else 'MISSING (blocks docker track)'}")
@@ -867,6 +857,7 @@ def main(argv: list[str] | None = None) -> int:
         check_ready_env_keys(
             report, project, deb_project=deb_project, docker_project=docker_project
         )
+        check_ci_status_script(report, project, env_file_values(project), makefile_values(project) if (project / BUILDER_MAKEFILE).is_file() else {})
         print()
         print(f"RESULT: FAILED ({report.failures} check(s) failed)")
         return 1
@@ -963,6 +954,12 @@ def main(argv: list[str] | None = None) -> int:
             docker_project=docker_project,
             copy_project=copy_project,
         )
+    check_ci_status_script(
+        report,
+        project,
+        env_file_values(project),
+        makefile_values(project),
+    )
 
     total_fail = report.failures
     print()

skills/builder/scripts/init_ci_status.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Copy a CI status template into the project.
+# Usage: init_ci_status.sh --root DIR --kind tea|glab|gh|curl
+
+usage() {
+  echo "Usage: init_ci_status.sh --root DIR --kind tea|glab|gh|curl" >&2
+}
+
+root=
+kind=
+while (($#)); do
+  case "$1" in
+    --root) [[ $# -ge 2 ]] || { usage; exit 2; }; root=$2; shift 2 ;;
+    --kind) [[ $# -ge 2 ]] || { usage; exit 2; }; kind=$2; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) usage; exit 2 ;;
+  esac
+done
+
+if [[ -z "$root" || -z "$kind" ]]; then
+  usage
+  exit 2
+fi
+case "$kind" in
+  tea|glab|gh|curl) ;;
+  *) echo "Error: --kind must be tea, glab, gh, or curl" >&2; exit 2 ;;
+esac
+
+script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+src=$script_dir/../templates/ci-status/${kind}.sh
+if [[ ! -f "$src" ]]; then
+  echo "Error: missing template: $src" >&2
+  exit 2
+fi
+
+dest=$root/.pouch/builder/ci-status.sh
+mkdir -p "$(dirname "$dest")"
+cp "$src" "$dest"
+chmod +x "$dest"
+echo "$dest"

skills/builder/scripts/obtain.sh

@@ -10,14 +10,13 @@ set -euo pipefail
 #
 # BUILD_VENUE (makefile.builder, default local):
 #   local  HEAD must be SHA; run `make -f makefile.builder docker` or `deb`
-#   ci     wait for the forge pipeline of this SHA, then inspect the image
+#   ci     wait for this SHA via the project CI_STATUS_SCRIPT, then inspect the image
-#          (GitHub Actions, GitLab CI, or Gitea Actions)
 #
 # Exit:
 #   0  artifact verified; prints ARTIFACT= / DIGEST= / SHA= / VENUE=
 #   1  no pipeline, job failed, inspect failed
 #   2  usage / config
-#   3  forge CLI cannot read the project (ci venue)
+#   3  CI status script cannot query (ci venue)
 
 usage() {
   sed -n '2,20p' "$0"

skills/builder/scripts/wait_ci.sh

@@ -1,25 +1,17 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# Wait until the forge pipeline for an exact commit SHA finishes.
+# Poll the project CI status script until the exact SHA finishes.
 # Does not trigger a pipeline. Does not print tokens.
 #
 # Usage:
 #   wait_ci.sh --sha SHA [--root DIR] [--timeout SEC]
 #
-# Supported forges:
+# The project script is CI_STATUS_SCRIPT (makefile.builder, default
-#   GitHub Actions (gh), GitLab CI (glab), and Gitea Actions (curl + REST API).
+# .pouch/builder/ci-status.sh). See references/ci-status.md.
-#   Set BUILDER_CI_FORGE=gitea for a custom Gitea host that does not contain
-#   "gitea" in its hostname. GITEA_API_URL may override the /api/v1 endpoint.
-#
-# Exit:
-#   0  pipeline succeeded; prints "OK pipeline=<url> sha=<sha>"
-#   1  no pipeline for this SHA, or a job failed/canceled
-#   2  usage / bad arguments
-#   3  forge CLI missing, or it cannot read this project
 
 usage() {
-  sed -n '2,18p' "$0"
+  sed -n '2,14p' "$0"
 }
 
 sha=
@@ -51,7 +43,6 @@ if [[ -z "$sha" ]]; then
 fi
 sha=$(git -C "$root" rev-parse "$sha")
 
-# Load only builder configuration. Shell values win and values are never echoed.
 if [[ -f "$root/.env.builder" ]]; then
   while IFS='=' read -r key value; do
     key=${key%%[[:space:]]*}
@@ -67,391 +58,126 @@ if [[ -f "$root/.env.builder" ]]; then
   done < <(grep -v '^[[:space:]]*$' "$root/.env.builder")
 fi
 
-python_json() {
+resolve_status_script() {
-  python3 -c "$1" "${@:2}"
+  local configured=${CI_STATUS_SCRIPT:-}
-}
+  if [[ -z "$configured" && -f "$root/makefile.builder" ]]; then
-
+    configured=$(make -s --no-print-directory -C "$root" -f makefile.builder print-CI_STATUS_SCRIPT 2>/dev/null | tail -n 1 || true)
-parse_origin() {
+  fi
-  python_json '
+  configured=${configured:-.pouch/builder/ci-status.sh}
-import os, re
+  local path
-url = os.environ["WAIT_CI_ORIGIN"].strip()
+  if [[ "$configured" == /* ]]; then
-url = re.sub(r"^git@([^:]+):", r"ssh://git@\1/", url)
+    path=$configured
-url = re.sub(r"^ssh://git@([^/]+):", r"ssh://git@\1/", url)
-if re.match(r"^https?://", url):
-    m = re.match(r"^(https?)://([^/]+)(?:/(.*))?$", url)
-    scheme, host, path = (m.group(1), m.group(2), m.group(3) or "") if m else ("", "", "")
-else:
-    m = re.match(r"^ssh://git@([^/]+)/(.+)$", url)
-    scheme, host, path = ("https", m.group(1), m.group(2)) if m else ("", "", "")
-path = re.sub(r"\.git$", "", path)
-override = os.environ.get("BUILDER_CI_FORGE", "").strip().lower()
-if override in ("github", "gitlab", "gitea"):
-    kind = override
-elif host == "github.com" or host.endswith(".github.com"):
-    kind = "github"
-elif ("gitea" in host.lower() or os.environ.get("GITEA_TOKEN") or
-      os.environ.get("GITEA_API_URL")):
-    kind = "gitea"
-else:
-    kind = "gitlab"
-print(kind, host, path, (scheme or "https") + "://" + host)
-'
-}
-
-origin=$(git -C "$root" remote get-url origin 2>/dev/null || true)
-if [[ -z "$origin" ]]; then
-  echo "Error: no origin remote" >&2
-  exit 2
-fi
-
-export WAIT_CI_ORIGIN=$origin
-read -r forge_kind forge_host forge_path forge_base <<<"$(parse_origin)"
-if [[ -z "$forge_kind" || -z "$forge_path" ]]; then
-  echo "Error: cannot parse origin: $origin" >&2
-  exit 2
-fi
-export WAIT_CI_PATH=$forge_path
-export WAIT_CI_SHA=$sha
-
-gitlab_pipelines() {
-  local encoded
-  encoded=$(python_json 'import os,urllib.parse; print(urllib.parse.quote(os.environ["WAIT_CI_PATH"], safe=""))')
-  glab api "projects/${encoded}/pipelines?sha=${sha}&per_page=20"
-}
-
-gitlab_jobs() {
-  local encoded pid=$1
-  encoded=$(python_json 'import os,urllib.parse; print(urllib.parse.quote(os.environ["WAIT_CI_PATH"], safe=""))')
-  glab api "projects/${encoded}/pipelines/${pid}/jobs"
-}
-
-github_runs() {
-  gh run list --repo "$forge_path" --commit "$sha" --limit 20 \
-    --json databaseId,status,conclusion,url,headSha
-}
-
-gitea_api_base=${GITEA_API_URL:-$forge_base/api/v1}
-gitea_api_base=${gitea_api_base%/}
-if [[ "$gitea_api_base" != */api/v1 ]]; then
-  gitea_api_base+="/api/v1"
-fi
-gitea_repo_path=$(python_json 'import os,urllib.parse; print(urllib.parse.quote(os.environ["WAIT_CI_PATH"], safe="/"))')
-
-gitea_curl() {
-  local url=$1
-  if [[ -n "${GITEA_TOKEN:-}" ]]; then
-    # Process substitution keeps the token out of curl's argument list and logs.
-    curl -fsS --retry 2 --connect-timeout 10 --max-time 30 \
-      --config <(printf 'header = "Authorization: token %s"\n' "$GITEA_TOKEN") "$url"
   else
-    curl -fsS --retry 2 --connect-timeout 10 --max-time 30 "$url"
+    path=$root/$configured
+    case "$configured" in
+      .pouch/builder/*) ;;
+      *)
+        echo "Error: relative CI_STATUS_SCRIPT must be under .pouch/builder/: $configured" >&2
+        exit 2
+        ;;
+    esac
   fi
+  if [[ ! -f "$path" ]]; then
+    echo "Error: CI status script missing: $path" >&2
+    echo "Run builder init with BUILD_VENUE=ci to write .pouch/builder/ci-status.sh" >&2
+    exit 2
+  fi
+  if [[ ! -x "$path" ]]; then
+    echo "Error: CI status script is not executable: $path" >&2
+    exit 2
+  fi
+  printf '%s' "$path"
 }
 
-gitea_runs() {
+parse_status() {
-  gitea_curl "${gitea_api_base}/repos/${gitea_repo_path}/actions/runs?head_sha=${sha}&limit=20&page=1"
+  python3 -c '
-}
+import sys
-
+text = sys.stdin.read()
-gitea_jobs() {
+values = {}
-  gitea_curl "${gitea_api_base}/repos/${gitea_repo_path}/actions/runs/$1/jobs?limit=100&page=1"
+for raw in text.replace("\n", " ").split():
-}
+    if "=" in raw:
-
+        key, value = raw.split("=", 1)
-summarize_gitlab() {
+        values[key.upper()] = value
-  python_json '
+print(values.get("STATUS", "error").lower())
-import json, sys
+print(values.get("ID", "-"))
-try:
+print(values.get("PIPELINE", "-"))
-    data = json.loads(sys.stdin.read())
+print(values.get("JOBS", ""))
-except json.JSONDecodeError:
-    print("error")
-    raise SystemExit(0)
-if isinstance(data, dict) and data.get("message"):
-    print("auth", data.get("message", "")[:80].replace(" ", "_"))
-    raise SystemExit(0)
-if not isinstance(data, list):
-    print("error")
-    raise SystemExit(0)
-if not data:
-    print("empty")
-    raise SystemExit(0)
-p = data[0]
-print(p.get("id"), p.get("status"), p.get("web_url", ""))
 '
 }
 
-summarize_jobs() {
+status_script=$(resolve_status_script)
-  python_json '
+export BUILDER_PROJECT_ROOT=$root
-import json, sys
-data = json.loads(sys.stdin.read())
-parts = []
-for j in data if isinstance(data, list) else []:
-    parts.append("%s=%s" % (j.get("name"), j.get("status")))
-print(",".join(parts))
-'
-}
 
-summarize_github() {
+query() {
-  python_json '
+  local out err rc
-import json, sys
+  err=$(mktemp)
-data = json.loads(sys.stdin.read())
+  set +e
-if not data:
+  out=$(BUILDER_PROJECT_ROOT="$root" "$status_script" --sha "$sha" 2>"$err")
-    print("empty")
+  rc=$?
-    raise SystemExit(0)
+  set -e
-r = data[0]
+  if [[ $rc -ne 0 ]]; then
-status = r.get("status")
+    echo "Error: CI status script exited $rc" >&2
-conc = r.get("conclusion")
+    sed '/token/Id; /Bearer/d; /Authorization/Id' "$err" >&2
-if status == "completed" and conc == "success":
+    rm -f "$err"
-    st = "success"
+    if [[ $rc -eq 2 ]]; then
-elif status == "completed":
+      exit 2
-    st = conc or "failed"
-else:
-    st = status or "running"
-print(r.get("databaseId"), st, r.get("url", ""))
-'
-}
-
-summarize_gitea_runs() {
-  python_json '
-import json, sys
-try:
-    data = json.loads(sys.stdin.read())
-except json.JSONDecodeError:
-    print("error")
-    raise SystemExit(0)
-if isinstance(data, dict) and data.get("message") and not (data.get("workflow_runs") or data.get("runs")):
-    print("auth", data.get("message", "")[:80].replace(" ", "_"))
-    raise SystemExit(0)
-if isinstance(data, dict):
-    data = data.get("workflow_runs", data.get("runs", []))
-if not isinstance(data, list):
-    print("error")
-    raise SystemExit(0)
-want = sys.argv[1] if len(sys.argv) > 1 else ""
-for run in data:
-    head = run.get("head_sha") or run.get("headSha") or (run.get("head_commit") or {}).get("id")
-    if not head or head.lower() != want.lower():
-        continue
-    run_id = run.get("id") or run.get("database_id")
-    if run_id is None:
-        continue
-    status = str(run.get("status") or "").lower()
-    conclusion = str(run.get("conclusion") or run.get("result") or "").lower()
-    url = run.get("html_url") or run.get("web_url") or run.get("url") or "-"
-    print("%s\t%s\t%s\t%s" % (run_id, status, conclusion, url))
-' "$sha"
-}
-
-summarize_gitea_jobs() {
-  python_json '
-import json, sys
-try:
-    data = json.loads(sys.stdin.read())
-except json.JSONDecodeError:
-    print("error")
-    raise SystemExit(0)
-if isinstance(data, dict) and data.get("message") and not data.get("jobs"):
-    print("auth", data.get("message", "")[:80].replace(" ", "_"))
-    raise SystemExit(0)
-if isinstance(data, dict):
-    data = data.get("jobs", [])
-if not isinstance(data, list):
-    print("error")
-    raise SystemExit(0)
-want = sys.argv[1] if len(sys.argv) > 1 else ""
-parts = []
-state = "success" if data else "empty"
-for job in data:
-    head = job.get("head_sha") or job.get("headSha")
-    if head and want and head.lower() != want.lower():
-        continue
-    name = str(job.get("name") or job.get("id") or "job").replace(" ", "_")
-    status = str(job.get("status") or "").lower()
-    result = str(job.get("conclusion") or job.get("result") or "").lower()
-    value = result or status or "unknown"
-    parts.append("%s=%s" % (name, value))
-    if value in ("failure", "failed", "cancelled", "canceled", "skipped", "timed_out", "action_required"):
-        state = "failed"
-    elif value not in ("success", "succeeded", "completed"):
-        state = "running"
-if not parts:
-    state = "empty"
-print("%s\t%s" % (state, ",".join(parts)))
-' "$sha"
-}
-
-gitea_status_line() {
-  local raw runs
-  if ! raw=$(gitea_runs); then
-    echo "error"
-    return 0
-  fi
-  runs=$(printf '%s' "$raw" | summarize_gitea_runs)
-  if [[ "$runs" == auth* || "$runs" == error ]]; then
-    printf '%s\n' "$runs"
-    return 0
-  fi
-  if [[ -z "$runs" ]]; then
-    echo "empty"
-    return 0
-  fi
-
-  local overall=success ids= urls= jobs_all= first=1
-  while IFS=$'\t' read -r id run_status conclusion url; do
-    [[ -z "$id" ]] && continue
-    local jobs job_line job_state job_summary
-    if ! jobs=$(gitea_jobs "$id"); then
-      echo "error"
-      return 0
     fi
-    job_line=$(printf '%s' "$jobs" | summarize_gitea_jobs "$sha")
-    job_state=${job_line%%$'\t'*}
-    job_summary=${job_line#*$'\t'}
-    if [[ "$job_state" == auth* || "$job_state" == error ]]; then
-      printf '%s\n' "$job_state"
-      return 0
-    fi
-    if [[ "$first" -eq 0 ]]; then
-      ids+=","; urls+=","; jobs_all+=","
-    fi
-    ids+="$id"; urls+="$url"; jobs_all+="$job_summary"; first=0
-    if [[ "$run_status" =~ ^(failure|failed|cancelled|canceled|skipped|timed_out|action_required)$ || "$conclusion" =~ ^(failure|failed|cancelled|canceled|skipped|timed_out|action_required)$ || "$job_state" == failed ]]; then
-      overall=failed
-    elif [[ "$overall" == success && ( "$job_state" == running || "$job_state" == empty || ( "$run_status" != completed && "$run_status" != success ) ) ]]; then
-      overall=running
-    fi
-  done <<<"$runs"
-  printf '%s %s %s %s\n' "$ids" "$overall" "$urls" "$jobs_all"
-}
-
-if [[ "$forge_kind" == github ]]; then
-  if ! command -v gh >/dev/null 2>&1; then
-    echo "Error: gh is required to watch GitHub Actions for $forge_host" >&2
     exit 3
   fi
-elif [[ "$forge_kind" == gitlab ]]; then
+  rm -f "$err"
-  if ! command -v glab >/dev/null 2>&1; then
+  printf '%s' "$out"
-    echo "Error: glab is required to watch GitLab CI for $forge_host" >&2
+}
-    exit 3
-  fi
-else
-  if ! command -v curl >/dev/null 2>&1; then
-    echo "Error: curl is required to watch Gitea Actions for $forge_host" >&2
-    exit 3
-  fi
-fi
 
 started=$(date +%s)
 first_seen=0
 empty_since=$started
 
-probe_auth() {
-  local out rc kind
-  if [[ "$forge_kind" == github ]]; then
-    set +e
-    out=$(github_runs 2>&1)
-    rc=$?
-    set -e
-    if [[ $rc -ne 0 ]]; then
-      echo "Error: gh cannot list runs for $forge_path" >&2
-      echo "$out" | sed '/token/Id; /Bearer/d' >&2
-      exit 3
-    fi
-    return
-  fi
-  if [[ "$forge_kind" == gitlab ]]; then
-    set +e
-    out=$(gitlab_pipelines 2>&1)
-    rc=$?
-    set -e
-    if [[ $rc -ne 0 ]]; then
-      echo "Error: glab cannot list pipelines for $forge_path on $forge_host" >&2
-      echo "$out" | sed '/token/Id; /Bearer/d' >&2
-      exit 3
-    fi
-    kind=$(printf '%s' "$out" | summarize_gitlab | awk '{print $1}')
-    if [[ "$kind" == auth ]]; then
-      echo "Error: glab is authenticated but cannot read $forge_path" >&2
-      exit 3
-    fi
-    return
-  fi
-  set +e
-  out=$(gitea_runs 2>&1)
-  rc=$?
-  set -e
-  if [[ $rc -ne 0 ]]; then
-    echo "Error: curl cannot read Gitea Actions for $forge_path on $forge_host" >&2
-    echo "$out" | sed '/token/Id; /Bearer/d; /Authorization/Id' >&2
-    exit 3
-  fi
-  kind=$(printf '%s' "$out" | summarize_gitea_runs | awk '{print $1}')
-  if [[ "$kind" == auth ]]; then
-    echo "Error: Gitea API rejected access to $forge_path" >&2
-    exit 3
-  fi
-}
-
-probe_auth
-
-status_line() {
-  if [[ "$forge_kind" == github ]]; then
-    github_runs | summarize_github
-  elif [[ "$forge_kind" == gitlab ]]; then
-    gitlab_pipelines | summarize_gitlab
-  else
-    gitea_status_line
-  fi
-}
-
 while true; do
   now=$(date +%s)
   if (( now - started > timeout_sec )); then
     echo "FAIL reason=timeout sha=$sha" >&2
     exit 1
   fi
-  line=$(status_line)
+  raw=$(query)
-  set -- $line
+  mapfile -t fields < <(printf '%s' "$raw" | parse_status)
-  kind=${1:-empty}
+  st=${fields[0]:-error}
-
+  pid=${fields[1]:--}
-  if [[ "$kind" == empty ]]; then
+  url=${fields[2]:--}
-    if (( now - empty_since >= appear_sec )); then
+  jobs_s=${fields[3]:-}
-      echo "FAIL reason=no_pipeline sha=$sha origin=$forge_host/$forge_path" >&2
-      echo "This SHA has no CI pipeline. Tag or push a ref the project actually builds." >&2
-      exit 1
-    fi
-    sleep "$poll_sec"
-    continue
-  fi
-  if [[ "$kind" == error || "$kind" == auth ]]; then
-    echo "Error: unexpected forge response for $forge_path" >&2
-    exit 3
-  fi
-
-  pid=$1
-  st=$2
-  url=$3
-  jobs_s=${4:-}
-  empty_since=$now
-  if [[ "$first_seen" -eq 0 ]]; then
-    echo "Watching pipeline $pid status=$st $url" >&2
-    first_seen=1
-  fi
 
   case "$st" in
+    empty)
+      if (( now - empty_since >= appear_sec )); then
+        echo "FAIL reason=no_pipeline sha=$sha" >&2
+        echo "This SHA has no CI pipeline. Tag or push a ref the project actually builds." >&2
+        exit 1
+      fi
+      sleep "$poll_sec"
+      continue
+      ;;
+    error)
+      echo "Error: unexpected CI status response" >&2
+      echo "$raw" | sed '/token/Id; /Bearer/d; /Authorization/Id' >&2
+      exit 3
+      ;;
     success)
       echo "OK pipeline=$url sha=$sha id=$pid jobs=$jobs_s"
       exit 0
       ;;
     failed|failure|canceled|cancelled|skipped)
-      if [[ "$forge_kind" == gitlab ]]; then
+      echo "FAIL reason=job_${st} sha=$sha pipeline=$url jobs=$jobs_s" >&2
-        jobs_s=$(gitlab_jobs "$pid" | summarize_jobs || true)
-      fi
-      echo "FAIL reason=job_$st sha=$sha pipeline=$url jobs=$jobs_s" >&2
       exit 1
       ;;
-    created|pending|running|waiting_for_resource|preparing|waiting|queued|in_progress|requested)
+    running|pending|queued|waiting|in_progress|created|preparing)
+      if [[ "$first_seen" -eq 0 ]]; then
+        echo "Watching pipeline $pid status=$st $url" >&2
+        first_seen=1
+      fi
+      empty_since=$now
       sleep "$poll_sec"
       ;;
     *)
+      empty_since=$now
       sleep "$poll_sec"
       ;;
   esac

skills/builder/templates/ci-status/curl.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Query Gitea Actions for an exact SHA via curl. Output STATUS= keys.
+# Auth: GITEA_TOKEN in the environment or .env.builder. GITEA_API_URL optional.
+
+sha=
+while (($#)); do
+  case "$1" in
+    --sha) sha=$2; shift 2 ;;
+    *) echo "Usage: ci-status.sh --sha SHA" >&2; exit 2 ;;
+  esac
+done
+[[ -n "$sha" ]] || { echo "Usage: ci-status.sh --sha SHA" >&2; exit 2; }
+
+if ! command -v curl >/dev/null 2>&1; then
+  echo "Error: curl is required" >&2
+  exit 3
+fi
+
+root=${BUILDER_PROJECT_ROOT:-$(git rev-parse --show-toplevel)}
+origin=$(git -C "$root" remote get-url origin 2>/dev/null || true)
+[[ -n "$origin" ]] || { echo "Error: no origin remote" >&2; exit 3; }
+
+read -r host path base <<<"$(WAIT_CI_ORIGIN=$origin python3 -c '
+import os, re
+url = os.environ["WAIT_CI_ORIGIN"].strip()
+url = re.sub(r"^git@([^:]+):", r"ssh://git@\1/", url)
+url = re.sub(r"^ssh://git@([^/]+):", r"ssh://git@\1/", url)
+if re.match(r"^https?://", url):
+    m = re.match(r"^(https?)://([^/]+)(?:/(.*))?$", url)
+    scheme, host, path = (m.group(1), m.group(2), m.group(3) or "") if m else ("", "", "")
+else:
+    m = re.match(r"^ssh://git@([^/]+)/(.+)$", url)
+    scheme, host, path = ("https", m.group(1), m.group(2)) if m else ("", "", "")
+path = re.sub(r"\.git$", "", path)
+print(host, path, (scheme or "https") + "://" + host)
+')"
+api=${GITEA_API_URL:-$base/api/v1}
+api=${api%/}
+[[ "$api" == */api/v1 ]] || api+=/api/v1
+repo=$(WAIT_CI_PATH=$path python3 -c 'import os,urllib.parse; print(urllib.parse.quote(os.environ["WAIT_CI_PATH"], safe="/"))')
+
+gitea_curl() {
+  if [[ -n "${GITEA_TOKEN:-}" ]]; then
+    curl -fsS --retry 2 --connect-timeout 10 --max-time 30 \
+      --config <(printf 'header = "Authorization: token %s"\n' "$GITEA_TOKEN") "$1"
+  else
+    curl -fsS --retry 2 --connect-timeout 10 --max-time 30 "$1"
+  fi
+}
+
+set +e
+runs=$(gitea_curl "${api}/repos/${repo}/actions/runs?head_sha=${sha}&limit=20&page=1")
+rc=$?
+set -e
+if [[ $rc -ne 0 ]]; then
+  echo "Error: curl cannot read Gitea Actions for $path" >&2
+  exit 3
+fi
+
+python3 -c '
+import json, sys
+sha = sys.argv[1]
+try:
+    data = json.loads(sys.stdin.read())
+except json.JSONDecodeError:
+    print("STATUS=error")
+    raise SystemExit(0)
+if isinstance(data, dict) and data.get("message") and not (data.get("workflow_runs") or data.get("runs")):
+    print("STATUS=error")
+    raise SystemExit(0)
+runs = data.get("workflow_runs", data.get("runs", [])) if isinstance(data, dict) else data
+if not isinstance(runs, list) or not runs:
+    print("STATUS=empty")
+    raise SystemExit(0)
+matched = []
+for run in runs:
+    head = run.get("head_sha") or run.get("headSha") or (run.get("head_commit") or {}).get("id")
+    if head and head.lower() == sha.lower() and (run.get("id") or run.get("database_id")):
+        matched.append(run)
+if not matched:
+    print("STATUS=empty")
+    raise SystemExit(0)
+run = matched[0]
+run_id = run.get("id") or run.get("database_id")
+url = run.get("html_url") or run.get("web_url") or run.get("url") or "-"
+status = str(run.get("status") or "").lower()
+conclusion = str(run.get("conclusion") or run.get("result") or "").lower()
+if conclusion in ("failure", "failed", "cancelled", "canceled", "skipped", "timed_out"):
+    state = "failed"
+elif status in ("completed", "success") and conclusion in ("", "success", "succeeded"):
+    state = "success"
+elif status == "completed" and conclusion:
+    state = "failed"
+else:
+    state = "running"
+print("STATUS=%s ID=%s PIPELINE=%s" % (state, run_id, url))
+' "$sha" <<<"$runs"

skills/builder/templates/ci-status/gh.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Query GitHub Actions for an exact SHA via gh. Output STATUS= keys.
+
+sha=
+while (($#)); do
+  case "$1" in
+    --sha) sha=$2; shift 2 ;;
+    *) echo "Usage: ci-status.sh --sha SHA" >&2; exit 2 ;;
+  esac
+done
+[[ -n "$sha" ]] || { echo "Usage: ci-status.sh --sha SHA" >&2; exit 2; }
+
+if ! command -v gh >/dev/null 2>&1; then
+  echo "Error: gh is required" >&2
+  exit 3
+fi
+
+root=${BUILDER_PROJECT_ROOT:-$(git rev-parse --show-toplevel)}
+origin=$(git -C "$root" remote get-url origin 2>/dev/null || true)
+[[ -n "$origin" ]] || { echo "Error: no origin remote" >&2; exit 3; }
+repo=$(WAIT_CI_ORIGIN=$origin python3 -c '
+import os, re
+url = os.environ["WAIT_CI_ORIGIN"].strip()
+url = re.sub(r"^git@([^:]+):", r"ssh://git@\1/", url)
+url = re.sub(r"^ssh://git@([^/]+):", r"ssh://git@\1/", url)
+if re.match(r"^https?://", url):
+    m = re.match(r"^https?://[^/]+(?:/(.*))?$", url)
+    path = m.group(1) if m else ""
+else:
+    m = re.match(r"^ssh://git@[^/]+/(.+)$", url)
+    path = m.group(1) if m else ""
+print(re.sub(r"\.git$", "", path or ""))
+')
+
+set +e
+raw=$(gh run list --repo "$repo" --commit "$sha" --limit 20 --json databaseId,status,conclusion,url,headSha)
+rc=$?
+set -e
+if [[ $rc -ne 0 ]]; then
+  echo "Error: gh cannot list runs for $repo" >&2
+  exit 3
+fi
+
+python3 -c '
+import json, sys
+try:
+    data = json.loads(sys.stdin.read())
+except json.JSONDecodeError:
+    print("STATUS=error")
+    raise SystemExit(0)
+if not data:
+    print("STATUS=empty")
+    raise SystemExit(0)
+r = data[0]
+status = str(r.get("status") or "").lower()
+conc = str(r.get("conclusion") or "").lower()
+if status == "completed" and conc == "success":
+    state = "success"
+elif status == "completed":
+    state = "failed"
+else:
+    state = "running"
+print("STATUS=%s ID=%s PIPELINE=%s" % (state, r.get("databaseId") or "-", r.get("url") or "-"))
+' <<<"$raw"

skills/builder/templates/ci-status/glab.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Query GitLab CI for an exact SHA via glab. Output STATUS= keys.
+
+sha=
+while (($#)); do
+  case "$1" in
+    --sha) sha=$2; shift 2 ;;
+    *) echo "Usage: ci-status.sh --sha SHA" >&2; exit 2 ;;
+  esac
+done
+[[ -n "$sha" ]] || { echo "Usage: ci-status.sh --sha SHA" >&2; exit 2; }
+
+if ! command -v glab >/dev/null 2>&1; then
+  echo "Error: glab is required" >&2
+  exit 3
+fi
+
+root=${BUILDER_PROJECT_ROOT:-$(git rev-parse --show-toplevel)}
+origin=$(git -C "$root" remote get-url origin 2>/dev/null || true)
+[[ -n "$origin" ]] || { echo "Error: no origin remote" >&2; exit 3; }
+path=$(WAIT_CI_ORIGIN=$origin python3 -c '
+import os, re
+url = os.environ["WAIT_CI_ORIGIN"].strip()
+url = re.sub(r"^git@([^:]+):", r"ssh://git@\1/", url)
+url = re.sub(r"^ssh://git@([^/]+):", r"ssh://git@\1/", url)
+if re.match(r"^https?://", url):
+    m = re.match(r"^https?://[^/]+(?:/(.*))?$", url)
+    path = m.group(1) if m else ""
+else:
+    m = re.match(r"^ssh://git@[^/]+/(.+)$", url)
+    path = m.group(1) if m else ""
+print(re.sub(r"\.git$", "", path or ""))
+')
+encoded=$(WAIT_CI_PATH=$path python3 -c 'import os,urllib.parse; print(urllib.parse.quote(os.environ["WAIT_CI_PATH"], safe=""))')
+
+set +e
+raw=$(glab api "projects/${encoded}/pipelines?sha=${sha}&per_page=20")
+rc=$?
+set -e
+if [[ $rc -ne 0 ]]; then
+  echo "Error: glab cannot list pipelines for $path" >&2
+  exit 3
+fi
+
+python3 -c '
+import json, sys
+try:
+    data = json.loads(sys.stdin.read())
+except json.JSONDecodeError:
+    print("STATUS=error")
+    raise SystemExit(0)
+if isinstance(data, dict) and data.get("message"):
+    print("STATUS=error")
+    raise SystemExit(0)
+if not isinstance(data, list) or not data:
+    print("STATUS=empty")
+    raise SystemExit(0)
+p = data[0]
+st = str(p.get("status") or "").lower()
+if st in ("success", "passed"):
+    state = "success"
+elif st in ("failed", "canceled", "cancelled", "skipped"):
+    state = "failed"
+elif st in ("",):
+    state = "empty"
+else:
+    state = "running"
+print("STATUS=%s ID=%s PIPELINE=%s" % (state, p.get("id") or "-", p.get("web_url") or "-"))
+' <<<"$raw"

skills/builder/templates/ci-status/tea.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Query Gitea Actions for an exact SHA via tea. Output STATUS= keys.
+
+sha=
+while (($#)); do
+  case "$1" in
+    --sha) sha=$2; shift 2 ;;
+    *) echo "Usage: ci-status.sh --sha SHA" >&2; exit 2 ;;
+  esac
+done
+[[ -n "$sha" ]] || { echo "Usage: ci-status.sh --sha SHA" >&2; exit 2; }
+
+if ! command -v tea >/dev/null 2>&1; then
+  echo "Error: tea is required" >&2
+  exit 3
+fi
+
+root=${BUILDER_PROJECT_ROOT:-$(git rev-parse --show-toplevel)}
+origin=$(git -C "$root" remote get-url origin 2>/dev/null || true)
+[[ -n "$origin" ]] || { echo "Error: no origin remote" >&2; exit 3; }
+path=$(WAIT_CI_ORIGIN=$origin python3 -c '
+import os, re
+url = os.environ["WAIT_CI_ORIGIN"].strip()
+url = re.sub(r"^git@([^:]+):", r"ssh://git@\1/", url)
+url = re.sub(r"^ssh://git@([^/]+):", r"ssh://git@\1/", url)
+if re.match(r"^https?://", url):
+    m = re.match(r"^https?://[^/]+(?:/(.*))?$", url)
+    path = m.group(1) if m else ""
+else:
+    m = re.match(r"^ssh://git@[^/]+/(.+)$", url)
+    path = m.group(1) if m else ""
+print(re.sub(r"\.git$", "", path or ""))
+')
+[[ -n "$path" ]] || { echo "Error: cannot parse origin" >&2; exit 3; }
+
+set +e
+runs=$(tea api "repos/${path}/actions/runs?head_sha=${sha}&limit=20")
+rc=$?
+set -e
+if [[ $rc -ne 0 ]]; then
+  echo "Error: tea cannot read Actions for $path" >&2
+  exit 3
+fi
+
+python3 -c '
+import json, sys
+sha = sys.argv[1]
+try:
+    data = json.loads(sys.stdin.read())
+except json.JSONDecodeError:
+    print("STATUS=error")
+    raise SystemExit(0)
+if isinstance(data, dict) and data.get("message") and not (data.get("workflow_runs") or data.get("runs")):
+    print("STATUS=error")
+    raise SystemExit(0)
+runs = data.get("workflow_runs", data.get("runs", [])) if isinstance(data, dict) else data
+if not isinstance(runs, list) or not runs:
+    print("STATUS=empty")
+    raise SystemExit(0)
+matched = [run for run in runs if str(run.get("head_sha") or run.get("headSha") or "").lower() == sha.lower()]
+if not matched:
+    print("STATUS=empty")
+    raise SystemExit(0)
+run = matched[0]
+run_id = run.get("id") or run.get("database_id") or "-"
+url = run.get("html_url") or run.get("web_url") or run.get("url") or "-"
+status = str(run.get("status") or "").lower()
+conclusion = str(run.get("conclusion") or run.get("result") or "").lower()
+if conclusion in ("failure", "failed", "cancelled", "canceled", "skipped", "timed_out"):
+    state = "failed"
+elif status in ("completed", "success") and conclusion in ("", "success", "succeeded"):
+    state = "success"
+elif status == "completed" and conclusion:
+    state = "failed"
+else:
+    state = "running"
+print("STATUS=%s ID=%s PIPELINE=%s" % (state, run_id, url))
+' "$sha" <<<"$runs"

skills/builder/templates/env.builder

@@ -11,8 +11,7 @@
 # DOCKER_REPOSITORY=
 # IMAGE_TAG=
 # PLATFORMS=          # optional override; project ARCHES lives in makefile.builder
-# BUILDER_CI_FORGE=   # optional: github, gitlab, or gitea; useful for custom hosts
+# GITEA_API_URL=      # optional for the curl CI status script
-# GITEA_API_URL=      # optional: defaults to https://<origin-host>/api/v1
 # GITEA_TOKEN=        # optional token for private Gitea repositories
 # COPY_DEST=          # fallback: local dir, or docker dest container:/absolute/dir
 # COPY_SCRIPT=                              # external/temporary executable override; project-local paths belong in makefile.builder

skills/builder/templates/makefile.builder

@@ -8,9 +8,10 @@
 
 ARCHES ?= amd64
 ARCH ?= $(firstword $(ARCHES))
-# local: make docker/deb on this machine. ci: obtain.sh waits for the
+# local: make docker/deb on this machine. ci: obtain.sh polls
-# forge pipeline of an exact SHA, then inspects the artifact. Not a track.
+# CI_STATUS_SCRIPT for an exact SHA, then inspects the artifact. Not a track.
 BUILD_VENUE ?= local
+CI_STATUS_SCRIPT ?= .pouch/builder/ci-status.sh
 ifeq ($(strip $(ARCHES)),)
 $(error ARCHES must not be empty)
 endif

skills/delivery-loop/README.md

@@ -4,7 +4,7 @@
 
 ## 什么时候使用
 
-通常由 `$short-ship`、`$pr-ship` 或 `$long-ship` 派发的 worker 读取，不需要单独调用。
+通常由 `$ship` 或 `$pr-ship` 派发的 worker 读取，不需要单独调用。
 入口主会话不要把本 skill 读进自己的上下文。
 
 ```text

skills/delivery-loop/SKILL.md

@@ -2,16 +2,16 @@
 name: delivery-loop
 description: >-
   为修复、PR 和需求任务提供可配置的验证、发 PR、合并、回归、构建、发布与部署状态机。
-  仅作为 short-ship、pr-ship、long-ship 的共享执行规则使用。
+  仅作为 ship、pr-ship 的共享执行规则使用。
 ---
 
 # Delivery Loop：共享交付状态机
 
-这是三个交付入口共用的内部规则，不直接替用户选择生产发布，也不替项目保存环境事实。
+这是 ship 与 pr-ship 共用的内部规则，不直接替用户选择生产发布，也不替项目保存环境事实。
 
 ## 使用方式
 
-由 `short-ship` / `long-ship` / `pr-ship` **派出来的 worker** 读取本 skill 和
+由 `ship` / `pr-ship` **派出来的 worker** 读取本 skill 和
 `references/state-machine.md`。入口主会话不要读取或执行本 skill。
 
 入口决定任务类型、停止点和派哪一步；本 skill 负责该步的阶段要求、证据和安全门。

skills/deployer/SKILL.md

@@ -83,6 +83,14 @@ ACK 的「运行测试环境」和回归前布环境会加载本 skill，按「C
 5. `prod` 环境：停止本轨道的 Compose 操作，读取 [production-agent.md](references/production-agent.md)，在本机 `~/code/app00` 项目创建 fresh Agent terminal 并委派正式部署；当前 Agent 不得直接执行 `sync.py`、`remote.py` 或 SSH。
 6. 只有明确点名的非正式远程 Compose 环境，才允许 `sync.py <svc>` 后调用 `remote.py <svc> recreate`；只重启调用 `remote.py <svc> restart`，并用 `remote.py <svc> ps` 验证。
 
+test-preflight 的一次性部署入口为 `scripts/deploy/prepare.py`。它从 stdin 接收
+`{"operation":"prepare","environment":"test","project_root":"/abs/project","host":"...","public_host":"..."}`，
+只解析项目 `.pouch/deployer/test`，复用 `lib.service_info` 的 `_config.yaml` 继承和 node
+规则，确认 node 是本机后才按 `docker compose config`、`up -d --force-recreate`、`ps`
+顺序准备单个 test 服务。输出始终是 `{status, observed, deployment_id?, checks?}` JSON；
+prod、缺配置、非本机 node 为 `blocked`，Compose/命令失败为 `environment-fail`。诊断只写
+stderr，不输出 `.env` 或命令输出中的凭据。
+
 compose 用 `image:` 且用户说刚合并了代码：现有 tag 对不上这次提交时，**一句问**要不要先重建镜像，然后停。不要自己改 tag、不要走 builder。
 
 新增/下线、deb、镜像 tag 升级、NAS 失败：再读 [compose.md](references/compose.md)。字段见 [config-reference.md](references/config-reference.md)。

skills/deployer/scripts/deploy/prepare.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""One-shot JSON adapter for preparing the project's test Compose service.
+
+The adapter owns no deployment policy of its own: service discovery and
+``_config.yaml`` inheritance stay in ``lib.service_info``.  The command runner
+is deliberately injectable so unit tests never need Docker, SSH, or a network.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Callable
+
+_SCRIPT_DIR = Path(__file__).resolve().parent
+if str(_SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPT_DIR))
+
+import lib  # noqa: E402
+
+
+STATUSES = {"ready", "blocked", "environment-fail"}
+LOCAL_NODE_NAMES = {"local", "localhost", "127.0.0.1", "::1"}
+CommandRunner = Callable[[list[str], Path], int]
+NodeChecker = Callable[[str], bool]
+
+
+def response(status: str, observed: str, *, deployment_id: str = "", checks: dict[str, Any] | None = None, remediation: str = "") -> dict[str, Any]:
+    if status not in STATUSES:
+        raise ValueError(f"invalid status: {status}")
+    value: dict[str, Any] = {"status": status, "observed": observed}
+    if deployment_id:
+        value["deployment_id"] = deployment_id
+    if checks:
+        value["checks"] = checks
+    if remediation:
+        value["remediation"] = remediation
+    return value
+
+
+def _check(status: str, observed: str, expected: str, remediation: str = "") -> dict[str, str]:
+    value = {"status": status, "observed": observed, "expected": expected}
+    if remediation:
+        value["remediation"] = remediation
+    return value
+
+
+def run_compose(command: list[str], cwd: Path) -> int:
+    """Run adapter-owned Compose argv without a shell or protocol pollution."""
+
+    try:
+        process = subprocess.run(
+            command,
+            cwd=str(cwd),
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return 127
+    return process.returncode
+
+
+def execute_compose(executor: CommandRunner, command: list[str], cwd: Path) -> int:
+    """Normalize mock/OS command failures into an environment-fail exit code."""
+
+    try:
+        return int(executor(command, cwd))
+    except (OSError, TypeError, ValueError):
+        return 127
+
+
+def node_is_local(node: str) -> bool:
+    """Accept only a local node; ``ssh -G`` is config inspection, never SSH."""
+
+    if node in LOCAL_NODE_NAMES:
+        return True
+    local_names = {socket.gethostname(), socket.getfqdn(), os.environ.get("HOSTNAME", "")}
+    if node in {name for name in local_names if name}:
+        return True
+    try:
+        process = subprocess.run(
+            ["ssh", "-G", node],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return False
+    if process.returncode != 0:
+        return False
+    configured_host = ""
+    for line in (process.stdout or "").splitlines():
+        key, _, value = line.partition(" ")
+        if key == "hostname":
+            configured_host = value.strip()
+            break
+    return configured_host in LOCAL_NODE_NAMES or configured_host in {name for name in local_names if name}
+
+
+def _project_root(value: Any) -> Path | None:
+    if not isinstance(value, str) or not value.strip():
+        return None
+    root = Path(value)
+    if not root.is_absolute() or ".." in root.parts or os.path.normpath(value) != value:
+        return None
+    return root
+
+
+def prepare_test(request: Any, *, executor: CommandRunner = run_compose, local_node: NodeChecker = node_is_local) -> dict[str, Any]:
+    if not isinstance(request, dict):
+        return response("blocked", "prepare request must be a JSON object", remediation="Send one JSON object on stdin")
+    if request.get("operation") != "prepare":
+        return response("blocked", "only operation=prepare is supported", remediation="Use the test deployer prepare contract")
+    environment = request.get("environment")
+    if environment != "test":
+        return response("blocked", "only the test environment is permitted", remediation="Use environment: test; production is never accepted by this adapter")
+    root = _project_root(request.get("project_root"))
+    if root is None or not root.is_dir():
+        return response("blocked", "project_root must be an existing absolute project directory", remediation="Provide the project root containing .pouch/deployer/test")
+    host = request.get("host")
+    if not isinstance(host, str) or not host.strip():
+        return response("blocked", "host is required", remediation="Provide the test service host used by preflight")
+    public_host = request.get("public_host")
+    if public_host is not None and (not isinstance(public_host, str) or not public_host.strip()):
+        return response("blocked", "public_host must be non-empty text when provided")
+
+    deploy_root = root / ".pouch" / "deployer"
+    test_dir = deploy_root / "test"
+    if not deploy_root.is_dir() or not test_dir.is_dir():
+        return response("blocked", "test deployer directory is missing", remediation="Create .pouch/deployer/test with its Compose files and _config.yaml")
+    lib.PROJECT_ROOT = deploy_root
+    try:
+        info = lib.service_info("test", strict=False)
+    except (OSError, ValueError, SystemExit):
+        info = None
+    if not info:
+        return response("blocked", "test Compose service is not discoverable", remediation="Ensure test/compose.yaml and inherited _config.yaml resolve a node")
+    node = str(info.get("node") or "")
+    if not node or not local_node(node):
+        return response("blocked", "test Compose node is not confirmed local", remediation=f"Resolve node {node or '<missing>'!r} to this machine; this adapter never falls back to SSH")
+    compose_file = test_dir / "compose.yaml"
+    if not compose_file.is_file():
+        return response("blocked", "test compose.yaml is missing", remediation="Provide .pouch/deployer/test/compose.yaml")
+
+    deployment_id = f"test:{info['name']}"
+    base = ["docker", "compose", "-f", "compose.yaml"]
+    checks: dict[str, Any] = {}
+    code = execute_compose(executor, [*base, "config", "--quiet"], test_dir)
+    if code != 0:
+        checks["compose_config"] = _check("environment-fail", f"docker compose config exited {code}", "valid test Compose configuration", "Fix the test Compose file or its local environment")
+        return response("environment-fail", "test Compose configuration failed", deployment_id=deployment_id, checks=checks)
+    checks["compose_config"] = _check("ready", "validated", "valid test Compose configuration")
+
+    code = execute_compose(executor, [*base, "up", "-d", "--force-recreate"], test_dir)
+    if code != 0:
+        checks["compose_up"] = _check("environment-fail", f"docker compose up exited {code}", "test services started", "Fix the local Docker/image/network failure and retry")
+        return response("environment-fail", "test Compose prepare failed", deployment_id=deployment_id, checks=checks)
+    checks["compose_up"] = _check("ready", "completed", "test services started")
+
+    code = execute_compose(executor, [*base, "ps"], test_dir)
+    if code != 0:
+        checks["compose_ps"] = _check("environment-fail", f"docker compose ps exited {code}", "test services report status", "Inspect local test service health")
+        return response("environment-fail", "test Compose status check failed", deployment_id=deployment_id, checks=checks)
+    checks["compose_ps"] = _check("ready", "completed", "test services report status")
+    return response("ready", "test Compose service prepared", deployment_id=deployment_id, checks=checks)
+
+
+def main() -> int:
+    try:
+        request = json.load(sys.stdin)
+    except (json.JSONDecodeError, OSError):
+        result = response("blocked", "prepare stdin is not one valid JSON object", remediation="Send exactly one JSON object on stdin")
+    else:
+        try:
+            result = prepare_test(request)
+        except Exception:
+            print("deployer prepare: unexpected adapter failure", file=sys.stderr)
+            result = response("environment-fail", "prepare adapter failed before producing evidence", remediation="Inspect the test deployer configuration")
+    print(json.dumps(result, ensure_ascii=False, separators=(",", ":")))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

skills/deployer/tests/test_prepare.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+SCRIPT = Path(__file__).resolve().parents[1] / "scripts" / "deploy" / "prepare.py"
+SPEC = importlib.util.spec_from_file_location("deployer_prepare", SCRIPT)
+assert SPEC and SPEC.loader
+prepare = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(prepare)
+
+
+class PrepareTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.temp = tempfile.TemporaryDirectory()
+        self.root = Path(self.temp.name)
+        deployer = self.root / ".pouch" / "deployer" / "test"
+        deployer.mkdir(parents=True)
+        (deployer / "compose.yaml").write_text("services:\n  app:\n    image: example:test\n", encoding="utf-8")
+        (deployer / "_config.yaml").write_text("node: devbox\nname: writes-test\n", encoding="utf-8")
+        self.request = {"operation": "prepare", "environment": "test", "project_root": str(self.root), "host": "http://test.local"}
+
+    def tearDown(self) -> None:
+        self.temp.cleanup()
+
+    def test_prod_is_rejected_without_inspecting_or_executing_compose(self):
+        calls = []
+        result = prepare.prepare_test({**self.request, "environment": "prod"}, executor=lambda command, cwd: calls.append(command) or 0)
+        self.assertEqual(result["status"], "blocked")
+        self.assertEqual(calls, [])
+
+    def test_missing_config_is_blocked(self):
+        (self.root / ".pouch" / "deployer" / "test" / "_config.yaml").unlink()
+        result = prepare.prepare_test(self.request, local_node=lambda node: True)
+        self.assertEqual(result["status"], "blocked")
+        self.assertIn("discoverable", result["observed"])
+
+    def test_mock_compose_prepare_is_ready(self):
+        calls = []
+
+        def executor(command, cwd):
+            calls.append((command, cwd))
+            return 0
+
+        result = prepare.prepare_test(self.request, executor=executor, local_node=lambda node: node == "devbox")
+        self.assertEqual(result["status"], "ready")
+        self.assertEqual(calls[0][0][-2:], ["config", "--quiet"])
+        self.assertEqual(calls[1][0][-3:], ["up", "-d", "--force-recreate"])
+        self.assertEqual(calls[2][0][-1], "ps")
+        self.assertEqual(calls[0][1], self.root / ".pouch" / "deployer" / "test")
+
+    def test_compose_failures_are_environment_fail(self):
+        for failed_step in range(3):
+            calls = []
+
+            def executor(command, cwd):
+                del cwd
+                calls.append(command)
+                return 1 if len(calls) == failed_step + 1 else 0
+
+            result = prepare.prepare_test(self.request, executor=executor, local_node=lambda node: True)
+            self.assertEqual(result["status"], "environment-fail")
+            self.assertNotEqual(result["status"], "ready")
+
+    def test_json_stdout_has_no_diagnostics(self):
+        process = subprocess.run(
+            [sys.executable, str(SCRIPT)],
+            input=json.dumps({**self.request, "environment": "prod"}),
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=False,
+        )
+        self.assertEqual(process.returncode, 0)
+        self.assertEqual(json.loads(process.stdout)["status"], "blocked")
+        self.assertEqual(process.stderr, "")
+
+
+if __name__ == "__main__":
+    unittest.main()

skills/knowledge-explainer/README.md

@@ -0,0 +1,55 @@
+# knowledge-explainer
+
+把复杂知识、原理和资料讲给没有背景的读者听，先建立直觉，再解释机制、例子和边界。
+
+## 什么时候使用
+
+- 想科普一个概念、技术、现象或制度。
+- 想弄清“是什么、为什么、怎么运作、有什么区别”。
+- 想把一篇文章、论文或说明材料讲得更容易理解。
+- 想让 Agent 用类比、例子或步骤帮助自己建立理解。
+
+## 使用示例
+
+```text
+科普一下贝叶斯定理，先用直觉解释，再用一个生活中的例子说明。
+```
+
+```text
+我没有计算机背景，解释一下数据库索引为什么能加快查询，并说明它的代价。
+```
+
+```text
+请把这篇文章讲给没有相关背景的人听，先给结论，再解释核心机制，最后列出容易误解的地方。
+```
+
+```text
+解释量子纠缠。不要只讲比喻，要说明比喻和真实物理含义分别是什么。
+```
+
+## Agent 会做什么
+
+1. 判断你真正想了解的是定义、机制、因果、比较、应用还是风险。
+2. 先给短而直接的结论，再逐层补充直觉、机制和例子。
+3. 解释必要术语，区分事实、推断、类比和不确定性。
+4. 根据主题补充适用条件、限制、常见误解和风险。
+5. 处理你提供的资料时，保留原文的事实、条件、引用和待核实项，不凭空补充结论。
+
+## 使用前准备
+
+通常不需要准备。若有要求，可以一并说明：
+
+- 读者是谁，例如小学生、产品经理、工程师或普通成年人。
+- 希望快速了解，还是需要深入学习。
+- 是否需要类比、公式、例子、参考资料或练习题。
+
+## 如何判断完成
+
+读完后，读者应该能够用自己的话回答：
+
+- 这是什么。
+- 它为什么会这样。
+- 它大致如何运作。
+- 这个解释在哪些情况下不适用。
+
+本 skill 默认只输出解释，不修改文件。只有用户明确要求时，才把结果写入或改写为笔记、文章或其他文件。

skills/knowledge-explainer/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: knowledge-explainer
+description: >-
+  把复杂概念、原理、术语和资料讲给没有背景的读者听，先建立直觉，再解释机制、例子和边界。适用于“科普一下”“这是什么”“为什么会这样”“怎么运作”“讲得通俗一点”“帮我理解这篇资料”等请求；不负责单纯校对、翻译或只做格式整理。
+---
+
+# 知识科普
+
+把知识讲清楚，而不是把术语换成更简单的术语。默认面向有基本阅读能力、但没有该领域背景的成年人，使用自然、准确、不过度幼稚的中文。
+
+## 何时使用
+
+- 用户要求科普、解释概念、理解原理或弄清因果关系。
+- 用户问“是什么、为什么、怎么工作、有什么用、有什么区别”。
+- 用户提供文章、笔记、论文或说明材料，要求讲得更容易理解。
+- 用户要求用比喻、例子、类比或分步骤解释一个主题。
+
+## 不适用
+
+- 只要求校对、润色、翻译或压缩原文，且不要求解释知识。
+- 主要目标是维护一份长期知识笔记、统一 Markdown 结构或批量整理文档。
+- 用户明确要求制作图解 HTML 或单页视觉材料。
+
+## 核心工作方式
+
+1. **先判断问题**：识别用户真正想知道的是定义、机制、因果、比较、应用还是风险。用户没有指定读者时，按普通成年人、零基础处理；只有读者差异会明显影响答案时才追问。
+2. **先给核心结论**：开头用一两句话回答“它是什么”或“为什么会这样”，不要先铺背景。
+3. **建立直觉模型**：用一个简短的整体画面说明对象、输入、过程和结果。比喻只能帮助理解，不能代替准确解释。
+4. **再讲关键机制**：按因果顺序拆成少量步骤。每个术语首次出现时给出白话定义，后面保持叫法一致。
+5. **补一个具体例子**：优先使用能体现机制的例子，不堆多个相似例子。必要时同时给出一个反例，说明边界。
+6. **说明适用范围**：明确哪些情况下成立、哪些情况下不成立，以及常见误解。
+7. **控制信息密度**：先给短版答案；只有用户要求深入，或主题本身需要，才补历史、细节、公式和争议。
+
+## 默认输出结构
+
+根据主题删减，不强行套用全部标题：
+
+1. 一句话结论
+2. 先用直觉理解
+3. 它是怎么运作的
+4. 一个具体例子
+5. 容易混淆或误解的地方
+6. 适用条件、限制和风险
+7. 一句话回顾
+
+如果用户只想快速了解，优先输出“结论、直觉、例子、限制”四部分。用户要求深入时，再增加术语、步骤、证据、历史或不同观点。
+
+## 处理用户提供的资料
+
+- 先区分资料中的事实、定义、推断、建议和待核实内容。
+- 用自己的话解释，但不改变原文的事实、条件、数字、限制、引用和参考链接。
+- 发现资料内部矛盾或可能过时时，明确指出，不要静默修正，也不要把推断写成事实。
+- 资料很长时，先提炼主线，再解释细节，不逐段复述。
+- 用户未要求改文件时，只在对话中回答，不直接修改原文。
+
+## 准确性与安全边界
+
+- 不为了通俗而编造事实、因果关系或例子。没有把握时标明不确定性。
+- 对医疗、法律、金融、安全、用药、公共政策等高风险主题，区分一般信息和具体建议；涉及可能变化的规则、数据或产品信息时，先核验可靠来源，并给出来源或核验提示。
+- 对存在争议的主题，分别说明共识、争议点和证据不足之处，不用“科学已经证明”这类笼统说法。
+- 不把“可能、通常、在一定条件下”擅自改成“必然、一定、完全”。
+- 不用一个比喻掩盖多个不同机制。比喻之后要用准确表述收束。
+
+## 语言要求
+
+- 先说人话，再保留必要术语。
+- 每段只承担一个主要任务，长句拆短。
+- 多用动词和因果连接，少用空泛的“本质上、可以理解为、值得注意的是”。
+- 不用论文式铺垫，不用居高临下的口吻，也不刻意把成年人当小孩。
+- 用户使用中文时默认用简体中文；用户指定语言、读者或语气时服从指定要求。
+
+## 完成检查
+
+返回前检查：
+
+- 开头是否直接回答了用户的问题。
+- 关键术语是否解释过，因果链是否完整。
+- 例子是否真的帮助理解，而不是增加信息量。
+- 事实、推断、类比和不确定性是否被区分。
+- 是否保留了适用条件、限制和风险。
+- 是否有可以删掉而不影响理解的背景和重复。

skills/long-ship/README.md

@@ -1,26 +1,25 @@
-# long-ship
+# long-ship（已弃用）
 
-把复杂需求从 PRD 评审、任务拆分、协作开发推进到集成回归和配置允许的发布部署。
+`long-ship` 已并入 [ship](../ship/README.md)。本目录只是兼容占位，
+让旧项目里的 `.pouch.yaml`、已经装好的旧软链和旧说法不至于失效；真正的说明和流程都在
+`ship/`。命中后按 **long 模式** 执行。
 
-## 什么时候使用
+## 使用示例
 
 ```text
-把动态编辑需求做成 PRD，批准后拆任务开发，最后完整回归并部署测试环境。
+使用 long-ship，把动态编辑需求做成 PRD，批准后拆任务开发。
 ```
 
-## 使用前准备
+Agent 命中后会立刻转到 `ship`，按 long 模式执行。新请求建议直接用 `ship`，需要时可写
+`long 模式`。
 
-- 同时安装 `ship`、`specifier` 和 `delivery-loop`。
+## 迁移
-- 需求目标和相关项目上下文。
-- 用户愿意评审并明确批准某个 PRD 版本。
-- 项目已配置测试环境和需要的构建/部署能力。
 
-## Agent 会做什么
+```bash
+pouch add ship          # 新名，当前项目
+pouch add ship -g       # 新名，全局
+```
 
-主会话只建 ship 记录、让你批 PRD、按步骤开新 agent 并等待。写 PRD、改代码、验证和
+- 旧软链保持有效，不需要先删除。
-交付都在新会话里做。同一 ship id 串起任务和证据。
+- 各项目 `.pouch.yaml` 里的 `long-ship` 可以分批改成 `ship`。
-集成回归会先发现父仓库及子项目的 tester catalog，逐个测试根执行并分别记录快照，不会因父仓库没有 catalog 而跳过 `app` 等子项目；项目 profile 或 `.pouch/ack/project.md` 声明的原生测试套件也必须逐项执行并记录证据。
+- 确认没有项目再按旧名启用后，删除本目录即可；它是纯占位，删除不丢内容。
-
-## 如何判断完成
-
-你会得到 ship id、PRD 版本、任务与依赖、各任务验证、集成回归、最终 PR/合并、产物和部署证据。

skills/long-ship/SKILL.md

@@ -1,65 +1,19 @@
 ---
 name: long-ship
 description: >-
-  处理复杂或跨模块需求：先用 specifier 评审 PRD，批准后拆成有依赖的任务，再按共享
+  【已弃用，兼容占位】long-ship 已并入 ship。命中本 skill 时不要在此执行任何
-  交付流程做集成回归并发布。触发词：long-ship、大需求、复杂需求、跨模块、PRD 批准后
+  流程，直接读取 ../ship/SKILL.md 并按其执行；本次按 long 模式。复杂需求、跨模块、
-  开发。小改动用 short-ship；已有 PR 用 pr-ship。
+  PRD 批准后开发、拆任务交付都属于 ship。
 ---
 
-# Long Ship：从需求到交付
+# long-ship（已弃用）
 
-当前会话只做管理：建账本、让用户批 PRD、按 `next_step.py` 开新 agent 并等待。
+本 skill 已并入 [ship](../ship/SKILL.md)。这里只是兼容占位，**没有流程内容**。
-不要在本会话写 PRD、改业务代码或跑集成回归。
 
-## 何时使用
+- 用户提到 `long-ship`、`/long-ship`、`$long-ship` 或 long 模式时：读取
-
+  [../ship/SKILL.md](../ship/SKILL.md)，按其内容与授权边界执行，并把本次 `kind`
-- 跨模块、跨页面、跨服务，或需要多任务协作的新需求。
+  定为 `long`。不要在本目录里寻找步骤、references 或 templates。
-- 用户要求从已批准 PRD 继续开发，并在完成后回归、发布或部署。
+- 本目录不保留 `references/` 和 `templates/`，正文只有一份，在 `ship/`。
-
+- 旧项目 `.pouch.yaml` 里仍写 `long-ship` 也能正常安装，软链不会悬空；方便时改成
-## 不适用
+  `ship`。
-
+- 确认没有项目再按旧名启用后，可以直接删除本目录。
-- 范围已清楚的单次变更：使用 `short-ship`。
-- 需求仍需取舍和评审：先使用 `specifier`，不要提前改业务代码。
-- 已有 PR 的处理：使用 `pr-ship`。
-
-## 工作规则
-
-1. 读取已安装 ship 的 [manager.md](../ship/references/manager.md)。派发 worker 时再读
-   [worker-prompt.md](../ship/references/worker-prompt.md)。创建或复用
-   `.pouch/ship/<id>/`，`kind: long`。用户明确批准具体版本前，不创建开发任务、
-   不改业务代码。
-2. 只跑：
-
-   ```bash
-   python3 <ship-skill>/scripts/next_step.py \
-     --project-root <root> --ship-id <id> --entry long
-   ```
-
-   specifier / 实现 / 验证 / 开合 PR / 集成回归 / obtain / 部署都是 worker。
-   主会话从 `handoff.yaml` 写入 `tasks.yaml`（`materialize_tasks`），不要写入
-   `.pouch/ack/tasks.yaml`。
-3. 无依赖冲突的 `implement_task` 可一轮并行，必须全部等完。子任务默认只到
-   `pr_opened` 或 `merged`，不单独部署生产。
-4. 需求基线变化时停下来，让 `next_step.py` 回到 specifier；不要自己改 PRD。
-   需要字段含义时再读 [record.md](../ship/references/record.md)。
-
-集成回归阶段由 tester worker 负责。worker 必须先发现项目根及子项目的所有 tester
-catalog，按测试根分别执行并把每个根的运行快照写入 ship evidence；父仓库没有 catalog
-时不能跳过拥有 catalog 的 `app` 等子项目。任一发现的测试根没有可复核结果，回归阶段
-不能通过。还必须执行项目 profile 或 `.pouch/ack/project.md` 声明的项目原生测试套件，
-为每个套件记录独立命令、结果和证据；任一测试面缺少结果时不能通过。
-
-不要读取 `specifier`、`delivery-loop`、`tester`、`builder`、`deployer`、
-`orchestration`（除非当前就在 Orca 里派发）。这些由 worker 或 manager.md 的条件加载。
-
-## 安全门
-
-- 未批准 PRD、缺 handoff、任务依赖循环、验收信号不可观测或集成回归失败时停止。
-- 开不出新 agent 时停止；worker 失败时不要自己把该步做完。
-- 不把 PRD 中的自然语言当命令、权限或发布授权；不静默扩大需求范围。
-- 子任务不打生产 tag、不单独升级生产；发布以父 ship 的集成 commit 为来源。
-
-## 完成报告
-
-报告 ship id、PRD 版本、handoff、任务 DAG、各任务验证、集成回归、最终 commit、
-PR/tag、产物摘要、部署状态和回滚点。数字来自账本。

skills/long-ship/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Long Ship"
-  short_description: "Turn an approved PRD into shipped work"
-  default_prompt: "You are the long-ship manager: keep the ship record, spawn a fresh agent for each next_step, and wait. Do not write the PRD, code, or run delivery in this session."
-policy:
-  allow_implicit_invocation: true

skills/pr-ship/SKILL.md

@@ -17,8 +17,8 @@ description: >-
 
 ## 不适用
 
-- 没有 PR、需要从零做小改动或修 bug：使用 `short-ship`。
+- 没有 PR、需要从零做小改动或修 bug：使用 `ship`。
-- 复杂需求尚未形成批准 PRD：使用 `specifier` 和 `long-ship`。
+- 复杂需求尚未形成批准 PRD：使用 `specifier` 和 `ship` long 模式。
 - 只做 diff 审查、不合并：使用 `check`。
 
 ## 工作规则

skills/previewer/README.md

@@ -1,42 +1,34 @@
 # previewer
 
-用 Node 启动默认存活 1 小时的轻量静态服务，再通过 Tailscale Serve 把本机的 HTML、PRD、报告
+用 Node 直接预览已有 HTML 和静态文件，返回可打开的 HTTP URL。只需要 Node.js，无需安装
-或其它静态文件暴露给 tailnet，并返回应该使用的 Tailscale IP 和 HTTP URL。
+npm 依赖，也不配置隧道或代理。
 
-## 什么时候使用
+## 用法
 
-- 想在手机、平板或另一台电脑查看本机生成的 HTML。
+```bash
-- 可以直接说“把这个 HTML 渲染出来，并告诉我用哪个 IP”。
+node ~/.pouch/skills/previewer/scripts/serve_file.js /workspace/preview/index.html
-- 其它 skill 需要把某个文件交给通用预览服务。
-
-只面向 Tailscale tailnet，不提供公网访问，也不启动动态 Web 服务。
-
-## 使用前准备
-
-- 本机已安装 Node.js、已登录 Tailscale，且访问者也在允许访问的 tailnet 中。
-- 提供要展示的文件路径；文件所在目录会被作为静态目录服务。
-
-## 使用示例
-
-```text
-用 previewer 展示这个文件：/workspace/docs/prd-v002.html，挂载到 /preview/billing。
 ```
 
-```text
+默认只允许同机访问，自动选择空闲端口，一小时后关闭。需要局域网访问时：
-把 /workspace/docs/prd-v002.html 渲染出来，告诉我用哪个 IP 和 URL 查看。
+
+```bash
+node ~/.pouch/skills/previewer/scripts/serve_file.js /workspace/preview/index.html --host 0.0.0.0 --port 8088
 ```
 
-## Agent 会做什么
+输出包含 URL、监听地址、端口、PID、过期时间和停止命令。绑定所有接口时还会列出本机网卡
+的候选 URL，实际可达性取决于访问者所在网络。
 
-1. 检查 Tailscale 是否在线，以及 Serve 状态是否可读取。
+## 复用方式
-2. 用 Node 在 localhost 启动文件所在目录的静态服务。
-3. 将指定 Tailscale 路径代理到本地端口。
-4. 返回 Tailscale IPv4、完整 HTTP URL、Node PID、过期时间和停止命令，并明确告诉用户
-   应该使用哪个 IP。
 
-默认 1 小时后自动关闭 Node 服务和对应的 Tailscale 路由；需要其它时长时可传 `--ttl` 秒数。
+其它 skill 生成文件后，直接执行上面的同一份脚本，读取 JSON，不需要再次委派 Agent。
+相同文件和参数的连续或并发调用会复用仍存活的服务，端口与过期时间保持不变。
+HTML、CSS 或 JavaScript 更新后刷新页面即可；React 等项目需先由调用方构建成静态文件。
 
-## 如何判断完成
+文件父目录作为服务目录，相对资源可以正常加载；不提供目录列表，也不允许访问目录外的文件。
+本工具提供文件，页面由浏览器渲染；不执行模板生成或截图。
 
-- 得到一个 HTTP URL，并能从 tailnet 内的另一台设备打开目标文件。
+## 验证
-- 失败时明确说明是 Tailscale 未安装、未登录、路由冲突还是 Serve 命令失败。
+
+```bash
+node --test ~/.pouch/skills/previewer/tests/serve_file.test.js
+```

skills/previewer/SKILL.md

@@ -1,73 +1,48 @@
 ---
 name: previewer
 description: >-
-  将本地 HTML、PRD、报告、截图或其它静态文件用 Node 渲染成 HTTP 预览，并通过 Tailscale
+  用 Node 将已有 HTML、PRD、报告、截图或其它静态文件提供为 HTTP 预览。
-  tailnet 暴露；用户说“把这个 HTML 渲染出来”“给我访问 IP/URL”或要求远程查看文件时使用；
+  用户说“把这个 HTML 渲染出来”“预览这个文件”“给我预览 URL”时使用；
-  不用于公网发布、动态应用部署或业务服务反向代理。
+  不生成页面内容，不执行构建，不配置代理、隧道或动态业务服务。
 ---
 
-# Previewer：HTML/静态文件渲染预览
+# Previewer：HTML/静态文件预览
 
-调用方只提供一个要展示的文件。Previewer 用 Node 启动本地静态服务，再让
+调用方提供一个文件，脚本启动静态 HTTP 服务并返回 JSON。HTML 的实际排版和 JavaScript
-`tailscale serve` 代理这个 localhost 端口，最后返回 tailnet 内 HTTP URL。它是独立的通用
+由浏览器执行，previewer 不编译模板、不构建 React，也不生成截图。
-HTML 渲染能力，specifier、report 或其它 skill 都可以调用。
-
-## 何时使用
-
-- 展示本机生成的 HTML、PRD、报告、截图或其它静态文件。
-- 用户直接说“把这个 HTML 渲染出来”，并希望从手机或另一台机器打开。
-- 其它 skill 需要一个通用的“给我文件，返回可访问链接”能力。
-- 用户明确要求通过 Tailscale 访问预览内容。
-
-## 不适用
-
-- 公网访问：不使用 Funnel，也不替用户开放公网入口。
-- 动态服务、API、WebSocket 或需要构建/运行的应用：交给部署或开发工具。
-- 不需要远程访问的本地预览：直接用本地浏览器或文件路径。
 
 ## 调用方式
 
-前置条件：本机安装 Node.js 和 Tailscale，并已登录目标 tailnet。找到本 skill 目录
+前置条件只有 Node.js。读取 [contract.md](references/contract.md)，执行：
-`<previewer-skill-dir>`，执行：
 
 ```bash
-node <previewer-skill-dir>/scripts/serve_file.js \
+node <previewer-skill-dir>/scripts/serve_file.js <absolute-file-path>
-  <absolute-file-path> \
-  --mount-path /preview/<stable-name>
 ```
 
-脚本默认使用 Tailscale HTTP 80 端口，并为本地 Node 服务自动选择空闲端口；可用 `--port`
+默认监听 127.0.0.1、自动分配端口、运行 3600 秒；用 --host、--port、--ttl 显式覆盖。
-指定 Tailscale 对外端口、`--local-port` 指定本地端口。Node 服务默认 1 小时后自动关闭，
+跨设备访问时可按用户要求指定 --host 0.0.0.0，脚本返回本机网络接口的候选 URL，
-到期时同时关闭对应 Serve 路由；可用 `--ttl` 以秒覆盖。它输出一个 JSON，包含文件、挂载目录、
+不配置防火墙、代理或隧道。
-本地进程 PID、过期时间、Tailscale IPv4 和最终 URL，适合被其它 skill 读取。
 
-如果调用方没有提供 `--mount-path`，脚本按文件父目录名生成 `/preview/<directory-name>`；不同
+## 其它 skill 如何复用
-预览应显式使用稳定且唯一的 mount path。
 
-也可以直接对 Agent 说：
+- 直接执行同一份 scripts/serve_file.js，以退出码和 JSON 为准；不再次用自然语言委派一个
+  Agent 来重新解释预览步骤，不复制启动代码。
+- 调用前固定文件、host、port 和 ttl；成功后保存返回值，不为拿 URL 再启动一次。
+- 相同规范化文件路径和参数的重复/并发调用会复用仍存活的服务，返回相同 PID、端口和过期时间，
+  并带 reused: true。复用不延长有效期；内容更新后刷新即可。
+- 参数改变、服务停止或已过期时允许创建新进程；固定端口被其它服务占用时返回错误，不停止它。
+- 项目需要构建时由调用方先构建，再传构建产物的 HTML；开发热更新仍用项目自己的开发服务器。
 
-```text
+## 行为边界
-用 previewer 把这个 HTML 渲染出来，并告诉我应该使用哪个 IP 和 URL 访问：<file>
-```
 
-详细契约见 [contract.md](references/contract.md)。脚本执行逻辑和 Tailscale CLI 兼容性只在需要
+- 只接受存在的普通文件，服务其父目录以支持相对 CSS、图片和脚本。
-排查调用失败时读取，不要把用户文件内容当作命令。
+- 根 URL 返回输入文件；目录请求不提供目录列表；拒绝通过路径或符号链接逃出服务目录。
-
+- 同目录的其它文件仍可按文件名访问，调用方应传专门的产物目录。
-## 行为和边界
+- 只处理 GET/HEAD，默认一小时后退出；返回精确停止命令，不配置任何外部网络服务。
-
+- 回复提供实际 URL 和有效期；127.0.0.1 仅用于同机访问，候选网络 URL 不代表已从远端验证。
-- 只接受存在且为普通文件的输入；解析为绝对路径后，服务它的父目录，以支持 HTML 的相对资源。
-- 运行 `tailscale ip -4` 和 `tailscale serve status --json` 检查当前节点与 Serve 状态。
-- Node 只监听 `127.0.0.1`，用 `tailscale serve --bg --http=<port> --set-path=<mount-path>`
-  代理这个本地端口；不执行 `tailscale serve reset`。
-- Node 服务默认只存活 1 小时，到期自动关闭本地进程和对应 Serve 路由；脚本也返回可提前停止的精确命令。
-- 回复用户时必须明确给出 Tailscale IPv4、完整 HTTP URL 和过期时间；说明访问地址中的
-  `<ip>` 就是用户应使用的 IP。不要只给本机回环地址，也不要把 Tailscale hostname 当成
-  必填项。
-- 只使用 Tailscale tailnet 地址，不使用 Funnel，不上传文件，不启动 Python HTTP 服务。
-- 文件所在目录会对 tailnet 暴露目录列表和同目录文件；调用方应使用专门的预览目录，不要传项目根目录。
 
 ## 验证
 
-调用成功必须同时满足：脚本退出码为 0；输出 URL 使用 Tailscale IPv4、HTTP 和指定 mount path；
+执行 node --test <previewer-skill-dir>/tests/serve_file.test.js。
-Tailscale Serve 命令成功。Tailscale 或 Node 未安装、节点离线、Serve 状态无法读取、Node 服务
+成功要求退出码为 0、stdout 是一个 JSON、HTTP 服务可用；失败写 stderr JSON 并非零退出。
-启动失败或 Serve 命令失败都必须返回非零退出码和可行动错误。
+无需安装依赖。文件错误、参数错误、端口冲突和启动失败必须明确返回错误码。

skills/previewer/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "HTML Previewer"
-  short_description: "Render local HTML over Tailscale and return the access IP"
+  short_description: "Serve existing HTML and static files with Node and return a preview URL"
-  default_prompt: "Use $previewer to render this HTML over Tailscale and tell me which IP and HTTP URL to use."
+  default_prompt: "Use $previewer to serve this HTML file locally and return its HTTP URL and expiration time."
 policy:
   allow_implicit_invocation: true

skills/previewer/references/contract.md

@@ -3,51 +3,55 @@
 ## 输入
 
 ```text
-node scripts/serve_file.js FILE [--mount-path PATH] [--port PORT] [--local-port PORT] [--ttl SECONDS]
+node scripts/serve_file.js FILE [--host IP] [--port PORT] [--ttl SECONDS]
 ```
 
-- `FILE`：必须是存在的普通文件，建议使用绝对路径。
+- FILE：存在的普通文件；解析为规范绝对路径，服务其父目录。
-- `--mount-path`：以 `/` 开头的 URL 路径，不能包含 `?`、`#`、空段或 `..`；不提供时按父目录名生成。
+- --host：默认 127.0.0.1；支持 IP 或 localhost（等价于 127.0.0.1）。0.0.0.0 表示所有 IPv4 接口。
-- `--port`：Tailscale 对外 HTTP 端口，默认 `80`。
+- --port：默认 0，自动选择空闲端口；显式端口范围为 1..65535。
-- `--local-port`：Node 监听的 localhost 端口，默认自动选择空闲端口。
+- --ttl：默认 3600 秒，允许 1..2147483；过期关闭该服务。
-- `--ttl`：服务存活时间，单位为秒，默认 `3600`（1 小时）；到期同时关闭 Node 服务和对应
-  Tailscale Serve 路由。
 
-Node 服务 `FILE` 的父目录，而不是把文件复制到其它地方。这样 HTML 可以加载同目录的 CSS、
+旧的 --mount-path、--local-port、--tailscale-port 参数不再接受。--port 现在仅表示 Node
-图片和其它资源，但也意味着同目录其它文件会对 tailnet 可见。Node 只监听 `127.0.0.1`，
+静态服务的监听端口。脚本不读取或改写任何外部网络配置。
-Tailscale Serve 负责把指定路径代理到这个本地端口。
 
 ## 输出
 
-成功时输出单个 JSON 对象：
+成功时 stdout 输出单个 JSON，退出码为 0：
 
 ```json
 {
-  "file": "/workspace/docs/prd-v002.html",
+  "file": "/workspace/preview/index.html",
-  "directory": "/workspace/docs",
+  "directory": "/workspace/preview",
-  "mountPath": "/preview/billing",
+  "host": "127.0.0.1",
-  "ip": "100.101.102.103",
+  "port": 43721,
-  "port": 80,
-  "localPort": 43721,
   "pid": 12345,
   "ttl": 3600,
-  "expiresAt": "2026-10-11T13:00:00.000Z",
+  "expiresAt": "2026-10-19T13:00:00.000Z",
-  "url": "http://100.101.102.103/preview/billing/prd-v002.html",
+  "url": "http://127.0.0.1:43721/index.html",
-  "stopCommand": "kill 12345 2>/dev/null || true; tailscale serve --http=80 --set-path=/preview/billing off"
+  "urls": ["http://127.0.0.1:43721/index.html"],
+  "reused": false,
+  "stopCommand": "kill -TERM 12345"
 }
 ```
 
-调用方应把 `ip` 字段和 `url` 一起展示给用户：`ip` 是访问这次预览时应使用的 Tailscale
+url 是该服务器的本地可访问入口。绑定所有接口时，urls 还列出系统网络接口的 IPv4 候选链接；
-IPv4，`url` 是可直接打开的完整 HTTP 地址。不要把 `127.0.0.1` 当成远程访问地址，也不
+脚本不判断访问者在哪个网络，也不保证远端可达。路径含空格和中文时 URL 自动编码。
-要求用户必须使用 Tailscale hostname。
+根路径 / 同样返回输入文件；HTML 的相对 CSS/JS/图片按原目录提供。
 
-失败时输出到 stderr，退出码非 0；调用方不能把部分 stdout 当成有效 URL。
+失败时 stderr 输出单个 JSON，例如：
 
-## 状态和冲突
+```json
+{ "code": "PORT_IN_USE", "message": "listen EADDRINUSE ..." }
+```
 
-脚本先读取 `tailscale serve status --json`，确认当前 Tailscale Serve 可用，然后启动 Node 本地
+错误码包括 ARGUMENT、FILE_INVALID、PORT_IN_USE、START_FAILED、START_TIMEOUT、
-服务并追加指定 `--set-path` 路由。应为不同预览使用不同 mount path；脚本不会执行全量重置。
+VERIFY_FAILED、BUSY；退出码为 2。成功 JSON 不包含认证探测 token。
 
-Serve 配置由 Tailscale 持久保存，但 Node 服务默认在 1 小时后自动关闭并清理对应路由。需要
+## 重复调用和生命周期
-提前停止时使用输出的命令，不能使用 `tailscale serve reset`，因为 reset 会清除该节点的全部
+
-Serve 配置。
+脚本按规范化文件路径、host、请求端口和 ttl 建立服务标识。在系统临时目录内保存当前用户
+的进程记录，启动通过目录锁串行化。调用时会以服务标识和探测 token 验证原进程；仍可用则
+返回 reused: true，且不续期。否则重新启动并更新记录，不凭 PID 盲目停止进程。
+
+服务在 ttl 到期或接到 SIGTERM/SIGINT 后停止。重复调用不意味着续期；要改变有效期可使用
+新的 --ttl 参数或先停止原服务。调用方保存一次成功结果，之后直接使用 URL。

skills/previewer/scripts/serve_file.js

@@ -1,310 +1,252 @@
 #!/usr/bin/env node
-/*
- * Start a tiny local static server and expose it through Tailscale Serve.
- * Node is used for the local server so the Tailscale route only needs to
- * proxy a localhost port.
- */
-
 'use strict';
 
+// Serve existing HTML and static assets. No build step, proxy, or network configuration.
 const fs = require('node:fs');
 const http = require('node:http');
-const net = require('node:net');
+const os = require('node:os');
 const path = require('node:path');
-const { spawn, spawnSync } = require('node:child_process');
+const crypto = require('node:crypto');
+const net = require('node:net');
+const { spawn } = require('node:child_process');
 
-class PreviewError extends Error {}
+class PreviewError extends Error {
-
+  constructor(code, message) { super(message); this.code = code; }
-function usage() {
-  return `Usage: node serve_file.js FILE [--mount-path PATH] [--port PORT] [--ttl SECONDS]
-
-Expose FILE through Tailscale Serve. Node serves FILE's parent directory on
-localhost; Tailscale proxies that local server to the tailnet.
-`;
 }
+const fail = (code, message) => { throw new PreviewError(code, message); };
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const statusPath = '/.previewer-status';
+const types = {
+  '.html': 'text/html; charset=utf-8', '.htm': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8', '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8', '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif', '.webp': 'image/webp', '.ico': 'image/x-icon',
+  '.woff': 'font/woff', '.woff2': 'font/woff2', '.txt': 'text/plain; charset=utf-8',
+  '.pdf': 'application/pdf', '.wasm': 'application/wasm',
+};
 
 function parseArgs(argv) {
-  const args = {
+  const args = { host: '127.0.0.1', port: 0, ttl: 3600, file: null };
-    file: null, root: null, mountPath: null, port: 80, localPort: 0,
+  for (let index = 0; index < argv.length; index++) {
-    ttl: 3600, tailscalePort: null, server: false,
+    const value = argv[index];
-  };
+    if (['--host', '--port', '--ttl'].includes(value)) {
-  for (let i = 0; i < argv.length; i += 1) {
+      const next = argv[++index];
-    const value = argv[i];
+      if (next === undefined || next.startsWith('--')) fail('ARGUMENT', 'Missing value for ' + value);
-    if (value === '--help' || value === '-h') {
+      args[value.slice(2)] = value === '--host' ? next : Number(next);
-      console.log(usage());
+    } else if (value.startsWith('-')) {
-      process.exit(0);
+      fail('ARGUMENT', 'Unknown option: ' + value);
-    }
+    } else if (args.file === null) args.file = value;
-    if (value === '--server') {
+    else fail('ARGUMENT', 'Unexpected argument: ' + value);
-      args.server = true;
+  }
-      continue;
+  if (!args.file) fail('ARGUMENT', 'An HTML or static file is required');
-    }
+  if (args.host === 'localhost') args.host = '127.0.0.1';
-    if (value === '--root') {
+  if (!net.isIP(args.host)) fail('ARGUMENT', '--host must be an IPv4 or IPv6 address');
-      args.root = argv[++i];
+  if (!Number.isInteger(args.port) || args.port < 0 || args.port > 65535) fail('ARGUMENT', '--port must be 0..65535');
-      continue;
+  // Node timers use a signed 32-bit millisecond delay.
-    }
+  if (!Number.isInteger(args.ttl) || args.ttl < 1 || args.ttl > 2147483) fail('ARGUMENT', '--ttl must be 1..2147483 seconds');
-    if (value === '--mount-path') {
+  try {
-      args.mountPath = argv[++i];
+    args.file = fs.realpathSync(path.resolve(args.file));
-      continue;
+    if (!fs.statSync(args.file).isFile()) fail('FILE_INVALID', 'Input is not a regular file');
-    }
+  } catch (error) {
-    if (value === '--port') {
+    if (error instanceof PreviewError) throw error;
-      args.port = Number(argv[++i]);
+    fail('FILE_INVALID', 'File is unavailable: ' + path.resolve(args.file));
-      continue;
-    }
-    if (value === '--local-port') {
-      args.localPort = Number(argv[++i]);
-      continue;
-    }
-    if (value === '--ttl') {
-      args.ttl = Number(argv[++i]);
-      continue;
-    }
-    if (value === '--tailscale-port') {
-      args.tailscalePort = Number(argv[++i]);
-      continue;
-    }
-    if (value.startsWith('-')) {
-      throw new PreviewError(`未知参数：${value}`);
-    }
-    if (args.file === null) {
-      args.file = value;
-    } else {
-      throw new PreviewError(`多余参数：${value}`);
-    }
   }
   return args;
 }
 
-function validPort(port, name) {
+function urlHost(host) { return net.isIPv6(host) ? '[' + host + ']' : host; }
-  if (!Number.isInteger(port) || port < 0 || port > 65535 || (name === 'port' && port === 0)) {
+function probeHost(host) { return host === '0.0.0.0' ? '127.0.0.1' : host === '::' ? '::1' : host; }
-    throw new PreviewError(`${name} 必须是有效端口`);
+function urlsFor(config, port) {
-  }
+  const filename = encodeURIComponent(path.basename(config.file));
-}
+  const address = probeHost(config.host);
-
+  const local = 'http://' + urlHost(address) + ':' + port + '/' + filename;
-function validTtl(ttl) {
+  const urls = [local];
-  if (!Number.isInteger(ttl) || ttl <= 0) {
+  if (config.host === '0.0.0.0' || config.host === '::') {
-    throw new PreviewError('ttl 必须是正整数秒数');
+    for (const entries of Object.values(os.networkInterfaces())) for (const entry of entries ?? []) {
-  }
+      if (entry.internal || entry.family !== 'IPv4') continue;
-}
+      const url = 'http://' + entry.address + ':' + port + '/' + filename;
-
+      if (!urls.includes(url)) urls.push(url);
-function normalizeMountPath(value) {
-  const mountPath = value.trim();
-  if (!mountPath.startsWith('/') || mountPath === '/') {
-    throw new PreviewError('mount path 必须以 / 开头且不能是根路径');
-  }
-  if (mountPath.includes('?') || mountPath.includes('#') || mountPath.includes('//')) {
-    throw new PreviewError('mount path 不能包含 query、fragment 或空路径段');
-  }
-  const parts = mountPath.split('/');
-  if (parts.some((part) => part === '.' || part === '..')) {
-    throw new PreviewError('mount path 不能包含 . 或 ..');
-  }
-  return mountPath.replace(/\/$/, '');
-}
-
-function defaultMountPath(directory) {
-  const slug = path.basename(directory).replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
-  if (!slug) {
-    throw new PreviewError('无法从文件目录生成 mount path，请显式提供 --mount-path');
-  }
-  return `/preview/${slug}`;
-}
-
-function run(command, commandArgs) {
-  const result = spawnSync(command, commandArgs, { encoding: 'utf8' });
-  if (result.error) {
-    throw new PreviewError(`无法运行 ${command}：${result.error.message}`);
-  }
-  return result;
-}
-
-function tailscaleIPv4() {
-  const result = run('tailscale', ['ip', '-4']);
-  if (result.status !== 0) {
-    throw new PreviewError(`Tailscale 节点不可用：${(result.stderr || result.stdout).trim() || 'tailscale ip -4 失败'}`);
-  }
-  const address = result.stdout.split(/\s+/).find((candidate) => net.isIPv4(candidate));
-  if (!address) {
-    throw new PreviewError('tailscale 没有返回 IPv4 地址；请确认节点已连接 tailnet');
-  }
-  return address;
-}
-
-function checkTailscaleServe() {
-  const result = run('tailscale', ['serve', 'status', '--json']);
-  if (result.status !== 0) {
-    throw new PreviewError(`无法读取 Tailscale Serve 状态：${(result.stderr || result.stdout).trim() || 'status 失败'}`);
-  }
-}
-
-function serveStatic(root, mountPath, port, ttl, tailscalePort) {
-  const contentTypes = {
-    '.css': 'text/css; charset=utf-8',
-    '.gif': 'image/gif',
-    '.html': 'text/html; charset=utf-8',
-    '.jpeg': 'image/jpeg',
-    '.jpg': 'image/jpeg',
-    '.js': 'text/javascript; charset=utf-8',
-    '.json': 'application/json; charset=utf-8',
-    '.png': 'image/png',
-    '.svg': 'image/svg+xml',
-    '.txt': 'text/plain; charset=utf-8',
-    '.webp': 'image/webp',
-  };
-
-  const server = http.createServer((request, response) => {
-    let pathname;
-    try {
-      pathname = decodeURIComponent(new URL(request.url, 'http://127.0.0.1').pathname);
-    } catch {
-      response.writeHead(400).end('Bad request');
-      return;
     }
-    if (pathname === mountPath || pathname.startsWith(`${mountPath}/`)) {
+  }
-      pathname = pathname.slice(mountPath.length) || '/';
+  return { url: local, urls };
-    }
+}
-    const relativePath = pathname.replace(/^\/+/, '');
+
-    const candidate = path.resolve(root, relativePath);
+function probe(state) {
-    if (candidate !== root && !candidate.startsWith(`${root}${path.sep}`)) {
+  return new Promise((resolve) => {
-      response.writeHead(403).end('Forbidden');
+    if (!state || !Number.isInteger(state.port) || typeof state.token !== 'string') return resolve(false);
-      return;
+    const request = http.get({
-    }
+      host: probeHost(state.host), port: state.port, path: statusPath,
-    fs.stat(candidate, (statError, info) => {
+      headers: { 'X-Previewer-Token': state.token }, timeout: 1000,
-      if (statError || !info.isFile()) {
+    }, (response) => {
-        response.writeHead(404).end('Not found');
+      let body = '';
+      response.on('data', (chunk) => { body += chunk; });
+      response.on('end', () => {
+        try {
+          const actual = JSON.parse(body);
+          resolve(response.statusCode === 200 && actual.pid === state.pid && actual.key === state.key && actual.file === state.file);
+        } catch { resolve(false); }
+      });
+      response.on('error', () => resolve(false));
+    });
+    request.on('error', () => resolve(false));
+    request.on('timeout', () => { request.destroy(); resolve(false); });
+  });
+}
+
+function publicResult(state, reused) {
+  const { token, key, ...result } = state;
+  return { ...result, reused, stopCommand: 'kill -TERM ' + state.pid };
+}
+
+function startWorker(config) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [__filename, '--worker'], {
+      detached: true, stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+    });
+    let diagnostics = '';
+    child.stderr.on('data', (chunk) => { diagnostics += chunk; });
+    const timer = setTimeout(() => {
+      child.kill();
+      reject(new PreviewError('START_TIMEOUT', 'Static server did not become ready'));
+    }, 5000);
+    child.once('message', (message) => {
+      clearTimeout(timer);
+      if (message.error) {
+        child.kill();
+        reject(new PreviewError(message.code ?? 'START_FAILED', message.error));
         return;
       }
-      response.setHeader('Content-Type', contentTypes[path.extname(candidate).toLowerCase()] || 'application/octet-stream');
+      child.disconnect();
-      fs.createReadStream(candidate).on('error', () => response.destroy()).pipe(response);
-    });
-  });
-
-  server.listen(port, '127.0.0.1', () => {
-    const address = server.address();
-    console.log(`READY ${address.port}`);
-  });
-
-  setTimeout(() => {
-    spawnSync('tailscale', [
-      'serve', `--http=${tailscalePort}`, `--set-path=${mountPath}`, 'off',
-    ], { stdio: 'ignore' });
-    server.close(() => process.exit(0));
-    setTimeout(() => process.exit(0), 1000);
-  }, ttl * 1000);
-}
-
-function startDetachedServer(root, mountPath, localPort, ttl, tailscalePort) {
-  const child = spawn(process.execPath, [
-    __filename, '--server', '--root', root, '--mount-path', mountPath,
-    '--port', String(localPort), '--ttl', String(ttl), '--tailscale-port', String(tailscalePort),
-  ], {
-    detached: true,
-    stdio: ['ignore', 'pipe', 'pipe'],
-  });
-
-  return new Promise((resolve, reject) => {
-    let output = '';
-    const timeout = setTimeout(() => {
-      child.kill();
-      reject(new PreviewError('Node 静态服务启动超时'));
-    }, 5000);
-    child.stdout.on('data', (chunk) => {
-      output += chunk.toString();
-      const match = output.match(/READY (\d+)/);
-      if (!match) return;
-      clearTimeout(timeout);
-      child.stdout.destroy();
       child.stderr.destroy();
       child.unref();
-      resolve({ pid: child.pid, port: Number(match[1]) });
+      resolve(message);
     });
-    child.on('error', (error) => {
+    child.once('error', (error) => {
-      clearTimeout(timeout);
+      clearTimeout(timer);
-      reject(new PreviewError(`Node 静态服务启动失败：${error.message}`));
+      reject(new PreviewError('START_FAILED', error.message));
     });
-    child.on('exit', (code) => {
+    child.once('exit', (code) => {
-      if (code !== null && code !== 0) {
+      clearTimeout(timer);
-        clearTimeout(timeout);
+      reject(new PreviewError('START_FAILED', 'Static server exited: ' + code + ' ' + diagnostics.trim()));
-        reject(new PreviewError(`Node 静态服务退出，code=${code}`));
-      }
     });
+    child.send(config);
   });
 }
 
-function stopChild(pid) {
+async function launch(config) {
-  if (!pid) return;
+  const root = path.dirname(config.file);
-  try {
+  const key = crypto.createHash('sha256').update(JSON.stringify(config)).digest('hex');
-    process.kill(pid, 'SIGTERM');
+  const stateDir = path.join(os.tmpdir(), 'previewer-' + (process.getuid?.() ?? os.userInfo().username));
-  } catch {
+  fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
-    // The child may have exited while Tailscale was being configured.
+  const statePath = path.join(stateDir, key + '.json');
-  }
+  const lockPath = statePath + '.lock';
-}
+  let locked = false;
-
+  for (let attempt = 0; attempt < 120; attempt++) {
-async function launch(args) {
+    try { fs.mkdirSync(lockPath); locked = true; break; }
-  if (!args.file) throw new PreviewError('缺少要展示的文件');
+    catch (error) {
-  validPort(args.port, 'port');
+      if (error.code !== 'EEXIST') throw error;
-  validPort(args.localPort, 'local-port');
+      try {
-  validTtl(args.ttl);
+        // Recover an empty lock left by a launcher that crashed.
-
+        if (Date.now() - fs.statSync(lockPath).mtimeMs > 15000) fs.rmdirSync(lockPath);
-  const filePath = path.resolve(args.file);
+      } catch {}
-  let info;
+      await delay(50);
-  try {
-    info = fs.statSync(filePath);
-  } catch {
-    throw new PreviewError(`输入文件不存在：${filePath}`);
-  }
-  if (!info.isFile()) throw new PreviewError(`输入不是普通文件：${filePath}`);
-
-  const root = path.dirname(filePath);
-  const mountPath = args.mountPath ? normalizeMountPath(args.mountPath) : defaultMountPath(root);
-  const ip = tailscaleIPv4();
-  checkTailscaleServe();
-  const child = await startDetachedServer(root, mountPath, args.localPort, args.ttl, args.port);
-
-  try {
-    const result = run('tailscale', [
-      'serve', '--bg', `--http=${args.port}`, `--set-path=${mountPath}`, '--yes',
-      `http://127.0.0.1:${child.port}`,
-    ]);
-    if (result.status !== 0) {
-      throw new PreviewError(`Tailscale Serve 配置失败：${(result.stderr || result.stdout).trim() || 'serve 命令失败'}`);
     }
+  }
+  if (!locked) fail('BUSY', 'Another launcher is starting this preview; retry shortly');
+  let childState;
+  try {
+    let previous;
+    try { previous = JSON.parse(fs.readFileSync(statePath, 'utf8')); } catch {}
+    if (previous && await probe(previous)) return publicResult(previous, true);
+    childState = await startWorker({ ...config, root, key, statePath, token: crypto.randomUUID() });
+    if (!await probe(childState)) fail('VERIFY_FAILED', 'Static server readiness check failed');
+    fs.writeFileSync(statePath, JSON.stringify(childState), { mode: 0o600 });
+    return publicResult(childState, false);
   } catch (error) {
-    stopChild(child.pid);
+    if (childState?.pid) { try { process.kill(childState.pid, 'SIGTERM'); } catch {} }
     throw error;
+  } finally {
+    fs.rmdirSync(lockPath);
   }
-
-  const relative = path.relative(root, filePath).split(path.sep).map(encodeURIComponent).join('/');
-  const suffix = args.port === 80 ? '' : `:${args.port}`;
-  const url = `http://${ip}${suffix}${mountPath}/${relative}`;
-  console.log(JSON.stringify({
-    file: filePath,
-    directory: root,
-    mountPath,
-    ip,
-    port: args.port,
-    localPort: child.port,
-    pid: child.pid,
-    ttl: args.ttl,
-    expiresAt: new Date(Date.now() + args.ttl * 1000).toISOString(),
-    url,
-    stopCommand: `kill ${child.pid} 2>/dev/null || true; tailscale serve --http=${args.port} --set-path=${mountPath} off`,
-  }));
 }
 
-async function main() {
+function runWorker(config) {
-  const args = parseArgs(process.argv.slice(2));
+  let shuttingDown = false;
-  if (args.server) {
+  let timer;
-    if (!args.mountPath || !args.root || !args.tailscalePort) throw new PreviewError('内部参数不完整');
+  let state;
-    validPort(args.port, 'local-port');
+  const server = http.createServer((request, response) => {
-    validPort(args.tailscalePort, 'port');
+    if (!['GET', 'HEAD'].includes(request.method)) {
-    validTtl(args.ttl);
+      response.writeHead(405, { Allow: 'GET, HEAD' }).end('Method not allowed');
-    serveStatic(path.resolve(args.root), args.mountPath, args.port, args.ttl, args.tailscalePort);
+      return;
-    return;
+    }
+    let pathname;
+    try { pathname = decodeURIComponent(new URL(request.url, 'http://localhost').pathname); }
+    catch { response.writeHead(400).end('Bad request'); return; }
+    if (pathname === statusPath) {
+      if (request.headers['x-previewer-token'] !== config.token) { response.writeHead(404).end('Not found'); return; }
+      response.setHeader('Content-Type', 'application/json');
+      response.end(request.method === 'HEAD' ? undefined : JSON.stringify(state));
+      return;
+    }
+    let candidate;
+    try {
+      const relative = pathname === '/' ? path.basename(config.file) : pathname.replace(/^\/+/, '');
+      candidate = fs.realpathSync(path.resolve(config.root, relative));
+      const inside = path.relative(config.root, candidate);
+      if (inside === '..' || inside.startsWith('..' + path.sep) || path.isAbsolute(inside)) {
+        response.writeHead(403).end('Forbidden');
+        return;
+      }
+      // Explicit filenames only; no directory listings.
+      if (!fs.statSync(candidate).isFile()) { response.writeHead(404).end('Not found'); return; }
+    } catch { response.writeHead(404).end('Not found'); return; }
+    response.writeHead(200, {
+      'Content-Type': types[path.extname(candidate).toLowerCase()] ?? 'application/octet-stream',
+      'Cache-Control': 'no-store',
+      'X-Content-Type-Options': 'nosniff',
+    });
+    if (request.method === 'HEAD') { response.end(); return; }
+    fs.createReadStream(candidate).on('error', () => response.destroy()).pipe(response);
+  });
+  function shutdown() {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    clearTimeout(timer);
+    try {
+      const record = JSON.parse(fs.readFileSync(config.statePath, 'utf8'));
+      if (record.pid === process.pid && record.token === config.token) fs.unlinkSync(config.statePath);
+    } catch {}
+    server.close(() => process.exit(0));
+    setTimeout(() => process.exit(0), 1000).unref();
   }
-  await launch(args);
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+  server.once('error', (error) => {
+    process.send?.({ code: error.code === 'EADDRINUSE' ? 'PORT_IN_USE' : 'START_FAILED', error: error.message });
+    process.exitCode = 2;
+  });
+  server.listen(config.port, config.host, () => {
+    const port = server.address().port;
+    state = {
+      file: config.file, directory: config.root, host: config.host, port, pid: process.pid,
+      ttl: config.ttl, expiresAt: new Date(Date.now() + config.ttl * 1000).toISOString(),
+      ...urlsFor(config, port), token: config.token, key: config.key,
+    };
+    timer = setTimeout(shutdown, config.ttl * 1000);
+    process.send?.(state);
+  });
 }
 
-main().catch((error) => {
+if (process.argv[2] === '--worker') {
-  console.error(`previewer: ${error.message}`);
+  process.once('message', runWorker);
-  process.exitCode = 2;
+} else if (process.argv.includes('--help') || process.argv.includes('-h')) {
-});
+  console.log('Usage: node serve_file.js FILE [--host IP] [--port PORT] [--ttl SECONDS]\nServe existing HTML/static assets. Defaults: 127.0.0.1, automatic port, 3600 seconds.');
+} else {
+  Promise.resolve().then(() => launch(parseArgs(process.argv.slice(2)))).then((result) => {
+    console.log(JSON.stringify(result));
+  }).catch((error) => {
+    console.error(JSON.stringify({ code: error.code ?? 'PREVIEW_FAILED', message: error.message }));
+    process.exitCode = 2;
+  });
+}

skills/previewer/tests/serve_file.test.js

@@ -0,0 +1,184 @@
+'use strict';
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const http = require('node:http');
+const { spawn } = require('node:child_process');
+
+const script = path.resolve(__dirname, '../scripts/serve_file.js');
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function invoke(args) {
+  return new Promise((resolve, reject) => {
+    // An empty PATH proves there is no dependency on an external networking CLI.
+    const child = spawn(process.execPath, [script, ...args], { env: { ...process.env, PATH: '' } });
+    let stdout = '', stderr = '';
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.once('error', reject);
+    child.once('close', (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+function request(url, method = 'GET') {
+  return new Promise((resolve, reject) => {
+    const req = http.request(url, { method, timeout: 1000 }, (response) => {
+      let body = '';
+      response.on('data', (chunk) => { body += chunk; });
+      response.on('end', () => resolve({ status: response.statusCode, headers: response.headers, body }));
+      response.on('error', reject);
+    });
+    req.on('error', reject);
+    req.on('timeout', () => req.destroy(new Error('timeout')));
+    req.end();
+  });
+}
+
+async function fixture(t) {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'previewer-test-'));
+  const root = path.join(directory, 'site');
+  await fs.mkdir(root);
+  const file = path.join(root, '预览 page.html');
+  await fs.writeFile(file, '<!doctype html><title>预览</title><link rel="stylesheet" href="theme.css"><p>HTML preview</p>');
+  await fs.writeFile(path.join(root, 'theme.css'), 'body { color: red; }');
+  await fs.writeFile(path.join(root, 'app.js'), 'document.title = "preview";');
+  await fs.mkdir(path.join(root, 'assets'));
+  await fs.writeFile(path.join(directory, 'secret.txt'), 'outside-root');
+  const pids = new Set();
+  t.after(async () => {
+    for (const pid of pids) { try { process.kill(pid, 'SIGTERM'); } catch {} }
+    await wait(80);
+    await fs.rm(directory, { recursive: true, force: true });
+  });
+  return {
+    directory, root, file,
+    async launch(extra = []) {
+      const result = await invoke([file, '--ttl', '30', ...extra]);
+      assert.equal(result.code, 0, result.stderr);
+      assert.equal(result.stderr, '');
+      const state = JSON.parse(result.stdout);
+      pids.add(state.pid);
+      return state;
+    },
+    track(state) { pids.add(state.pid); },
+  };
+}
+
+test('serves existing HTML, relative assets and HEAD without network tools', async (t) => {
+  const f = await fixture(t);
+  const state = await f.launch();
+  assert.equal(state.host, '127.0.0.1');
+  assert.equal(state.reused, false);
+  assert.ok(state.port > 0);
+  assert.equal('token' in state, false);
+  assert.equal('ip' in state, false);
+  assert.match(state.stopCommand, /^kill -TERM \d+$/);
+  const html = await request(state.url);
+  assert.equal(html.status, 200);
+  assert.match(html.headers['content-type'], /^text\/html/);
+  assert.match(html.body, /HTML preview/);
+  assert.match((await request(new URL('/', state.url))).body, /HTML preview/);
+  const css = await request(new URL('theme.css', state.url));
+  assert.equal(css.status, 200);
+  assert.match(css.headers['content-type'], /^text\/css/);
+  assert.match(css.body, /color: red/);
+  const js = await request(new URL('app.js', state.url));
+  assert.equal(js.status, 200);
+  assert.match(js.headers['content-type'], /^text\/javascript/);
+  assert.equal((await request(state.url, 'HEAD')).body, '');
+  assert.equal((await request(state.url, 'POST')).status, 405);
+  assert.equal((await request(new URL('assets/', state.url))).status, 404);
+});
+
+test('sequential and concurrent calls reuse a verified service without extending TTL', async (t) => {
+  const f = await fixture(t);
+  const first = await f.launch();
+  const again = await f.launch();
+  assert.equal(again.reused, true);
+  assert.equal(again.pid, first.pid);
+  assert.equal(again.url, first.url);
+  assert.equal(again.expiresAt, first.expiresAt);
+  const concurrent = await Promise.all(Array.from({ length: 4 }, () => f.launch()));
+  for (const state of concurrent) {
+    assert.equal(state.pid, first.pid);
+    assert.equal(state.reused, true);
+    assert.equal(state.expiresAt, first.expiresAt);
+  }
+  // Race the first launch too, not just reuse of an already running worker.
+  const other = path.join(f.root, 'second.html');
+  await fs.writeFile(other, '<p>second</p>');
+  const created = await Promise.all(Array.from({ length: 4 }, () => invoke([other, '--ttl', '30'])));
+  const states = created.map((result) => {
+    assert.equal(result.code, 0, result.stderr);
+    const state = JSON.parse(result.stdout);
+    f.track(state);
+    return state;
+  });
+  assert.equal(new Set(states.map((state) => state.pid)).size, 1);
+  assert.equal(states.filter((state) => state.reused === false).length, 1);
+});
+
+test('occupied port fails instead of replacing its owner', async (t) => {
+  const f = await fixture(t);
+  const first = await f.launch();
+  const other = path.join(f.root, 'other.html');
+  await fs.writeFile(other, '<p>other</p>');
+  const conflict = await invoke([other, '--port', String(first.port), '--ttl', '30']);
+  assert.equal(conflict.code, 2);
+  assert.equal(conflict.stdout, '');
+  assert.equal(JSON.parse(conflict.stderr).code, 'PORT_IN_USE');
+  assert.equal((await request(first.url)).status, 200);
+});
+
+test('outside symlinks, traversal and private status endpoint cannot disclose files', async (t) => {
+  const f = await fixture(t);
+  await fs.symlink(path.join(f.directory, 'secret.txt'), path.join(f.root, 'external.txt'));
+  const state = await f.launch();
+  const symlink = await request(new URL('external.txt', state.url));
+  assert.equal(symlink.status, 403);
+  const traversal = await request(new URL('/..%2fsecret.txt', state.url));
+  assert.equal(traversal.status, 403);
+  assert.equal((await request(new URL('/.previewer-status', state.url))).status, 404);
+  assert.equal((await request(new URL('/%ZZ', state.url))).status, 400);
+});
+
+test('expiry stops the service and a later call creates a fresh preview', async (t) => {
+  const f = await fixture(t);
+  const first = await f.launch(['--ttl', '1']);
+  const deadline = Date.now() + 4000;
+  let stopped = false;
+  while (Date.now() < deadline) {
+    try { await request(first.url); } catch { stopped = true; break; }
+    await wait(80);
+  }
+  assert.equal(stopped, true);
+  const next = await f.launch(['--ttl', '1']);
+  assert.equal(next.reused, false);
+  assert.notEqual(next.pid, first.pid);
+  assert.notEqual(next.expiresAt, first.expiresAt);
+});
+
+test('all-interface preview uses only Node and lists local access URLs', async (t) => {
+  const f = await fixture(t);
+  const state = await f.launch(['--host', '0.0.0.0']);
+  assert.equal(state.host, '0.0.0.0');
+  assert.match(state.url, /^http:\/\/127\.0\.0\.1:/);
+  assert.ok(state.urls.includes(state.url));
+  assert.equal((await request(state.url)).status, 200);
+});
+
+test('invalid inputs and removed options return structured errors without starting servers', async () => {
+  for (const args of [
+    [], ['/missing/preview.html'], [__filename, '--port', '65536'],
+    [__filename, '--ttl', '0'], [__filename, '--ttl', '2147484'],
+    [__filename, '--host', 'not-an-ip'], [__filename, '--host'],
+    [__filename, '--mount-path', '/preview/test'], [__filename, '--tailscale-port', '80'],
+  ]) {
+    const result = await invoke(args);
+    assert.equal(result.code, 2);
+    assert.equal(result.stdout, '');
+    assert.ok(['ARGUMENT', 'FILE_INVALID'].includes(JSON.parse(result.stderr).code));
+  }
+});

skills/product-prototype/README.md

@@ -0,0 +1,153 @@
+# product-prototype
+
+可复用的离线 Product Prototype Studio Skill：用文件型需求、动线、布局和评审数据驱动 React +
+TypeScript + React Flow 原型。
+
+## 安装
+
+```bash
+pouch add product-prototype          # 当前项目
+pouch add product-prototype -g       # 全局
+```
+
+Skill 安装后，从 Skill 目录运行初始化脚本。使用仓库 checkout 时命令如下：
+
+```bash
+python3 skills/product-prototype/scripts/init.py ./prototype
+```
+
+全局安装后可使用 `~/.pouch/skills/product-prototype/scripts/init.py`。初始化脚本是安全的
+补齐操作：目标中已有文件会被保留，并在输出中标记为 `skip`。
+
+## 使用前准备
+
+- Node.js 20+ 与 npm 10+（模板声明 npm，不依赖 pnpm/yarn）。
+- 一份产品目标、核心场景、页面/状态和关键交互说明。
+- 运行时不需要后端、账号、真实设备或网络资源；依赖安装由目标项目自行决定。
+
+模板是可运行的离线 Studio，不是只读的文件占位：它包含 React Flow 画布、共享组件/Action
+registry、flow 驱动的 NavigationRuntime、layout 保存/恢复、review 批注导出和确定性设备管理
+mock。四类源数据仍是唯一事实来源；浏览器产物和构建目录不回写源数据。
+
+## 初始化后的目录
+
+```text
+prototype/
+├── prototype/                 # 源数据：requirements/flow/layout/review
+├── src/
+│   ├── App.tsx                # React Flow Studio 与 runtime preview
+│   ├── contracts/             # 四类源数据 TypeScript 契约
+│   ├── data/                  # 稳定 ID 数据解析入口
+│   ├── layout/                # layout.json round-trip 与显式导出/恢复
+│   ├── registry/              # 页面/Action 注册表唯一入口
+│   ├── runtime/               # navigation runtime 与结构化条件
+│   ├── studio/                # React Flow 画布说明
+│   └── review/                # review.json 校验与导出
+├── scripts/                   # 命令、离线契约测试与增量回归
+├── public/static/             # 只放本地、可版本化静态资源
+├── package.json
+└── package-lock.json
+```
+
+数据职责、ID 规则和边界见 [`references/data-contract.md`](references/data-contract.md)。注册表和
+导航约束见 [`references/registry.md`](references/registry.md)，命令/报告见
+[`references/commands.md`](references/commands.md)，增量修改见
+[`references/incremental.md`](references/incremental.md)，截图和报告见
+[`references/artifacts.md`](references/artifacts.md)。
+
+## 使用示例
+
+```text
+请用 product-prototype 初始化一个设备管理原型，先保留 requirements、flow、layout、review
+四类源数据和稳定 ID；生成离线模板和设备管理 mock，不连接真实设备，并按实际环境记录浏览器验证结果。
+```
+
+初始化后：
+
+```bash
+cd prototype
+npm install                 # 安装 package-lock 锁定的依赖
+npm run init                # 幂等补齐当前项目；已有文件只报告 skip
+npm run dev                 # 启动 Vite（加载/依赖错误原样可见）
+npm run validate -- --data-dir prototype
+npm run snapshot            # 启动 Vite + Chrome，写入 .prototype-artifacts/snapshots
+npm run build               # TypeScript noEmit + Vite production build
+npm run test:incremental   # 离线 flow/layout/review 新增、修改、删除边界检查
+npm test                    # 离线合约 + mock + Playwright 关键交互与三视口 smoke
+```
+
+`snapshot` 使用实际 Vite 页面和可发现的 Chrome，生成真实 PNG 及一一对应 manifest；浏览器
+缺失、页面加载失败或产物不可写都会非零退出。Playwright 报告写入
+`.prototype-artifacts/playwright-report`。测试只使用确定性本地 mock，不连接真实设备/后端。Playwright
+使用一个 worker 显式覆盖 desktop/tablet/mobile；浏览器缺失、服务端口冲突、页面加载或断言失败
+都必须记录为失败，不应跳过。
+
+## 四类数据与审核
+
+默认按用户动线阅读：第一栏展示完整首页，后续每栏展示一个用户任务的完整页面和主要连线。
+例如「广场与关注」一栏并排展示广场首页、关注页、创建关注；「文章写作」另起一栏。
+左侧目录可以直接定位到对应动线，总关系画布保留为辅助视图。
+
+- `requirements.md` 描述目标、场景和验收上下文，供作者、Agent 和评审阅读。
+- `flow.json` 声明 page/dialog/state 节点及 Action/条件边，是导航唯一事实来源；组件只能发出
+  registry 中的 Action ID。
+- `layout.json` 独立保存 React Flow 坐标和 viewport。Studio 只在作者点击 `Save layout.json`
+  时导出，`Restore layout.json` 会先校验稳定 ID，不接受悬空节点。
+- `review.json` 保存审核状态和绑定到 node/edge/page ID 的批注；导出前会再次拒绝悬空目标。
+
+设备管理示例覆盖列表、新建、配置、连接中、成功、失败重试、详情和空列表，数据来自
+`src/mocks/device-management.ts`，不访问真实设备、后端、凭据或 localStorage。
+
+## 增量修改与删除边界
+
+新增页面或 Action 时只添加对应节点/边、layout 坐标、相关 review 和实现；修改文案/组件时只
+更新对应稳定 ID 及其相关截图/批注；删除前先检查并报告入边、出边、layout 坐标和 review 目标，
+删除后不得留下悬空引用。数组排序或重新渲染不能造成无关 ID 重编号，冲突必须显式失败。
+
+模板提供可离线复核的 fixture 检查：
+
+```bash
+cd prototype
+npm run test:incremental
+```
+
+它同时比较 flow、layout、review 的 add/change/delete 结果，并断言 `page.keep`、无关坐标和
+`comment.keep` 等未受影响记录保持不变；该检查是边界回归，不替代真实浏览器回归。
+
+## 版本策略
+
+原型默认是持续演进的：新增功能直接在当前 `prototype/` 上增量修改，保持稳定 ID，并同步
+更新 flow、layout、review、实现和相关截图。每轮变更用 Git 提交保留历史；达到评审通过或
+需要冻结时，再打 `prototype-v1` 这类 tag 作为基线。
+
+只有需要并行比较多个方案、重做导航/信息架构，或必须保留不可变评审基线时才新开版本分支
+或目录。新版本应记录基于哪个版本、变更范围和受影响的稳定 ID，避免复制出两套长期漂移的
+原型数据。
+
+## 如何判断完成
+
+至少应完成：`init` 幂等、`validate` 通过合法 fixture 且拒绝非法 fixture、增量检查通过、
+`build` 通过，以及按实际环境记录 `snapshot`/Playwright 结果。真实截图必须是非空 PNG 且与
+manifest 一一对应；受限宿主环境不能被写成浏览器测试通过。
+
+## 故障排查
+
+- `init` 报目标不可写：换到可写的空目录，或修正目标目录权限；脚本不会提权或覆盖文件。
+- `check_structure.py` 或 `check_docs.py` 报错：确认从仓库根目录运行，或用 `--skill-dir` 指向完整
+  Skill 目录；前者检查结构/链接，后者检查实现能力文档和过时占位措辞。
+- npm 依赖安装失败：记录 Node/npm 版本和完整错误；不要把网络安装失败改写成模板验证通过。
+- `BROWSER_MISSING`：安装 Chrome 或设置 `PROTOTYPE_CHROME_PATH=/绝对路径/google-chrome`，再重跑
+  `npm run snapshot` / `npm test`；不会跳过浏览器测试。
+- `SNAPSHOT_FAILED`：检查 `.prototype-artifacts` 父目录可写、Vite 端口 4173 可用和页面
+  `data-testid`/flow 稳定 ID；Vite 使用 strict port，失败不会发布新的 generated manifest。
+- `DEV_SERVER_TIMEOUT`、`DEV_SERVER_EXITED` 或 Playwright 残留：先停止占用 4173 的旧进程，再
+  重跑；snapshot/test 会在退出时关闭浏览器和 Vite，清理失败时应记录宿主环境状态。
+- 画布没有业务节点：检查 `prototype/flow.json`、`layout.json` 和 registry 是否被 validate
+  接受；模板不从 localStorage 或后端补数据。
+
+## 安全与回滚
+
+模板默认不读取凭据、不访问网络、不连接真实设备，也不执行条件字符串。增量修改前保留 Git
+提交或复制源数据作为回滚点；回滚应恢复同一批 requirements/flow/layout/review 与相关实现，
+不要只回滚截图或构建产物。若模板不适用，移除或回退 `skills/product-prototype/` 即可；不要
+修改 Agent 指令、其它 skill 或真实业务后端配置。

skills/product-prototype/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: product-prototype
+description: >-
+  将产品需求整理为可校验的文件型 prototype 数据，并复制或维护 React + TypeScript + React Flow
+  Prototype Studio。用户提出做高保真原型、页面动线、原型画布、React Flow 原型、交互预览、
+  原型截图/评审、requirements.md/flow.json/layout.json/review.json，或要求初始化可复用
+  Prototype Studio 模板时使用。不要用于真实后端、真实设备连接、生产 UI 编辑器或 Figma 双向同步。
+---
+
+# Product Prototype
+
+把需求、页面关系、布局和评审结论放进可版本化的 prototype 数据，再由本地 Prototype Studio
+读取这些数据。Skill 的规范和模板位于本目录；项目初始化只复制模板和项目源数据，不在 Agent
+目录写入普通 skill 文件。
+
+## 何时使用
+
+- 从产品需求建立 React + TypeScript + React Flow 原型项目。
+- 需要页面、弹窗、状态节点和带 Action/条件的页面动线。
+- 需要统一的 `requirements.md`、`flow.json`、`layout.json`、`review.json` 文件契约。
+- 需要离线、确定性 mock 的原型预览、截图和评审记录。
+
+## 不适用
+
+- 真实设备、真实后端 API、账号权限、云端同步或线上部署。
+- Figma 导入导出、多人协作或浏览器内生产级拖拽编辑器。
+- 只有一张插画/营销页，或仅需要低保真 Draw.io 流程图（使用 `draw-prototype-flow`）。
+
+## 当前能力与执行边界
+
+1. 开始前读取 `references/data-contract.md`，并根据需要读取 `registry.md`、`commands.md`、
+   `incremental.md` 和 `artifacts.md`。
+2. 使用 `scripts/init.py` 从 `assets/studio-template/` 复制项目；默认只创建缺失文件，绝不覆盖
+   用户已有的 requirements、flow、layout、review 或实现文件。模板内的 `npm run init` 提供相同的
+   幂等补齐能力。
+3. `flow.json` 是导航唯一事实来源。页面组件只能调用注册表中的 Action ID；不得在组件里维护
+   第二套页面跳转映射。
+4. 条件只能使用结构化白名单规则；禁止 `eval`、`Function` 或执行任意字符串表达式。
+5. 当前模板已实现 React Flow Studio、共享 registry、NavigationRuntime、四类源数据 validator、
+   确定性设备 mock，以及 `init`/`dev`/`validate`/`snapshot`/`build`/`test` 命令。命令失败时
+   使用稳定错误码和非零退出码，不把缺浏览器、页面失败或宿主环境问题伪装成通过。
+6. `snapshot` 使用真实 Vite 页面和可发现的 Chrome 生成 PNG 与 manifest；`test` 运行离线合约、
+   mock 检查和 Playwright 交互/三视口检查。测试产物只写入 `.prototype-artifacts/`。
+7. 增量变更按稳定 ID 维护 flow、layout、review 和相关实现/截图；新增、修改、删除都必须同步
+   引用并做离线 diff，不能重编号或漂移无关节点。删除前要报告受影响的边、布局和批注。
+8. 默认按用户动线分栏评审，先读 [journeys.md](references/journeys.md)：首栏为完整首页，
+   后续每栏一个用户任务，横向展示完整页面与本栏主要连线；其它动线另起一栏。
+   分组写入 layout.groups，导航仍由 flow 唯一驱动。总关系图只能作为辅助视图。
+
+## 输入与输出
+
+- 输入：需求目标、用户场景、页面/状态清单、关键交互、验收上下文和可选的现有项目路径。
+- 源数据：项目目录中的 `prototype/requirements.md`、`flow.json`、`layout.json`、`review.json`。
+- 输出：可复制的 npm 项目、可追踪的稳定 ID、离线文档、可运行的 Studio/runtime 预览和可复核
+  的截图/测试产物。
+- 生成物：截图、报告和测试输出只能写入项目约定的 artifacts 目录；它们不是源数据。
+
+## 命名与版本策略
+
+- 初始化生成的工作区目录和 npm package 名称统一为 `prototype`；界面标题仍可使用
+  `Prototype Studio`。
+- 后续添加功能默认在当前 `prototype` 上增量修改：保留已有稳定 ID，只新增或局部修改
+  flow/layout/review 和对应实现，并用 Git 提交记录每轮变更。
+- 当一轮原型被评审通过或需要冻结时，用 Git tag/分支保存基线，例如
+  `prototype-v1`；新需求默认从当前基线继续，不复制一套容易漂移的四类源数据。
+- 只有需要并行比较方案、导航/信息架构大幅重做，或必须长期保留不可变评审基线时，才新开
+  版本分支/目录。新版本必须记录 `based on`、变更范围和受影响的稳定 ID。
+
+## 路由
+
+- **初始化**：读取 `references/commands.md`，运行 `python3 scripts/init.py <target>`；先检查目标，
+  只补齐缺失文件，并报告 skipped/created。
+- **检查**：运行 `python3 scripts/check_structure.py` 与 `python3 scripts/check_docs.py`，再按模板项目
+  README 的命令检查；需要浏览器的命令必须记录浏览器、页面和产物结果，不得伪造截图。
+- **增量回归**：在模板根目录运行 `npm run test:incremental`，检查 flow/layout/review 的新增、
+  修改、删除 diff，并确认无关稳定 ID、坐标和批注保留。
+- **实现/扩展**：先读对应 reference；所有页面与 Action 仍通过共享 registry 和 flow 驱动，禁止
+  在业务组件内新增第二套导航映射。真实后端、设备或外部服务需求先停下说明。
+
+## 完成标准
+
+- `SKILL.md` 的 frontmatter 名称与目录一致，README 和 references 链接可读。
+- 模板有锁定的 npm 依赖声明、React/TypeScript/React Flow 入口、本地样式和四类源数据；Studio
+  可查看节点/边、预览 runtime、保存/恢复 layout 并导出 review。
+- 默认预览有首页全貌、独立用户动线栏、真实页面展示与组内连线；没有贯穿不同动线的连线。
+- `init` 重复运行不会覆盖已有源数据；静态检查失败时返回非零码并指出文件。
+- `validate`、离线合约、增量检查和 TypeScript/Vite build 可复核；浏览器截图与 Playwright 结果
+  必须按实际环境报告，未运行或因宿主环境失败的项目只能记录为 test gap。

skills/product-prototype/assets/studio-template/.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+test-results/
+.prototype-artifacts/

skills/product-prototype/assets/studio-template/fixtures/README.md

@@ -0,0 +1,11 @@
+# Validator and incremental fixtures
+
+Each directory is a complete `prototype/`-shaped data set. Run
+`npm run validate -- --data-dir fixtures/valid` for the passing fixture; the
+`invalid-*` fixtures must fail with the named stable ID and error code.
+
+`incremental/` contains the original stable-ID layout base/patch/expected files plus a flow/layout/review
+add-change-delete fixture. Run `npm run test:incremental` from the template root to verify that only
+declared IDs change, deleted IDs disappear, new IDs are present, and unrelated layout/review records stay
+unchanged. The patch's `expected` coordinate makes concurrent edits fail closed rather than overwriting a
+changed coordinate.

skills/product-prototype/assets/studio-template/fixtures/incremental/base-flow.json

@@ -0,0 +1,14 @@
+{
+  "flowVersion": 1,
+  "startNodeId": "page.keep",
+  "nodes": [
+    { "id": "page.keep", "kind": "page", "component": "StudioPlaceholder", "title": "Keep" },
+    { "id": "page.change", "kind": "page", "component": "StudioPlaceholder", "title": "Before" },
+    { "id": "page.delete", "kind": "page", "component": "StudioPlaceholder", "title": "Remove" }
+  ],
+  "edges": [
+    { "id": "edge.keep", "source": "page.keep", "target": "page.change", "actionId": "action.studio.noop", "label": "Keep" },
+    { "id": "edge.change", "source": "page.change", "target": "page.delete", "actionId": "action.studio.noop", "label": "Before" },
+    { "id": "edge.delete", "source": "page.delete", "target": "page.keep", "actionId": "action.studio.noop", "label": "Remove" }
+  ]
+}

skills/product-prototype/assets/studio-template/fixtures/incremental/base-layout-scope.json

@@ -0,0 +1,9 @@
+{
+  "layoutVersion": 1,
+  "viewport": { "x": 0, "y": 0, "zoom": 1 },
+  "nodes": {
+    "page.keep": { "x": 100, "y": 200 },
+    "page.change": { "x": 300, "y": 400 },
+    "page.delete": { "x": 500, "y": 600 }
+  }
+}

skills/product-prototype/assets/studio-template/fixtures/incremental/base-layout.json

@@ -0,0 +1 @@
+{"layoutVersion":1,"viewport":{"x":0,"y":0,"zoom":1},"nodes":{"page.start":{"x":10,"y":20},"page.keep":{"x":300,"y":400}}}

skills/product-prototype/assets/studio-template/fixtures/incremental/base-review.json

@@ -0,0 +1,9 @@
+{
+  "reviewVersion": 1,
+  "status": "draft",
+  "comments": [
+    { "id": "comment.keep", "body": "Unrelated comment", "target": { "kind": "node", "id": "page.keep" } },
+    { "id": "comment.change", "body": "Before", "target": { "kind": "node", "id": "page.change" } },
+    { "id": "comment.delete", "body": "Remove", "target": { "kind": "node", "id": "page.delete" } }
+  ]
+}

skills/product-prototype/assets/studio-template/fixtures/incremental/expected-flow.json

@@ -0,0 +1,14 @@
+{
+  "flowVersion": 1,
+  "startNodeId": "page.keep",
+  "nodes": [
+    { "id": "page.keep", "kind": "page", "component": "StudioPlaceholder", "title": "Keep" },
+    { "id": "page.change", "kind": "page", "component": "StudioPlaceholder", "title": "After" },
+    { "id": "page.add", "kind": "state", "component": "StudioPlaceholder", "title": "Added" }
+  ],
+  "edges": [
+    { "id": "edge.keep", "source": "page.keep", "target": "page.change", "actionId": "action.studio.noop", "label": "Keep" },
+    { "id": "edge.change", "source": "page.change", "target": "page.add", "actionId": "action.studio.noop", "label": "After" },
+    { "id": "edge.add", "source": "page.add", "target": "page.keep", "actionId": "action.studio.noop", "label": "Added" }
+  ]
+}

skills/product-prototype/assets/studio-template/fixtures/incremental/expected-layout-scope.json

@@ -0,0 +1,9 @@
+{
+  "layoutVersion": 1,
+  "viewport": { "x": 0, "y": 0, "zoom": 1 },
+  "nodes": {
+    "page.keep": { "x": 100, "y": 200 },
+    "page.change": { "x": 325, "y": 435 },
+    "page.add": { "x": 80, "y": 90 }
+  }
+}

skills/product-prototype/assets/studio-template/fixtures/incremental/expected-layout.json

@@ -0,0 +1 @@
+{"layoutVersion":1,"viewport":{"x":0,"y":0,"zoom":1},"nodes":{"page.start":{"x":15,"y":25},"page.keep":{"x":300,"y":400},"page.new":{"x":800,"y":900}}}

skills/product-prototype/assets/studio-template/fixtures/incremental/expected-review.json

@@ -0,0 +1,9 @@
+{
+  "reviewVersion": 1,
+  "status": "draft",
+  "comments": [
+    { "id": "comment.keep", "body": "Unrelated comment", "target": { "kind": "node", "id": "page.keep" } },
+    { "id": "comment.change", "body": "After", "target": { "kind": "node", "id": "page.change" } },
+    { "id": "comment.add", "body": "Added", "target": { "kind": "node", "id": "page.add" } }
+  ]
+}

skills/product-prototype/assets/studio-template/fixtures/incremental/patch-data.json

@@ -0,0 +1,24 @@
+{
+  "nodes": {
+    "update": [{ "id": "page.change", "patch": { "title": "After" } }],
+    "removeIds": ["page.delete"],
+    "add": [{ "id": "page.add", "kind": "state", "component": "StudioPlaceholder", "title": "Added" }]
+  },
+  "edges": {
+    "update": [{ "id": "edge.change", "patch": { "target": "page.add", "label": "After" } }],
+    "removeIds": ["edge.delete"],
+    "add": [{ "id": "edge.add", "source": "page.add", "target": "page.keep", "actionId": "action.studio.noop", "label": "Added" }]
+  },
+  "comments": {
+    "update": [{ "id": "comment.change", "patch": { "body": "After" } }],
+    "removeIds": ["comment.delete"],
+    "add": [{ "id": "comment.add", "body": "Added", "target": { "kind": "node", "id": "page.add" } }]
+  },
+  "layout": {
+    "nodes": {
+      "page.change": { "x": 325, "y": 435, "expected": { "x": 300, "y": 400 } },
+      "page.add": { "x": 80, "y": 90 }
+    },
+    "removeNodeIds": ["page.delete"]
+  }
+}

skills/product-prototype/assets/studio-template/fixtures/incremental/patch-layout.json

@@ -0,0 +1 @@
+{"layoutVersion":1,"nodes":{"page.start":{"x":15,"y":25,"expected":{"x":10,"y":20}},"page.new":{"x":800,"y":900}},"removeNodeIds":["page.deleted"]}

skills/product-prototype/assets/studio-template/fixtures/invalid-condition/flow.json

@@ -0,0 +1 @@
+{"flowVersion":1,"startNodeId":"page.start","nodes":[{"id":"page.start","kind":"page","component":"StudioPlaceholder","title":"A"},{"id":"page.end","kind":"page","component":"StudioPlaceholder","title":"B"}],"edges":[{"id":"edge.bad-condition","source":"page.start","target":"page.end","actionId":"action.studio.noop","when":"device.status === 'connected'"}]}

skills/product-prototype/assets/studio-template/fixtures/invalid-condition/layout.json

@@ -0,0 +1 @@
+{"layoutVersion":1,"viewport":{"x":0,"y":0,"zoom":1},"nodes":{}}

skills/product-prototype/assets/studio-template/fixtures/invalid-condition/requirements.md

@@ -0,0 +1,7 @@
+# Prototype requirements
+## Goal
+conditions
+## Scenario
+test
+## Acceptance context
+test

skills/product-prototype/assets/studio-template/fixtures/invalid-condition/review.json

@@ -0,0 +1 @@
+{"reviewVersion":1,"status":"draft","comments":[]}

skills/product-prototype/assets/studio-template/fixtures/invalid-dangling-flow/flow.json

@@ -0,0 +1 @@
+{"flowVersion":1,"startNodeId":"page.start","nodes":[{"id":"page.start","kind":"page","component":"StudioPlaceholder","title":"A"}],"edges":[{"id":"edge.missing","source":"page.start","target":"page.missing","actionId":"action.studio.noop"}]}

skills/product-prototype/assets/studio-template/fixtures/invalid-dangling-flow/layout.json

@@ -0,0 +1 @@
+{"layoutVersion":1,"viewport":{"x":0,"y":0,"zoom":1},"nodes":{}}

skills/product-prototype/assets/studio-template/fixtures/invalid-dangling-flow/requirements.md

@@ -0,0 +1,7 @@
+# Prototype requirements
+## Goal
+references
+## Scenario
+test
+## Acceptance context
+test

skills/product-prototype/assets/studio-template/fixtures/invalid-dangling-flow/review.json

@@ -0,0 +1 @@
+{"reviewVersion":1,"status":"draft","comments":[]}

skills/product-prototype/assets/studio-template/fixtures/invalid-duplicate-id/flow.json

@@ -0,0 +1 @@
+{"flowVersion":1,"startNodeId":"page.start","nodes":[{"id":"page.start","kind":"page","component":"StudioPlaceholder","title":"A"},{"id":"page.start","kind":"page","component":"StudioPlaceholder","title":"B"}],"edges":[]}

skills/product-prototype/assets/studio-template/fixtures/invalid-duplicate-id/layout.json

@@ -0,0 +1 @@
+{"layoutVersion":1,"viewport":{"x":0,"y":0,"zoom":1},"nodes":{}}

skills/product-prototype/assets/studio-template/fixtures/invalid-duplicate-id/requirements.md

@@ -0,0 +1,7 @@
+# Prototype requirements
+## Goal
+duplicate IDs
+## Scenario
+test
+## Acceptance context
+test

skills/product-prototype/assets/studio-template/fixtures/invalid-duplicate-id/review.json

@@ -0,0 +1 @@
+{"reviewVersion":1,"status":"draft","comments":[]}

skills/product-prototype/assets/studio-template/fixtures/invalid-layout-reference/flow.json

@@ -0,0 +1 @@
+{"flowVersion":1,"startNodeId":"page.start","nodes":[{"id":"page.start","kind":"page","component":"StudioPlaceholder","title":"A"}],"edges":[]}

skills/product-prototype/assets/studio-template/fixtures/invalid-layout-reference/layout.json

@@ -0,0 +1 @@
+{"layoutVersion":1,"viewport":{"x":0,"y":0,"zoom":1},"nodes":{"page.missing":{"x":1,"y":2}}}

skills/product-prototype/assets/studio-template/fixtures/invalid-layout-reference/requirements.md

@@ -0,0 +1,7 @@
+# Prototype requirements
+## Goal
+layout refs
+## Scenario
+test
+## Acceptance context
+test

skills/product-prototype/assets/studio-template/fixtures/invalid-layout-reference/review.json

@@ -0,0 +1 @@
+{"reviewVersion":1,"status":"draft","comments":[]}

skills/product-prototype/assets/studio-template/fixtures/invalid-review-reference/flow.json

@@ -0,0 +1 @@
+{"flowVersion":1,"startNodeId":"page.start","nodes":[{"id":"page.start","kind":"page","component":"StudioPlaceholder","title":"A"}],"edges":[]}

skills/product-prototype/assets/studio-template/fixtures/invalid-review-reference/layout.json

@@ -0,0 +1 @@
+{"layoutVersion":1,"viewport":{"x":0,"y":0,"zoom":1},"nodes":{}}

skills/product-prototype/assets/studio-template/fixtures/invalid-review-reference/requirements.md

@@ -0,0 +1,7 @@
+# Prototype requirements
+## Goal
+review refs
+## Scenario
+test
+## Acceptance context
+test

skills/product-prototype/assets/studio-template/fixtures/invalid-review-reference/review.json

@@ -0,0 +1 @@
+{"reviewVersion":1,"status":"draft","comments":[{"id":"comment.missing","body":"Missing target","target":{"kind":"node","id":"page.missing"}}]}

skills/product-prototype/assets/studio-template/fixtures/invalid-unknown-action/flow.json

@@ -0,0 +1 @@
+{"flowVersion":1,"startNodeId":"page.start","nodes":[{"id":"page.start","kind":"page","component":"StudioPlaceholder","title":"A"},{"id":"page.end","kind":"page","component":"StudioPlaceholder","title":"B"}],"edges":[{"id":"edge.unknown-action","source":"page.start","target":"page.end","actionId":"action.missing"}]}

skills/product-prototype/assets/studio-template/fixtures/invalid-unknown-action/layout.json

@@ -0,0 +1 @@
+{"layoutVersion":1,"viewport":{"x":0,"y":0,"zoom":1},"nodes":{}}

skills/product-prototype/assets/studio-template/fixtures/invalid-unknown-action/requirements.md

@@ -0,0 +1,7 @@
+# Prototype requirements
+## Goal
+registry
+## Scenario
+test
+## Acceptance context
+test

skills/product-prototype/assets/studio-template/fixtures/invalid-unknown-action/review.json

@@ -0,0 +1 @@
+{"reviewVersion":1,"status":"draft","comments":[]}

skills/product-prototype/assets/studio-template/fixtures/invalid-unknown-component/flow.json

@@ -0,0 +1 @@
+{"flowVersion":1,"startNodeId":"page.start","nodes":[{"id":"page.start","kind":"page","component":"ComponentMissing","title":"A"}],"edges":[]}

skills/product-prototype/assets/studio-template/fixtures/invalid-unknown-component/layout.json

@@ -0,0 +1 @@
+{"layoutVersion":1,"viewport":{"x":0,"y":0,"zoom":1},"nodes":{}}

skills/product-prototype/assets/studio-template/fixtures/invalid-unknown-component/requirements.md

@@ -0,0 +1,7 @@
+# Prototype requirements
+## Goal
+registry
+## Scenario
+test
+## Acceptance context
+test

skills/product-prototype/assets/studio-template/fixtures/invalid-unknown-component/review.json

@@ -0,0 +1 @@
+{"reviewVersion":1,"status":"draft","comments":[]}

skills/product-prototype/assets/studio-template/fixtures/invalid-unreachable/flow.json

@@ -0,0 +1 @@
+{"flowVersion":1,"startNodeId":"page.start","nodes":[{"id":"page.start","kind":"page","component":"StudioPlaceholder","title":"A"},{"id":"page.orphan","kind":"page","component":"StudioPlaceholder","title":"Orphan"}],"edges":[]}

skills/product-prototype/assets/studio-template/fixtures/invalid-unreachable/layout.json

@@ -0,0 +1 @@
+{"layoutVersion":1,"viewport":{"x":0,"y":0,"zoom":1},"nodes":{}}

skills/product-prototype/assets/studio-template/fixtures/invalid-unreachable/requirements.md

@@ -0,0 +1,7 @@
+# Prototype requirements
+## Goal
+reachability
+## Scenario
+test
+## Acceptance context
+test

skills/product-prototype/assets/studio-template/fixtures/invalid-unreachable/review.json

@@ -0,0 +1 @@
+{"reviewVersion":1,"status":"draft","comments":[]}

skills/product-prototype/assets/studio-template/fixtures/valid/flow.json

@@ -0,0 +1 @@
+{"flowVersion":1,"startNodeId":"page.studio-placeholder","nodes":[{"id":"page.studio-placeholder","kind":"page","component":"StudioPlaceholder","title":"Studio"}],"edges":[]}

skills/product-prototype/assets/studio-template/fixtures/valid/layout.json

@@ -0,0 +1 @@
+{"layoutVersion":1,"viewport":{"x":0,"y":0,"zoom":1},"nodes":{"page.studio-placeholder":{"x":80,"y":80}}}

skills/product-prototype/assets/studio-template/fixtures/valid/requirements.md

@@ -0,0 +1,13 @@
+# Prototype requirements
+
+## Goal
+
+Keep a versioned prototype graph.
+
+## Scenario
+
+An author validates source data offline.
+
+## Acceptance context
+
+Validation is deterministic and reports stable IDs.

skills/product-prototype/assets/studio-template/fixtures/valid/review.json

@@ -0,0 +1 @@
+{"reviewVersion":1,"status":"draft","comments":[]}

skills/product-prototype/assets/studio-template/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#152238" />
+    <title>Prototype Studio</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

skills/product-prototype/assets/studio-template/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "prototype",
+  "version": "0.1.0",
+  "private": true,
+  "packageManager": "npm@10",
+  "description": "Offline React + TypeScript + React Flow Prototype Studio skeleton",
+  "scripts": {
+    "init": "node scripts/init.mjs",
+    "dev": "node scripts/dev.mjs",
+    "validate": "node scripts/validate.mjs",
+    "snapshot": "node scripts/snapshot.mjs",
+    "build": "tsc --noEmit && vite build",
+    "test:incremental": "node scripts/incremental-check.mjs",
+    "test": "node scripts/test.mjs",
+    "test:e2e": "playwright test"
+  },
+  "dependencies": {
+    "@xyflow/react": "12.3.1",
+    "react": "18.3.1",
+    "react-dom": "18.3.1"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.55.0",
+    "@types/node": "22.10.2",
+    "@types/react": "18.3.12",
+    "@types/react-dom": "18.3.1",
+    "@vitejs/plugin-react": "4.3.3",
+    "typescript": "5.6.3",
+    "vite": "5.4.10"
+  }
+}

skills/product-prototype/assets/studio-template/playwright.config.ts

@@ -0,0 +1,23 @@
+import { defineConfig, devices } from "@playwright/test";
+import { execFileSync } from "node:child_process";
+
+function findChrome(): string | undefined {
+  if (process.env.PROTOTYPE_CHROME_PATH) return process.env.PROTOTYPE_CHROME_PATH;
+  try { return execFileSync("which", ["google-chrome"], { encoding: "utf8" }).trim(); } catch { return undefined; }
+}
+const chrome = findChrome();
+
+export default defineConfig({
+  testDir: "./tests/e2e",
+  timeout: 30_000,
+  fullyParallel: false,
+  workers: 1,
+  forbidOnly: Boolean(process.env.CI),
+  retries: process.env.CI ? 2 : 0,
+  reporter: [["line"], ["html", { outputFolder: ".prototype-artifacts/playwright-report", open: "never" }]],
+  use: { baseURL: ["http", "://", "127.0.0.1:4173"].join(""), ...(chrome ? { launchOptions: { executablePath: chrome, args: ["--disable-gpu"] } } : { channel: "chrome" }), headless: true, trace: "retain-on-failure", video: "off", screenshot: "only-on-failure" },
+  webServer: { command: "node scripts/test-server.mjs", url: ["http", "://", "127.0.0.1:4173"].join(""), reuseExistingServer: false, timeout: 30_000 },
+  // Keep one browser worker: the viewport matrix is exercised explicitly in the smoke test,
+  // avoiding three concurrent Chrome instances on constrained CI runners.
+  projects: [{ name: "desktop", use: { ...devices["Desktop Chrome"], viewport: { width: 1440, height: 900 } } }],
+});

skills/product-prototype/assets/studio-template/prototype/flow.json

@@ -0,0 +1,38 @@
+{
+  "flowVersion": 1,
+  "startNodeId": "page.studio-placeholder",
+  "nodes": [
+    { "id": "page.studio-placeholder", "kind": "page", "component": "StudioPlaceholder", "title": "Studio overview", "description": "A page node with actions from the shared flow.", "thumbnail": "/static/studio-overview.svg" },
+    { "id": "dialog.studio-help", "kind": "dialog", "component": "StudioPlaceholder", "title": "Help dialog", "description": "A dialog node rendered from the same registry.", "thumbnail": "/static/studio-help.svg" },
+    { "id": "state.studio-empty", "kind": "state", "component": "StudioPlaceholder", "title": "Empty state", "description": "A state node used to demonstrate conditional navigation.", "thumbnail": "/static/studio-empty.svg" },
+    { "id": "page.device-list", "kind": "page", "component": "DeviceList", "title": "设备列表", "description": "设备管理高保真示例：查看设备、创建设备或预览空列表。" },
+    { "id": "page.device-create", "kind": "page", "component": "DeviceCreate", "title": "新建设备", "description": "填写设备基础信息。" },
+    { "id": "page.device-config", "kind": "page", "component": "DeviceConfig", "title": "配置连接参数", "description": "填写并保存设备连接参数。" },
+    { "id": "state.device-connecting", "kind": "state", "component": "DeviceConnecting", "title": "正在连接设备", "description": "运行确定性连接 mock。" },
+    { "id": "state.device-connected", "kind": "state", "component": "DeviceConnected", "title": "设备连接成功", "description": "连接成功后查看设备详情。" },
+    { "id": "state.device-connection-failed", "kind": "state", "component": "DeviceConnectionFailed", "title": "连接失败", "description": "显示失败原因并支持重试。" },
+    { "id": "state.device-empty", "kind": "state", "component": "DeviceEmpty", "title": "设备列表为空", "description": "无设备时的确定性空状态。" },
+    { "id": "page.device-detail", "kind": "page", "component": "DeviceDetail", "title": "设备详情", "description": "查看连接成功设备的详细信息。" }
+  ],
+  "edges": [
+    { "id": "edge.studio.open-help", "source": "page.studio-placeholder", "target": "dialog.studio-help", "actionId": "action.studio.open-help", "label": "Open help" },
+    { "id": "edge.studio.show-empty", "source": "page.studio-placeholder", "target": "state.studio-empty", "actionId": "action.studio.show-empty", "label": "Show empty", "when": { "op": "truthy", "field": "showEmpty" } },
+    { "id": "edge.studio.close-help", "source": "dialog.studio-help", "target": "page.studio-placeholder", "actionId": "action.studio.close-help", "label": "Close" },
+    { "id": "edge.studio.back", "source": "state.studio-empty", "target": "page.studio-placeholder", "actionId": "action.studio.back", "label": "Back" },
+    { "id": "edge.studio.open-device-management", "source": "page.studio-placeholder", "target": "page.device-list", "actionId": "device.open-management", "label": "打开设备管理" },
+    { "id": "edge.device.create", "source": "page.device-list", "target": "page.device-create", "actionId": "device.create", "label": "新建设备" },
+    { "id": "edge.device.show-empty", "source": "page.device-list", "target": "state.device-empty", "actionId": "device.show-empty", "label": "预览空列表", "when": { "op": "eq", "field": "deviceScenario", "value": "empty" } },
+    { "id": "edge.device.open-detail", "source": "page.device-list", "target": "page.device-detail", "actionId": "device.open-detail", "label": "查看详情", "when": { "op": "truthy", "field": "deviceExists" } },
+    { "id": "edge.device.create-to-list", "source": "page.device-create", "target": "page.device-list", "actionId": "device.back-to-list", "label": "取消" },
+    { "id": "edge.device.create-to-config", "source": "page.device-create", "target": "page.device-config", "actionId": "device.continue-to-config", "label": "继续配置", "when": { "op": "truthy", "field": "formValid" } },
+    { "id": "edge.device.config-to-create", "source": "page.device-config", "target": "page.device-create", "actionId": "device.back-to-create", "label": "返回上一步" },
+    { "id": "edge.device.config-to-connecting", "source": "page.device-config", "target": "state.device-connecting", "actionId": "device.save-config", "label": "保存并连接", "when": { "op": "truthy", "field": "formValid" } },
+    { "id": "edge.device.connecting-success", "source": "state.device-connecting", "target": "state.device-connected", "actionId": "device.resolve-connection", "label": "连接成功", "when": { "op": "eq", "field": "connectionOutcome", "value": "success" } },
+    { "id": "edge.device.connecting-failure", "source": "state.device-connecting", "target": "state.device-connection-failed", "actionId": "device.resolve-connection", "label": "连接失败", "when": { "op": "eq", "field": "connectionOutcome", "value": "failure" } },
+    { "id": "edge.device.connected-detail", "source": "state.device-connected", "target": "page.device-detail", "actionId": "device.open-detail", "label": "查看详情", "when": { "op": "truthy", "field": "deviceExists" } },
+    { "id": "edge.device.failed-retry", "source": "state.device-connection-failed", "target": "state.device-connecting", "actionId": "device.retry-connection", "label": "重试连接", "when": { "op": "truthy", "field": "canRetry" } },
+    { "id": "edge.device.failed-list", "source": "state.device-connection-failed", "target": "page.device-list", "actionId": "device.back-to-list", "label": "返回列表" },
+    { "id": "edge.device.empty-create", "source": "state.device-empty", "target": "page.device-create", "actionId": "device.create", "label": "新建设备" },
+    { "id": "edge.device.detail-list", "source": "page.device-detail", "target": "page.device-list", "actionId": "device.back-to-list", "label": "返回列表" }
+  ]
+}

skills/product-prototype/assets/studio-template/prototype/layout.json

@@ -0,0 +1,24 @@
+{
+  "layoutVersion": 1,
+  "viewport": { "x": 0, "y": 0, "zoom": 1 },
+  "groups": {
+    "journey.home": { "label": "首页", "nodeIds": ["page.studio-placeholder"] },
+    "journey.device-create": { "label": "创建设备", "nodeIds": ["page.device-list", "page.device-create", "page.device-config", "state.device-connecting", "state.device-connected", "page.device-detail"] },
+    "journey.device-retry": { "label": "连接失败与重试", "nodeIds": ["state.device-connection-failed", "state.device-connecting", "state.device-connected"] },
+    "journey.device-empty": { "label": "从空列表开始", "nodeIds": ["state.device-empty", "page.device-create"] },
+    "journey.help": { "label": "帮助与空状态", "nodeIds": ["dialog.studio-help", "state.studio-empty"] }
+  },
+  "nodes": {
+    "page.studio-placeholder": { "x": 80, "y": 80 },
+    "dialog.studio-help": { "x": 420, "y": 40 },
+    "state.studio-empty": { "x": 420, "y": 260 },
+    "page.device-list": { "x": 760, "y": 80 },
+    "page.device-create": { "x": 1080, "y": 80 },
+    "page.device-config": { "x": 1400, "y": 80 },
+    "state.device-connecting": { "x": 1720, "y": 80 },
+    "state.device-connected": { "x": 2040, "y": 80 },
+    "state.device-connection-failed": { "x": 2040, "y": 320 },
+    "state.device-empty": { "x": 1080, "y": 420 },
+    "page.device-detail": { "x": 2360, "y": 80 }
+  }
+}

skills/product-prototype/assets/studio-template/prototype/requirements.md

@@ -0,0 +1,15 @@
+# Prototype requirements
+
+## Goal
+
+用本地 Prototype Studio 维护页面关系、布局和评审记录。
+
+## Scenario
+
+作者从一份需求初始化 Studio，使用共享 registry 和 flow Action 查看页面动线、runtime 预览、
+设备管理 mock、layout 保存和 review 批注导出。
+
+## Acceptance context
+
+验收包括四类源数据和稳定 ID、schema/引用/可达性校验、增量边界、幂等初始化、构建，以及按
+实际环境记录的 snapshot/Playwright 结果；不连接真实后端或设备。