sandcastle

/sandcastle

Two modes. Pick by what the repo already has.

• .sandcastle/ missing → SETUP
• .sandcastle/ present → CHECK (default; also use after a run misbehaves)

Never guess a value. Every item below is a command whose output decides the answer. Report a table of PASS / WARN / FAIL with the fix next to each failure, then offer to apply the fixes — don't apply silently.

CHECK

Run these from the repo root. Each line is one check.

# 1. harness files
ls .sandcastle/{main.mts,plan-prompt.md,implement-prompt.md,review-prompt.md,merge-prompt.md,Dockerfile}

# 2. deps + script  (FAIL → npm i -D @ai-hero/sandcastle tsx zod; npm pkg set scripts.sandcastle="tsx .sandcastle/main.mts")
ls -d node_modules/@ai-hero/sandcastle && npm pkg get scripts.sandcastle

# 3. real .env, not just the example  (FAIL → cp .sandcastle/.env.example .sandcastle/.env and fill it)
test -f .sandcastle/.env && grep -c "^GH_TOKEN=." .sandcastle/.env

# 4. WORKSPACE_DIR points at a real workspace (empty value = repo root is the workspace)
W=$(grep -m1 "^WORKSPACE_DIR=" .sandcastle/.env | cut -d= -f2); ls "${W:-.}/package.json"

# 5. the false-green guard — see "Three slots" below
test -f .sandcastle/workspace-hint.md

# 6. optional planner knowledge
test -f .sandcastle/planning-rules.md

# 7. DEP_ORDER_FILE, if set, must exist
D=$(grep -m1 "^DEP_ORDER_FILE=" .sandcastle/.env | cut -d= -f2); [ -z "$D" ] || ls "$D"

# 8. issues exist — github: the label has open issues; local: issue files present
S=$(grep -m1 "^ISSUE_SOURCE=" .sandcastle/.env | cut -d= -f2); S=${S:-github}
if [ "$S" = "local" ]; then ls .sandcastle/issues/*.md; else
  L=$(grep -m1 "^ISSUE_LABEL=" .sandcastle/.env | cut -d= -f2); L=${L:-ready-for-agent}
  gh label list --search "$L" | head -3; gh issue list --state open --label "$L" --limit 5
fi

# 9. models live + sandbox image built + prompt args wired + no built-in overridden
npx tsx .sandcastle/check-models.mts

# 9b. the harness's own rules and its docs agree with its code (~200ms, no Docker)
npx tsx --test .sandcastle/*.test.mts

# 10. how many runs are live — TWO lines per run, 0 before you start another
ps -eo pid,lstart,command | grep "[.]sandcastle/main[.]mts"

# 11. containers: 2 per issue in flight is normal; only non-zero with NO run live is a leak
docker ps -a --filter name=sandcastle -q | wc -l

# 12. worktrees left dirty by a killed run — startup auto-rescues these (WIP commit on the issue branch, then clears); listed here so you know a kill happened
for w in .sandcastle/worktrees/*/; do [ -d "$w" ] && git -C "$w" status --porcelain | head -3; done