Merge pull request #107 from protocol-security/feature/0.22.0

Trixie image, harvest restore tags, post-process setup, dashboard keys

Author: moodmosaic

CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## Unreleased
 
+## 0.22.0 — 2026-06-08
+
+- **Build: base the agent image on Debian trixie.** Replaces
+  `debian:bookworm-slim` (glibc 2.36) so binaries that require
+  glibc 2.39+ run inside the container.
+- **Build: install `unzip` in the agent image.** Available for
+  setup scripts and agents that need to extract archives.
+- **Feature: harvest tags a restore point before merging.**
+  `harvest.sh` creates a local `swarm-harvest-<date>-<time>` tag on
+  the pre-merge branch tip, so a harvest can be undone with
+  `git reset --hard <tag>`. Skipped on `--dry` and when nothing is
+  new; never pushed.
+- **Feature: `post_process.setup` overrides the post-process setup.**
+  A path runs a lighter setup, `false`/`""` skips setup so a heavy
+  top-level `setup` is not redone, and omitting it inherits the
+  top-level setup.
+- **Dashboard (breaking): swap the post-process keys.** `P` now
+  tails the post-process logs (matching the `P` row, like `[1-9]`
+  for agent rows) and lowercase `p` starts post-processing. The
+  log hint reads `[1-9/P]` once the container exists. Previously
+  `p` tailed logs and `P` started the run.
+- **Docs: document the dashboard effort letters.** The Model
+  column's parenthesised suffix is `(h)` high, `(m)` medium,
+  `(l)` low, `(x)` xhigh, `(n)` none, and `(M)` max.
+
 ## 0.21.1 — 2026-06-08
 
 - **Fix: `post-process` propagates the container's exit code.**

Dockerfile

@@ -1,4 +1,4 @@
-FROM debian:bookworm-slim
+FROM debian:trixie-slim
 
 RUN apt-get update && apt-get install -y --no-install-recommends \
     git \
@@ -8,6 +8,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     make \
     jq \
     sudo \
+    unzip \
     openssh-client \
     && rm -rf /var/lib/apt/lists/*
 

USAGE.md

@@ -319,10 +319,15 @@ do not count toward numbered-agent completion.
 |-----|--------|
 | `q` | Quit. |
 | `1`-`9` | Logs for agent N. |
+| `P` | Post-process logs (the `P` row), if it exists. |
 | `h` | Harvest results. |
 | `s` | Stop numbered agents and post-process. |
-| `p` | Post-process logs, if the container exists. |
-| `P` | Start post-process after confirmation. |
+| `p` | Start post-process after confirmation. |
+
+The Model column appends the agent's reasoning effort as a
+parenthesised letter: `(h)` high, `(m)` medium, `(l)` low,
+`(x)` xhigh, `(n)` none, and `(M)` max. Models configured
+without an `effort` show no suffix.
 
 ## Activity streaming
 
@@ -448,6 +453,12 @@ post-processing, run `./launch.sh post-process`; use that command
 directly when you intentionally want to run only the post-process
 agent and then harvest.
 
+Before merging, `harvest.sh` tags the current branch tip with a
+local `swarm-harvest-<date>-<time>` tag (skipped on `--dry` and
+when nothing is new). Undo a harvest with
+`git reset --hard <tag>`. The tag is never pushed and does not
+interfere with the harvested branches.
+
 `post_process` also accepts `base_url`, `api_key`,
 `auth_token`, `auth`, `tag`, `driver`, and `max_idle` -- same
 fields as per-group agents -- to route post-processing through
@@ -456,6 +467,11 @@ many consecutive sessions with no commits before the
 post-processor exits. When omitted it inherits the top-level
 `max_idle` (default: `3`).
 
+`post_process.setup` overrides the setup script for the
+post-process pass: a path runs that script, `false` or `""`
+skips setup (so a heavy top-level `setup` is not redone), and
+omitting the key inherits the top-level `setup`.
+
 `./launch.sh post-process` (and `wait` when it triggers
 post-processing) exits with the post-process container's exit
 code. Harvest still runs first, so a crashed agent's in-flight

VERSION

@@ -1 +1 @@
-0.21.1
+0.22.0

dashboard.sh

@@ -28,10 +28,10 @@ interactive session branches.
 Keybindings:
   q           Quit the dashboard.
   1-9         Tail logs for agent N.
+  P           Tail post-process logs (the "P" row) when it exists.
   h           Harvest agent results into current branch.
   s           Stop numbered, interactive, and post-process agents.
-  p           Tail post-process logs when the container exists.
-  P           Start post-process after confirmation.
+  p           Start post-process after confirmation.
 
 Environment:
   SWARM_TITLE    Dashboard title override.
@@ -758,18 +758,21 @@ draw() {
     # Help bar.
     # shellcheck disable=SC2059
     printf " ${DIM}[q]${RESET} quit"
-    # shellcheck disable=SC2059
-    printf "  ${DIM}[1-9]${RESET} logs"
+    if post_process_container_exists; then
+        # The "P" row's logs join the numbered agent logs.
+        # shellcheck disable=SC2059
+        printf "  ${DIM}[1-9/P]${RESET} logs"
+    else
+        # shellcheck disable=SC2059
+        printf "  ${DIM}[1-9]${RESET} logs"
+    fi
     # shellcheck disable=SC2059
     printf "  ${DIM}[h]${RESET} harvest"
     # shellcheck disable=SC2059
     printf "  ${DIM}[s]${RESET} stop all"
-    if post_process_container_exists; then
-        # shellcheck disable=SC2059
-        printf "  ${DIM}[p]${RESET} post-process logs"
-    elif post_process_configured; then
+    if post_process_configured && ! post_process_container_exists; then
         # shellcheck disable=SC2059
-        printf "  ${DIM}[P]${RESET} post-process"
+        printf "  ${DIM}[p]${RESET} post-process"
     fi
     printf "\n"
 }
@@ -823,24 +826,8 @@ while true; do
                 enter_alt_screen
                 ;;
             p)
-                leave_alt_screen
-                _pp_name="${IMAGE_NAME}-post"
-                if post_process_container_exists; then
-                    echo "--- Logs for ${_pp_name} (Ctrl-C to return) ---"
-                    docker logs -f "$_pp_name" 2>&1 || true
-                    if ! docker inspect -f '{{.State.Running}}' \
-                            "$_pp_name" 2>/dev/null | grep -q true; then
-                        echo ""
-                        read -rp "Press Enter to return to dashboard..." _
-                    fi
-                else
-                    echo "(post-processing is not running -- press P to start)"
-                    echo ""
-                    read -rp "Press Enter to return to dashboard..." _
-                fi
-                enter_alt_screen
-                ;;
-            P)
+                # Lowercase p starts post-processing (an action),
+                # gated on confirmation and a stopped swarm.
                 leave_alt_screen
                 if ! post_process_configured; then
                     echo "(post-processing not configured)"
@@ -852,7 +839,7 @@ while true; do
                 fi
                 _pp_name="${IMAGE_NAME}-post"
                 if post_process_container_exists; then
-                    echo "(post-processing is already running -- press p for logs)"
+                    echo "(post-processing is already running -- press P for logs)"
                     echo "Stop it first with s before starting a new run."
                     echo ""
                     read -rp "Press Enter to return to dashboard..." _
@@ -882,6 +869,26 @@ while true; do
                 read -rp "Press Enter to return to dashboard..." _
                 enter_alt_screen
                 ;;
+            P)
+                # Uppercase P tails the "P" row's logs, mirroring how
+                # [1-9] tail the numbered agent rows.
+                leave_alt_screen
+                _pp_name="${IMAGE_NAME}-post"
+                if post_process_container_exists; then
+                    echo "--- Logs for ${_pp_name} (Ctrl-C to return) ---"
+                    docker logs -f "$_pp_name" 2>&1 || true
+                    if ! docker inspect -f '{{.State.Running}}' \
+                            "$_pp_name" 2>/dev/null | grep -q true; then
+                        echo ""
+                        read -rp "Press Enter to return to dashboard..." _
+                    fi
+                else
+                    echo "(post-processing is not running -- press p to start)"
+                    echo ""
+                    read -rp "Press Enter to return to dashboard..." _
+                fi
+                enter_alt_screen
+                ;;
         esac
     fi
 done

harvest.sh

@@ -151,6 +151,16 @@ if [ "$TOTAL_NEW_COMMITS" -eq 0 ]; then
     exit 0
 fi
 
+# Tag a restore point on the pre-merge HEAD so this harvest can be
+# undone with `git reset --hard <tag>`.  The tag lives in refs/tags
+# and never collides with the harvested branches in refs/heads, so
+# it is safe alongside agent-work.  Skip if HEAD is already tagged.
+if ! git tag --points-at HEAD | grep -q '^swarm-harvest-'; then
+    harvest_tag="swarm-harvest-$(date +%Y-%m-%d-%H%M%S)"
+    git tag "$harvest_tag"
+    echo "Tagged restore point: ${harvest_tag}"
+fi
+
 echo ""
 for item in "${MERGE_BRANCHES[@]}"; do
     branch="${item%%|*}"

launch.sh

@@ -821,7 +821,7 @@ cmd_wait() {
 }
 
 cmd_post_process() {
-    local pp_prompt pp_model pp_base_url pp_api_key pp_effort pp_auth pp_auth_token pp_tag pp_driver pp_max_idle
+    local pp_prompt pp_model pp_base_url pp_api_key pp_effort pp_auth pp_auth_token pp_tag pp_driver pp_max_idle pp_setup
     pp_prompt=$(jq -r '.post_process.prompt // empty' "$CONFIG_FILE")
     pp_max_idle=$(jq -r '.post_process.max_idle // .max_idle // 3' "$CONFIG_FILE")
     pp_model=$(jq -r '.post_process.model // "claude-opus-4-6"' "$CONFIG_FILE")
@@ -836,6 +836,18 @@ cmd_post_process() {
     pp_tag="$(expand_env_ref "$pp_tag")"
     pp_driver=$(jq -r '.post_process.driver // .driver // "claude-code"' "$CONFIG_FILE")
 
+    # Resolve the post-process setup script.  An explicit
+    # post_process.setup wins (a path runs it, false/empty skips it so a
+    # heavy top-level setup is not redone); omitting the key inherits
+    # the top-level setup.
+    if jq -e '(.post_process // {}) | has("setup")' "$CONFIG_FILE" \
+            >/dev/null 2>&1; then
+        pp_setup=$(jq -r '.post_process.setup // ""' "$CONFIG_FILE")
+        [ "$pp_setup" = "false" ] && pp_setup=""
+    else
+        pp_setup="${SWARM_SETUP:-}"
+    fi
+
     if [ -z "$pp_prompt" ]; then
         echo "ERROR: post_process.prompt is not set in ${CONFIG_FILE}." >&2
         exit 1
@@ -892,7 +904,7 @@ cmd_post_process() {
         -e "SWARM_EFFORT=${pp_effort}" \
         -e "CLAUDE_MODEL=${pp_model}" \
         -e "SWARM_PROMPT=${pp_prompt}" \
-        -e "SWARM_SETUP=${SWARM_SETUP:-}" \
+        -e "SWARM_SETUP=${pp_setup}" \
         -e "MAX_IDLE=${pp_max_idle}" \
         -e "MAX_RETRY_WAIT=${MAX_RETRY_WAIT}" \
         -e "GIT_USER_NAME=${GIT_USER_NAME}" \
@@ -903,7 +915,7 @@ cmd_post_process() {
         -e "SWARM_DRIVER=${pp_driver}" \
         -e "SWARM_RUN_CONTEXT=${SWARM_RUN_CONTEXT}" \
         -e "SWARM_CFG_PROMPT=${pp_prompt}" \
-        -e "SWARM_CFG_SETUP=${SWARM_SETUP:-}" \
+        -e "SWARM_CFG_SETUP=${pp_setup}" \
         -e "SWARM_ACTIVITY_TIMEOUT=${SWARM_ACTIVITY_TIMEOUT:-0}" \
         -e "SWARM_ACTIVITY_POLL=${SWARM_ACTIVITY_POLL:-10}" \
         -e "SWARM_WATCHDOG_GRACE=${SWARM_WATCHDOG_GRACE:-10}" \

tests/manual_interactive_e2e.sh

@@ -15,7 +15,10 @@ set -euo pipefail
 # - Claude OAuth env forwarding;
 # - dashboard configured rows before containers exist;
 # - dashboard I* rows for interactive containers;
-# - dashboard P row and [P] post-process action.
+# - dashboard P row, with P tailing its logs and lowercase p
+#   starting the post-process run;
+# - post_process.setup override that runs a lighter post-process
+#   setup instead of inheriting the top-level setup.
 #
 # The generated config uses normal prompts and max_idle=3.  It does
 # not include a timeboxed "keep running for N minutes" prompt.  Stop
@@ -139,6 +142,25 @@ setup_log="test-results/setup-${setup_id}.log"
 EOF
 chmod +x "$REPO_DIR/scripts/setup.sh"
 
+cat > "$REPO_DIR/scripts/post-setup.sh" <<'EOF'
+#!/bin/bash
+set -euo pipefail
+
+# Lighter setup used only for the post-process pass.  swarm.json sets
+# post_process.setup to this script, so launch.sh runs it instead of
+# inheriting the heavier top-level scripts/setup.sh.  The unique marker
+# makes the override observable: it proves the post-process container
+# ran this lighter script and did not redo the top-level setup.
+mkdir -p test-results
+{
+    printf 'POST_SETUP_RAN at %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    printf 'driver=%s model=%s\n' \
+        "${SWARM_DRIVER:-unknown}" \
+        "${SWARM_MODEL:-unknown}"
+} >> test-results/post-process-setup.log
+EOF
+chmod +x "$REPO_DIR/scripts/post-setup.sh"
+
 cat > "$REPO_DIR/prompts/headless.md" <<'EOF'
 You are running a manual claude-swarm smoke test in a disposable repo.
 
@@ -241,6 +263,7 @@ cat > "$REPO_DIR/swarm.json" <<'EOF'
   ],
   "post_process": {
     "prompt": "prompts/post-process.md",
+    "setup": "scripts/post-setup.sh",
     "driver": "codex-cli",
     "model": "gpt-5.4",
     "effort": "medium",
@@ -309,9 +332,10 @@ Expected result:
   \`unknown\` / \`not found\`.
 - Omitted \`count\` on \`claude-manual\` and \`count: 0\` on
   \`codex-manual\` should not add numbered rows.
-- The post-process row should appear as \`P\`, matching the key that
-  starts it.
-- The footer should show \`[P] post-process\`.
+- The post-process row should appear as \`P\`, the same letter as the
+  \`P\` key that tails its logs once it exists.
+- The footer should show \`[p] post-process\` -- lowercase \`p\`
+  starts the run.
 
 Press \`q\` to exit.
 
@@ -326,10 +350,11 @@ Expected result:
 - Five numbered containers start: 3 Claude OAuth and 2 Codex ChatGPT.
 - The dashboard header reports 5 agents.
 - Press \`1\` through \`5\` to inspect numbered-agent logs.
-- \`p\` should only tail post-process logs after a post-process
-  container exists.  When it appears, \`P\` should be hidden because
-  post-process is already running.
-- \`P\` should ask for confirmation before starting post-process.
+- \`P\` should only tail post-process logs after a post-process
+  container exists; the logs hint becomes \`[1-9/P]\` then.
+- \`p\` should ask for confirmation before starting post-process.
+  Once the container exists, the \`[p] post-process\` start hint
+  disappears (stop with \`s\` before starting another run).
 
 This fixture uses \`max_idle: 3\` and normal prompts, so agents can
 finish naturally.  Once you have seen enough, press \`s\` in the
@@ -434,10 +459,10 @@ Expected result:
 ./dashboard.sh
 \`\`\`
 
-Press \`P\`, confirm with \`y\`, and watch the \`P\` row.  After the
-post-process container exists, lowercase \`p\` should tail its logs and
-\`P\` should disappear.  Use \`s\` or \`./launch.sh stop\` before
-starting a new post-process run.
+Press \`p\`, confirm with \`y\`, and watch the \`P\` row.  After the
+post-process container exists, uppercase \`P\` tails its logs and the
+\`[p] post-process\` start hint disappears.  Use \`s\` or
+\`./launch.sh stop\` before starting a new post-process run.
 
 Equivalent non-dashboard command:
 
@@ -448,9 +473,28 @@ Equivalent non-dashboard command:
 Expected result:
 
 - Post-process uses the Codex ChatGPT profile from \`post_process\`.
+- Before the prompt runs, the container executes
+  \`scripts/post-setup.sh\` (from \`post_process.setup\`), which appends
+  a \`POST_SETUP_RAN\` line to \`test-results/post-process-setup.log\`.
+  This is the lighter post-process setup; the heavier top-level
+  \`scripts/setup.sh\` is not redone here.
 - It writes \`test-results/post-process-summary.md\`.
+- The summary lists \`post-process-setup.log\`, so the override stays
+  visible after harvest.
 - The summary ends with \`POST_PROCESS_DONE\`.
 
+The \`post_process.setup\` key has three modes.  This fixture ships the
+override (a path); to try the others, edit \`swarm.json\`:
+
+- Path (the default here): \`"setup": "scripts/post-setup.sh"\` runs
+  that lighter script for the post-process pass only.
+- Skip: \`"setup": false\` or \`"setup": ""\` runs no setup, so a heavy
+  top-level setup is not repeated.  \`post-process-setup.log\` is then
+  absent.
+- Inherit: remove the \`setup\` key from \`post_process\` to reuse the
+  top-level \`scripts/setup.sh\`; a \`test-results/setup-*.log\` for the
+  post-process pass appears instead.
+
 ## 8. Harvest And Inspect
 
 \`\`\`bash