@aipper/aiws-spec 0.0.28 → 0.0.30

package/templates/workspace/.opencode/commands/ws-pull.md

@@ -4,84 +4,15 @@ description: 拉取：fast-forward 拉取并对齐 submodules（尽量避免 det
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-pull -->
 # ws pull
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+Thin CLI wrapper. Delegates to `aiws pull`.
 
-目标：安全拉取 superproject，并对齐 submodules，尽量把 submodule 从 detached HEAD “挂回”分支（仅当该分支包含 gitlink commit），减少人为操作差异。
-
-安全约束（强制）：
-- 不执行破坏性命令；不自动提交/不自动 push
-- 若工作区不干净：停止并要求用户先 commit 或 stash
-- `git pull` 默认只允许 fast-forward（避免隐式 merge/rebase）
-
-步骤（建议）：
-1) 输出上下文并检查工作区干净：
-```bash
-git rev-parse --show-toplevel
-git branch --show-current
-git status --porcelain
-```
-若 `git status --porcelain` 非空：停止。
-
-2) 拉取 superproject（fast-forward only）：
 ```bash
-git pull --ff-only
-```
-若失败：停止并说明需要用户明确选择 `git pull --rebase` 或手动处理。
-
-3) 更新 submodules 到 superproject 记录的 gitlink commit：
-```bash
-if [[ -f .gitmodules ]]; then
-  git submodule sync --recursive
-  git submodule update --init --recursive
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws pull
+elif command -v aiws >/dev/null 2>&1; then
+  aiws pull
 else
-  echo "[info] no .gitmodules"
-fi
-```
-
-4) （可选但推荐）把 submodule 从 detached HEAD 尽量“挂回分支”（不改动 gitlink commit）：
-为避免 origin 多分支时“猜错分支”，本步骤只在 `.gitmodules` 明确配置了 `submodule.<name>.branch` 时才执行；否则保持 detached 并提示先运行 `/ws-submodule-setup` 对齐配置。
-```bash
-if [[ -f .gitmodules ]]; then
-  base_branch="$(git branch --show-current)"
-  git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null \
-    | while read -r key sub_path; do
-      [[ -z "${sub_path:-}" ]] && continue
-      name="${key#submodule.}"; name="${name%.path}"
-      echo "== submodule: ${sub_path} (${name}) =="
-      sub_sha="$(git rev-parse "HEAD:${sub_path}" 2>/dev/null || true)"
-      [[ -z "${sub_sha:-}" ]] && { echo "[warn] no gitlink sha"; continue; }
-
-      cfg_branch="$(git config --file .gitmodules --get "submodule.${name}.branch" 2>/dev/null || true)"
-      if [[ "${cfg_branch:-}" == "." ]]; then cfg_branch="$base_branch"; fi
-      if [[ -z "${cfg_branch:-}" ]]; then
-        echo "[warn] ${sub_path}: missing .gitmodules submodule.${name}.branch; keep detached (run ws-submodule-setup)"
-        continue
-      fi
-      target_branch="${cfg_branch}"
-      pin_branch="aiws/pin/${target_branch}"
-
-      git -C "${sub_path}" fetch origin --prune || true
-      if git -C "${sub_path}" show-ref --verify --quiet "refs/remotes/origin/${target_branch}"; then
-        if git -C "${sub_path}" merge-base --is-ancestor "${sub_sha}" "origin/${target_branch}"; then
-          git -C "${sub_path}" checkout -B "${pin_branch}" "${sub_sha}"
-          git -C "${sub_path}" branch --set-upstream-to "origin/${target_branch}" "${pin_branch}" >/dev/null 2>&1 || true
-          echo "[ok] attached ${sub_path} to ${pin_branch} (upstream=origin/${target_branch}) at ${sub_sha}"
-        else
-          echo "[warn] ${sub_path}: ${sub_sha} is not in origin/${target_branch}; keep detached"
-        fi
-      else
-        echo "[warn] ${sub_path}: origin/${target_branch} not found; keep detached"
-      fi
-    done
+  npx @aipper/aiws pull
 fi
 ```
-
-可选（方案 2，一次性设置 submodule 跟踪分支，会改 `.gitmodules`，需提交）：
-```bash
-git submodule set-branch --branch main <sub_path>
-git add .gitmodules
-git commit -m "chore(submodule): set tracking branch"
-```
 <!-- AIWS_MANAGED_END:opencode:ws-pull -->
-
-可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-push.md

@@ -4,90 +4,15 @@ description: 推送：submodule 感知（先 submodules 后 superproject；fast-
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-push -->
 # ws push
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+Thin CLI wrapper. Delegates to `aiws push`.
 
-目标：安全 push 当前仓库；若仓库包含 submodules，则先 push submodules，再 push superproject（默认 fast-forward；不 force）。
-
-强制约束：
-- 不自动提交、不自动 `git add -A`
-- 不使用 `--force` / `--force-with-lease`
-- 若工作区不干净：停止并要求先 commit 或 stash
-
-步骤（建议）：
-1) 输出上下文并检查工作区干净：
-```bash
-git branch --show-current
-git status --porcelain
-git status -sb
-```
-若 `git status --porcelain` 非空：停止。
-
-2) 判断是否存在 submodules：
-```bash
-if [[ -f .gitmodules ]]; then
-  git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' || true
-fi
-```
-
-3) 若没有 submodules：正常 push（仍需用户确认远端/分支）：
-```bash
-git remote -v
-git push
-```
-
-4) 若有 submodules：先检查 `.gitmodules` 的 `submodule.<name>.branch` 是否齐全（缺失则停止并提示 `/ws-submodule-setup`）：
 ```bash
-missing=0
-while read -r key sub_path; do
-  name="${key#submodule.}"; name="${name%.path}"
-  b="$(git config --file .gitmodules --get "submodule.${name}.branch" 2>/dev/null || true)"
-  if [[ -z "${b:-}" ]]; then
-    echo "error: missing .gitmodules submodule.${name}.branch (path=${sub_path})"
-    missing=1
-  fi
-done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
-if [[ "$missing" -ne 0 ]]; then
-  echo "hint: run /ws-submodule-setup (and commit .gitmodules), then retry"
-  exit 2
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws push
+elif command -v aiws >/dev/null 2>&1; then
+  aiws push
+else
+  npx @aipper/aiws push
 fi
 ```
-
-5) 逐个 push submodules（fast-forward only），再 push superproject：
-```bash
-base_branch="$(git branch --show-current)"
-
-git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null \
-  | while read -r key sub_path; do
-    name="${key#submodule.}"; name="${name%.path}"
-    echo "== submodule: ${sub_path} (${name}) =="
-
-    if [[ -n "$(git -C "${sub_path}" status --porcelain 2>/dev/null || true)" ]]; then
-      echo "error: submodule dirty: ${sub_path}"
-      exit 2
-    fi
-
-    cfg_branch="$(git config --file .gitmodules --get "submodule.${name}.branch" 2>/dev/null || true)"
-    if [[ "${cfg_branch:-}" == "." ]]; then cfg_branch="$base_branch"; fi
-    target_branch="${cfg_branch}"
-
-    git -C "${sub_path}" fetch origin --prune
-    if ! git -C "${sub_path}" show-ref --verify --quiet "refs/remotes/origin/${target_branch}"; then
-      echo "error: missing origin/${target_branch} for ${sub_path}"
-      exit 2
-    fi
-
-    if ! git -C "${sub_path}" merge-base --is-ancestor "origin/${target_branch}" HEAD; then
-      echo "error: non-fast-forward (submodule=${sub_path}, branch=${target_branch})"
-      exit 2
-    fi
-
-    git -C "${sub_path}" push origin "HEAD:refs/heads/${target_branch}"
-  done
-
-git remote -v
-git push
-```
 <!-- AIWS_MANAGED_END:opencode:ws-push -->
-
-可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。
-

package/templates/workspace/.opencode/commands/ws-review.md

@@ -19,7 +19,11 @@ description: 评审：提交前审计改动并落盘证据
 3) 将审计落盘到（目录不存在则创建）：
    - 默认：`changes/<change-id>/review/codex-review.md`
    - 回退：`.agentdocs/tmp/review/codex-review.md`（仅在无法确定 `change-id` 时使用）
-4) 回复中输出：
+4) 若当前任务已进入“准备提交/交付/finish”的语境，继续补齐 dual review gate：
+   - 运行/收敛 `/ws-spec-review`，落盘 `changes/<change-id>/review/spec-review.md`
+   - 运行/收敛 `/ws-quality-review`，落盘 `changes/<change-id>/review/quality-review.md`
+   - 不要把单个 `codex-review.md` 误当成 finish gate 已完成
+5) 回复中输出：
    - `证据（Evidence）:` 证据文件路径
    - `主要风险（Top risks）:` 3–8 条（高→低）
    - `下一步（Next）:` 最小修复清单 + 最小验证命令

package/templates/workspace/.opencode/commands/ws-submodule-setup.md

@@ -4,54 +4,15 @@ description: 子模块分支对齐（写入 .gitmodules 的 submodule.<name>.bra
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-submodule-setup -->
 # ws submodule setup
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+Thin CLI wrapper. Delegates to `aiws submodule-setup`.
 
-目标：为每个 submodule 写入 `.gitmodules` 的 `submodule.<name>.branch`（团队真值），让 `/ws-pull`、`/ws-finish` 能确定性地减少 detached 与人为差异；并使 `aiws validate` 的 submodule 分支门禁通过。
-
-约束：
-- 不自动提交、不自动 push（必须先输出 diff 并让用户确认）
-- 不做破坏性命令
-
-步骤（建议）：
-1) 确认工作区干净：
-```bash
-git status --porcelain
-```
-非空则停止。
-
-2) 列出 submodules：
 ```bash
-test -f .gitmodules || { echo "no .gitmodules"; exit 0; }
-git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'
-```
-
-3) 对每个 submodule 让用户选择目标分支（推荐具体分支名；可选 `.` 表示跟随 superproject 分支名）：
-```bash
-while read -r key sub_path; do
-  name="${key#submodule.}"; name="${name%.path}"
-  echo "== submodule: ${name} path=${sub_path} =="
-  echo "[current] branch=$(git config --file .gitmodules --get submodule.${name}.branch || true)"
-  echo "[origin]  HEAD=$(git -C \"${sub_path}\" symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || true)"
-done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$')
-```
-
-4) 写入分支配置：
-```bash
-git submodule set-branch --branch <branch-or-dot> <sub_path>
-```
-
-5) 输出 diff 并让用户确认是否提交：
-```bash
-git diff -- .gitmodules
-git status --porcelain
-```
-
-6) 用户确认后提交：
-```bash
-git add .gitmodules
-git commit -m "chore(submodule): set tracking branches"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws submodule-setup
+elif command -v aiws >/dev/null 2>&1; then
+  aiws submodule-setup
+else
+  npx @aipper/aiws submodule-setup
+fi
 ```
 <!-- AIWS_MANAGED_END:opencode:ws-submodule-setup -->
-
-可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。
-

package/templates/workspace/.opencode/commands/ws-verify-before-complete.md

@@ -4,24 +4,15 @@ description: 完成前验证：finish / handoff 前检查双审查与 validate/e
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-verify-before-complete -->
 # ws verify before complete
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+Thin CLI wrapper. Delegates to `aiws verify-bc`.
 
-目标：在 `/ws-finish` 或 `/ws-handoff` 前检查双审查、validate stamp 与 evidence 是否齐全。
-
-步骤（建议）：
-1) 检查以下最小 gate：
-   - `changes/<change-id>/review/spec-review.md`
-   - `changes/<change-id>/review/quality-review.md`
-   - `.agentdocs/tmp/aiws-validate/*.json`
-2) 若存在 `changes/<change-id>/evidence/`，检查 review / validate / collaboration summary 是否已收敛。
-3) 将结果落盘到：
-   - 默认：`changes/<change-id>/evidence/verify-before-complete.md`
-   - 回退：`.agentdocs/tmp/review/verify-before-complete.md`
-4) 输出：
-   - `证据（Evidence）:`
-   - `结论（Result）: pass|fail`
-   - `缺失项（Missing）:`
-   - `下一步（Next）:`
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws verify-bc
+elif command -v aiws >/dev/null 2>&1; then
+  aiws verify-bc
+else
+  npx @aipper/aiws verify-bc
+fi
+```
 <!-- AIWS_MANAGED_END:opencode:ws-verify-before-complete -->
-
-可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/helpers/approval-whitelist-check.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+workspace_root="${1:-.}"
+shift || true
+
+command_text=""
+decision_kind="unknown"
+paths=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --command)
+      command_text="${2:-}"
+      shift 2
+      ;;
+    --kind)
+      decision_kind="${2:-unknown}"
+      shift 2
+      ;;
+    --path)
+      paths+=("${2:-}")
+      shift 2
+      ;;
+    *)
+      echo "error: unknown argument: $1" >&2
+      exit 2
+      ;;
+  esac
+done
+
+python3 - "$workspace_root" "$command_text" "$decision_kind" "${paths[@]-}" <<'PY'
+import json
+import os
+import shlex
+import sys
+from datetime import datetime, timezone
+from fnmatch import fnmatch
+from pathlib import Path
+
+workspace_root = Path(sys.argv[1]).resolve()
+command_text = sys.argv[2]
+decision_kind = sys.argv[3]
+paths = sys.argv[4:]
+
+config_path = workspace_root / ".opencode" / "oh-my-opencode.json"
+out_dir = Path(os.environ.get("AIWS_OPENCODE_AUTONOMY_DIR", workspace_root / ".aiws" / "tmp" / "opencode-autonomy"))
+out_dir.mkdir(parents=True, exist_ok=True)
+log_file = out_dir / "approval-whitelist.log"
+result_file = out_dir / "approval-whitelist-last.json"
+
+decision = "manual"
+reason = "missing_policy"
+policy = None
+
+def normalize_signature(command: str) -> str:
+    if not command.strip():
+        return ""
+    tokens = shlex.split(command)
+    if not tokens:
+        return ""
+    if tokens[0] == "git" and len(tokens) >= 2:
+        return f"git {tokens[1]}"
+    return tokens[0]
+
+if config_path.exists():
+    try:
+        raw = json.loads(config_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        payload = {
+            "workspace_root": str(workspace_root),
+            "config_path": str(config_path),
+            "command": command_text,
+            "command_signature": normalize_signature(command_text) if command_text.strip() else "",
+            "kind": decision_kind,
+            "paths": paths,
+            "decision": "manual",
+            "reason": "invalid_config_json",
+        }
+        result_file.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+        with log_file.open("a", encoding="utf-8") as fh:
+            fh.write(f"[{timestamp}] decision=manual reason=invalid_config_json kind={decision_kind} signature={(payload['command_signature'] or '(empty)')} paths={paths}\n")
+        print(json.dumps(payload, ensure_ascii=False))
+        sys.exit(0)
+    policy = raw.get("aiws", {}).get("autonomy", {}).get("approval_whitelist", {})
+
+def path_matches(target: str, patterns: list[str]) -> bool:
+    normalized = target.replace("\\", "/")
+    for pattern in patterns:
+        if fnmatch(normalized, pattern):
+            return True
+        if pattern.endswith("/") and fnmatch(normalized, f"{pattern}*"):
+            return True
+    return False
+
+command_signature = normalize_signature(command_text)
+
+payload = {
+    "workspace_root": str(workspace_root),
+    "config_path": str(config_path),
+    "command": command_text,
+    "command_signature": command_signature,
+    "kind": decision_kind,
+    "paths": paths,
+    "decision": decision,
+    "reason": reason,
+}
+
+if policy and policy.get("enabled") is True:
+    deny_commands = [item for item in policy.get("deny_commands", []) if isinstance(item, str) and item.strip()]
+    deny_paths = [item for item in policy.get("deny_paths", []) if isinstance(item, str) and item.strip()]
+    read_only_commands = [item for item in policy.get("read_only_commands", []) if isinstance(item, str) and item.strip()]
+    write_allow_paths = [item for item in policy.get("write_allow_paths", []) if isinstance(item, str) and item.strip()]
+    host_permission_mode = policy.get("host_permission_mode", "")
+
+    if decision_kind == "host-permission":
+        decision = "manual"
+        reason = f"host_permission_mode={host_permission_mode or 'missing'}"
+    elif command_signature in deny_commands:
+        decision = "deny"
+        reason = "deny_command"
+    elif any(path_matches(path, deny_paths) for path in paths):
+        decision = "deny"
+        reason = "deny_path"
+    elif decision_kind == "read" and command_signature in read_only_commands:
+        decision = "allow"
+        reason = "read_only_command"
+    elif decision_kind == "write" and paths and all(path_matches(path, write_allow_paths) for path in paths):
+        decision = "allow"
+        reason = "write_allow_path"
+    else:
+        decision = "manual"
+        reason = "policy_requires_manual_review"
+
+    payload["host_permission_mode"] = host_permission_mode
+    payload["policy_mode"] = policy.get("mode", "")
+
+payload["decision"] = decision
+payload["reason"] = reason
+result_file.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+with log_file.open("a", encoding="utf-8") as fh:
+    fh.write(f"[{timestamp}] decision={decision} reason={reason} kind={decision_kind} signature={command_signature or '(empty)'} paths={paths}\n")
+
+print(json.dumps(payload, ensure_ascii=False))
+PY

package/templates/workspace/.opencode/helpers/approval-whitelist-run.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+workspace_root="${1:-.}"
+shift || true
+
+helper_dir="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
+check_script="${helper_dir}/approval-whitelist-check.sh"
+
+if [[ ! -x "${check_script}" && ! -f "${check_script}" ]]; then
+  echo "error: missing checker: ${check_script}" >&2
+  exit 2
+fi
+
+decision_json="$(bash "${check_script}" "${workspace_root}" "$@")"
+
+python3 - "${workspace_root}" "${decision_json}" <<'PY'
+import json
+import os
+import shlex
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+workspace_root = Path(sys.argv[1]).resolve()
+payload = json.loads(sys.argv[2])
+
+out_dir = Path(os.environ.get("AIWS_OPENCODE_AUTONOMY_DIR", workspace_root / ".aiws" / "tmp" / "opencode-autonomy"))
+out_dir.mkdir(parents=True, exist_ok=True)
+log_file = out_dir / "approval-whitelist-exec.log"
+result_file = out_dir / "approval-whitelist-exec-last.json"
+
+decision = payload.get("decision", "manual")
+command_text = str(payload.get("command", ""))
+
+def finish(result: dict, exit_code: int) -> None:
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    result_file.write_text(json.dumps(result, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    with log_file.open("a", encoding="utf-8") as fh:
+        fh.write(
+            f"[{timestamp}] decision={result.get('decision')} executed={result.get('executed')} exit_code={result.get('exit_code')} reason={result.get('reason')} command={result.get('command_signature') or '(empty)'}\n"
+        )
+    print(json.dumps(result, ensure_ascii=False))
+    sys.exit(exit_code)
+
+if decision == "deny":
+    finish({**payload, "executed": False, "exit_code": None, "reason": payload.get("reason", "deny_command")}, 4)
+
+if decision != "allow":
+    finish({**payload, "executed": False, "exit_code": None, "reason": payload.get("reason", "manual_review_required")}, 3)
+
+if not command_text.strip():
+    finish({**payload, "decision": "manual", "executed": False, "exit_code": None, "reason": "empty_command"}, 3)
+
+unsafe_fragments = ["&&", "||", ";", "|", ">", "<", "$(", "`"]
+if any(fragment in command_text for fragment in unsafe_fragments):
+    finish({**payload, "decision": "manual", "executed": False, "exit_code": None, "reason": "unsupported_shell_syntax"}, 3)
+
+command_args = shlex.split(command_text)
+if not command_args:
+    finish({**payload, "decision": "manual", "executed": False, "exit_code": None, "reason": "empty_command"}, 3)
+
+proc = subprocess.run(
+    command_args,
+    cwd=str(workspace_root),
+    text=True,
+    capture_output=True,
+    check=False,
+)
+
+result = {
+    **payload,
+    "executed": True,
+    "exit_code": proc.returncode,
+    "stdout_line_count": len(proc.stdout.splitlines()),
+    "stderr_line_count": len(proc.stderr.splitlines()),
+    "reason": "executed",
+}
+
+finish(result, proc.returncode)
+PY

package/templates/workspace/.opencode/helpers/approval-whitelist-watchdog.sh

@@ -0,0 +1,144 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+workspace_root="${1:-.}"
+shift || true
+
+out_dir="${AIWS_OPENCODE_AUTONOMY_DIR:-${workspace_root}/.aiws/tmp/opencode-autonomy}"
+queue_file="${out_dir}/approval-watchdog-queue.jsonl"
+once=false
+poll_ms=2000
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --queue)
+      queue_file="${2:-}"
+      shift 2
+      ;;
+    --once)
+      once=true
+      shift
+      ;;
+    --poll-ms)
+      poll_ms="${2:-2000}"
+      shift 2
+      ;;
+    *)
+      echo "error: unknown argument: $1" >&2
+      exit 2
+      ;;
+  esac
+done
+
+helper_dir="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
+runner_script="${helper_dir}/approval-whitelist-run.sh"
+
+python3 - "$workspace_root" "$queue_file" "$runner_script" "$poll_ms" "$once" <<'PY'
+import json
+import subprocess
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+workspace_root = Path(sys.argv[1]).resolve()
+queue_file = Path(sys.argv[2]).resolve()
+runner_script = Path(sys.argv[3]).resolve()
+poll_ms = max(int(sys.argv[4]), 100)
+once = sys.argv[5].lower() == "true"
+
+out_dir = queue_file.parent
+out_dir.mkdir(parents=True, exist_ok=True)
+results_file = out_dir / "approval-watchdog-results.jsonl"
+state_file = out_dir / "approval-watchdog-state.json"
+log_file = out_dir / "approval-watchdog.log"
+
+def now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+def load_state() -> dict:
+    if not state_file.exists():
+        return {"processed_ids": [], "last_run_at": None, "processed_count": 0}
+    return json.loads(state_file.read_text(encoding="utf-8"))
+
+def save_state(state: dict) -> None:
+    state_file.write_text(json.dumps(state, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+def append_log(message: str) -> None:
+    with log_file.open("a", encoding="utf-8") as fh:
+        fh.write(f"[{now()}] {message}\n")
+
+def normalize_entry(raw: dict, index: int) -> dict:
+    entry_id = str(raw.get("id") or f"queue-{index}")
+    kind = str(raw.get("kind") or "unknown")
+    command = str(raw.get("command") or "")
+    paths = raw.get("paths") if isinstance(raw.get("paths"), list) else []
+    paths = [str(item) for item in paths if str(item).strip()]
+    return {"id": entry_id, "kind": kind, "command": command, "paths": paths}
+
+def run_entry(entry: dict) -> dict:
+    args = ["bash", str(runner_script), str(workspace_root), "--kind", entry["kind"], "--command", entry["command"]]
+    for path in entry["paths"]:
+        args.extend(["--path", path])
+    proc = subprocess.run(args, cwd=str(workspace_root), text=True, capture_output=True, check=False)
+    stdout = proc.stdout.strip()
+    payload = json.loads(stdout) if stdout else {}
+    result = {
+        "id": entry["id"],
+        "queued_kind": entry["kind"],
+        "queued_command": entry["command"],
+        "queued_paths": entry["paths"],
+        "runner_exit_code": proc.returncode,
+        "result": payload,
+        "processed_at": now(),
+    }
+    with results_file.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(result, ensure_ascii=False) + "\n")
+    append_log(
+        f"id={entry['id']} exit_code={proc.returncode} decision={payload.get('decision', 'unknown')} executed={payload.get('executed', False)}"
+    )
+    return result
+
+def process_pending() -> int:
+    state = load_state()
+    processed_ids = set(str(item) for item in state.get("processed_ids", []))
+    processed_now = 0
+    if not queue_file.exists():
+        state["last_run_at"] = now()
+        save_state(state)
+        append_log("queue_missing")
+        return processed_now
+    lines = queue_file.read_text(encoding="utf-8").splitlines()
+    for index, line in enumerate(lines, start=1):
+        stripped = line.strip()
+        if not stripped:
+            continue
+        raw = json.loads(stripped)
+        entry = normalize_entry(raw, index)
+        if entry["id"] in processed_ids:
+            continue
+        run_entry(entry)
+        processed_ids.add(entry["id"])
+        processed_now += 1
+    state["processed_ids"] = sorted(processed_ids)
+    state["processed_count"] = len(processed_ids)
+    state["last_run_at"] = now()
+    save_state(state)
+    append_log(f"cycle_complete processed_now={processed_now}")
+    return processed_now
+
+if once:
+    process_pending()
+    print(state_file)
+    sys.exit(0)
+
+append_log(f"watchdog_start poll_ms={poll_ms}")
+try:
+    while True:
+        process_pending()
+        time.sleep(poll_ms / 1000.0)
+except KeyboardInterrupt:
+    append_log("watchdog_stop keyboard_interrupt")
+    print(state_file)
+    sys.exit(0)
+PY