add ai-sandbox: rootless podman sandbox for agentic development

A single bash script that runs a coding harness (pi by default) inside a
rootless Ubuntu 24.04 container with only the current directory mounted at
/project, an explicit egress allowlist and an explicit environment: nothing
is passed in that was not named on the command line or in a config file.

Network enforcement here is empirical rather than assumed
(tests/spike_network.sh, docs/networking.md). The original design -- a sidecar
proxy on an internal network -- does not work rootless on this host, so allow
mode runs pasta with --map-host-loopback, installs an inet aisb ruleset inside
the container that drops every egress path except the gate's, and relays
through a squid gate bound to the host's loopback that resolves names itself
and refuses anything unlisted. The entrypoint checks that the default-drop rule
really exists before setpriv drops to uid 1000 with an empty capability set,
and exits 77/78 rather than run unenforced.

The Containerfile, the entrypoint, the squid config generator and the ruleset
renderer all live in bin/ai-sandbox, and the image is tagged by content hash,
so a policy change can never silently reuse a stale image. Tests are pure
bash: 161 assertions start no container and touch no network, 256 run real
ones, including proof that a raw socket, a stripped proxy env and DNS all stay
blocked while an allowlisted host works over both http and CONNECT.

LLM-Generated: true

tests/run.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# tests/run.sh -- the ai-sandbox test runner.
+#
+#   ./tests/run.sh              unit tests (no containers started, no network)
+#   ./tests/run.sh --e2e        everything, including real containers and egress tests
+#   ./tests/run.sh --only 04    just the files matching 04
+#   ./tests/run.sh --verbose    show each test file's raw output as it runs
+#
+# Every test file runs with its own XDG state so nothing here touches the real
+# machine's config, state or cache directories.
+set -uo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(dirname "$HERE")"
+AISB="${AISB:-$ROOT/bin/ai-sandbox}"
+export AISB
+
+WITH_E2E=0 ONLY="" VERBOSE=0
+while (($#)); do
+  case "$1" in
+    --e2e|-e)   WITH_E2E=1; shift ;;
+    --only)     ONLY="${2:-}"; shift 2 ;;
+    --verbose|-v) export VERBOSE=1; shift ;;   # lib.sh reads VERBOSE
+    --help|-h)  sed -n '2,12p' "$0"; exit 0 ;;
+    *) echo "unknown option: $1" >&2; exit 2 ;;
+  esac
+done
+
+command -v podman >/dev/null || { echo "podman is required to run the tests" >&2; exit 2; }
+
+# Syntax-check every shell file in the project before running anything.
+SYNTAX_BAD=0
+for f in "$AISB" "$HERE"/*.sh "$HERE"/unit/*.sh "$HERE"/e2e/*.sh "$ROOT"/install.sh; do
+  [[ -f "$f" ]] || continue
+  if ! syn="$(bash -n "$f" 2>&1)"; then
+    echo "SYNTAX: $f" >&2; printf '%s\n' "$syn" | sed 's/^/    /' >&2; SYNTAX_BAD=1
+  fi
+done
+(( SYNTAX_BAD )) && exit 2
+
+FILES=( "$HERE"/unit/*.sh )
+(( WITH_E2E )) && FILES+=( "$HERE"/e2e/*.sh )
+if [[ -n "$ONLY" ]]; then
+  mapfile -t FILES < <(printf '%s\n' "${FILES[@]}" | grep "/[^/]*$ONLY")
+fi
+
+BASE="$(mktemp -d "${TMPDIR:-/tmp}/ai-sandbox-tests.XXXXXX")"
+COUNTS="$BASE/counts"
+: > "$COUNTS"
+trap 'chmod -R u+rwX "$BASE" 2>/dev/null; rm -rf "$BASE" 2>/dev/null' EXIT
+
+echo "ai-sandbox test suite"
+echo "  script : $AISB"
+echo "  mode   : $([[ $WITH_E2E == 1 ]] && echo 'unit + e2e (real containers)' || echo 'unit only (add --e2e for containers)')"
+echo "  files  : ${#FILES[@]}"
+echo
+
+FAILED_FILES=()
+for f in "${FILES[@]}"; do
+  name="$(basename "$f")"
+  W="$BASE/$name"; mkdir -p "$W"/{state,cache,cfg}
+  echo "=================================================================="
+  echo "== $name"
+  echo "=================================================================="
+  # shellcheck disable=SC1090
+  (
+    export AISB_STATE_DIR="$W/state" AISB_CACHE_DIR="$W/cache" AISB_CONFIG_DIR="$W/cfg"
+    export WORK="$W" TESTS="$HERE" AISB_TEST_COUNTS="$COUNTS"
+    # NOTE: HOME is deliberately not overridden -- podman storage lives there.
+    unset AISB_ALLOW AISB_ENV AISB_MOUNT AISB_INSTALL AISB_NET AISB_EXTRA_ARGS AISB_SESSION_OVERRIDE
+    source "$f"
+    summary
+  ) || FAILED_FILES+=("$name")
+  echo
+done
+
+TOTAL_P=0 TOTAL_F=0
+while read -r p fl; do TOTAL_P=$((TOTAL_P + p)); TOTAL_F=$((TOTAL_F + fl)); done < "$COUNTS"
+
+echo "=================================================================="
+if ((${#FAILED_FILES[@]})); then
+  printf '\033[31mFAILED\033[0m  %d passed, %d failed across %d file(s)\n' "$TOTAL_P" "$TOTAL_F" "${#FAILED_FILES[@]}"
+  printf '  failing files: %s\n' "${FAILED_FILES[*]}"
+  exit 1
+fi
+printf '\033[32mALL PASS\033[0m  %d assertions, %d file(s), %s mode\n' \
+  "$TOTAL_P" "${#FILES[@]}" "$([[ $WITH_E2E == 1 ]] && echo unit+e2e || echo unit)"