oh-my-opencode 4.10.0 → 4.11.0

package/.agents/skills/codex-qa/scripts/lib/app-server-client.mjs

@@ -0,0 +1,117 @@
+// app-server-client.mjs - drive a real `codex app-server` turn for QA.
+//
+// This is the FIRST-PARTY way to QA the omo Codex plugin: instead of scripting
+// the TUI, we speak the app-server's own protocol (newline-delimited JSON over
+// stdio - NO "jsonrpc" field) and watch the structured notification stream.
+//
+//   initialize -> initialized -> thread/start -> turn/start
+//   ... collect hook/started + hook/completed (plugin proof)
+//   ... collect item/completed agentMessage (assistant text)
+//   stop on turn/completed (turn.status == "completed" | "failed")
+//
+// Env (CODEX_HOME is inherited and MUST already point at the isolated home):
+//   MOCK_PORT     port of the mock model server (required; no real API call).
+//   PROMPT        user message text (default "say hello").
+//   QA_CWD        conversation working dir (default process.cwd()).
+//   DEADLINE_MS   hard stop (default 60000).
+//   EXPECT_HOOK   comma-separated hook eventNames that MUST complete for exit 0
+//                 (e.g. "userPromptSubmit,sessionStart"). Empty = only require
+//                 turn/completed.
+//   CODEX_BIN     codex binary (default "codex"; PATH lookup, no shell function).
+//
+// Prints a JSON summary to stdout. Exit 0 iff the turn completed AND every
+// EXPECT_HOOK fired with status "completed".
+import { spawn } from "node:child_process";
+
+const CODEX_BIN = process.env.CODEX_BIN || "codex";
+const MOCK_PORT = process.env.MOCK_PORT;
+const PROMPT = process.env.PROMPT || "say hello";
+const CWD = process.env.QA_CWD || process.cwd();
+const DEADLINE_MS = Number(process.env.DEADLINE_MS || 60000);
+const EXPECT = (process.env.EXPECT_HOOK || "").split(",").map((s) => s.trim()).filter(Boolean);
+
+if (!MOCK_PORT) {
+  console.error("app-server-client: MOCK_PORT is required (start lib/mock-model.mjs first)");
+  process.exit(2);
+}
+
+// Config overrides force codex onto the local mock provider, never the real one.
+const overrides = [
+  `model="mock-model"`,
+  `model_provider="mock_provider"`,
+  `model_providers.mock_provider.name="codex-qa mock"`,
+  `model_providers.mock_provider.base_url="http://127.0.0.1:${MOCK_PORT}/v1"`,
+  `model_providers.mock_provider.wire_api="responses"`,
+  `model_providers.mock_provider.request_max_retries=0`,
+  `model_providers.mock_provider.stream_max_retries=0`,
+  `approval_policy="never"`,
+  `sandbox_mode="read-only"`,
+];
+const args = overrides.flatMap((o) => ["-c", o]).concat("app-server");
+
+const child = spawn(CODEX_BIN, args, { stdio: ["pipe", "pipe", "pipe"], env: process.env });
+let stderr = "";
+child.stderr.on("data", (c) => (stderr += c));
+
+const hooks = [];
+let assistantText = null;
+let threadId = null;
+let turnId = null;
+let turnStatus = null;
+let buf = "";
+let finished = false;
+
+const send = (obj) => child.stdin.write(JSON.stringify(obj) + "\n");
+
+function finish() {
+  if (finished) return;
+  finished = true;
+  try { child.kill("SIGTERM"); } catch {}
+  const completed = new Set(hooks.filter((h) => h.method === "hook/completed" && h.status === "completed").map((h) => h.eventName));
+  const missing = EXPECT.filter((e) => !completed.has(e));
+  const ok = turnStatus === "completed" && missing.length === 0;
+  console.log(JSON.stringify({ ok, turnStatus, assistantText, threadId, turnId, expectHook: EXPECT, missingHooks: missing, hooks, stderrTail: stderr.split("\n").slice(-10).join("\n") }, null, 2));
+  process.exit(ok ? 0 : 1);
+}
+
+function handle(msg) {
+  if (msg.id === 1 && msg.result) {
+    send({ method: "initialized" });
+    send({ id: 2, method: "thread/start", params: { cwd: CWD } });
+  } else if (msg.id === 2 && msg.result) {
+    threadId = msg.result.thread?.id;
+    send({ id: 3, method: "turn/start", params: { threadId, input: [{ type: "text", text: PROMPT }] } });
+  } else if (msg.id === 3 && msg.result) {
+    turnId = msg.result.turn?.id;
+  } else if (msg.method === "hook/started" || msg.method === "hook/completed") {
+    const run = msg.params?.run || {};
+    hooks.push({ method: msg.method, eventName: run.eventName, status: run.status, source: run.source ?? run.pluginId });
+  } else if (msg.method === "item/completed") {
+    const item = msg.params?.item;
+    if (item?.type === "agentMessage" && typeof item.text === "string") assistantText = item.text;
+  } else if (msg.method === "turn/completed") {
+    turnStatus = msg.params?.turn?.status;
+    finish();
+  }
+}
+
+child.stdout.on("data", (chunk) => {
+  buf += chunk;
+  let nl;
+  while ((nl = buf.indexOf("\n")) >= 0) {
+    const line = buf.slice(0, nl).trim();
+    buf = buf.slice(nl + 1);
+    if (!line) continue;
+    let msg;
+    try { msg = JSON.parse(line); } catch { continue; }
+    handle(msg);
+  }
+});
+child.on("exit", (code) => {
+  if (finished) return;
+  console.log(JSON.stringify({ ok: false, exitCode: code, turnStatus, hooks, stderrTail: stderr.split("\n").slice(-15).join("\n") }, null, 2));
+  process.exit(1);
+});
+
+send({ id: 1, method: "initialize", params: { clientInfo: { name: "codex-qa", version: "0.1.0" }, capabilities: { experimentalApi: true, requestAttestation: false } } });
+setTimeout(() => { stderr += "\n[driver] deadline reached\n"; finish(); }, DEADLINE_MS);

package/.agents/skills/codex-qa/scripts/lib/common.sh

@@ -0,0 +1,180 @@
+#!/usr/bin/env bash
+# common.sh - shared helpers for codex-qa scripts.
+#
+# Source it from a sibling script:
+#   SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+#   . "$SCRIPT_DIR/lib/common.sh"
+#
+# SAFETY MODEL (read this):
+#   - We QA ONLY our plugin, never the user's real codex. Everything that
+#     spawns codex runs against an ISOLATED CODEX_HOME (cqa_mk_isolated_home)
+#     plus a LOCAL mock model provider (cqa_start_mock) - so there is no real
+#     API call and the real ~/.codex is never read or written.
+#   - cqa_guard_real_home snapshots the real ~/.codex/config.toml up front;
+#     cqa_assert_real_home_unchanged proves QA never touched it.
+#   - cqa_cleanup runs on EXIT and tears down the app-server, mock model, tmux
+#     sessions, and every temp dir the helpers created.
+#
+# The interactive shell may wrap `codex` in a function that injects
+# `--profile`; bash scripts do not see that function, so `codex` here is the
+# real binary on PATH. We still resolve it explicitly via cqa_codex_bin.
+
+set -uo pipefail
+
+CQA_TMPDIRS=()
+CQA_PIDS=()
+CQA_TMUX_SESSIONS=()
+CQA_REAL_HOME_SUM=""
+
+cqa_log()  { printf '%s\n' "$*" >&2; }
+cqa_pass() { printf 'PASS: %s\n' "$*"; }
+cqa_fail() { printf 'FAIL: %s\n' "$*" >&2; return 1; }
+
+# cqa_require <bin>...  -> 0 if all present, else 1 (names the missing ones).
+cqa_require() {
+  local missing=0 b
+  for b in "$@"; do
+    command -v "$b" >/dev/null 2>&1 || { cqa_log "missing dependency: $b"; missing=1; }
+  done
+  return "$missing"
+}
+
+# Absolute path of the REAL codex binary (bypasses any interactive shell
+# function/alias). Override with CODEX_BIN.
+cqa_codex_bin() {
+  if [ -n "${CODEX_BIN:-}" ]; then printf '%s' "$CODEX_BIN"; return 0; fi
+  command -v codex 2>/dev/null
+}
+
+cqa_real_codex_home() { printf '%s' "${HOME}/.codex"; }
+
+# Snapshot the real ~/.codex/config.toml so we can prove QA never touched it.
+cqa_guard_real_home() {
+  local cfg; cfg="$(cqa_real_codex_home)/config.toml"
+  if [ -f "$cfg" ]; then
+    CQA_REAL_HOME_SUM="$(shasum "$cfg" 2>/dev/null | awk '{print $1}')"
+  else
+    CQA_REAL_HOME_SUM="ABSENT"
+  fi
+}
+
+cqa_assert_real_home_unchanged() {
+  local cfg now; cfg="$(cqa_real_codex_home)/config.toml"
+  if [ -f "$cfg" ]; then now="$(shasum "$cfg" 2>/dev/null | awk '{print $1}')"; else now="ABSENT"; fi
+  if [ "$now" = "$CQA_REAL_HOME_SUM" ]; then
+    cqa_pass "real ~/.codex/config.toml unchanged ($now)"
+    return 0
+  fi
+  cqa_fail "real ~/.codex/config.toml CHANGED ($CQA_REAL_HOME_SUM -> $now)"
+}
+
+# Create an isolated CODEX_HOME and project dir, export the env that keeps the
+# run hermetic, and register the temp root for cleanup. Sets globals
+# CQA_HOME_ROOT / CODEX_HOME / OMO_CODEX_PROJECT / QA_CWD.
+#
+# IMPORTANT: call this DIRECTLY, never via $(...). A subshell would discard the
+# exports and the cleanup registration.
+cqa_mk_isolated_home() {
+  local root; root="$(mktemp -d -t cqa-home.XXXXXX)" || return 1
+  CQA_TMPDIRS+=("$root")
+  # CODEX_HOME must EXIST before codex launches, or codex hard-errors.
+  mkdir -p "$root/codex" "$root/proj"
+  export CQA_HOME_ROOT="$root"
+  export CODEX_HOME="$root/codex"
+  export OMO_CODEX_PROJECT="$root/proj"
+  export QA_CWD="$root/proj"
+  # never leak install bins or telemetry out of the sandbox
+  export CODEX_LOCAL_BIN_DIR="$root/codex/bin"
+  export OMO_DISABLE_POSTHOG=1
+  export OMO_CODEX_DISABLE_POSTHOG=1
+}
+
+# Start the local mock model server. Sets CQA_MOCK_PID + exports MOCK_PORT.
+# Call DIRECTLY (not via $(...)) so the PID + export land in the caller.
+cqa_start_mock() {
+  local lib_dir log; lib_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  log="$(mktemp -t cqa-mock.XXXXXX)"; CQA_TMPDIRS+=("$log")
+  node "$lib_dir/mock-model.mjs" >"$log" 2>&1 &
+  CQA_MOCK_PID=$!; CQA_PIDS+=("$CQA_MOCK_PID")
+  local i port=""
+  for i in $(seq 1 100); do
+    port="$(awk '/MOCK_LISTENING/{print $2; exit}' "$log" 2>/dev/null)"
+    [ -n "$port" ] && break
+    kill -0 "$CQA_MOCK_PID" 2>/dev/null || { cqa_log "mock model died:"; cat "$log" >&2; return 1; }
+    sleep 0.1
+  done
+  [ -n "$port" ] || { cqa_log "mock model never reported a port"; return 1; }
+  export MOCK_PORT="$port"
+}
+
+# Install THIS repo's local omo build into the isolated CODEX_HOME. Requires
+# cqa_mk_isolated_home first. REPO_ROOT defaults to the repo containing this skill.
+cqa_install_local_omo() {
+  local repo="${REPO_ROOT:-}"
+  if [ -z "$repo" ]; then
+    repo="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../../.." && pwd)"
+  fi
+  local installer="$repo/packages/omo-codex/scripts/install-local.mjs"
+  [ -f "$installer" ] || { cqa_fail "installer not found: $installer"; return 1; }
+  node "$installer" install >"$CQA_HOME_ROOT/install.log" 2>&1
+}
+
+# Teardown everything the helpers created. Safe to call multiple times.
+cqa_cleanup() {
+  local p s d
+  for p in "${CQA_PIDS[@]:-}"; do
+    [ -n "$p" ] && kill "$p" 2>/dev/null || true
+  done
+  for s in "${CQA_TMUX_SESSIONS[@]:-}"; do
+    [ -n "$s" ] && tmux kill-session -t "$s" 2>/dev/null || true
+  done
+  for d in "${CQA_TMPDIRS[@]:-}"; do
+    [ -n "$d" ] && rm -rf "$d" 2>/dev/null || true
+  done
+  CQA_TMPDIRS=(); CQA_PIDS=(); CQA_TMUX_SESSIONS=()
+}
+trap cqa_cleanup EXIT
+
+# ---- self-check ------------------------------------------------------------
+# Run: bash scripts/lib/common.sh --self-check
+cqa__self_check() {
+  local fails=0
+  if cqa_require codex node jq tmux; then cqa_pass "dependencies present (codex node jq tmux)"
+  else cqa_log "FAIL: missing dependencies"; fails=$((fails+1)); fi
+
+  local bin; bin="$(cqa_codex_bin)"
+  if [ -n "$bin" ]; then cqa_pass "codex binary -> $bin"
+  else cqa_log "FAIL: codex binary not found"; fails=$((fails+1)); fi
+
+  cqa_guard_real_home
+
+  # isolation + trap teardown: an inner shell creates a sandbox (DIRECTLY) and
+  # exits; the EXIT trap must remove it. Pass the path out via a marker file.
+  local marker root home
+  marker="$(mktemp -t cqa-marker.XXXXXX)"
+  bash -c '. "'"${BASH_SOURCE[0]}"'"; cqa_mk_isolated_home; printf "%s\n%s\n" "$CQA_HOME_ROOT" "$CODEX_HOME" > "'"$marker"'"'
+  root="$(sed -n '1p' "$marker" 2>/dev/null)"; home="$(sed -n '2p' "$marker" 2>/dev/null)"
+  rm -f "$marker"
+  if [ -n "$root" ] && [ ! -d "$root" ]; then cqa_pass "isolated CODEX_HOME auto-removed on exit ($root)"
+  else cqa_log "FAIL: sandbox not cleaned: '$root'"; fails=$((fails+1)); fi
+  if [ -n "$home" ] && [ "$home" = "$root/codex" ]; then cqa_pass "CODEX_HOME points inside sandbox, not ~/.codex"
+  else cqa_log "FAIL: CODEX_HOME not isolated ('$home')"; fails=$((fails+1)); fi
+
+  # mock model: start it, confirm it serves the Responses SSE, then cleanup.
+  cqa_mk_isolated_home
+  if cqa_start_mock; then
+    if curl -s -X POST "http://127.0.0.1:$MOCK_PORT/v1/responses" -d '{}' 2>/dev/null | grep -q 'response.completed'; then
+      cqa_pass "mock model serves Responses SSE on :$MOCK_PORT"
+    else cqa_log "FAIL: mock model did not return response.completed"; fails=$((fails+1)); fi
+  else cqa_log "FAIL: mock model did not start"; fails=$((fails+1)); fi
+
+  cqa_assert_real_home_unchanged || fails=$((fails+1))
+
+  if [ "$fails" -eq 0 ]; then cqa_pass "common.sh self-check"; return 0; fi
+  cqa_log "common.sh self-check had $fails failure(s)"; return 1
+}
+
+if [ "${1:-}" = "--self-check" ]; then
+  cqa__self_check
+  exit $?
+fi

package/.agents/skills/codex-qa/scripts/lib/mock-model.mjs

@@ -0,0 +1,56 @@
+// mock-model.mjs - a local OpenAI Responses-API SSE server for codex-qa.
+//
+// WHY: codex talks to a model over HTTP. Pointing a custom model_provider at
+// this server lets QA drive a REAL codex turn end-to-end with NO real API
+// call, no key, and no network egress - so we test OUR plugin, never OpenAI.
+//
+// It answers POST .../responses with the 3-event Responses stream codex needs
+// for one assistant message (response.created -> output_item.done ->
+// response.completed). Each POST gets a fresh response, so a turn that makes
+// several model requests (session-start probe + the turn itself) is covered.
+//
+// Env:
+//   MOCK_PORT  TCP port to bind (default 0 = OS-assigned; the chosen port is
+//              printed as "MOCK_LISTENING <port>" on stdout so the caller can
+//              read it back).
+//   MOCK_TEXT  assistant message text (default below).
+import { createServer } from "node:http";
+
+const TEXT = process.env.MOCK_TEXT || "Hello from the codex-qa mock model.";
+
+const server = createServer((req, res) => {
+  if (req.method === "POST" && req.url && req.url.endsWith("/responses")) {
+    let body = "";
+    req.on("data", (c) => (body += c));
+    req.on("end", () => {
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+      });
+      const sse = (obj) => res.write(`event: ${obj.type}\ndata: ${JSON.stringify(obj)}\n\n`);
+      sse({ type: "response.created", response: { id: "resp-1" } });
+      sse({
+        type: "response.output_item.done",
+        item: {
+          type: "message",
+          role: "assistant",
+          id: "msg-1",
+          content: [{ type: "output_text", text: TEXT }],
+        },
+      });
+      sse({
+        type: "response.completed",
+        response: { id: "resp-1", usage: { input_tokens: 0, output_tokens: 0, total_tokens: 0 } },
+      });
+      res.end();
+    });
+    return;
+  }
+  res.writeHead(404).end();
+});
+
+const port = Number(process.env.MOCK_PORT || 0);
+server.listen(port, "127.0.0.1", () => {
+  process.stdout.write(`MOCK_LISTENING ${server.address().port}\n`);
+});

package/.agents/skills/codex-qa/scripts/tui-smoke.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# tui-smoke.sh - boot the real codex TUI under tmux in an ISOLATED CODEX_HOME
+# (+ local mock model) and capture the rendered pane. SMOKE only: it proves the
+# TUI launches, renders, and stays alive - it does NOT assert turn behavior
+# (use app-server-drive.sh for that). The captured pane is the artifact.
+#
+#   --self-test       boot bare TUI, assert it renders + survives, capture pane
+#   --plugin          install local omo first, then boot (proves the plugin
+#                     loads in the real TUI without crashing it)
+#   --seconds <n>     dwell time before capture (default 5)
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$SCRIPT_DIR/lib/common.sh"
+
+cqa_tui_smoke() {
+  local plugin="$1" dwell="$2"
+  cqa_require codex tmux node || return 1
+  cqa_guard_real_home
+  cqa_mk_isolated_home
+  if [ "$plugin" = "1" ]; then
+    cqa_log "installing local omo into $CODEX_HOME ..."
+    cqa_install_local_omo || { tail -20 "$CQA_HOME_ROOT/install.log" >&2; return 1; }
+  fi
+  cqa_start_mock || return 1
+  local bin sess cap launch exitf errf; bin="$(cqa_codex_bin)"
+  sess="cqa-tui-$$"; CQA_TMUX_SESSIONS+=("$sess")
+  cap="$CQA_HOME_ROOT/tui-pane.txt"
+  launch="$CQA_HOME_ROOT/tui-launch.sh"
+  exitf="$CQA_HOME_ROOT/tui-exit.txt"
+  errf="$CQA_HOME_ROOT/tui-stderr.txt"
+  cat > "$launch" <<LAUNCH
+#!/usr/bin/env bash
+export CODEX_HOME="$CODEX_HOME"
+cd "$QA_CWD" || exit 97
+"$bin" -c model=mock-model -c model_provider=mock_provider \
+  -c model_providers.mock_provider.name="codex-qa mock" \
+  -c model_providers.mock_provider.base_url=http://127.0.0.1:$MOCK_PORT/v1 \
+  -c model_providers.mock_provider.wire_api=responses \
+  -c approval_policy=never -c sandbox_mode=read-only 2>"$errf"
+echo "\$?" > "$exitf"
+sleep 600
+LAUNCH
+  chmod +x "$launch"
+  tmux new-session -d -s "$sess" -x 200 -y 50 "bash '$launch'"
+  sleep "$dwell"
+  tmux capture-pane -t "$sess" -p -S - > "$cap" 2>/dev/null
+  tmux send-keys -t "$sess" C-c 2>/dev/null; sleep 0.3
+  tmux kill-session -t "$sess" 2>/dev/null
+  cqa_assert_real_home_unchanged || return 1
+  if [ -f "$exitf" ]; then
+    cqa_log "codex exited during boot (code $(cat "$exitf")); stderr:"; sed -n '1,20p' "$errf" >&2
+    return "$(cqa_fail "codex TUI did not stay up")"
+  fi
+  cqa_log "captured pane -> $cap"; sed -n '1,40p' "$cap" >&2
+  if [ ! -s "$cap" ]; then cqa_fail "TUI pane was empty (did not render)"; return 1; fi
+  if grep -qiE 'panic|panicked|fatal' "$cap"; then cqa_fail "TUI crashed (panic/fatal in pane)"; return 1; fi
+  cqa_pass "codex TUI booted, rendered, and survived ${dwell}s (no early exit)"; return 0
+}
+
+MODE=0; DWELL=5
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --self-test) MODE=0; shift ;;
+    --plugin) MODE=1; shift ;;
+    --seconds) DWELL="$2"; shift 2 ;;
+    -h|--help) sed -n '2,12p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) cqa_log "unknown option: $1"; shift ;;
+  esac
+done
+cqa_tui_smoke "$MODE" "$DWELL"
+exit $?

package/.agents/skills/opencode-qa/SKILL.md

@@ -10,7 +10,7 @@ helper script and a deep reference. Every script ships a `--self-test` that
 asserts its scenario against the live machine, so the scripts are both the QA
 tools and their own regression checks.
 
-Verified against opencode v1.15.13 (bun 1.3.12, macOS). Confirm the installed
+Verified against opencode v1.17.7 (bun 1.3.12, macOS). Confirm the installed
 version with `opencode --version`; the surface is stable but always sanity
 check a flag with `opencode <cmd> --help`.
 
@@ -39,6 +39,12 @@ cd <this-skill-dir>                        # .agents/skills/opencode-qa
 bash scripts/lib/common.sh --self-check    # confirm the harness + deps
 ```
 
+**Docker is the default QA surface.** Run QA inside a disposable container that
+has the latest opencode and a copy of your config, with the host untouched:
+`script/agent/qa-docker.sh` (see [references/docker-qa.md](references/docker-qa.md)).
+The local scripts below are the fallback for when Docker is unavailable or on
+Windows.
+
 `common.sh` provides the shared harness (DB path, SQL escaping, isolated XDG
 sandbox, free port, server start/stop, and an EXIT-trap cleanup). It requires
 `opencode`, `sqlite3`, `curl`, `jq`, and `tmux` on PATH.
@@ -193,3 +199,4 @@ isolated sandbox and clean up on exit.
 - `references/tui-tmux.md` - tmux recipe, isolation, TUI control API
 - `references/testing-harness.md` - how opencode tests itself (bun test)
 - `references/sdk.md` - the @opencode-ai/sdk client (reference only)
+- `references/docker-qa.md` - run QA in a disposable Docker container (default; local is the fallback)

package/.agents/skills/opencode-qa/references/docker-qa.md

@@ -0,0 +1,72 @@
+# Docker QA (default path)
+
+Run opencode QA inside a DISPOSABLE container so the host is never touched and
+you always test against the latest opencode. The container itself is the
+sandbox: latest released opencode + codex are baked in, a COPY of your local
+config is loaded, and the container is removed on exit (`docker run --rm`). This
+is the DEFAULT; fall back to running the scripts locally (see SKILL.md) only
+when Docker is unavailable or on Windows.
+
+## Use it
+
+`qa-docker.sh` brings up a disposable box (builds `omo-dev` then `omo-qa` on
+first use, reused after) and either drops you into it or serves opencode to
+your host. From the repo root:
+
+```bash
+# a shell inside the box: just type `opencode ...` or `codex ...`
+script/agent/qa-docker.sh
+script/agent/qa-docker.sh shell
+
+# serve opencode's HTTP API to the host, then drive it from OUTSIDE:
+script/agent/qa-docker.sh serve 4096               # terminal 1 (Ctrl-C stops + removes)
+curl http://127.0.0.1:4096/global/health           # host -> {"healthy":true,"version":"1.17.7"}
+opencode run "hi" --attach http://127.0.0.1:4096   # a real turn against the box
+
+# one-off command, or a skill's own self-test, inside:
+script/agent/qa-docker.sh exec opencode --version
+script/agent/qa-docker.sh exec bash .agents/skills/opencode-qa/scripts/server-smoke.sh --self-test
+
+script/agent/qa-docker.sh --no-config exec opencode --version   # skip the config copy
+script/agent/qa-docker.sh --clean                               # remove the QA images
+```
+
+`omo-qa` is `omo-dev` (`.devcontainer/Dockerfile`) plus the latest `opencode-ai`
+and `@openai/codex` npm packages and `sqlite3 jq curl rsync`. Pin with
+`--build-arg OMO_OPENCODE_VERSION=...` on the qa.Dockerfile for a specific release.
+
+## Why the container is the sandbox
+
+The local scripts isolate by pointing `XDG_*` at temp dirs so they never
+pollute the real `~/.local/share/opencode/opencode.db`. In Docker the whole
+container is throwaway, so isolation is structural: your host DB and config are
+never written. `qa-docker.sh` mounts `~/.config/opencode` (and `~/.codex`)
+READ-ONLY at `/mnt/host/*`; the entrypoint copies them into the container's
+writable home (heavy caches excluded) so QA runs against a COPY.
+
+## Credentials
+
+Secrets are never baked into the image. Provide them at run time only:
+
+- a gitignored `.env` or `.env.local` at the repo root (auto-sourced by
+  `script/agent/setup.sh` and `script/agent/qa-sandbox.sh`),
+- GitHub Codespaces secrets, or
+- the devcontainer `remoteEnv` passthrough.
+
+The host config is mounted read-only, so auth that already lives in
+`~/.config/opencode` rides along without copying secrets into any image layer.
+
+Fish caveat: if your shell sets `OPENCODE_CONFIG_DIR` (for example a
+`profiles/today` override), export it before calling `qa-docker.sh` so the
+container resolves the same profile (the runner forwards it with `-e`).
+
+## Fallback: local / Windows
+
+`qa-docker.sh` exits 3 with guidance when Docker is unavailable or on Windows.
+There, run the scripts directly on the host (the rest of this skill); they
+isolate via temp `XDG_*`. Windows has no Docker QA path here by design.
+
+## Cleanup
+
+Each run auto-removes its container (`--rm`). The `omo-dev` / `omo-qa` images
+persist for fast re-runs; drop them with `script/agent/qa-docker.sh --clean`.

package/.agents/skills/tech-debt-audit/SKILL.md

@@ -5,7 +5,7 @@ description: "Thorough, file-cited technical debt audit across 9 dimensions usin
 
 # Tech Debt Audit Protocol
 
-Model-agnostic technical debt audit for oh-my-openagent (OMO). Uses OMO's built-in tools (`ast_grep_search`, `grep`, `glob`, `bash`, `read`, `lsp_diagnostics`, `task`) plus **optional CodeGraph MCP** for enhanced code graph analysis when available. Produces a grounded, citable `TECH_DEBT_AUDIT.md` artifact.
+Model-agnostic technical debt audit for oh-my-openagent (OMO). Uses OMO's built-in tools (`grep`, `glob`, `bash` with `sg`, `read`, `lsp_diagnostics`, `task`) plus **optional CodeGraph MCP** for enhanced code graph analysis when available. Produces a grounded, citable `TECH_DEBT_AUDIT.md` artifact.
 
 ## CodeGraph Enhancement (Optional)
 
@@ -62,8 +62,8 @@ Use OMO tools for each dimension. Run parallel tool calls within each dimension.
 ### 1. Architectural Decay
 
 #### Standard (always run)
-- `ast_grep_search(pattern="import { $$$ } from '$SRC'", lang="typescript")` — map module graph, look for circular patterns
-- `ast_grep_search(pattern="class $NAME { $$$ }", lang="typescript")` — check for god classes
+- `bash("sg -p \"import { $$$ } from '$SRC'\" -l ts .")` — map module graph, look for circular patterns
+- `bash("sg -p \"class $NAME { $$$ }\" -l ts .")` — check for god classes
 - `grep("TODO|FIXME|HACK|XXX|WORKAROUND|TEMP")` — tagged debt markers
 - `grep("async|await")` on sync-looking files — misplaced async boundaries
 - `bash("wc -l <file>")` on each large file found in Phase 0
@@ -100,9 +100,9 @@ Use `codegraph_explore` to survey actual module structure.
 ### 2. Consistency Rot
 
 #### Standard (always run)
-- `ast_grep_search(pattern="import axios|import fetch|import got|import superagent", lang="typescript")` — multiple HTTP clients
+- `bash("sg -p \"import $CLIENT from '$PKG'\" -l ts .")` — multiple HTTP clients
 - `grep("console.log|console.error|console.warn")` — direct console use vs logger
-- `ast_grep_search(pattern="try { $$$ } catch ($$$) { $$$ }", lang="typescript")` — error handling patterns
+- `bash("sg -p \"try { $$$ } catch ($$$) { $$$ }\" -l ts .")` — error handling patterns
 - `grep("as any|@ts-ignore|@ts-expect-error|as unknown")` — type escapes
 - `grep("eslint-disable|prettier-ignore")` — lint suppressions
 
@@ -115,10 +115,10 @@ Use `codegraph_explore` to survey actual module structure.
 ### 3. Type & Contract Debt
 
 #### Standard (always run)
-- `ast_grep_search(pattern="as any", lang="typescript")` — runtime type escapes
-- `ast_grep_search(pattern="@ts-expect-error", lang="typescript")` — suppressed errors
-- `ast_grep_search(pattern="@ts-ignore", lang="typescript")` — suppressed errors (legacy)
-- `ast_grep_search(pattern=": any", lang="typescript")` — typed as any
+- `bash("sg -p \"$VALUE as any\" -l ts .")` — runtime type escapes
+- `grep("@ts-expect-error")` — suppressed errors
+- `grep("@ts-ignore")` — suppressed errors (legacy)
+- `bash("sg -p \"$NAME: any\" -l ts .")` — typed as any
 - `lsp_diagnostics(filePath="<src-dir>")` — current type errors
 
 #### What to flag
@@ -165,7 +165,7 @@ Run this on a few key internal modules (logger, config loader, HTTP client) to s
 ### 6. Performance & Resource Hygiene
 
 #### Standard (always run)
-- `ast_grep_search(pattern="for ($$$ of $$$) { $$$ await $$$ }", lang="typescript")` — async-in-loop
+- `bash("sg -p \"for ($$$ of $$$) { $$$ await $$$ }\" -l ts .")` — async-in-loop
 - `grep("await.*map|await.*filter|await.*forEach")` — sequential async iteration
 - `grep("Promise\\.all|Promise\\.allSettled")` — existing parallel patterns (good signal)
 - `grep("addEventListener|on\\(|subscribe")` without `removeEventListener|off\\(|unsubscribe` nearby — listener hygiene
@@ -179,10 +179,10 @@ Run this on a few key internal modules (logger, config loader, HTTP client) to s
 ### 7. Error Handling & Observability
 
 #### Standard (always run)
-- `ast_grep_search(pattern="catch ($$$) { $$$ }", lang="typescript")` — catch blocks
+- `bash("sg -p \"catch ($$$) { $$$ }\" -l ts .")` — catch blocks
 - `grep("catch.*{}|catch.*{\\s*}")` — empty catch blocks
 - `grep("console.error|logger\\.error|log\\.error")` — actual error logging
-- `ast_grep_search(pattern="throw new $ERR(", lang="typescript")` — error types used
+- `bash("sg -p \"throw new $ERR($$$)\" -l ts .")` — error types used
 
 #### CodeGraph Enhancement (if available)
 
@@ -210,8 +210,8 @@ Check the blast radius of custom error classes. If changing an error type would
 
 #### Standard (always run)
 - `grep("api[Kk]ey|api_secret|password|secret|token|credential")` in source files (not config or env)
-- `ast_grep_search(pattern="SELECT .* FROM|INSERT INTO|UPDATE.*SET|DELETE FROM", lang="typescript")` — SQL construction
-- `ast_grep_search(pattern="innerHTML|dangerouslySetInnerHTML", lang="typescript")` — XSS vectors
+- `grep("SELECT .* FROM|INSERT INTO|UPDATE.*SET|DELETE FROM")` — SQL construction
+- `grep("innerHTML|dangerouslySetInnerHTML")` — XSS vectors
 - `grep("eval\\(|Function\\(|setTimeout\\(.*string|setInterval\\(.*string")` — code injection
 
 #### What to flag