@intentsolutionsio/dolt-mcp-vcs 0.1.0

package/scripts/check-agent-safety.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# check-agent-safety.sh — the §10 union safety gate (blueprint §3 / blocker B1-iii).
+#
+# Asserts the mutation-verb taxonomy is enforced at the GRANT layer, across BOTH
+# the MCP and the Bash surfaces (the original gate inspected only `mcp__*` and was
+# blind to the Bash door). For every agent (and the core skill) it checks the
+# tool ALLOWLIST — never the denylist — for:
+#
+#   1. no `Bash(<cmd>:*)` wildcard that reaches a history-affecting op
+#      (bash/sh = arbitrary; dolt/bd/bd-sync/git = push/reset/branch -D/killall);
+#   2. no granted MCP tool outside the read/safe set (so a future `…__exec`,
+#      `…__merge`, `…__push`, `…__reset` grant fails the build).
+#
+# `disallowedTools` (the kebab/camel denylists) are intentionally NOT scanned —
+# a destructive pattern there is the mitigation, not a violation.
+#
+# Usage:  scripts/check-agent-safety.sh        (exit 0 = pass, 1 = violation)
+set -uo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+FORBIDDEN_WILDCARD='Bash\((bash|sh|dolt|bd|bd-sync|git):\*\)'
+ALLOWED_MCP='query|list_databases|list_dolt_commits|list_dolt_branches|show_tables'
+fail=0
+checked=0
+
+check_allowlist() {
+  local f="$1" field="$2" line val
+  line=$(grep -m1 -E "^${field}:" "$f" 2>/dev/null || true)
+  [ -n "$line" ] || return 0
+  checked=$((checked + 1))
+  val=${line#*:}
+
+  if echo "$val" | grep -qE "$FORBIDDEN_WILDCARD"; then
+    echo "FAIL: $(basename "$f") — allowlist holds a forbidden wildcard Bash grant:" \
+         "$(echo "$val" | grep -oE "$FORBIDDEN_WILDCARD" | tr '\n' ' ')"
+    fail=1
+  fi
+
+  local tok name
+  for tok in $(echo "$val" | grep -oE 'mcp__[A-Za-z0-9_-]+__[A-Za-z0-9_]+' || true); do
+    name=${tok##*__}
+    if ! echo "$name" | grep -qE "^(${ALLOWED_MCP})$"; then
+      echo "FAIL: $(basename "$f") — grants non-read MCP tool '$tok' (not in the read/safe set)"
+      fail=1
+    fi
+  done
+}
+
+shopt -s nullglob
+for f in "$ROOT"/agents/*.md; do
+  check_allowlist "$f" "tools"
+done
+for f in "$ROOT"/skills/*/SKILL.md; do
+  check_allowlist "$f" "allowed-tools"
+done
+
+if [ "$fail" -eq 0 ]; then
+  echo "PASS: §10 safety gate — $checked allowlist(s) clean (no history-affecting Bash wildcard; no non-read MCP grant)."
+else
+  echo "----"
+  echo "The mutation-verb taxonomy is violated: a read/safe-write agent or the core skill"
+  echo "holds a grant that reaches a history-affecting operation. Narrow it to explicit"
+  echo "read-only subcommands and move destructive forms to disallowedTools / recommend-only."
+fi
+exit "$fail"

package/scripts/dep-graph.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# dep-graph.sh — bead dependency analysis through the dolt-mcp server.
+# Surfaces bottlenecks (open issues blocking the most other open work) and any
+# direct dependency cycles. Runs SQL via dolt-mcp-client.py.
+#
+# Usage:  dep-graph.sh                          # uses $DOLT_PORT / $DOLT_DATABASE
+#         dep-graph.sh --port 35579 --database beads [--top 10]
+#
+# Requires: python3, dolt-mcp-server on PATH, a running bd dolt sql-server.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+PORT="${DOLT_PORT:-}"; DB="${DOLT_DATABASE:-}"; TOP=10
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --port) PORT="$2"; shift 2 ;;
+    --database) DB="$2"; shift 2 ;;
+    --top) TOP="$2"; shift 2 ;;
+    *) echo "unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+[ -n "$PORT" ] || { echo "error: set --port or DOLT_PORT (see 'bd dolt show')" >&2; exit 2; }
+[ -n "$DB" ]   || { echo "error: set --database or DOLT_DATABASE (see 'bd dolt show')" >&2; exit 2; }
+
+q() { python3 "$SCRIPT_DIR/dolt-mcp-client.py" --port "$PORT" --database "$DB" query "$1"; }
+
+echo "# Dependency analysis — database '$DB' (port $PORT)"
+echo
+echo "## Bottlenecks — open issues blocking the most other OPEN issues (top $TOP)"
+q "SELECT b.id AS blocker, b.status, COUNT(*) AS blocking_open, LEFT(b.title,55) AS title
+   FROM dependencies d
+   JOIN issues b ON b.id=d.depends_on_id
+   JOIN issues blocked ON blocked.id=d.issue_id
+   WHERE d.type='blocks' AND b.status<>'closed' AND blocked.status<>'closed'
+   GROUP BY b.id, b.status, b.title
+   ORDER BY blocking_open DESC
+   LIMIT ${TOP}"
+
+echo
+echo "## Direct cycles — A blocks B and B blocks A (should be none)"
+q "SELECT d1.issue_id AS a, d1.depends_on_id AS b
+   FROM dependencies d1
+   JOIN dependencies d2 ON d2.issue_id=d1.depends_on_id AND d2.depends_on_id=d1.issue_id
+   WHERE d1.type='blocks' AND d2.type='blocks' AND d1.issue_id < d1.depends_on_id"

package/scripts/descriptor-to-mcp-args.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""descriptor-to-mcp-args.py — the connection-descriptor -> .mcp.json transform,
+plus the descriptor validator rule (blueprint §2 / the creds-ref MAJOR).
+
+Reads a `connection.descriptor.json` (the committed per-workspace home), VALIDATES
+it, and emits the `dolt-mcp-server` args + env the .mcp.json wires — turning
+`flavor`/`endpoint`/`database`/`maturity` from frozen literals into data.
+
+Validator rule (fail-closed): the run is rejected (exit 2) if
+  * a required field is missing (flavor, endpoint, database, creds-ref, maturity);
+  * `flavor` is not a known flavor;
+  * `maturity` is not ga|beta|alpha|experimental;
+  * `creds-ref` does not start with a known `scheme:` (env:/sops:/pass:) — a
+    creds-ref is a pointer, never a literal, so anything without a known scheme is
+    refused rather than silently treated as a password.
+Alpha/experimental flavors are emitted with DOLT_MATURITY set so the client gate
+(sql_classifier.gate_decision) holds them to read-only.
+
+Usage:
+  descriptor-to-mcp-args.py [--descriptor connection.descriptor.json] [--format json|args]
+    --format json  (default) -> {"args": [...], "env": {...}}  (machine-readable)
+    --format args             -> the args, space-joined (for eyeballing)
+Exit: 0 ok · 2 invalid descriptor / unknown scheme.
+"""
+import argparse
+import json
+import os
+import sys
+
+REQUIRED = ("flavor", "endpoint", "database", "creds-ref", "maturity")
+FLAVOR_CONNECT = {"dolt": "--dolt", "doltgres": "--doltgres"}
+# alpha/experimental flavors have no wired connect flag yet (descriptor-stub only,
+# decision 6) — they validate but cannot be transformed into a live connection.
+FLAVOR_STUB = {"doltlite", "dumbo"}
+MATURITIES = {"ga", "beta", "alpha", "experimental"}
+KNOWN_CREDS_SCHEMES = ("env:", "sops:", "pass:")
+
+
+def eprint(*a):
+    print(*a, file=sys.stderr)
+
+
+def validate(d):
+    errs = []
+    for f in REQUIRED:
+        if not d.get(f):
+            errs.append(f"missing required field '{f}'")
+    flavor = d.get("flavor")
+    if flavor and flavor not in FLAVOR_CONNECT and flavor not in FLAVOR_STUB:
+        errs.append(f"unknown flavor '{flavor}' (known: "
+                    f"{', '.join(sorted(set(FLAVOR_CONNECT) | FLAVOR_STUB))})")
+    maturity = (d.get("maturity") or "").lower()
+    if maturity and maturity not in MATURITIES:
+        errs.append(f"unknown maturity '{maturity}' (known: {', '.join(sorted(MATURITIES))})")
+    cref = d.get("creds-ref")
+    if cref and not str(cref).startswith(KNOWN_CREDS_SCHEMES):
+        errs.append(f"creds-ref '{cref}' has no known scheme prefix "
+                    f"({', '.join(KNOWN_CREDS_SCHEMES)}); a creds-ref must be a pointer, "
+                    "never a literal secret")
+    return errs
+
+
+def split_endpoint(endpoint):
+    host, _, port = endpoint.partition(":")
+    return host or "127.0.0.1", port or "3308"
+
+
+def transform(d):
+    flavor = d["flavor"]
+    if flavor in FLAVOR_STUB:
+        raise ValueError(f"flavor '{flavor}' is a descriptor-stub (pre-beta) — no live "
+                         "connection flag is wired yet (decision 6). It validates but "
+                         "cannot be transformed until dolt-watch reports it has reached beta.")
+    host, port = split_endpoint(d["endpoint"])
+    user = os.environ.get("DOLT_USER", "root")
+    args = ["--stdio", FLAVOR_CONNECT[flavor],
+            "--host", host, "--port", port,
+            "--user", user, "--database", d["database"]]
+    env = {
+        # the secret is resolved at runtime from the creds-ref pointer (never inlined)
+        "DOLT_PASSWORD": "${DOLT_PASSWORD:-}",
+        "DOLT_MATURITY": d["maturity"].lower(),
+    }
+    return {"args": args, "env": env, "creds-ref": d["creds-ref"]}
+
+
+def main():
+    ap = argparse.ArgumentParser(description="connection-descriptor -> .mcp.json args (validated)")
+    ap.add_argument("--descriptor", default="connection.descriptor.json")
+    ap.add_argument("--format", choices=["json", "args"], default="json")
+    args = ap.parse_args()
+
+    try:
+        with open(args.descriptor) as fh:
+            d = json.load(fh)
+    except (OSError, json.JSONDecodeError) as e:
+        eprint(f"error: cannot read descriptor '{args.descriptor}': {e}")
+        return 2
+
+    errs = validate(d)
+    if errs:
+        eprint(f"invalid descriptor '{args.descriptor}':")
+        for e in errs:
+            eprint(f"  - {e}")
+        return 2
+
+    try:
+        out = transform(d)
+    except ValueError as e:
+        eprint(f"error: {e}")
+        return 2
+
+    if args.format == "args":
+        print(" ".join(out["args"]))
+    else:
+        print(json.dumps(out, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/dolt-idle-reaper.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# dolt-idle-reaper.sh — gracefully stop idle bd-managed `dolt sql-server`
+# processes so they don't accumulate (the "18 sprawled servers" problem).
+#
+# Safe by design: bd auto-restarts a workspace's dolt server on the next bd
+# command, so stopping an idle one is non-destructive — worst case is a ~2s
+# respawn latency next time that workspace is used. Data lives in Dolt (durable)
+# + the .beads JSONL; stopping a server never loses anything.
+#
+# "Idle" = the workspace's .beads/ activity files (last-touched, issues.jsonl,
+# dolt-server.log — the log updates on every query, so reads count too) have not
+# changed in $IDLE_MIN minutes.
+#
+# Usage:
+#   dolt-idle-reaper.sh                 # reap servers idle > IDLE_MIN (default 90)
+#   dolt-idle-reaper.sh --dry-run       # show what WOULD be reaped, change nothing
+#   IDLE_MIN=120 dolt-idle-reaper.sh    # custom idle threshold
+#
+# Cron (every 30 min):
+#   3,33 * * * * /path/to/dolt-idle-reaper.sh >> ~/.local/state/dolt-reaper/reap.log 2>&1
+set -uo pipefail
+
+IDLE_MIN="${IDLE_MIN:-90}"
+DRY=0
+[ "${1:-}" = "--dry-run" ] && DRY=1
+
+LOGDIR="$HOME/.local/state/dolt-reaper"
+mkdir -p "$LOGDIR"
+LOCK="$LOGDIR/.lock"
+exec 9>"$LOCK"
+flock -n 9 || { echo "[$(date '+%F %T')] another reaper run is active; skip."; exit 0; }
+
+now=$(date +%s)
+idle_secs=$(( IDLE_MIN * 60 ))
+reaped=0 kept=0 total=0
+
+# Resolve a server process's workspace root from its cwd (cwd is either the
+# workspace root or its .beads/dolt data-dir).
+ws_root() {
+  local cwd="$1"
+  case "$cwd" in
+    */.beads/dolt) echo "${cwd%/.beads/dolt}" ;;
+    */.beads)      echo "${cwd%/.beads}" ;;
+    *)             echo "$cwd" ;;
+  esac
+}
+
+# Most-recent activity timestamp (epoch) across a workspace's .beads activity files.
+latest_activity() {
+  local bd="$1/.beads" newest=0 m
+  for f in last-touched issues.jsonl dolt-server.log interactions.jsonl; do
+    [ -f "$bd/$f" ] || continue
+    m=$(stat -c %Y "$bd/$f" 2>/dev/null || echo 0)
+    [ "$m" -gt "$newest" ] && newest=$m
+  done
+  echo "$newest"
+}
+
+echo "[$(date '+%F %T')] reaper start (IDLE_MIN=$IDLE_MIN, dry-run=$DRY)"
+for pid in $(pgrep -f 'dolt sql-server' 2>/dev/null); do
+  total=$((total+1))
+  cwd=$(readlink "/proc/$pid/cwd" 2>/dev/null) || { continue; }
+  ws=$(ws_root "$cwd")
+  short=$(echo "$ws" | sed "s#$HOME/##")
+  act=$(latest_activity "$ws")
+  if [ "$act" -eq 0 ]; then
+    # No activity files found — fall back to the process start time via /proc.
+    act=$(stat -c %Y "/proc/$pid" 2>/dev/null || echo "$now")
+  fi
+  age_min=$(( (now - act) / 60 ))
+  if [ "$(( now - act ))" -ge "$idle_secs" ]; then
+    if [ "$DRY" -eq 1 ]; then
+      echo "  WOULD REAP  pid=$pid idle=${age_min}m  $short"
+    else
+      kill -TERM "$pid" 2>/dev/null && echo "  reaped      pid=$pid idle=${age_min}m  $short" || echo "  reap-failed pid=$pid  $short"
+    fi
+    reaped=$((reaped+1))
+  else
+    kept=$((kept+1))
+  fi
+done
+echo "[$(date '+%F %T')] reaper done — $total servers, $reaped $([ $DRY -eq 1 ] && echo would-reap || echo reaped), $kept kept (active within ${IDLE_MIN}m). bd respawns on next use."

package/scripts/dolt-mcp-client.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""
+dolt-mcp-client.py — minimal, robust stdio client for the dolthub/dolt-mcp server.
+
+The reusable foundation the dolt-mcp-vcs agents/scripts use to run SQL against a
+bd Dolt server *through the MCP* (not by shelling `dolt` directly), so the path
+exercised in production is the same one the plugin ships.
+
+Spawns `dolt-mcp-server --stdio`, performs the JSON-RPC handshake, calls one tool,
+prints the tool's text result, and exits. Reads until the matching response id
+arrives (no sleep-based timing).
+
+This client is the plugin's mutation chokepoint (blueprint §3 / blocker B1): every
+`query`/`exec` SQL string is run through the verb-class statement classifier
+(`sql_classifier.py`) and gated BEFORE it reaches the server. Reads execute freely;
+safe-writes require `--allow-mutation` on a non-`main` agent branch and a GA flavor;
+history-affecting statements (push / merge / reset --hard / branch-delete / DROP
+DATABASE / unknown CALL) are always refused (recommend-only).
+
+Requires: python3 (stdlib only) + a PINNED `dolt-mcp-server` on PATH. The plugin
+  pins the binary (blocker B4) — do NOT install `@latest`:
+    go install github.com/dolthub/dolt-mcp/mcp/cmd/dolt-mcp-server@v0.3.6
+  Pinned: github.com/dolthub/dolt-mcp v0.3.6
+  Module checksum (verified by `go install @v0.3.6` against sum.golang.org):
+    h1:uwjh1zf0er51VBT6uY3tI7JLj5pYxWyk9uB6CYQOhfU=
+  A bump is proposed only by the dolt-watch routine (never auto-trusted).
+
+Usage:
+  dolt-mcp-client.py --port 35579 --database beads query "SELECT COUNT(*) FROM issues"
+  dolt-mcp-client.py --port 35579 list_databases
+  echo "SELECT ..." | dolt-mcp-client.py --port 35579 --database beads query -
+  # a safe-write must opt in AND target an agent branch (never main):
+  dolt-mcp-client.py --port 35579 --database beads --allow-mutation \
+      --branch agent/my-task exec "INSERT INTO issues ..."
+
+Connection defaults come from env when flags are omitted:
+  DOLT_HOST (127.0.0.1), DOLT_PORT, DOLT_USER (root), DOLT_DATABASE, DOLT_PASSWORD ('')
+  DOLT_MATURITY (ga) — alpha/experimental restrict the connection to read-only.
+Exit codes: 0 ok · 2 bad usage · 3 binary missing · 4 connection/tool error ·
+            5 timeout · 6 mutation refused by the verb-class gate
+"""
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+import threading
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from sql_classifier import gate_decision  # noqa: E402
+
+BIN = "dolt-mcp-server"
+PINNED_VERSION = "v0.3.6"  # blocker B4 — see module docstring; bump only via dolt-watch
+INSTALL_HINT = (f"go install github.com/dolthub/dolt-mcp/mcp/cmd/"
+                f"dolt-mcp-server@{PINNED_VERSION}")
+
+
+def eprint(*a):
+    print(*a, file=sys.stderr)
+
+
+def main():
+    ap = argparse.ArgumentParser(description="stdio client for dolthub/dolt-mcp")
+    ap.add_argument("--host", default=os.environ.get("DOLT_HOST", "127.0.0.1"))
+    ap.add_argument("--port", default=os.environ.get("DOLT_PORT"))
+    ap.add_argument("--user", default=os.environ.get("DOLT_USER", "root"))
+    ap.add_argument("--database", default=os.environ.get("DOLT_DATABASE", "information_schema"))
+    ap.add_argument("--branch", default=os.environ.get("DOLT_BRANCH", "main"),
+                    help="working branch (the dolt-mcp query/exec tools require it; default main)")
+    ap.add_argument("--password", default=os.environ.get("DOLT_PASSWORD", ""))
+    ap.add_argument("--maturity", default=os.environ.get("DOLT_MATURITY", "ga"),
+                    help="flavor maturity (ga|beta|alpha|experimental); pre-GA is read-only")
+    ap.add_argument("--allow-mutation", action="store_true",
+                    help="opt in to safe-write SQL (still refused on main / pre-GA / for "
+                         "history-affecting statements)")
+    ap.add_argument("--timeout", type=float, default=25.0, help="seconds")
+    ap.add_argument("tool", help="MCP tool name, e.g. query, exec, list_databases, list_dolt_commits")
+    ap.add_argument("sql", nargs="?", help="SQL for query/exec ('-' to read from stdin)")
+    args = ap.parse_args()
+
+    if not args.port:
+        eprint("error: --port (or DOLT_PORT) is required")
+        return 2
+    if not shutil.which(BIN):
+        eprint(f"error: '{BIN}' not found on PATH. Install (pinned): {INSTALL_HINT}")
+        return 3
+
+    # Build tool arguments
+    tool_args = {}
+    if args.tool in ("query", "exec"):
+        sql = args.sql
+        if sql == "-" or (sql is None and not sys.stdin.isatty()):
+            sql = sys.stdin.read()
+        if not sql or not sql.strip():
+            eprint(f"error: tool '{args.tool}' requires a SQL string")
+            return 2
+        sql = sql.strip()
+        # The mutation chokepoint (blocker B1): classify + gate BEFORE the server call.
+        allowed, verb_class, reason = gate_decision(
+            sql, allow_mutation=args.allow_mutation,
+            branch=args.branch, maturity=args.maturity)
+        if not allowed:
+            eprint(f"refused [{verb_class}]: {reason}")
+            return 6
+        tool_args["query"] = sql
+        tool_args["working_database"] = args.database
+        tool_args["working_branch"] = args.branch  # server enforces this for query/exec
+    elif args.tool in ("list_dolt_commits", "list_dolt_branches", "show_tables"):
+        tool_args["working_database"] = args.database
+        if args.tool == "list_dolt_commits":
+            tool_args["working_branch"] = args.branch
+
+    cmd = [BIN, "--stdio", "--dolt",
+           "--host", args.host, "--port", str(args.port),
+           "--user", args.user, "--database", args.database]
+    env = dict(os.environ)
+    if args.password:
+        env["DOLT_PASSWORD"] = args.password
+
+    requests = [
+        {"jsonrpc": "2.0", "id": 1, "method": "initialize",
+         "params": {"protocolVersion": "2024-11-05", "capabilities": {},
+                    "clientInfo": {"name": "dolt-mcp-client", "version": "0.1"}}},
+        {"jsonrpc": "2.0", "method": "notifications/initialized"},
+        {"jsonrpc": "2.0", "id": 2, "method": "tools/call",
+         "params": {"name": args.tool, "arguments": tool_args}},
+    ]
+
+    try:
+        proc = subprocess.Popen(cmd, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                                stderr=subprocess.PIPE, text=True, env=env)
+    except OSError as e:
+        eprint(f"error: failed to spawn {BIN}: {e}")
+        return 3
+
+    # Watchdog: kill the process if it runs past the timeout
+    timer = threading.Timer(args.timeout, proc.kill)
+    timer.start()
+    try:
+        for r in requests:
+            proc.stdin.write(json.dumps(r) + "\n")
+        proc.stdin.flush()
+
+        result_text, err = None, None
+        for line in proc.stdout:
+            line = line.strip()
+            if not line.startswith("{"):
+                continue
+            try:
+                o = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if o.get("id") == 2:
+                if "error" in o:
+                    err = o["error"].get("message", str(o["error"]))
+                else:
+                    res = o.get("result", {})
+                    parts = [c.get("text", "") for c in res.get("content", []) if c.get("type") == "text"]
+                    result_text = "\n".join(parts)
+                    if res.get("isError"):
+                        err = result_text or "tool reported isError"
+                        result_text = None
+                break
+    finally:
+        timer.cancel()
+        try:
+            proc.stdin.close()
+        except Exception:
+            pass
+        proc.terminate()
+
+    if not timer.is_alive() and result_text is None and err is None:
+        eprint(f"error: timed out after {args.timeout}s")
+        return 5
+    if err is not None:
+        eprint(f"MCP error: {err}")
+        return 4
+    if result_text is None:
+        eprint("error: no result returned (connection failed?). stderr:")
+        eprint((proc.stderr.read() or "").strip()[:500])
+        return 4
+    print(result_text)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/dolt-push-dolthub.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# dolt-push-dolthub.sh — flush + push a bd workspace's Dolt database to its
+# DoltHub remote. Built to run on a schedule (cron/systemd timer) so DoltHub
+# stays current, instead of pushing per-command (too slow). Idempotent and safe
+# to run when nothing changed.
+#
+# Safety (blocker B2):
+#   * A failed `bd export` flush ABORTS the push — we never push on an unverified
+#     flush (the `|| true` swallow that masked flush failures was removed).
+#   * A flock guard makes overlapping scheduled runs a no-op (no double-apply).
+#   * On an ambiguous push (non-zero exit), we poll the DoltHub SQL API to read
+#     the TERMINAL state before reporting — a push that timed out client-side may
+#     have actually landed; we surface the real state instead of blind-retrying.
+#     The script itself never auto-retries; a Dolt push is idempotent, so a human
+#     (or the next scheduled run) can safely re-run it.
+#
+# Usage:  dolt-push-dolthub.sh [WORKSPACE_DIR] [--remote NAME]
+#   WORKSPACE_DIR  bd workspace to push (default: current dir). Must contain .beads/.
+#   --remote NAME  Dolt remote to push (default: origin).
+#
+# Cron example (every 20 min):
+#   */20 * * * * /path/to/dolt-push-dolthub.sh ~/my-workspace >> ~/.local/state/dolt-push.log 2>&1
+#
+# Requires: bd >= 1.0.4 with a Dolt remote already configured
+#           (bd dolt remote add origin https://doltremoteapi.dolthub.com/ORG/REPO).
+#           Optional: curl (enables the DoltHub SQL-API terminal-state poll).
+# Exit: 0 pushed or nothing-to-do · 2 bad usage · 3 no remote configured ·
+#       4 push failed (and the poll could not confirm it landed) ·
+#       5 flush failed (did NOT push) · 0 also when a failed push is confirmed-landed by the poll.
+set -uo pipefail
+
+WORKSPACE="."; REMOTE="origin"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --remote) REMOTE="$2"; shift 2 ;;
+    -*) echo "unknown arg: $1" >&2; exit 2 ;;
+    *) WORKSPACE="$1"; shift ;;
+  esac
+done
+command -v bd >/dev/null 2>&1 || { echo "error: bd not on PATH" >&2; exit 2; }
+cd "$WORKSPACE" || { echo "error: cannot cd to $WORKSPACE" >&2; exit 2; }
+[ -d .beads ] || { echo "error: $WORKSPACE is not a bd workspace (no .beads/)" >&2; exit 2; }
+
+ts() { date '+%Y-%m-%dT%H:%M:%S'; }
+
+# Idempotency guard: serialize concurrent runs for THIS workspace so two timers
+# can't push the same workspace at once. Non-blocking — a second run just exits.
+LOCKDIR="${XDG_STATE_HOME:-$HOME/.local/state}/dolt-push"
+mkdir -p "$LOCKDIR"
+LOCK="$LOCKDIR/$(echo "$PWD" | tr '/' '_').lock"
+exec 9>"$LOCK"
+flock -n 9 || { echo "[$(ts)] another push for $PWD is in progress — skip."; exit 0; }
+
+# No remote => nothing to push; say so clearly (the #1 "beads not in DoltHub" cause).
+if ! bd dolt remote list 2>/dev/null | grep -q "$REMOTE"; then
+  echo "[$(ts)] no Dolt remote '$REMOTE' configured in $WORKSPACE — nothing pushed." >&2
+  echo "      fix: bd dolt remote add $REMOTE https://doltremoteapi.dolthub.com/ORG/REPO" >&2
+  exit 3
+fi
+
+# Poll the DoltHub SQL API for a terminal state (a cheap COUNT(*) read). Best-effort:
+# resolves ORG/REPO from the remote URL; prints the count or nothing. Never fatal.
+poll_remote_terminal() {
+  command -v curl >/dev/null 2>&1 || return 1
+  local url org_repo
+  url="$(bd dolt remote list 2>/dev/null | grep -oE 'https://doltremoteapi\.dolthub\.com/[^ ]+' | head -1)"
+  [ -n "$url" ] || return 1
+  org_repo="${url#https://doltremoteapi.dolthub.com/}"
+  org_repo="${org_repo%/}"
+  curl -sf --max-time 15 \
+    "https://www.dolthub.com/api/v1alpha1/${org_repo}/main?q=SELECT%20COUNT(*)%20AS%20n%20FROM%20issues" \
+    2>/dev/null
+}
+
+# Flush the JSONL projection. A failed flush is a real signal — DO NOT push on it.
+if ! bd export >/dev/null 2>&1; then
+  echo "[$(ts)] bd export (flush) FAILED — NOT pushing on an unverified flush." >&2
+  echo "      The Dolt DB may be locked or the server down. Resolve, then re-run." >&2
+  exit 5
+fi
+
+echo "[$(ts)] pushing $WORKSPACE -> remote '$REMOTE' ..."
+if bd dolt push --remote "$REMOTE" 2>&1; then
+  echo "[$(ts)] push complete."
+  exit 0
+fi
+
+# Ambiguous failure: poll the remote's terminal state before declaring defeat. The
+# push may have landed despite a client-side error; report what actually happened.
+echo "[$(ts)] push returned non-zero — polling DoltHub for terminal state ..." >&2
+if poll_remote_terminal >/dev/null 2>&1; then
+  echo "[$(ts)] remote is reachable and reflects an 'issues' table — the push likely landed." >&2
+  echo "      Verify: curl the DoltHub SQL API for COUNT(*); re-running this script is safe (idempotent)." >&2
+  exit 0
+fi
+echo "[$(ts)] push FAILED and could not be confirmed landed (remote unreachable, creds, or DoltHub repo missing)." >&2
+echo "      Not auto-retrying — a Dolt push is idempotent, so re-run after fixing the cause." >&2
+exit 4

package/scripts/epic-closure-audit.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# epic-closure-audit.sh — find OPEN epics whose entire child set is already closed
+# (the "stale-open epic" drift: every parent-child child is closed but the epic
+# itself is still open, so its GitHub/Plane cluster issue never gets the close
+# fan-out). Runs the audit SQL through the dolt-mcp server via dolt-mcp-client.py.
+#
+# Usage:  epic-closure-audit.sh                 # uses $DOLT_PORT / $DOLT_DATABASE
+#         DOLT_PORT=35579 DOLT_DATABASE=beads epic-closure-audit.sh
+#         epic-closure-audit.sh --port 35579 --database beads
+#
+# Requires: python3, dolt-mcp-server on PATH, a running bd dolt sql-server.
+# Exit: 0 ok (whether or not drift was found) · non-zero on connection/tool error.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+PORT="${DOLT_PORT:-}"; DB="${DOLT_DATABASE:-}"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --port) PORT="$2"; shift 2 ;;
+    --database) DB="$2"; shift 2 ;;
+    *) echo "unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+[ -n "$PORT" ] || { echo "error: set --port or DOLT_PORT (see 'bd dolt show')" >&2; exit 2; }
+[ -n "$DB" ]   || { echo "error: set --database or DOLT_DATABASE (see 'bd dolt show')" >&2; exit 2; }
+
+read -r -d '' SQL <<'EOSQL' || true
+SELECT e.id AS epic, COUNT(d.issue_id) AS children,
+       SUM(CASE WHEN c.status='closed' THEN 1 ELSE 0 END) AS closed,
+       LEFT(e.title,60) AS title
+FROM issues e
+JOIN dependencies d ON d.depends_on_id=e.id AND d.type='parent-child'
+JOIN issues c ON c.id=d.issue_id
+WHERE e.issue_type='epic' AND e.status<>'closed'
+GROUP BY e.id, e.title
+HAVING children>0 AND closed=children
+ORDER BY children DESC
+EOSQL
+
+echo "# Epic-closure drift audit — database '$DB' (port $PORT)"
+echo "# OPEN epics whose every parent-child child is already closed (candidates to close)."
+OUT="$(python3 "$SCRIPT_DIR/dolt-mcp-client.py" --port "$PORT" --database "$DB" query "$SQL")"
+echo "$OUT"
+# Rows beyond the header/separator => drift found
+if [ "$(printf '%s\n' "$OUT" | sed '1,2d' | grep -c .)" -eq 0 ]; then
+  echo "# ✓ No stale-open-epic drift found."
+else
+  echo "# ⚠ Above epics have all children closed — close each via: bd-sync close <epic> --also-close-gh"
+fi