From b6758cf30a4817b347fafd3f6a569652452def5b Mon Sep 17 00:00:00 2001
From: Grant <grant@ten31.xyz>
Date: Wed, 17 Jun 2026 10:58:23 -0500
Subject: [PATCH] Add full Stage 2 teardown + harvest guidance

teardown-stage2.sh stops every Stage 2 run (daemon + docs + sandbox), kills any
orphaned sandbox dev server on :4311 the onboarding-tester left behind, and stops
the regtest BTCPay docker stack + volumes (--keep-btcpay to leave it up). README
documents it as the always-run cleanup step, and adds a harvest note: on a clean
run, check whether the existing public docs already cover the success story before
adding anything.
---
 onboarding-harness/README.md                 | 11 ++++
 onboarding-harness/stage2/teardown-stage2.sh | 56 ++++++++++++++++++++
 2 files changed, 67 insertions(+)
 create mode 100755 onboarding-harness/stage2/teardown-stage2.sh

diff --git a/onboarding-harness/README.md b/onboarding-harness/README.md
index ee97329..cc0a09b 100644
--- a/onboarding-harness/README.md
+++ b/onboarding-harness/README.md
@@ -53,15 +53,26 @@ that boundary is a feature, not a gap.
 
 ```sh
 (cd stage2/btcpay-regtest && docker compose -p keysat-btcpay up -d)   # one-time
+./stage2/btcpay-regtest/probe.sh  # mints the BTCPay store token into .live-env (one-time)
 ./stage2/run-stage2.sh            # boots sandbox daemon + regtest wiring + scoped key
 # feed runs/<id>/AGENT_BRIEF.md to the onboarding-tester agent
+./stage2/teardown-stage2.sh       # WHEN DONE: stop daemon(s) + docs + sandbox dev server + BTCPay stack
 ```
 
 - `stage2/btcpay-regtest/` — the BTCPay regtest compose + de-risk probe (`FINDINGS.md`).
 - `stage2/validate-gate.sh` — end-to-end gate check (deny mainnet/undetermined, allow regtest).
 - `stage2/buyer-pay.sh` — the test buyer's wallet (pay invoice on regtest + mine).
+- `stage2/teardown-stage2.sh` — full cleanup: tears down every Stage 2 run, kills any orphaned
+  sandbox dev server (`:4311`), and stops the BTCPay docker stack + volumes (`--keep-btcpay`
+  to leave it up between runs). **Always run this when finished** — the agent can leave a
+  daemon, a docs server, or an `npm run dev` behind.
 - `stage2/STAGE2-RESULT.md` — convergence + the publishable walkthrough.
 
+**Harvesting on a clean run:** do NOT reflexively bolt a new success story onto the public
+HTML. First check whether `keysat-docs/agent.html` (the connect workflow + worked example)
+and the docs already cover the buyer-pays + SDK-gating case well enough; only propose
+additions for a genuine gap, with operator approval.
+
 ## Requirements
 
 `cargo`, `node`/`npm`, `python3`, `curl`, `jq`, `openssl`. (Docker is only
diff --git a/onboarding-harness/stage2/teardown-stage2.sh b/onboarding-harness/stage2/teardown-stage2.sh
new file mode 100755
index 0000000..1d1ec9d
--- /dev/null
+++ b/onboarding-harness/stage2/teardown-stage2.sh
@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Full Stage 2 teardown — run when the onboarding test is done so nothing keeps
+# running. Stops, for each Stage 2 run: the ephemeral daemon + docs server +
+# sandbox copy (via the shared teardown.sh); then kills any sandbox dev server
+# the onboarding-tester left behind; then stops the shared regtest BTCPay docker
+# stack (containers + volumes).
+#
+# Usage:
+#   ./teardown-stage2.sh                 # tear down ALL Stage 2 runs + dev servers + BTCPay stack
+#   ./teardown-stage2.sh --keep-btcpay   # same, but leave the BTCPay stack up (iterating)
+#   ./teardown-stage2.sh runs/<id>       # one specific run dir (path relative to onboarding-harness/)
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$HERE/../lib.sh"
+
+KEEP_BTCPAY=0; ONE_RUN=""
+for a in "$@"; do
+  case "$a" in
+    --keep-btcpay) KEEP_BTCPAY=1 ;;
+    *) ONE_RUN="$a" ;;
+  esac
+done
+
+# 1. Per-run teardown (daemon + docs server + sandbox copy + freed ports).
+if [[ -n "$ONE_RUN" ]]; then
+  "$HARNESS_DIR/teardown.sh" "$ONE_RUN" || true
+else
+  shopt -s nullglob
+  any=0
+  for d in "$RUNS_DIR"/*stage2*/; do
+    [[ -f "${d}state.env" ]] || continue
+    "$HARNESS_DIR/teardown.sh" "${d%/}" || true
+    any=1
+  done
+  [[ "$any" == 0 ]] && warn "no Stage 2 run dirs found under $RUNS_DIR"
+fi
+
+# 2. Kill any sandbox dev server the agent left running. The proof-of-work app
+#    serves on :4311 (npm run dev); the onboarding-tester may start it and not
+#    stop it.
+for pid in $(lsof -ti tcp:4311 -sTCP:LISTEN 2>/dev/null || true); do
+  kill "$pid" 2>/dev/null && log "stopped orphaned sandbox dev server (pid $pid on :4311)" || true
+done
+
+# 3. Stop the shared regtest BTCPay stack (containers + volumes) unless told to keep it.
+if [[ "$KEEP_BTCPAY" == 1 ]]; then
+  ok "left BTCPay regtest stack running (--keep-btcpay)"
+elif docker ps -a --filter "name=keysat-btcpay" --format '{{.Names}}' 2>/dev/null | grep -q .; then
+  ( cd "$HERE/btcpay-regtest" && docker compose -p keysat-btcpay down -v ) >/dev/null 2>&1 \
+    && ok "stopped BTCPay regtest stack (containers + volumes removed)" \
+    || warn "could not fully stop BTCPay — check: docker ps -a --filter name=keysat-btcpay"
+else
+  ok "BTCPay regtest stack already stopped"
+fi
+
+ok "Stage 2 teardown complete"